X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fuser-manual.sgml;h=d1b597ff0fc951268823b1130d14df303290d5fd;hp=68a53abf02e63b8c5f6c344d43feac65cf91de1d;hb=d32e97dce787ca5afc7791215e78a01e0db76f0b;hpb=352696e3ebdddaaf4d370ee35f2bab3ed3b18134 diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml index 68a53abf..d1b597ff 100644 --- a/doc/source/user-manual.sgml +++ b/doc/source/user-manual.sgml @@ -10,14 +10,15 @@ + - - + + - - + + @@ -30,13 +31,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 $ - -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 @@ -343,30 +316,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 @@ -561,7 +659,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 @@ -574,7 +672,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. @@ -927,7 +1025,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 ! @@ -939,13 +1037,13 @@ 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 ]
@@ -956,7 +1054,7 @@ How to install the binary packages depends on your operating system: - Tools -> Options -> Advanced -> Network ->Connection -> Settings + Edit -> Preferences -> Network Settings -> Settings @@ -1013,7 +1111,7 @@ 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! @@ -1095,16 +1193,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 @@ -1387,16 +1475,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 client's address         ▪  View the request headers. @@ -1454,9 +1541,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. @@ -1473,7 +1560,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 config.txt on Windows. This is a required file. @@ -1672,7 +1759,7 @@ for details. The default profiles, and their associated actions, as pre-defined in default.action are: - Default Configurations +
Default Configurations @@ -1958,7 +2045,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). @@ -2120,7 +2207,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 @@ -2172,6 +2259,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. + + @@ -2182,7 +2275,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. @@ -2947,7 +3040,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 +3055,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 +3069,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 +3259,7 @@ new action # Block the non-existent "Privacy-Violation:" client header { +crunch-client-header{Privacy-Violation:} } / - + @@ -3248,7 +3341,8 @@ new action {+hide-if-modified-since{-60} \ +overwrite-last-modified{randomize} \ +crunch-if-none-match} -/ +/ + @@ -3395,7 +3489,8 @@ new action # Crunch server headers that try to prevent caching { +crunch-server-header{no-cache} } -/ +/ + @@ -3536,6 +3631,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 +3773,7 @@ problem-host.example.com + external-filter @@ -3793,7 +3959,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. @@ -3888,9 +4054,9 @@ 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. @@ -4127,7 +4293,7 @@ new action +force-text-mode - + @@ -4272,7 +4438,7 @@ new action -overwrite-last-modified \ } TAG:^User-Agent: fetch libfetch/2\.0$ - + @@ -4348,7 +4514,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 +4683,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} \ } -/ +/ + @@ -4937,7 +5104,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. @@ -4952,6 +5119,154 @@ 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 + 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. + + + This is an experimental feature. + + + + + + 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 @@ -5186,9 +5501,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. @@ -5436,6 +5752,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@}} @@ -5519,7 +5839,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 +6310,7 @@ hal stop here +set-image-blocker{pattern} \ } / # Match all URLs - + The default behavior is now set. @@ -6640,7 +6960,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 @@ -7136,7 +7456,7 @@ pre-defined filters for your convenience: sometimes appear on some pages, or user agents that don't correct for this on the fly. @@ -7527,16 +7847,37 @@ 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 + + @@ -7847,23 +8188,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
@@ -8256,7 +8597,8 @@ In file: user.action [ View ] [ Edit ] + +set-image-blocker {pattern} + Notice the only difference here to the previous listing, is to