X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;f=doc%2Fsource%2Fp-config.sgml;h=d509c42ffd850b344bbd9cff7836dee92566a9f6;hb=2e8c7e4321104708859ad7bf3e5697c0897778c5;hp=3e6042152d6aa58275ad6f4ac9d6bc119126c3eb;hpb=57359624a31a97c3e9b79c17527012c2ae4a9b53;p=privoxy.git diff --git a/doc/source/p-config.sgml b/doc/source/p-config.sgml index 3e604215..d509c42f 100644 --- a/doc/source/p-config.sgml +++ b/doc/source/p-config.sgml @@ -3,9 +3,9 @@ Purpose : Used with other docs and files only. - $Id: p-config.sgml,v 2.87 2012/10/21 13:02:01 fabiankeil Exp $ + $Id: p-config.sgml,v 2.127 2017/06/26 12:14:38 fabiankeil Exp $ - Copyright (C) 2001-2011 Privoxy Developers http://www.privoxy.org/ + Copyright (C) 2001-2017 Privoxy Developers https://www.privoxy.org/ See LICENSE. ======================================================================== @@ -94,32 +94,33 @@ @@TITLE<!-- between the @@ is stripped by Makefile -->@@ - Sample Configuration File for Privoxy v&p-version; + Sample Configuration File for Privoxy &p-version; - $Id: p-config.sgml,v 2.87 2012/10/21 13:02:01 fabiankeil Exp $ + $Id: p-config.sgml,v 2.127 2017/06/26 12:14:38 fabiankeil Exp $ -Copyright (C) 2001-2011 Privoxy Developers http://www.privoxy.org/ +Copyright (C) 2001-2017 Privoxy Developers https://www.privoxy.org/ -################################################################# - # - Table of Contents # - # - I. INTRODUCTION # - II. FORMAT OF THE CONFIGURATION FILE # - # - 1. LOCAL SET-UP DOCUMENTATION # - 2. CONFIGURATION AND LOG FILE LOCATIONS # - 3. DEBUGGING # - 4. ACCESS CONTROL AND SECURITY # - 5. FORWARDING # - 6. WINDOWS GUI OPTIONS # - # -################################################################# +################################################################## + # + Table of Contents # + # + I. INTRODUCTION # + II. FORMAT OF THE CONFIGURATION FILE # + # + 1. LOCAL SET-UP DOCUMENTATION # + 2. CONFIGURATION AND LOG FILE LOCATIONS # + 3. DEBUGGING # + 4. ACCESS CONTROL AND SECURITY # + 5. FORWARDING # + 6. MISCELLANEOUS # + 7. WINDOWS GUI OPTIONS # + # +################################################################## @@ -228,7 +229,7 @@ II. FORMAT OF THE CONFIGURATION FILE Effect if unset: - http://www.privoxy.org/version/user-manual/ + https://www.privoxy.org/version/user-manual/ will be used, where version is the Privoxy version. @@ -315,7 +316,7 @@ II. FORMAT OF THE CONFIGURATION FILE -@@#user-manual http://www.privoxy.org/user-manual/]]> +@@#user-manual https://www.privoxy.org/user-manual/]]> @@ -533,16 +534,6 @@ II. FORMAT OF THE CONFIGURATION FILE No trailing /, please. - @@ -597,6 +588,55 @@ II. FORMAT OF THE CONFIGURATION FILE + +temporary-directory + + + + Specifies: + + A directory where Privoxy can create temporary files. + + + + Type of value: + + Path name + + + + Default value: + + unset + + + + Effect if unset: + + No temporary files are created, external filters don't work. + + + + Notes: + + + To execute external filters, + Privoxy has to create temporary files. + This directive specifies the directory the temporary files should + be written to. + + + It should be a directory only Privoxy + (and trusted users) can access. + + + + + +@@#temporary-directory .]]> + + + logdir @@ -703,13 +743,6 @@ actionsfile Actions files contain all the per site and per URL configuration for ad blocking, cookie management, privacy considerations, etc. - There is no point in using Privoxy without at - least one actions file. - - - Note that since Privoxy 3.0.7, the complete filename, including the .action - extension has to be specified. The syntax change was necessary to be consistent - with the other file options and to allow previously forbidden characters. @@ -846,22 +879,22 @@ actionsfile Depending on the debug options below, the logfile may be a privacy risk if third parties can get access to it. As most users will never look - at it, Privoxy 3.0.7 and later only log fatal - errors by default. + at it, Privoxy only logs fatal errors by default. For most troubleshooting purposes, you will have to change that, please refer to the debugging section for details. - - 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 man cron). - Any log files must be writable by whatever user Privoxy is being run as (on Unix, default user id is privoxy). + + To prevent the logfile from growing indefinitely, it is recommended to + periodically rotate or shorten it. Many operating systems support log + rotation out of the box, some require additional software to do it. + For details, please refer to the documentation for your operating system. + @@ -1032,12 +1065,6 @@ actionsfile 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). - - - - &my-app; 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. If you are used to the more verbose settings, simply enable the debug lines @@ -1083,13 +1110,13 @@ actionsfile Type of value: - None + 1 or 0 Default value: - Unset + 0 @@ -1112,7 +1139,7 @@ actionsfile -@@#single-threaded]]> +@@#single-threaded 1]]> @@ -1365,18 +1392,6 @@ actionsfile toggled off mode, i.e. mostly behave like a normal, content-neutral proxy with both ad blocking and content filtering disabled. See enable-remote-toggle below. - - - - The windows version will only display the toggle icon in the system tray - if this option is present. @@ -1882,6 +1897,143 @@ ACLs: permit-access and deny-access @@buffer-limit 4096]]> + +enable-proxy-authentication-forwarding + + + Specifies: + + + Whether or not proxy authentication through &my-app; should work. + + + + + Type of value: + + 0 or 1 + + + + Default value: + + 0 + + + + Effect if unset: + + + Proxy authentication headers are removed. + + + + + Notes: + + + Privoxy itself does not support proxy authentication, but can + allow clients to authenticate against Privoxy's parent proxy. + + + 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. + + + If this option is enabled the headers are forwarded. + + + Enabling this option is not recommended 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. + + + + + +@@enable-proxy-authentication-forwarding 0]]> + + + +trusted-cgi-referer + + + Specifies: + + + A trusted website or webpage whose links can be followed to reach sensitive CGI pages + + + + + Type of value: + + URL or URL prefix + + + + Default value: + + Unset + + + + Effect if unset: + + + No external pages are considered trusted referers. + + + + + Notes: + + + Before &my-app; accepts configuration changes through CGI pages like + client-tags or the + remote toggle, it checks + the Referer header to see if the request comes from a trusted source. + + + By default only the webinterface domains + config.privoxy.org + and + p.p + 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. + + + 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. + + + The trusted-cgi-referer 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. + + + + 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. + + + + + + +@@trusted-cgi-referer http://www.example.org/local-privoxy-control-page]]> + + @@ -2028,7 +2180,7 @@ ACLs: permit-access and deny-access -forward-socks4, forward-socks4a and forward-socks5 +forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t @@ -2091,6 +2243,12 @@ forward-socks4, forward-socks4a and forward-socks5 With forward-socks5 the DNS resolution will happen on the remote server as well. + + forward-socks5t works like vanilla forward-socks5 but + lets &my-app; 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. + socks_proxy and http_parent can be a @@ -2139,11 +2297,16 @@ forward-socks4, forward-socks4a and forward-socks5 - forward-socks5 / 127.0.0.1:9050 . + forward-socks5t / 127.0.0.1:9050 . - - + + 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 + Tor website. + + The public Tor 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: @@ -2380,6 +2543,9 @@ forward-socks4, forward-socks4a and forward-socks5 option and configure your packet filter to redirect outgoing HTTP connections into Privoxy. + + Note that intercepting encrypted connections (HTTPS) isn't supported. + Make sure that Privoxy's own requests aren't redirected as well. Additionally take care that @@ -2388,6 +2554,12 @@ forward-socks4, forward-socks4a and forward-socks5 Privoxy's listening port is reachable by the outside or an attacker has access to the pages you visit. + + If you are running Privoxy as intercepting proxy without being + able to intercept all client requests you may want to adjust + the CGI templates to make sure they don't reference content from + config.privoxy.org. + @@ -2662,7 +2834,8 @@ forward-socks4, forward-socks4a and forward-socks5 that improves performance mainly depends on the client configuration. - This options is new and should be considered experimental. + If you are seeing problems with pages not properly loading, + disabling this option could work around the problem. @@ -2675,7 +2848,7 @@ forward-socks4, forward-socks4a and forward-socks5 -@@#tolerate-pipelining 1]]> +@@tolerate-pipelining 1]]> @@ -2936,7 +3109,7 @@ forward-socks4, forward-socks4a and forward-socks5 Default value: - None + 128 @@ -2981,6 +3154,13 @@ forward-socks4, forward-socks4a and forward-socks5 Obviously using this option only makes sense if you choose a limit below the one enforced by the operating system. + + One most POSIX-compliant systems &my-app; can't properly deal with + more than FD_SETSIZE file descriptors at the same time and has to reject + connections if the limit is reached. This will likely change in a + future version, but currently this limit can't be increased without + recompiling &my-app; with a different FD_SETSIZE limit. + @@ -2996,6 +3176,156 @@ forward-socks4, forward-socks4a and forward-socks5 +listen-backlog + + + Specifies: + + + Connection queue length requested from the operating system. + + + + + Type of value: + + + Number. + + + + + Default value: + + 128 + + + + Effect if unset: + + + A connection queue length of 128 is requested from the operating system. + + + + + Notes: + + + Under high load incoming connection may queue up before Privoxy + gets around to serve them. The queue length is limitted by the + operating system. Once the queue is full, additional connections + are dropped before Privoxy can accept and serve them. + + + Increasing the queue length allows Privoxy to accept more + incomming connections that arrive roughly at the same time. + + + Note that Privoxy can only request a certain queue length, + whether or not the requested length is actually used depends + on the operating system which may use a different length instead. + + + On many operating systems a limit of -1 can be specified to + instruct the operating system to use the maximum queue length + allowed. Check the listen man page to see if your platform allows this. + + + On some platforms you can use "netstat -Lan -p tcp" to see the effective + queue length. + + + Effectively using a value above 128 usually requires changing + the system configuration as well. On FreeBSD-based system the + limit is controlled by the kern.ipc.soacceptqueue sysctl. + + + + + Examples: + + + listen-backlog 4096 + + + + +@@#listen-backlog -1]]> + + + +enable-accept-filter + + + Specifies: + + + Whether or not Privoxy should use an accept filter + + + + + Type of value: + + + 0 or 1 + + + + + Default value: + + 0 + + + + Effect if unset: + + + No accept filter is enabled. + + + + + Notes: + + + Accept filters reduce the number of context switches by not + passing sockets for new connections to Privoxy until a complete + HTTP request is available. + + + As a result, Privoxy can process the whole request right away + without having to wait for additional data first. + + + For this option to work, Privoxy has to be compiled with + FEATURE_ACCEPT_FILTER and the operating system has to support + it (which may require loading a kernel module). + + + Currently accept filters are only supported on FreeBSD-based + systems. Check the + accf_http(9) + man page + to learn how to enable the support in the operating system. + + + + + Examples: + + + enable-accept-filter 1 + + + + +@@#enable-accept-filter 1]]> + + + handle-as-empty-doc-returns-ok @@ -3043,15 +3373,13 @@ forward-socks4, forward-socks4a and forward-socks5 Notes: - This is a work-around for Firefox bug 492459: - - Websites are no longer rendered if SSL requests for JavaScripts are blocked by a proxy. - + This directive was added as 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. + >https://bugzilla.mozilla.org/show_bug.cgi?id=492459), + the bug has been fixed for quite some time, but this directive is also useful + to make it harder for websites to detect whether or not resources are being + blocked. @@ -3238,24 +3566,324 @@ forward-socks4, forward-socks4a and forward-socks5 @@#client-header-order Host \ -# User-Agent \ -# Accept \ -# Accept-Language \ -# Accept-Encoding \ -# Proxy-Connection,\ -# Referer,Cookie \ -# If-Modified-Since \ -# Cache-Control \ -# Content-Length \ -# Content-Type + User-Agent \ + Accept \ + Accept-Language \ + Accept-Encoding \ + Proxy-Connection \ + Referer \ + Cookie \ + DNT \ + If-Modified-Since \ + Cache-Control \ + Content-Length \ + Content-Type ]]> - +client-specific-tag + + + Specifies: + + + The name of a tag that will always be set for clients that + requested it through the webinterface. + + + + + Type of value: + + + Tag name followed by a description that will be shown in the webinterface + + + + + Default value: + + None + + + + Notes: + + + + This is an experimental feature. The syntax is likely to change + in future versions. + + + + Client-specific tags allow Privoxy admins to create different + profiles and let the users chose which one they want without + impacting other users. + + + One use case is allowing users to circumvent certain blocks + without having to allow them to circumvent all blocks. + This is not possible with the + enable-remote-toggle feature + because it would bluntly disable all blocks for all users and also affect + other actions like filters. + It also is set globally which renders it useless in most multi-user setups. + + + After a client-specific tag has been defined with the client-specific-tag + directive, action sections can be activated based on the tag by using a + CLIENT-TAG pattern. + The CLIENT-TAG pattern is evaluated at the same priority + as URL patterns, as a result the last matching pattern wins. + Tags that are created based on client or server headers are evaluated + later on and can overrule CLIENT-TAG and URL patterns! + + + The tag is set for all requests that come from clients that requested + it to be set. + Note that "clients" are differentiated by IP address, + if the IP address changes the tag has to be requested again. + + + Clients can request tags to be set by using the CGI interface http://config.privoxy.org/client-tags. + The specific tag description is only used on the web page and should + be phrased in away that the user understand the effect of the tag. + + + + + Examples: + + + + # Define a couple of tags, the described effect requires action sections + # that are enabled based on CLIENT-TAG patterns. + client-specific-tag circumvent-blocks Overrule blocks but do not affect other actions + disable-content-filters Disable content-filters but do not affect other actions + + + + + + +client-tag-lifetime + + + Specifies: + + + How long a temporarily enabled tag remains enabled. + + + + + Type of value: + + + Time in seconds. + + + + + Default value: + + 60 + + + + Notes: + + + + This is an experimental feature. The syntax is likely to change + in future versions. + + + + In case of some tags users may not want to enable them permanently, + but only for a short amount of time, for example to circumvent a block + that is the result of an overly-broad URL pattern. + + + The CGI interface http://config.privoxy.org/client-tags + therefore provides a "enable this tag temporarily" option. + If it is used, the tag will be set until the client-tag-lifetime + is over. + + + + + Examples: + + + + # Increase the time to life for temporarily enabled tags to 3 minutes + client-tag-lifetime 180 + + + + + + + + + +trust-x-forwarded-for + + + Specifies: + + + Whether or not Privoxy should use IP addresses specified with the X-Forwarded-For header + + + + + Type of value: + + + 0 or one + + + + + Default value: + + 0 + + + + Notes: + + + + This is an experimental feature. The syntax is likely to change + in future versions. + + + + If clients reach Privoxy through another proxy, for example a load + balancer, Privoxy can't tell the client's IP address from the connection. + If multiple clients use the same proxy, they will share the same + client tag settings which is usually not desired. + + + This option lets Privoxy use the X-Forwarded-For header value as + client IP address. If the proxy sets the header, multiple clients + using the same proxy do not share the same client tag settings. + + + This option should only be enabled if Privoxy can only be reached + through a proxy and if the proxy can be trusted to set the header + correctly. It is recommended that ACL are used to make sure only + trusted systems can reach Privoxy. + + + If access to Privoxy isn't limited to trusted systems, this option + would allow malicious clients to change the client tags for other + clients or increase Privoxy's memory requirements by registering + lots of client tag settings for clients that don't exist. + + + + + Examples: + + + + # Allow systems that can reach Privoxy to provide the client + # IP address with a X-Forwarded-For header. + trust-x-forwarded-for 1 + + + + + + + + + + + +receive-buffer-size + + + Specifies: + + + The size of the buffer Privoxy uses to receive data from the server. + + + + + Type of value: + + + Size in bytes + + + + + Default value: + + 5000 + + + + Notes: + + + Increasing the receive-buffer-size increases Privoxy's memory usage but + can lower the number of context switches and thereby reduce the + cpu usage and potentially increase the throughput. + + + This is mostly relevant for fast network connections and + large downloads that don't require filtering. + + + Reducing the buffer size reduces the amount of memory Privoxy + needs to handle the request but increases the number of systemcalls + and may reduce the throughput. + + + A dtrace command like: + sudo dtrace -n 'syscall::read:return /execname == "privoxy"/ { @[execname] = llquantize(arg0, 10, 0, 5, 20); @m = max(arg0)}' + can be used to properly tune the receive-buffer-size. + On systems without dtrace, strace or truss may be used as + less convenient alternatives. + + + If the buffer is too large it will increase Privoxy's memory + footprint without any benefit. As the memory is (currently) + cleared before using it, a buffer that is too large can + actually reduce the throughput. + + + + + Examples: + + + + # Increase the receive buffer size + receive-buffer-size 32768 + + + + + + + + + +