Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 30 additions & 5 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,42 @@
# Changelog

## Unreleased
## v0.8.1

- Use the combined uBlock Origin CDN lists for Ads, Badware risks, Privacy, Quick
fixes, and Unbreak. Migrate existing subscriptions without changing enabled
states, and retain an existing CDN subscription when an old source duplicates it.
- Update bundled uBO scriptlets to 1.76.2, including JSON-edit and newer video
response hooks. Preserve shared dependencies and all scriptlet arguments,
isolate helpers from page globals, and honor trusted-scriptlet permissions.
- Evaluate nested filter-list conditions before rule parsing using a portable
capability profile. Expand active relative `!#include` sub-lists, including the
uBO-specific rules in EasyList Cookie and Fanboy's Annoyance. Bound downloads,
reject cycles and paths outside the permitted source, and preserve the last
complete cache if a sub-list fails. Report malformed directives and unknown
conditions; log loaded-rule counts and reasons for unsupported or invalid rules.
- Add a shared footer with the running server version linked to the project.
Check for stable releases automatically when opened and hourly thereafter,
showing an "Update available" release link only when a newer version is found.
Update checks are authenticated and time-limited, with successful checks cached
for one hour and failures for one minute.
- Added opt-in persistent statistics and individual request history using redb.
History includes time ranges, trends, top domains/clients, and pagination, with
privacy levels that remove identifiers before collection. URL paths, query
strings, headers, and bodies are never saved in statistics.
privacy levels that remove identifiers before collection. Query strings, URL
credentials, headers, and bodies are never saved in statistics.
- Add an Endpoint column to Dashboard request history with the path separate
from the domain, visual truncation for long values, and the full path on hover.
Store paths without the first slash and restore it for display. Migrate existing
endpoint values to compact paths when upgrading the statistics database.
Endpoints follow domain privacy settings; older saved records remain readable.
- Deduplicate domains, endpoints, and clients in shared lookup tables, with
compact ID references in each request. Upgrade existing history atomically to
storage version 3 and compact it. Remove unused values when requests expire;
privacy changes remove the corresponding values and lookup indexes.
- Add client names in Statistics settings, shown in both dashboard layouts and
request history with the IP available on hover. Renaming preserves counts and
updates existing history; client privacy also hides names.
- Added Statistics settings for retention, a request-count limit, clearing saved
history, and excluding domain patterns from both statistics and the live
history, and excluding domain patterns or client IPs from statistics and the live
Requests log. Exclusions do not change filtering behavior and work even when
persistence is disabled.
- Bounded statistics buffering, batched transactional writes, visible storage
Expand Down Expand Up @@ -84,7 +108,8 @@

## v0.8.0 - 2026-10-02

Release highlights and upgrade notes are in [RELEASE.md](RELEASE.md).
Release highlights and upgrade notes are in the
[v0.8.0 release notes](https://github.com/joshrmcdaniel/privaxy/blob/v0.8.0/RELEASE.md).

- Support both plain HTTP and HTTPS inside CONNECT tunnels, allowing compatible
HTTP proxies and adapters to chain into Privaxy. Detect HTTP versus TLS on any
Expand Down
2 changes: 1 addition & 1 deletion Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

71 changes: 63 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,34 @@ blocker more than it strictly replaces one.
- [filterlists.com](https://filterlists.com) integration
- Ability to add custom filters

Privaxy uses the combined uBlock Origin CDN lists for Ads, Badware risks,
Privacy, Quick fixes, and Unbreak. Existing source-list subscriptions migrate
automatically, preserving their enabled state. An already configured CDN
subscription takes precedence over its old source-list duplicate. Separate
mobile and resource-abuse subscriptions are retained for existing choices,
although their rules are also included in the combined Ads and Privacy lists.

Filter-list `!#if`, `!#else`, and `!#endif` directives use a portable uBO syntax
profile (`ext_ublock` enabled, browser-specific flags and unsupported capabilities
disabled). This selects scriptlet fallbacks for `!cap_html_filtering`; proxy HTML
injection does not implement uBO's HTML-filtering or `$replace` syntax. Unknown
conditions retain both branches, matching uBO, and are reported in the logs.
Active `!#include` directives load relative sub-lists from the same directory or
its descendants, following uBO's subscription format. Includes are expanded
before caching; inactive branches are not downloaded. Failed downloads,
malformed conditions, cycles, and includes outside the permitted source leave
the previous complete cache untouched. Downloads are limited to 64 files,
16 include levels, and 64 MiB per subscription. Custom filters have no source URL
and cannot use includes.

Bundled scriptlets come from uBlock Origin 1.76.2. Scriptlets marked
`requiresTrust` are available to the official uBO filter repositories and manually
entered Custom filters, but not arbitrary remote subscriptions. Unsupported
filter rules are counted by rejection reason alongside the number loaded. These
warnings do not mean the whole list failed to load. Filter syntax and browser
integration still differ from the uBO extension, so list compatibility does not
guarantee identical results on every video site.

## Installation

You can either utilize the docker image, binary, or the deb avaiable in releases.
Expand Down Expand Up @@ -356,23 +384,35 @@ Old `/history` bookmarks redirect to the Dashboard.
Persistence is **off by default**; enabling it starts collecting new activity,
without importing the live Requests feed.

History records timestamps, destination hostnames, client IP addresses, and
whether a request was blocked or successfully forwarded. It never stores URL
paths, query strings, headers, cookies, or request/response bodies. Raw CONNECT
tunnels and requests that fail before being forwarded are not counted. Clients
behind another proxy share that proxy's client address.
History records timestamps, destination hostnames, endpoint paths, client IP
addresses, and whether a request was blocked or successfully forwarded, according
to the selected privacy level. The Endpoint column shows only the path, such as
`/204`, beside the separate domain. The database saves `204`, without duplicating
the domain or the first `/`; that separator is restored for display. Query
strings, URL credentials, headers, cookies, and request/response bodies are never
stored. Long paths are shortened visually; hover over one to see its full value.
Older records without an endpoint show "Not recorded". Domains, endpoints, and
clients each have a shared lookup table: repeated values are saved once and
request rows reference their IDs. Unused values are removed when their last
request expires. Existing history migrates automatically to storage version 3
and is compacted, converting older hostname-prefixed endpoints to paths too.
Earlier builds that only support versions 1 or 2 cannot read the upgraded
history database.
Raw CONNECT tunnels and requests that fail before being forwarded are not
counted. Clients behind another proxy share that proxy's client address.

The privacy levels follow [Pi-hole's approach](https://docs.pi-hole.net/ftldns/privacylevels/):

| Level | Saved identifiers |
| --- | --- |
| Show domains and clients | Hostname and client IP |
| Show domains and clients | Hostname, endpoint path, and client IP |
| Hide domains | Client IP only |
| Hide domains and clients (default) | Neither; request times and outcomes remain |
| Anonymous | No new history; session counters only |

Hidden identifiers are removed **before queueing or storage**, without retaining
a reversible mapping or a hash. While collection is enabled, raising privacy
Hiding domains also hides endpoints. Hidden identifiers are removed **before
queueing or storage**, without retaining a reversible mapping or a hash. While
collection is enabled, raising privacy
also redacts identifiers in existing history, including when entering anonymous
mode. Lowering privacy cannot restore them. These controls apply to statistics;
the separate live Requests feed and diagnostic logs can still contain full URLs.
Expand All @@ -385,6 +425,17 @@ apply. Use one case-insensitive hostname or wildcard pattern per line:
include schemes, ports, or paths. Existing history and diagnostic logs are
unaffected.

**Exclude clients from statistics and request logs** applies the same exclusions
to one exact IPv4 or IPv6 address per line. This works with persistence off too;
it does not bypass ad blocking or delete previously saved requests.

**Client names** assigns friendly names to IP addresses. Names appear in both
dashboard layouts and saved history wherever client addresses are visible;
hover over a name to see its IP. Renaming updates existing history without
changing counts or merging different clients. Names are saved in configuration,
so clearing history keeps them. Privacy settings that hide clients also hide
their names on the Dashboard.

Defaults are **7 days** and **100,000 saved requests**. The oldest records expire
when either limit is reached; valid limits are 1–365 days and 100–1,000,000
requests. History totals and top lists describe retained requests, so they can
Expand All @@ -403,6 +454,10 @@ privacy = "hide_domains_and_clients" # full, hide_domains, hide_domains_and_clie
retention_days = 7
max_entries = 100000
excluded_domains = ["example.com", "*.example.com"]
excluded_clients = ["192.0.2.10", "2001:db8::10"]

[statistics.client_names]
"192.0.2.20" = "Living room TV"
```

UI changes apply immediately; file edits also apply on SIGHUP. Data stays local
Expand Down
124 changes: 61 additions & 63 deletions RELEASE.md
Original file line number Diff line number Diff line change
@@ -1,75 +1,73 @@
# Privaxy v0.8.0
# v0.8.1

Privaxy v0.8.0 adds userscripts, filtering for selected hosts, and broader HTTP
CONNECT support. It also improves streaming performance, filter-list recovery,
and the tools for diagnosing sites that break under interception.
Privaxy v0.8.1 improves uBlock Origin filter-list compatibility, adds optional
persistent statistics, and fixes HTTP/2 failures and page-loading delays.

## Highlights

- **Userscripts managed from the web UI.** Install by URL or paste, edit source,
enable or disable individual scripts, and check for updates. Supports common
Greasemonkey/Tampermonkey metadata and APIs, persistent storage, resources,
menu commands, and server-side requests controlled by each script's
`@connect` rules. URL-installed scripts also check for updates automatically.
- **Filter only selected hosts.** Inclusion mode intercepts the hosts you
select and tunnels everything else. Exclusions always take precedence, and
an empty inclusion list bypasses all hosts. The same policy applies to
HTTP, HTTPS, and PAC files; existing configurations keep their previous mode.
- **HTTP CONNECT and incoming proxy chaining.** Compatible HTTP proxies and
adapters can send both plain HTTP and HTTPS through CONNECT to Privaxy,
including on nonstandard ports. Traffic uses the existing filtering,
injection, and inclusion/exclusion policies. The README includes tun2proxy
as one example, with routing configured by the user.
- **Better filter-list management.** Refresh all enabled lists on demand, see
download failures and their causes, and edit or remove user-added lists.
Empty or invalid caches are recovered or downloaded again, and atomic
replacement prevents failed writes from truncating a working list.
- **Easier interception troubleshooting.** Proxy error pages link to an
exclusion confirmation page. The UI also lists recent TLS interception
failures, with actions to exclude or ignore a host. A configurable GUI URL
keeps these links usable behind reverse proxies and Docker NAT.
- **Updated uBlock Origin filtering.** Use the combined official CDN lists for
Ads, Badware risks, Privacy, Quick fixes, and Unbreak. Bundled scriptlets are
updated to uBO 1.76.2, including newer JSON-edit and video-response hooks,
shared helpers, and trusted-scriptlet permissions.
- **Conditional rules and sub-lists.** Evaluate nested filter-list conditions
and download active relative `!#include` files. This fixes updates for EasyList
Cookie and Fanboy's Annoyance and loads their uBO-specific rules. Failed
sub-list downloads preserve the previous complete cache. Logs now show how
many rules loaded and why individual rules were rejected.
- **Persistent statistics on the Dashboard.** Optional history provides time
ranges, trends, top domains and clients, and paginated requests. Settings
control privacy, retention, storage limits, exclusions, and clearing history.
With persistence off or Anonymous mode selected, the Dashboard retains its
original live layout. Old `/history` bookmarks redirect to the Dashboard.
Request history shows paths separately from domains, truncating long values
with the full path available on hover. Paths are stored without the first `/`,
which is restored in the UI. Domains, endpoints, and clients are stored once
and shared across request records to reduce repeated data. Assign friendly
client names or exclude client IPs from statistics and the live Requests log
in Statistics settings; excluded clients still receive normal filtering.
- **More reliable live views and settings.** Dashboard statistics, Requests,
and logs show connection status and reconnect automatically. Settings retain
unsaved edits after errors, report save results accurately, and fit smaller
screens more comfortably.
- **Version and update status.** The footer links the running Privaxy version
to the project and automatically shows an update link when a newer stable
release is detected.

## Reliability and performance

- HTML responses stream as they are rewritten, allowing browsers to start
rendering before the complete document arrives. Bounded buffering limits
memory use when downstream clients are slow.
- Larger WebSocket buffers, a shared adblock engine, and fewer repeated
cosmetic lookups reduce overhead. Filter updates replace the engine without
pausing requests for the full rebuild.
- The proxy waits for initial filter loading before accepting traffic. The
web UI remains available during loading and reports list failures.
- Invalid configuration edits retain the last working configuration. Reloads
no longer race for the web UI listener, and bind failures retry.
- Fixes cover filtering on upgraded requests, WebSocket/MMTLS handling,
truncated upstream responses, replacement-resource decoding, IPv6
certificates, and CSP compatibility for injected content.
- PAC files are also served at `/wpad.dat`, and CIDR bypass rules now render
valid subnet masks.
- The HTTP/TLS stack and frontend dependencies have been updated. Docker
examples include log rotation to limit disk usage.
- Larger HTTP/2 header limits fix 502 protocol errors on responses with large
CSP or Set-Cookie headers. Intercepted TLS connections advertise HTTP/2 so
browsers can multiplex requests; adaptive flow control and TCP_NODELAY reduce
delays. Known-empty requests can recover from retryable HTTP/2 failures.
- IP-address CONNECT requests use TLS ClientHello SNI for certificates,
hostname policy, and upstream TLS verification while retaining the original
destination IP. Protocol detection and TLS handshakes have bounded timeouts.
CONNECT traffic to port 853 tunnels DNS-over-TLS without interception.
- Proxy error pages and logs include underlying DNS, TLS, socket, and HTTP/2
failure causes. HTML modification counts no longer double-count a response
that receives both scripts and cosmetic styles.
- CI validates release tags against the package version, avoids stale package
assets, improves build caches, and keeps pull-request Docker checks separate
from image publishing.

## Upgrading and compatibility

- Existing configuration files remain supported. For v0.7.1 configurations,
inclusion mode defaults off and no userscripts are installed automatically.
- If upgrading from a development build with userscripts, **reload open pages**
after upgrading. Userscript endpoints now use tokens bound to each script
and matched page; disabling a script or changing its match rules revokes
access.
- Installed userscripts run on matching pages for every client behind the
proxy, in the page's main JavaScript world. This is a subset of browser
userscript-manager functionality; see the changelog for supported APIs and
known limitations. Requests to private networks remain disabled by default.
- For incoming proxy chains, preserve destination hostnames in CONNECT so
domain filtering and HTTPS certificates work correctly. Clients still need
to trust Privaxy's CA. This release does not add configuration for routing
Privaxy's outbound traffic through another upstream proxy. TUN setup,
routing, and UDP/QUIC handling remain the user's responsibility.
- To pin this release in Docker, use `ghcr.io/joshrmcdaniel/privaxy:0.8.0`.
Existing containers need to be recreated to adopt the log-rotation options
shown in the README.
- Existing configurations remain supported. Persistent statistics stay off
until enabled in Settings. Endpoints follow domain privacy settings; query
strings, URL credentials, headers, and bodies are never saved in statistics.
Existing history migrates to statistics storage version 3 when opened;
earlier builds that only support versions 1 or 2 cannot read the upgraded
database. Client names stay in configuration when saved history is cleared.
- Legacy subscriptions for the five updated uBO lists migrate automatically
while preserving enabled states. An existing CDN subscription takes
precedence over its old source-list duplicate. Refresh enabled lists and
reload open pages after upgrading to use the latest rules and scriptlets.
- Filter syntax and browser integration still differ from the uBO extension.
Unsupported-rule warnings describe individual skipped rules, not failed
subscription downloads, and this update does not guarantee identical video
ad blocking on every site.
- To pin this release in Docker, use `ghcr.io/joshrmcdaniel/privaxy:0.8.1`.

See the [full changelog](https://github.com/joshrmcdaniel/privaxy/blob/v0.8.0/CHANGELOG.md)
and [proxy-chaining setup](https://github.com/joshrmcdaniel/privaxy/blob/v0.8.0/README.md#6-http-connect-and-proxy-chaining)
See the [full changelog](https://github.com/joshrmcdaniel/privaxy/blob/v0.8.1/CHANGELOG.md)
and [setup documentation](https://github.com/joshrmcdaniel/privaxy/blob/v0.8.1/README.md#setup)
for details.
2 changes: 1 addition & 1 deletion privaxy/Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[package]
name = "privaxy"
description = "Next generation tracker and advertisement blocker"
version = "0.8.0"
version = "0.8.1"
edition = "2021"
repository = "https://github.com/joshrmcdaniel/privaxy"
authors = [
Expand Down
Loading
Loading