<!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.28">
+<!entity p-version "3.0.29">
<!entity p-status "stable">
<!entity % p-authors-formal "INCLUDE"> <!-- include additional text, etc -->
<!entity % p-not-stable "IGNORE">
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.
========================================================================
<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-2018 by
+ <link linkend="copyright">Copyright</link> &my-copy; 2001-2020 by
<ulink url="https://www.privoxy.org/">Privoxy Developers</ulink>
</subscript>
</pubdate>
<para>
In addition to the core
features of ad blocking and
- <ulink url="http://en.wikipedia.org/wiki/Browser_cookie">cookie</ulink> management,
+ <ulink url="https://en.wikipedia.org/wiki/Browser_cookie">cookie</ulink> management,
<application>Privoxy</application> provides many supplemental
features<![%p-not-stable;[, some of them currently under development]]>,
that give the end-user more control, more privacy and more freedom:
</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>
<listitem>
<para>
Set your browser to use <application>Privoxy</application> as HTTP and
- HTTPS (SSL) <ulink url="http://en.wikipedia.org/wiki/Proxy_server">proxy</ulink>
+ HTTPS (SSL) <ulink url="https://en.wikipedia.org/wiki/Proxy_server">proxy</ulink>
by setting the proxy configuration for address of
<literal>127.0.0.1</literal> and port <literal>8118</literal>.
<emphasis>DO NOT</emphasis> activate proxying for <literal>FTP</literal> or
<para>
Flush your browser's disk and memory caches, to remove any cached ad images.
If using <application>Privoxy</application> to manage
- <ulink url="http://en.wikipedia.org/wiki/Browser_cookie">cookies</ulink>,
+ <ulink url="https://en.wikipedia.org/wiki/Browser_cookie">cookies</ulink>,
you should remove any currently stored cookies too.
</para>
</listitem>
Before launching <application>Privoxy</application> for the first time, you
will want to configure your browser(s) to use
<application>Privoxy</application> as a HTTP and HTTPS (SSL)
- <ulink url="http://en.wikipedia.org/wiki/Proxy_server">proxy</ulink>. The default is
+ <ulink url="https://en.wikipedia.org/wiki/Proxy_server">proxy</ulink>. 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 <emphasis>that must be done
</emphasis>!
<!-- image of Mozilla Proxy configuration -->
<figure pgwide="0" float="0"><title>Proxy Configuration Showing
- Mozilla/Netscape HTTP and HTTPS (SSL) Settings</title>
+ Mozilla Firefox HTTP and HTTPS (SSL) Settings</title>
<mediaobject>
<imageobject>
<imagedata fileref="proxy_setup.jpg" format="jpg">
</imageobject>
<textobject>
- <phrase>[ Screenshot of Mozilla Proxy Configuration ]</phrase>
+ <phrase>[ Screenshot of Mozilla Firefox Proxy Configuration ]</phrase>
</textobject>
</mediaobject>
</figure>
</para>
<literallayout>
- <guibutton>Tools</guibutton> -> <guibutton>Options</guibutton> -> <guibutton>Advanced</guibutton> -> <guibutton>Network</guibutton> -><guibutton>Connection</guibutton> -> <guibutton>Settings</guibutton>
+ <guibutton>Edit</guibutton> -> <guibutton>Preferences</guibutton> -> <guibutton>Network Settings</guibutton> -> <guibutton>Settings</guibutton>
</literallayout>
<para>
<para>
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 <ulink url="http://en.wikipedia.org/wiki/Browser_cookie">cookies</ulink>,
+ any <ulink url="https://en.wikipedia.org/wiki/Browser_cookie">cookies</ulink>,
if you want <application>Privoxy</application> to manage that. You are now
ready to start enjoying the benefits of using
<application>Privoxy</application>!
</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>
▪ <ulink url="http://config.privoxy.org/show-status">View & change the current configuration</ulink>
</member>
<member>
- ▪ <ulink url="http://config.privoxy.org/client-tags">View or toggle the tags that can be set based on the clients address</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>
<title>Configuration Files Overview</title>
<para>
For Unix, *BSD and GNU/Linux, all configuration files are located in
- <filename>/etc/privoxy/</filename> by default. For MS Windows and OS/2
+ <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
<listitem>
<para>
The <link linkend="config">main configuration file</link> is named <filename>config</filename>
- on GNU/Linux, Unix, BSD, and OS/2, and <filename>config.txt</filename>
+ on GNU/Linux, Unix, BSD, and <filename>config.txt</filename>
on Windows. This is a required file.
</para>
</listitem>
The default profiles, and their associated actions, as pre-defined in
<filename>default.action</filename> are:
</para>
- <table frame=all><title>Default Configurations</title>
+ <table frame=all id="default-configurations"><title>Default Configurations</title>
<tgroup cols=4 align=left colsep=1 rowsep=1>
<colspec colname=c1>
<colspec colname=c2>
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
- <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
+ <ulink url="https://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
Expressions</quote></ulink> (POSIX 1003.2).
</para>
<para>
themselves. These work similarly to shell globbing type wild-cards:
<quote>*</quote> represents zero or more arbitrary characters (this is
equivalent to the
- <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
+ <ulink url="https://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
Expression</quote></ulink> based syntax of <quote>.*</quote>),
<quote>?</quote> represents any single character (this is equivalent to the
regular expression syntax of a simple <quote>.</quote>), and you can define
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 ~ -->
<para>
<application>Privoxy</application> uses <quote>modern</quote> POSIX 1003.2
- <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
+ <ulink url="https://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
Expressions</quote></ulink> for matching the path portion (after the slash),
and is thus more flexible.
</para>
</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>
<para>
<quote>Rolling your own</quote>
filters requires a knowledge of
- <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
+ <ulink url="https://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
Expressions</quote></ulink> and
- <ulink url="http://en.wikipedia.org/wiki/Html"><quote>HTML</quote></ulink>.
+ <ulink url="https://en.wikipedia.org/wiki/Html"><quote>HTML</quote></ulink>.
This is very powerful feature, and potentially very intrusive.
Filters should be used with caution, and where an equivalent
<quote>action</quote> is not available.
More information on known user-agent strings can be found at
<ulink url="http://www.user-agents.org/">http://www.user-agents.org/</ulink>
and
- <ulink url="http://en.wikipedia.org/wiki/User_agent">http://en.wikipedia.org/wiki/User_agent</ulink>.
+ <ulink url="https://en.wikipedia.org/wiki/User_agent">http://en.wikipedia.org/wiki/User_agent</ulink>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <screen>+hide-user-agent{Mozilla/5.0 (X11; ElectroBSD i386; rv:78.0) Gecko/20100101 Firefox/78.0}</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#HTTPS-INSPECTION-DIRECTIVES">HTTPS inspection 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>
+ <para>
+ This is an experimental feature.
+ </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>+hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)}</screen>
+ <screen>
+ {+ignore-certificate-errors}
+ www.example.org
+ </screen>
</listitem>
</varlistentry>
</variablelist>
<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>
# 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@}}
<para>
If you are new to
- <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
+ <ulink url="https://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
Expressions</quote></ulink>, you might want to take a look at
the <link linkend="regex">Appendix on regular expressions</link>, and
see the <ulink url="http://perldoc.perl.org/perlre.html">Perl
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 a
+ <ulink url="https://tls.mbed.org/">mbed TLS</ulink> version
+ that is licensed under the Apache 2.0 license in which
+ case you can redistribute and/or modify the <application>Privoxy</application>
+ binaries 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 ~ -->
projects / privoxy.git / blobdiff