X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fwebserver%2Fuser-manual%2Fconfig.html;h=65d38bef5781347227a65ea13b99f52eae68ac34;hp=88e628f861badaaa85917bbb8835671b55abc62b;hb=5700aead3098beb0cc5a02bc0034a0d4194774a6;hpb=3ec6603d75254171971d369543469c44d681dcae diff --git a/doc/webserver/user-manual/config.html b/doc/webserver/user-manual/config.html index 88e628f8..65d38bef 100644 --- a/doc/webserver/user-manual/config.html +++ b/doc/webserver/user-manual/config.html @@ -7,7 +7,7 @@ NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.79"> +HREF="../p_doc.css">
Again, the main configuration file is named By default, the main configuration file is named config on - Linux/Unix/BSD and OS/2, and , + with the exception of Windows, where it is named config.txt on Windows. +>. Configuration lines consist of an initial keyword followed by a list of values, all separated by whitespace (any number of spaces or tabs). For example:
Privoxy's operation that are not location dependent (i.e. they apply universally, no matter - where you may be surfing).Two example URLs are provided
UnsetThe directory where all logging takes place - (i.e. where logfile and - jarfile are located). +> is located).
standard.action # Internal purposes, no editing recommended
match-all.action # Actions that are applied to all sites and maybe overruled later on.default.action # Main actions file
default.action # Main actions fileuser.action # User customizations
user.action # User customizations
- The default values include standard.action, which is used
- for internal purposes and should be loaded, default.action,
- which is the , which is the
+ "main" actions file maintained by the developers, and
@@ -1152,79 +1155,8 @@ CLASS="SECT3"
> The file to store intercepted cookies in
- File name, relative to logdir Unset (commented out). When activated: jarfile (Unix) or privoxy.jar (Windows). Intercepted cookies are not stored in a dedicated log file.
- The jarfile may grow to ridiculous sizes over time.
- If debug 8 (show header parsing) is enabled, cookies are
- also written to the logfile with the rest of the headers.
- Therefore this option isn't very useful and may be removed
- in future releases. Please report to the developers if you
- are still using it.
- The hostname shown on the CGI pages.
+ Text Unset The hostname provided by the operating system is used.
+ 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.
+ 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.
+ Note that Privoxy does not validate the specified hostname value.
+ The IP address and TCP port on which The address and TCP port on which Privoxy will
@@ -1653,6 +1655,18 @@ CLASS="REPLACEABLE"
>Port [Hostname]:Port Bind to 127.0.0.1 (localhost), port 8118. This is suitable and recommended for
- home users who run Bind to 127.0.0.1 (IPv4 localhost), port 8118. This is suitable and
+ recommended for home users who run Privoxy on the same machine as
- their browser.
+> on
+ the same machine as their browser.
If you leave out the IP address, You can use this statement multiple times to make
+ Privoxy will
- bind to all interfaces (addresses) on your machine and may become reachable
- from the Internet. In that case, consider using listen on more ports or more
+ IP addresses. Suitable if your operating system does not
+ support sharing IPv6 and IPv4 protocols
+ on the same socket.
+ If a hostname is used instead of an IP address, Privoxy
+ will try to resolve it to an IP address and if there are multiple, use the first
+ one returned.
+ 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.
+ If the specified address isn't available on the system, or if the
+ hostname can't be resolved, Privoxy
+ will fail to start.
+ IPv6 addresses containing colons have to be quoted by brackets.
+ They can only be used if Privoxy has
+ been compiled with IPv6 support. If you aren't sure if your version
+ supports it, have a look at
+ http://config.privoxy.org/show-status.
+ 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.
+ 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.
+ If you leave out the address, Privoxy 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 Privoxyversion behaves differently.
+ If you configure Privoxyto be reachable from the
+ network, consider using access control lists (ACL's, see below), and/or
- a firewall.
+>
+ (ACL's, see below), and/or a firewall.
If you open
With the exception noted above, listening on multiple addresses is currently
+ not supported by Privoxy directly.
+ It can be done on most operating systems by letting a packet filter
+ redirect request for certain addresses to Privoxy, though.
+ Suppose you are running Privoxy on an
+ IPv6-capable machine and you want it to listen on the IPv6 address
+ of the loopback device:
+ If your system implements
+ RFC 3493, then
+ src_addr and dst_addr can be IPv6 addresses delimeted by
+ brackets, port can be a number
+ or a service name, and
+ src_masklen and
+ dst_masklen can be a number
+ from 0 to 128.
+ Don't restrict access further than implied by listen-address
- Don't restrict access further than implied by listen-address
+ Access controls are included at the request of ISPs and systems
administrators, and 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). Privoxy can handle it
+ and maps such ACL addresses automatically.
+ 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).
@@ -2508,6 +2715,44 @@ CLASS="SCREEN"
>
+ 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):
+ This is equivalent to the following line even if listening on an
+ IPv4 address (not supported on all platforms):
+ http_parent can be a
+ numerical IPv6 address (if
+ RFC 3493 is
+ implemented). To prevent clashes with the port delimiter, the whole IP
+ address has to be put into brackets. On the other hand a target_pattern containing an IPv6 address
+ has to be put into angle brackets (normal brackets are reserved for
+ regular expressions already).
+ Multiple lines are OK, they are checked in sequence, and the last match wins.
Parent proxy specified by an IPv6 address:
+ Suppose your parent proxy doesn't support IPv6:
+ With forward-socks5 the DNS resolution will happen on the remote server as well.
+ socks_proxy and
+ http_parent can be a
+ numerical IPv6 address (if
+ RFC 3493 is
+ implemented). To prevent clashes with the port delimiter, the whole IP
+ address has to be put into brackets. On the other hand a target_pattern containing an IPv6 address
+ has to be put into angle brackets (normal brackets are reserved for
+ regular expressions already).
+ If Number of seconds after which an open connection will no longer be reused.
+ Time in seconds.
+ None Connections are not kept alive.
+ This option allows clients to keep the connection to Privoxy has a number of options specific to the
- Windows GUI interface: If "activity-animation" is set to 1, the
-
+ alive. If the server supports it, Privoxy icon will animate when
- "Privoxy" is active. To turn off, set to 0. activity-animation 1 If "log-messages" is set to 1,
- This option has no effect if Privoxy will log messages to the console
- window: log-messages 1 Several users have reported this as a Privoxy bug, so the
+ default value has been reduced. Consider increasing it to
+ 300 seconds or even more if you think your browser can handle
+ it. If your browser appears to be hanging it can't.
+ keep-alive-timeout 300
+ Assumed server-side keep-alive timeout if not specified by the server.
+ Time in seconds.
+ None Connections for which the server didn't specify the keep-alive
+ timeout are not reused.
+ Enabling this option significantly increases the number of connections
+ that are reused, provided the keep-alive-timeout option
+ is also enabled.
+ While it also increases the number of connections problems
+ when Privoxy tries to reuse a connection that already has
+ been closed on the server side, or is closed while Privoxy
+ is trying to reuse it, this should only be a problem if it
+ happens for the first request sent by the client. If it happens
+ for requests on reused client connections, Privoxy will simply
+ close the connection and the client is supposed to retry the
+ request without bothering the user.
+ Enabling this option is therefore only recommended if the
+ connection-sharing option
+ is disabled.
+ It is an error to specify a value larger than the keep-alive-timeout value.
+ This option has no effect if Privoxy
+ has been compiled without keep-alive support.
+ default-server-timeout 60
+ Whether or not outgoing connections that have been kept alive
+ should be shared between different incoming connections.
+ 0 or 1
+ None Connections are not shared.
+ This option has no effect if Privoxy
+ has been compiled without keep-alive support, or if it's disabled.
+ Note that reusing connections doesn't necessary cause speedups.
+ There are also a few privacy implications you should be aware of.
+ If this option is effective, outgoing connections are shared between
+ clients (if there are more than one) and closing the browser that initiated
+ the outgoing connection does no longer affect the connection between Privoxy
+ and the server unless the client's request hasn't been completed yet.
+ If the outgoing connection is idle, it will not be closed until either
+ Privoxy's or the server's timeout is reached.
+ While it's open, the server knows that the system running Privoxy is still
+ there.
+ If there are more than one client (maybe even belonging to multiple users),
+ they will be able to reuse each others connections. This is potentially
+ dangerous in case of authentication schemes like NTLM where only the
+ connection is authenticated, instead of requiring authentication for
+ each request.
+ If there is only a single client, and if said client can keep connections
+ alive on its own, enabling this option has next to no effect. If the client
+ doesn't support connection keep-alive, enabling this option may make sense
+ as it allows Privoxy to keep outgoing connections alive even if the client
+ itself doesn't support it.
+ You should also be aware that enabling this option increases the likelihood
+ of getting the "No server or forwarder data" error message, especially if you
+ are using a slow connection to the Internet.
+ This option should only be used by experienced users who
+ understand the risks and can weight them against the benefits.
+ connection-sharing 1
+ Number of seconds after which a socket times out if
+ no data is received.
+ Time in seconds.
+ None A default value of 300 seconds is used.
+ The default is quite high and you probably want to reduce it.
+ If you aren't using an occasionally slow proxy like Tor, reducing
+ it to a few seconds should be fine.
+ socket-timeout 300
+ Maximum number of client connections that will be served.
+ Positive number.
+ None Connections are served until a resource limit is reached.
+ Privoxy creates one thread (or process) for every incoming client
+ connection that isn't rejected based on the access control settings.
+ If the system is powerful enough, Privoxy can theoretically deal with
+ several hundred (or thousand) connections at the same time, but some
+ operating systems enforce resource limits by shutting down offending
+ processes and their default limits may be below the ones Privoxy would
+ require under heavy load.
+ Configuring Privoxy to enforce a connection limit below the thread
+ or process limit used by the operating system makes sure this doesn't
+ happen. Simply increasing the operating system's limit would work too,
+ but if Privoxy isn't the only application running on the system,
+ you may actually want to limit the resources used by Privoxy.
+ If Privoxy is only used by a single trusted user, limiting the
+ number of client connections is probably unnecessary. If there
+ are multiple possibly untrusted users you probably still want to
+ additionally use a packet filter to limit the maximal number of
+ incoming connections per client. Otherwise a malicious user could
+ intentionally create a high number of connections to prevent other
+ users from using Privoxy.
+ Obviously using this option only makes sense if you choose a limit
+ below the one enforced by the operating system.
+ max-client-connections 256
+ The status code Privoxy returns for pages blocked with
+
+ +handle-as-empty-document.
+ 0 or 1
+ 0 Privoxy returns a status 403(forbidden) for all blocked pages.
+ Privoxy returns a status 200(OK) for pages blocked with +handle-as-empty-document
+ and a status 403(Forbidden) for all other blocked pages.
+ This is a work-around for Firefox bug 492459:
+ " Websites are no longer rendered if SSL requests for JavaScripts are blocked by a proxy.
+ "
+ (https://bugzilla.mozilla.org/show_bug.cgi?id=492459)
+ As the bug has been fixed for quite some time this option should no longer
+ be needed and will be removed in a future release. Please speak up if you
+ have a reason why the option should be kept around.
+ Whether or not buffered content is compressed before delivery.
+ 0 or 1
+ 0 Privoxy does not compress buffered content.
+ Privoxy compresses buffered content before delivering it to the client,
+ provided the client supports it.
+ This directive is only supported if Privoxy has been compiled with
+ FEATURE_COMPRESSION, which should not to be confused with FEATURE_ZLIB.
+ Compressing buffered content is mainly useful if Privoxy and the
+ client are running on different systems. If they are running on the
+ same system, enabling compression is likely to slow things down.
+ If you didn't measure otherwise, you should assume that it does
+ and keep this option disabled.
+ Privoxy will not compress buffered content below a certain length.
+ The compression level that is passed to the zlib library when compressing buffered content.
+ Positive number ranging from 0 to 9.
+ 1 Compressing the data more takes usually longer than compressing
+ it less or not compressing it at all. Which level is best depends
+ on the connection between Privoxy and the client. If you can't
+ be bothered to benchmark it for yourself, you should stick with
+ the default and keep compression disabled.
+ If compression is disabled, the compression level is irrelevant.
+ Privoxy has a number of options specific to the
+ Windows GUI interface: If "activity-animation" is set to 1, the
+ Privoxy icon will animate when
+ "Privoxy" is active. To turn off, set to 0. activity-animation 1 If "log-messages" is set to 1,
+ Privoxy will log messages to the console
+ window: log-messages 17.2.7. jarfile
7.2.8. trustfile7.2.7. trustfile
1, 4096 and 8192 are recommended1, 1024, 4096 and 8192 are recommended
so that you will notice when things go wrong. The other levels are
@@ -1598,6 +1534,72 @@ CLASS="EMPHASIS"
> debug 1 # log each request destination (and the crunch reason if Privoxy intercepted the request)
- debug 2 # show each connection status
- debug 4 # show I/O status
- debug 8 # show header parsing
- debug 16 # log all data written to the network into the logfile
- debug 32 # debug force feature
- debug 64 # debug regular expression filters
- debug 128 # debug redirects
- debug 256 # debug GIF de-animation
- debug 512 # Common Log Format
- debug 1024 # debug kill pop-ups
- debug 2048 # CGI user interface
- debug 4096 # Startup banner and warnings.
- debug 8192 # Non-fatal errors
debug 1 # Log the destination for each request Privoxy let through. See also debug 1024.
+ debug 2 # show each connection status
+ debug 4 # show I/O status
+ debug 8 # show header parsing
+ debug 16 # log all data written to the network
+ debug 32 # debug force feature
+ debug 64 # debug regular expression filters
+ debug 128 # debug redirects
+ debug 256 # debug GIF de-animation
+ debug 512 # Common Log Format
+ debug 1024 # Log the destination for requests Privoxy didn't let through, and the reason why.
+ debug 2048 # CGI user interface
+ debug 4096 # Startup banner and warnings.
+ debug 8192 # Non-fatal errors
+ debug 32768 # log all data read from the network7.3.3. hostname
src_addr[/[:port][/src_masklendst_addr[/[:port][/dst_masklendst_addr are IP addresses in dotted decimal notation or valid
- DNS names, and are IPv4 addresses in dotted decimal notation or valid
+ DNS names, port is a port
+ number, and src_masklen listen-address [::1]:8118
+ permit-access 192.0.2.0/24
permit-access [::ffff:192.0.2.0]/120
+ forward / [2001:DB8::1]:8000
7.5.2. forward-socks4 and forward-socks4a7.5.2. forward-socks4, forward-socks4a and forward-socks5target_pattern is a is a
+ URL pattern
- that specifies to which requests (i.e. URLs) this forward rule shall apply. Use that specifies to which
+ requests (i.e. URLs) this forward rule shall apply. Use / to
denote "all URLs".
- . http_parent and
+ and socks_proxy
- are IP addresses in dotted decimal notation or valid DNS names (http_parentport parameters are TCP ports, i.e. integer values from 1 to 64535
+> parameters are TCP ports,
+ i.e. integer values from 1 to 65535
forward / parent-proxy.example.org:8000
+ forward ipv6-server.example.org .
+ forward <[2-3][0-9a-f][0-9a-f][0-9a-f]:*> .
forward-socks4a / 127.0.0.1:9050 .
forward-socks5 / 127.0.0.1:9050 .7.6. Miscellaneous
7.5.5. accept-intercepted-requests7.6.1. accept-intercepted-requests
7.5.6. allow-cgi-request-crunching7.6.2. allow-cgi-request-crunching7.5.7. split-large-forms7.6.3. split-large-forms
7.6.4. keep-alive-timeout7.6. Windows GUI Options
-
- 7.6.5. default-server-timeout
7.6.6. connection-sharing
7.6.7. socket-timeout
7.6.8. max-client-connections
7.6.9. handle-as-empty-doc-returns-ok
7.6.10. enable-compression
7.6.11. compression-level
+ # Best speed (compared to the other levels)
+ compression-level 1
+ # Best compression
+ compression-level 9
+ # No compression. Only useful for testing as the added header
+ # slightly increases the amount of data that has to be sent.
+ # If your benchmark shows that using this compression level
+ # is superior to using no compression at all, the benchmark
+ # is likely to be flawed.
+ compression-level 0
+
7.7. Windows GUI Options
+
+