4 >The Main Configuration File</TITLE
7 CONTENT="Modular DocBook HTML Stylesheet Version 1.64
10 TITLE="Privoxy User Manual"
11 HREF="index.html"><LINK
13 TITLE="Privoxy Configuration"
14 HREF="configuration.html"><LINK
17 HREF="actions-file.html"><LINK
20 HREF="../p_doc.css"></HEAD
39 >Privoxy User Manual</TH
47 HREF="configuration.html"
60 HREF="actions-file.html"
74 >8. The Main Configuration File</A
77 > Again, the main configuration file is named <TT
81 Linux/Unix/BSD and OS/2, and <TT
85 Configuration lines consist of an initial keyword followed by a list of
86 values, all separated by whitespace (any number of spaces or tabs). For
95 >confdir /etc/privoxy</I
102 > Assigns the value <TT
109 > and thus indicates that the configuration
110 directory is named <SPAN
112 >"/etc/privoxy/"</SPAN
115 > All options in the config file except for <TT
122 > are optional. Watch out in the below description
123 for what happens if you leave them unset.</P
125 > The main config file controls all aspects of <SPAN
129 operation that are not location dependent (i.e. they apply universally, no matter
130 where you may be surfing).</P
137 >8.1. Configuration and Log File Locations</A
143 > can (and normally does) use a number of
144 other files for additional configuration, help and logging.
145 This section of the configuration file tells <SPAN
149 where to find those other files. </P
167 >The directory where the other configuration files are located</P
179 >/etc/privoxy (Unix) <I
185 > installation dir (Windows) </P
188 >Effect if unset:</DT
209 > When development goes modular and multi-user, the blocker, filter, and
210 per-user config will be stored in subdirectories of <SPAN
214 For now, the configuration directory structure is flat, except for
217 >confdir/templates</TT
218 >, where the HTML templates for CGI
219 output reside (e.g. <SPAN
245 > The directory where all logging takes place (i.e. where <TT
265 >/var/log/privoxy (Unix) <I
271 > installation dir (Windows) </P
274 >Effect if unset:</DT
304 >8.1.3. actionsfile</A
307 NAME="DEFAULT.ACTION"
310 NAME="STANDARD.ACTION"
325 HREF="actions-file.html#ACTIONS"
334 >File name, relative to <TT
350 CLASS="LITERALLAYOUT"
351 > standard # Internal purposes, recommended not editing</P
358 CLASS="LITERALLAYOUT"
359 > default # Main actions file</P
366 CLASS="LITERALLAYOUT"
367 > user # User customizations</P
377 >Effect if unset:</DT
380 > No actions are taken at all. Simple neutral proxying.
390 > lines are permitted, and are in fact recommended!
394 The default values include standard.action, which is used for internal
395 purposes and should be loaded, default.action, which is the
399 > actions file maintained by the developers, and
403 >, where you can make your personal additions.
407 Actions files are where all the per site and per URL configuration is done for
408 ad blocking, cookie management, privacy considerations, etc.
409 There is no point in using <SPAN
413 least one actions file.
425 >8.1.4. filterfile</A
428 NAME="DEFAULT.FILTER"
440 HREF="actions-file.html#FILTER"
449 >File name, relative to <TT
458 >default.filter (Unix) <I
461 > default.filter.txt (Windows)</P
464 >Effect if unset:</DT
467 > No textual content filtering takes place, i.e. all
477 actions in the actions files are turned off
486 >"default.filter"</SPAN
487 > file contains content modification rules
490 >"regular expressions"</SPAN
491 >. These rules permit powerful
492 changes on the content of Web pages, e.g., you could disable your favorite
493 JavaScript annoyances, re-write the actual displayed text, or just have some
501 it appears on a Web page.
524 > The log file to use
531 >File name, relative to <TT
543 > privoxy.log (Windows)</P
546 >Effect if unset:</DT
549 > No log file is used, all log messages go to the console (<TT
559 > The windows version will additionally log to the console.
562 > The logfile is where all logging and error messages are written. The level
563 of detail and number of messages are set with the <TT
567 option (see below). The logfile can be useful for tracking down a problem with
571 > (e.g., it's not blocking an ad you
572 think it should block) but in most cases you probably will never look at it.
575 > Your logfile will grow indefinitely, and you will probably want to
576 periodically remove it. On Unix systems, you can do this with a cron job
580 >). For Red Hat, a <B
584 script has been included.
587 > On SuSE Linux systems, you can place a line like <SPAN
590 +1024k 644 nobody.nogroup"</SPAN
595 the effect that cron.daily will automatically archive, gzip, and empty the
596 log, when it exceeds 1M size.
619 > The file to store intercepted cookies in
626 >File name, relative to <TT
638 > privoxy.jar (Windows)</P
641 >Effect if unset:</DT
644 > Intercepted cookies are not stored at all.
651 > The jarfile may grow to ridiculous sizes over time.
674 > The trust file to use
681 >File name, relative to <TT
692 >Unset (commented out)</I
693 >. When activated: trust (Unix) <I
696 > trust.txt (Windows)</P
699 >Effect if unset:</DT
702 > The whole trust mechanism is turned off.
709 > The trust mechanism is an experimental feature for building white-lists and should
710 be used with care. It is <I
713 > recommended for the casual user.
716 > If you specify a trust file, <SPAN
720 access to sites that are named in the trustfile.
721 You can also mark sites as trusted referrers (with <TT
725 the effect that access to untrusted sites will be granted, if a link from a
726 trusted referrer was used.
727 The link target will then be added to the <SPAN
731 Possible applications include limiting Internet access for children.
737 > operator in the trust file, it may grow considerably over time.
749 >8.1.8. user-manual</A
760 > Location of the <SPAN
770 >A fully qualified URI</P
777 HREF="http://www.privoxy.org/user-manual/"
779 >http://www.privoxy.org/user-manual/</A
783 >Effect if unset:</DT
786 > The default will be used.
793 > The User Manual is used for help hints from some of the internal CGI pages.
794 It is normally packaged with the binary distributions, and would make more
795 sense to have this pointed at a locally installed copy.
798 > A more useful example (Unix):
804 >user-manual  file:///usr/share/doc/privoxy-2.9.14/user-manual/</I
818 >8.2. Local Set-up Documentation</A
821 > If you intend to operate <SPAN
825 that just yourself, it might be a good idea to let them know how to reach
826 you, what you block and why you do that, your policies etc.
833 NAME="TRUST-INFO-URL"
834 >8.2.1. trust-info-url</A
845 > A URL to be displayed in the error page that users will see if access to an untrusted page is denied.
858 >Two example URL are provided</P
861 >Effect if unset:</DT
864 > No links are displayed on the "untrusted" error page.
871 > The value of this option only matters if the experimental trust mechanism has been
878 > If you use the trust mechanism, it is a good idea to write up some on-line
879 documentation about your trust policy and to specify the URL(s) here.
880 Use multiple times for multiple URLs.
883 > The URL(s) should be added to the trustfile as well, so users don't end up
884 locked out from the information on why they were locked out in the first place!
896 >8.2.2. admin-address</A
907 > An email address to reach the proxy administrator.
926 >Effect if unset:</DT
929 > No email address is displayed on error pages and the CGI user interface.
943 are unset, the whole "Local Privoxy Support" box on all generated pages will
955 NAME="PROXY-INFO-URL"
956 >8.2.3. proxy-info-url</A
967 > A URL to documentation about the local <SPAN
971 configuration or policies.
990 >Effect if unset:</DT
993 > No link to local documentation is displayed on error pages and the CGI user interface.
1007 are unset, the whole "Local Privoxy Support" box on all generated pages will
1011 > This URL shouldn't be blocked ;-)
1027 > These options are mainly useful when tracing a problem.
1028 Note that you might also want to invoke
1036 command line option when debugging.
1049 CLASS="VARIABLELIST"
1055 > Key values that determine what information gets logged.
1068 >12289 (i.e.: URLs plus informational and warning messages)</P
1071 >Effect if unset:</DT
1074 > Nothing gets logged.
1081 > The available debug levels are:
1091 CLASS="PROGRAMLISTING"
1092 > debug 1 # show each GET/POST/CONNECT request
1093 debug 2 # show each connection status
1094 debug 4 # show I/O status
1095 debug 8 # show header parsing
1096 debug 16 # log all data into the logfile
1097 debug 32 # debug force feature
1098 debug 64 # debug regular expression filter
1099 debug 128 # debug fast redirects
1100 debug 256 # debug GIF de-animation
1101 debug 512 # Common Log Format
1102 debug 1024 # debug kill pop-ups
1103 debug 4096 # Startup banner and warnings.
1104 debug 8192 # Non-fatal errors</PRE
1111 > To select multiple debug levels, you can either add them or use
1118 > A debug level of 1 is informative because it will show you each request
1121 >1, 4096 and 8192 are highly recommended</I
1123 so that you will notice when things go wrong. The other levels are probably
1124 only of interest if you are hunting down a specific problem. They can produce
1125 a hell of an output (especially 16).
1129 > The reporting of <I
1132 > errors (i.e. ones which crash
1136 >) is always on and cannot be disabled.
1139 > If you want to use CLF (Common Log Format), you should set <SPAN
1146 > and not enable anything else.
1157 NAME="SINGLE-THREADED"
1158 >8.3.2. single-threaded</A
1163 CLASS="VARIABLELIST"
1169 > Whether to run only one server thread
1191 >Effect if unset:</DT
1194 > Multi-threaded (or, where unavailable: forked) operation, i.e. the ability to
1195 serve multiple requests simultaneously.
1202 > This option is only there for debug purposes and you should never
1205 >It will drastically reduce performance.</I
1218 NAME="ACCESS-CONTROL"
1219 >8.4. Access Control and Security</A
1222 > This section of the config file controls the security-relevant aspects
1233 NAME="LISTEN-ADDRESS"
1234 >8.4.1. listen-address</A
1239 CLASS="VARIABLELIST"
1245 > The IP address and TCP port on which <SPAN
1249 listen for client requests.
1275 >Effect if unset:</DT
1278 > Bind to localhost (127.0.0.1), port 8118. This is suitable and recommended for
1279 home users who run <SPAN
1282 > on the same machine as
1290 > You will need to configure your browser(s) to this proxy address and port.
1293 > If you already have another service running on port 8118, or if you want to
1294 serve requests from other machines (e.g. on your local network) as well, you
1295 will need to override the default.
1298 > If you leave out the IP address, <SPAN
1302 bind to all interfaces (addresses) on your machine and may become reachable
1303 from the Internet. In that case, consider using access control lists (ACL's)
1307 > below), or a firewall.
1314 > Suppose you are running <SPAN
1318 a machine which has the address 192.168.0.1 on your local private network
1319 (192.168.0.0) and has another outside connection with a different address.
1320 You want it to serve requests from inside only:
1330 CLASS="PROGRAMLISTING"
1331 > listen-address 192.168.0.1:8118</PRE
1352 CLASS="VARIABLELIST"
1358 > Initial state of "toggle" status
1374 >Effect if unset:</DT
1377 > Act as if toggled on
1384 > If set to 0, <SPAN
1390 >"toggled off"</SPAN
1391 > mode, i.e. behave like a normal, content-neutral
1394 >enable-remote-toggle</TT
1396 below. This is not really useful anymore, since toggling is much easier
1398 HREF="http://config.privoxy.org/toggle"
1402 > than via editing the <TT
1408 > The windows version will only display the toggle icon in the system tray
1409 if this option is present.
1420 NAME="ENABLE-REMOTE-TOGGLE"
1421 >8.4.3. enable-remote-toggle</A
1426 CLASS="VARIABLELIST"
1432 > Whether or not the <A
1433 HREF="http://config.privoxy.org/toggle"
1453 >Effect if unset:</DT
1456 > The web-based toggle feature is disabled.
1463 > When toggled off, <SPAN
1466 > acts like a normal,
1467 content-neutral proxy, i.e. it acts as if none of the actions applied to
1471 > For the time being, access to the toggle feature can <I
1475 controlled separately by <SPAN
1478 > or HTTP authentication,
1479 so that everybody who can access <SPAN
1490 toggle it for all users. So this option is <I
1494 for multi-user environments with untrusted users.
1497 > Note that you must have compiled <SPAN
1501 support for this feature, otherwise this option has no effect.
1512 NAME="ENABLE-EDIT-ACTIONS"
1513 >8.4.4. enable-edit-actions</A
1518 CLASS="VARIABLELIST"
1524 > Whether or not the <A
1525 HREF="http://config.privoxy.org/show-status"
1545 >Effect if unset:</DT
1548 > The web-based actions file editor is disabled.
1555 > For the time being, access to the editor can <I
1559 controlled separately by <SPAN
1562 > or HTTP authentication,
1563 so that everybody who can access <SPAN
1574 modify its configuration for all users. So this option is <I
1578 > for multi-user environments with untrusted users.
1581 > Note that you must have compiled <SPAN
1585 support for this feature, otherwise this option has no effect.
1597 >8.4.5. ACLs: permit-access and deny-access</A
1608 CLASS="VARIABLELIST"
1614 > Who can access what.
1656 > are IP addresses in dotted decimal notation or valid
1668 > are subnet masks in CIDR notation, i.e. integer
1669 values from 2 to 30 representing the length (in bits) of the network address. The masks and the whole
1670 destination part are optional.
1683 >Effect if unset:</DT
1686 > Don't restrict access further than implied by <TT
1696 > Access controls are included at the request of ISPs and systems
1697 administrators, and <I
1699 >are not usually needed by individual users</I
1701 For a typical home user, it will normally suffice to ensure that
1705 > only listens on the localhost or internal (home)
1706 network address by means of the <TT
1712 > Please see the warnings in the FAQ that this proxy is not intended to be a substitute
1713 for a firewall or to encourage anyone to defer addressing basic security
1717 > Multiple ACL lines are OK.
1718 If any ACLs are specified, then the <SPAN
1722 talks only to IP addresses that match at least one <TT
1726 and don't match any subsequent <TT
1729 > line. In other words, the
1730 last match wins, with the default being <TT
1739 > is using a forwarder (see <TT
1743 for a particular destination URL, the <TT
1749 that is examined is the address of the forwarder and <I
1753 of the ultimate target. This is necessary because it may be impossible for the local
1757 > to determine the IP address of the
1758 ultimate target (that's often what gateways are used for).
1761 > You should prefer using IP addresses over DNS names, because the address lookups take
1762 time. All DNS names must resolve! You can <I
1765 > use domain patterns
1769 > or partial domain names. If a DNS name resolves to multiple
1770 IP addresses, only the first one is used.
1773 > Denying access to particular sites by ACL may have undesired side effects
1774 if the site in question is hosted on a machine which also hosts other sites.
1781 > Explicitly define the default behavior if no ACL and
1789 is OK. The absence of a <TT
1798 > destination addresses are OK:
1809 > permit-access localhost</PRE
1816 > Allow any host on the same class C subnet as www.privoxy.org access to
1817 nothing but www.example.com:
1828 > permit-access www.privoxy.org/24 www.example.com/32</PRE
1835 > Allow access from any host on the 26-bit subnet 192.168.45.64 to anywhere,
1836 with the exception that 192.168.45.73 may not access www.dirty-stuff.example.com:
1847 > permit-access 192.168.45.64/26
1848 deny-access 192.168.45.73 www.dirty-stuff.example.com</PRE
1864 >8.4.6. buffer-limit</A
1869 CLASS="VARIABLELIST"
1875 > Maximum size of the buffer for content filtering.
1891 >Effect if unset:</DT
1894 > Use a 4MB (4096 KB) limit.
1901 > For content filtering, i.e. the <TT
1908 > actions, it is necessary that
1912 > buffers the entire document body.
1913 This can be potentially dangerous, since a server could just keep sending
1914 data indefinitely and wait for your RAM to exhaust -- with nasty consequences.
1918 > When a document buffer size reaches the <TT
1922 flushed to the client unfiltered and no further attempt to
1923 filter the rest of the document is made. Remember that there may be multiple threads
1924 running, which might require up to <TT
1931 >, unless you have enabled <SPAN
1933 >"single-threaded"</SPAN
1951 > This feature allows routing of HTTP requests through a chain of
1953 It can be used to better protect privacy and confidentiality when
1954 accessing specific domains by routing requests to those domains
1955 through an anonymous public proxy (see e.g. <A
1956 HREF="http://www.multiproxy.org/anon_list.htm"
1958 >http://www.multiproxy.org/anon_list.htm</A
1960 Or to use a caching proxy to speed up browsing. Or chaining to a parent
1961 proxy may be necessary because the machine that <SPAN
1965 runs on has no direct Internet access.</P
1967 > Also specified here are SOCKS proxies. <SPAN
1971 supports the SOCKS 4 and SOCKS 4A protocols.</P
1983 CLASS="VARIABLELIST"
1989 > To which parent HTTP proxy specific requests should be routed.
2025 > is a domain name pattern (see the
2026 chapter on domain matching in the <TT
2035 > is the address of the parent HTTP proxy
2036 as an IP addresses in dotted decimal notation or as a valid DNS name (or <SPAN
2042 >"no forwarding"</SPAN
2049 > parameters are TCP ports, i.e. integer
2050 values from 1 to 64535
2063 >Effect if unset:</DT
2066 > Don't use parent HTTP proxies.
2081 >, then requests are not
2082 forwarded to another HTTP proxy but are made directly to the web servers.
2085 > Multiple lines are OK, they are checked in sequence, and the last match wins.
2092 > Everything goes to an example anonymizing proxy, except SSL on port 443 (which it doesn't handle):
2103 > forward .* anon-proxy.example.org:8080
2111 > Everything goes to our example ISP's caching proxy, except for requests
2112 to that ISP's sites:
2123 > forward .*. caching-proxy.example-isp.net:8000
2124 forward .example-isp.net .</PRE
2140 >8.5.2. forward-socks4 and forward-socks4a</A
2143 NAME="FORWARD-SOCKS4"
2146 NAME="FORWARD-SOCKS4A"
2151 CLASS="VARIABLELIST"
2157 > Through which SOCKS proxy (and to which parent HTTP proxy) specific requests should be routed.
2204 > is a domain name pattern (see the
2205 chapter on domain matching in the <TT
2220 are IP addresses in dotted decimal notation or valid DNS names (<TT
2231 >"no HTTP forwarding"</SPAN
2232 >), and the optional
2238 > parameters are TCP ports, i.e. integer values from 1 to 64535
2251 >Effect if unset:</DT
2254 > Don't use SOCKS proxies.
2261 > Multiple lines are OK, they are checked in sequence, and the last match wins.
2264 > The difference between <TT
2269 >forward-socks4a</TT
2271 is that in the SOCKS 4A protocol, the DNS resolution of the target hostname happens on the SOCKS
2272 server, while in SOCKS 4 it happens locally.
2283 >, then requests are not
2284 forwarded to another HTTP proxy but are made (HTTP-wise) directly to the web servers, albeit through
2292 > From the company example.com, direct connections are made to all
2296 > domains, but everything outbound goes through
2297 their ISP's proxy by way of example.com's corporate SOCKS 4A gateway to
2309 > forward-socks4a .*. socks-gw.example.com:1080 www-cache.example-isp.net:8080
2310 forward .example.com .</PRE
2317 > A rule that uses a SOCKS 4 gateway for all destinations but no HTTP parent looks like this:
2328 > forward-socks4 .*. socks-gw.example.com:1080 .</PRE
2343 NAME="ADVANCED-FORWARDING-EXAMPLES"
2344 >8.5.3. Advanced Forwarding Examples</A
2347 > If you have links to multiple ISPs that provide various special content
2348 only to their subscribers, you can configure multiple <SPAN
2352 which have connections to the respective ISPs to act as forwarders to each other, so that
2356 > users can see the internal content of all ISPs.</P
2358 > Assume that host-a has a PPP connection to isp-a.net. And host-b has a PPP connection to
2359 isp-b.net. Both run <SPAN
2363 configuration can look like this:</P
2376 forward .isp-b.net host-b:8118</PRE
2393 forward .isp-a.net host-a:8118</PRE
2399 > Now, your users can set their browser's proxy to use either
2400 host-a or host-b and be able to browse the internal content
2401 of both isp-a and isp-b.</P
2403 > If you intend to chain <SPAN
2410 > locally, then chain as
2413 >browser -> squid -> privoxy</TT
2414 > is the recommended way. </P
2416 > Assuming that <SPAN
2423 run on the same box, your squid configuration could then look like this:</P
2433 > # Define Privoxy as parent proxy (without ICP)
2434 cache_peer 127.0.0.1 parent 8118 7 no-query
2436 # Define ACL for protocol FTP
2439 # Do not forward FTP requests to Privoxy
2440 always_direct allow ftp
2442 # Forward all the rest to Privoxy
2443 never_direct allow all</PRE
2449 > You would then need to change your browser's proxy settings to <SPAN
2452 >'s address and port.
2453 Squid normally uses port 3128. If unsure consult <TT
2468 >8.6. Windows GUI Options</A
2474 > has a number of options specific to the
2475 Windows GUI interface:</P
2477 NAME="ACTIVITY-ANIMATION"
2482 >"activity-animation"</SPAN
2487 > icon will animate when
2491 > is active. To turn off, set to 0.</P
2496 CLASS="LITERALLAYOUT"
2499 >activity-animation 1</I
2501 </P
2511 >"log-messages"</SPAN
2516 > will log messages to the console
2522 CLASS="LITERALLAYOUT"
2527 </P
2532 NAME="LOG-BUFFER-SIZE"
2538 >"log-buffer-size"</SPAN
2539 > is set to 1, the size of the log buffer,
2540 i.e. the amount of memory used for the log messages displayed in the
2541 console window, will be limited to <SPAN
2543 >"log-max-lines"</SPAN
2546 > Warning: Setting this to 0 will result in the buffer to grow infinitely and
2547 eat up all your memory!</P
2552 CLASS="LITERALLAYOUT"
2555 >log-buffer-size 1</I
2557 </P
2562 NAME="LOG-MAX-LINES"
2567 >log-max-lines</SPAN
2568 > is the maximum number of lines held
2569 in the log buffer. See above.</P
2574 CLASS="LITERALLAYOUT"
2577 >log-max-lines 200</I
2579 </P
2584 NAME="LOG-HIGHLIGHT-MESSAGES"
2589 >"log-highlight-messages"</SPAN
2594 > will highlight portions of the log
2595 messages with a bold-faced font:</P
2600 CLASS="LITERALLAYOUT"
2603 >log-highlight-messages 1</I
2605 </P
2610 NAME="LOG-FONT-NAME"
2613 > The font used in the console window:</P
2618 CLASS="LITERALLAYOUT"
2621 >log-font-name Comic Sans MS</I
2623 </P
2628 NAME="LOG-FONT-SIZE"
2631 > Font size used in the console window:</P
2636 CLASS="LITERALLAYOUT"
2641 </P
2646 NAME="SHOW-ON-TASK-BAR"
2652 >"show-on-task-bar"</SPAN
2653 > controls whether or not
2657 > will appear as a button on the Task bar
2663 CLASS="LITERALLAYOUT"
2666 >show-on-task-bar 0</I
2668 </P
2673 NAME="CLOSE-BUTTON-MINIMIZES"
2678 >"close-button-minimizes"</SPAN
2679 > is set to 1, the Windows close
2680 button will minimize <SPAN
2683 > instead of closing
2684 the program (close with the exit option on the File menu).</P
2689 CLASS="LITERALLAYOUT"
2692 >close-button-minimizes 1</I
2694 </P
2704 >"hide-console"</SPAN
2705 > option is specific to the MS-Win console
2709 >. If this option is used,
2713 > will disconnect from and hide the
2719 CLASS="LITERALLAYOUT"
2724 </P
2745 HREF="configuration.html"
2761 HREF="actions-file.html"