1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01
2 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
5 <meta name="generator" content="HTML Tidy, see www.w3.org">
7 The Main Configuration File
9 <meta name="GENERATOR" content=
10 "Modular DocBook HTML Stylesheet Version 1.79">
11 <link rel="HOME" title="Privoxy 3.0.18 User Manual" href="index.html">
12 <link rel="PREVIOUS" title="Privoxy Configuration" href=
14 <link rel="NEXT" title="Actions Files" href="actions-file.html">
15 <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
16 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
17 <link rel="STYLESHEET" type="text/css" href="p_doc.css">
18 <style type="text/css">
20 background-color: #EEEEEE;
23 :link { color: #0000FF }
24 :visited { color: #840084 }
25 :active { color: #0000FF }
26 hr.c1 {text-align: left}
30 <div class="NAVHEADER">
31 <table summary="Header navigation table" width="100%" border="0"
32 cellpadding="0" cellspacing="0">
34 <th colspan="3" align="center">
35 Privoxy 3.0.18 User Manual
39 <td width="10%" align="left" valign="bottom">
40 <a href="configuration.html" accesskey="P">Prev</a>
42 <td width="80%" align="center" valign="bottom">
44 <td width="10%" align="right" valign="bottom">
45 <a href="actions-file.html" accesskey="N">Next</a>
49 <hr width="100%" class="c1">
53 <a name="CONFIG">7. The Main Configuration File</a>
56 By default, the main configuration file is named <tt class=
57 "FILENAME">config</tt>, with the exception of Windows, where it is
58 named <tt class="FILENAME">config.txt</tt>. Configuration lines
59 consist of an initial keyword followed by a list of values, all
60 separated by whitespace (any number of spaces or tabs). For example:
64 <p class="LITERALLAYOUT">
65 <tt class="LITERAL"> <span class="emphasis"><i class=
66 "EMPHASIS">confdir /etc/privoxy</i></span></tt>
70 Assigns the value <tt class="LITERAL">/etc/privoxy</tt> to the option
71 <tt class="LITERAL">confdir</tt> and thus indicates that the
72 configuration directory is named <span class=
73 "QUOTE">"/etc/privoxy/"</span>.
76 All options in the config file except for <tt class=
77 "LITERAL">confdir</tt> and <tt class="LITERAL">logdir</tt> are
78 optional. Watch out in the below description for what happens if you
82 The main config file controls all aspects of <span class=
83 "APPLICATION">Privoxy</span>'s operation that are not location
84 dependent (i.e. they apply universally, no matter where you may be
85 surfing). Like the filter and action files, the config file is a
86 plain text file and can be modified with a text editor like emacs,
91 <a name="LOCAL-SET-UP">7.1. Local Set-up Documentation</a>
94 If you intend to operate <span class="APPLICATION">Privoxy</span>
95 for more users than just yourself, it might be a good idea to let
96 them know how to reach you, what you block and why you do that,
101 <a name="USER-MANUAL">7.1.1. user-manual</a>
103 <div class="VARIABLELIST">
110 Location of the <span class="APPLICATION">Privoxy</span>
119 A fully qualified URI
127 <span class="emphasis"><i class="EMPHASIS">Unset</i></span>
135 <a href="http://www.privoxy.org/user-manual/" target=
136 "_top">http://www.privoxy.org/<tt class=
137 "REPLACEABLE"><i>version</i></tt>/user-manual/</a> will be
138 used, where <tt class="REPLACEABLE"><i>version</i></tt> is
139 the <span class="APPLICATION">Privoxy</span> version.
147 The User Manual URI is the single best source of
148 information on <span class="APPLICATION">Privoxy</span>,
149 and is used for help links from some of the internal CGI
150 pages. The manual itself is normally packaged with the
151 binary distributions, so you probably want to set this to a
152 locally installed copy.
158 The best all purpose solution is simply to put the full
159 local <tt class="LITERAL">PATH</tt> to where the <i class=
160 "CITETITLE">User Manual</i> is located:
164 <table border="0" bgcolor="#E0E0E0" width="90%">
168 user-manual /usr/share/doc/privoxy/user-manual
175 The User Manual is then available to anyone with access to
176 <span class="APPLICATION">Privoxy</span>, by following the
177 built-in URL: <tt class=
178 "LITERAL">http://config.privoxy.org/user-manual/</tt> (or
179 the shortcut: <tt class=
180 "LITERAL">http://p.p/user-manual/</tt>).
183 If the documentation is not on the local system, it can be
184 accessed from a remote server, as:
188 <table border="0" bgcolor="#E0E0E0" width="90%">
192 user-manual http://example.com/privoxy/user-manual/
198 <div class="WARNING">
199 <table class="WARNING" border="1" width="90%">
208 If set, this option should be <span class=
209 "emphasis"><i class="EMPHASIS">the first option in
210 the config file</i></span>, because it is used
211 while the config file is being read on start-up.
223 <a name="TRUST-INFO-URL">7.1.2. trust-info-url</a>
225 <div class="VARIABLELIST">
232 A URL to be displayed in the error page that users will see
233 if access to an untrusted page is denied.
249 <span class="emphasis"><i class="EMPHASIS">Unset</i></span>
257 No links are displayed on the "untrusted" error page.
265 The value of this option only matters if the experimental
266 trust mechanism has been activated. (See <a href=
267 "config.html#TRUSTFILE"><span class="emphasis"><i class=
268 "EMPHASIS">trustfile</i></span></a> below.)
271 If you use the trust mechanism, it is a good idea to write
272 up some on-line documentation about your trust policy and
273 to specify the URL(s) here. Use multiple times for multiple
277 The URL(s) should be added to the trustfile as well, so
278 users don't end up locked out from the information on why
279 they were locked out in the first place!
287 <a name="ADMIN-ADDRESS">7.1.3. admin-address</a>
289 <div class="VARIABLELIST">
296 An email address to reach the <span class=
297 "APPLICATION">Privoxy</span> administrator.
313 <span class="emphasis"><i class="EMPHASIS">Unset</i></span>
321 No email address is displayed on error pages and the CGI
330 If both <tt class="LITERAL">admin-address</tt> and <tt
331 class="LITERAL">proxy-info-url</tt> are unset, the whole
332 "Local Privoxy Support" box on all generated pages will not
341 <a name="PROXY-INFO-URL">7.1.4. proxy-info-url</a>
343 <div class="VARIABLELIST">
350 A URL to documentation about the local <span class=
351 "APPLICATION">Privoxy</span> setup, configuration or
368 <span class="emphasis"><i class="EMPHASIS">Unset</i></span>
376 No link to local documentation is displayed on error pages
377 and the CGI user interface.
385 If both <tt class="LITERAL">admin-address</tt> and <tt
386 class="LITERAL">proxy-info-url</tt> are unset, the whole
387 "Local Privoxy Support" box on all generated pages will not
391 This URL shouldn't be blocked ;-)
400 <a name="CONF-LOG-LOC">7.2. Configuration and Log File
404 <span class="APPLICATION">Privoxy</span> can (and normally does)
405 use a number of other files for additional configuration, help and
406 logging. This section of the configuration file tells <span class=
407 "APPLICATION">Privoxy</span> where to find those other files.
410 The user running <span class="APPLICATION">Privoxy</span>, must
411 have read permission for all configuration files, and write
412 permission to any files that would be modified, such as log files
417 <a name="CONFDIR">7.2.1. confdir</a>
419 <div class="VARIABLELIST">
426 The directory where the other configuration files are
443 /etc/privoxy (Unix) <span class="emphasis"><i class=
444 "EMPHASIS">or</i></span> <span class=
445 "APPLICATION">Privoxy</span> installation dir (Windows)
453 <span class="emphasis"><i class=
454 "EMPHASIS">Mandatory</i></span>
462 No trailing <span class="QUOTE">"<tt class=
463 "LITERAL">/</tt>"</span>, please.
471 <a name="TEMPLDIR">7.2.2. templdir</a>
473 <div class="VARIABLELIST">
480 An alternative directory where the templates are loaded
505 The templates are assumed to be located in
514 <span class="APPLICATION">Privoxy's</span> original
515 templates are usually overwritten with each update. Use
516 this option to relocate customized templates that should be
517 kept. As template variables might change between updates,
518 you shouldn't expect templates to work with <span class=
519 "APPLICATION">Privoxy</span> releases other than the one
520 they were part of, though.
528 <a name="LOGDIR">7.2.3. logdir</a>
530 <div class="VARIABLELIST">
537 The directory where all logging takes place (i.e. where the
538 <tt class="FILENAME">logfile</tt> is located).
554 /var/log/privoxy (Unix) <span class="emphasis"><i class=
555 "EMPHASIS">or</i></span> <span class=
556 "APPLICATION">Privoxy</span> installation dir (Windows)
564 <span class="emphasis"><i class=
565 "EMPHASIS">Mandatory</i></span>
573 No trailing <span class="QUOTE">"<tt class=
574 "LITERAL">/</tt>"</span>, please.
582 <a name="ACTIONSFILE">7.2.4. actionsfile</a>
584 <a name="DEFAULT.ACTION"></a><a name="STANDARD.ACTION"></a><a name=
586 <div class="VARIABLELIST">
593 The <a href="actions-file.html">actions file(s)</a> to use
601 Complete file name, relative to <tt class=
602 "LITERAL">confdir</tt>
613 <p class="LITERALLAYOUT">
614 match-all.action # Actions that are applied to all sites and maybe overruled later on.
620 <p class="LITERALLAYOUT">
621 default.action # Main actions file
627 <p class="LITERALLAYOUT">
628 user.action # User customizations
640 No actions are taken at all. More or less neutral proxying.
648 Multiple <tt class="LITERAL">actionsfile</tt> lines are
649 permitted, and are in fact recommended!
652 The default values are <tt class=
653 "FILENAME">default.action</tt>, which is the <span class=
654 "QUOTE">"main"</span> actions file maintained by the
655 developers, and <tt class="FILENAME">user.action</tt>,
656 where you can make your personal additions.
659 Actions files contain all the per site and per URL
660 configuration for ad blocking, cookie management, privacy
661 considerations, etc. There is no point in using <span
662 class="APPLICATION">Privoxy</span> without at least one
666 Note that since Privoxy 3.0.7, the complete filename,
667 including the <span class="QUOTE">".action"</span>
668 extension has to be specified. The syntax change was
669 necessary to be consistent with the other file options and
670 to allow previously forbidden characters.
678 <a name="FILTERFILE">7.2.5. filterfile</a>
680 <a name="DEFAULT.FILTER"></a>
681 <div class="VARIABLELIST">
688 The <a href="filter-file.html">filter file(s)</a> to use
696 File name, relative to <tt class="LITERAL">confdir</tt>
704 default.filter (Unix) <span class="emphasis"><i class=
705 "EMPHASIS">or</i></span> default.filter.txt (Windows)
713 No textual content filtering takes place, i.e. all <tt
714 class="LITERAL">+<a href=
715 "actions-file.html#FILTER">filter</a>{<tt class=
716 "REPLACEABLE"><i>name</i></tt>}</tt> actions in the actions
717 files are turned neutral.
725 Multiple <tt class="LITERAL">filterfile</tt> lines are
729 The <a href="filter-file.html">filter files</a> contain
730 content modification rules that use <a href=
731 "appendix.html#REGEX">regular expressions</a>. These rules
732 permit powerful changes on the content of Web pages, and
733 optionally the headers as well, e.g., you could try to
734 disable your favorite JavaScript annoyances, re-write the
735 actual displayed text, or just have some fun playing
736 buzzword bingo with web pages.
739 The <tt class="LITERAL">+<a href=
740 "actions-file.html#FILTER">filter</a>{<tt class=
741 "REPLACEABLE"><i>name</i></tt>}</tt> actions rely on the
742 relevant filter (<tt class="REPLACEABLE"><i>name</i></tt>)
743 to be defined in a filter file!
746 A pre-defined filter file called <tt class=
747 "FILENAME">default.filter</tt> that contains a number of
748 useful filters for common problems is included in the
749 distribution. See the section on the <tt class="LITERAL"><a
750 href="actions-file.html#FILTER">filter</a></tt> action for
754 It is recommended to place any locally adapted filters into
755 a separate file, such as <tt class=
756 "FILENAME">user.filter</tt>.
764 <a name="LOGFILE">7.2.6. logfile</a>
766 <div class="VARIABLELIST">
781 File name, relative to <tt class="LITERAL">logdir</tt>
789 <span class="emphasis"><i class="EMPHASIS">Unset (commented
790 out)</i></span>. When activated: logfile (Unix) <span
791 class="emphasis"><i class="EMPHASIS">or</i></span>
792 privoxy.log (Windows).
800 No logfile is written.
808 The logfile is where all logging and error messages are
809 written. The level of detail and number of messages are set
810 with the <tt class="LITERAL">debug</tt> option (see below).
811 The logfile can be useful for tracking down a problem with
812 <span class="APPLICATION">Privoxy</span> (e.g., it's not
813 blocking an ad you think it should block) and it can help
814 you to monitor what your browser is doing.
817 Depending on the debug options below, the logfile may be a
818 privacy risk if third parties can get access to it. As most
819 users will never look at it, <span class=
820 "APPLICATION">Privoxy</span> 3.0.7 and later only log fatal
824 For most troubleshooting purposes, you will have to change
825 that, please refer to the debugging section for details.
828 Your logfile will grow indefinitely, and you will probably
829 want to periodically remove it. On Unix systems, you can do
830 this with a cron job (see <span class="QUOTE">"man
831 cron"</span>). For Red Hat based Linux distributions, a <b
832 class="COMMAND">logrotate</b> script has been included.
835 Any log files must be writable by whatever user <span
836 class="APPLICATION">Privoxy</span> is being run as (on
837 Unix, default user id is <span class=
838 "QUOTE">"privoxy"</span>).
846 <a name="TRUSTFILE">7.2.7. trustfile</a>
848 <div class="VARIABLELIST">
855 The name of the trust file to use
863 File name, relative to <tt class="LITERAL">confdir</tt>
871 <span class="emphasis"><i class="EMPHASIS">Unset (commented
872 out)</i></span>. When activated: trust (Unix) <span class=
873 "emphasis"><i class="EMPHASIS">or</i></span> trust.txt
882 The entire trust mechanism is disabled.
890 The trust mechanism is an experimental feature for building
891 white-lists and should be used with care. It is <span
892 class="emphasis"><i class="EMPHASIS">NOT</i></span>
893 recommended for the casual user.
896 If you specify a trust file, <span class=
897 "APPLICATION">Privoxy</span> will only allow access to
898 sites that are specified in the trustfile. Sites can be
899 listed in one of two ways:
902 Prepending a <tt class="LITERAL">~</tt> character limits
903 access to this site only (and any sub-paths within this
904 site), e.g. <tt class="LITERAL">~www.example.com</tt>
905 allows access to <tt class=
906 "LITERAL">~www.example.com/features/news.html</tt>, etc.
909 Or, you can designate sites as <span class="emphasis"><i
910 class="EMPHASIS">trusted referrers</i></span>, by
911 prepending the name with a <tt class="LITERAL">+</tt>
912 character. The effect is that access to untrusted sites
913 will be granted -- but only if a link from this trusted
914 referrer was used to get there. The link target will then
915 be added to the <span class="QUOTE">"trustfile"</span> so
916 that future, direct accesses will be granted. Sites added
917 via this mechanism do not become trusted referrers
918 themselves (i.e. they are added with a <tt class=
919 "LITERAL">~</tt> designation). There is a limit of 512 such
920 entries, after which new entries will not be made.
923 If you use the <tt class="LITERAL">+</tt> operator in the
924 trust file, it may grow considerably over time.
927 It is recommended that <span class=
928 "APPLICATION">Privoxy</span> be compiled with the <tt
929 class="LITERAL">--disable-force</tt>, <tt class=
930 "LITERAL">--disable-toggle</tt> and <tt class=
931 "LITERAL">--disable-editor</tt> options, if this feature is
935 Possible applications include limiting Internet access for
945 <a name="DEBUGGING">7.3. Debugging</a>
948 These options are mainly useful when tracing a problem. Note that
949 you might also want to invoke <span class=
950 "APPLICATION">Privoxy</span> with the <tt class=
951 "LITERAL">--no-daemon</tt> command line option when debugging.
955 <a name="DEBUG">7.3.1. debug</a>
957 <div class="VARIABLELIST">
964 Key values that determine what information gets logged.
980 0 (i.e.: only fatal errors (that cause Privoxy to exit) are
989 Default value is used (see above).
997 The available debug levels are:
1001 <table border="0" bgcolor="#E0E0E0" width="90%">
1004 <pre class="PROGRAMLISTING">
1005 debug 1 # Log the destination for each request <span class=
1006 "APPLICATION">Privoxy</span> let through. See also debug 1024.
1007 debug 2 # show each connection status
1008 debug 4 # show I/O status
1009 debug 8 # show header parsing
1010 debug 16 # log all data written to the network
1011 debug 32 # debug force feature
1012 debug 64 # debug regular expression filters
1013 debug 128 # debug redirects
1014 debug 256 # debug GIF de-animation
1015 debug 512 # Common Log Format
1016 debug 1024 # Log the destination for requests <span class=
1017 "APPLICATION">Privoxy</span> didn't let through, and the reason why.
1018 debug 2048 # CGI user interface
1019 debug 4096 # Startup banner and warnings.
1020 debug 8192 # Non-fatal errors
1021 debug 32768 # log all data read from the network
1028 To select multiple debug levels, you can either add them or
1029 use multiple <tt class="LITERAL">debug</tt> lines.
1032 A debug level of 1 is informative because it will show you
1033 each request as it happens. <span class="emphasis"><i
1034 class="EMPHASIS">1, 1024, 4096 and 8192 are
1035 recommended</i></span> so that you will notice when things
1036 go wrong. The other levels are probably only of interest if
1037 you are hunting down a specific problem. They can produce a
1038 hell of an output (especially 16).
1041 <span class="APPLICATION">Privoxy</span> used to ship with
1042 the debug levels recommended above enabled by default, but
1043 due to privacy concerns 3.0.7 and later are configured to
1044 only log fatal errors.
1047 If you are used to the more verbose settings, simply enable
1048 the debug lines below again.
1051 If you want to use pure CLF (Common Log Format), you should
1052 set <span class="QUOTE">"debug 512"</span> <span class=
1053 "emphasis"><i class="EMPHASIS">ONLY</i></span> and not
1054 enable anything else.
1057 <span class="APPLICATION">Privoxy</span> has a hard-coded
1058 limit for the length of log messages. If it's reached,
1059 messages are logged truncated and marked with <span class=
1060 "QUOTE">"... [too long, truncated]"</span>.
1063 Please don't file any support requests without trying to
1064 reproduce the problem with increased debug level first.
1065 Once you read the log messages, you may even be able to
1066 solve the problem on your own.
1074 <a name="SINGLE-THREADED">7.3.2. single-threaded</a>
1076 <div class="VARIABLELIST">
1083 Whether to run only one server thread.
1091 <span class="emphasis"><i class="EMPHASIS">None</i></span>
1099 <span class="emphasis"><i class="EMPHASIS">Unset</i></span>
1107 Multi-threaded (or, where unavailable: forked) operation,
1108 i.e. the ability to serve multiple requests simultaneously.
1116 This option is only there for debugging purposes. <span
1117 class="emphasis"><i class="EMPHASIS">It will drastically
1118 reduce performance.</i></span>
1126 <a name="HOSTNAME">7.3.3. hostname</a>
1128 <div class="VARIABLELIST">
1135 The hostname shown on the CGI pages.
1151 <span class="emphasis"><i class="EMPHASIS">Unset</i></span>
1159 The hostname provided by the operating system is used.
1167 On some misconfigured systems resolving the hostname fails
1168 or takes too much time and slows Privoxy down. Setting a
1169 fixed hostname works around the problem.
1172 In other circumstances it might be desirable to show a
1173 hostname other than the one returned by the operating
1174 system. For example if the system has several different
1175 hostnames and you don't want to use the first one.
1178 Note that Privoxy does not validate the specified hostname
1188 <a name="ACCESS-CONTROL">7.4. Access Control and Security</a>
1191 This section of the config file controls the security-relevant
1192 aspects of <span class="APPLICATION">Privoxy</span>'s
1197 <a name="LISTEN-ADDRESS">7.4.1. listen-address</a>
1199 <div class="VARIABLELIST">
1206 The address and TCP port on which <span class=
1207 "APPLICATION">Privoxy</span> will listen for client
1216 [<tt class="REPLACEABLE"><i>IP-Address</i></tt>]:<tt class=
1217 "REPLACEABLE"><i>Port</i></tt>
1220 [<tt class="REPLACEABLE"><i>Hostname</i></tt>]:<tt class=
1221 "REPLACEABLE"><i>Port</i></tt>
1237 Bind to 127.0.0.1 (IPv4 localhost), port 8118. This is
1238 suitable and recommended for home users who run <span
1239 class="APPLICATION">Privoxy</span> on the same machine as
1248 You will need to configure your browser(s) to this proxy
1252 If you already have another service running on port 8118,
1253 or if you want to serve requests from other machines (e.g.
1254 on your local network) as well, you will need to override
1258 You can use this statement multiple times to make <span
1259 class="APPLICATION">Privoxy</span> listen on more ports or
1260 more <abbr class="ABBREV">IP</abbr> addresses. Suitable if
1261 your operating system does not support sharing <abbr class=
1262 "ABBREV">IPv6</abbr> and <abbr class="ABBREV">IPv4</abbr>
1263 protocols on the same socket.
1266 If a hostname is used instead of an IP address, <span
1267 class="APPLICATION">Privoxy</span> will try to resolve it
1268 to an IP address and if there are multiple, use the first
1272 If the address for the hostname isn't already known on the
1273 system (for example because it's in /etc/hostname), this
1274 may result in DNS traffic.
1277 If the specified address isn't available on the system, or
1278 if the hostname can't be resolved, <span class=
1279 "APPLICATION">Privoxy</span> will fail to start.
1282 IPv6 addresses containing colons have to be quoted by
1283 brackets. They can only be used if <span class=
1284 "APPLICATION">Privoxy</span> has been compiled with IPv6
1285 support. If you aren't sure if your version supports it,
1286 have a look at <tt class=
1287 "LITERAL">http://config.privoxy.org/show-status</tt>.
1290 Some operating systems will prefer IPv6 to IPv4 addresses
1291 even if the system has no IPv6 connectivity which is
1292 usually not expected by the user. Some even rely on DNS to
1293 resolve localhost which mean the "localhost" address used
1294 may not actually be local.
1297 It is therefore recommended to explicitly configure the
1298 intended IP address instead of relying on the operating
1299 system, unless there's a strong reason not to.
1302 If you leave out the address, <span class=
1303 "APPLICATION">Privoxy</span> will bind to all IPv4
1304 interfaces (addresses) on your machine and may become
1305 reachable from the Internet and/or the local network. Be
1306 aware that some GNU/Linux distributions modify that
1307 behaviour without updating the documentation. Check for
1308 non-standard patches if your <span class=
1309 "APPLICATION">Privoxy</span>version behaves differently.
1312 If you configure <span class="APPLICATION">Privoxy</span>to
1313 be reachable from the network, consider using <a href=
1314 "config.html#ACLS">access control lists</a> (ACL's, see
1315 below), and/or a firewall.
1318 If you open <span class="APPLICATION">Privoxy</span> to
1319 untrusted users, you will also want to make sure that the
1320 following actions are disabled: <tt class="LITERAL"><a
1322 "config.html#ENABLE-EDIT-ACTIONS">enable-edit-actions</a></tt>
1323 and <tt class="LITERAL"><a href=
1324 "config.html#ENABLE-REMOTE-TOGGLE">enable-remote-toggle</a></tt>
1327 With the exception noted above, listening on multiple
1328 addresses is currently not supported by <span class=
1329 "APPLICATION">Privoxy</span> directly. It can be done on
1330 most operating systems by letting a packet filter redirect
1331 request for certain addresses to Privoxy, though.
1339 Suppose you are running <span class=
1340 "APPLICATION">Privoxy</span> on a machine which has the
1341 address 192.168.0.1 on your local private network
1342 (192.168.0.0) and has another outside connection with a
1343 different address. You want it to serve requests from
1348 <table border="0" bgcolor="#E0E0E0" width="90%">
1351 <pre class="PROGRAMLISTING">
1352 listen-address 192.168.0.1:8118
1359 Suppose you are running <span class=
1360 "APPLICATION">Privoxy</span> on an IPv6-capable machine and
1361 you want it to listen on the IPv6 address of the loopback
1366 <table border="0" bgcolor="#E0E0E0" width="90%">
1369 <pre class="PROGRAMLISTING">
1370 listen-address [::1]:8118
1381 <a name="TOGGLE">7.4.2. toggle</a>
1383 <div class="VARIABLELIST">
1390 Initial state of "toggle" status
1414 Act as if toggled on
1422 If set to 0, <span class="APPLICATION">Privoxy</span> will
1423 start in <span class="QUOTE">"toggled off"</span> mode,
1424 i.e. mostly behave like a normal, content-neutral proxy
1425 with both ad blocking and content filtering disabled. See
1426 <tt class="LITERAL">enable-remote-toggle</tt> below.
1429 The windows version will only display the toggle icon in
1430 the system tray if this option is present.
1438 <a name="ENABLE-REMOTE-TOGGLE">7.4.3. enable-remote-toggle</a>
1440 <div class="VARIABLELIST">
1447 Whether or not the <a href=
1448 "http://config.privoxy.org/toggle" target="_top">web-based
1449 toggle feature</a> may be used
1473 The web-based toggle feature is disabled.
1481 When toggled off, <span class="APPLICATION">Privoxy</span>
1482 mostly acts like a normal, content-neutral proxy, i.e.
1483 doesn't block ads or filter content.
1486 Access to the toggle feature can <span class="emphasis"><i
1487 class="EMPHASIS">not</i></span> be controlled separately by
1488 <span class="QUOTE">"ACLs"</span> or HTTP authentication,
1489 so that everybody who can access <span class=
1490 "APPLICATION">Privoxy</span> (see <span class=
1491 "QUOTE">"ACLs"</span> and <tt class=
1492 "LITERAL">listen-address</tt> above) can toggle it for all
1493 users. So this option is <span class="emphasis"><i class=
1494 "EMPHASIS">not recommended</i></span> for multi-user
1495 environments with untrusted users.
1498 Note that malicious client side code (e.g Java) is also
1499 capable of using this option.
1502 As a lot of <span class="APPLICATION">Privoxy</span> users
1503 don't read documentation, this feature is disabled by
1507 Note that you must have compiled <span class=
1508 "APPLICATION">Privoxy</span> with support for this feature,
1509 otherwise this option has no effect.
1517 <a name="ENABLE-REMOTE-HTTP-TOGGLE">7.4.4.
1518 enable-remote-http-toggle</a>
1520 <div class="VARIABLELIST">
1527 Whether or not Privoxy recognizes special HTTP headers to
1528 change its behaviour.
1552 Privoxy ignores special HTTP headers.
1560 When toggled on, the client can change <span class=
1561 "APPLICATION">Privoxy's</span> behaviour by setting special
1562 HTTP headers. Currently the only supported special header
1563 is <span class="QUOTE">"X-Filter: No"</span>, to disable
1564 filtering for the ongoing request, even if it is enabled in
1565 one of the action files.
1568 This feature is disabled by default. If you are using <span
1569 class="APPLICATION">Privoxy</span> in a environment with
1570 trusted clients, you may enable this feature at your
1571 discretion. Note that malicious client side code (e.g Java)
1572 is also capable of using this feature.
1575 This option will be removed in future releases as it has
1576 been obsoleted by the more general header taggers.
1584 <a name="ENABLE-EDIT-ACTIONS">7.4.5. enable-edit-actions</a>
1586 <div class="VARIABLELIST">
1593 Whether or not the <a href=
1594 "http://config.privoxy.org/show-status" target=
1595 "_top">web-based actions file editor</a> may be used
1619 The web-based actions file editor is disabled.
1627 Access to the editor can <span class="emphasis"><i class=
1628 "EMPHASIS">not</i></span> be controlled separately by <span
1629 class="QUOTE">"ACLs"</span> or HTTP authentication, so that
1630 everybody who can access <span class=
1631 "APPLICATION">Privoxy</span> (see <span class=
1632 "QUOTE">"ACLs"</span> and <tt class=
1633 "LITERAL">listen-address</tt> above) can modify its
1634 configuration for all users.
1637 This option is <span class="emphasis"><i class=
1638 "EMPHASIS">not recommended</i></span> for environments with
1639 untrusted users and as a lot of <span class=
1640 "APPLICATION">Privoxy</span> users don't read
1641 documentation, this feature is disabled by default.
1644 Note that malicious client side code (e.g Java) is also
1645 capable of using the actions editor and you shouldn't
1646 enable this options unless you understand the consequences
1647 and are sure your browser is configured correctly.
1650 Note that you must have compiled <span class=
1651 "APPLICATION">Privoxy</span> with support for this feature,
1652 otherwise this option has no effect.
1660 <a name="ENFORCE-BLOCKS">7.4.6. enforce-blocks</a>
1662 <div class="VARIABLELIST">
1669 Whether the user is allowed to ignore blocks and can <span
1670 class="QUOTE">"go there anyway"</span>.
1678 <tt class="REPLACEABLE"><i>0 or 1</i></tt>
1686 <span class="emphasis"><i class="EMPHASIS">0</i></span>
1694 Blocks are not enforced.
1702 <span class="APPLICATION">Privoxy</span> is mainly used to
1703 block and filter requests as a service to the user, for
1704 example to block ads and other junk that clogs the pipes.
1705 <span class="APPLICATION">Privoxy's</span> configuration
1706 isn't perfect and sometimes innocent pages are blocked. In
1707 this situation it makes sense to allow the user to enforce
1708 the request and have <span class=
1709 "APPLICATION">Privoxy</span> ignore the block.
1712 In the default configuration <span class=
1713 "APPLICATION">Privoxy's</span> <span class=
1714 "QUOTE">"Blocked"</span> page contains a <span class=
1715 "QUOTE">"go there anyway"</span> link to adds a special
1716 string (the force prefix) to the request URL. If that link
1717 is used, <span class="APPLICATION">Privoxy</span> will
1718 detect the force prefix, remove it again and let the
1722 Of course <span class="APPLICATION">Privoxy</span> can also
1723 be used to enforce a network policy. In that case the user
1724 obviously should not be able to bypass any blocks, and
1725 that's what the <span class="QUOTE">"enforce-blocks"</span>
1726 option is for. If it's enabled, <span class=
1727 "APPLICATION">Privoxy</span> hides the <span class=
1728 "QUOTE">"go there anyway"</span> link. If the user adds the
1729 force prefix by hand, it will not be accepted and the
1730 circumvention attempt is logged.
1746 <a name="ACLS">7.4.7. ACLs: permit-access and deny-access</a>
1748 <a name="PERMIT-ACCESS"></a><a name="DENY-ACCESS"></a>
1749 <div class="VARIABLELIST">
1756 Who can access what.
1764 <tt class="REPLACEABLE"><i>src_addr</i></tt>[:<tt class=
1765 "REPLACEABLE"><i>port</i></tt>][/<tt class=
1766 "REPLACEABLE"><i>src_masklen</i></tt>] [<tt class=
1767 "REPLACEABLE"><i>dst_addr</i></tt>[:<tt class=
1768 "REPLACEABLE"><i>port</i></tt>][/<tt class=
1769 "REPLACEABLE"><i>dst_masklen</i></tt>]]
1772 Where <tt class="REPLACEABLE"><i>src_addr</i></tt> and <tt
1773 class="REPLACEABLE"><i>dst_addr</i></tt> are IPv4 addresses
1774 in dotted decimal notation or valid DNS names, <tt class=
1775 "REPLACEABLE"><i>port</i></tt> is a port number, and <tt
1776 class="REPLACEABLE"><i>src_masklen</i></tt> and <tt class=
1777 "REPLACEABLE"><i>dst_masklen</i></tt> are subnet masks in
1778 CIDR notation, i.e. integer values from 2 to 30
1779 representing the length (in bits) of the network address.
1780 The masks and the whole destination part are optional.
1783 If your system implements <a href=
1784 "http://tools.ietf.org/html/rfc3493" target="_top">RFC
1785 3493</a>, then <tt class="REPLACEABLE"><i>src_addr</i></tt>
1786 and <tt class="REPLACEABLE"><i>dst_addr</i></tt> can be
1787 IPv6 addresses delimeted by brackets, <tt class=
1788 "REPLACEABLE"><i>port</i></tt> can be a number or a service
1789 name, and <tt class="REPLACEABLE"><i>src_masklen</i></tt>
1790 and <tt class="REPLACEABLE"><i>dst_masklen</i></tt> can be
1791 a number from 0 to 128.
1799 <span class="emphasis"><i class="EMPHASIS">Unset</i></span>
1802 If no <tt class="REPLACEABLE"><i>port</i></tt> is
1803 specified, any port will match. If no <tt class=
1804 "REPLACEABLE"><i>src_masklen</i></tt> or <tt class=
1805 "REPLACEABLE"><i>src_masklen</i></tt> is given, the
1806 complete IP address has to match (i.e. 32 bits for IPv4 and
1815 Don't restrict access further than implied by <tt class=
1816 "LITERAL">listen-address</tt>
1824 Access controls are included at the request of ISPs and
1825 systems administrators, and <span class="emphasis"><i
1826 class="EMPHASIS">are not usually needed by individual
1827 users</i></span>. For a typical home user, it will normally
1828 suffice to ensure that <span class=
1829 "APPLICATION">Privoxy</span> only listens on the localhost
1830 (127.0.0.1) or internal (home) network address by means of
1831 the <a href="config.html#LISTEN-ADDRESS"><span class=
1832 "emphasis"><i class=
1833 "EMPHASIS">listen-address</i></span></a> option.
1836 Please see the warnings in the FAQ that <span class=
1837 "APPLICATION">Privoxy</span> is not intended to be a
1838 substitute for a firewall or to encourage anyone to defer
1839 addressing basic security weaknesses.
1842 Multiple ACL lines are OK. If any ACLs are specified, <span
1843 class="APPLICATION">Privoxy</span> only talks to IP
1844 addresses that match at least one <tt class=
1845 "LITERAL">permit-access</tt> line and don't match any
1846 subsequent <tt class="LITERAL">deny-access</tt> line. In
1847 other words, the last match wins, with the default being
1848 <tt class="LITERAL">deny-access</tt>.
1851 If <span class="APPLICATION">Privoxy</span> is using a
1852 forwarder (see <tt class="LITERAL">forward</tt> below) for
1853 a particular destination URL, the <tt class=
1854 "REPLACEABLE"><i>dst_addr</i></tt> that is examined is the
1855 address of the forwarder and <span class="emphasis"><i
1856 class="EMPHASIS">NOT</i></span> the address of the ultimate
1857 target. This is necessary because it may be impossible for
1858 the local <span class="APPLICATION">Privoxy</span> to
1859 determine the IP address of the ultimate target (that's
1860 often what gateways are used for).
1863 You should prefer using IP addresses over DNS names,
1864 because the address lookups take time. All DNS names must
1865 resolve! You can <span class="emphasis"><i class=
1866 "EMPHASIS">not</i></span> use domain patterns like <span
1867 class="QUOTE">"*.org"</span> or partial domain names. If a
1868 DNS name resolves to multiple IP addresses, only the first
1872 Some systems allow IPv4 clients to connect to IPv6 server
1873 sockets. Then the client's IPv4 address will be translated
1874 by the system into IPv6 address space with special prefix
1875 ::ffff:0:0/96 (so called IPv4 mapped IPv6 address). <span
1876 class="APPLICATION">Privoxy</span> can handle it and maps
1877 such ACL addresses automatically.
1880 Denying access to particular sites by ACL may have
1881 undesired side effects if the site in question is hosted on
1882 a machine which also hosts other sites (most sites are).
1890 Explicitly define the default behavior if no ACL and <tt
1891 class="LITERAL">listen-address</tt> are set: <span class=
1892 "QUOTE">"localhost"</span> is OK. The absence of a <tt
1893 class="REPLACEABLE"><i>dst_addr</i></tt> implies that <span
1894 class="emphasis"><i class="EMPHASIS">all</i></span>
1895 destination addresses are OK:
1899 <table border="0" bgcolor="#E0E0E0" width="90%">
1902 <pre class="SCREEN">
1903 permit-access localhost
1910 Allow any host on the same class C subnet as
1911 www.privoxy.org access to nothing but www.example.com (or
1912 other domains hosted on the same system):
1916 <table border="0" bgcolor="#E0E0E0" width="90%">
1919 <pre class="SCREEN">
1920 permit-access www.privoxy.org/24 www.example.com/32
1927 Allow access from any host on the 26-bit subnet
1928 192.168.45.64 to anywhere, with the exception that
1929 192.168.45.73 may not access the IP address behind
1930 www.dirty-stuff.example.com:
1934 <table border="0" bgcolor="#E0E0E0" width="90%">
1937 <pre class="SCREEN">
1938 permit-access 192.168.45.64/26
1939 deny-access 192.168.45.73 www.dirty-stuff.example.com
1946 Allow access from the IPv4 network 192.0.2.0/24 even if
1947 listening on an IPv6 wild card address (not supported on
1952 <table border="0" bgcolor="#E0E0E0" width="90%">
1955 <pre class="PROGRAMLISTING">
1956 permit-access 192.0.2.0/24
1963 This is equivalent to the following line even if listening
1964 on an IPv4 address (not supported on all platforms):
1968 <table border="0" bgcolor="#E0E0E0" width="90%">
1971 <pre class="PROGRAMLISTING">
1972 permit-access [::ffff:192.0.2.0]/120
1983 <a name="BUFFER-LIMIT">7.4.8. buffer-limit</a>
1985 <div class="VARIABLELIST">
1992 Maximum size of the buffer for content filtering.
2016 Use a 4MB (4096 KB) limit.
2024 For content filtering, i.e. the <tt class=
2025 "LITERAL">+filter</tt> and <tt class=
2026 "LITERAL">+deanimate-gif</tt> actions, it is necessary that
2027 <span class="APPLICATION">Privoxy</span> buffers the entire
2028 document body. This can be potentially dangerous, since a
2029 server could just keep sending data indefinitely and wait
2030 for your RAM to exhaust -- with nasty consequences. Hence
2034 When a document buffer size reaches the <tt class=
2035 "LITERAL">buffer-limit</tt>, it is flushed to the client
2036 unfiltered and no further attempt to filter the rest of the
2037 document is made. Remember that there may be multiple
2038 threads running, which might require up to <tt class=
2039 "LITERAL">buffer-limit</tt> Kbytes <span class=
2040 "emphasis"><i class="EMPHASIS">each</i></span>, unless you
2041 have enabled <span class="QUOTE">"single-threaded"</span>
2051 <a name="FORWARDING">7.5. Forwarding</a>
2054 This feature allows routing of HTTP requests through a chain of
2058 Forwarding can be used to chain Privoxy with a caching proxy to
2059 speed up browsing. Using a parent proxy may also be necessary if
2060 the machine that <span class="APPLICATION">Privoxy</span> runs on
2061 has no direct Internet access.
2064 Note that parent proxies can severely decrease your privacy level.
2065 For example a parent proxy could add your IP address to the request
2066 headers and if it's a caching proxy it may add the <span class=
2067 "QUOTE">"Etag"</span> header to revalidation requests again, even
2068 though you configured Privoxy to remove it. It may also ignore
2069 Privoxy's header time randomization and use the original values
2070 which could be used by the server as cookie replacement to track
2071 your steps between visits.
2074 Also specified here are SOCKS proxies. <span class=
2075 "APPLICATION">Privoxy</span> supports the SOCKS 4 and SOCKS 4A
2080 <a name="FORWARD">7.5.1. forward</a>
2082 <div class="VARIABLELIST">
2089 To which parent HTTP proxy specific requests should be
2098 <tt class="REPLACEABLE"><i>target_pattern</i></tt> <tt
2099 class="REPLACEABLE"><i>http_parent</i></tt>[:<tt class=
2100 "REPLACEABLE"><i>port</i></tt>]
2103 where <tt class="REPLACEABLE"><i>target_pattern</i></tt> is
2104 a <a href="actions-file.html#AF-PATTERNS">URL pattern</a>
2105 that specifies to which requests (i.e. URLs) this forward
2106 rule shall apply. Use <tt class="LITERAL">/</tt> to denote
2107 <span class="QUOTE">"all URLs"</span>. <tt class=
2108 "REPLACEABLE"><i>http_parent</i></tt>[:<tt class=
2109 "REPLACEABLE"><i>port</i></tt>] is the DNS name or IP
2110 address of the parent HTTP proxy through which the requests
2111 should be forwarded, optionally followed by its listening
2112 port (default: 8000). Use a single dot (<tt class=
2113 "LITERAL">.</tt>) to denote <span class="QUOTE">"no
2122 <span class="emphasis"><i class="EMPHASIS">Unset</i></span>
2130 Don't use parent HTTP proxies.
2138 If <tt class="REPLACEABLE"><i>http_parent</i></tt> is <span
2139 class="QUOTE">"."</span>, then requests are not forwarded
2140 to another HTTP proxy but are made directly to the web
2144 <tt class="REPLACEABLE"><i>http_parent</i></tt> can be a
2145 numerical IPv6 address (if <a href=
2146 "http://tools.ietf.org/html/rfc3493" target="_top">RFC
2147 3493</a> is implemented). To prevent clashes with the port
2148 delimiter, the whole IP address has to be put into
2149 brackets. On the other hand a <tt class=
2150 "REPLACEABLE"><i>target_pattern</i></tt> containing an IPv6
2151 address has to be put into angle brackets (normal brackets
2152 are reserved for regular expressions already).
2155 Multiple lines are OK, they are checked in sequence, and
2156 the last match wins.
2164 Everything goes to an example parent proxy, except SSL on
2165 port 443 (which it doesn't handle):
2169 <table border="0" bgcolor="#E0E0E0" width="90%">
2172 <pre class="SCREEN">
2173 forward / parent-proxy.example.org:8080
2181 Everything goes to our example ISP's caching proxy, except
2182 for requests to that ISP's sites:
2186 <table border="0" bgcolor="#E0E0E0" width="90%">
2189 <pre class="SCREEN">
2190 forward / caching-proxy.isp.example.net:8000
2191 forward .isp.example.net .
2198 Parent proxy specified by an IPv6 address:
2202 <table border="0" bgcolor="#E0E0E0" width="90%">
2205 <pre class="PROGRAMLISTING">
2206 forward / [2001:DB8::1]:8000
2213 Suppose your parent proxy doesn't support IPv6:
2217 <table border="0" bgcolor="#E0E0E0" width="90%">
2220 <pre class="PROGRAMLISTING">
2221 forward / parent-proxy.example.org:8000
2222 forward ipv6-server.example.org .
2223 forward <[2-3][0-9a-f][0-9a-f][0-9a-f]:*> .
2234 <a name="SOCKS">7.5.2. forward-socks4, forward-socks4a and
2237 <a name="FORWARD-SOCKS4"></a><a name="FORWARD-SOCKS4A"></a>
2238 <div class="VARIABLELIST">
2245 Through which SOCKS proxy (and optionally to which parent
2246 HTTP proxy) specific requests should be routed.
2254 <tt class="REPLACEABLE"><i>target_pattern</i></tt> <tt
2255 class="REPLACEABLE"><i>socks_proxy</i></tt>[:<tt class=
2256 "REPLACEABLE"><i>port</i></tt>] <tt class=
2257 "REPLACEABLE"><i>http_parent</i></tt>[:<tt class=
2258 "REPLACEABLE"><i>port</i></tt>]
2261 where <tt class="REPLACEABLE"><i>target_pattern</i></tt> is
2262 a <a href="actions-file.html#AF-PATTERNS">URL pattern</a>
2263 that specifies to which requests (i.e. URLs) this forward
2264 rule shall apply. Use <tt class="LITERAL">/</tt> to denote
2265 <span class="QUOTE">"all URLs"</span>. <tt class=
2266 "REPLACEABLE"><i>http_parent</i></tt> and <tt class=
2267 "REPLACEABLE"><i>socks_proxy</i></tt> are IP addresses in
2268 dotted decimal notation or valid DNS names (<tt class=
2269 "REPLACEABLE"><i>http_parent</i></tt> may be <span class=
2270 "QUOTE">"."</span> to denote <span class="QUOTE">"no HTTP
2271 forwarding"</span>), and the optional <tt class=
2272 "REPLACEABLE"><i>port</i></tt> parameters are TCP ports,
2273 i.e. integer values from 1 to 65535
2281 <span class="emphasis"><i class="EMPHASIS">Unset</i></span>
2289 Don't use SOCKS proxies.
2297 Multiple lines are OK, they are checked in sequence, and
2298 the last match wins.
2301 The difference between <tt class=
2302 "LITERAL">forward-socks4</tt> and <tt class=
2303 "LITERAL">forward-socks4a</tt> is that in the SOCKS 4A
2304 protocol, the DNS resolution of the target hostname happens
2305 on the SOCKS server, while in SOCKS 4 it happens locally.
2308 With <tt class="LITERAL">forward-socks5</tt> the DNS
2309 resolution will happen on the remote server as well.
2312 <tt class="REPLACEABLE"><i>socks_proxy</i></tt> and <tt
2313 class="REPLACEABLE"><i>http_parent</i></tt> can be a
2314 numerical IPv6 address (if <a href=
2315 "http://tools.ietf.org/html/rfc3493" target="_top">RFC
2316 3493</a> is implemented). To prevent clashes with the port
2317 delimiter, the whole IP address has to be put into
2318 brackets. On the other hand a <tt class=
2319 "REPLACEABLE"><i>target_pattern</i></tt> containing an IPv6
2320 address has to be put into angle brackets (normal brackets
2321 are reserved for regular expressions already).
2324 If <tt class="REPLACEABLE"><i>http_parent</i></tt> is <span
2325 class="QUOTE">"."</span>, then requests are not forwarded
2326 to another HTTP proxy but are made (HTTP-wise) directly to
2327 the web servers, albeit through a SOCKS proxy.
2335 From the company example.com, direct connections are made
2336 to all <span class="QUOTE">"internal"</span> domains, but
2337 everything outbound goes through their ISP's proxy by way
2338 of example.com's corporate SOCKS 4A gateway to the
2343 <table border="0" bgcolor="#E0E0E0" width="90%">
2346 <pre class="SCREEN">
2347 forward-socks4a / socks-gw.example.com:1080 www-cache.isp.example.net:8080
2348 forward .example.com .
2355 A rule that uses a SOCKS 4 gateway for all destinations but
2356 no HTTP parent looks like this:
2360 <table border="0" bgcolor="#E0E0E0" width="90%">
2363 <pre class="SCREEN">
2364 forward-socks4 / socks-gw.example.com:1080 .
2371 To chain Privoxy and Tor, both running on the same system,
2372 you would use something like:
2376 <table border="0" bgcolor="#E0E0E0" width="90%">
2379 <pre class="SCREEN">
2380 forward-socks5 / 127.0.0.1:9050 .
2387 The public <span class="APPLICATION">Tor</span> network
2388 can't be used to reach your local network, if you need to
2389 access local servers you therefore might want to make some
2394 <table border="0" bgcolor="#E0E0E0" width="90%">
2397 <pre class="SCREEN">
2398 forward 192.168.*.*/ .
2400 forward 127.*.*.*/ .
2407 Unencrypted connections to systems in these address ranges
2408 will be as (un)secure as the local network is, but the
2409 alternative is that you can't reach the local network
2410 through <span class="APPLICATION">Privoxy</span> at all. Of
2411 course this may actually be desired and there is no reason
2412 to make these exceptions if you aren't sure you need them.
2415 If you also want to be able to reach servers in your local
2416 network by using their names, you will need additional
2417 exceptions that look like this:
2421 <table border="0" bgcolor="#E0E0E0" width="90%">
2424 <pre class="SCREEN">
2425 forward localhost/ .
2436 <a name="ADVANCED-FORWARDING-EXAMPLES">7.5.3. Advanced Forwarding
2440 If you have links to multiple ISPs that provide various special
2441 content only to their subscribers, you can configure multiple
2442 <span class="APPLICATION">Privoxies</span> which have connections
2443 to the respective ISPs to act as forwarders to each other, so
2444 that <span class="emphasis"><i class="EMPHASIS">your</i></span>
2445 users can see the internal content of all ISPs.
2448 Assume that host-a has a PPP connection to isp-a.example.net. And
2449 host-b has a PPP connection to isp-b.example.org. Both run <span
2450 class="APPLICATION">Privoxy</span>. Their forwarding
2451 configuration can look like this:
2458 <table border="0" bgcolor="#E0E0E0" width="100%">
2461 <pre class="SCREEN">
2463 forward .isp-b.example.net host-b:8118
2474 <table border="0" bgcolor="#E0E0E0" width="100%">
2477 <pre class="SCREEN">
2479 forward .isp-a.example.org host-a:8118
2486 Now, your users can set their browser's proxy to use either
2487 host-a or host-b and be able to browse the internal content of
2488 both isp-a and isp-b.
2491 If you intend to chain <span class="APPLICATION">Privoxy</span>
2492 and <span class="APPLICATION">squid</span> locally, then chaining
2493 as <tt class="LITERAL">browser -> squid -> privoxy</tt> is
2494 the recommended way.
2497 Assuming that <span class="APPLICATION">Privoxy</span> and <span
2498 class="APPLICATION">squid</span> run on the same box, your <span
2499 class="APPLICATION">squid</span> configuration could then look
2504 <table border="0" bgcolor="#E0E0E0" width="100%">
2507 <pre class="SCREEN">
2508 # Define Privoxy as parent proxy (without ICP)
2509 cache_peer 127.0.0.1 parent 8118 7 no-query
2511 # Define ACL for protocol FTP
2514 # Do not forward FTP requests to Privoxy
2515 always_direct allow ftp
2517 # Forward all the rest to Privoxy
2518 never_direct allow all
2525 You would then need to change your browser's proxy settings to
2526 <span class="APPLICATION">squid</span>'s address and port. Squid
2527 normally uses port 3128. If unsure consult <tt class=
2528 "LITERAL">http_port</tt> in <tt class="FILENAME">squid.conf</tt>.
2531 You could just as well decide to only forward requests you
2532 suspect of leading to Windows executables through a
2533 virus-scanning parent proxy, say, on <tt class=
2534 "LITERAL">antivir.example.com</tt>, port 8010:
2538 <table border="0" bgcolor="#E0E0E0" width="100%">
2541 <pre class="SCREEN">
2543 forward /.*\.(exe|com|dll|zip)$ antivir.example.com:8010
2551 <a name="FORWARDED-CONNECT-RETRIES">7.5.4.
2552 forwarded-connect-retries</a>
2554 <div class="VARIABLELIST">
2561 How often Privoxy retries if a forwarded connection request
2570 <tt class="REPLACEABLE"><i>Number of retries.</i></tt>
2578 <span class="emphasis"><i class="EMPHASIS">0</i></span>
2586 Connections forwarded through other proxies are treated
2587 like direct connections and no retry attempts are made.
2596 "REPLACEABLE"><i>forwarded-connect-retries</i></tt> is
2597 mainly interesting for socks4a connections, where <span
2598 class="APPLICATION">Privoxy</span> can't detect why the
2599 connections failed. The connection might have failed
2600 because of a DNS timeout in which case a retry makes sense,
2601 but it might also have failed because the server doesn't
2602 exist or isn't reachable. In this case the retry will just
2603 delay the appearance of Privoxy's error message.
2606 Note that in the context of this option, <span class=
2607 "QUOTE">"forwarded connections"</span> includes all
2608 connections that Privoxy forwards through other proxies.
2609 This option is not limited to the HTTP CONNECT method.
2612 Only use this option, if you are getting lots of
2613 forwarding-related error messages that go away when you try
2614 again manually. Start with a small value and check
2615 Privoxy's logfile from time to time, to see how many
2616 retries are usually needed.
2624 forwarded-connect-retries 1
2633 <a name="MISC">7.6. Miscellaneous</a>
2637 <a name="ACCEPT-INTERCEPTED-REQUESTS">7.6.1.
2638 accept-intercepted-requests</a>
2640 <div class="VARIABLELIST">
2647 Whether intercepted requests should be treated as valid.
2655 <tt class="REPLACEABLE"><i>0 or 1</i></tt>
2663 <span class="emphasis"><i class="EMPHASIS">0</i></span>
2671 Only proxy requests are accepted, intercepted requests are
2680 If you don't trust your clients and want to force them to
2681 use <span class="APPLICATION">Privoxy</span>, enable this
2682 option and configure your packet filter to redirect
2683 outgoing HTTP connections into <span class=
2684 "APPLICATION">Privoxy</span>.
2687 Make sure that <span class="APPLICATION">Privoxy's</span>
2688 own requests aren't redirected as well. Additionally take
2689 care that <span class="APPLICATION">Privoxy</span> can't
2690 intentionally connect to itself, otherwise you could run
2691 into redirection loops if <span class=
2692 "APPLICATION">Privoxy's</span> listening port is reachable
2693 by the outside or an attacker has access to the pages you
2702 accept-intercepted-requests 1
2710 <a name="ALLOW-CGI-REQUEST-CRUNCHING">7.6.2.
2711 allow-cgi-request-crunching</a>
2713 <div class="VARIABLELIST">
2720 Whether requests to <span class=
2721 "APPLICATION">Privoxy's</span> CGI pages can be blocked or
2730 <tt class="REPLACEABLE"><i>0 or 1</i></tt>
2738 <span class="emphasis"><i class="EMPHASIS">0</i></span>
2746 <span class="APPLICATION">Privoxy</span> ignores block and
2747 redirect actions for its CGI pages.
2755 By default <span class="APPLICATION">Privoxy</span> ignores
2756 block or redirect actions for its CGI pages. Intercepting
2757 these requests can be useful in multi-user setups to
2758 implement fine-grained access control, but it can also
2759 render the complete web interface useless and make
2760 debugging problems painful if done without care.
2763 Don't enable this option unless you're sure that you really
2772 allow-cgi-request-crunching 1
2780 <a name="SPLIT-LARGE-FORMS">7.6.3. split-large-forms</a>
2782 <div class="VARIABLELIST">
2789 Whether the CGI interface should stay compatible with
2790 broken HTTP clients.
2798 <tt class="REPLACEABLE"><i>0 or 1</i></tt>
2806 <span class="emphasis"><i class="EMPHASIS">0</i></span>
2814 The CGI form generate long GET URLs.
2822 <span class="APPLICATION">Privoxy's</span> CGI forms can
2823 lead to rather long URLs. This isn't a problem as far as
2824 the HTTP standard is concerned, but it can confuse clients
2825 with arbitrary URL length limitations.
2828 Enabling split-large-forms causes <span class=
2829 "APPLICATION">Privoxy</span> to divide big forms into
2830 smaller ones to keep the URL length down. It makes editing
2831 a lot less convenient and you can no longer submit all
2832 changes at once, but at least it works around this browser
2836 If you don't notice any editing problems, there is no
2837 reason to enable this option, but if one of the submit
2838 buttons appears to be broken, you should give it a try.
2854 <a name="KEEP-ALIVE-TIMEOUT">7.6.4. keep-alive-timeout</a>
2856 <div class="VARIABLELIST">
2863 Number of seconds after which an open connection will no
2872 <tt class="REPLACEABLE"><i>Time in seconds.</i></tt>
2888 Connections are not kept alive.
2896 This option allows clients to keep the connection to <span
2897 class="APPLICATION">Privoxy</span> alive. If the server
2898 supports it, <span class="APPLICATION">Privoxy</span> will
2899 keep the connection to the server alive as well. Under
2900 certain circumstances this may result in speed-ups.
2903 By default, <span class="APPLICATION">Privoxy</span> will
2904 close the connection to the server if the client connection
2905 gets closed, or if the specified timeout has been reached
2906 without a new request coming in. This behaviour can be
2907 changed with the <a href="#CONNECTION-SHARING" target=
2908 "_top">connection-sharing</a> option.
2911 This option has no effect if <span class=
2912 "APPLICATION">Privoxy</span> has been compiled without
2916 Note that a timeout of five seconds as used in the default
2917 configuration file significantly decreases the number of
2918 connections that will be reused. The value is used because
2919 some browsers limit the number of connections they open to
2920 a single host and apply the same limit to proxies. This can
2921 result in a single website <span class=
2922 "QUOTE">"grabbing"</span> all the connections the browser
2923 allows, which means connections to other websites can't be
2924 opened until the connections currently in use time out.
2927 Several users have reported this as a Privoxy bug, so the
2928 default value has been reduced. Consider increasing it to
2929 300 seconds or even more if you think your browser can
2930 handle it. If your browser appears to be hanging it can't.
2938 keep-alive-timeout 300
2946 <a name="DEFAULT-SERVER-TIMEOUT">7.6.5.
2947 default-server-timeout</a>
2949 <div class="VARIABLELIST">
2956 Assumed server-side keep-alive timeout if not specified by
2965 <tt class="REPLACEABLE"><i>Time in seconds.</i></tt>
2981 Connections for which the server didn't specify the
2982 keep-alive timeout are not reused.
2990 Enabling this option significantly increases the number of
2991 connections that are reused, provided the <a href=
2992 "#KEEP-ALIVE-TIMEOUT" target="_top">keep-alive-timeout</a>
2993 option is also enabled.
2996 While it also increases the number of connections problems
2997 when <span class="APPLICATION">Privoxy</span> tries to
2998 reuse a connection that already has been closed on the
2999 server side, or is closed while <span class=
3000 "APPLICATION">Privoxy</span> is trying to reuse it, this
3001 should only be a problem if it happens for the first
3002 request sent by the client. If it happens for requests on
3003 reused client connections, <span class=
3004 "APPLICATION">Privoxy</span> will simply close the
3005 connection and the client is supposed to retry the request
3006 without bothering the user.
3009 Enabling this option is therefore only recommended if the
3010 <a href="#CONNECTION-SHARING" target=
3011 "_top">connection-sharing</a> option is disabled.
3014 It is an error to specify a value larger than the <a href=
3015 "#KEEP-ALIVE-TIMEOUT" target="_top">keep-alive-timeout</a>
3019 This option has no effect if <span class=
3020 "APPLICATION">Privoxy</span> has been compiled without
3029 default-server-timeout 60
3037 <a name="CONNECTION-SHARING">7.6.6. connection-sharing</a>
3039 <div class="VARIABLELIST">
3046 Whether or not outgoing connections that have been kept
3047 alive should be shared between different incoming
3056 <tt class="REPLACEABLE"><i>0 or 1</i></tt>
3072 Connections are not shared.
3080 This option has no effect if <span class=
3081 "APPLICATION">Privoxy</span> has been compiled without
3082 keep-alive support, or if it's disabled.
3090 Note that reusing connections doesn't necessary cause
3091 speedups. There are also a few privacy implications you
3095 If this option is effective, outgoing connections are
3096 shared between clients (if there are more than one) and
3097 closing the browser that initiated the outgoing connection
3098 does no longer affect the connection between <span class=
3099 "APPLICATION">Privoxy</span> and the server unless the
3100 client's request hasn't been completed yet.
3103 If the outgoing connection is idle, it will not be closed
3104 until either <span class="APPLICATION">Privoxy's</span> or
3105 the server's timeout is reached. While it's open, the
3106 server knows that the system running <span class=
3107 "APPLICATION">Privoxy</span> is still there.
3110 If there are more than one client (maybe even belonging to
3111 multiple users), they will be able to reuse each others
3112 connections. This is potentially dangerous in case of
3113 authentication schemes like NTLM where only the connection
3114 is authenticated, instead of requiring authentication for
3118 If there is only a single client, and if said client can
3119 keep connections alive on its own, enabling this option has
3120 next to no effect. If the client doesn't support connection
3121 keep-alive, enabling this option may make sense as it
3122 allows <span class="APPLICATION">Privoxy</span> to keep
3123 outgoing connections alive even if the client itself
3127 You should also be aware that enabling this option
3128 increases the likelihood of getting the "No server or
3129 forwarder data" error message, especially if you are using
3130 a slow connection to the Internet.
3133 This option should only be used by experienced users who
3134 understand the risks and can weight them against the
3143 connection-sharing 1
3151 <a name="SOCKET-TIMEOUT">7.6.7. socket-timeout</a>
3153 <div class="VARIABLELIST">
3160 Number of seconds after which a socket times out if no data
3169 <tt class="REPLACEABLE"><i>Time in seconds.</i></tt>
3185 A default value of 300 seconds is used.
3193 The default is quite high and you probably want to reduce
3194 it. If you aren't using an occasionally slow proxy like
3195 Tor, reducing it to a few seconds should be fine.
3211 <a name="MAX-CLIENT-CONNECTIONS">7.6.8.
3212 max-client-connections</a>
3214 <div class="VARIABLELIST">
3221 Maximum number of client connections that will be served.
3229 <tt class="REPLACEABLE"><i>Positive number.</i></tt>
3245 Connections are served until a resource limit is reached.
3253 <span class="APPLICATION">Privoxy</span> creates one thread
3254 (or process) for every incoming client connection that
3255 isn't rejected based on the access control settings.
3258 If the system is powerful enough, <span class=
3259 "APPLICATION">Privoxy</span> can theoretically deal with
3260 several hundred (or thousand) connections at the same time,
3261 but some operating systems enforce resource limits by
3262 shutting down offending processes and their default limits
3263 may be below the ones <span class=
3264 "APPLICATION">Privoxy</span> would require under heavy
3268 Configuring <span class="APPLICATION">Privoxy</span> to
3269 enforce a connection limit below the thread or process
3270 limit used by the operating system makes sure this doesn't
3271 happen. Simply increasing the operating system's limit
3272 would work too, but if <span class=
3273 "APPLICATION">Privoxy</span> isn't the only application
3274 running on the system, you may actually want to limit the
3275 resources used by <span class="APPLICATION">Privoxy</span>.
3278 If <span class="APPLICATION">Privoxy</span> is only used by
3279 a single trusted user, limiting the number of client
3280 connections is probably unnecessary. If there are multiple
3281 possibly untrusted users you probably still want to
3282 additionally use a packet filter to limit the maximal
3283 number of incoming connections per client. Otherwise a
3284 malicious user could intentionally create a high number of
3285 connections to prevent other users from using <span class=
3286 "APPLICATION">Privoxy</span>.
3289 Obviously using this option only makes sense if you choose
3290 a limit below the one enforced by the operating system.
3298 max-client-connections 256
3306 <a name="HANDLE-AS-EMPTY-DOC-RETURNS-OK">7.6.9.
3307 handle-as-empty-doc-returns-ok</a>
3309 <div class="VARIABLELIST">
3316 The status code Privoxy returns for pages blocked with <tt
3317 class="LITERAL"><a href=
3318 "actions-file.html#HANDLE-AS-EMPTY-DOCUMENT" target=
3319 "_top">+handle-as-empty-document</a></tt>.
3327 <tt class="REPLACEABLE"><i>0 or 1</i></tt>
3343 Privoxy returns a status 403(forbidden) for all blocked
3352 Privoxy returns a status 200(OK) for pages blocked with
3353 +handle-as-empty-document and a status 403(Forbidden) for
3354 all other blocked pages.
3362 This is a work-around for Firefox bug 492459: <span class=
3363 "QUOTE">" Websites are no longer rendered if SSL requests
3364 for JavaScripts are blocked by a proxy. "</span> (<a href=
3365 "https://bugzilla.mozilla.org/show_bug.cgi?id=492459"
3367 "_top">https://bugzilla.mozilla.org/show_bug.cgi?id=492459</a>)
3368 As the bug has been fixed for quite some time this option
3369 should no longer be needed and will be removed in a future
3370 release. Please speak up if you have a reason why the
3371 option should be kept around.
3379 <a name="ENABLE-COMPRESSION">7.6.10. enable-compression</a>
3381 <div class="VARIABLELIST">
3388 Whether or not buffered content is compressed before
3397 <tt class="REPLACEABLE"><i>0 or 1</i></tt>
3413 Privoxy does not compress buffered content.
3421 Privoxy compresses buffered content before delivering it to
3422 the client, provided the client supports it.
3430 This directive is only supported if Privoxy has been
3431 compiled with FEATURE_COMPRESSION, which should not to be
3432 confused with FEATURE_ZLIB.
3435 Compressing buffered content is mainly useful if Privoxy
3436 and the client are running on different systems. If they
3437 are running on the same system, enabling compression is
3438 likely to slow things down. If you didn't measure
3439 otherwise, you should assume that it does and keep this
3443 Privoxy will not compress buffered content below a certain
3452 <a name="COMPRESSION-LEVEL">7.6.11. compression-level</a>
3454 <div class="VARIABLELIST">
3461 The compression level that is passed to the zlib library
3462 when compressing buffered content.
3470 <tt class="REPLACEABLE"><i>Positive number ranging from 0
3487 Compressing the data more takes usually longer than
3488 compressing it less or not compressing it at all. Which
3489 level is best depends on the connection between Privoxy and
3490 the client. If you can't be bothered to benchmark it for
3491 yourself, you should stick with the default and keep
3492 compression disabled.
3495 If compression is disabled, the compression level is
3505 <table border="0" bgcolor="#E0E0E0" width="90%">
3508 <pre class="SCREEN">
3509 # Best speed (compared to the other levels)
3513 # No compression. Only useful for testing as the added header
3514 # slightly increases the amount of data that has to be sent.
3515 # If your benchmark shows that using this compression level
3516 # is superior to using no compression at all, the benchmark
3517 # is likely to be flawed.
3531 <a name="WINDOWS-GUI">7.7. Windows GUI Options</a>
3534 <span class="APPLICATION">Privoxy</span> has a number of options
3535 specific to the Windows GUI interface:
3537 <a name="ACTIVITY-ANIMATION"></a>
3539 If <span class="QUOTE">"activity-animation"</span> is set to 1, the
3540 <span class="APPLICATION">Privoxy</span> icon will animate when
3541 <span class="QUOTE">"Privoxy"</span> is active. To turn off, set to
3546 <p class="LITERALLAYOUT">
3547 <tt class="LITERAL"> <span class="emphasis"><i class=
3548 "EMPHASIS">activity-animation 1</i></span><br>
3549 </tt>
3551 <a name="LOG-MESSAGES"></a>
3553 If <span class="QUOTE">"log-messages"</span> is set to 1, <span
3554 class="APPLICATION">Privoxy</span> will log messages to the console
3559 <p class="LITERALLAYOUT">
3560 <tt class="LITERAL"> <span class="emphasis"><i class=
3561 "EMPHASIS">log-messages 1</i></span><br>
3562 </tt>
3564 <a name="LOG-BUFFER-SIZE"></a>
3566 If <span class="QUOTE">"log-buffer-size"</span> is set to 1, the
3567 size of the log buffer, i.e. the amount of memory used for the log
3568 messages displayed in the console window, will be limited to <span
3569 class="QUOTE">"log-max-lines"</span> (see below).
3572 Warning: Setting this to 0 will result in the buffer to grow
3573 infinitely and eat up all your memory!
3577 <p class="LITERALLAYOUT">
3578 <tt class="LITERAL"> <span class="emphasis"><i class=
3579 "EMPHASIS">log-buffer-size 1</i></span><br>
3580 </tt>
3582 <a name="LOG-MAX-LINES"></a>
3584 <span class="APPLICATION">log-max-lines</span> is the maximum
3585 number of lines held in the log buffer. See above.
3589 <p class="LITERALLAYOUT">
3590 <tt class="LITERAL"> <span class="emphasis"><i class=
3591 "EMPHASIS">log-max-lines 200</i></span><br>
3592 </tt>
3594 <a name="LOG-HIGHLIGHT-MESSAGES"></a>
3596 If <span class="QUOTE">"log-highlight-messages"</span> is set to 1,
3597 <span class="APPLICATION">Privoxy</span> will highlight portions of
3598 the log messages with a bold-faced font:
3602 <p class="LITERALLAYOUT">
3603 <tt class="LITERAL"> <span class="emphasis"><i class=
3604 "EMPHASIS">log-highlight-messages 1</i></span><br>
3605 </tt>
3607 <a name="LOG-FONT-NAME"></a>
3609 The font used in the console window:
3613 <p class="LITERALLAYOUT">
3614 <tt class="LITERAL"> <span class="emphasis"><i class=
3615 "EMPHASIS">log-font-name Comic Sans MS</i></span><br>
3616 </tt>
3618 <a name="LOG-FONT-SIZE"></a>
3620 Font size used in the console window:
3624 <p class="LITERALLAYOUT">
3625 <tt class="LITERAL"> <span class="emphasis"><i class=
3626 "EMPHASIS">log-font-size 8</i></span><br>
3627 </tt>
3629 <a name="SHOW-ON-TASK-BAR"></a>
3631 <span class="QUOTE">"show-on-task-bar"</span> controls whether or
3632 not <span class="APPLICATION">Privoxy</span> will appear as a
3633 button on the Task bar when minimized:
3637 <p class="LITERALLAYOUT">
3638 <tt class="LITERAL"> <span class="emphasis"><i class=
3639 "EMPHASIS">show-on-task-bar 0</i></span><br>
3640 </tt>
3642 <a name="CLOSE-BUTTON-MINIMIZES"></a>
3644 If <span class="QUOTE">"close-button-minimizes"</span> is set to 1,
3645 the Windows close button will minimize <span class=
3646 "APPLICATION">Privoxy</span> instead of closing the program (close
3647 with the exit option on the File menu).
3651 <p class="LITERALLAYOUT">
3652 <tt class="LITERAL"> <span class="emphasis"><i class=
3653 "EMPHASIS">close-button-minimizes 1</i></span><br>
3654 </tt>
3656 <a name="HIDE-CONSOLE"></a>
3658 The <span class="QUOTE">"hide-console"</span> option is specific to
3659 the MS-Win console version of <span class=
3660 "APPLICATION">Privoxy</span>. If this option is used, <span class=
3661 "APPLICATION">Privoxy</span> will disconnect from and hide the
3666 <p class="LITERALLAYOUT">
3667 <tt class="LITERAL"> #<span class="emphasis"><i class=
3668 "EMPHASIS">hide-console</i></span><br>
3669 </tt>
3673 <div class="NAVFOOTER">
3674 <hr width="100%" class="c1">
3675 <table summary="Footer navigation table" width="100%" border="0"
3676 cellpadding="0" cellspacing="0">
3678 <td width="33%" align="left" valign="top">
3679 <a href="configuration.html" accesskey="P">Prev</a>
3681 <td width="34%" align="center" valign="top">
3682 <a href="index.html" accesskey="H">Home</a>
3684 <td width="33%" align="right" valign="top">
3685 <a href="actions-file.html" accesskey="N">Next</a>
3689 <td width="33%" align="left" valign="top">
3690 Privoxy Configuration
3692 <td width="34%" align="center" valign="top">
3695 <td width="33%" align="right" valign="top">