X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fuser-manual.sgml;h=112f8f184ee8c9a7413e4d464d2b813752daaecd;hp=01601cdc74c405a9b6d3c2af141d3e177f6910a7;hb=d4679114d0e9fec9f110caeb3ecd300928994323;hpb=451adf5e77554240efa778fc2e52e5d5b52c2059 diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml index 01601cdc..112f8f18 100644 --- a/doc/source/user-manual.sgml +++ b/doc/source/user-manual.sgml @@ -13,7 +13,7 @@ - + @@ -30,13 +30,11 @@ Privoxy"> ]> - Copyright &my-copy; 2001-2017 by + Copyright &my-copy; 2001-2020 by Privoxy Developers -$Id: user-manual.sgml,v 2.221 2017/05/20 09:27:54 fabiankeil Exp $ - + 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 privoxy/windows. + Then edit the windows/GNUmakefile to set the location of the NSIS executable - eg: + + +# Path to NSIS +MAKENSIS = ./nsis/makensis.exe + + + + + 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 + --disable-dynamic-pcre + + + + 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 --disable-dynamic-pcre + $ make # build Privoxy + + + + See the Developer's Manual + for building a Windows release package. + + + + + + Keeping your Installation Up-to-Date @@ -410,7 +531,6 @@ How to install the binary packages depends on your operating system: versions of Privoxy: - @@ -495,11 +615,9 @@ 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. - Or if you use a number of filters, or filter many sites, you may just want to turn off compression for all sites in @@ -527,14 +645,13 @@ How to install the binary packages depends on your operating system: --> - Quickstart to Using Privoxy - + @@ -634,7 +751,6 @@ How to install the binary packages depends on your operating system: - @@ -711,7 +827,6 @@ How to install the binary packages depends on your operating system: set-image-blocker: - @@ -786,7 +901,6 @@ How to install the binary packages depends on your operating system: - Advanced users will eventually want to explore &my-app; @@ -832,7 +946,6 @@ How to install the binary packages depends on your operating system: A quick and simple step by step example: - @@ -856,7 +969,6 @@ How to install the binary packages depends on your operating system: -
Actions Files in Use @@ -867,7 +979,6 @@ How to install the binary packages depends on your operating system:
- @@ -902,7 +1013,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 @@ -950,7 +1060,6 @@ How to install the binary packages depends on your operating system: -
Proxy Configuration Showing Mozilla/Netscape HTTP and HTTPS (SSL) Settings @@ -962,7 +1071,6 @@ How to install the binary packages depends on your operating system:
- @@ -971,7 +1079,6 @@ How to install the binary packages depends on your operating system: Tools -> Options -> Advanced -> Network ->Connection -> Settings - @@ -980,7 +1087,6 @@ How to install the binary packages depends on your operating system: Edit -> Preferences -> General -> Connection Settings -> Manual Proxy Configuration - @@ -994,7 +1100,6 @@ How to install the binary packages depends on your operating system: Edit -> Preferences -> Advanced -> Proxies -> HTTP Proxy - @@ -1014,7 +1119,6 @@ How to install the binary packages depends on your operating system: -
Proxy Configuration Showing Internet Explorer HTTP and HTTPS (Secure) Settings @@ -1026,7 +1130,6 @@ How to install the binary packages depends on your operating system:
- @@ -1054,11 +1157,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 - @@ -1077,11 +1178,9 @@ How to install the binary packages depends on your operating system: To start Privoxy manually, run: - # service privoxy onestart - @@ -1107,11 +1206,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 - Note that if you installed Privoxy through a package manager, the package will probably contain a platform-specific @@ -1258,7 +1355,6 @@ must find a better place for this paragraph command-line options: - @@ -1374,7 +1470,6 @@ must find a better place for this paragraph - On MS Windows only there are two additional @@ -1411,20 +1506,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 clients address         ▪  View the request headers. @@ -1482,9 +1575,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 and OS/2 + these are all in the same directory as the Privoxy executable. @@ -1496,13 +1589,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 OS/2, and config.txt on Windows. This is a required file. @@ -1554,7 +1646,6 @@ for details. - The syntax of the configuration and filter files may change between different @@ -1640,7 +1731,6 @@ for details. are three action files included with Privoxy with differing purposes: - @@ -1703,7 +1793,6 @@ for details. The default profiles, and their associated actions, as pre-defined in default.action are: - Default Configurations @@ -1821,11 +1910,9 @@ for details.
- - The list of actions files to be used are defined in the main configuration @@ -1949,14 +2036,12 @@ 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/ - You can trace this process for URL patterns and any given URL by visiting - # If the admin defined the client-specific-tag circumvent-blocks, # and the request comes from a client that previously requested @@ -2446,7 +2530,6 @@ CLIENT-TAG:^circumvent-blocks$ # the previous one. {+block{Nobody is supposed to request this.}} example.org/blocked-example-page - @@ -2468,7 +2551,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. - @@ -2484,18 +2566,15 @@ 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 - Example: +handle-as-image @@ -2507,12 +2586,10 @@ 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 - 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. @@ -2531,13 +2608,11 @@ 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 - Examples: +add-header{X-Fun-Header: Some text} and +filter{html-annoyances} @@ -2545,7 +2620,6 @@ example.org/blocked-example-page - If nothing is specified in any actions file, no actions are @@ -2640,7 +2714,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. # @@ -2651,7 +2724,6 @@ example.org/blocked-example-page # header may make user-tracking easier. {+add-header{DNT: 1}} / - @@ -2740,7 +2812,6 @@ example.org/blocked-example-page Example usage (section): - {+block{No nasty stuff for you.}} # Block and replace with "blocked" page .nasty-stuff.example.com @@ -2753,7 +2824,6 @@ example.org/blocked-example-page {+block{Layered ads.} +handle-as-empty-document} # Block and then ignore adserver.example.net/.*\.js$ - @@ -2824,9 +2894,7 @@ example.org/blocked-example-page Example usage: - +change-x-forwarded-for{block} - @@ -2904,13 +2972,11 @@ example.org/blocked-example-page Example usage (section): - # Hide Tor exit notation in Host and Referer Headers {+client-header-filter{hide-tor-exit-notation}} / - - + @@ -2979,7 +3045,6 @@ example.org/blocked-example-page Example usage (section): - # Tag every request with the User-Agent header {+client-header-tagger{user-agent}} @@ -3003,9 +3068,8 @@ 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}} @@ -3019,9 +3083,8 @@ TAG:^User-Agent: MPlayer/ # parts of multimedia files. {-filter -deanimate-gifs} TAG:^RANGE-REQUEST$ - - - + + # Tag all requests with the client IP address # @@ -3034,8 +3097,7 @@ TAG:^RANGE-REQUEST$ # 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$ - - + @@ -3135,7 +3197,6 @@ TAG:^IP-ADDRESS: 10\.0\.0\.1$ Example usage (sections): - # Check if www.example.net/ really uses valid XHTML { +content-type-overwrite{application/xml} } www.example.net/ @@ -3145,7 +3206,6 @@ www.example.net/ www.example.net/.*\.css$ www.example.net/.*style - @@ -3224,12 +3284,10 @@ new action Example usage (section): - # Block the non-existent "Privacy-Violation:" client header { +crunch-client-header{Privacy-Violation:} } / - - + @@ -3306,14 +3364,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} -/ - +/ + @@ -3381,9 +3438,7 @@ new action Example usage: - +crunch-incoming-cookies - @@ -3460,11 +3515,10 @@ new action Example usage (section): - # Crunch server headers that try to prevent caching { +crunch-server-header{no-cache} } -/ - +/ + @@ -3531,9 +3585,7 @@ new action Example usage: - +crunch-outgoing-cookies - @@ -3601,14 +3653,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 @@ -3673,16 +3793,15 @@ new action Example usage (section): - {+downgrade-http-version} problem-host.example.com - + external-filter @@ -3763,9 +3882,7 @@ problem-host.example.com Example usage: - +external-filter{fancy-filter} - @@ -3870,7 +3987,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. @@ -3880,14 +3997,12 @@ problem-host.example.com Example usage: - { +fast-redirects{simple-check} } one.example.com { +fast-redirects{check-decoded-url} } another.example.com/testing - @@ -4029,112 +4144,112 @@ 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{no-ping} # Removes non-standard ping attributes in <a> and <area> tags. - +filter{google} # CSS-based block for Google text ads. Also removes a width limitation and the toolbar advertisement. + +filter{google} # CSS-based block for Google text ads. Also removes a width limitation and the toolbar advertisement. - +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{blogspot} # Cleans up some Blogspot blogs. Read the fine print before using this. @@ -4204,11 +4319,9 @@ new action Example usage: - +force-text-mode - - + @@ -4337,7 +4450,6 @@ new action Example usage: - # Use an ssh tunnel for requests previously tagged as # User-Agent: fetch libfetch/2.0 and make sure @@ -4354,8 +4466,7 @@ new action -overwrite-last-modified \ } TAG:^User-Agent: fetch libfetch/2\.0$ - - + @@ -4427,13 +4538,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$ - - + @@ -4508,7 +4617,6 @@ example.org/.*\.js$ Example usage (sections): - # Generic image extensions: # {+handle-as-image} @@ -4520,7 +4628,6 @@ example.org/.*\.js$ {+block{Nasty banners.} +handle-as-image} nasty-banner-server.example.com/junk.cgi\?output=trash - @@ -4600,13 +4707,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} \ } -/ - +/ + @@ -4690,13 +4796,11 @@ new action Example usage: - # Disarm the download link in Sourceforge's patch tracker { -filter \ +content-type-overwrite{text/plain}\ +hide-content-disposition{block} } .sourceforge.net/tracker/download\.php - @@ -4779,13 +4883,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} / - @@ -4854,10 +4956,9 @@ new action Example usage: - - +hide-from-header{block} or + +hide-from-header{block} + or +hide-from-header{spam-me-senseless@sittingduck.example.com} - @@ -4958,10 +5059,9 @@ new action Example usage: - - +hide-referrer{forge} or + +hide-referrer{forge} + or +hide-referrer{http://www.yahoo.com/} - @@ -5040,9 +5140,149 @@ new action Example usage: - +hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)} + + + + + + + + +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 and send it + to the client which has to accept it. + + + Before this works the directives in the + TLS 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: + + + When the + +https-inspection + action is used &my-app; by default verifies that the remote site uses a valid + certificate. + + + If the certificate is invalid the connection is aborted. + + + This action disabled the certificate check allowing requests to sites + with invalid certificates. + + + + + Example usage: + + + {+ignore-certificate-errors} + www.example.org + @@ -5118,13 +5358,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 - @@ -5209,10 +5447,7 @@ new action Example usages: - - +limit-cookie-lifetime{60} - - + +limit-cookie-lifetime{60} @@ -5298,7 +5533,6 @@ new action Example usage (sections): - # Selectively turn off compression, and enable a filter # @@ -5317,7 +5551,6 @@ new action # { -prevent-compression } .compusa.com/ - @@ -5409,13 +5642,11 @@ new action Example usage: - # Let the browser revalidate without being tracked across sessions { +hide-if-modified-since{-60} \ +overwrite-last-modified{randomize} \ +crunch-if-none-match} / - @@ -5506,7 +5737,6 @@ new action Example usages: - # Replace example.com's style sheet with another one { +redirect{http://localhost/css-replacements/example.com.css} } example.com/stylesheet\.css @@ -5547,7 +5777,6 @@ i[0-9][0-9][0-9][0-9]*/ # to the local version delivered by Privoxy {+redirect{s@^http://www@http://config@}} www.privoxy.org/user-manual/ - @@ -5621,15 +5850,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 - - + @@ -5706,7 +5933,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}} @@ -5719,8 +5945,7 @@ example.org/instance-that-is-delivered-as-xml-but-is-not # silly example. {+external-filter{rotate-image} +force-text-mode} TAG:^image/ - - + @@ -5813,9 +6038,7 @@ TAG:^image/ Example usage: - +session-cookies-only - @@ -5915,21 +6138,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} - @@ -5996,7 +6213,6 @@ TAG:^image/ Now let's define some aliases... - # Useful custom aliases we can use later. # @@ -6024,7 +6240,6 @@ TAG:^image/ # c0 = +crunch-all-cookies c1 = -crunch-all-cookies - ...and put them to use. These sections would appear in the lower part of an @@ -6032,7 +6247,6 @@ TAG:^image/ up for the / pattern): - # These sites are either very complex or very keen on # user data and require minimal interference to work: @@ -6056,7 +6270,6 @@ TAG:^image/ {-filter{all-popups} -filter{unsolicited-popups}} .dabs.com .overclockers.co.uk - Aliases like shop and fragile are typically used for @@ -6107,7 +6320,6 @@ hal stop here multiple lines with line continuation. - { \ +change-x-forwarded-for{block} \ @@ -6115,8 +6327,7 @@ hal stop here +set-image-blocker{pattern} \ } / # Match all URLs - - + The default behavior is now set. @@ -6143,14 +6354,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 @@ -6158,7 +6367,6 @@ for-privoxy-version=3.0.11 that also explains why and how aliases are used: - ########################################################################## # Aliases @@ -6178,7 +6386,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 @@ -6189,7 +6396,6 @@ for-privoxy-version=3.0.11 of actions explicitly: - ########################################################################## # Exceptions for sites that'll break under the default action set: @@ -6201,7 +6407,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 @@ -6209,7 +6414,6 @@ mail.google.com carts or item details. Again, we'll use a pre-defined alias: - # Shopping sites: # @@ -6218,7 +6422,6 @@ mail.google.com .worldpay.com # for quietpc.com .jungle.com .scan.co.uk - The fast-redirects @@ -6226,7 +6429,6 @@ mail.google.com breaks some sites. So disable it for popular sites where we know it misbehaves: - { -fast-redirects } login.yahoo.com @@ -6235,7 +6437,6 @@ edit.*.yahoo.com .altavista.com/.*(like|url|link):http .altavista.com/trans.*urltext=http .nytimes.com - It is important that Privoxy knows which @@ -6250,7 +6451,6 @@ edit.*.yahoo.com good start: - ########################################################################## # Images: @@ -6261,7 +6461,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 @@ -6278,7 +6477,6 @@ edit.*.yahoo.com action before, it still applies and needn't be repeated: - # Known ad generators: # @@ -6290,7 +6488,6 @@ ar.atwola.com .a[0-9].yimg.com/(?:(?!/i/).)*$ bs*.gsanet.com .qkimg.net - One of the most important jobs of Privoxy @@ -6310,7 +6507,6 @@ bs*.gsanet.com to keep the example short: - ########################################################################## # Block these fine banners: @@ -6329,7 +6525,6 @@ count*. # Site-specific patterns (abbreviated): # .hitbox.com - It's quite remarkable how many advertisers actually call their banner @@ -6359,7 +6554,6 @@ count*. with no block action applying. - ########################################################################## # Save some innocent victims of the above generic block patterns: @@ -6383,7 +6577,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, @@ -6393,7 +6586,6 @@ www.ugu.com/sui/ugu/adv disables all filters in one fell swoop! - # Don't filter code! # @@ -6403,7 +6595,6 @@ bugzilla. developer. wiki. .sourceforge.net - The actual default.action is of course much more @@ -6437,10 +6628,8 @@ wiki. - # My user.action file. <fred@example.com> - As aliases are local to the actions @@ -6448,7 +6637,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: @@ -6479,8 +6667,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 @@ -6490,30 +6676,25 @@ handle-as-text = -filter +-filter } .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: @@ -6525,7 +6706,6 @@ handle-as-text = -filter +-block action. Say you've @@ -6538,12 +6718,10 @@ stupid-server.example.com/ in default.action anyway: - { +block{Nasty ads.} } www.example.com/nasty-ads/sponsor\.gif another.example.net/more/junk/here/ - The URLs of dynamically generated banners, especially from large banner @@ -6557,14 +6735,12 @@ stupid-server.example.com/ browser. Use cautiously. - { +block-as-image } .doubleclick.net .fastclick.net /Realmedia/ads/ ar.atwola.com/ - Now you noticed that the default configuration breaks Forbes Magazine, @@ -6578,13 +6754,11 @@ stupid-server.example.com/ that misbehave, and add those to our personalized list of troublemakers: - { fragile } .forbes.com webmail.example.com .mybank.com - You like the fun text replacements in default.filter, @@ -6593,11 +6767,9 @@ stupid-server.example.com/ update-safe config, once and for all: - { +filter{fun} } / # For ALL sites! - Note that the above is not really a good idea: There are exceptions @@ -6614,13 +6786,11 @@ stupid-server.example.com/ sites that you feel provide value to you: - { allow-ads } .sourceforge.net .slashdot.org .osdn.net - Note that allow-ads has been aliased to @@ -6636,11 +6806,9 @@ stupid-server.example.com/ it should I choose to. - { handle-as-text } /.*\.sh$ - user.action is generally the best place to define @@ -6652,11 +6820,9 @@ stupid-server.example.com/ paths and patterns: - { +set-image-blocker{blank} } / # ALL sites - @@ -6768,9 +6934,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 @@ -6836,9 +7000,7 @@ stupid-server.example.com/ needed: - s/foo/bar/ - But wait! Didn't the comment say that all occurrences @@ -6847,17 +7009,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 @@ -6866,14 +7025,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 @@ -6955,12 +7112,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, @@ -6983,12 +7138,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 @@ -7009,14 +7162,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) @@ -7026,7 +7177,6 @@ s/microsoft(?!\.com)/MicroSuck/ig still replacing the word everywhere else. - # Buzzword Bingo (example for extended regex syntax) # @@ -7042,7 +7192,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 @@ -7077,6 +7226,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 + @@ -7100,7 +7250,6 @@ pre-defined filters for your convenience: - Use with caution. This is an aggressive filter, and can break sites that rely heavily on JavaScript. @@ -7324,7 +7473,7 @@ pre-defined filters for your convenience: sometimes appear on some pages, or user agents that don't correct for this on the fly. @@ -7559,7 +7708,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 @@ -7585,7 +7734,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]" - - @@ -7658,14 +7806,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 @@ -7673,9 +7819,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 @@ -7728,9 +7872,8 @@ Requests License - + - @@ -7819,35 +7962,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 @@ -7856,25 +7999,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 @@ -7883,7 +8026,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 @@ -8011,7 +8154,6 @@ Requests rules and other configuration options, and even turn Privoxy's filtering off, all with a web browser. - @@ -8022,7 +8164,6 @@ Requests necessary either. - @@ -8043,23 +8184,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
@@ -8114,7 +8255,6 @@ Requests - @@ -8128,7 +8268,6 @@ Requests page is requested by your browser: - @@ -8237,7 +8376,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 @@ -8310,7 +8449,6 @@ Requests configuration may vary): - Matches for http://www.google.com: @@ -8340,7 +8478,6 @@ Requests In file: user.action [ View ] [ Edit ] (no matches in this file) - This is telling us how we have defined our @@ -8396,12 +8533,9 @@ In file: user.action [ View ] [ Edit ]Privoxy is applying all its actions to google.com: - - - Final results: -add-header @@ -8459,8 +8593,8 @@ In file: user.action [ View ] [ Edit ] - + +set-image-blocker {pattern} + Notice the only difference here to the previous listing, is to @@ -8473,9 +8607,7 @@ In file: user.action [ View ] [ Edit ]ad.doubleclick.net: - - { +block{Domains starts with "ad"} } ad*. @@ -8485,7 +8617,6 @@ In file: user.action [ View ] [ Edit ] - We'll just show the interesting part here - the explicit matches. It is @@ -8517,9 +8648,7 @@ In file: user.action [ View ] [ Edit ] - - Matches for http://www.example.net/adsl/HOWTO/: In file: default.action [ View ] [ Edit ] @@ -8583,7 +8712,6 @@ In file: user.action [ View ] [ Edit ] - Ooops, the /adsl/ is matching /ads in our @@ -8599,13 +8727,10 @@ In file: user.action [ View ] [ Edit ] - - { -block } /adsl - Now the page displays ;-) @@ -8619,13 +8744,10 @@ In file: user.action [ View ] [ Edit ] - - { +block{Path starts with "ads".} +handle-as-image } /ads - That actually was very helpful and pointed us quickly to where the problem @@ -8639,9 +8761,7 @@ In file: user.action [ View ] [ Edit ]+filter: - - { shop } .quietpc.com .worldpay.com # for quietpc.com @@ -8649,25 +8769,20 @@ In file: user.action [ View ] [ Edit ] - { 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 - This would turn off all filtering for these sites. This is best @@ -8690,14 +8805,12 @@ In file: user.action [ View ] [ Edit ] - - + { fragile } # Handle with care: easy to break mail.google. mybank.example.com -