X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;f=doc%2Fsource%2Fuser-manual.sgml;h=d9ee3ea0eccbd1238759b5a1ad91f95e9cda6095;hb=77d14e843e0f4c0ed64258f106804612a6359d70;hp=68a53abf02e63b8c5f6c344d43feac65cf91de1d;hpb=352696e3ebdddaaf4d370ee35f2bab3ed3b18134;p=privoxy.git
diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml
index 68a53abf..d9ee3ea0 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
@@ -1387,16 +1509,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.
@@ -1454,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.
@@ -1473,7 +1594,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.
@@ -2947,7 +3068,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
@@ -2962,7 +3083,7 @@ TAG:^User-Agent: MPlayer/
# parts of multimedia files.
{-filter -deanimate-gifs}
TAG:^RANGE-REQUEST$
-
+
# Tag all requests with the client IP address
@@ -2976,7 +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$
-
+
@@ -3166,7 +3287,7 @@ new action
# Block the non-existent "Privacy-Violation:" client header
{ +crunch-client-header{Privacy-Violation:} }
/
-
+
@@ -3248,7 +3369,8 @@ new action
{+hide-if-modified-since{-60} \
+overwrite-last-modified{randomize} \
+crunch-if-none-match}
-/
+/
+
@@ -3395,7 +3517,8 @@ new action
# Crunch server headers that try to prevent caching
{ +crunch-server-header{no-cache} }
-/
+/
+
@@ -3536,6 +3659,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
@@ -3608,6 +3801,7 @@ problem-host.example.com
+
external-filter
@@ -3793,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.
@@ -4127,7 +4321,7 @@ new action
+force-text-mode
-
+
@@ -4272,7 +4466,7 @@ new action
-overwrite-last-modified \
}
TAG:^User-Agent: fetch libfetch/2\.0$
-
+
@@ -4348,7 +4542,7 @@ new action
# but send an empty document instead of the usual HTML message.
{+block{Blocked JavaScript} +handle-as-empty-document}
example.org/.*\.js$
-
+
@@ -4517,7 +4711,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} \
}
-/
+/
+
@@ -4952,6 +5147,148 @@ 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 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
+
+
+
+
+
+
+
limit-connect
@@ -5186,9 +5523,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.
@@ -5519,7 +5857,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
-
+
@@ -5990,7 +6328,7 @@ hal stop here
+set-image-blocker{pattern} \
}
/ # Match all URLs
-
+
The default behavior is now set.
@@ -7136,7 +7474,7 @@ pre-defined filters for your convenience:
sometimes appear on some pages, or user agents that don't correct for this on
the fly.
@@ -7847,23 +8185,23 @@ Requests
- Show information about the current configuration, including viewing and
- editing of actions files:
+ View and toggle client tags:
@@ -8256,7 +8594,8 @@ In file: user.action [ View ][ Edit ]
+ +set-image-blocker {pattern}
+
Notice the only difference here to the previous listing, is to