X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fuser-manual.sgml;h=4ea6bc0a1784f46cb7e2be4bb4baeb2d5fa28625;hp=62cf7c62ed89940cb0de6608d1d71aa171eeb76d;hb=457ac456ad60717f738a10e9600856ad23df5960;hpb=7ecdaff4e6e989eaa70d1ffec88c0e5dfbeb19bb
diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml
index 62cf7c62..4ea6bc0a 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-2021 Privoxy Developers https://www.privoxy.org/
See LICENSE.
========================================================================
@@ -53,7 +54,7 @@
- Copyright &my-copy; 2001-2017 by
+ Copyright &my-copy; 2001-2021 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!
]]>
@@ -131,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:
@@ -225,31 +227,6 @@ How to install the binary packages depends on your operating system:
-
-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
@@ -339,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
@@ -557,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
@@ -570,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.
@@ -923,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
!
@@ -935,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 ]
@@ -952,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
@@ -1009,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!
@@ -1091,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
@@ -1383,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.
@@ -1450,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.
@@ -1469,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.
@@ -1668,7 +1759,7 @@ for details.
The default profiles, and their associated actions, as pre-defined in
default.action are:
-
Default Configurations
+
Default Configurations
@@ -1954,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).
@@ -2116,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
@@ -2168,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.
+
+
@@ -2178,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.
@@ -2835,6 +2932,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
@@ -2858,6 +2970,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}}
+/
+
+
+
+
+
+
+
@@ -2943,7 +3132,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 +3147,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 +3161,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 +3351,7 @@ new action
# Block the non-existent "Privacy-Violation:" client header
{ +crunch-client-header{Privacy-Violation:} }
/
-
+
@@ -3244,7 +3433,8 @@ new action
{+hide-if-modified-since{-60} \
+overwrite-last-modified{randomize} \
+crunch-if-none-match}
-/
+/
+
@@ -3391,7 +3581,8 @@ new action
# Crunch server headers that try to prevent caching
{ +crunch-server-header{no-cache} }
-/
+/
+
@@ -3532,6 +3723,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 +3865,7 @@ problem-host.example.com
+
external-filter
@@ -3789,7 +4051,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.
@@ -3884,15 +4146,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
@@ -4036,6 +4298,10 @@ 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.
@@ -4052,6 +4318,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.
@@ -4123,7 +4393,7 @@ new action
+force-text-mode
-
+
@@ -4268,7 +4538,7 @@ new action
-overwrite-last-modified \
}
TAG:^User-Agent: fetch libfetch/2\.0$
-
+
@@ -4344,7 +4614,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 +4783,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} \
}
-/
+/
+
@@ -4933,7 +5204,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.
@@ -4941,7 +5212,155 @@ 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}
+
+
+
+
+
+
+
+
+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
+
@@ -5182,9 +5601,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.
@@ -5432,6 +5852,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@}}
@@ -5515,7 +5939,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
-
+
@@ -5612,6 +6036,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
@@ -5986,7 +6467,7 @@ hal stop here
+set-image-blocker{pattern} \
}
/ # Match all URLs
-
+
The default behavior is now set.
@@ -6504,13 +6985,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.
@@ -6569,7 +7052,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
keywordsFILTER:,
- 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
@@ -6636,7 +7120,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
@@ -7132,7 +7616,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 +8007,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
+
+
@@ -7843,23 +8348,23 @@ Requests
- Show information about the current configuration, including viewing and
- editing of actions files:
+ View and toggle client tags:
@@ -8252,7 +8757,8 @@ In file: user.action [ View ][ Edit ]
+ +set-image-blocker {pattern}
+
Notice the only difference here to the previous listing, is to