-<sect4 id="confdir"><title>confdir</title>
-
-<variablelist>
- <varlistentry>
- <term>Specifies:</term>
- <listitem>
- <para>The directory where the other configuration files are located</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Type of value:</term>
- <listitem>
- <para>Path name</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Default value:</term>
- <listitem>
- <para>/etc/privoxy (Unix) <emphasis>or</emphasis> <application>Privoxy</application> installation dir (Windows) </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Effect if unset:</term>
- <listitem>
- <para><emphasis>Mandatory</emphasis></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- No trailing <quote><literal>/</literal></quote>, please
- </para>
- <para>
- When development goes modular and multi-user, the blocker, filter, and
- per-user config will be stored in subdirectories of <quote>confdir</quote>.
- For now, the configuration directory structure is flat, except for
- <filename>confdir/templates</filename>, where the HTML templates for CGI
- output reside (e.g. <application>Privoxy's</application> 404 error page).
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect4>
-
-
-<sect4 id="logdir"><title>logdir</title>
-
-<variablelist>
- <varlistentry>
- <term>Specifies:</term>
- <listitem>
- <para>
- The directory where all logging takes place (i.e. where <filename>logfile</filename> and
- <filename>jarfile</filename> are located)
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Type of value:</term>
- <listitem>
- <para>Path name</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Default value:</term>
- <listitem>
- <para>/var/log/privoxy (Unix) <emphasis>or</emphasis> <application>Privoxy</application> installation dir (Windows) </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Effect if unset:</term>
- <listitem>
- <para><emphasis>Mandatory</emphasis></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- No trailing <quote><literal>/</literal></quote>, please
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect4>
-
-<sect4 id="actionsfile"><title>
-<anchor id="default.action">
-<anchor id="standard.action">
-<anchor id="user.action">
-actionsfile
-</title>
-
-<variablelist>
- <varlistentry>
- <term>Specifies:</term>
- <listitem>
- <para>
- The actions file(s) to use
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Type of value:</term>
- <listitem>
- <para>File name, relative to <literal>confdir</literal></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Default value:</term>
- <listitem>
- <simplelist>
- <member>
- <msgtext><literallayout> standard # Internal purposes, recommended not editing</literallayout></msgtext>
- </member>
- <member>
- <msgtext><literallayout> default # Main actions file</literallayout></msgtext>
- </member>
- <member>
- <msgtext><literallayout> user # User customizations</literallayout></msgtext>
- </member>
- </simplelist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Effect if unset:</term>
- <listitem>
- <para>
- No actions are taken at all. Simple neutral proxying.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- Multiple <literal>actionsfile</literal> lines are OK and are in fact recommended!
- </para>
- <para>
- The default values include standard.action, which is used for internal
- purposes and should be loaded, default.action, which is the
- <quote>main</quote> actions file maintained by the developers, and
- user.action, where you can make your personal additions.
- </para>
- <para>
- There is no point in using <application>Privoxy</application> without an actions file.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect4>
-
-<sect4 id="filterfile"><title><anchor id="default.filter">filterfile</title>
-<variablelist>
- <varlistentry>
- <term>Specifies:</term>
- <listitem>
- <para>
- The filter file to use
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Type of value:</term>
- <listitem>
- <para>File name, relative to <literal>confdir</literal></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Default value:</term>
- <listitem>
- <para>default.filter (Unix) <emphasis>or</emphasis> default.filter.txt (Windows)</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Effect if unset:</term>
- <listitem>
- <para>
- No textual content filtering takes place, i.e. all
- <literal>+filter{<replaceable class="parameter">name</replaceable>}</literal>
- actions in the actions files are turned off
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- The <quote>default.filter</quote> file contains content modification rules
- that use <quote>regular expressions</quote>. These rules permit powerful
- changes on the content of Web pages, e.g., you could disable your favorite
- JavaScript annoyances, re-write the actual displayed text, or just have some
- fun replacing <quote>Microsoft</quote> with <quote>MicroSuck</quote> wherever
- it appears on a Web page.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect4>
-
-<sect4 id="logfile"><title>logfile</title>
-
-<variablelist>
- <varlistentry>
- <term>Specifies:</term>
- <listitem>
- <para>
- The log file to use
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Type of value:</term>
- <listitem>
- <para>File name, relative to <literal>logdir</literal></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Default value:</term>
- <listitem>
- <para>logfile (Unix) <emphasis>or</emphasis> privoxy.log (Windows)</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Effect if unset:</term>
- <listitem>
- <para>
- No log file is used, all log messages go to the console (<literal>stderr</literal>).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- The windows version will additionally log to the console.
- </para>
- <para>
- The logfile is where all logging and error messages are written. The level
- of detail and number of messages are set with the <literal>debug</literal>
- option (see below). The logfile can be useful for tracking down a problem with
- <application>Privoxy</application> (e.g., it's not blocking an ad you
- think it should block) but in most cases you probably will never look at it.
- </para>
- <para>
- Your logfile will grow indefinitely, and you will probably want to
- periodically remove it. On Unix systems, you can do this with a cron job
- (see <quote>man cron</quote>). For Red Hat, a <command>logrotate</command>
- script has been included.
- </para>
- <para>
- On SuSE Linux systems, you can place a line like <quote>/var/log/privoxy.*
- +1024k 644 nobody.nogroup</quote> in <filename>/etc/logfiles</filename>, with
- the effect that cron.daily will automatically archive, gzip, and empty the
- log, when it exceeds 1M size.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect4>
-
-<sect4 id="jarfile"><title>jarfile</title>
-
-<variablelist>
- <varlistentry>
- <term>Specifies:</term>
- <listitem>
- <para>
- The file to store intercepted cookies in
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Type of value:</term>
- <listitem>
- <para>File name, relative to <literal>logdir</literal></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Default value:</term>
- <listitem>
- <para>jarfile (Unix) <emphasis>or</emphasis> privoxy.jar (Windows)</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Effect if unset:</term>
- <listitem>
- <para>
- Intercepted cookies are not stored at all.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- The jarfile may grow to ridiculous sizes over time.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect4>
-
-<sect4 id="trustfile"><title>trustfile</title>
-
-<variablelist>
- <varlistentry>
- <term>Specifies:</term>
- <listitem>
- <para>
- The trust file to use
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Type of value:</term>
- <listitem>
- <para>File name, relative to <literal>confdir</literal></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Default value:</term>
- <listitem>
- <para><emphasis>Unset (commented out)</emphasis>. When activated: trust (Unix) <emphasis>or</emphasis> trust.txt (Windows)</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Effect if unset:</term>
- <listitem>
- <para>
- The whole trust mechanism is turned off.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- The trust mechanism is an experimental feature for building white-lists and should
- be used with care. It is <emphasis>NOT</emphasis> recommended for the casual user.
- </para>
- <para>
- If you specify a trust file, <application>Privoxy</application> will only allow
- access to sites that are named in the trustfile.
- You can also mark sites as trusted referrers (with <literal>+</literal>), with
- the effect that access to untrusted sites will be granted, if a link from a
- trusted referrer was used.
- The link target will then be added to the <quote>trustfile</quote>.
- Possible applications include limiting Internet access for children.
- </para>
- <para>
- If you use <literal>+</literal> operator in the trust file, it may grow considerably over time.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect4>
-
-</sect3>
-
-<!-- ~ End section ~ -->
-
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-
-<sect3 id="local-set-up">
-<title>Local Set-up Documentation</title>
-
- <para>
- If you intend to operate <application>Privoxy</application> for more users
- that just yourself, it might be a good idea to let them know how to reach
- you, what you block and why you do that, your policies etc.
- </para>
-
-<sect4 id="trust-info-url"><title>trust-info-url</title>
-
-<variablelist>
- <varlistentry>
- <term>Specifies:</term>
- <listitem>
- <para>
- A URL to be displayed in the error page that users will see if access to an untrusted page is denied.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Type of value:</term>
- <listitem>
- <para>URL</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Default value:</term>
- <listitem>
- <para>Two example URL are provided</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Effect if unset:</term>
- <listitem>
- <para>
- No links are displayed on the "untrusted" error page.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- The value of this option only matters if the experimental trust mechanism has been
- activated. (See <literal>trustfile</literal> above.)
- </para>
- <para>
- If you use the trust mechanism, it is a good idea to write up some on-line
- documentation about your trust policy and to specify the URL(s) here.
- Use multiple times for multiple URLs.
- </para>
- <para>
- The URL(s) should be added to the trustfile as well, so users don't end up
- locked out from the information on why they were locked out in the first place!
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect4>
-
-<sect4 id="admin-address"><title>admin-address</title>
-
-<variablelist>
- <varlistentry>
- <term>Specifies:</term>
- <listitem>
- <para>
- An email address to reach the proxy administrator.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Type of value:</term>
- <listitem>
- <para>Email address</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Default value:</term>
- <listitem>
- <para><emphasis>Unset</emphasis></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Effect if unset:</term>
- <listitem>
- <para>
- No email address is displayed on error pages and the CGI user interface.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- If both <literal>admin-address</literal> and <literal>proxy-info-url</literal>
- are unset, the whole "Local Privoxy Support" box on all generated pages will
- not be shown.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect4>
-
-<sect4 id="proxy-info-url"><title>proxy-info-url</title>
-
-<variablelist>
- <varlistentry>
- <term>Specifies:</term>
- <listitem>
- <para>
- A URL to documentation about the local <application>Privoxy</application> setup,
- configuration or policies.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Type of value:</term>
- <listitem>
- <para>URL</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Default value:</term>
- <listitem>
- <para><emphasis>Unset</emphasis></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Effect if unset:</term>
- <listitem>
- <para>
- No link to local documentation is displayed on error pages and the CGI user interface.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- If both <literal>admin-address</literal> and <literal>proxy-info-url</literal>
- are unset, the whole "Local Privoxy Support" box on all generated pages will
- not be shown.
- </para>
- <para>
- This URL shouldn't be blocked ;-)
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect4>
-
-</sect3>
-<!-- ~ End section ~ -->
-
-<!-- ~~~~~ New section ~~~~~ -->
-
-<sect3 id="debugging">
-<title>Debugging</title>
-
- <para>
- These options are mainly useful when tracing a problem.
- Note that you might also want to invoke
- <application>Privoxy</application> with the <literal>--no-daemon</literal>
- command line option when debugging.
- </para>
-
-<sect4 id="debug"><title>debug</title>
-
-<variablelist>
- <varlistentry>
- <term>Specifies:</term>
- <listitem>
- <para>
- Key values that determine what information gets logged.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Type of value:</term>
- <listitem>
- <para>Integer values</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Default value:</term>
- <listitem>
- <para>12289 (i.e.: URLs plus informational and warning messages)</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Effect if unset:</term>
- <listitem>
- <para>
- Nothing gets logged.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- The available debug levels are:
- </para>
- <para>
- <programlisting>
- debug 1 # show each GET/POST/CONNECT request
- debug 2 # show each connection status
- debug 4 # show I/O status
- debug 8 # show header parsing
- debug 16 # log all data into the logfile
- debug 32 # debug force feature
- debug 64 # debug regular expression filter
- debug 128 # debug fast redirects
- debug 256 # debug GIF de-animation
- debug 512 # Common Log Format
- debug 1024 # debug kill pop-ups
- debug 4096 # Startup banner and warnings.
- debug 8192 # Non-fatal errors
- </programlisting>
- </para>
- <para>
- To select multiple debug levels, you can either add them or use
- multiple <literal>debug</literal> lines.
- </para>
- <para>
- A debug level of 1 is informative because it will show you each request
- as it happens. <emphasis>1, 4096 and 8192 are highly recommended</emphasis>
- so that you will notice when things go wrong. The other levels are probably
- only of interest if you are hunting down a specific problem. They can produce
- a hell of an output (especially 16).
- <!-- LOL -->
- </para>
- <para>
- The reporting of <emphasis>fatal</emphasis> errors (i.e. ones which crash
- <application>Privoxy</application>) is always on and cannot be disabled.
- </para>
- <para>
- If you want to use CLF (Common Log Format), you should set <quote>debug
- 512</quote> <emphasis>ONLY</emphasis> and not enable anything else.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect4>
-
-<sect4 id="single-threaded"><title>single-threaded</title>
-
-<variablelist>
- <varlistentry>
- <term>Specifies:</term>
- <listitem>
- <para>
- Whether to run only one server thread
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Type of value:</term>
- <listitem>
- <para><emphasis>None</emphasis></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Default value:</term>
- <listitem>
- <para><emphasis>Unset</emphasis></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Effect if unset:</term>
- <listitem>
- <para>
- Multi-threaded (or, where unavailable: forked) operation, i.e. the ability to
- serve multiple requests simultaneously.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- This option is only there for debug purposes and you should never
- need to use it. <emphasis>It will drastically reduce performance.</emphasis>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect4>
-
-</sect3>
-
-<!-- ~~~~~ New section ~~~~~ -->
-
-<sect3 id="access-control">
-<title>Access Control and Security</title>
-
- <para>
- This section of the config file controls the security-relevant aspects
- of <application>Privoxy</application>'s configuration.
- </para>
-
-<sect4 id="listen-address"><title>listen-address</title>
-
-<variablelist>
- <varlistentry>
- <term>Specifies:</term>
- <listitem>
- <para>
- The IP address and TCP port on which <application>Privoxy</application> will
- listen for client requests.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Type of value:</term>
- <listitem>
- <para>[<replaceable class="parameter">IP-Address</replaceable>]:<replaceable class="parameter">Port</replaceable></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Default value:</term>
- <listitem>
- <para>localhost:8118</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Effect if unset:</term>
- <listitem>
- <para>
- Bind to localhost (127.0.0.1), port 8118. This is suitable and recommended for
- home users who run <application>Privoxy</application> on the same machine as
- their browser.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- You will need to configure your browser(s) to this proxy address and port.
- </para>
- <para>
- If you already have another service running on port 8118, or if you want to
- serve requests from other machines (e.g. on your local network) as well, you
- will need to override the default.
- </para>
- <para>
- If you leave out the IP address, <application>Privoxy</application> will
- bind to all interfaces (addresses) on your machine and may become reachable
- from the Internet. In that case, consider using access control lists (ACL's)
- (see <quote>ACLs</quote> below), or a firewall.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Example:</term>
- <listitem>
- <para>
- Suppose you are running <application>Privoxy</application> on
- a machine which has the address 192.168.0.1 on your local private network
- (192.168.0.0) and has another outside connection with a different address.
- You want it to serve requests from inside only:
- </para>
- <para>
- <programlisting>
- listen-address 192.168.0.1:8118
- </programlisting>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect4>
-
-<sect4 id="toggle"><title>toggle</title>
-
-<variablelist>
- <varlistentry>
- <term>Specifies:</term>
- <listitem>
- <para>
- Initial state of "toggle" status
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Type of value:</term>
- <listitem>
- <para>1 or 0</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Default value:</term>
- <listitem>
- <para>1</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Effect if unset:</term>
- <listitem>
- <para>
- Act as if toggled on
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- If set to 0, <application>Privoxy</application> will start in
- <quote>toggled off</quote> mode, i.e. behave like a normal, content-neutral
- proxy. See <literal>enable-remote-toggle</literal>
- below. This is not really useful anymore, since toggling is much easier
- via <ulink url="http://config.privoxy.org/toggle">the web
- interface</ulink> then via editing the <filename>conf</filename> file.
- </para>
- <para>
- The windows version will only display the toggle icon in the system tray
- if this option is present.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect4>
-
-
-<sect4 id="enable-remote-toggle"><title>enable-remote-toggle</title>
-<variablelist>
- <varlistentry>
- <term>Specifies:</term>
- <listitem>
- <para>
- Whether or not the <ulink url="http://config.privoxy.org/toggle">web-based toggle
- feature</ulink> may be used
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Type of value:</term>
- <listitem>
- <para>0 or 1</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Default value:</term>
- <listitem>
- <para>1</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Effect if unset:</term>
- <listitem>
- <para>
- The web-based toggle feature is disabled.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- When toggled off, <application>Privoxy</application> acts like a normal,
- content-neutral proxy, i.e. it acts as if none of the actions applied to
- any URL.
- </para>
- <para>
- For the time being, access to the toggle feature can <emphasis>not</emphasis> be
- controlled separately by <quote>ACLs</quote> or HTTP authentication,
- so that everybody who can access <application>Privoxy</application> (see
- <quote>ACLs</quote> and <literal>listen-address</literal> above) can
- toggle it for all users. So this option is <emphasis>not recommended</emphasis>
- for multi-user environments with untrusted users.
- </para>
- <para>
- Note that you must have compiled <application>Privoxy</application> with
- support for this feature, otherwise this option has no effect.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect4>
-
-
-<sect4 id="enable-edit-actions"><title>enable-edit-actions</title>
-<variablelist>
- <varlistentry>
- <term>Specifies:</term>
- <listitem>
- <para>
- Whether or not the <ulink url="http://config.privoxy.org/edit-actions">web-based actions
- file editor</ulink> may be used
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Type of value:</term>
- <listitem>
- <para>0 or 1</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Default value:</term>
- <listitem>
- <para>1</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Effect if unset:</term>
- <listitem>
- <para>
- The web-based actions file editor is disabled.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- For the time being, access to the editor can <emphasis>not</emphasis> be
- controlled separately by <quote>ACLs</quote> or HTTP authentication,
- so that everybody who can access <application>Privoxy</application> (see
- <quote>ACLs</quote> and <literal>listen-address</literal> above) can
- modify its configuration for all users. So this option is <emphasis>not
- recommended</emphasis> for multi-user environments with untrusted users.
- </para>
- <para>
- Note that you must have compiled <application>Privoxy</application> with
- support for this feature, otherwise this option has no effect.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect4>
-
-<sect4 id="acls"><title>
-<anchor id="permit-acces">
-<anchor id="deny-acces">
-ACLs: permit-access and deny-access</title>
-
-<variablelist>
- <varlistentry>
- <term>Specifies:</term>
- <listitem>
- <para>
- Who can access what.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Type of value:</term>
- <listitem>
- <para>
- <replaceable class="parameter">src_addr</replaceable>[/<replaceable class="parameter">src_masklen</replaceable>]
- [<replaceable class="parameter">dst_addr</replaceable>[/<replaceable class="parameter">dst_masklen</replaceable>]]
- </para>
- <para>
- Where <replaceable class="parameter">src_addr</replaceable> and
- <replaceable class="parameter">dst_addr</replaceable> are IP addresses in dotted decimal notation or valid
- DNS names, and <replaceable class="parameter">src_masklen</replaceable> and
- <replaceable class="parameter">dst_masklen</replaceable> are subnet masks in CIDR notation, i.e. integer
- values from 2 to 30 representing the length (in bits) of the network address. The masks and the whole
- destination part are optional.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Default value:</term>
- <listitem>
- <para><emphasis>Unset</emphasis></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Effect if unset:</term>
- <listitem>
- <para>
- Don't restrict access further than implied by <literal>listen-address</literal>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- Access controls are included at the request of ISPs and systems
- administrators, and <emphasis>are not usually needed by individual users</emphasis>.
- For a typical home user, it will normally suffice to ensure that
- <application>Privoxy</application> only listens on the localhost or internal (home)
- network address by means of the <literal>listen-address</literal> option.
- </para>
- <para>
- Please see the warnings in the FAQ that this proxy is not intended to be a substitute
- for a firewall or to encourage anyone to defer addressing basic security
- weaknesses.
- </para>
- <para>
- Multiple ACL lines are OK.
- If any ACLs are specified, then the <application>Privoxy</application>
- talks only to IP addresses that match at least one <literal>permit-access</literal> line
- and don't match any subsequent <literal>deny-access</literal> line. In other words, the
- last match wins, with the default being <literal>deny-access</literal>.
- </para>
- <para>
- If <application>Privoxy</application> is using a forwarder (see <literal>forward</literal> below)
- for a particular destination URL, the <replaceable class="parameter">dst_addr</replaceable>
- that is examined is the address of the forwarder and <emphasis>NOT</emphasis> the address
- of the ultimate target. This is necessary because it may be impossible for the local
- <application>Privoxy</application> to determine the IP address of the
- ultimate target (that's often what gateways are used for).
- </para>
- <para>
- You should prefer using IP addresses over DNS names, because the address lookups take
- time. All DNS names must resolve! You can <emphasis>not</emphasis> use domain patterns
- like <quote>*.org</quote> or partial domain names. If a DNS name resolves to multiple
- IP addresses, only the first one is used.
- </para>
- <para>
- Denying access to particular sites by ACL may have undesired side effects
- if the site in question is hosted on a machine which also hosts other sites.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Examples:</term>
- <listitem>
- <para>
- Explicitly define the default behavior if no ACL and
- <literal>listen-address</literal> are set: <quote>localhost</quote>
- is OK. The absence of a <replaceable class="parameter">dst_addr</replaceable> implies that
- <emphasis>all</emphasis> destination addresses are OK:
- </para>
- <para>
- <screen>
- permit-access localhost
- </screen>
- </para>
- <para>
- Allow any host on the same class C subnet as www.privoxy.org access to
- nothing but www.example.com:
- </para>
- <para>
- <screen>
- permit-access www.privoxy.org/24 www.example.com/32
- </screen>
- </para>
- <para>
- Allow access from any host on the 26-bit subnet 192.168.45.64 to anywhere,
- with the exception that 192.168.45.73 may not access www.dirty-stuff.example.com:
- </para>
- <para>
- <screen>
- permit-access 192.168.45.64/26
- deny-access 192.168.45.73 www.dirty-stuff.example.com
- </screen>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect4>
-
-<sect4 id="buffer-limit"><title>buffer-limit</title>
-
-<variablelist>
- <varlistentry>
- <term>Specifies:</term>
- <listitem>
- <para>
- Maximum size of the buffer for content filtering.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Type of value:</term>
- <listitem>
- <para>Size in Kbytes</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Default value:</term>
- <listitem>
- <para>4096</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Effect if unset:</term>
- <listitem>
- <para>
- Use a 4MB (4096 KB) limit.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- For content filtering, i.e. the <literal>+filter</literal> and
- <literal>+deanimate-gif</literal> actions, it is necessary that
- <application>Privoxy</application> buffers the entire document body.
- This can be potentially dangerous, since a server could just keep sending
- data indefinitely and wait for your RAM to exhaust -- with nasty consequences.
- Hence this option.
- </para>
- <para>
- When a document buffer size reaches the <literal>buffer-limit</literal>, it is
- flushed to the client unfiltered and no further attempt to
- filter the rest of the document is made. Remember that there may be multiple threads
- running, which might require up to <literal>buffer-limit</literal> Kbytes
- <emphasis>each</emphasis>, unless you have enabled <quote>single-threaded</quote>
- above.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect4>
-
-</sect3>
-
-<!-- ~ End section ~ -->
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-
-<sect3 id="forwarding">
-<title>Forwarding</title>
-
-<para>
- This feature allows routing of HTTP requests through a chain of
- multiple proxies.
- It can be used to better protect privacy and confidentiality when
- accessing specific domains by routing requests to those domains
- through an anonymous public proxy (see e.g. <ulink
- url="http://www.multiproxy.org/anon_list.htm">http://www.multiproxy.org/anon_list.htm</ulink>)
- Or to use a caching proxy to speed up browsing. Or chaining to a parent
- proxy may be necessary because the machine that <application>Privoxy</application>
- runs on has no direct Internet access.
-</para>
-
-<para>
- Also specified here are SOCKS proxies. <application>Privoxy</application>
- supports the SOCKS 4 and SOCKS 4A protocols.
-</para>
-
-<sect4 id="forward"><title>forward</title>
-<variablelist>
- <varlistentry>
- <term>Specifies:</term>
- <listitem>
- <para>
- To which parent HTTP proxy specific requests should be routed.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Type of value:</term>
- <listitem>
- <para>
- <replaceable class="parameter">target_domain</replaceable>[:<replaceable class="parameter">port</replaceable>]
- <replaceable class="parameter">http_parent</replaceable>[/<replaceable class="parameter">port</replaceable>]
- </para>
- <para>
- Where <replaceable class="parameter">target_domain</replaceable> is a domain name pattern (see the
- chapter on domain matching in the <filename>default.action</filename> file),
- <replaceable class="parameter">http_parent</replaceable> is the address of the parent HTTP proxy
- as an IP addresses in dotted decimal notation or as a valid DNS name (or <quote>.</quote> to denote
- <quote>no forwarding</quote>, and the optional
- <replaceable class="parameter">port</replaceable> parameters are TCP ports, i.e. integer
- values from 1 to 64535
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Default value:</term>
- <listitem>
- <para><emphasis>Unset</emphasis></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Effect if unset:</term>
- <listitem>
- <para>
- Don't use parent HTTP proxies.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- If <replaceable class="parameter">http_parent</replaceable> is <quote>.</quote>, then requests are not
- forwarded to another HTTP proxy but are made directly to the web servers.
- </para>
- <para>
- Multiple lines are OK, they are checked in sequence, and the last match wins.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Examples:</term>
- <listitem>
- <para>
- Everything goes to an example anonymizing proxy, except SSL on port 443 (which it doesn't handle):
- </para>
- <para>
- <screen>
- forward .* anon-proxy.example.org:8080
- forward :443 .
- </screen>
- </para>
- <para>
- Everything goes to our example ISP's caching proxy, except for requests
- to that ISP's sites:
- </para>
- <para>
- <screen>
- forward .*. caching-proxy.example-isp.net:8000
- forward .example-isp.net .
- </screen>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect4>
-
-<sect4 id="socks"><title>
-<anchor id="forward-socks4">
-<anchor id="forward-socks4a">
-forward-socks4 and forward-socks4a</title>
-
-<variablelist>
- <varlistentry>
- <term>Specifies:</term>
- <listitem>
- <para>
- Through which SOCKS proxy (and to which parent HTTP proxy) specific requests should be routed.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Type of value:</term>
- <listitem>
- <para>
- <replaceable class="parameter">target_domain</replaceable>[:<replaceable class="parameter">port</replaceable>]
- <replaceable class="parameter">socks_proxy</replaceable>[/<replaceable class="parameter">port</replaceable>]
- <replaceable class="parameter">http_parent</replaceable>[/<replaceable class="parameter">port</replaceable>]
- </para>
- <para>
- Where <replaceable class="parameter">target_domain</replaceable> is a domain name pattern (see the
- chapter on domain matching in the <filename>default.action</filename> file),
- <replaceable class="parameter">http_parent</replaceable> and <replaceable class="parameter">socks_proxy</replaceable>
- are IP addresses in dotted decimal notation or valid DNS names (<replaceable class="parameter">http_parent</replaceable>
- may be <quote>.</quote> to denote <quote>no HTTP forwarding</quote>), and the optional
- <replaceable class="parameter">port</replaceable> parameters are TCP ports, i.e. integer values from 1 to 64535
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Default value:</term>
- <listitem>
- <para><emphasis>Unset</emphasis></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Effect if unset:</term>
- <listitem>
- <para>
- Don't use SOCKS proxies.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- Multiple lines are OK, they are checked in sequence, and the last match wins.
- </para>
- <para>
- The difference between <literal>forward-socks4</literal> and <literal>forward-socks4a</literal>
- is that in the SOCKS 4A protocol, the DNS resolution of the target hostname happens on the SOCKS
- server, while in SOCKS 4 it happens locally.
- </para>
- <para>
- If <replaceable class="parameter">http_parent</replaceable> is <quote>.</quote>, then requests are not
- forwarded to another HTTP proxy but are made (HTTP-wise) directly to the web servers, albeit through
- a SOCKS proxy.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Examples:</term>
- <listitem>
- <para>
- From the company example.com, direct connections are made to all
- <quote>internal</quote> domains, but everything outbound goes through
- their ISP's proxy by way of example.com's corporate SOCKS 4A gateway to
- the Internet.
- </para>
- <para>
- <screen>
- forward-socks4a .*. socks-gw.example.com:1080 www-cache.example-isp.net:8080
- forward .example.com .
- </screen>
- </para>
- <para>
- A rule that uses a SOCKS 4 gateway for all destinations but no HTTP parent looks like this:
- </para>
- <para>
- <screen>
- forward-socks4 .*. socks-gw.example.com:1080 .
- </screen>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect4>
-
-<sect4 id="advanced-forwarding-examples"><title>Advanced Forwarding Examples</title>