<!entity copyright SYSTEM "copyright.sgml">
<!entity license SYSTEM "license.sgml">
<!entity GPLv2 SYSTEM "../../LICENSE">
+<!entity GPLv3 SYSTEM "../../LICENSE.GPLv3">
<!entity p-authors SYSTEM "p-authors.sgml">
<!entity config SYSTEM "p-config.sgml">
<!entity changelog SYSTEM "changelog.sgml">
-<!entity p-version "3.0.27">
+<!entity p-version "3.0.29">
<!entity p-status "UNRELEASED">
<!entity % p-authors-formal "INCLUDE"> <!-- include additional text, etc -->
<!entity % p-not-stable "INCLUDE">
<!entity my-app "<application>Privoxy</application>">
]>
<!--
- File : $Source: /cvsroot/ijbswa/current/doc/source/user-manual.sgml,v $
+ File : doc/source/user-manual.sgml
Purpose : user manual
- This file belongs into
- ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- Copyright (C) 2001-2017 Privoxy Developers https://www.privoxy.org/
+ Copyright (C) 2001-2020 Privoxy Developers https://www.privoxy.org/
See LICENSE.
========================================================================
<subscript>
<!-- Completely the wrong markup, but very little is allowed -->
<!-- in this part of an article. FIXME -->
- <link linkend="copyright">Copyright</link> &my-copy; 2001-2017 by
+ <link linkend="copyright">Copyright</link> &my-copy; 2001-2020 by
<ulink url="https://www.privoxy.org/">Privoxy Developers</ulink>
</subscript>
</pubdate>
-<pubdate>$Id: user-manual.sgml,v 2.221 2017/05/20 09:27:54 fabiankeil Exp $</pubdate>
-
<!--
Note: the following should generate a separate page, and a live link to it,
<para>
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 <emphasis>may be</emphasis> bugs, though hopefully
+ <ulink url="https://www.privoxy.org/gitweb/?p=privoxy.git;a=summary">git sources</ulink>).
+ And there <emphasis>may be</emphasis> bugs, though hopefully
not many!
</para>
]]>
</sect3>
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 id="installation-os2"><title>OS/2</title>
-
-<para>
- First, make sure that no previous installations of
- <application>Junkbuster</application> and / or
- <application>Privoxy</application> are left on your
- system. Check that no <application>Junkbuster</application>
- or <application>Privoxy</application> objects are in
- your startup folder.
-</para>
-
-<para>
- Then, just double-click the WarpIN self-installing archive, which will
- guide you through the installation process. A shadow of the
- <application>Privoxy</application> executable will be placed in your
- startup folder so it will start automatically whenever OS/2 starts.
-</para>
-
-<para>
- The directory you choose to install <application>Privoxy</application>
- into will contain all of the configuration files.
-</para>
-</sect3>
-
<!-- ~~~~~ New section ~~~~~ -->
<sect3 id="installation-mac"><title>Mac OS X</title>
<para>
<sect2 id="installation-source"><title>Building from Source</title>
<para>
- The most convenient way to obtain the <application>Privoxy</application> sources
- is to download the source tarball from our
- <ulink url="https://sourceforge.net/projects/ijbswa/files/Sources/">project download
- page</ulink>.
-</para>
-
-<para>
- 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 <ulink url="https://sourceforge.net/p/ijbswa/code/?source=navbar">the
- CVS repository</ulink>.
-<!--
- deprecated...out of business.
- or simply download <ulink
- url="http://cvs.sourceforge.net/cvstarballs/ijbswa-cvsroot.tar.bz2">the nightly CVS
- tarball.</ulink>
--->
+ The most convenient way to obtain the <application>Privoxy</application> source
+ code is to download the source tarball from our
+ <ulink url="https://sourceforge.net/projects/ijbswa/files/Sources/">
+ project download page</ulink>,
+ or you can get the up-to-the-minute, possibly unstable, development version from
+ <ulink url="https://www.privoxy.org/">https://www.privoxy.org/</ulink>.
</para>
<!-- include buildsource.sgml boilerplate: -->
&buildsource;
<!-- end boilerplate -->
+
+ <sect3 id="WINBUILD-CYGWIN"><title>Windows</title>
+
+ <sect4 id="WINBUILD-SETUP"><title>Setup</title>
+ <para>
+ Install the Cygwin utilities needed to build <application>Privoxy</application>.
+ If you have a 64 bit CPU (which most people do by now), get the
+ Cygwin setup-x86_64.exe program <ulink url="https://cygwin.com/setup-x86_64.exe">here</ulink>
+ (the .sig file is <ulink url="https://cygwin.com/setup-x86_64.exe.sig">here</ulink>).
+ </para>
+ <para>
+ Run the setup program and from View / Category select:
+ </para>
+ <screen>
+ 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
+</screen>
+
+ <para>
+ If you haven't already downloaded the Privoxy source code, get it now:
+ </para>
+ <screen>
+ mkdir <root-dir>
+ cd <root-dir>
+ git clone https://www.privoxy.org/git/privoxy.git
+</screen>
+
+ <para>
+ Get the source code (.zip or .tar.gz) for tidy from
+ <ulink url="https://github.com/htacg/tidy-html5/releases">
+ https://github.com/htacg/tidy-html5/releases</ulink>,
+ unzip into <root-dir> and build the software:
+ </para>
+ <screen>
+ 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
+</screen>
+
+ <para>
+ If you want to be able to make a Windows release package, get the NSIS .zip file from
+ <!-- FIXME: which version(s) are known to work? -->
+ <ulink url="https://sourceforge.net/projects/nsis/files/NSIS%203/">
+ https://sourceforge.net/projects/nsis/files/NSIS%203/</ulink>
+ and extract the NSIS directory to <literal>privoxy/windows</literal>.
+ Then edit the windows/GNUmakefile to set the location of the NSIS executable - eg:
+ </para>
+ <screen>
+# Path to NSIS
+MAKENSIS = ./nsis/makensis.exe
+</screen>
+
+ </sect4>
+
+ <sect4 id="WINBUILD-BUILD"><title>Build</title>
+
+ <para>
+ To build just the Privoxy executable and not the whole installation package, do:
+ </para>
+ <programlisting>
+ cd <root-dir>/privoxy
+ ./windows/MYconfigure && make
+</programlisting>
+
+ <para>
+ Privoxy uses the <ulink url="https://en.wikipedia.org/wiki/GNU_build_system">GNU Autotools</ulink>
+ for building software, so the process is:
+ </para>
+ <programlisting>
+ $ 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
+</programlisting>
+
+ <para>
+ The usual <literal>configure</literal> options for building a native Windows application under cygwin are
+ </para>
+
+ <literallayout class="Monospaced">
+ --host=i686-w64-mingw32
+ --enable-mingw32
+ --enable-zlib
+ --enable-static-linking
+ --disable-pthread
+ --disable-dynamic-pcre
+</literallayout>
+
+ <para>
+ You can set the <literal>CFLAGS</literal> and <literal>LDFLAGS</literal> envars before
+ running <literal>configure</literal> to set compiler and linker flags. For example:
+ </para>
+
+ <programlisting>
+ $ 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
+</programlisting>
+
+ <para>
+ See the <ulink url="../developer-manual/newrelease.html#NEWRELEASE-WINDOWS">Developer's Manual</ulink>
+ for building a Windows release package.
+ </para>
+
+ </sect4>
+ </sect3>
</sect2>
+
+
<!-- ~~~~~ New section ~~~~~ -->
<sect2 id="installation-keepupdated"><title>Keeping your Installation Up-to-Date</title>
</para>
</sect2>
-<sect2 id="start-os2">
-<title>OS/2</title>
-<para>
- During installation, <application>Privoxy</application> is configured to
- start automatically when the system restarts. You can start it manually by
- double-clicking on the <application>Privoxy</application> icon in the
- <application>Privoxy</application> folder.
-</para>
-</sect2>
-
<sect2 id="start-macosx">
<title>Mac OS X</title>
<para>
</para>
<!-- Needs to be put in a table and colorized -->
-<screen>
+<screen><!-- want the background color that goes with screen -->
<msgtext>
<bridgehead renderas="sect2"> Privoxy Menu</bridgehead>
-
<simplelist>
<member>
▪ <ulink url="http://config.privoxy.org/show-status">View & change the current configuration</ulink>
</member>
<member>
- ▪ <ulink url="http://config.privoxy.org/show-version">View the source code version numbers</ulink>
+ ▪ <ulink url="http://config.privoxy.org/client-tags">View or toggle the tags that can be set based on the client's address</ulink>
</member>
<member>
▪ <ulink url="http://config.privoxy.org/show-request">View the request headers.</ulink>
<sect2 id="confoverview">
<title>Configuration Files Overview</title>
<para>
- For Unix, *BSD and Linux, all configuration files are located in
- <filename>/etc/privoxy/</filename> 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
+ <filename>/etc/privoxy/</filename> by default. For MS Windows
+ these are all in the same directory as the
<application>Privoxy</application> executable. <![%p-not-stable;[ The name
and number of configuration files has changed from previous versions, and is
subject to change as development progresses.]]>
<listitem>
<para>
The <link linkend="config">main configuration file</link> is named <filename>config</filename>
- on Linux, Unix, BSD, OS/2, and AmigaOS and <filename>config.txt</filename>
+ on GNU/Linux, Unix, BSD, and <filename>config.txt</filename>
on Windows. This is a required file.
</para>
</listitem>
While flexible, this is not the sophistication of full regular expression based syntax.
</para>
+<para>
+ When compiled with FEATURE_PCRE_HOST_PATTERNS patterns can be prefixed with
+ <quote>PCRE-HOST-PATTERN:</quote> in which case full regular expression
+ (PCRE) can be used for the host pattern as well.
+</para>
+
</sect3>
<!-- ~ End section ~ -->
TAG:^User-Agent: fetch libfetch/
TAG:^User-Agent: Ubuntu APT-HTTP/
TAG:^User-Agent: MPlayer/
- </screen>
+</screen>
<screen>
# Tag all requests with the Range header set
# parts of multimedia files.
{-filter -deanimate-gifs}
TAG:^RANGE-REQUEST$
- </screen>
+</screen>
<screen>
# Tag all requests with the client IP address
# 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$
- </screen>
+</screen>
</listitem>
</varlistentry>
<screen># Block the non-existent "Privacy-Violation:" client header
{ +crunch-client-header{Privacy-Violation:} }
/
- </screen>
+</screen>
</listitem>
</varlistentry>
</variablelist>
{+hide-if-modified-since{-60} \
+overwrite-last-modified{randomize} \
+crunch-if-none-match}
-/ </screen>
+/
+</screen>
</listitem>
</varlistentry>
</variablelist>
<listitem>
<screen># Crunch server headers that try to prevent caching
{ +crunch-server-header{no-cache} }
-/ </screen>
+/
+</screen>
</listitem>
</varlistentry>
</variablelist>
</variablelist>
</sect3>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="delay-response">
+<title>delay-response</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Delay responses to the client to reduce the load</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Delays responses to the client by sending the response in ca. 10 byte chunks.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ <quote>Number of milliseconds</quote>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ <para>
+ This action delays responses to the client and can be combined
+ with <literal><link linkend="block">blocks</link></literal>
+ to slow down the JavaScript code, thus reducing
+ the load on the client.
+ </para>
+ <para>
+ When used without <literal><link linkend="block">blocks</link></literal>
+ the action can also be used to simulate a slow internet connection.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <screen>+delay-response{100}</screen>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="downgrade-http-version">
<title>downgrade-http-version</title>
</variablelist>
</sect3>
+
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="external-filter">
<title>external-filter</title>
looks for the string <quote>http://</quote>, either in plain text
(invalid but often used) or encoded as <quote>http%3a//</quote>.
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
<literal>fast-redirects</literal> is fooled and the request reaches the
redirection server where it probably gets logged.
</para>
<listitem>
<screen>
+force-text-mode
- </screen>
+</screen>
</listitem>
</varlistentry>
</variablelist>
-overwrite-last-modified \
}
TAG:^User-Agent: fetch libfetch/2\.0$
- </screen>
+</screen>
</listitem>
</varlistentry>
</variablelist>
# but send an empty document instead of the usual HTML message.
{+block{Blocked JavaScript} +handle-as-empty-document}
example.org/.*\.js$
- </screen>
+</screen>
</listitem>
</varlistentry>
</variablelist>
{+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} \
}
-/ </screen>
+/
+</screen>
</listitem>
</varlistentry>
</variablelist>
</sect3>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="https-inspection">
+<title>https-inspection</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Filter encrypted requests and responses</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Encrypted requests are decrypted, filtered and forwarded encrypted.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ N/A
+ </para>
+ </listitem>
+ </varlistentry>
+
+<varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ <para>
+ Before this works the directives in the
+ <literal><ulink url="config.html#TLS">TLS section</ulink></literal>
+ of the config file have to be configured.
+ </para>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage (section):</term>
+ <listitem>
+ <screen>{+https-inspection}
+www.example.com</screen>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect3>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="ignore-certificate-errors">
+<title>ignore-certificate-errors</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Filter encrypted requests and responses without verifying the certificate</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Encrypted requests are forwarded to sites without verifying the certificate.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Boolean.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ N/A
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ When the
+ <link linkend="HTTPS-INSPECTION"><quote>+https-inspection</quote></link>
+ action is used &my-app; by default verifies that the remote site uses a valid
+ certificate.
+ </para>
+ <para>
+ If the certificate can't be validated by &my-app; the connection is aborted.
+ </para>
+ <para>
+ This action disables the certificate check so requests to sites
+ with certificates that can't be validated are allowed.
+ </para>
+ <para>
+ Note that enabling this action allows Man-in-the-middle attacks.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <screen>
+ {+ignore-certificate-errors}
+ www.example.org
+ </screen>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="limit-connect">
<title>limit-connect</title>
<para>
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
- <literal>prevent-compression</literal> 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 <literal>prevent-compression</literal> per default, you might
+ want to add exceptions for those sites. See the example for how to do that.
</para>
</listitem>
</varlistentry>
{+server-header-filter{xml-to-html}}
example.org/instance-that-is-delivered-as-xml-but-is-not
- </screen>
+</screen>
</listitem>
</varlistentry>
+<link linkend="SET-IMAGE-BLOCKER">set-image-blocker{pattern}</link> \
}
/ # Match all URLs
- </screen>
+</screen>
<para>
The default behavior is now set.
sometimes appear on some pages, or user agents that don't correct for this on
the fly.
<!--
- My version of Mozilla (ancient) shows litte square boxes for quote
+ My version of Mozilla (ancient) shows little square boxes for quote
characters, and apostrophes on moronized pages. So many pages have this, I
can read them fine now. HB 08/27/06
-->
<para>
<application>Privoxy</application> is free software; you can
- redistribute it and/or modify it under the terms of the
- <citetitle>GNU General Public License</citetitle>, 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 <citetitle>GNU General Public License</citetitle>
+ as published by the Free Software Foundation, either version 2
+ of the license, or (at your option) any later version.
+</para>
+
+<para>
+ The same is true for <application>Privoxy</application> binaries
+ unless they are linked with
+ <ulink url="https://tls.mbed.org/">mbed TLS</ulink> in which
+ case you can redistribute them and/or modify them under the terms
+ of the <citetitle>GNU General Public License</citetitle>
+ as published by the Free Software Foundation, either version 3
+ of the license, or (at your option) any later version.
+</para>
+
+<para>
+ Both licenses are included in the next section.
</para>
<!-- ~~~~~ New section ~~~~~ -->
<sect2 id="license"><title>License</title>
+<sect3 id="gplv2"><title>GNU General Public License version 2</title>
<screen><![ RCDATA [ &GPLv2; ]]></screen>
+</sect3>
+
+<sect3 id="gplv3"><title>GNU General Public License version 3</title>
+ <screen><![ RCDATA [ &GPLv3; ]]></screen>
+</sect3>
</sect2>
<!-- ~ End section ~ -->
<listitem>
<para>
- Show information about the current configuration, including viewing and
- editing of actions files:
+ View and toggle client tags:
</para>
<blockquote>
<para>
- <ulink url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
+ <ulink url="http://config.privoxy.org/client-tags">http://config.privoxy.org/client-tags</ulink>
</para>
</blockquote>
</listitem>
<listitem>
<para>
- Show the source code version numbers:
+ Show information about the current configuration, including viewing and
+ editing of actions files:
</para>
- <blockquote>
+ <blockquote>
<para>
- <ulink url="http://config.privoxy.org/show-version">http://config.privoxy.org/show-version</ulink>
+ <ulink url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
</para>
</blockquote>
</listitem>
-server-header-filter{xml-to-html}
-server-header-filter{html-to-xml}
-session-cookies-only
- +set-image-blocker {pattern} </screen>
+ +set-image-blocker {pattern}
+</screen>
<para>
Notice the only difference here to the previous listing, is to