X-Git-Url: http://www.privoxy.org/gitweb/contact.html?a=blobdiff_plain;f=doc%2Fsource%2Fuser-manual.sgml;h=2d16b835ba722a1718b7f13c5d33524ff097c39b;hb=5573b7911631b77dac62de585f3082c3d3d71a77;hp=344fbd65caf55b1ca86c108e44ecc36ac012a38f;hpb=920990b6c085dce841d9ada825dbb0e0a65b4b56;p=privoxy.git diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml index 344fbd65..2d16b835 100644 --- a/doc/source/user-manual.sgml +++ b/doc/source/user-manual.sgml @@ -14,7 +14,7 @@ - + @@ -35,7 +35,7 @@ Purpose : user manual - Copyright (C) 2001-2020 Privoxy Developers https://www.privoxy.org/ + Copyright (C) 2001-2021 Privoxy Developers https://www.privoxy.org/ See LICENSE. ======================================================================== @@ -54,7 +54,7 @@ - Copyright &my-copy; 2001-2020 by + Copyright &my-copy; 2001-2021 by Privoxy Developers @@ -133,7 +133,7 @@ Hal. In addition to the core features of ad blocking and - cookie management, + cookie management, Privoxy provides many supplemental features, that give the end-user more control, more privacy and more freedom: @@ -398,14 +398,93 @@ How to install the binary packages depends on your operating system: 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: + 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 = ./nsis/makensis.exe +MAKENSIS = /<root-dir>/nsis/makensis.exe + + Get the latest 8.x PCRE code from + PCRE + https://ftp.pcre.org/pub/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.16.x MBED-TLS library source code from + + https://github.com/ARMmbed/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 @@ -439,7 +518,8 @@ MAKENSIS = ./nsis/makensis.exe --enable-zlib --enable-static-linking --disable-pthread - --disable-dynamic-pcre + --with-brotli + --with-mbedtls @@ -659,7 +739,7 @@ MAKENSIS = ./nsis/makensis.exe 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 @@ -672,7 +752,7 @@ MAKENSIS = ./nsis/makensis.exe 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. @@ -1025,7 +1105,7 @@ MAKENSIS = ./nsis/makensis.exe 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 ! @@ -1037,13 +1117,13 @@ MAKENSIS = ./nsis/makensis.exe
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 ]
@@ -1054,7 +1134,7 @@ MAKENSIS = ./nsis/makensis.exe - Tools -> Options -> Advanced -> Network ->Connection -> Settings + Edit -> Preferences -> Network Settings -> Settings @@ -1111,7 +1191,7 @@ MAKENSIS = ./nsis/makensis.exe 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! @@ -1759,7 +1839,7 @@ for details. The default profiles, and their associated actions, as pre-defined in default.action are: - Default Configurations +
Default Configurations @@ -2045,7 +2125,7 @@ for details. The pattern matching syntax is different for the host and path parts of the URL. The host part uses a simple globbing type matching technique, while the path part uses more flexible - Regular + Regular Expressions (POSIX 1003.2). @@ -2207,7 +2287,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 @@ -2275,7 +2355,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. @@ -2932,6 +3012,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 @@ -2955,6 +3050,83 @@ example.org/blocked-example-page + + +client-body-filter + + + + Typical use: + + + Rewrite or remove client request body. + + + + + + Effect: + + + All request bodies to which this action applies are filtered on-the-fly through + the specified regular expression based substitutions. + + + + + + Type: + + + Multi-value. + + + + + Parameter: + + + The name of a client-body filter, as defined in one of the + filter files. + + + + + + Notes: + + + Please refer to the filter file chapter + to learn how to create your own client-body filters. + + + 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): + + +# Remove "test" everywhere in the request body +{+client-body-filter{remove-test}} +/ + + + + + + + @@ -4054,15 +4226,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 @@ -4206,10 +4378,18 @@ problem-host.example.com +filter{no-ping} # Removes non-standard ping attributes in <a> and <area> tags. + + + + +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. @@ -4222,6 +4402,10 @@ problem-host.example.com +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. @@ -5104,7 +5288,7 @@ 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. @@ -5112,7 +5296,7 @@ new action Example usage: - +hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)} + +hide-user-agent{Mozilla/5.0 (X11; ElectroBSD i386; rv:78.0) Gecko/20100101 Firefox/78.0} @@ -5167,7 +5351,7 @@ new action Before this works the directives in the - TLS section + HTTPS inspection section of the config file have to be configured. @@ -5752,6 +5936,10 @@ 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@}} @@ -5932,6 +6120,63 @@ 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$ + + + + + + + + session-cookies-only @@ -6824,13 +7069,15 @@ 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. @@ -6889,7 +7136,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 @@ -6956,7 +7204,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 @@ -7868,11 +8116,37 @@ Requests 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 and + OpenSSL. + + + When compiled with FEATURE_ZLIB (optional), + Privoxy depends on zlib. +