X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fuser-manual.sgml;h=0b085aa72b1e5fa814a6219cb007146194113c34;hp=62cf7c62ed89940cb0de6608d1d71aa171eeb76d;hb=be39c0d173684ff52f080530859cd07edecc574f;hpb=7ecdaff4e6e989eaa70d1ffec88c0e5dfbeb19bb diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml index 62cf7c62..0b085aa7 100644 --- a/doc/source/user-manual.sgml +++ b/doc/source/user-manual.sgml @@ -10,10 +10,11 @@ + - + @@ -34,7 +35,7 @@ Purpose : user manual - Copyright (C) 2001-2018 Privoxy Developers https://www.privoxy.org/ + Copyright (C) 2001-2020 Privoxy Developers https://www.privoxy.org/ See LICENSE. ======================================================================== @@ -53,7 +54,7 @@ - Copyright &my-copy; 2001-2017 by + Copyright &my-copy; 2001-2020 by Privoxy Developers @@ -121,7 +122,8 @@ Hal. Since this is a &p-status; version, not all new features are well tested. This documentation may be slightly out of sync as a result (especially with - CVS sources). And there may be bugs, though hopefully + git sources). + And there may be bugs, though hopefully not many! ]]> @@ -339,30 +341,155 @@ 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 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 @@ -1383,16 +1510,15 @@ for details. - +     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. @@ -1450,9 +1576,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. @@ -1469,7 +1595,7 @@ for details. 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. @@ -2168,6 +2294,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. + + @@ -2943,7 +3075,7 @@ 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 @@ -2958,7 +3090,7 @@ TAG:^User-Agent: MPlayer/ # parts of multimedia files. {-filter -deanimate-gifs} TAG:^RANGE-REQUEST$ - + # Tag all requests with the client IP address @@ -2972,7 +3104,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$ - + @@ -3162,7 +3294,7 @@ new action # Block the non-existent "Privacy-Violation:" client header { +crunch-client-header{Privacy-Violation:} } / - + @@ -3244,7 +3376,8 @@ new action {+hide-if-modified-since{-60} \ +overwrite-last-modified{randomize} \ +crunch-if-none-match} -/ +/ + @@ -3391,7 +3524,8 @@ new action # Crunch server headers that try to prevent caching { +crunch-server-header{no-cache} } -/ +/ + @@ -3532,6 +3666,76 @@ new action + + + +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 @@ -3604,6 +3808,7 @@ problem-host.example.com + external-filter @@ -3789,7 +3994,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. @@ -4123,7 +4328,7 @@ new action +force-text-mode - + @@ -4268,7 +4473,7 @@ new action -overwrite-last-modified \ } TAG:^User-Agent: fetch libfetch/2\.0$ - + @@ -4344,7 +4549,7 @@ new action # but send an empty document instead of the usual HTML message. {+block{Blocked JavaScript} +handle-as-empty-document} example.org/.*\.js$ - + @@ -4513,7 +4718,8 @@ new action {+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} \ } -/ +/ + @@ -4948,6 +5154,151 @@ new action + + +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 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 + + + + + + + limit-connect @@ -5182,9 +5533,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. @@ -5515,7 +5867,7 @@ 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 - + @@ -5986,7 +6338,7 @@ hal stop here +set-image-blocker{pattern} \ } / # Match all URLs - + The default behavior is now set. @@ -7132,7 +7484,7 @@ pre-defined filters for your convenience: sometimes appear on some pages, or user agents that don't correct for this on the fly. @@ -7523,16 +7875,36 @@ 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 + mbed TLS in which + case you can redistribute them and/or modify them 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 + + @@ -7843,23 +8215,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
@@ -8252,7 +8624,8 @@ In file: user.action [ View ] [ Edit ] + +set-image-blocker {pattern} + Notice the only difference here to the previous listing, is to