X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;f=doc%2Fsource%2Fuser-manual.sgml;h=0f7f833b5f44a4acd36cfeb467024c1f713e1a95;hb=dd4013765fc5c0b8b052365f20a59a31f88797a8;hp=8a2b4a8e175916eabcfa758b73176ebcd3a67864;hpb=584674c60a8487df489d44e926eb9a3dc6130a23;p=privoxy.git diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml index 8a2b4a8e..0f7f833b 100644 --- a/doc/source/user-manual.sgml +++ b/doc/source/user-manual.sgml @@ -10,14 +10,15 @@ + - - + + - - + + @@ -30,15 +31,11 @@ Privoxy"> ]> - Copyright &my-copy; 2001-2016 by + Copyright &my-copy; 2001-2022 by Privoxy Developers -$Id: user-manual.sgml,v 2.218 2017/02/20 13:45:36 fabiankeil Exp $ - -OS/2 - - - First, make sure that no previous installations of - Junkbuster and / or - Privoxy are left on your - system. Check that no Junkbuster - or Privoxy objects are in - your startup folder. - - - - - Then, just double-click the WarpIN self-installing archive, which will - guide you through the installation process. A shadow of the - Privoxy executable will be placed in your - startup folder so it will start automatically whenever OS/2 starts. - - - - The directory you choose to install Privoxy - into will contain all of the configuration files. - - - Mac OS X @@ -346,30 +316,235 @@ How to install the binary packages depends on your operating system: Building from Source - The most convenient way to obtain the Privoxy sources - is to download the source tarball from our - project download - page. - - - - If you like to live on the bleeding edge and are not afraid of using - possibly unstable development versions, you can check out the up-to-the-minute - version directly from the - CVS repository. - + The most convenient way to obtain the Privoxy source + code is to download the source tarball from our + + project download page, + or you can get the up-to-the-minute, possibly unstable, development version from + https://www.privoxy.org/. &buildsource; + + Windows + + Setup + + Install the Cygwin utilities needed to build Privoxy. + If you have a 64 bit CPU (which most people do by now), get the + Cygwin setup-x86_64.exe program here + (the .sig file is here). + + + Run the setup program and from View / Category select: + + +Devel + autoconf 2.5 + automake 1.15 + binutils + cmake + gcc-core + gcc-g++ + git + make + mingw64-i686-gcc-core + mingw64-i686-zlib +Editors + vim +Libs + libxslt: GNOME XSLT library (runtime) +Net + curl + openssh +Text + docbook-dssl + docbook-sgml31 + docbook-utils + openjade +Utils + gnupg +Web + w3m + + + + If you haven't already downloaded the Privoxy source code, get it now: + + +mkdir <root-dir> +cd <root-dir> +git clone https://www.privoxy.org/git/privoxy.git + + + + Get the source code (.zip or .tar.gz) for tidy from + + https://github.com/htacg/tidy-html5/releases, + unzip into <root-dir> and build the software: + + +cd <root-dir> +cd tidy-html5-x.y.z/build/cmake +cmake ../.. -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIB:BOOL=OFF -DCMAKE_INSTALL_PREFIX=/usr/local +make && make install + + + + If you want to be able to make a Windows release package, get the NSIS .zip file from + + + https://sourceforge.net/projects/nsis/files/NSIS%203/ + and extract the NSIS directory to /<root-dir>/nsis/. + Then edit the windows/GNUmakefile to set the location + of the NSIS executable - eg: + + +# Path to NSIS +MAKENSIS = /<root-dir>/nsis/makensis.exe + + + + Get the latest 8.x PCRE code from + PCRE + https://sourceforge.net/projects/pcre/files/pcre/ + and build the static PCRE libraries with + + +export CFLAGS="-O2 -fstack-protector-strong -D_FORTIFY_SOURCE=2" +export LDFLAGS="-fstack-protector-strong" +export CPPFLAGS="-DPCRE_STATIC" + +./configure --host=i686-w64-mingw32 \ + --prefix=/usr/local/i686-w64-mingw32 \ + --enable-utf --enable-unicode-properties \ + --enable-jit \ + --enable-newline-is-anycrlf \ + --enable-pcre16 \ + --enable-pcre32 \ + --disable-pcregrep-libbz2 \ + --disable-pcregrep-libz \ + --disable-pcretest-libreadline \ + --disable-stack-for-recursion \ + --enable-static --disable-shared \ + && make + + + + + + If you want to be able to have Privoxy do TLS Inspection, get the latest + 2.28.x MBED-TLS library source code from + + https://github.com/Mbed-TLS/mbedtls/tags, + extract the tar file into <root-dir> + and build the static libraries with + +export WINDOWS_BUILD=1 +# build for a Windows platform + +unset DEBUG + +export CC=i686-w64-mingw32-gcc +export LD=i686-w64-mingw32-gcc +export CFLAGS="-O2 -fstack-protector-strong -D_FORTIFY_SOURCE=2" +export LDFLAGS="${LDFLAGS} -fstack-protector-strong" + +make lib +# build the libraries + + + + + + Get the brotli library from + + https://github.com/google/brotli/releases + and build the static libraries with + +./bootstrap +# to create the GNU autotools files + +autoconf + +export CFLAGS="-O2 -fstack-protector-strong -D_FORTIFY_SOURCE=2" +export LDFLAGS="${LDFLAGS} -fstack-protector-strong" + +./configure --host=i686-w64-mingw32 \ + --prefix=/usr/local/i686-w64-mingw32 \ + --enable-static \ + --disable-shared \ + --with-gnu-ld \ + --disable-silent-rules \ + && make + + + + + + + + Build + + + To build just the Privoxy executable and not the whole installation package, do: + + +cd <root-dir>/privoxy +./windows/MYconfigure && make + + + + Privoxy uses the GNU Autotools + for building software, so the process is: + + +autoheader # creates config.h.in +autoconf # uses config.h.in to create the configure shell script +./configure [options] # creates GNUmakefile +make [options] # builds the program + + + + The usual configure options for building a native Windows application under cygwin are + + + + --host=i686-w64-mingw32 + --enable-mingw32 + --enable-zlib + --enable-static-linking + --disable-pthread + --with-brotli + --with-mbedtls + + + + You can set the CFLAGS and LDFLAGS envars before + running configure to set compiler and linker flags. For example: + + + +$ export CFLAGS="-O2" # set gcc optimization level +$ export LDFLAGS="-Wl,--nxcompat" # Enable DEP +$ ./configure --host=i686-w64-mingw32 --enable-mingw32 --enable-zlib \ +> --enable-static-linking --disable-pthread +$ make # build Privoxy + + + + See the Developer's Manual + for building a Windows release package. + + + + + + Keeping your Installation Up-to-Date @@ -412,7 +587,6 @@ How to install the binary packages depends on your operating system: versions of Privoxy: - @@ -497,11 +671,10 @@ How to install the binary packages depends on your operating system: that filtering does not work on compressed pages, so if you use, or want to use, filtering, you will need to force compression off. Example: - - { +filter{google} +prevent-compression } - .google. - +{ +filter{google} +prevent-compression } +.google. + Or if you use a number of filters, or filter many sites, you may just want to turn off compression for all sites in @@ -529,14 +702,13 @@ How to install the binary packages depends on your operating system: --> - Quickstart to Using Privoxy - + @@ -568,7 +740,7 @@ How to install the binary packages depends on your operating system: Set your browser to use Privoxy as HTTP and - HTTPS (SSL) proxy + HTTPS (SSL) proxy by setting the proxy configuration for address of 127.0.0.1 and port 8118. DO NOT activate proxying for FTP or @@ -581,7 +753,7 @@ How to install the binary packages depends on your operating system: Flush your browser's disk and memory caches, to remove any cached ad images. If using Privoxy to manage - cookies, + cookies, you should remove any currently stored cookies too. @@ -636,7 +808,6 @@ How to install the binary packages depends on your operating system: - @@ -713,7 +884,6 @@ How to install the binary packages depends on your operating system: set-image-blocker: - @@ -788,7 +958,6 @@ How to install the binary packages depends on your operating system: - Advanced users will eventually want to explore &my-app; @@ -834,7 +1003,6 @@ How to install the binary packages depends on your operating system: A quick and simple step by step example: - @@ -858,7 +1026,6 @@ How to install the binary packages depends on your operating system: -
Actions Files in Use @@ -869,7 +1036,6 @@ How to install the binary packages depends on your operating system:
- @@ -904,7 +1070,6 @@ How to install the binary packages depends on your operating system: - This is a very crude and simple example. There might be good reasons to use a @@ -941,7 +1106,7 @@ How to install the binary packages depends on your operating system: Before launching Privoxy for the first time, you will want to configure your browser(s) to use Privoxy as a HTTP and HTTPS (SSL) - proxy. The default is + proxy. The default is 127.0.0.1 (or localhost) for the proxy address, and port 8118 (earlier versions used port 8000). This is the one configuration step that must be done ! @@ -952,19 +1117,17 @@ How to install the binary packages depends on your operating system: -
Proxy Configuration Showing - Mozilla/Netscape HTTP and HTTPS (SSL) Settings + Mozilla Firefox HTTP and HTTPS (SSL) Settings - [ Screenshot of Mozilla Proxy Configuration ] + [ Screenshot of Mozilla Firefox Proxy Configuration ]
- @@ -972,8 +1135,7 @@ How to install the binary packages depends on your operating system: - Tools -> Options -> Advanced -> Network ->Connection -> Settings - + Edit -> Preferences -> Network Settings -> Settings @@ -982,7 +1144,6 @@ How to install the binary packages depends on your operating system: Edit -> Preferences -> General -> Connection Settings -> Manual Proxy Configuration - @@ -996,7 +1157,6 @@ How to install the binary packages depends on your operating system: Edit -> Preferences -> Advanced -> Proxies -> HTTP Proxy - @@ -1016,7 +1176,6 @@ How to install the binary packages depends on your operating system: -
Proxy Configuration Showing Internet Explorer HTTP and HTTPS (Secure) Settings @@ -1028,13 +1187,12 @@ How to install the binary packages depends on your operating system:
- After doing this, flush your browser's disk and memory caches to force a re-reading of all pages and to get rid of any ads that may be cached. Remove - any cookies, + any cookies, if you want Privoxy to manage that. You are now ready to start enjoying the benefits of using Privoxy! @@ -1056,11 +1214,9 @@ How to install the binary packages depends on your operating system: /etc/privoxy/config as its main configuration file. - - # /etc/init.d/privoxy start +# /etc/init.d/privoxy start - @@ -1079,11 +1235,9 @@ How to install the binary packages depends on your operating system: To start Privoxy manually, run: - - # service privoxy onestart +# service privoxy onestart - @@ -1109,11 +1263,9 @@ Click on the &my-app; Icon to start Privoxy. If no co Example Unix startup command: - - # /usr/sbin/privoxy --user privoxy /etc/privoxy/config +# /usr/sbin/privoxy --user privoxy /etc/privoxy/config - Note that if you installed Privoxy through a package manager, the package will probably contain a platform-specific @@ -1122,16 +1274,6 @@ Example Unix startup command: - -OS/2 - - During installation, Privoxy is configured to - start automatically when the system restarts. You can start it manually by - double-clicking on the Privoxy icon in the - Privoxy folder. - - - Mac OS X @@ -1260,7 +1402,6 @@ must find a better place for this paragraph command-line options: - @@ -1376,7 +1517,6 @@ must find a better place for this paragraph - On MS Windows only there are two additional @@ -1413,20 +1553,18 @@ for details. (shortcut: http://p.p/), which is a built-in page and works without Internet access. You will see the following section: - - +     Privoxy Menu -         ▪  View & change the current configuration -         ▪  View the source code version numbers +         ▪  View or toggle the tags that can be set based on the client's address         ▪  View the request headers. @@ -1484,9 +1622,9 @@ for details. Configuration Files Overview - For Unix, *BSD and Linux, all configuration files are located in - /etc/privoxy/ by default. For MS Windows, OS/2, and - AmigaOS these are all in the same directory as the + For Unix, *BSD and GNU/Linux, all configuration files are located in + /etc/privoxy/ by default. For MS Windows + these are all in the same directory as the Privoxy executable. @@ -1498,13 +1636,12 @@ for details. principle configuration files are: - The main configuration file is named config - on Linux, Unix, BSD, OS/2, and AmigaOS and config.txt + on GNU/Linux, Unix, BSD, and config.txt on Windows. This is a required file. @@ -1556,7 +1693,6 @@ for details. - The syntax of the configuration and filter files may change between different @@ -1642,7 +1778,6 @@ for details. are three action files included with Privoxy with differing purposes: - @@ -1705,8 +1840,7 @@ for details. The default profiles, and their associated actions, as pre-defined in default.action are: - - Default Configurations +
Default Configurations @@ -1823,11 +1957,9 @@ for details.
- - The list of actions files to be used are defined in the main configuration @@ -1951,14 +2083,13 @@ for details. might look like: - - - { +handle-as-image +block{Banner ads.} } - # Block these as if they were images. Send no block page. - banners.example.com - media.example.com/.*banners - .example.com/images/ads/ - + +{ +handle-as-image +block{Banner ads.} } +# Block these as if they were images. Send no block page. +banners.example.com +media.example.com/.*banners +.example.com/images/ads/ + You can trace this process for URL patterns and any given URL by visiting Regular + Regular Expressions (POSIX 1003.2). @@ -2158,7 +2289,7 @@ for details. themselves. These work similarly to shell globbing type wild-cards: * represents zero or more arbitrary characters (this is equivalent to the - Regular + Regular Expression based syntax of .*), ? represents any single character (this is equivalent to the regular expression syntax of a simple .), and you can define @@ -2210,6 +2341,12 @@ for details. While flexible, this is not the sophistication of full regular expression based syntax. + + When compiled with FEATURE_PCRE_HOST_PATTERNS patterns can be prefixed with + PCRE-HOST-PATTERN: in which case full regular expression + (PCRE) can be used for the host pattern as well. + + @@ -2220,7 +2357,7 @@ for details. Privoxy uses modern POSIX 1003.2 - Regular + Regular Expressions for matching the path portion (after the slash), and is thus more flexible. @@ -2278,7 +2415,7 @@ for details. This regular expression is conditional so it will match any page named index.html regardless of path which in this case can have one or more /'s. And this one must contain exactly - .html (but does not have to end with that!). + .html (and end with that!). @@ -2290,6 +2427,7 @@ for details. that contains any of the words ads, banner, banners (because of the ?) or junk. The path does not have to end in these words, just contain them. + The path has to contain at least two slashes (including the one at the beginning). @@ -2398,12 +2536,6 @@ for details. - - - This is an experimental feature. The syntax is likely to change in future versions. - - - Client tag patterns are not set based on HTTP headers but based on the client's IP address. Users can enable them themselves, but the @@ -2434,7 +2566,6 @@ for details. Example: - # If the admin defined the client-specific-tag circumvent-blocks, # and the request comes from a client that previously requested @@ -2447,7 +2578,6 @@ CLIENT-TAG:^circumvent-blocks$ # the previous one. {+block{Nobody is supposed to request this.}} example.org/blocked-example-page - @@ -2469,7 +2599,6 @@ example.org/blocked-example-page following patterns, and -block means don't block URLs that match the following patterns, even if +block previously applied. - @@ -2485,18 +2614,16 @@ example.org/blocked-example-page Actions fall into three categories: - Boolean, i.e the action can only be enabled or disabled. Syntax: - - +name # enable action name - -name # disable action name - ++name # enable action name +-name # disable action name + Example: +handle-as-image @@ -2508,12 +2635,11 @@ example.org/blocked-example-page Parameterized, where some value is required in order to enable this type of action. Syntax: - - - +name{param} # enable action and set parameter to param, - # overwriting parameter from previous match if necessary - -name # disable action. The parameter can be omitted - + ++name{param} # enable action and set parameter to param, + # overwriting parameter from previous match if necessary +-name # disable action. The parameter can be omitted + Note that if the URL matches multiple positive forms of a parameterized action, the last match wins, i.e. the params from earlier matches are simply ignored. @@ -2532,13 +2658,12 @@ example.org/blocked-example-page that can be executed for the same request repeatedly, like adding multiple headers, or filtering through multiple filters. Syntax: - - - +name{param} # enable action and add param to the list of parameters - -name{param} # remove the parameter param from the list of parameters - # If it was the last one left, disable the action. - -name # disable this action completely and remove all parameters from the list - + ++name{param} # enable action and add param to the list of parameters +-name{param} # remove the parameter param from the list of parameters + # If it was the last one left, disable the action. +-name # disable this action completely and remove all parameters from the list + Examples: +add-header{X-Fun-Header: Some text} and +filter{html-annoyances} @@ -2546,7 +2671,6 @@ example.org/blocked-example-page - If nothing is specified in any actions file, no actions are @@ -2641,7 +2765,6 @@ example.org/blocked-example-page Example usage: - # Add a DNT ("Do not track") header to all requests, # event to those that already have one. # @@ -2652,7 +2775,6 @@ example.org/blocked-example-page # header may make user-tracking easier. {+add-header{DNT: 1}} / - @@ -2741,20 +2863,20 @@ example.org/blocked-example-page Example usage (section): - - {+block{No nasty stuff for you.}} + +{+block{No nasty stuff for you.}} # Block and replace with "blocked" page - .nasty-stuff.example.com +.nasty-stuff.example.com {+block{Doubleclick banners.} +handle-as-image} # Block and replace with image - .ad.doubleclick.net - .ads.r.us/banners/ +.ad.doubleclick.net +.ads.r.us/banners/ {+block{Layered ads.} +handle-as-empty-document} # Block and then ignore - adserver.example.net/.*\.js$ - +adserver.example.net/.*\.js$ + @@ -2825,9 +2947,7 @@ example.org/blocked-example-page Example usage: - +change-x-forwarded-for{block} - @@ -2893,6 +3013,21 @@ example.org/blocked-example-page one. This can be used to rewrite the request destination behind the client's back, for example to specify a Tor exit relay for certain requests. + + Note that to change the destination host for + https-inspected + requests a protocol and host has to be added to the URI. + + + If https inspection + is enabled, the protocol can be downgraded from https to http + but upgrading a request from http to https is currently not + supported. + + + After detecting a rewrite, &my-app; does not update the actions + used for the request based on the new host. + Please refer to the filter file chapter to learn which client-header filters are available by default, and how to @@ -2905,30 +3040,27 @@ example.org/blocked-example-page Example usage (section): - # Hide Tor exit notation in Host and Referer Headers {+client-header-filter{hide-tor-exit-notation}} / - - + - - -client-header-tagger + +client-body-filter Typical use: - Block requests based on their headers. + Rewrite or remove client request body. @@ -2937,9 +3069,8 @@ example.org/blocked-example-page Effect: - Client headers to which this action applies are filtered on-the-fly through - the specified regular expression based substitutions, the result is used as - tag. + All request bodies to which this action applies are filtered on-the-fly through + the specified regular expression based substitutions. @@ -2956,7 +3087,7 @@ example.org/blocked-example-page Parameter: - The name of a client-header tagger, as defined in one of the + The name of a client-body filter, as defined in one of the filter files. @@ -2966,77 +3097,31 @@ example.org/blocked-example-page Notes: - Client-header taggers are applied to each header on its own, - and as the header isn't modified, each tagger sees - the original. + Please refer to the filter file chapter + to learn how to create your own client-body filters. - Client-header taggers are the first actions that are executed - and their tags can be used to control every other action. + The distribution default.filter file contains a selection of + client-body filters for example purposes. - + + The amount of data that can be filtered is limited by the + buffer-limit + option in the main config file. The + default is 4096 KB (4 Megs). Once this limit is exceeded, the whole + request body is passed through unfiltered. + + Example usage (section): - - -# Tag every request with the User-Agent header -{+client-header-tagger{user-agent}} -/ - -# Tagging itself doesn't change the action -# settings, sections with TAG patterns do: -# -# If it's a download agent, use a different forwarding proxy, -# show the real User-Agent and make sure resume works. -{+forward-override{forward-socks5 10.0.0.2:2222 .} \ - -hide-if-modified-since \ - -overwrite-last-modified \ - -hide-user-agent \ - -filter \ - -deanimate-gifs \ -} -TAG:^User-Agent: NetBSD-ftp/ -TAG:^User-Agent: Novell ZYPP Installer -TAG:^User-Agent: RPM APT-HTTP/ -TAG:^User-Agent: fetch libfetch/ -TAG:^User-Agent: Ubuntu APT-HTTP/ -TAG:^User-Agent: MPlayer/ - - - - -# Tag all requests with the Range header set -{+client-header-tagger{range-requests}} -/ - -# Disable filtering for the tagged requests. -# -# With filtering enabled Privoxy would remove the Range headers -# to be able to filter the whole response. The downside is that -# it prevents clients from resuming downloads or skipping over -# parts of multimedia files. -{-filter -deanimate-gifs} -TAG:^RANGE-REQUEST$ - - - -# Tag all requests with the client IP address -# -# (Technically the client IP address isn't included in the -# client headers but client-header taggers can set it anyway. -# For details see the tagger in default.filter) -{+client-header-tagger{client-ip-address}} +# Remove "test" everywhere in the request body +{+client-body-filter{remove-test}} / - -# Change forwarding settings for requests coming from address 10.0.0.1 -{+forward-override{forward-socks5 127.0.1.2:2222 .}} -TAG:^IP-ADDRESS: 10\.0\.0\.1$ - - + @@ -3045,14 +3130,16 @@ TAG:^IP-ADDRESS: 10\.0\.0\.1$ - -content-type-overwrite + +client-body-tagger Typical use: - Stop useless download menus from popping up, or change the browser's rendering mode + + Block requests based on the content of the body data. + @@ -3060,16 +3147,17 @@ TAG:^IP-ADDRESS: 10\.0\.0\.1$ Effect: - Replaces the Content-Type: HTTP server header. + Client request bodies to which this action applies are filtered on-the-fly through + the specified regular expression based substitutions, the result is used as tag. Type: - + - Parameterized. + Multi-value. @@ -3077,7 +3165,8 @@ TAG:^IP-ADDRESS: 10\.0\.0\.1$ Parameter: - Any string. + The name of a client-body tagger, as defined in one of the + filter files. @@ -3086,67 +3175,261 @@ TAG:^IP-ADDRESS: 10\.0\.0\.1$ Notes: - The Content-Type: HTTP server header is used by the - browser to decide what to do with the document. The value of this - header can cause the browser to open a download menu instead of - displaying the document by itself, even if the document's format is - supported by the browser. - - - The declared content type can also affect which rendering mode - the browser chooses. If XHTML is delivered as text/html, - many browsers treat it as yet another broken HTML document. - If it is send as application/xml, browsers with - XHTML support will only display it, if the syntax is correct. - - - If you see a web site that proudly uses XHTML buttons, but sets - Content-Type: text/html, you can use &my-app; - to overwrite it with application/xml and validate - the web master's claim inside your XHTML-supporting browser. - If the syntax is incorrect, the browser will complain loudly. - - - You can also go the opposite direction: if your browser prints - error messages instead of rendering a document falsely declared - as XHTML, you can overwrite the content type with - text/html and have it rendered as broken HTML document. - - - By default content-type-overwrite only replaces - Content-Type: headers that look like some kind of text. - If you want to overwrite it unconditionally, you have to combine it with - force-text-mode. - This limitation exists for a reason, think twice before circumventing it. + Please refer to the filter file chapter + to learn how to create your own client-body tagger. - Most of the time it's easier to replace this action with a custom - server-header filter. - It allows you to activate it for every document of a certain site and it will still - only replace the content types you aimed at. + Client-body taggers are applied to each request body on its own, + and as the body isn't modified, each tagger "sees" the original. - Of course you can apply content-type-overwrite - to a whole site and then make URL based exceptions, but it's a lot - more work to get the same precision. + Chunk-encoded request bodies currently can't be tagged. + Request bodies larger than the buffer-limit can't be tagged either. - Example usage (sections): + Example usage (section): - - # Check if www.example.net/ really uses valid XHTML -{ +content-type-overwrite{application/xml} } -www.example.net/ - + +# Apply blafasel tagger. +{+client-body-tagger{blafasel}} +/ + +# Block request based on the tag created by the blafasel tagger. +{+block{Request body contains blafasel}} +TAG:^content contains blafasel$ + + + + + + + + + + +client-header-tagger + + + + Typical use: + + + Block requests based on their headers. + + + + + + Effect: + + + Client headers to which this action applies are filtered on-the-fly through + the specified regular expression based substitutions, the result is used as + tag. + + + + + + Type: + + + Multi-value. + + + + + Parameter: + + + The name of a client-header tagger, as defined in one of the + filter files. + + + + + + Notes: + + + Client-header taggers are applied to each header on its own, + and as the header isn't modified, each tagger sees + the original. + + + Client-header taggers are the first actions that are executed + and their tags can be used to control every other action. + + + + + + Example usage (section): + + +# Tag every request with the User-Agent header +{+client-header-tagger{user-agent}} +/ + +# Tagging itself doesn't change the action +# settings, sections with TAG patterns do: +# +# If it's a download agent, use a different forwarding proxy, +# show the real User-Agent and make sure resume works. +{+forward-override{forward-socks5 10.0.0.2:2222 .} \ + -hide-if-modified-since \ + -overwrite-last-modified \ + -hide-user-agent \ + -filter \ + -deanimate-gifs \ +} +TAG:^User-Agent: NetBSD-ftp/ +TAG:^User-Agent: Novell ZYPP Installer +TAG:^User-Agent: RPM APT-HTTP/ +TAG:^User-Agent: fetch libfetch/ +TAG:^User-Agent: Ubuntu APT-HTTP/ +TAG:^User-Agent: MPlayer/ + + + +# Tag all requests with the Range header set +{+client-header-tagger{range-requests}} +/ + +# Disable filtering for the tagged requests. +# +# With filtering enabled Privoxy would remove the Range headers +# to be able to filter the whole response. The downside is that +# it prevents clients from resuming downloads or skipping over +# parts of multimedia files. +{-filter -deanimate-gifs} +TAG:^RANGE-REQUEST$ + + + +# Tag all requests with the client IP address +# +# (Technically the client IP address isn't included in the +# client headers but client-header taggers can set it anyway. +# For details see the tagger in default.filter) +{+client-header-tagger{client-ip-address}} +/ + +# Change forwarding settings for requests coming from address 10.0.0.1 +{+forward-override{forward-socks5 127.0.1.2:2222 .}} +TAG:^IP-ADDRESS: 10\.0\.0\.1$ + + + + + + + + + + +content-type-overwrite + + + + Typical use: + + Stop useless download menus from popping up, or change the browser's rendering mode + + + + + Effect: + + + Replaces the Content-Type: HTTP server header. + + + + + + Type: + + + Parameterized. + + + + + Parameter: + + + Any string. + + + + + + Notes: + + + The Content-Type: HTTP server header is used by the + browser to decide what to do with the document. The value of this + header can cause the browser to open a download menu instead of + displaying the document by itself, even if the document's format is + supported by the browser. + + + The declared content type can also affect which rendering mode + the browser chooses. If XHTML is delivered as text/html, + many browsers treat it as yet another broken HTML document. + If it is send as application/xml, browsers with + XHTML support will only display it, if the syntax is correct. + + + If you see a web site that proudly uses XHTML buttons, but sets + Content-Type: text/html, you can use &my-app; + to overwrite it with application/xml and validate + the web master's claim inside your XHTML-supporting browser. + If the syntax is incorrect, the browser will complain loudly. + + + You can also go the opposite direction: if your browser prints + error messages instead of rendering a document falsely declared + as XHTML, you can overwrite the content type with + text/html and have it rendered as broken HTML document. + + + By default content-type-overwrite only replaces + Content-Type: headers that look like some kind of text. + If you want to overwrite it unconditionally, you have to combine it with + force-text-mode. + This limitation exists for a reason, think twice before circumventing it. + + + Most of the time it's easier to replace this action with a custom + server-header filter. + It allows you to activate it for every document of a certain site and it will still + only replace the content types you aimed at. + + + Of course you can apply content-type-overwrite + to a whole site and then make URL based exceptions, but it's a lot + more work to get the same precision. + + + + + + Example usage (sections): + + # Check if www.example.net/ really uses valid XHTML +{ +content-type-overwrite{application/xml} } +www.example.net/ + # but leave the content type unmodified if the URL looks like a style sheet {-content-type-overwrite} www.example.net/.*\.css$ www.example.net/.*style - @@ -3225,12 +3508,10 @@ new action Example usage (section): - # Block the non-existent "Privacy-Violation:" client header { +crunch-client-header{Privacy-Violation:} } / - - + @@ -3307,14 +3588,13 @@ new action Example usage (section): - # Let the browser revalidate cached documents but don't # allow the server to use the revalidation headers for user tracking. {+hide-if-modified-since{-60} \ +overwrite-last-modified{randomize} \ +crunch-if-none-match} -/ - +/ + @@ -3382,9 +3662,7 @@ new action Example usage: - +crunch-incoming-cookies - @@ -3461,11 +3739,10 @@ new action Example usage (section): - # Crunch server headers that try to prevent caching { +crunch-server-header{no-cache} } -/ - +/ + @@ -3532,9 +3809,7 @@ new action Example usage: - +crunch-outgoing-cookies - @@ -3602,14 +3877,82 @@ new action Example usage: - +deanimate-gifs{last} - + + + +delay-response + + + + Typical use: + + Delay responses to the client to reduce the load + + + + + Effect: + + + Delays responses to the client by sending the response in ca. 10 byte chunks. + + + + + + Type: + + + Parameterized. + + + + + Parameter: + + + Number of milliseconds + + + + + + Notes: + + + Sometimes when JavaScript code is used to fetch advertisements + it doesn't respect Privoxy's blocks and retries to fetch the + same resource again causing unnecessary load on the client. + + + This action delays responses to the client and can be combined + with blocks + to slow down the JavaScript code, thus reducing + the load on the client. + + + When used without blocks + the action can also be used to simulate a slow internet connection. + + + + + + Example usage: + + +delay-response{100} + + + + + + downgrade-http-version @@ -3674,16 +4017,15 @@ new action Example usage (section): - {+downgrade-http-version} problem-host.example.com - + external-filter @@ -3764,9 +4106,7 @@ problem-host.example.com Example usage: - +external-filter{fancy-filter} - @@ -3871,7 +4211,7 @@ problem-host.example.com looks for the string http://, either in plain text (invalid but often used) or encoded as http%3a//. Some sites use their own URL encoding scheme, encrypt the address - of the target server or replace it with a database id. In theses cases + of the target server or replace it with a database id. In these cases fast-redirects is fooled and the request reaches the redirection server where it probably gets logged. @@ -3881,14 +4221,13 @@ problem-host.example.com Example usage: - - { +fast-redirects{simple-check} } - one.example.com +{ +fast-redirects{simple-check} } +one.example.com - { +fast-redirects{check-decoded-url} } - another.example.com/testing - +{ +fast-redirects{check-decoded-url} } +another.example.com/testing + @@ -3968,15 +4307,15 @@ problem-host.example.com Rolling your own filters requires a knowledge of - Regular + Regular Expressions and - HTML. + HTML. This is very powerful feature, and potentially very intrusive. Filters should be used with caution, and where an equivalent action is not available. - The amount of data that can be filtered is limited to the + The amount of data that can be filtered is limited by the buffer-limit option in the main config file. The default is 4096 KB (4 Megs). Once this limit is exceeded, the buffered @@ -4030,112 +4369,128 @@ problem-host.example.com - +filter{js-annoyances} # Get rid of particularly annoying JavaScript abuse. + +filter{js-annoyances} # Get rid of particularly annoying JavaScript abuse. - +filter{js-events} # Kill JavaScript event bindings and timers (Radically destructive! Only for extra nasty sites). + +filter{js-events} # Kill JavaScript event bindings and timers (Radically destructive! Only for extra nasty sites). - +filter{html-annoyances} # Get rid of particularly annoying HTML abuse. + +filter{html-annoyances} # Get rid of particularly annoying HTML abuse. - +filter{content-cookies} # Kill cookies that come in the HTML or JS content. + +filter{content-cookies} # Kill cookies that come in the HTML or JS content. - +filter{refresh-tags} # Kill automatic refresh tags if refresh time is larger than 9 seconds. + +filter{refresh-tags} # Kill automatic refresh tags if refresh time is larger than 9 seconds. - +filter{unsolicited-popups} # Disable only unsolicited pop-up windows. + +filter{unsolicited-popups} # Disable only unsolicited pop-up windows. - +filter{all-popups} # Kill all popups in JavaScript and HTML. + +filter{all-popups} # Kill all popups in JavaScript and HTML. - +filter{img-reorder} # Reorder attributes in <img> tags to make the banners-by-* filters more effective. + +filter{img-reorder} # Reorder attributes in <img> tags to make the banners-by-* filters more effective. - +filter{banners-by-size} # Kill banners by size. + +filter{banners-by-size} # Kill banners by size. - +filter{banners-by-link} # Kill banners by their links to known clicktrackers. + +filter{banners-by-link} # Kill banners by their links to known clicktrackers. - +filter{webbugs} # Squish WebBugs (1x1 invisible GIFs used for user tracking). + +filter{webbugs} # Squish WebBugs (1x1 invisible GIFs used for user tracking). - +filter{tiny-textforms} # Extend those tiny textareas up to 40x80 and kill the hard wrap. + +filter{tiny-textforms} # Extend those tiny textareas up to 40x80 and kill the hard wrap. - +filter{jumping-windows} # Prevent windows from resizing and moving themselves. + +filter{jumping-windows} # Prevent windows from resizing and moving themselves. - +filter{frameset-borders} # Give frames a border and make them resizable. + +filter{frameset-borders} # Give frames a border and make them resizable. - +filter{iframes} # Removes all detected iframes. Should only be enabled for individual sites. + +filter{iframes} # Removes all detected iframes. Should only be enabled for individual sites. - +filter{demoronizer} # Fix MS's non-standard use of standard charsets. + +filter{demoronizer} # Fix MS's non-standard use of standard charsets. - +filter{shockwave-flash} # Kill embedded Shockwave Flash objects. + +filter{shockwave-flash} # Kill embedded Shockwave Flash objects. - +filter{quicktime-kioskmode} # Make Quicktime movies saveable. + +filter{quicktime-kioskmode} # Make Quicktime movies saveable. - +filter{fun} # Text replacements for subversive browsing fun! + +filter{fun} # Text replacements for subversive browsing fun! - +filter{crude-parental} # Crude parental filtering. Note that this filter doesn't work reliably. + +filter{crude-parental} # Crude parental filtering. Note that this filter doesn't work reliably. - +filter{ie-exploits} # Disable some known Internet Explorer bug exploits. + +filter{ie-exploits} # Disable some known Internet Explorer bug exploits. - +filter{site-specifics} # Cure for site-specific problems. Don't apply generally! + +filter{site-specifics} # Cure for site-specific problems. Don't apply generally! + +filter{no-ping} # Removes non-standard ping attributes in <a> and <area> tags. + + + + +filter{bundeswehr.de} # Hide the cookie and privacy info banner on bundeswehr.de. + + + +filter{github} # Removes the annoying "Sign-Up" banner and the Cookie disclaimer. + +filter{google} # CSS-based block for Google text ads. Also removes a width limitation and the toolbar advertisement. + + + +filter{imdb} # Removes some ads on IMDb. - +filter{yahoo} # CSS-based block for Yahoo text ads. Also removes a width limitation. + +filter{yahoo} # CSS-based block for Yahoo text ads. Also removes a width limitation. - +filter{msn} # CSS-based block for MSN text ads. Also removes tracking URLs and a width limitation. + +filter{msn} # CSS-based block for MSN text ads. Also removes tracking URLs and a width limitation. + +filter{blogspot} # Cleans up some Blogspot blogs. Read the fine print before using this. + + + +filter{sourceforge} # Reduces the amount of ads for proprietary software on SourceForge. @@ -4205,11 +4560,9 @@ new action Example usage: - +force-text-mode - - + @@ -4338,7 +4691,6 @@ new action Example usage: - # Use an ssh tunnel for requests previously tagged as # User-Agent: fetch libfetch/2.0 and make sure @@ -4355,8 +4707,7 @@ new action -overwrite-last-modified \ } TAG:^User-Agent: fetch libfetch/2\.0$ - - + @@ -4428,13 +4779,11 @@ new action Example usage: - # Block all documents on example.org that end with ".js", # but send an empty document instead of the usual HTML message. {+block{Blocked JavaScript} +handle-as-empty-document} example.org/.*\.js$ - - + @@ -4509,7 +4858,6 @@ example.org/.*\.js$ Example usage (sections): - # Generic image extensions: # {+handle-as-image} @@ -4521,7 +4869,6 @@ example.org/.*\.js$ {+block{Nasty banners.} +handle-as-image} nasty-banner-server.example.com/junk.cgi\?output=trash - @@ -4601,13 +4948,12 @@ new action Example usage (section): - # Pretend to use Canadian language settings. {+hide-accept-language{en-ca} \ +hide-user-agent{Mozilla/5.0 (X11; U; OpenBSD i386; en-CA; rv:1.8.0.4) Gecko/20060628 Firefox/1.5.0.4} \ } -/ - +/ + @@ -4691,13 +5037,14 @@ new action Example usage: - - # Disarm the download link in Sourceforge's patch tracker + +# Disarm the download link in Sourceforge's patch tracker { -filter \ - +content-type-overwrite{text/plain}\ - +hide-content-disposition{block} } - .sourceforge.net/tracker/download\.php - + +content-type-overwrite{text/plain} \ + +hide-content-disposition{block} \ +} +.sourceforge.net/tracker/download\.php + @@ -4780,13 +5127,11 @@ new action Example usage (section): - # Let the browser revalidate but make tracking based on the time less likely. {+hide-if-modified-since{-60} \ +overwrite-last-modified{randomize} \ +crunch-if-none-match} / - @@ -4855,10 +5200,9 @@ new action Example usage: - - +hide-from-header{block} or + +hide-from-header{block} + or +hide-from-header{spam-me-senseless@sittingduck.example.com} - @@ -4959,10 +5303,9 @@ new action Example usage: - - +hide-referrer{forge} or + +hide-referrer{forge} + or +hide-referrer{http://www.yahoo.com/} - @@ -5033,17 +5376,160 @@ new action More information on known user-agent strings can be found at http://www.user-agents.org/ and - http://en.wikipedia.org/wiki/User_agent. + http://en.wikipedia.org/wiki/User_agent. Example usage: + + +hide-user-agent{Mozilla/5.0 (X11; ElectroBSD i386; rv:78.0) Gecko/20100101 Firefox/78.0} + + + + + + + + +https-inspection + + + + Typical use: + + Filter encrypted requests and responses + + + + + Effect: + + + Encrypted requests are decrypted, filtered and forwarded encrypted. + + + + + + Type: + + + Boolean. + + + + + Parameter: + + + N/A + + + + + + Notes: + + + This action allows &my-app; to filter encrypted requests and responses. + For this to work &my-app; has to generate a certificate for the web site + and send it to the client which has to accept it. + + + Before this works the directives in the + HTTPS inspection section + of the config file have to be configured. + + + Note that the action has to be enabled based on the CONNECT + request which doesn't contain a path. Enabling it based on + a pattern with path doesn't work as the path is only seen + by &my-app; if the action is already enabled. + + + + + + Example usage (section): + + {+https-inspection} +www.example.com + + + + + + + + + +ignore-certificate-errors + + + + Typical use: + + Filter encrypted requests and responses without verifying the certificate + + + + + Effect: + + + Encrypted requests are forwarded to sites without verifying the certificate. + + + + + + Type: + + + Boolean. + + + + + Parameter: + + + N/A + + + + + + Notes: - +hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)} + When the + +https-inspection + action is used &my-app; by default verifies that the remote site uses a valid + certificate. + + If the certificate can't be validated by &my-app; the connection is aborted. + + + This action disables the certificate check so requests to sites + with certificates that can't be validated are allowed. + + + Note that enabling this action allows Man-in-the-middle attacks. + + + + + + Example usage: + + + {+ignore-certificate-errors} + www.example.org + @@ -5119,13 +5605,11 @@ new action - +limit-connect{443} # Port 443 is OK. +limit-connect{80,443} # Ports 80 and 443 are OK. +limit-connect{-3, 7, 20-100, 500-} # Ports less than 3, 7, 20 to 100 and above 500 are OK. +limit-connect{-} # All ports are OK +limit-connect{,} # No HTTPS/SSL traffic is allowed - @@ -5210,10 +5694,7 @@ new action Example usages: - - +limit-cookie-lifetime{60} - - + +limit-cookie-lifetime{60} @@ -5289,9 +5770,10 @@ new action Note that some (rare) ill-configured sites don't handle requests for uncompressed documents correctly. Broken PHP applications tend to send an empty document body, - some IIS versions only send the beginning of the content. If you enable - prevent-compression per default, you might want to add - exceptions for those sites. See the example for how to do that. + some IIS versions only send the beginning of the content and some content delivery + networks let the connection time out. + If you enable prevent-compression per default, you might + want to add exceptions for those sites. See the example for how to do that. @@ -5299,26 +5781,25 @@ new action Example usage (sections): - # Selectively turn off compression, and enable a filter # { +filter{tiny-textforms} +prevent-compression } # Match only these sites - .google. - sourceforge.net - sf.net +.google. +sourceforge.net +sf.net # Or instead, we could set a universal default: # { +prevent-compression } - / # Match all sites +/ # Match all sites # Then maybe make exceptions for broken sites: # { -prevent-compression } -.compusa.com/ - +.compusa.com/ + @@ -5410,13 +5891,14 @@ new action Example usage: - - # Let the browser revalidate without being tracked across sessions + +# Let the browser revalidate without being tracked across sessions { +hide-if-modified-since{-60} \ - +overwrite-last-modified{randomize} \ - +crunch-if-none-match} -/ - + +overwrite-last-modified{randomize} \ + +crunch-if-none-match \ +} +/ + @@ -5507,15 +5989,15 @@ new action Example usages: - - # Replace example.com's style sheet with another one + +# Replace example.com's style sheet with another one { +redirect{http://localhost/css-replacements/example.com.css} } - example.com/stylesheet\.css +example.com/stylesheet\.css # Create a short, easy to remember nickname for a favorite site # (relies on the browser to accept and forward invalid URLs to &my-app;) { +redirect{https://www.privoxy.org/user-manual/actions-file.html} } - a +a # Always use the expanded view for Undeadly.org articles # (Note the $ at the end of the URL pattern to make sure @@ -5544,11 +6026,14 @@ example.com/.*toChange=(?!bar) # Redirect Destination = https://www.illumos.org/issues/4974 i[0-9][0-9][0-9][0-9]*/ +# Redirect requests for the old Tor Hidden Service of the Privoxy website to the new one +{+redirect{s@^http://jvauzb4sb3bwlsnc.onion/@http://l3tczdiiwoo63iwxty4lhs6p7eaxop5micbn7vbliydgv63x5zrrrfyd.onion/@}} +jvauzb4sb3bwlsnc.onion/ + # Redirect remote requests for this manual # to the local version delivered by Privoxy {+redirect{s@^http://www@http://config@}} www.privoxy.org/user-manual/ - @@ -5622,15 +6107,13 @@ www.privoxy.org/user-manual/ Example usage (section): - {+server-header-filter{html-to-xml}} example.org/xml-instance-that-is-delivered-as-html {+server-header-filter{xml-to-html}} example.org/instance-that-is-delivered-as-xml-but-is-not - - + @@ -5707,7 +6190,6 @@ example.org/instance-that-is-delivered-as-xml-but-is-not Example usage (section): - # Tag every request with the content type declared by the server {+server-header-tagger{content-type}} @@ -5720,8 +6202,64 @@ example.org/instance-that-is-delivered-as-xml-but-is-not # silly example. {+external-filter{rotate-image} +force-text-mode} TAG:^image/ - - + + + + + + + + + + +suppress-tag + + + + Typical use: + + + Suppress client or server tag. + + + + + + Effect: + + + Server or client tags to which this action applies are not added to the request, + thus making all actions that are specific to these request tags inactive. + + + + + + Type: + + + Multi-value. + + + + + Parameter: + + + The result tag of a server-header or client-header tagger, as defined in one of the + filter files. + + + + + + Example usage (section): + + +# Suppress tag produced by range-requests client-header tagger for requests coming from address 10.0.0.1 +{+suppress-tag{RANGE-REQUEST}} +TAG:^IP-ADDRESS: 10\.0\.0\.1$ + @@ -5814,9 +6352,7 @@ TAG:^image/ Example usage: - +session-cookies-only - @@ -5916,21 +6452,15 @@ TAG:^image/ Built-in pattern: - +set-image-blocker{pattern} - Redirect to the BSD daemon: - +set-image-blocker{http://www.freebsd.org/gifs/dae_up3.gif} - Redirect to the built-in pattern for better caching: - +set-image-blocker{http://config.privoxy.org/send-banner?type=pattern} - @@ -5997,35 +6527,34 @@ TAG:^image/ Now let's define some aliases... - - # Useful custom aliases we can use later. - # - # Note the (required!) section header line and that this section - # must be at the top of the actions file! - # - {{alias}} +# Useful custom aliases we can use later. +# +# Note the (required!) section header line and that this section +# must be at the top of the actions file! +# +{{alias}} - # These aliases just save typing later: - # (Note that some already use other aliases!) - # - +crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies - -crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies - +block-as-image = +block{Blocked image.} +handle-as-image - allow-all-cookies = -crunch-all-cookies -session-cookies-only -filter{content-cookies} +# These aliases just save typing later: +# (Note that some already use other aliases!) +# ++crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies +-crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies ++block-as-image = +block{Blocked image.} +handle-as-image +allow-all-cookies = -crunch-all-cookies -session-cookies-only -filter{content-cookies} - # These aliases define combinations of actions - # that are useful for certain types of sites: - # - fragile = -block -filter -crunch-all-cookies -fast-redirects -hide-referrer -prevent-compression +# These aliases define combinations of actions +# that are useful for certain types of sites: +# +fragile = -block -filter -crunch-all-cookies -fast-redirects -hide-referrer -prevent-compression - shop = -crunch-all-cookies -filter{all-popups} +shop = -crunch-all-cookies -filter{all-popups} - # Short names for other aliases, for really lazy people ;-) - # - c0 = +crunch-all-cookies - c1 = -crunch-all-cookies - +# Short names for other aliases, for really lazy people ;-) +# +c0 = +crunch-all-cookies +c1 = -crunch-all-cookies + ...and put them to use. These sections would appear in the lower part of an @@ -6033,31 +6562,30 @@ TAG:^image/ up for the / pattern): - - # These sites are either very complex or very keen on - # user data and require minimal interference to work: - # - {fragile} - .office.microsoft.com - .windowsupdate.microsoft.com - # Gmail is really mail.google.com, not gmail.com - mail.google.com - - # Shopping sites: - # Allow cookies (for setting and retrieving your customer data) - # - {shop} - .quietpc.com - .worldpay.com # for quietpc.com - mybank.example.com +# These sites are either very complex or very keen on +# user data and require minimal interference to work: +# +{fragile} +.office.microsoft.com +.windowsupdate.microsoft.com +# Gmail is really mail.google.com, not gmail.com +mail.google.com - # These shops require pop-ups: - # - {-filter{all-popups} -filter{unsolicited-popups}} - .dabs.com - .overclockers.co.uk - +# Shopping sites: +# Allow cookies (for setting and retrieving your customer data) +# +{shop} +.quietpc.com +.worldpay.com # for quietpc.com +mybank.example.com + +# These shops require pop-ups: +# +{-filter{all-popups} -filter{unsolicited-popups}} +.dabs.com +.overclockers.co.uk + Aliases like shop and fragile are typically used for @@ -6108,7 +6636,6 @@ hal stop here multiple lines with line continuation. - { \ +change-x-forwarded-for{block} \ @@ -6116,8 +6643,7 @@ hal stop here +set-image-blocker{pattern} \ } / # Match all URLs - - + The default behavior is now set. @@ -6144,14 +6670,12 @@ hal stop here that prevents older &my-app; versions from reading the file: - ########################################################################## # Settings -- Don't change! For internal Privoxy use ONLY. ########################################################################## {{settings}} for-privoxy-version=3.0.11 - After that comes the (optional) alias section. We'll use the example @@ -6159,7 +6683,6 @@ for-privoxy-version=3.0.11 that also explains why and how aliases are used: - ########################################################################## # Aliases @@ -6171,7 +6694,7 @@ for-privoxy-version=3.0.11 # +crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies -crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies - +block-as-image = +block{Blocked image.} +handle-as-image + +block-as-image = +block{Blocked image.} +handle-as-image mercy-for-cookies = -crunch-all-cookies -session-cookies-only -filter{content-cookies} # These aliases define combinations of actions @@ -6179,7 +6702,6 @@ for-privoxy-version=3.0.11 # fragile = -block -filter -crunch-all-cookies -fast-redirects -hide-referrer shop = -crunch-all-cookies -filter{all-popups} - The first of our specialized sections is concerned with fragile @@ -6190,7 +6712,6 @@ for-privoxy-version=3.0.11 of actions explicitly: - ########################################################################## # Exceptions for sites that'll break under the default action set: @@ -6202,7 +6723,6 @@ for-privoxy-version=3.0.11 .office.microsoft.com # surprise, surprise! .windowsupdate.microsoft.com mail.google.com - Shopping sites are not as fragile, but they typically @@ -6210,7 +6730,6 @@ mail.google.com carts or item details. Again, we'll use a pre-defined alias: - # Shopping sites: # @@ -6219,7 +6738,6 @@ mail.google.com .worldpay.com # for quietpc.com .jungle.com .scan.co.uk - The fast-redirects @@ -6227,7 +6745,6 @@ mail.google.com breaks some sites. So disable it for popular sites where we know it misbehaves: - { -fast-redirects } login.yahoo.com @@ -6236,7 +6753,6 @@ edit.*.yahoo.com .altavista.com/.*(like|url|link):http .altavista.com/trans.*urltext=http .nytimes.com - It is important that Privoxy knows which @@ -6251,7 +6767,6 @@ edit.*.yahoo.com good start: - ########################################################################## # Images: @@ -6262,7 +6777,6 @@ edit.*.yahoo.com # { +handle-as-image } /.*\.(gif|jpe?g|png|bmp|ico)$ - And then there are known banner sources. They often use scripts to @@ -6279,7 +6793,6 @@ edit.*.yahoo.com action before, it still applies and needn't be repeated: - # Known ad generators: # @@ -6291,7 +6804,6 @@ ar.atwola.com .a[0-9].yimg.com/(?:(?!/i/).)*$ bs*.gsanet.com .qkimg.net - One of the most important jobs of Privoxy @@ -6311,7 +6823,6 @@ bs*.gsanet.com to keep the example short: - ########################################################################## # Block these fine banners: @@ -6330,7 +6841,6 @@ count*. # Site-specific patterns (abbreviated): # .hitbox.com - It's quite remarkable how many advertisers actually call their banner @@ -6360,7 +6870,6 @@ count*. with no block action applying. - ########################################################################## # Save some innocent victims of the above generic block patterns: @@ -6384,7 +6893,6 @@ ad[ud]*. # (adult.* and add.*) # www.globalintersec.com/adv # (adv = advanced) www.ugu.com/sui/ugu/adv - Filtering source code can have nasty side effects, @@ -6394,7 +6902,6 @@ www.ugu.com/sui/ugu/adv disables all filters in one fell swoop! - # Don't filter code! # @@ -6404,7 +6911,6 @@ bugzilla. developer. wiki. .sourceforge.net - The actual default.action is of course much more @@ -6438,10 +6944,8 @@ wiki. - # My user.action file. <fred@example.com> - As aliases are local to the actions @@ -6449,7 +6953,6 @@ wiki. default.action, unless you repeat them here: - # Aliases are local to the file they are defined in. # (Re-)define aliases for this file: @@ -6480,8 +6983,6 @@ allow-ads = -block -filter{banners-by-size} -filter{banners-by-link} # MIME types. We want the browser to force these to be text documents. handle-as-text = -filter +-content-type-overwrite{text/plain} +-force-text-mode -hide-content-disposition - - Say you have accounts on some sites that you visit regularly, and you don't want to have to log in manually each time. So you'd like @@ -6491,30 +6992,27 @@ handle-as-text = -filter +-filter } - .your-home-banking-site.com - +.your-home-banking-site.com + Some file types you may not want to filter for various reasons: - # Technical documentation is likely to contain strings that might # erroneously get altered by the JavaScript-oriented filters: @@ -6526,7 +7024,6 @@ handle-as-text = -filter +-block action. Say you've @@ -6539,12 +7036,11 @@ stupid-server.example.com/ in default.action anyway: - { +block{Nasty ads.} } - www.example.com/nasty-ads/sponsor\.gif - another.example.net/more/junk/here/ - +www.example.com/nasty-ads/sponsor\.gif +another.example.net/more/junk/here/ + The URLs of dynamically generated banners, especially from large banner @@ -6558,14 +7054,13 @@ stupid-server.example.com/ browser. Use cautiously. - { +block-as-image } - .doubleclick.net - .fastclick.net - /Realmedia/ads/ - ar.atwola.com/ - +.doubleclick.net +.fastclick.net +/Realmedia/ads/ +ar.atwola.com/ + Now you noticed that the default configuration breaks Forbes Magazine, @@ -6579,13 +7074,12 @@ stupid-server.example.com/ that misbehave, and add those to our personalized list of troublemakers: - { fragile } - .forbes.com - webmail.example.com - .mybank.com - +.forbes.com +webmail.example.com +.mybank.com + You like the fun text replacements in default.filter, @@ -6594,11 +7088,10 @@ stupid-server.example.com/ update-safe config, once and for all: - { +filter{fun} } - / # For ALL sites! - +/ # For ALL sites! + Note that the above is not really a good idea: There are exceptions @@ -6615,13 +7108,12 @@ stupid-server.example.com/ sites that you feel provide value to you: - { allow-ads } - .sourceforge.net - .slashdot.org - .osdn.net - +.sourceforge.net +.slashdot.org +.osdn.net + Note that allow-ads has been aliased to @@ -6637,11 +7129,10 @@ stupid-server.example.com/ it should I choose to. - { handle-as-text } - /.*\.sh$ - +/.*\.sh$ + user.action is generally the best place to define @@ -6653,11 +7144,9 @@ stupid-server.example.com/ paths and patterns: - { +set-image-blocker{blank} } / # ALL sites - @@ -6680,18 +7169,21 @@ stupid-server.example.com/ - &my-app; supports three different pcrs-based filter actions: + &my-app; supports four different pcrs-based filter actions: filter to rewrite the content that is send to the client, client-header-filter - to rewrite headers that are send by the client, and + to rewrite headers that are send by the client, server-header-filter - to rewrite headers that are send by the server. + to rewrite headers that are send by the server, and + client-body-filter + to rewrite client request body. - &my-app; also supports two tagger actions: - client-header-tagger + &my-app; also supports three tagger actions: + client-header-tagger, + client-body-tagger and server-header-tagger. Taggers and filters use the same syntax in the filter files, the difference @@ -6745,7 +7237,8 @@ stupid-server.example.com/ filter file is organized in sections, which are called filters here. Each filter consists of a heading line, that starts with one of the keywords FILTER:, - CLIENT-HEADER-FILTER: or SERVER-HEADER-FILTER: + CLIENT-HEADER-FILTER:, SERVER-HEADER-FILTER: or + CLIENT-BODY-FILTER: followed by the filter's name, and a short (one line) description of what it does. Below that line come the jobs, i.e. lines that define the actual @@ -6769,9 +7262,7 @@ stupid-server.example.com/ like this: - FILTER: foo Replace all "foo" with "bar" - Below that line, and up to the next header line, come the jobs that @@ -6814,7 +7305,7 @@ stupid-server.example.com/ If you are new to - Regular + Regular Expressions, you might want to take a look at the Appendix on regular expressions, and see the Perl @@ -6837,9 +7328,7 @@ stupid-server.example.com/ needed: - s/foo/bar/ - But wait! Didn't the comment say that all occurrences @@ -6848,17 +7337,14 @@ stupid-server.example.com/ we'll need to add the g option: - s/foo/bar/g - Our complete filter now looks like this: - + FILTER: foo Replace all "foo" with "bar" s/foo/bar/g - Let's look at some real filters for more interesting examples. Here you see @@ -6867,14 +7353,12 @@ s/foo/bar/g - FILTER: js-annoyances Get rid of particularly annoying JavaScript abuse # Get rid of JavaScript referrer tracking. Test page: http://www.randomoddness.com/untitled.htm # s|(<script.*)document\.referrer(.*</script>)|$1"Not Your Business!"$2|Usg - Following the header line and a comment, you see the job. Note that it uses @@ -6956,12 +7440,10 @@ s|(<script.*)document\.referrer(.*</script>)|$1"Not Your Business!"$2|U this time only point out the constructs of special interest: - # The status bar is for displaying link targets, not pointless blahblah # s/window\.status\s*=\s*(['"]).*?\1/dUmMy=1/ig - \s stands for whitespace characters (space, tab, newline, @@ -6984,12 +7466,10 @@ s/window\.status\s*=\s*(['"]).*?\1/dUmMy=1/ig you move your mouse over links. - # Kill OnUnload popups. Yummy. Test: http://www.zdnet.com/zdsubs/yahoo/tree/yfs.html # s/(<body [^>]*)onunload(.*>)/$1never$2/iU - Including the @@ -7010,14 +7490,12 @@ s/(<body [^>]*)onunload(.*>)/$1never$2/iU The last example is from the fun department: - FILTER: fun Fun text replacements # Spice the daily news: # s/microsoft(?!\.com)/MicroSuck/ig - Note the (?!\.com) part (a so-called negative lookahead) @@ -7027,7 +7505,6 @@ s/microsoft(?!\.com)/MicroSuck/ig still replacing the word everywhere else. - # Buzzword Bingo (example for extended regex syntax) # @@ -7043,7 +7520,6 @@ s* industry[ -]leading \ | unrivalled \ *<font color="red"><b>BINGO!</b></font> \ *igx - The x option in this job turns on extended syntax, and allows for @@ -7078,6 +7554,7 @@ pre-defined filters for your convenience: The purpose of this filter is to get rid of particularly annoying JavaScript abuse. To that end, it + @@ -7101,7 +7578,6 @@ pre-defined filters for your convenience: - Use with caution. This is an aggressive filter, and can break sites that rely heavily on JavaScript. @@ -7241,9 +7717,9 @@ pre-defined filters for your convenience: banners-by-link - This is an experimental filter that attempts to kill any banners if - their URLs seem to point to known or suspected click trackers. It is currently - not of much value and is not recommended for use by default. + This filter attempts to kill any banners if their URLs seem to point + to known or suspected click trackers. It is currently not of much value + and is not recommended for use by default. @@ -7325,7 +7801,7 @@ pre-defined filters for your convenience: sometimes appear on some pages, or user agents that don't correct for this on the fly. @@ -7560,7 +8036,7 @@ pre-defined filters for your convenience: &my-app; will temporary store the content to filter in the temporary-directory. - + EXTERNAL-FILTER: cat Pointless example filter that doesn't actually modify the content /bin/cat @@ -7586,7 +8062,6 @@ EXTERNAL-FILTER: rotate-image Rotate an image by 180 degree. Test filter with li EXTERNAL-FILTER: citation-needed Adds a "[citation needed]" tag to an image. The coordinates may need adjustment. /usr/local/bin/convert - -pointsize 16 -fill white -annotate +17+418 "[citation needed]" - - @@ -7659,14 +8134,12 @@ EXTERNAL-FILTER: citation-needed Adds a "[citation needed]" tag to an image. The is in an alpha or beta development stage: - <!-- @if-unstable-start --> ... beta warning HTML code goes here ... <!-- if-unstable-end@ --> - If the "unstable" symbol is set, everything in between and including @@ -7674,9 +8147,7 @@ EXTERNAL-FILTER: citation-needed Adds a "[citation needed]" tag to an image. The will disappear, leaving nothing but an empty comment: - <!-- --> - There's also an if-then-else construct and an #include @@ -7721,17 +8192,63 @@ Requests Privoxy is free software; you can - redistribute it and/or modify it under the terms of the - GNU General Public License, version 2, - as published by the Free Software Foundation and included in - the next section. + redistribute and/or modify its source code under the terms + of the GNU General Public License + as published by the Free Software Foundation, either version 2 + of the license, or (at your option) any later version. + + + + The same is true for Privoxy binaries + unless they are linked with a + mbed TLS version + that is licensed under the Apache 2.0 license in which + case you can redistribute and/or modify the Privoxy + binaries under the terms of the GNU General Public License + as published by the Free Software Foundation, either version 3 + of the license, or (at your option) any later version. + + + + Both licenses are included in the next section. License + +GNU General Public License version 2 + + + +GNU General Public License version 3 + + + +Third-party licenses and copyrights + + Privoxy depends on a couple of third-party libraries which have seperate licenses. + Please refer to the third-party websites for up-to-date license and copyright + information. + + + Privoxy depends on pcre. + + + When compiled with FEATURE_BROTLI (optional), Privoxy depends on + brotli. + - + When compiled with FEATURE_HTTPS_INSPECTION (optional), + Privoxy depends on a TLS library. The supported libraries are + LibreSSL, + mbed TLS 2.28.x and + OpenSSL. + + When compiled with FEATURE_ZLIB (optional), + Privoxy depends on zlib. + + @@ -7820,35 +8337,35 @@ Requests and then some examples: - + . - Matches any single character, e.g. a, A, 4, :, or @. - + - + ? - The preceding character or expression is matched ZERO or ONE times. Either/or. - + - + + - The preceding character or expression is matched ONE or MORE times. - + - + * - The preceding character or expression is matched ZERO or MORE times. - + - + \ - The escape character denotes that the following character should be taken literally. This is used where one of the @@ -7857,25 +8374,25 @@ Requests sure the period is recognized only as a period (and not expanded to its meta-character meaning of any single character). - + - + [ ] - Characters enclosed in brackets will be matched if any of the enclosed characters are encountered. For instance, [0-9] matches any numeric digit (zero through nine). As an example, we can combine this with + to match any digit one of more times: [0-9]+. - + - + ( ) - parentheses are used to group a sub-expression, or multiple sub-expressions. - + - + | - The bar character works like an or conditional statement. A match is successful if the @@ -7884,7 +8401,7 @@ Requests and would match either this example or that example, and nothing else. - + These are just some of the ones you are likely to use when matching URLs with @@ -8012,7 +8529,6 @@ Requests rules and other configuration options, and even turn Privoxy's filtering off, all with a web browser. - @@ -8023,7 +8539,6 @@ Requests necessary either. - @@ -8044,23 +8559,23 @@ Requests - Show information about the current configuration, including viewing and - editing of actions files: + View and toggle client tags:
- http://config.privoxy.org/show-status + http://config.privoxy.org/client-tags
- Show the source code version numbers: + Show information about the current configuration, including viewing and + editing of actions files: -
+
- http://config.privoxy.org/show-version + http://config.privoxy.org/show-status
@@ -8115,7 +8630,6 @@ Requests - @@ -8129,7 +8643,6 @@ Requests page is requested by your browser: - @@ -8238,7 +8751,7 @@ Requests - + NOTE: This is somewhat of a simplistic overview of what happens with each URL request. For the sake of brevity and simplicity, we have focused on @@ -8311,13 +8824,12 @@ Requests configuration may vary): - - Matches for http://www.google.com: +Matches for http://www.google.com: - In file: default.action [ View ] [ Edit ] +In file: default.action [ View ] [ Edit ] - {+change-x-forwarded-for{block} +{+change-x-forwarded-for{block} +deanimate-gifs {last} +fast-redirects {check-decoded-url} +filter {refresh-tags} @@ -8329,19 +8841,18 @@ Requests +hide-from-header {block} +hide-referrer {forge} +session-cookies-only - +set-image-blocker {pattern} + +set-image-blocker {pattern} } / - { -session-cookies-only } - .google.com +{ -session-cookies-only } +.google.com - { -fast-redirects } - .google.com +{ -fast-redirects } +.google.com In file: user.action [ View ] [ Edit ] (no matches in this file) - This is telling us how we have defined our @@ -8397,15 +8908,127 @@ In file: user.action [ View ] [ Edit ]Privoxy is applying all its actions to google.com: + + + +Final results: + +-add-header +-block ++change-x-forwarded-for{block} +-client-header-filter{hide-tor-exit-notation} +-content-type-overwrite +-crunch-client-header +-crunch-if-none-match +-crunch-incoming-cookies +-crunch-outgoing-cookies +-crunch-server-header ++deanimate-gifs {last} +-downgrade-http-version +-fast-redirects +-filter {js-events} +-filter {content-cookies} +-filter {all-popups} +-filter {banners-by-link} +-filter {tiny-textforms} +-filter {frameset-borders} +-filter {demoronizer} +-filter {shockwave-flash} +-filter {quicktime-kioskmode} +-filter {fun} +-filter {crude-parental} +-filter {site-specifics} +-filter {js-annoyances} +-filter {html-annoyances} ++filter {refresh-tags} +-filter {unsolicited-popups} ++filter {img-reorder} ++filter {banners-by-size} ++filter {webbugs} ++filter {jumping-windows} ++filter {ie-exploits} +-filter {google} +-filter {yahoo} +-filter {msn} +-filter {blogspot} +-filter {no-ping} +-force-text-mode +-handle-as-empty-document +-handle-as-image +-hide-accept-language +-hide-content-disposition ++hide-from-header {block} +-hide-if-modified-since ++hide-referrer {forge} +-hide-user-agent +-limit-connect +-overwrite-last-modified +-prevent-compression +-redirect +-server-header-filter{xml-to-html} +-server-header-filter{html-to-xml} +-session-cookies-only ++set-image-blocker {pattern} + + + + Notice the only difference here to the previous listing, is to + fast-redirects and session-cookies-only, + which are activated specifically for this site in our configuration, + and thus show in the Final Results. + + + + Now another example, ad.doubleclick.net: + + + +{ +block{Domains starts with "ad"} } +ad*. + +{ +block{Domain contains "ad"} } +.ad. +{ +block{Doubleclick banner server} +handle-as-image } +.[a-vx-z]*.doubleclick.net + + + + We'll just show the interesting part here - the explicit matches. It is + matched three different times. Two +block{} sections, + and a +block{} +handle-as-image, + which is the expanded form of one of our aliases that had been defined as: + +block-as-image. (Aliases are defined in + the first section of the actions file and typically used to combine more + than one action.) + + + + Any one of these would have done the trick and blocked this as an unwanted + image. This is unnecessarily redundant since the last case effectively + would also cover the first. No point in taking chances with these guys + though ;-) Note that if you want an ad or obnoxious + URL to be invisible, it should be defined as ad.doubleclick.net + is done here -- as both a +block{} + and an + +handle-as-image. + The custom alias +block-as-image just + simplifies the process and make it more readable. + One last example. Let's try http://www.example.net/adsl/HOWTO/. + This one is giving us problems. We are getting a blank page. Hmmm ... + + +Matches for http://www.example.net/adsl/HOWTO/: - Final results: +In file: default.action [ View ] [ Edit ] - -add-header +{-add-header -block +change-x-forwarded-for{block} -client-header-filter{hide-tor-exit-notation} @@ -8415,9 +9038,9 @@ In file: user.action [ View ] [ Edit ][ View ] [ Edit ] - - - - Notice the only difference here to the previous listing, is to - fast-redirects and session-cookies-only, - which are activated specifically for this site in our configuration, - and thus show in the Final Results. - - - - Now another example, ad.doubleclick.net: - - - - - - { +block{Domains starts with "ad"} } - ad*. - - { +block{Domain contains "ad"} } - .ad. - - { +block{Doubleclick banner server} +handle-as-image } - .[a-vx-z]*.doubleclick.net - - - - - We'll just show the interesting part here - the explicit matches. It is - matched three different times. Two +block{} sections, - and a +block{} +handle-as-image, - which is the expanded form of one of our aliases that had been defined as: - +block-as-image. (Aliases are defined in - the first section of the actions file and typically used to combine more - than one action.) - - - - Any one of these would have done the trick and blocked this as an unwanted - image. This is unnecessarily redundant since the last case effectively - would also cover the first. No point in taking chances with these guys - though ;-) Note that if you want an ad or obnoxious - URL to be invisible, it should be defined as ad.doubleclick.net - is done here -- as both a +block{} - and an - +handle-as-image. - The custom alias +block-as-image just - simplifies the process and make it more readable. - - - - One last example. Let's try http://www.example.net/adsl/HOWTO/. - This one is giving us problems. We are getting a blank page. Hmmm ... - - - - + +session-cookies-only + +set-image-blocker{blank} } +/ - Matches for http://www.example.net/adsl/HOWTO/: - - In file: default.action [ View ] [ Edit ] - - {-add-header - -block - +change-x-forwarded-for{block} - -client-header-filter{hide-tor-exit-notation} - -content-type-overwrite - -crunch-client-header - -crunch-if-none-match - -crunch-incoming-cookies - -crunch-outgoing-cookies - -crunch-server-header - +deanimate-gifs - -downgrade-http-version - +fast-redirects {check-decoded-url} - -filter {js-events} - -filter {content-cookies} - -filter {all-popups} - -filter {banners-by-link} - -filter {tiny-textforms} - -filter {frameset-borders} - -filter {demoronizer} - -filter {shockwave-flash} - -filter {quicktime-kioskmode} - -filter {fun} - -filter {crude-parental} - -filter {site-specifics} - -filter {js-annoyances} - -filter {html-annoyances} - +filter {refresh-tags} - -filter {unsolicited-popups} - +filter {img-reorder} - +filter {banners-by-size} - +filter {webbugs} - +filter {jumping-windows} - +filter {ie-exploits} - -filter {google} - -filter {yahoo} - -filter {msn} - -filter {blogspot} - -filter {no-ping} - -force-text-mode - -handle-as-empty-document - -handle-as-image - -hide-accept-language - -hide-content-disposition - +hide-from-header{block} - +hide-referer{forge} - -hide-user-agent - -overwrite-last-modified - +prevent-compression - -redirect - -server-header-filter{xml-to-html} - -server-header-filter{html-to-xml} - +session-cookies-only - +set-image-blocker{blank} } - / - - { +block{Path contains "ads".} +handle-as-image } - /ads +{ +block{Path contains "ads".} +handle-as-image } +/ads - Ooops, the /adsl/ is matching /ads in our @@ -8600,13 +9102,10 @@ In file: user.action [ View ] [ Edit ] - - - { -block } - /adsl +{ -block } +/adsl - Now the page displays ;-) @@ -8620,13 +9119,10 @@ In file: user.action [ View ] [ Edit ] - - - { +block{Path starts with "ads".} +handle-as-image } - /ads +{ +block{Path starts with "ads".} +handle-as-image } +/ads - That actually was very helpful and pointed us quickly to where the problem @@ -8640,35 +9136,28 @@ In file: user.action [ View ] [ Edit ]+filter: - - - { shop } - .quietpc.com - .worldpay.com # for quietpc.com - .jungle.com - .scan.co.uk - .forbes.com +{ shop } +.quietpc.com +.worldpay.com # for quietpc.com +.jungle.com +.scan.co.uk +.forbes.com - { shop } is an alias that expands to { -filter -session-cookies-only }. Or you could do your own exception to negate filtering: - - - - { -filter } - # Disable ALL filter actions for sites in this section - .forbes.com - developer.ibm.com - localhost +{ -filter } +# Disable ALL filter actions for sites in this section +.forbes.com +developer.ibm.com +localhost - This would turn off all filtering for these sites. This is best @@ -8691,14 +9180,13 @@ In file: user.action [ View ] [ Edit ] - - - { fragile } - # Handle with care: easy to break - mail.google. - mybank.example.com - + +{ fragile } +# Handle with care: easy to break +mail.google. +mybank.example.com +