- debug 8192 # Non-fatal errors</PRE
-></TD
-></TR
-></TABLE
->
- </P
-><P
-> To select multiple debug levels, you can either add them or use
- multiple <TT
-CLASS="LITERAL"
->debug</TT
-> lines.
- </P
-><P
-> A debug level of 1 is informative because it will show you each request
- as it happens. <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->1, 4096 and 8192 are recommended</I
-></SPAN
->
- 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).
-
- </P
-><P
-> <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> used to ship with the debug levels recommended above enabled by
- default, but due to privacy concerns 3.0.7 and later are configured to
- only log fatal errors.
- </P
-><P
-> If you are used to the more verbose settings, simply enable the debug lines
- below again.
- </P
-><P
-> If you want to use pure CLF (Common Log Format), you should set <SPAN
-CLASS="QUOTE"
->"debug
- 512"</SPAN
-> <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->ONLY</I
-></SPAN
-> and not enable anything else.
- </P
-><P
-> <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> has a hard-coded limit for the
- length of log messages. If it's reached, messages are logged truncated
- and marked with <SPAN
-CLASS="QUOTE"
->"... [too long, truncated]"</SPAN
->.
- </P
-><P
-> Please don't file any support requests without trying to reproduce
- the problem with increased debug level first. Once you read the log
- messages, you may even be able to solve the problem on your own.
- </P
-></DD
-></DL
-></DIV
-></DIV
-><DIV
-CLASS="SECT3"
-><H4
-CLASS="SECT3"
-><A
-NAME="SINGLE-THREADED"
->7.3.2. single-threaded</A
-></H4
-><P
-></P
-><DIV
-CLASS="VARIABLELIST"
-><DL
-><DT
->Specifies:</DT
-><DD
-><P
-> Whether to run only one server thread.
- </P
-></DD
-><DT
->Type of value:</DT
-><DD
-><P
-><SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->None</I
-></SPAN
-></P
-></DD
-><DT
->Default value:</DT
-><DD
-><P
-><SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->Unset</I
-></SPAN
-></P
-></DD
-><DT
->Effect if unset:</DT
-><DD
-><P
-> Multi-threaded (or, where unavailable: forked) operation, i.e. the ability to
- serve multiple requests simultaneously.
- </P
-></DD
-><DT
->Notes:</DT
-><DD
-><P
-> This option is only there for debugging purposes.
- <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->It will drastically reduce performance.</I
-></SPAN
->
- </P
-></DD
-></DL
-></DIV
-></DIV
-><DIV
-CLASS="SECT3"
-><H4
-CLASS="SECT3"
-><A
-NAME="HOSTNAME"
->7.3.3. hostname</A
-></H4
-><P
-></P
-><DIV
-CLASS="VARIABLELIST"
-><DL
-><DT
->Specifies:</DT
-><DD
-><P
-> The hostname shown on the CGI pages.
- </P
-></DD
-><DT
->Type of value:</DT
-><DD
-><P
->Text</P
-></DD
-><DT
->Default value:</DT
-><DD
-><P
-><SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->Unset</I
-></SPAN
-></P
-></DD
-><DT
->Effect if unset:</DT
-><DD
-><P
-> The hostname provided by the operating system is used.
- </P
-></DD
-><DT
->Notes:</DT
-><DD
-><P
-> On some misconfigured systems resolving the hostname fails or
- takes too much time and slows Privoxy down. Setting a fixed hostname
- works around the problem.
- </P
-><P
-> In other circumstances it might be desirable to show a hostname
- other than the one returned by the operating system. For example
- if the system has several different hostnames and you don't want
- to use the first one.
- </P
-><P
-> Note that Privoxy does not validate the specified hostname value.
- </P
-></DD
-></DL
-></DIV
-></DIV
-></DIV
-><DIV
-CLASS="SECT2"
-><H2
-CLASS="SECT2"
-><A
-NAME="ACCESS-CONTROL"
->7.4. Access Control and Security</A
-></H2
-><P
-> This section of the config file controls the security-relevant aspects
- of <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
->'s configuration.
- </P
-><DIV
-CLASS="SECT3"
-><H4
-CLASS="SECT3"
-><A
-NAME="LISTEN-ADDRESS"
->7.4.1. listen-address</A
-></H4
-><P
-></P
-><DIV
-CLASS="VARIABLELIST"
-><DL
-><DT
->Specifies:</DT
-><DD
-><P
-> The IP address and TCP port on which <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> will
- listen for client requests.
- </P
-></DD
-><DT
->Type of value:</DT
-><DD
-><P
->[<TT
-CLASS="REPLACEABLE"
-><I
->IP-Address</I
-></TT
->]:<TT
-CLASS="REPLACEABLE"
-><I
->Port</I
-></TT
-></P
-></DD
-><DT
->Default value:</DT
-><DD
-><P
->127.0.0.1:8118</P
-></DD
-><DT
->Effect if unset:</DT
-><DD
-><P
-> Bind to 127.0.0.1 (localhost), port 8118. This is suitable and recommended for
- home users who run <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> on the same machine as
- their browser.
- </P
-></DD
-><DT
->Notes:</DT
-><DD
-><P
-> You will need to configure your browser(s) to this proxy address and port.
- </P
-><P
-> 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.
- </P
-><P
-> If you leave out the IP address, <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> will
- bind to all interfaces (addresses) on your machine and may become reachable
- from the Internet. In that case, consider using <A
-HREF="config.html#ACLS"
->access control lists</A
-> (ACL's, see below), and/or
- a firewall.
- </P
-><P
-> If you open <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> to untrusted users, you will
- also want to make sure that the following actions are disabled: <TT
-CLASS="LITERAL"
-><A
-HREF="config.html#ENABLE-EDIT-ACTIONS"
->enable-edit-actions</A
-></TT
-> and
- <TT
-CLASS="LITERAL"
-><A
-HREF="config.html#ENABLE-REMOTE-TOGGLE"
->enable-remote-toggle</A
-></TT
->
- </P
-></DD
-><DT
->Example:</DT
-><DD
-><P
-> Suppose you are running <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> 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:
- </P
-><P
-> <TABLE
-BORDER="0"
-BGCOLOR="#E0E0E0"
-WIDTH="90%"
-><TR
-><TD
-><PRE
-CLASS="PROGRAMLISTING"
-> listen-address 192.168.0.1:8118</PRE
-></TD
-></TR
-></TABLE
->
- </P
-></DD
-></DL
-></DIV
-></DIV
-><DIV
-CLASS="SECT3"
-><H4
-CLASS="SECT3"
-><A
-NAME="TOGGLE"
->7.4.2. toggle</A
-></H4
-><P
-></P
-><DIV
-CLASS="VARIABLELIST"
-><DL
-><DT
->Specifies:</DT
-><DD
-><P
-> Initial state of "toggle" status
- </P
-></DD
-><DT
->Type of value:</DT
-><DD
-><P
->1 or 0</P
-></DD
-><DT
->Default value:</DT
-><DD
-><P
->1</P
-></DD
-><DT
->Effect if unset:</DT
-><DD
-><P
-> Act as if toggled on
- </P
-></DD
-><DT
->Notes:</DT
-><DD
-><P
-> If set to 0, <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> will start in
- <SPAN
-CLASS="QUOTE"
->"toggled off"</SPAN
-> mode, i.e. mostly behave like a normal,
- content-neutral proxy with both ad blocking and content filtering
- disabled. See <TT
-CLASS="LITERAL"
->enable-remote-toggle</TT
-> below.
- </P
-><P
-> The windows version will only display the toggle icon in the system tray
- if this option is present.
- </P
-></DD
-></DL
-></DIV
-></DIV
-><DIV
-CLASS="SECT3"
-><H4
-CLASS="SECT3"
-><A
-NAME="ENABLE-REMOTE-TOGGLE"
->7.4.3. enable-remote-toggle</A
-></H4
-><P
-></P
-><DIV
-CLASS="VARIABLELIST"
-><DL
-><DT
->Specifies:</DT
-><DD
-><P
-> Whether or not the <A
-HREF="http://config.privoxy.org/toggle"
-TARGET="_top"
->web-based toggle
- feature</A
-> may be used
- </P
-></DD
-><DT
->Type of value:</DT
-><DD
-><P
->0 or 1</P
-></DD
-><DT
->Default value:</DT
-><DD
-><P
->0</P
-></DD
-><DT
->Effect if unset:</DT
-><DD
-><P
-> The web-based toggle feature is disabled.
- </P
-></DD
-><DT
->Notes:</DT
-><DD
-><P
-> When toggled off, <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> mostly acts like a normal,
- content-neutral proxy, i.e. doesn't block ads or filter content.
- </P
-><P
-> Access to the toggle feature can <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->not</I
-></SPAN
-> be
- controlled separately by <SPAN
-CLASS="QUOTE"
->"ACLs"</SPAN
-> or HTTP authentication,
- so that everybody who can access <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> (see
- <SPAN
-CLASS="QUOTE"
->"ACLs"</SPAN
-> and <TT
-CLASS="LITERAL"
->listen-address</TT
-> above) can
- toggle it for all users. So this option is <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->not recommended</I
-></SPAN
->
- for multi-user environments with untrusted users.
- </P
-><P
-> Note that malicious client side code (e.g Java) is also
- capable of using this option.
- </P
-><P
-> As a lot of <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> users don't read
- documentation, this feature is disabled by default.
- </P
-><P
-> Note that you must have compiled <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> with
- support for this feature, otherwise this option has no effect.
- </P
-></DD
-></DL
-></DIV
-></DIV
-><DIV
-CLASS="SECT3"
-><H4
-CLASS="SECT3"
-><A
-NAME="ENABLE-REMOTE-HTTP-TOGGLE"
->7.4.4. enable-remote-http-toggle</A
-></H4
-><P
-></P
-><DIV
-CLASS="VARIABLELIST"
-><DL
-><DT
->Specifies:</DT
-><DD
-><P
-> Whether or not Privoxy recognizes special HTTP headers to change its behaviour.
- </P
-></DD
-><DT
->Type of value:</DT
-><DD
-><P
->0 or 1</P
-></DD
-><DT
->Default value:</DT
-><DD
-><P
->0</P
-></DD
-><DT
->Effect if unset:</DT
-><DD
-><P
-> Privoxy ignores special HTTP headers.
- </P
-></DD
-><DT
->Notes:</DT
-><DD
-><P
-> When toggled on, the client can change <SPAN
-CLASS="APPLICATION"
->Privoxy's</SPAN
->
- behaviour by setting special HTTP headers. Currently the only supported
- special header is <SPAN
-CLASS="QUOTE"
->"X-Filter: No"</SPAN
->, to disable filtering for
- the ongoing request, even if it is enabled in one of the action files.
- </P
-><P
-> This feature is disabled by default. If you are using
- <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> in a environment with trusted clients,
- you may enable this feature at your discretion. Note that malicious client
- side code (e.g Java) is also capable of using this feature.
- </P
-><P
-> This option will be removed in future releases as it has been obsoleted
- by the more general header taggers.
- </P
-></DD
-></DL
-></DIV
-></DIV
-><DIV
-CLASS="SECT3"
-><H4
-CLASS="SECT3"
-><A
-NAME="ENABLE-EDIT-ACTIONS"
->7.4.5. enable-edit-actions</A
-></H4
-><P
-></P
-><DIV
-CLASS="VARIABLELIST"
-><DL
-><DT
->Specifies:</DT
-><DD
-><P
-> Whether or not the <A
-HREF="http://config.privoxy.org/show-status"
-TARGET="_top"
->web-based actions
- file editor</A
-> may be used
- </P
-></DD
-><DT
->Type of value:</DT
-><DD
-><P
->0 or 1</P
-></DD
-><DT
->Default value:</DT
-><DD
-><P
->0</P
-></DD
-><DT
->Effect if unset:</DT
-><DD
-><P
-> The web-based actions file editor is disabled.
- </P
-></DD
-><DT
->Notes:</DT
-><DD
-><P
-> Access to the editor can <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->not</I
-></SPAN
-> be
- controlled separately by <SPAN
-CLASS="QUOTE"
->"ACLs"</SPAN
-> or HTTP authentication,
- so that everybody who can access <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> (see
- <SPAN
-CLASS="QUOTE"
->"ACLs"</SPAN
-> and <TT
-CLASS="LITERAL"
->listen-address</TT
-> above) can
- modify its configuration for all users.
- </P
-><P
-> This option is <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->not recommended</I
-></SPAN
-> for environments
- with untrusted users and as a lot of <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
->
- users don't read documentation, this feature is disabled by default.
- </P
-><P
-> Note that malicious client side code (e.g Java) is also
- capable of using the actions editor and you shouldn't enable
- this options unless you understand the consequences and are
- sure your browser is configured correctly.
- </P
-><P
-> Note that you must have compiled <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> with
- support for this feature, otherwise this option has no effect.
- </P
-></DD
-></DL
-></DIV
-></DIV
-><DIV
-CLASS="SECT3"
-><H4
-CLASS="SECT3"
-><A
-NAME="ENFORCE-BLOCKS"
->7.4.6. enforce-blocks</A
-></H4
-><P
-></P
-><DIV
-CLASS="VARIABLELIST"
-><DL
-><DT
->Specifies:</DT
-><DD
-><P
-> Whether the user is allowed to ignore blocks and can <SPAN
-CLASS="QUOTE"
->"go there anyway"</SPAN
->.
- </P
-></DD
-><DT
->Type of value:</DT
-><DD
-><P
-> <TT
-CLASS="REPLACEABLE"
-><I
->0 or 1</I
-></TT
->
- </P
-></DD
-><DT
->Default value:</DT
-><DD
-><P
-><SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->0</I
-></SPAN
-></P
-></DD
-><DT
->Effect if unset:</DT
-><DD
-><P
-> Blocks are not enforced.
- </P
-></DD
-><DT
->Notes:</DT
-><DD
-><P
-> <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> is mainly used to block and filter
- requests as a service to the user, for example to block ads and other
- junk that clogs the pipes. <SPAN
-CLASS="APPLICATION"
->Privoxy's</SPAN
-> configuration
- isn't perfect and sometimes innocent pages are blocked. In this situation it
- makes sense to allow the user to enforce the request and have
- <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> ignore the block.
- </P
-><P
-> In the default configuration <SPAN
-CLASS="APPLICATION"
->Privoxy's</SPAN
->
- <SPAN
-CLASS="QUOTE"
->"Blocked"</SPAN
-> page contains a <SPAN
-CLASS="QUOTE"
->"go there anyway"</SPAN
->
- link to adds a special string (the force prefix) to the request URL.
- If that link is used, <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> will
- detect the force prefix, remove it again and let the request pass.
- </P
-><P
-> Of course <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> can also be used to enforce
- a network policy. In that case the user obviously should not be able to
- bypass any blocks, and that's what the <SPAN
-CLASS="QUOTE"
->"enforce-blocks"</SPAN
->
- option is for. If it's enabled, <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> hides
- the <SPAN
-CLASS="QUOTE"
->"go there anyway"</SPAN
-> link. If the user adds the force
- prefix by hand, it will not be accepted and the circumvention attempt
- is logged.
- </P
-></DD
-><DT
->Examples:</DT
-><DD
-><P
-> enforce-blocks 1
- </P
-></DD
-></DL
-></DIV
-></DIV
-><DIV
-CLASS="SECT3"
-><H4
-CLASS="SECT3"
-><A
-NAME="ACLS"
->7.4.7. ACLs: permit-access and deny-access</A
-></H4
-><A
-NAME="PERMIT-ACCESS"
-></A
-><A
-NAME="DENY-ACCESS"
-></A
-><P
-></P
-><DIV
-CLASS="VARIABLELIST"
-><DL
-><DT
->Specifies:</DT
-><DD
-><P
-> Who can access what.
- </P
-></DD
-><DT
->Type of value:</DT
-><DD
-><P
-> <TT
-CLASS="REPLACEABLE"
-><I
->src_addr</I
-></TT
->[/<TT
-CLASS="REPLACEABLE"
-><I
->src_masklen</I
-></TT
->]
- [<TT
-CLASS="REPLACEABLE"
-><I
->dst_addr</I
-></TT
->[/<TT
-CLASS="REPLACEABLE"
-><I
->dst_masklen</I
-></TT
->]]
- </P
-><P
-> Where <TT
-CLASS="REPLACEABLE"
-><I
->src_addr</I
-></TT
-> and
- <TT
-CLASS="REPLACEABLE"
-><I
->dst_addr</I
-></TT
-> are IP addresses in dotted decimal notation or valid
- DNS names, and <TT
-CLASS="REPLACEABLE"
-><I
->src_masklen</I
-></TT
-> and
- <TT
-CLASS="REPLACEABLE"
-><I
->dst_masklen</I
-></TT
-> 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.
- </P
-></DD
-><DT
->Default value:</DT
-><DD
-><P
-><SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->Unset</I
-></SPAN
-></P
-></DD
-><DT
->Effect if unset:</DT
-><DD
-><P
-> Don't restrict access further than implied by <TT
-CLASS="LITERAL"
->listen-address</TT
->
- </P
-></DD
-><DT
->Notes:</DT
-><DD
-><P
-> Access controls are included at the request of ISPs and systems
- administrators, and <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->are not usually needed by individual users</I
-></SPAN
->.
- For a typical home user, it will normally suffice to ensure that
- <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> only listens on the localhost
- (127.0.0.1) or internal (home) network address by means of the
- <A
-HREF="config.html#LISTEN-ADDRESS"
-><SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->listen-address</I
-></SPAN
-></A
->
- option.
- </P
-><P
-> Please see the warnings in the FAQ that <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
->
- is not intended to be a substitute for a firewall or to encourage anyone
- to defer addressing basic security weaknesses.
- </P
-><P
-> Multiple ACL lines are OK.
- If any ACLs are specified, <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> only talks
- to IP addresses that match at least one <TT
-CLASS="LITERAL"
->permit-access</TT
-> line
- and don't match any subsequent <TT
-CLASS="LITERAL"
->deny-access</TT
-> line. In other words, the
- last match wins, with the default being <TT
-CLASS="LITERAL"
->deny-access</TT
->.
- </P
-><P
-> If <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> is using a forwarder (see <TT
-CLASS="LITERAL"
->forward</TT
-> below)
- for a particular destination URL, the <TT
-CLASS="REPLACEABLE"
-><I
->dst_addr</I
-></TT
->
- that is examined is the address of the forwarder and <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->NOT</I
-></SPAN
-> the address
- of the ultimate target. This is necessary because it may be impossible for the local
- <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> to determine the IP address of the
- ultimate target (that's often what gateways are used for).
- </P
-><P
-> You should prefer using IP addresses over DNS names, because the address lookups take
- time. All DNS names must resolve! You can <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->not</I
-></SPAN
-> use domain patterns
- like <SPAN
-CLASS="QUOTE"
->"*.org"</SPAN
-> or partial domain names. If a DNS name resolves to multiple
- IP addresses, only the first one is used.
- </P
-><P
-> 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
- (most sites are).
- </P
-></DD
-><DT
->Examples:</DT
-><DD
-><P
-> Explicitly define the default behavior if no ACL and
- <TT
-CLASS="LITERAL"
->listen-address</TT
-> are set: <SPAN
-CLASS="QUOTE"
->"localhost"</SPAN
->
- is OK. The absence of a <TT
-CLASS="REPLACEABLE"
-><I
->dst_addr</I
-></TT
-> implies that
- <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->all</I
-></SPAN
-> destination addresses are OK:
- </P
-><P
-> <TABLE
-BORDER="0"
-BGCOLOR="#E0E0E0"
-WIDTH="90%"
-><TR
-><TD
-><PRE
-CLASS="SCREEN"
-> permit-access localhost</PRE
-></TD
-></TR
-></TABLE
->
- </P
-><P
-> Allow any host on the same class C subnet as www.privoxy.org access to
- nothing but www.example.com (or other domains hosted on the same system):
- </P
-><P
-> <TABLE
-BORDER="0"
-BGCOLOR="#E0E0E0"
-WIDTH="90%"
-><TR
-><TD
-><PRE
-CLASS="SCREEN"
-> permit-access www.privoxy.org/24 www.example.com/32</PRE
-></TD
-></TR
-></TABLE
->
- </P
-><P
-> 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 the IP address behind
- www.dirty-stuff.example.com:
- </P
-><P
-> <TABLE
-BORDER="0"
-BGCOLOR="#E0E0E0"
-WIDTH="90%"
-><TR
-><TD
-><PRE
-CLASS="SCREEN"
-> permit-access 192.168.45.64/26
- deny-access 192.168.45.73 www.dirty-stuff.example.com</PRE
-></TD
-></TR
-></TABLE
->
- </P
-></DD
-></DL
-></DIV
-></DIV
-><DIV
-CLASS="SECT3"
-><H4
-CLASS="SECT3"
-><A
-NAME="BUFFER-LIMIT"
->7.4.8. buffer-limit</A
-></H4
-><P
-></P
-><DIV
-CLASS="VARIABLELIST"
-><DL
-><DT
->Specifies:</DT
-><DD
-><P
-> Maximum size of the buffer for content filtering.
- </P
-></DD
-><DT
->Type of value:</DT
-><DD
-><P
->Size in Kbytes</P
-></DD
-><DT
->Default value:</DT
-><DD
-><P
->4096</P
-></DD
-><DT
->Effect if unset:</DT
-><DD
-><P
-> Use a 4MB (4096 KB) limit.
- </P
-></DD
-><DT
->Notes:</DT
-><DD
-><P
-> For content filtering, i.e. the <TT
-CLASS="LITERAL"
->+filter</TT
-> and
- <TT
-CLASS="LITERAL"
->+deanimate-gif</TT
-> actions, it is necessary that
- <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> 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.
- </P
-><P
-> When a document buffer size reaches the <TT
-CLASS="LITERAL"
->buffer-limit</TT
->, 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 <TT
-CLASS="LITERAL"
->buffer-limit</TT
-> Kbytes
- <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->each</I
-></SPAN
->, unless you have enabled <SPAN
-CLASS="QUOTE"
->"single-threaded"</SPAN
->
- above.
- </P
-></DD
-></DL
-></DIV
-></DIV
-></DIV
-><DIV
-CLASS="SECT2"
-><H2
-CLASS="SECT2"
-><A
-NAME="FORWARDING"
->7.5. Forwarding</A
-></H2
-><P
-> This feature allows routing of HTTP requests through a chain of
- multiple proxies.</P
-><P
-> Forwarding can be used to chain Privoxy with a caching proxy to speed
- up browsing. Using a parent proxy may also be necessary if the machine
- that <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> runs on has no direct Internet access.</P
-><P
-> Note that parent proxies can severely decrease your privacy level.
- For example a parent proxy could add your IP address to the request
- headers and if it's a caching proxy it may add the <SPAN
-CLASS="QUOTE"
->"Etag"</SPAN
->
- header to revalidation requests again, even though you configured Privoxy
- to remove it. It may also ignore Privoxy's header time randomization and use the
- original values which could be used by the server as cookie replacement
- to track your steps between visits.</P
-><P
-> Also specified here are SOCKS proxies. <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
->
- supports the SOCKS 4 and SOCKS 4A protocols.</P
-><DIV
-CLASS="SECT3"
-><H4
-CLASS="SECT3"
-><A
-NAME="FORWARD"
->7.5.1. forward</A
-></H4
-><P
-></P
-><DIV
-CLASS="VARIABLELIST"
-><DL
-><DT
->Specifies:</DT
-><DD
-><P
-> To which parent HTTP proxy specific requests should be routed.
- </P
-></DD
-><DT
->Type of value:</DT
-><DD
-><P
-> <TT
-CLASS="REPLACEABLE"
-><I
->target_pattern</I
-></TT
->
- <TT
-CLASS="REPLACEABLE"
-><I
->http_parent</I
-></TT
->[:<TT
-CLASS="REPLACEABLE"
-><I
->port</I
-></TT
->]
- </P
-><P
-> where <TT
-CLASS="REPLACEABLE"
-><I
->target_pattern</I
-></TT
-> is a <A
-HREF="actions-file.html#AF-PATTERNS"
->URL pattern</A
->
- that specifies to which requests (i.e. URLs) this forward rule shall apply. Use <TT
-CLASS="LITERAL"
->/</TT
-> to
- denote <SPAN
-CLASS="QUOTE"
->"all URLs"</SPAN
->.
- <TT
-CLASS="REPLACEABLE"
-><I
->http_parent</I
-></TT
->[:<TT
-CLASS="REPLACEABLE"
-><I
->port</I
-></TT
->]
- is the DNS name or IP address of the parent HTTP proxy through which the requests should be forwarded,
- optionally followed by its listening port (default: 8080).
- Use a single dot (<TT
-CLASS="LITERAL"
->.</TT
->) to denote <SPAN
-CLASS="QUOTE"
->"no forwarding"</SPAN
->.
- </P
-></DD
-><DT
->Default value:</DT
-><DD
-><P
-><SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->Unset</I
-></SPAN
-></P
-></DD
-><DT
->Effect if unset:</DT
-><DD
-><P
-> Don't use parent HTTP proxies.
- </P
-></DD
-><DT
->Notes:</DT
-><DD
-><P
-> If <TT
-CLASS="REPLACEABLE"
-><I
->http_parent</I
-></TT
-> is <SPAN
-CLASS="QUOTE"
->"."</SPAN
->, then requests are not
- forwarded to another HTTP proxy but are made directly to the web servers.
- </P
-><P
-> Multiple lines are OK, they are checked in sequence, and the last match wins.
- </P
-></DD
-><DT
->Examples:</DT
-><DD
-><P
-> Everything goes to an example parent proxy, except SSL on port 443 (which it doesn't handle):
- </P
-><P
-> <TABLE
-BORDER="0"
-BGCOLOR="#E0E0E0"
-WIDTH="90%"
-><TR
-><TD
-><PRE
-CLASS="SCREEN"
-> forward / parent-proxy.example.org:8080
- forward :443 .</PRE
-></TD
-></TR
-></TABLE
->
- </P
-><P
-> Everything goes to our example ISP's caching proxy, except for requests
- to that ISP's sites:
- </P
-><P
-> <TABLE
-BORDER="0"
-BGCOLOR="#E0E0E0"
-WIDTH="90%"
-><TR
-><TD
-><PRE
-CLASS="SCREEN"
-> forward / caching-proxy.isp.example.net:8000
- forward .isp.example.net .</PRE
-></TD
-></TR
-></TABLE
->
- </P
-></DD
-></DL
-></DIV
-></DIV
-><DIV
-CLASS="SECT3"
-><H4
-CLASS="SECT3"
-><A
-NAME="SOCKS"
->7.5.2. forward-socks4, forward-socks4a and forward-socks5</A
-></H4
-><A
-NAME="FORWARD-SOCKS4"
-></A
-><A
-NAME="FORWARD-SOCKS4A"
-></A
-><P
-></P
-><DIV
-CLASS="VARIABLELIST"
-><DL
-><DT
->Specifies:</DT
-><DD
-><P
-> Through which SOCKS proxy (and optionally to which parent HTTP proxy) specific requests should be routed.
- </P
-></DD
-><DT
->Type of value:</DT
-><DD
-><P
-> <TT
-CLASS="REPLACEABLE"
-><I
->target_pattern</I
-></TT
->
- <TT
-CLASS="REPLACEABLE"
-><I
->socks_proxy</I
-></TT
->[:<TT
-CLASS="REPLACEABLE"
-><I
->port</I
-></TT
->]
- <TT
-CLASS="REPLACEABLE"
-><I
->http_parent</I
-></TT
->[:<TT
-CLASS="REPLACEABLE"
-><I
->port</I
-></TT
->]
- </P
-><P
-> where <TT
-CLASS="REPLACEABLE"
-><I
->target_pattern</I
-></TT
-> is a
- <A
-HREF="actions-file.html#AF-PATTERNS"
->URL pattern</A
-> that specifies to which
- requests (i.e. URLs) this forward rule shall apply. Use <TT
-CLASS="LITERAL"
->/</TT
-> to
- denote <SPAN
-CLASS="QUOTE"
->"all URLs"</SPAN
->. <TT
-CLASS="REPLACEABLE"
-><I
->http_parent</I
-></TT
->
- and <TT
-CLASS="REPLACEABLE"
-><I
->socks_proxy</I
-></TT
->
- are IP addresses in dotted decimal notation or valid DNS names
- (<TT
-CLASS="REPLACEABLE"
-><I
->http_parent</I
-></TT
->
- may be <SPAN
-CLASS="QUOTE"
->"."</SPAN
-> to denote <SPAN
-CLASS="QUOTE"
->"no HTTP forwarding"</SPAN
->), and the optional
- <TT
-CLASS="REPLACEABLE"
-><I
->port</I
-></TT
-> parameters are TCP ports,
- i.e. integer values from 1 to 65535
- </P
-></DD
-><DT
->Default value:</DT
-><DD
-><P
-><SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->Unset</I
-></SPAN
-></P
-></DD
-><DT
->Effect if unset:</DT
-><DD
-><P
-> Don't use SOCKS proxies.
- </P
-></DD
-><DT
->Notes:</DT
-><DD
-><P
-> Multiple lines are OK, they are checked in sequence, and the last match wins.
- </P
-><P
-> The difference between <TT
-CLASS="LITERAL"
->forward-socks4</TT
-> and <TT
-CLASS="LITERAL"
->forward-socks4a</TT
->
- 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.
- </P
-><P
-> With <TT
-CLASS="LITERAL"
->forward-socks5</TT
-> the DNS resolution will happen on the remote server as well.
- </P
-><P
-> If <TT
-CLASS="REPLACEABLE"
-><I
->http_parent</I
-></TT
-> is <SPAN
-CLASS="QUOTE"
->"."</SPAN
->, then requests are not
- forwarded to another HTTP proxy but are made (HTTP-wise) directly to the web servers, albeit through
- a SOCKS proxy.
- </P
-></DD
-><DT
->Examples:</DT
-><DD
-><P
-> From the company example.com, direct connections are made to all
- <SPAN
-CLASS="QUOTE"
->"internal"</SPAN
-> domains, but everything outbound goes through
- their ISP's proxy by way of example.com's corporate SOCKS 4A gateway to
- the Internet.
- </P
-><P
-> <TABLE
-BORDER="0"
-BGCOLOR="#E0E0E0"
-WIDTH="90%"
-><TR
-><TD
-><PRE
-CLASS="SCREEN"
-> forward-socks4a / socks-gw.example.com:1080 www-cache.isp.example.net:8080
- forward .example.com .</PRE
-></TD
-></TR
-></TABLE
->
- </P
-><P
-> A rule that uses a SOCKS 4 gateway for all destinations but no HTTP parent looks like this:
- </P
-><P
-> <TABLE
-BORDER="0"
-BGCOLOR="#E0E0E0"
-WIDTH="90%"
-><TR
-><TD
-><PRE
-CLASS="SCREEN"
-> forward-socks4 / socks-gw.example.com:1080 .</PRE
-></TD
-></TR
-></TABLE
->
- </P
-><P
-> To chain Privoxy and Tor, both running on the same system, you would use
- something like:
- </P
-><P
-> <TABLE
-BORDER="0"
-BGCOLOR="#E0E0E0"
-WIDTH="90%"
-><TR
-><TD
-><PRE
-CLASS="SCREEN"
-> forward-socks4a / 127.0.0.1:9050 .</PRE
-></TD
-></TR
-></TABLE
->
- </P
-><P
-> The public <SPAN
-CLASS="APPLICATION"
->Tor</SPAN
-> network can't be used to
- reach your local network, if you need to access local servers you
- therefore might want to make some exceptions:
- </P
-><P
-> <TABLE
-BORDER="0"
-BGCOLOR="#E0E0E0"
-WIDTH="90%"
-><TR
-><TD
-><PRE
-CLASS="SCREEN"
-> forward 192.168.*.*/ .
- forward 10.*.*.*/ .
- forward 127.*.*.*/ .</PRE
-></TD
-></TR
-></TABLE
->
- </P
-><P
-> Unencrypted connections to systems in these address ranges will
- be as (un)secure as the local network is, but the alternative is that you
- can't reach the local network through <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
->
- at all. Of course this may actually be desired and there is no reason
- to make these exceptions if you aren't sure you need them.
- </P
-><P
-> If you also want to be able to reach servers in your local network by
- using their names, you will need additional exceptions that look like
- this:
- </P
-><P
-> <TABLE
-BORDER="0"
-BGCOLOR="#E0E0E0"
-WIDTH="90%"
-><TR
-><TD
-><PRE
-CLASS="SCREEN"
-> forward localhost/ .</PRE
-></TD
-></TR
-></TABLE
->
- </P
-></DD
-></DL
-></DIV
-></DIV
-><DIV
-CLASS="SECT3"
-><H4
-CLASS="SECT3"
-><A
-NAME="ADVANCED-FORWARDING-EXAMPLES"
->7.5.3. Advanced Forwarding Examples</A
-></H4
-><P
-> If you have links to multiple ISPs that provide various special content
- only to their subscribers, you can configure multiple <SPAN
-CLASS="APPLICATION"
->Privoxies</SPAN
->
- which have connections to the respective ISPs to act as forwarders to each other, so that
- <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->your</I
-></SPAN
-> users can see the internal content of all ISPs.</P
-><P
-> Assume that host-a has a PPP connection to isp-a.example.net. And host-b has a PPP connection to
- isp-b.example.org. Both run <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
->. Their forwarding
- configuration can look like this:</P
-><P
-> host-a:</P
-><P
-> <TABLE
-BORDER="0"
-BGCOLOR="#E0E0E0"
-WIDTH="100%"
-><TR
-><TD
-><PRE
-CLASS="SCREEN"
-> forward / .
- forward .isp-b.example.net host-b:8118</PRE
-></TD
-></TR
-></TABLE
-></P
-><P
-> host-b:</P
-><P
-> <TABLE
-BORDER="0"
-BGCOLOR="#E0E0E0"
-WIDTH="100%"
-><TR
-><TD
-><PRE
-CLASS="SCREEN"
-> forward / .
- forward .isp-a.example.org host-a:8118</PRE
-></TD
-></TR
-></TABLE
-></P
-><P
-> Now, your users can set their browser's proxy to use either
- host-a or host-b and be able to browse the internal content
- of both isp-a and isp-b.</P
-><P
-> If you intend to chain <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> and
- <SPAN
-CLASS="APPLICATION"
->squid</SPAN
-> locally, then chaining as
- <TT
-CLASS="LITERAL"
->browser -> squid -> privoxy</TT
-> is the recommended way. </P
-><P
-> Assuming that <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> and <SPAN
-CLASS="APPLICATION"
->squid</SPAN
->
- run on the same box, your <SPAN
-CLASS="APPLICATION"
->squid</SPAN
-> configuration could then look like this:</P
-><P
-> <TABLE
-BORDER="0"
-BGCOLOR="#E0E0E0"
-WIDTH="100%"
-><TR
-><TD
-><PRE
-CLASS="SCREEN"
-> # Define Privoxy as parent proxy (without ICP)
- cache_peer 127.0.0.1 parent 8118 7 no-query
+ debug 8192 # Non-fatal errors
+ debug 32768 # log all data read from the network
+ debug 65536 # Log the applying actions</pre>
+ </td>
+ </tr>
+ </table>
+ <p>To select multiple debug levels, you can either add them or use multiple <tt class=
+ "LITERAL">debug</tt> lines.</p>
+ <p>A debug level of 1 is informative because it will show you each request as it happens. <span class=
+ "emphasis"><i class="EMPHASIS">1, 1024, 4096 and 8192 are recommended</i></span> 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).</p>
+ <p>If you are used to the more verbose settings, simply enable the debug lines below again.</p>
+ <p>If you want to use pure CLF (Common Log Format), you should set <span class="QUOTE">"debug 512"</span>
+ <span class="emphasis"><i class="EMPHASIS">ONLY</i></span> and not enable anything else.</p>
+ <p><span class="APPLICATION">Privoxy</span> has a hard-coded limit for the length of log messages. If
+ it's reached, messages are logged truncated and marked with <span class="QUOTE">"... [too long,
+ truncated]"</span>.</p>
+ <p>Please don't file any support requests without trying to reproduce the problem with increased debug
+ level first. Once you read the log messages, you may even be able to solve the problem on your own.</p>
+ </dd>
+ </dl>
+ </div>
+ </div>
+ <div class="SECT3">
+ <h4 class="SECT3"><a name="SINGLE-THREADED" id="SINGLE-THREADED">7.3.2. single-threaded</a></h4>
+ <div class="VARIABLELIST">
+ <dl>
+ <dt>Specifies:</dt>
+ <dd>
+ <p>Whether to run only one server thread.</p>
+ </dd>
+ <dt>Type of value:</dt>
+ <dd>
+ <p><span class="emphasis"><i class="EMPHASIS">1 or 0</i></span></p>
+ </dd>
+ <dt>Default value:</dt>
+ <dd>
+ <p><span class="emphasis"><i class="EMPHASIS">0</i></span></p>
+ </dd>
+ <dt>Effect if unset:</dt>
+ <dd>
+ <p>Multi-threaded (or, where unavailable: forked) operation, i.e. the ability to serve multiple requests
+ simultaneously.</p>
+ </dd>
+ <dt>Notes:</dt>
+ <dd>
+ <p>This option is only there for debugging purposes. <span class="emphasis"><i class="EMPHASIS">It will
+ drastically reduce performance.</i></span></p>
+ </dd>
+ </dl>
+ </div>
+ </div>
+ <div class="SECT3">
+ <h4 class="SECT3"><a name="HOSTNAME" id="HOSTNAME">7.3.3. hostname</a></h4>
+ <div class="VARIABLELIST">
+ <dl>
+ <dt>Specifies:</dt>
+ <dd>
+ <p>The hostname shown on the CGI pages.</p>
+ </dd>
+ <dt>Type of value:</dt>
+ <dd>
+ <p>Text</p>
+ </dd>
+ <dt>Default value:</dt>
+ <dd>
+ <p><span class="emphasis"><i class="EMPHASIS">Unset</i></span></p>
+ </dd>
+ <dt>Effect if unset:</dt>
+ <dd>
+ <p>The hostname provided by the operating system is used.</p>
+ </dd>
+ <dt>Notes:</dt>
+ <dd>
+ <p>On some misconfigured systems resolving the hostname fails or takes too much time and slows Privoxy
+ down. Setting a fixed hostname works around the problem.</p>
+ <p>In other circumstances it might be desirable to show a hostname other than the one returned by the
+ operating system. For example if the system has several different hostnames and you don't want to use the
+ first one.</p>
+ <p>Note that Privoxy does not validate the specified hostname value.</p>
+ </dd>
+ </dl>
+ </div>
+ </div>
+ </div>
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="ACCESS-CONTROL" id="ACCESS-CONTROL">7.4. Access Control and Security</a></h2>
+ <p>This section of the config file controls the security-relevant aspects of <span class=
+ "APPLICATION">Privoxy</span>'s configuration.</p>
+ <div class="SECT3">
+ <h4 class="SECT3"><a name="LISTEN-ADDRESS" id="LISTEN-ADDRESS">7.4.1. listen-address</a></h4>
+ <div class="VARIABLELIST">
+ <dl>
+ <dt>Specifies:</dt>
+ <dd>
+ <p>The address and TCP port on which <span class="APPLICATION">Privoxy</span> will listen for client
+ requests.</p>
+ </dd>
+ <dt>Type of value:</dt>
+ <dd>
+ <p>[<tt class="REPLACEABLE"><i>IP-Address</i></tt>]:<tt class="REPLACEABLE"><i>Port</i></tt></p>
+ <p>[<tt class="REPLACEABLE"><i>Hostname</i></tt>]:<tt class="REPLACEABLE"><i>Port</i></tt></p>
+ </dd>
+ <dt>Default value:</dt>
+ <dd>
+ <p>127.0.0.1:8118</p>
+ </dd>
+ <dt>Effect if unset:</dt>
+ <dd>
+ <p>Bind to 127.0.0.1 (IPv4 localhost), port 8118. This is suitable and recommended for home users who run
+ <span class="APPLICATION">Privoxy</span> on the same machine as their browser.</p>
+ </dd>
+ <dt>Notes:</dt>
+ <dd>
+ <p>You will need to configure your browser(s) to this proxy address and port.</p>
+ <p>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.</p>
+ <p>You can use this statement multiple times to make <span class="APPLICATION">Privoxy</span> listen on
+ more ports or more <abbr class="ABBREV">IP</abbr> addresses. Suitable if your operating system does not
+ support sharing <abbr class="ABBREV">IPv6</abbr> and <abbr class="ABBREV">IPv4</abbr> protocols on the
+ same socket.</p>
+ <p>If a hostname is used instead of an IP address, <span class="APPLICATION">Privoxy</span> will try to
+ resolve it to an IP address and if there are multiple, use the first one returned.</p>
+ <p>If the address for the hostname isn't already known on the system (for example because it's in
+ /etc/hostname), this may result in DNS traffic.</p>
+ <p>If the specified address isn't available on the system, or if the hostname can't be resolved,
+ <span class="APPLICATION">Privoxy</span> will fail to start.</p>
+ <p>IPv6 addresses containing colons have to be quoted by brackets. They can only be used if <span class=
+ "APPLICATION">Privoxy</span> has been compiled with IPv6 support. If you aren't sure if your version
+ supports it, have a look at <tt class="LITERAL">http://config.privoxy.org/show-status</tt>.</p>
+ <p>Some operating systems will prefer IPv6 to IPv4 addresses even if the system has no IPv6 connectivity
+ which is usually not expected by the user. Some even rely on DNS to resolve localhost which mean the
+ "localhost" address used may not actually be local.</p>
+ <p>It is therefore recommended to explicitly configure the intended IP address instead of relying on the
+ operating system, unless there's a strong reason not to.</p>
+ <p>If you leave out the address, <span class="APPLICATION">Privoxy</span> will bind to all IPv4
+ interfaces (addresses) on your machine and may become reachable from the Internet and/or the local
+ network. Be aware that some GNU/Linux distributions modify that behaviour without updating the
+ documentation. Check for non-standard patches if your <span class="APPLICATION">Privoxy</span> version
+ behaves differently.</p>
+ <p>If you configure <span class="APPLICATION">Privoxy</span> to be reachable from the network, consider
+ using <a href="config.html#ACLS">access control lists</a> (ACL's, see below), and/or a firewall.</p>
+ <p>If you open <span class="APPLICATION">Privoxy</span> to untrusted users, you will also want to make
+ sure that the following actions are disabled: <tt class="LITERAL"><a href=
+ "config.html#ENABLE-EDIT-ACTIONS">enable-edit-actions</a></tt> and <tt class="LITERAL"><a href=
+ "config.html#ENABLE-REMOTE-TOGGLE">enable-remote-toggle</a></tt></p>
+ </dd>
+ <dt>Example:</dt>
+ <dd>
+ <p>Suppose you are running <span class="APPLICATION">Privoxy</span> 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:</p>
+ <table border="0" bgcolor="#E0E0E0" width="90%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING"> listen-address 192.168.0.1:8118</pre>
+ </td>
+ </tr>
+ </table>
+ <p>Suppose you are running <span class="APPLICATION">Privoxy</span> on an IPv6-capable machine and you
+ want it to listen on the IPv6 address of the loopback device:</p>
+ <table border="0" bgcolor="#E0E0E0" width="90%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING"> listen-address [::1]:8118</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
+ </div>
+ </div>
+ <div class="SECT3">
+ <h4 class="SECT3"><a name="TOGGLE" id="TOGGLE">7.4.2. toggle</a></h4>
+ <div class="VARIABLELIST">
+ <dl>
+ <dt>Specifies:</dt>
+ <dd>
+ <p>Initial state of "toggle" status</p>
+ </dd>
+ <dt>Type of value:</dt>
+ <dd>
+ <p>1 or 0</p>
+ </dd>
+ <dt>Default value:</dt>
+ <dd>
+ <p>1</p>
+ </dd>
+ <dt>Effect if unset:</dt>
+ <dd>
+ <p>Act as if toggled on</p>
+ </dd>
+ <dt>Notes:</dt>
+ <dd>
+ <p>If set to 0, <span class="APPLICATION">Privoxy</span> will start in <span class="QUOTE">"toggled
+ off"</span> mode, i.e. mostly behave like a normal, content-neutral proxy with both ad blocking and
+ content filtering disabled. See <tt class="LITERAL">enable-remote-toggle</tt> below.</p>
+ </dd>
+ </dl>
+ </div>
+ </div>
+ <div class="SECT3">
+ <h4 class="SECT3"><a name="ENABLE-REMOTE-TOGGLE" id="ENABLE-REMOTE-TOGGLE">7.4.3. enable-remote-toggle</a></h4>
+ <div class="VARIABLELIST">
+ <dl>
+ <dt>Specifies:</dt>
+ <dd>
+ <p>Whether or not the <a href="http://config.privoxy.org/toggle" target="_top">web-based toggle
+ feature</a> may be used</p>
+ </dd>
+ <dt>Type of value:</dt>
+ <dd>
+ <p>0 or 1</p>
+ </dd>
+ <dt>Default value:</dt>
+ <dd>
+ <p>0</p>
+ </dd>
+ <dt>Effect if unset:</dt>
+ <dd>
+ <p>The web-based toggle feature is disabled.</p>
+ </dd>
+ <dt>Notes:</dt>
+ <dd>
+ <p>When toggled off, <span class="APPLICATION">Privoxy</span> mostly acts like a normal, content-neutral
+ proxy, i.e. doesn't block ads or filter content.</p>
+ <p>Access to the toggle feature can <span class="emphasis"><i class="EMPHASIS">not</i></span> be
+ controlled separately by <span class="QUOTE">"ACLs"</span> or HTTP authentication, so that everybody who
+ can access <span class="APPLICATION">Privoxy</span> (see <span class="QUOTE">"ACLs"</span> and <tt class=
+ "LITERAL">listen-address</tt> above) can toggle it for all users. So this option is <span class=
+ "emphasis"><i class="EMPHASIS">not recommended</i></span> for multi-user environments with untrusted
+ users.</p>
+ <p>Note that malicious client side code (e.g Java) is also capable of using this option.</p>
+ <p>As a lot of <span class="APPLICATION">Privoxy</span> users don't read documentation, this feature is
+ disabled by default.</p>
+ <p>Note that you must have compiled <span class="APPLICATION">Privoxy</span> with support for this
+ feature, otherwise this option has no effect.</p>
+ </dd>
+ </dl>
+ </div>
+ </div>
+ <div class="SECT3">
+ <h4 class="SECT3"><a name="ENABLE-REMOTE-HTTP-TOGGLE" id="ENABLE-REMOTE-HTTP-TOGGLE">7.4.4.
+ enable-remote-http-toggle</a></h4>
+ <div class="VARIABLELIST">
+ <dl>
+ <dt>Specifies:</dt>
+ <dd>
+ <p>Whether or not Privoxy recognizes special HTTP headers to change its behaviour.</p>
+ </dd>
+ <dt>Type of value:</dt>
+ <dd>
+ <p>0 or 1</p>
+ </dd>
+ <dt>Default value:</dt>
+ <dd>
+ <p>0</p>
+ </dd>
+ <dt>Effect if unset:</dt>
+ <dd>
+ <p>Privoxy ignores special HTTP headers.</p>
+ </dd>
+ <dt>Notes:</dt>
+ <dd>
+ <p>When toggled on, the client can change <span class="APPLICATION">Privoxy's</span> behaviour by setting
+ special HTTP headers. Currently the only supported special header is <span class="QUOTE">"X-Filter:
+ No"</span>, to disable filtering for the ongoing request, even if it is enabled in one of the action
+ files.</p>
+ <p>This feature is disabled by default. If you are using <span class="APPLICATION">Privoxy</span> in a
+ environment with trusted clients, you may enable this feature at your discretion. Note that malicious
+ client side code (e.g Java) is also capable of using this feature.</p>
+ <p>This option will be removed in future releases as it has been obsoleted by the more general header
+ taggers.</p>
+ </dd>
+ </dl>
+ </div>
+ </div>
+ <div class="SECT3">
+ <h4 class="SECT3"><a name="ENABLE-EDIT-ACTIONS" id="ENABLE-EDIT-ACTIONS">7.4.5. enable-edit-actions</a></h4>
+ <div class="VARIABLELIST">
+ <dl>
+ <dt>Specifies:</dt>
+ <dd>
+ <p>Whether or not the <a href="http://config.privoxy.org/show-status" target="_top">web-based actions
+ file editor</a> may be used</p>
+ </dd>
+ <dt>Type of value:</dt>
+ <dd>
+ <p>0 or 1</p>
+ </dd>
+ <dt>Default value:</dt>
+ <dd>
+ <p>0</p>
+ </dd>
+ <dt>Effect if unset:</dt>
+ <dd>
+ <p>The web-based actions file editor is disabled.</p>
+ </dd>
+ <dt>Notes:</dt>
+ <dd>
+ <p>Access to the editor can <span class="emphasis"><i class="EMPHASIS">not</i></span> be controlled
+ separately by <span class="QUOTE">"ACLs"</span> or HTTP authentication, so that everybody who can access
+ <span class="APPLICATION">Privoxy</span> (see <span class="QUOTE">"ACLs"</span> and <tt class=
+ "LITERAL">listen-address</tt> above) can modify its configuration for all users.</p>
+ <p>This option is <span class="emphasis"><i class="EMPHASIS">not recommended</i></span> for environments
+ with untrusted users and as a lot of <span class="APPLICATION">Privoxy</span> users don't read
+ documentation, this feature is disabled by default.</p>
+ <p>Note that malicious client side code (e.g Java) is also capable of using the actions editor and you
+ shouldn't enable this options unless you understand the consequences and are sure your browser is
+ configured correctly.</p>
+ <p>Note that you must have compiled <span class="APPLICATION">Privoxy</span> with support for this
+ feature, otherwise this option has no effect.</p>
+ </dd>
+ </dl>
+ </div>
+ </div>
+ <div class="SECT3">
+ <h4 class="SECT3"><a name="ENFORCE-BLOCKS" id="ENFORCE-BLOCKS">7.4.6. enforce-blocks</a></h4>
+ <div class="VARIABLELIST">
+ <dl>
+ <dt>Specifies:</dt>
+ <dd>
+ <p>Whether the user is allowed to ignore blocks and can <span class="QUOTE">"go there anyway"</span>.</p>
+ </dd>
+ <dt>Type of value:</dt>
+ <dd>
+ <p><tt class="REPLACEABLE"><i>0 or 1</i></tt></p>
+ </dd>
+ <dt>Default value:</dt>
+ <dd>
+ <p><span class="emphasis"><i class="EMPHASIS">0</i></span></p>
+ </dd>
+ <dt>Effect if unset:</dt>
+ <dd>
+ <p>Blocks are not enforced.</p>
+ </dd>
+ <dt>Notes:</dt>
+ <dd>
+ <p><span class="APPLICATION">Privoxy</span> is mainly used to block and filter requests as a service to
+ the user, for example to block ads and other junk that clogs the pipes. <span class=
+ "APPLICATION">Privoxy's</span> configuration isn't perfect and sometimes innocent pages are blocked. In
+ this situation it makes sense to allow the user to enforce the request and have <span class=
+ "APPLICATION">Privoxy</span> ignore the block.</p>
+ <p>In the default configuration <span class="APPLICATION">Privoxy's</span> <span class=
+ "QUOTE">"Blocked"</span> page contains a <span class="QUOTE">"go there anyway"</span> link to adds a
+ special string (the force prefix) to the request URL. If that link is used, <span class=
+ "APPLICATION">Privoxy</span> will detect the force prefix, remove it again and let the request pass.</p>
+ <p>Of course <span class="APPLICATION">Privoxy</span> can also be used to enforce a network policy. In
+ that case the user obviously should not be able to bypass any blocks, and that's what the <span class=
+ "QUOTE">"enforce-blocks"</span> option is for. If it's enabled, <span class="APPLICATION">Privoxy</span>
+ hides the <span class="QUOTE">"go there anyway"</span> link. If the user adds the force prefix by hand,
+ it will not be accepted and the circumvention attempt is logged.</p>
+ </dd>
+ <dt>Examples:</dt>
+ <dd>
+ <p>enforce-blocks 1</p>
+ </dd>
+ </dl>
+ </div>
+ </div>
+ <div class="SECT3">
+ <h4 class="SECT3"><a name="ACLS" id="ACLS">7.4.7. ACLs: permit-access and deny-access</a></h4><a name=
+ "PERMIT-ACCESS" id="PERMIT-ACCESS"></a><a name="DENY-ACCESS" id="DENY-ACCESS"></a>
+ <div class="VARIABLELIST">
+ <dl>
+ <dt>Specifies:</dt>
+ <dd>
+ <p>Who can access what.</p>
+ </dd>
+ <dt>Type of value:</dt>
+ <dd>
+ <p><tt class="REPLACEABLE"><i>src_addr</i></tt>[:<tt class="REPLACEABLE"><i>port</i></tt>][/<tt class=
+ "REPLACEABLE"><i>src_masklen</i></tt>] [<tt class="REPLACEABLE"><i>dst_addr</i></tt>[:<tt class=
+ "REPLACEABLE"><i>port</i></tt>][/<tt class="REPLACEABLE"><i>dst_masklen</i></tt>]]</p>
+ <p>Where <tt class="REPLACEABLE"><i>src_addr</i></tt> and <tt class="REPLACEABLE"><i>dst_addr</i></tt>
+ are IPv4 addresses in dotted decimal notation or valid DNS names, <tt class=
+ "REPLACEABLE"><i>port</i></tt> is a port number, and <tt class="REPLACEABLE"><i>src_masklen</i></tt> and
+ <tt class="REPLACEABLE"><i>dst_masklen</i></tt> 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.</p>
+ <p>If your system implements <a href="http://tools.ietf.org/html/rfc3493" target="_top">RFC 3493</a>,
+ then <tt class="REPLACEABLE"><i>src_addr</i></tt> and <tt class="REPLACEABLE"><i>dst_addr</i></tt> can be
+ IPv6 addresses delimeted by brackets, <tt class="REPLACEABLE"><i>port</i></tt> can be a number or a
+ service name, and <tt class="REPLACEABLE"><i>src_masklen</i></tt> and <tt class=
+ "REPLACEABLE"><i>dst_masklen</i></tt> can be a number from 0 to 128.</p>
+ </dd>
+ <dt>Default value:</dt>
+ <dd>
+ <p><span class="emphasis"><i class="EMPHASIS">Unset</i></span></p>
+ <p>If no <tt class="REPLACEABLE"><i>port</i></tt> is specified, any port will match. If no <tt class=
+ "REPLACEABLE"><i>src_masklen</i></tt> or <tt class="REPLACEABLE"><i>src_masklen</i></tt> is given, the
+ complete IP address has to match (i.e. 32 bits for IPv4 and 128 bits for IPv6).</p>
+ </dd>
+ <dt>Effect if unset:</dt>
+ <dd>
+ <p>Don't restrict access further than implied by <tt class="LITERAL">listen-address</tt></p>
+ </dd>
+ <dt>Notes:</dt>
+ <dd>
+ <p>Access controls are included at the request of ISPs and systems administrators, and <span class=
+ "emphasis"><i class="EMPHASIS">are not usually needed by individual users</i></span>. For a typical home
+ user, it will normally suffice to ensure that <span class="APPLICATION">Privoxy</span> only listens on
+ the localhost (127.0.0.1) or internal (home) network address by means of the <a href=
+ "config.html#LISTEN-ADDRESS"><span class="emphasis"><i class="EMPHASIS">listen-address</i></span></a>
+ option.</p>
+ <p>Please see the warnings in the FAQ that <span class="APPLICATION">Privoxy</span> is not intended to be
+ a substitute for a firewall or to encourage anyone to defer addressing basic security weaknesses.</p>
+ <p>Multiple ACL lines are OK. If any ACLs are specified, <span class="APPLICATION">Privoxy</span> only
+ talks to IP addresses that match at least one <tt class="LITERAL">permit-access</tt> line and don't match
+ any subsequent <tt class="LITERAL">deny-access</tt> line. In other words, the last match wins, with the
+ default being <tt class="LITERAL">deny-access</tt>.</p>
+ <p>If <span class="APPLICATION">Privoxy</span> is using a forwarder (see <tt class="LITERAL">forward</tt>
+ below) for a particular destination URL, the <tt class="REPLACEABLE"><i>dst_addr</i></tt> that is
+ examined is the address of the forwarder and <span class="emphasis"><i class="EMPHASIS">NOT</i></span>
+ the address of the ultimate target. This is necessary because it may be impossible for the local
+ <span class="APPLICATION">Privoxy</span> to determine the IP address of the ultimate target (that's often
+ what gateways are used for).</p>
+ <p>You should prefer using IP addresses over DNS names, because the address lookups take time. All DNS
+ names must resolve! You can <span class="emphasis"><i class="EMPHASIS">not</i></span> use domain patterns
+ like <span class="QUOTE">"*.org"</span> or partial domain names. If a DNS name resolves to multiple IP
+ addresses, only the first one is used.</p>
+ <p>Some systems allow IPv4 clients to connect to IPv6 server sockets. Then the client's IPv4 address will
+ be translated by the system into IPv6 address space with special prefix ::ffff:0:0/96 (so called IPv4
+ mapped IPv6 address). <span class="APPLICATION">Privoxy</span> can handle it and maps such ACL addresses
+ automatically.</p>
+ <p>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 (most sites are).</p>
+ </dd>
+ <dt>Examples:</dt>
+ <dd>
+ <p>Explicitly define the default behavior if no ACL and <tt class="LITERAL">listen-address</tt> are set:
+ <span class="QUOTE">"localhost"</span> is OK. The absence of a <tt class=
+ "REPLACEABLE"><i>dst_addr</i></tt> implies that <span class="emphasis"><i class="EMPHASIS">all</i></span>
+ destination addresses are OK:</p>
+ <table border="0" bgcolor="#E0E0E0" width="90%">
+ <tr>
+ <td>
+ <pre class="SCREEN"> permit-access localhost</pre>
+ </td>
+ </tr>
+ </table>
+ <p>Allow any host on the same class C subnet as www.privoxy.org access to nothing but www.example.com (or
+ other domains hosted on the same system):</p>
+ <table border="0" bgcolor="#E0E0E0" width="90%">
+ <tr>
+ <td>
+ <pre class="SCREEN"> permit-access www.privoxy.org/24 www.example.com/32</pre>
+ </td>
+ </tr>
+ </table>
+ <p>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 the IP address behind www.dirty-stuff.example.com:</p>
+ <table border="0" bgcolor="#E0E0E0" width="90%">
+ <tr>
+ <td>
+ <pre class="SCREEN"> permit-access 192.168.45.64/26
+ deny-access 192.168.45.73 www.dirty-stuff.example.com</pre>
+ </td>
+ </tr>
+ </table>
+ <p>Allow access from the IPv4 network 192.0.2.0/24 even if listening on an IPv6 wild card address (not
+ supported on all platforms):</p>
+ <table border="0" bgcolor="#E0E0E0" width="90%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING"> permit-access 192.0.2.0/24</pre>
+ </td>
+ </tr>
+ </table>
+ <p>This is equivalent to the following line even if listening on an IPv4 address (not supported on all
+ platforms):</p>
+ <table border="0" bgcolor="#E0E0E0" width="90%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING"> permit-access [::ffff:192.0.2.0]/120</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
+ </div>
+ </div>
+ <div class="SECT3">
+ <h4 class="SECT3"><a name="BUFFER-LIMIT" id="BUFFER-LIMIT">7.4.8. buffer-limit</a></h4>
+ <div class="VARIABLELIST">
+ <dl>
+ <dt>Specifies:</dt>
+ <dd>
+ <p>Maximum size of the buffer for content filtering.</p>
+ </dd>
+ <dt>Type of value:</dt>
+ <dd>
+ <p>Size in Kbytes</p>
+ </dd>
+ <dt>Default value:</dt>
+ <dd>
+ <p>4096</p>
+ </dd>
+ <dt>Effect if unset:</dt>
+ <dd>
+ <p>Use a 4MB (4096 KB) limit.</p>
+ </dd>
+ <dt>Notes:</dt>
+ <dd>
+ <p>For content filtering, i.e. the <tt class="LITERAL">+filter</tt> and <tt class=
+ "LITERAL">+deanimate-gif</tt> actions, it is necessary that <span class="APPLICATION">Privoxy</span>
+ 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.</p>
+ <p>When a document buffer size reaches the <tt class="LITERAL">buffer-limit</tt>, 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 <tt class="LITERAL">buffer-limit</tt> Kbytes
+ <span class="emphasis"><i class="EMPHASIS">each</i></span>, unless you have enabled <span class=
+ "QUOTE">"single-threaded"</span> above.</p>
+ </dd>
+ </dl>
+ </div>
+ </div>
+ <div class="SECT3">
+ <h4 class="SECT3"><a name="ENABLE-PROXY-AUTHENTICATION-FORWARDING" id=
+ "ENABLE-PROXY-AUTHENTICATION-FORWARDING">7.4.9. enable-proxy-authentication-forwarding</a></h4>
+ <div class="VARIABLELIST">
+ <dl>
+ <dt>Specifies:</dt>
+ <dd>
+ <p>Whether or not proxy authentication through <span class="APPLICATION">Privoxy</span> should work.</p>
+ </dd>
+ <dt>Type of value:</dt>
+ <dd>
+ <p>0 or 1</p>
+ </dd>
+ <dt>Default value:</dt>
+ <dd>
+ <p>0</p>
+ </dd>
+ <dt>Effect if unset:</dt>
+ <dd>
+ <p>Proxy authentication headers are removed.</p>
+ </dd>
+ <dt>Notes:</dt>
+ <dd>
+ <p>Privoxy itself does not support proxy authentication, but can allow clients to authenticate against
+ Privoxy's parent proxy.</p>
+ <p>By default Privoxy (3.0.21 and later) don't do that and remove Proxy-Authorization headers in requests
+ and Proxy-Authenticate headers in responses to make it harder for malicious sites to trick inexperienced
+ users into providing login information.</p>
+ <p>If this option is enabled the headers are forwarded.</p>
+ <p>Enabling this option is <span class="emphasis"><i class="EMPHASIS">not recommended</i></span> if there
+ is no parent proxy that requires authentication or if the local network between Privoxy and the parent
+ proxy isn't trustworthy. If proxy authentication is only required for some requests, it is recommended to
+ use a client header filter to remove the authentication headers for requests where they aren't
+ needed.</p>
+ </dd>
+ </dl>
+ </div>
+ </div>
+ <div class="SECT3">
+ <h4 class="SECT3"><a name="TRUSTED-CGI-REFERER" id="TRUSTED-CGI-REFERER">7.4.10. trusted-cgi-referer</a></h4>
+ <div class="VARIABLELIST">
+ <dl>
+ <dt>Specifies:</dt>
+ <dd>
+ <p>A trusted website or webpage whose links can be followed to reach sensitive CGI pages</p>
+ </dd>
+ <dt>Type of value:</dt>
+ <dd>
+ <p>URL or URL prefix</p>
+ </dd>
+ <dt>Default value:</dt>
+ <dd>
+ <p>Unset</p>
+ </dd>
+ <dt>Effect if unset:</dt>
+ <dd>
+ <p>No external pages are considered trusted referers.</p>
+ </dd>
+ <dt>Notes:</dt>
+ <dd>
+ <p>Before <span class="APPLICATION">Privoxy</span> accepts configuration changes through CGI pages like
+ <a href="config.html#CLIENT-SPECIFIC-TAG">client-tags</a> or the <a href=
+ "config.html#ENABLE-REMOTE-TOGGLE">remote toggle</a>, it checks the Referer header to see if the request
+ comes from a trusted source.</p>
+ <p>By default only the webinterface domains <a href="http://config.privoxy.org/" target=
+ "_top">config.privoxy.org</a> and <a href="http://p.p/" target="_top">p.p</a> are considered trustworthy.
+ Requests originating from other domains are rejected to prevent third-parties from modifiying Privoxy's
+ state by e.g. embedding images that result in CGI requests.</p>
+ <p>In some environments it may be desirable to embed links to CGI pages on external pages, for example on
+ an Intranet homepage the Privoxy admin controls.</p>
+ <p>The <span class="QUOTE">"trusted-cgi-referer"</span> option can be used to add that page, or the whole
+ domain, as trusted source so the resulting requests aren't rejected. Requests are accepted if the
+ specified trusted-cgi-refer is the prefix of the Referer.</p>
+ <p>If the trusted source is supposed to access the CGI pages via JavaScript the <a href=
+ "config.html#CORS-ALLOWED-ORIGIN">cors-allowed-origin</a> option can be used.</p>
+ <div class="WARNING">
+ <table class="WARNING" border="1" width="90%">
+ <tr>
+ <td align="center"><b>Warning</b></td>
+ </tr>
+ <tr>
+ <td align="left">
+ <p>Declaring pages the admin doesn't control trustworthy may allow malicious third parties to
+ modify Privoxy's internal state against the user's wishes and without the user's knowledge.</p>
+ </td>
+ </tr>
+ </table>
+ </div>
+ </dd>
+ </dl>
+ </div>
+ </div>
+ <div class="SECT3">
+ <h4 class="SECT3"><a name="CORS-ALLOWED-ORIGIN" id="CORS-ALLOWED-ORIGIN">7.4.11. cors-allowed-origin</a></h4>
+ <div class="VARIABLELIST">
+ <dl>
+ <dt>Specifies:</dt>
+ <dd>
+ <p>A trusted website which can access <span class="APPLICATION">Privoxy</span>'s CGI pages through
+ JavaScript.</p>
+ </dd>
+ <dt>Type of value:</dt>
+ <dd>
+ <p>URL</p>
+ </dd>
+ <dt>Default value:</dt>
+ <dd>
+ <p>Unset</p>
+ </dd>
+ <dt>Effect if unset:</dt>
+ <dd>
+ <p>No external sites get access via cross-origin resource sharing.</p>
+ </dd>
+ <dt>Notes:</dt>
+ <dd>
+ <p>Modern browsers by default prevent cross-origin requests made via JavaScript to <span class=
+ "APPLICATION">Privoxy</span>'s CGI interface even if <span class="APPLICATION">Privoxy</span> would trust
+ the referer because it's white listed via the <a href=
+ "config.html#TRUSTED-CGI-REFERER">trusted-cgi-referer</a> directive.</p>
+ <p><a href="https://en.wikipedia.org/wiki/Cross-origin_resource_sharing" target="_top">Cross-origin
+ resource sharing (CORS)</a> is a mechanism to allow cross-origin requests.</p>
+ <p>The <span class="QUOTE">"cors-allowed-origin"</span> option can be used to specify a domain that is
+ allowed to make requests to Privoxy CGI interface via JavaScript. It is used in combination with the
+ <a href="config.html#TRUSTED-CGI-REFERER">trusted-cgi-referer</a> directive.</p>
+ <div class="WARNING">
+ <table class="WARNING" border="1" width="90%">
+ <tr>
+ <td align="center"><b>Warning</b></td>
+ </tr>
+ <tr>
+ <td align="left">
+ <p>Declaring domains the admin doesn't control trustworthy may allow malicious third parties to
+ modify Privoxy's internal state against the user's wishes and without the user's knowledge.</p>
+ </td>
+ </tr>
+ </table>
+ </div>
+ </dd>
+ </dl>
+ </div>
+ </div>
+ </div>
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="FORWARDING" id="FORWARDING">7.5. Forwarding</a></h2>
+ <p>This feature allows routing of HTTP requests through a chain of multiple proxies.</p>
+ <p>Forwarding can be used to chain Privoxy with a caching proxy to speed up browsing. Using a parent proxy may
+ also be necessary if the machine that <span class="APPLICATION">Privoxy</span> runs on has no direct Internet
+ access.</p>
+ <p>Note that parent proxies can severely decrease your privacy level. For example a parent proxy could add your
+ IP address to the request headers and if it's a caching proxy it may add the <span class="QUOTE">"Etag"</span>
+ header to revalidation requests again, even though you configured Privoxy to remove it. It may also ignore
+ Privoxy's header time randomization and use the original values which could be used by the server as cookie
+ replacement to track your steps between visits.</p>
+ <p>Also specified here are SOCKS proxies. <span class="APPLICATION">Privoxy</span> supports the SOCKS 4 and SOCKS
+ 4A protocols.</p>
+ <div class="SECT3">
+ <h4 class="SECT3"><a name="FORWARD" id="FORWARD">7.5.1. forward</a></h4>
+ <div class="VARIABLELIST">
+ <dl>
+ <dt>Specifies:</dt>
+ <dd>
+ <p>To which parent HTTP proxy specific requests should be routed.</p>
+ </dd>
+ <dt>Type of value:</dt>
+ <dd>
+ <p><tt class="REPLACEABLE"><i>target_pattern</i></tt> <tt class=
+ "REPLACEABLE"><i>http_parent</i></tt>[:<tt class="REPLACEABLE"><i>port</i></tt>]</p>
+ <p>where <tt class="REPLACEABLE"><i>target_pattern</i></tt> is a <a href=
+ "actions-file.html#AF-PATTERNS">URL pattern</a> that specifies to which requests (i.e. URLs) this forward
+ rule shall apply. Use <tt class="LITERAL">/</tt> to denote <span class="QUOTE">"all URLs"</span>.
+ <tt class="REPLACEABLE"><i>http_parent</i></tt>[:<tt class="REPLACEABLE"><i>port</i></tt>] is the DNS
+ name or IP address of the parent HTTP proxy through which the requests should be forwarded, optionally
+ followed by its listening port (default: 8000). Use a single dot (<tt class="LITERAL">.</tt>) to denote
+ <span class="QUOTE">"no forwarding"</span>.</p>
+ </dd>
+ <dt>Default value:</dt>
+ <dd>
+ <p><span class="emphasis"><i class="EMPHASIS">Unset</i></span></p>
+ </dd>
+ <dt>Effect if unset:</dt>
+ <dd>
+ <p>Don't use parent HTTP proxies.</p>
+ </dd>
+ <dt>Notes:</dt>
+ <dd>
+ <p>If <tt class="REPLACEABLE"><i>http_parent</i></tt> is <span class="QUOTE">"."</span>, then requests
+ are not forwarded to another HTTP proxy but are made directly to the web servers.</p>
+ <p><tt class="REPLACEABLE"><i>http_parent</i></tt> can be a numerical IPv6 address (if <a href=
+ "http://tools.ietf.org/html/rfc3493" target="_top">RFC 3493</a> is implemented). To prevent clashes with
+ the port delimiter, the whole IP address has to be put into brackets. On the other hand a <tt class=
+ "REPLACEABLE"><i>target_pattern</i></tt> containing an IPv6 address has to be put into angle brackets
+ (normal brackets are reserved for regular expressions already).</p>
+ <p>Multiple lines are OK, they are checked in sequence, and the last match wins.</p>
+ </dd>
+ <dt>Examples:</dt>
+ <dd>
+ <p>Everything goes to an example parent proxy, except SSL on port 443 (which it doesn't handle):</p>
+ <table border="0" bgcolor="#E0E0E0" width="90%">
+ <tr>
+ <td>
+ <pre class="SCREEN"> forward / parent-proxy.example.org:8080
+ forward :443 .</pre>
+ </td>
+ </tr>
+ </table>
+ <p>Everything goes to our example ISP's caching proxy, except for requests to that ISP's sites:</p>
+ <table border="0" bgcolor="#E0E0E0" width="90%">
+ <tr>
+ <td>
+ <pre class="SCREEN"> forward / caching-proxy.isp.example.net:8000
+ forward .isp.example.net .</pre>
+ </td>
+ </tr>
+ </table>
+ <p>Parent proxy specified by an IPv6 address:</p>
+ <table border="0" bgcolor="#E0E0E0" width="90%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING"> forward / [2001:DB8::1]:8000</pre>
+ </td>
+ </tr>
+ </table>
+ <p>Suppose your parent proxy doesn't support IPv6:</p>
+ <table border="0" bgcolor="#E0E0E0" width="90%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING"> forward / parent-proxy.example.org:8000
+ forward ipv6-server.example.org .
+ forward <[2-3][0-9a-f][0-9a-f][0-9a-f]:*> .</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
+ </div>
+ </div>
+ <div class="SECT3">
+ <h4 class="SECT3"><a name="SOCKS" id="SOCKS">7.5.2. forward-socks4, forward-socks4a, forward-socks5 and
+ forward-socks5t</a></h4><a name="FORWARD-SOCKS4" id="FORWARD-SOCKS4"></a><a name="FORWARD-SOCKS4A" id=
+ "FORWARD-SOCKS4A"></a>
+ <div class="VARIABLELIST">
+ <dl>
+ <dt>Specifies:</dt>
+ <dd>
+ <p>Through which SOCKS proxy (and optionally to which parent HTTP proxy) specific requests should be
+ routed.</p>
+ </dd>
+ <dt>Type of value:</dt>
+ <dd>
+ <p><tt class="REPLACEABLE"><i>target_pattern</i></tt> <tt class=
+ "REPLACEABLE"><i>socks_proxy</i></tt>[:<tt class="REPLACEABLE"><i>port</i></tt>] <tt class=
+ "REPLACEABLE"><i>http_parent</i></tt>[:<tt class="REPLACEABLE"><i>port</i></tt>]</p>
+ <p>where <tt class="REPLACEABLE"><i>target_pattern</i></tt> is a <a href=
+ "actions-file.html#AF-PATTERNS">URL pattern</a> that specifies to which requests (i.e. URLs) this forward
+ rule shall apply. Use <tt class="LITERAL">/</tt> to denote <span class="QUOTE">"all URLs"</span>.
+ <tt class="REPLACEABLE"><i>http_parent</i></tt> and <tt class="REPLACEABLE"><i>socks_proxy</i></tt> are
+ IP addresses in dotted decimal notation or valid DNS names (<tt class=
+ "REPLACEABLE"><i>http_parent</i></tt> may be <span class="QUOTE">"."</span> to denote <span class=
+ "QUOTE">"no HTTP forwarding"</span>), and the optional <tt class="REPLACEABLE"><i>port</i></tt>
+ parameters are TCP ports, i.e. integer values from 1 to 65535</p>
+ </dd>
+ <dt>Default value:</dt>
+ <dd>
+ <p><span class="emphasis"><i class="EMPHASIS">Unset</i></span></p>
+ </dd>
+ <dt>Effect if unset:</dt>
+ <dd>
+ <p>Don't use SOCKS proxies.</p>
+ </dd>
+ <dt>Notes:</dt>
+ <dd>
+ <p>Multiple lines are OK, they are checked in sequence, and the last match wins.</p>
+ <p>The difference between <tt class="LITERAL">forward-socks4</tt> and <tt class=
+ "LITERAL">forward-socks4a</tt> 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.</p>
+ <p>With <tt class="LITERAL">forward-socks5</tt> the DNS resolution will happen on the remote server as
+ well.</p>
+ <p><tt class="LITERAL">forward-socks5t</tt> works like vanilla <tt class="LITERAL">forward-socks5</tt>
+ but lets <span class="APPLICATION">Privoxy</span> additionally use Tor-specific SOCKS extensions.
+ Currently the only supported SOCKS extension is optimistic data which can reduce the latency for the
+ first request made on a newly created connection.</p>
+ <p><tt class="REPLACEABLE"><i>socks_proxy</i></tt> and <tt class="REPLACEABLE"><i>http_parent</i></tt>
+ can be a numerical IPv6 address (if <a href="http://tools.ietf.org/html/rfc3493" target="_top">RFC
+ 3493</a> is implemented). To prevent clashes with the port delimiter, the whole IP address has to be put
+ into brackets. On the other hand a <tt class="REPLACEABLE"><i>target_pattern</i></tt> containing an IPv6
+ address has to be put into angle brackets (normal brackets are reserved for regular expressions
+ already).</p>
+ <p>If <tt class="REPLACEABLE"><i>http_parent</i></tt> is <span class="QUOTE">"."</span>, then requests
+ are not forwarded to another HTTP proxy but are made (HTTP-wise) directly to the web servers, albeit
+ through a SOCKS proxy.</p>
+ </dd>
+ <dt>Examples:</dt>
+ <dd>
+ <p>From the company example.com, direct connections are made to all <span class="QUOTE">"internal"</span>
+ domains, but everything outbound goes through their ISP's proxy by way of example.com's corporate SOCKS
+ 4A gateway to the Internet.</p>
+ <table border="0" bgcolor="#E0E0E0" width="90%">
+ <tr>
+ <td>
+ <pre class="SCREEN">
+ forward-socks4a / socks-gw.example.com:1080 www-cache.isp.example.net:8080
+ forward .example.com .</pre>
+ </td>
+ </tr>
+ </table>
+ <p>A rule that uses a SOCKS 4 gateway for all destinations but no HTTP parent looks like this:</p>
+ <table border="0" bgcolor="#E0E0E0" width="90%">
+ <tr>
+ <td>
+ <pre class="SCREEN"> forward-socks4 / socks-gw.example.com:1080 .</pre>
+ </td>
+ </tr>
+ </table>
+ <p>To chain Privoxy and Tor, both running on the same system, you would use something like:</p>
+ <table border="0" bgcolor="#E0E0E0" width="90%">
+ <tr>
+ <td>
+ <pre class="SCREEN"> forward-socks5t / 127.0.0.1:9050 .</pre>
+ </td>
+ </tr>
+ </table>
+ <p>Note that if you got Tor through one of the bundles, you may have to change the port from 9050 to 9150
+ (or even another one). For details, please check the documentation on the <a href=
+ "https://torproject.org/" target="_top">Tor website</a>.</p>
+ <p>The public <span class="APPLICATION">Tor</span> network can't be used to reach your local network, if
+ you need to access local servers you therefore might want to make some exceptions:</p>
+ <table border="0" bgcolor="#E0E0E0" width="90%">
+ <tr>
+ <td>
+ <pre class="SCREEN"> forward 192.168.*.*/ .
+ forward 10.*.*.*/ .
+ forward 127.*.*.*/ .</pre>
+ </td>
+ </tr>
+ </table>
+ <p>Unencrypted connections to systems in these address ranges will be as (un)secure as the local network
+ is, but the alternative is that you can't reach the local network through <span class=
+ "APPLICATION">Privoxy</span> at all. Of course this may actually be desired and there is no reason to
+ make these exceptions if you aren't sure you need them.</p>
+ <p>If you also want to be able to reach servers in your local network by using their names, you will need
+ additional exceptions that look like this:</p>
+ <table border="0" bgcolor="#E0E0E0" width="90%">
+ <tr>
+ <td>
+ <pre class="SCREEN"> forward localhost/ .</pre>
+ </td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
+ </div>
+ </div>
+ <div class="SECT3">
+ <h4 class="SECT3"><a name="ADVANCED-FORWARDING-EXAMPLES" id="ADVANCED-FORWARDING-EXAMPLES">7.5.3. Advanced
+ Forwarding Examples</a></h4>
+ <p>If you have links to multiple ISPs that provide various special content only to their subscribers, you can
+ configure multiple <span class="APPLICATION">Privoxies</span> which have connections to the respective ISPs to
+ act as forwarders to each other, so that <span class="emphasis"><i class="EMPHASIS">your</i></span> users can
+ see the internal content of all ISPs.</p>
+ <p>Assume that host-a has a PPP connection to isp-a.example.net. And host-b has a PPP connection to
+ isp-b.example.org. Both run <span class="APPLICATION">Privoxy</span>. Their forwarding configuration can look
+ like this:</p>
+ <p>host-a:</p>
+ <table border="0" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="SCREEN"> forward / .
+ forward .isp-b.example.net host-b:8118</pre>
+ </td>
+ </tr>
+ </table>
+ <p>host-b:</p>
+ <table border="0" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="SCREEN"> forward / .
+ forward .isp-a.example.org host-a:8118</pre>
+ </td>
+ </tr>
+ </table>
+ <p>Now, your users can set their browser's proxy to use either host-a or host-b and be able to browse the
+ internal content of both isp-a and isp-b.</p>
+ <p>If you intend to chain <span class="APPLICATION">Privoxy</span> and <span class="APPLICATION">squid</span>
+ locally, then chaining as <tt class="LITERAL">browser -> squid -> privoxy</tt> is the recommended
+ way.</p>
+ <p>Assuming that <span class="APPLICATION">Privoxy</span> and <span class="APPLICATION">squid</span> run on the
+ same box, your <span class="APPLICATION">squid</span> configuration could then look like this:</p>
+ <table border="0" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="SCREEN"> # Define Privoxy as parent proxy (without ICP)
+ cache_peer 127.0.0.1 parent 8118 7 no-query