5 $Id: user-manual.sgml,v 1.60 2002/03/27 01:57:34 hal9 Exp $
7 The user manual gives users information on how to install, configure and use
8 Privoxy. Privoxy is a web proxy with advanced filtering capabilities for
9 protecting privacy, filtering web page content, managing cookies, controlling
10 access, and removing ads, banners, pop-ups and other obnoxious Internet Junk.
11 Privoxy has a very flexible configuration and can be customized to suit
12 individual needs and tastes. Privoxy has application for both stand-alone
13 systems and multi-user networks.
15 You can find the latest version of the user manual at http://www.privoxy.org/
18 -------------------------------------------------------------------------------
34 3. Privoxy Configuration
36 3.1. Controlling Privoxy with Your Web Browser
37 3.2. Configuration Files Overview
38 3.3. The Main Configuration File
40 3.3.1. Defining Other Configuration Files
41 3.3.2. Other Configuration Options
42 3.3.3. Access Control List (ACL)
44 3.3.5. Windows GUI Options
48 3.4.1. URL Domain and Path Syntax
55 4. Quickstart to Using Privoxy
57 4.1. Command Line Options
59 5. Contacting the Developers, Bug Reporting and Feature Requests
60 6. Copyright and History
68 8.1. Regular Expressions
69 8.2. Privoxy's Internal Pages
70 8.3. Anatomy of an Action
74 Privoxy is a web proxy with advanced filtering capabilities for protecting
75 privacy, filtering web page content, managing cookies, controlling access, and
76 removing ads, banners, pop-ups and other obnoxious Internet junk. Privoxy has a
77 very flexible configuration and can be customized to suit individual needs and
78 tastes. Privoxy has application for both stand-alone systems and multi-user
81 Privoxy is based on the code of the Internet Junkbuster. Junkbuster was
82 originally written by JunkBusters Corporation, and was released as free
83 open-source software under the GNU GPL. Stefan Waldherr made many improvements,
84 and started the SourceForge project to continue development.
86 Privoxy continues the Junkbuster tradition, but adds many refinements and
89 This documentation is included with the current BETA version of Privoxy and is
90 mostly complete at this point. The most up to date reference for the time being
91 is still the comments in the source files and in the individual configuration
92 files. Development of version 3.0 is currently nearing completion, and includes
93 many significant changes and enhancements over earlier versions. The target
94 release date for stable v3.0 is "soon" ;-)
96 Since this is a BETA version, not all new features are well tested. This
97 documentation may be slightly out of sync as a result (especially with CVS
98 sources). And there may be bugs, though hopefully not many!
100 -------------------------------------------------------------------------------
104 In addition to Internet Junkbuster's traditional feature of ad and banner
105 blocking and cookie management, Privoxy provides new features, some of them
106 currently under development:
108 * Integrated browser based configuration and control utility (http://p.p).
109 Browser-based tracing of rule and filter effects.
111 * Blocking of annoying pop-up browser windows.
113 * HTTP/1.1 compliant (most, but not all 1.1 features are supported).
115 * Support for Perl Compatible Regular Expressions in the configuration files,
116 and generally a more sophisticated and flexible configuration syntax over
121 * Web page content filtering (removes banners based on size, invisible
122 "web-bugs", JavaScript, pop-ups, status bar abuse, etc.)
124 * Bypass many click-tracking scripts (avoids script redirection).
126 * Multi-threaded (POSIX and native threads).
128 * Auto-detection and re-reading of config file changes.
130 * User-customizable HTML templates (e.g. 404 error page).
132 * Improved cookie management features (e.g. session based cookies).
134 * Builds from source on most UNIX-like systems. Packages available for: Linux
135 (RedHat, SuSE, or Debian), Windows, Sun Solaris, Mac OSX, OS/2, HP-UX 11
138 * In addition, the configuration is much more powerful and versatile
141 -------------------------------------------------------------------------------
145 Privoxy is available as raw source code, or pre-compiled binaries. See the
146 Privoxy Home Page for binaries and current release info. Privoxy is also
147 available via CVS. This is the recommended approach at this time. But please be
148 aware that CVS is constantly changing, and it may break in mysterious ways.
150 -------------------------------------------------------------------------------
154 For gzipped tar archives, unpack the source:
156 tar xzvf privoxy-2.9.13-beta-src* [.tgz or .tar.gz]
157 cd privoxy-2.9.13-beta
160 For retrieving the current CVS sources, you'll need the CVS package installed
161 first. To download CVS source:
163 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
164 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co current
168 This will create a directory named current/, which will contain the source
171 Then, in either case, to build from tarball/CVS source:
173 ./configure (--help to see options)
174 make (the make from gnu, gmake for *BSD)
176 make -n install (to see where all the files will go)
177 make install (to really install)
180 For Redhat and SuSE Linux RPM packages, see below.
182 -------------------------------------------------------------------------------
186 To build Redhat RPM packages, install source as above. Then:
194 This will create both binary and src RPMs in the usual places. Example:
196 /usr/src/redhat/RPMS/i686/privoxy-2.9.11-1.i686.rpm
198 /usr/src/redhat/SRPMS/privoxy-2.9.11-1.src.rpm
200 To install, of course:
202 rpm -Uvv /usr/src/redhat/RPMS/i686/privoxy-2.9.11-1.i686.rpm
205 This will place the Privoxy configuration files in /etc/privoxy/, and log files
206 in /var/log/privoxy/.
208 -------------------------------------------------------------------------------
212 To build SuSE RPM packages, install source as above. Then:
220 This will create both binary and src RPMs in the usual places. Example:
222 /usr/src/packages/RPMS/i686/privoxy-2.9.11-1.i686.rpm
224 /usr/src/packages/SRPMS/privoxy-2.9.11-1.src.rpm
226 To install, of course:
228 rpm -Uvv /usr/src/packages/RPMS/i686/privoxy-2.9.11-1.i686.rpm
231 This will place the Privoxy configuration files in /etc/privoxy/, and log files
232 in /var/log/privoxy/.
234 -------------------------------------------------------------------------------
238 Privoxy is packaged in a WarpIN self- installing archive. The self-installing
239 program will be named depending on the release version, something like:
240 ijbos2_setup_1.2.3.exe. In order to install it, simply run this executable or
241 double-click on its icon and follow the WarpIN installation panels. A shadow of
242 the Privoxy executable will be placed in your startup folder so it will start
243 automatically whenever OS/2 starts.
245 The directory you choose to install Privoxy into will contain all of the
248 If you would like to build binary images on OS/2 yourself, you will need a few
249 Unix-like tools: autoconf, autoheader and sh. These tools will be used to
250 create the required config.h file, which is not part of the source distribution
251 because it differs based on platform. You will also need a compiler. The
252 distribution has been created using IBM VisualAge compilers, but you can use
253 any compiler you like. GCC/EMX has the disadvantage of needing to be
254 single-threaded due to a limitation of EMX's implementation of the select()
257 In addition to needing the source code distribution as outlined earlier, you
258 will want to extract the os2seutp directory from CVS:
260 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
261 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co os2setup
264 This will create a directory named os2setup/, which will contain the
265 Makefile.vac makefile and os2build.cmd which is used to completely create the
266 binary distribution. The sequence of events for building the executable for
267 yourself goes something like this:
274 nmake -f Makefile.vac
277 You will see this sequence laid out in os2build.cmd.
279 -------------------------------------------------------------------------------
283 Click-click. (I need help on this. Not a clue here. Also for configuration
286 -------------------------------------------------------------------------------
290 Some quick notes on other Operating Systems.
292 For FreeBSD (and other *BSDs?), the build will require gmake instead of the
293 included make. gmake is available from http://www.gnu.org. The rest should be
294 the same as above for Linux/Unix.
296 -------------------------------------------------------------------------------
298 3. Privoxy Configuration
300 All Privoxy configuration is kept in text files. These files can be edited with
301 a text editor. Many important aspects of Privoxy can also be controlled easily
304 -------------------------------------------------------------------------------
306 3.1. Controlling Privoxy with Your Web Browser
308 Privoxy can be reached by the special URL http://p.p/ (or alternately http://
309 www.privoxy.org/config/), which is an internal page. You will see the following
312 Please choose from the following options:
314 * Show information about the current configuration
315 * Show the source code version numbers
316 * Show the client's request headers.
317 * Show which actions apply to a URL and why
318 * Toggle Privoxy on or off
319 * Edit the actions list
323 This should be self-explanatory. Note the last item is an editor for the
324 "actions list", which is where much of the ad, banner, cookie, and URL blocking
325 magic is configured as well as other advanced features of Privoxy. This is an
326 easy way to adjust various aspects of Privoxy configuration. The actions file,
327 and other configuration files, are explained in detail below. Privoxy will
328 automatically detect any changes to these files.
330 "Toggle Privoxy On or Off" is handy for sites that might have problems with
331 your current actions and filters, or just to test if a site misbehaves, whether
332 it is Privoxy causing the problem or not. Privoxy continues to run as a proxy
333 in this case, but all filtering is disabled.
335 -------------------------------------------------------------------------------
337 3.2. Configuration Files Overview
339 For Unix, *BSD and Linux, all configuration files are located in /etc/privoxy/
340 by default. For MS Windows, OS/2, and AmigaOS these are all in the same
341 directory as the Privoxy executable. The name and number of configuration files
342 has changed from previous versions, and is subject to change as development
345 The installed defaults provide a reasonable starting point, though possibly
346 aggressive by some standards. For the time being, there are only three default
347 configuration files (this will change in time):
349 * The main configuration file is named config on Linux, Unix, BSD, OS/2, and
350 AmigaOS and config.txt on Windows.
352 * The default.action file is used to define various "actions" relating to
353 images, banners, pop-ups, access restrictions, banners and cookies. There
354 is a CGI based editor for this file that can be accessed via http://p.p.
355 (Other actions files are included as well with differing levels of
356 filtering and blocking, e.g. ijb-basic.action.)
358 * The default.filter file can be used to re-write the raw page content,
359 including viewable text as well as embedded HTML and JavaScript, and
360 whatever else lurks on any given web page.
362 default.action and default.filter can use Perl style regular expressions for
363 maximum flexibility. All files use the "#" character to denote a comment. Such
364 lines are not processed by Privoxy. After making any changes, there is no need
365 to restart Privoxy in order for the changes to take effect. Privoxy should
366 detect such changes automatically.
368 While under development, the configuration content is subject to change. The
369 below documentation may not be accurate by the time you read this. Also, what
370 constitutes a "default" setting, may change, so please check all your
371 configuration files on important issues.
373 -------------------------------------------------------------------------------
375 3.3. The Main Configuration File
377 Again, the main configuration file is named config on Linux/Unix/BSD and OS/2,
378 and config.txt on Windows. Configuration lines consist of an initial keyword
379 followed by a list of values, all separated by whitespace (any number of spaces
380 or tabs). For example:
382 blockfile blocklist.ini
385 Indicates that the blockfile is named "blocklist.ini". (A default installation
388 A "#" indicates a comment. Any part of a line following a "#" is ignored,
389 except if the "#" is preceded by a "\".
391 Thus, by placing a "#" at the start of an existing configuration line, you can
392 make it a comment and it will be treated as if it weren't there. This is called
393 "commenting out" an option and can be useful to turn off features: If you
394 comment out the "logfile" line, Privoxy will not log to a file at all. Watch
395 for the "default:" section in each explanation to see what happens if the
396 option is left unset (or commented out).
398 Long lines can be continued on the next line by using a "\" as the very last
401 There are various aspects of Privoxy behavior that can be tuned.
403 -------------------------------------------------------------------------------
405 3.3.1. Defining Other Configuration Files
407 Privoxy can use a number of other files to tell it what ads to block, what
408 cookies to accept, etc. This section of the configuration file tells Privoxy
409 where to find all those other files.
411 On Windows and AmigaOS, Privoxy looks for these files in the same directory as
412 the executable. On Unix and OS/2, Privoxy looks for these files in the current
413 working directory. In either case, an absolute path name can be used to avoid
416 When development goes modular and multi-user, the blocker, filter, and per-user
417 config will be stored in subdirectories of "confdir". For now, only confdir/
418 templates is used for storing HTML templates for CGI results.
420 The location of the configuration files:
422 confdir /etc/privoxy # No trailing /, please.
425 The directory where all logging (i.e. logfile and jarfile) takes place. No
426 trailing "/", please:
428 logdir /var/log/privoxy
431 Note that all file specifications below are relative to the above two
434 The "default.action" file contains patterns to specify the actions to apply to
435 requests for each site. Default: Cookies to and from all destinations are kept
436 only during the current browser session (i.e. they are not saved to disk).
437 Pop-ups are disabled for all sites. All sites are filtered through selected
438 sections of "default.filter". No sites are blocked. Privoxy displays a
439 checkboard type pattern for filtered ads and other images. The syntax of this
440 file is explained in detail below. Other "actions" files are included, and you
441 are free to use any of them. They have varying degrees of aggressiveness.
443 actionsfile default.action
446 The "default.filter" file contains content modification rules that use "regular
447 expressions". These rules permit powerful changes on the content of Web pages,
448 e.g., you could disable your favorite JavaScript annoyances, re-write the
449 actual displayed text, or just have some fun replacing "Microsoft" with
450 "MicroSuck" wherever it appears on a Web page. Default: whatever the developers
453 Filtering requires buffering the page content, which may appear to slow down
454 page rendering since nothing is displayed until all content has passed the
455 filters. (It does not really take longer, but seems that way since the page is
456 not incrementally displayed.) This effect will be more noticeable on slower
459 filterfile default.filter
462 The logfile is where all logging and error messages are written. The logfile
463 can be useful for tracking down a problem with Privoxy (e.g., it's not blocking
464 an ad you think it should block) but in most cases you probably will never look
467 Your logfile will grow indefinitely, and you will probably want to periodically
468 remove it. On Unix systems, you can do this with a cron job (see "man cron").
469 For Redhat, a logrotate script has been included.
471 On SuSE Linux systems, you can place a line like "/var/log/privoxy.* +1024k 644
472 nobody.nogroup" in /etc/logfiles, with the effect that cron.daily will
473 automatically archive, gzip, and empty the log, when it exceeds 1M size.
475 Default: Log to the a file named logfile. Comment out to disable logging.
480 The "jarfile" defines where Privoxy stores the cookies it intercepts. Note that
481 if you use a "jarfile", it may grow quite large. Default: Don't store
487 If you specify a "trustfile", Privoxy will only allow access to sites that are
488 named in the trustfile. You can also mark sites as trusted referrers, with the
489 effect that access to untrusted sites will be granted, if a link from a trusted
490 referrer was used. The link target will then be added to the "trustfile". This
491 is a very restrictive feature that typical users most probably want to leave
492 disabled. Default: Disabled, don't use the trust mechanism.
497 If you use the trust mechanism, it is a good idea to write up some on-line
498 documentation about your blocking policy and to specify the URL(s) here. They
499 will appear on the page that your users receive when they try to access
500 untrusted content. Use multiple times for multiple URLs. Default: Don't display
501 links on the "untrusted" info page.
503 trust-info-url http://www.your-site.com/why_we_block.html
504 trust-info-url http://www.your-site.com/what_we_allow.html
507 -------------------------------------------------------------------------------
509 3.3.2. Other Configuration Options
511 This part of the configuration file contains options that control how Privoxy
514 "Admin-address" should be set to the email address of the proxy administrator.
515 It is used in many of the proxy-generated pages. Default: fill@me.in.please.
517 #admin-address fill@me.in.please
520 "Proxy-info-url" can be set to a URL that contains more info about this Privoxy
521 installation, it's configuration and policies. It is used in many of the
522 proxy-generated pages and its use is highly recommended in multi-user
523 installations, since your users will want to know why certain content is
524 blocked or modified. Default: Don't show a link to on-line documentation.
526 proxy-info-url http://www.your-site.com/proxy.html
529 "Listen-address" specifies the address and port where Privoxy will listen for
530 connections from your Web browser. The default is to listen on the localhost
531 port 8118, and this is suitable for most users. (In your web browser, under
532 proxy configuration, list the proxy server as "localhost" and the port as
535 If you already have another service running on port 8118, or if you want to
536 serve requests from other machines (e.g. on your local network) as well, you
537 will need to override the default. The syntax is "listen-address
538 [<ip-address>]:<port>". If you leave out the IP address, Privoxy will bind to
539 all interfaces (addresses) on your machine and may become reachable from the
540 Internet. In that case, consider using access control lists (acl's) (see
541 "aclfile" above), or a firewall.
543 For example, suppose you are running Privoxy on a machine which has the address
544 192.168.0.1 on your local private network (192.168.0.0) and has another outside
545 connection with a different address. You want it to serve requests from inside
548 listen-address 192.168.0.1:8118
551 If you want it to listen on all addresses (including the outside connection):
556 If you do this, consider using ACLs (see "aclfile" above). Note: you will need
557 to point your browser(s) to the address and port that you have configured here.
558 Default: localhost:8118 (127.0.0.1:8118).
560 The debug option sets the level of debugging information to log in the logfile
561 (and to the console in the Windows version). A debug level of 1 is informative
562 because it will show you each request as it happens. Higher levels of debug are
563 probably only of interest to developers.
565 debug 1 # GPC = show each GET/POST/CONNECT request
566 debug 2 # CONN = show each connection status
567 debug 4 # IO = show I/O status
568 debug 8 # HDR = show header parsing
569 debug 16 # LOG = log all data into the logfile
570 debug 32 # FRC = debug force feature
571 debug 64 # REF = debug regular expression filter
572 debug 128 # = debug fast redirects
573 debug 256 # = debug GIF de-animation
574 debug 512 # CLF = Common Log Format
575 debug 1024 # = debug kill pop-ups
576 debug 4096 # INFO = Startup banner and warnings.
577 debug 8192 # ERROR = Non-fatal errors
580 It is highly recommended that you enable ERROR reporting (debug 8192), at least
581 until v3.0 is released.
583 The reporting of FATAL errors (i.e. ones which crash Privoxy) is always on and
586 If you want to use CLF (Common Log Format), you should set "debug 512" ONLY, do
587 not enable anything else.
589 Multiple "debug" directives, are OK - they're logical-OR'd together.
591 debug 15 # same as setting the first 4 listed above
598 debug 8192 # Errors - *we highly recommended enabling this*
601 Privoxy normally uses "multi-threading", a software technique that permits it
602 to handle many different requests simultaneously. In some cases you may wish to
603 disable this -- particularly if you're trying to debug a problem. The
604 "single-threaded" option forces Privoxy to handle requests sequentially.
605 Default: Multi-threaded mode.
610 "toggle" allows you to temporarily disable all Privoxy's filtering. Just set
613 The Windows version of Privoxy puts an icon in the system tray, which also
614 allows you to change this option. If you right-click on that icon (or select
615 the "Options" menu), one choice is "Enable". Clicking on enable toggles Privoxy
616 on and off. This is useful if you want to temporarily disable Privoxy, e.g., to
617 access a site that requires cookies which you would otherwise have blocked.
618 This can also be toggled via a web browser at the Privoxy internal address of
619 http://p.p on any platform.
621 "toggle 1" means Privoxy runs normally, "toggle 0" means that Privoxy becomes a
622 non-anonymizing non-blocking proxy. Default: 1 (on).
627 For content filtering, i.e. the "+filter" and "+deanimate-gif" actions, it is
628 necessary that Privoxy buffers the entire document body. This can be
629 potentially dangerous, since a server could just keep sending data indefinitely
630 and wait for your RAM to exhaust. With nasty consequences.
632 The buffer-limit option lets you set the maximum size in Kbytes that each
633 buffer may use. When the documents buffer exceeds this size, it is flushed to
634 the client unfiltered and no further attempt to filter the rest of it is made.
635 Remember that there may multiple threads running, which might require
636 increasing the "buffer-limit" Kbytes each, unless you have enabled
637 "single-threaded" above.
642 To enable the web-based default.action file editor set enable-edit-actions to
643 1, or 0 to disable. Note that you must have compiled Privoxy with support for
644 this feature, otherwise this option has no effect. This internal page can be
645 reached at http://p.p.
647 Security note: If this is enabled, anyone who can use the proxy can edit the
648 actions file, and their changes will affect all users. For shared proxies, you
649 probably want to disable this. Default: enabled.
651 enable-edit-actions 1
654 Allow Privoxy to be toggled on and off remotely, using your web browser. Set
655 "enable-remote-toggle"to 1 to enable, and 0 to disable. Note that you must have
656 compiled Privoxy with support for this feature, otherwise this option has no
659 Security note: If this is enabled, anyone who can use the proxy can toggle it
660 on or off (see http://p.p), and their changes will affect all users. For shared
661 proxies, you probably want to disable this. Default: enabled.
663 enable-remote-toggle 1
666 -------------------------------------------------------------------------------
668 3.3.3. Access Control List (ACL)
670 Access controls are included at the request of some ISPs and systems
671 administrators, and are not usually needed by individual users. Please note the
672 warnings in the FAQ that this proxy is not intended to be a substitute for a
673 firewall or to encourage anyone to defer addressing basic security weaknesses.
675 If no access settings are specified, the proxy talks to anyone that connects.
676 If any access settings file are specified, then the proxy talks only to IP
677 addresses permitted somewhere in this file and not denied later in this file.
679 Summary -- if using an ACL:
681 Client must have permission to receive service.
683 LAST match in ACL wins.
685 Default behavior is to deny service.
687 The syntax for an entry in the Access Control List is:
689 ACTION SRC_ADDR[/SRC_MASKLEN] [ DST_ADDR[/DST_MASKLEN] ]
692 Where the individual fields are:
694 ACTION = "permit-access" or "deny-access"
696 SRC_ADDR = client hostname or dotted IP address
697 SRC_MASKLEN = number of bits in the subnet mask for the source
699 DST_ADDR = server or forwarder hostname or dotted IP address
700 DST_MASKLEN = number of bits in the subnet mask for the target
703 The field separator (FS) is whitespace (space or tab).
705 IMPORTANT NOTE: If Privoxy is using a forwarder (see below) or a gateway for a
706 particular destination URL, the DST_ADDR that is examined is the address of the
707 forwarder or the gateway and NOT the address of the ultimate target. This is
708 necessary because it may be impossible for the local Privoxy to determine the
709 address of the ultimate target (that's often what gateways are used for).
711 Here are a few examples to show how the ACL features work:
713 "localhost" is OK -- no DST_ADDR implies that ALL destination addresses are OK:
715 permit-access localhost
718 A silly example to illustrate permitting any host on the class-C subnet with
719 Privoxy to go anywhere:
721 permit-access www.privoxy.com/24
724 Except deny one particular IP address from using it at all:
726 deny-access ident.privoxy.com
729 You can also specify an explicit network address and subnet mask. Explicit
730 addresses do not have to be resolved to be used.
732 permit-access 207.153.200.0/24
735 A subnet mask of 0 matches anything, so the next line permits everyone.
737 permit-access 0.0.0.0/0
740 Note, you cannot say:
745 to allow all *.org domains. Every IP address listed must resolve fully.
747 An ISP may want to provide a Privoxy that is accessible by "the world" and yet
748 restrict use of some of their private content to hosts on its internal network
749 (i.e. its own subscribers). Say, for instance the ISP owns the Class-B IP
750 address block 123.124.0.0 (a 16 bit netmask). This is how they could do it:
752 permit-access 0.0.0.0/0 0.0.0.0/0 # other clients can go anywhere
753 # with the following exceptions:
755 deny-access 0.0.0.0/0 123.124.0.0/16 # block all external requests for
756 # sites on the ISP's network
758 permit 0.0.0.0/0 www.my_isp.com # except for the ISP's main
761 permit 123.124.0.0/16 0.0.0.0/0 # the ISP's clients can go
765 Note that if some hostnames are listed with multiple IP addresses, the primary
766 value returned by DNS (via gethostbyname()) is used. Default: Anyone can access
769 -------------------------------------------------------------------------------
773 This feature allows chaining of HTTP requests via multiple proxies. It can be
774 used to better protect privacy and confidentiality when accessing specific
775 domains by routing requests to those domains to a special purpose filtering
776 proxy such as lpwa.com. Or to use a caching proxy to speed up browsing.
778 It can also be used in an environment with multiple networks to route requests
779 via multiple gateways allowing transparent access to multiple networks without
780 having to modify browser configurations.
782 Also specified here are SOCKS proxies. Privoxy SOCKS 4 and SOCKS 4A. The
783 difference is that SOCKS 4A will resolve the target hostname using DNS on the
784 SOCKS server, not our local DNS client.
786 The syntax of each line is:
788 forward target_domain[:port] http_proxy_host[:port]
789 forward-socks4 target_domain[:port] socks_proxy_host[:port] http_proxy_host[:
791 forward-socks4a target_domain[:port] socks_proxy_host[:port] http_proxy_host[:
795 If http_proxy_host is ".", then requests are not forwarded to a HTTP proxy but
796 are made directly to the web servers.
798 Lines are checked in sequence, and the last match wins.
800 There is an implicit line equivalent to the following, which specifies that
801 anything not finding a match on the list is to go out without forwarding or
802 gateway protocol, like so:
804 forward .* . # implicit
807 In the following common configuration, everything goes to Lucent's LPWA, except
808 SSL on port 443 (which it doesn't handle):
810 forward .* lpwa.com:8000
814 Some users have reported difficulties related to LPWA's use of "." as the last
815 element of the domain, and have said that this can be fixed with this:
817 forward lpwa. lpwa.com:8000
820 (NOTE: the syntax for specifying target_domain has changed since the previous
821 paragraph was written -- it will not work now. More information is welcome.)
823 In this fictitious example, everything goes via an ISP's caching proxy, except
824 requests to that ISP:
826 forward .* caching.myisp.net:8000
830 For the @home network, we're told the forwarding configuration is this:
832 forward .* proxy:8080
835 Also, we're told they insist on getting cookies and JavaScript, so you should
836 allow cookies from home.com. We consider JavaScript a potential security risk.
837 Java need not be enabled.
839 In this example direct connections are made to all "internal" domains, but
840 everything else goes through Lucent's LPWA by way of the company's SOCKS
841 gateway to the Internet.
843 forward-socks4 .* lpwa.com:8000 firewall.my_company.com:1080
844 forward my_company.com .
847 This is how you could set up a site that always uses SOCKS but no forwarders:
849 forward-socks4a .* . firewall.my_company.com:1080
852 An advanced example for network administrators:
854 If you have links to multiple ISPs that provide various special content to
855 their subscribers, you can configure forwarding to pass requests to the
856 specific host that's connected to that ISP so that everybody can see all of the
857 content on all of the ISPs.
859 This is a bit tricky, but here's an example:
861 host-a has a PPP connection to isp-a.com. And host-b has a PPP connection to
862 isp-b.com. host-a can run a Privoxy proxy with forwarding like this:
865 forward isp-b.com host-b:8118
868 host-b can run a Privoxy proxy with forwarding like this:
871 forward isp-a.com host-a:8118
874 Now, anyone on the Internet (including users on host-a and host-b) can set
875 their browser's proxy to either host-a or host-b and be able to browse the
876 content on isp-a or isp-b.
878 Here's another practical example, for University of Kent at Canterbury students
879 with a network connection in their room, who need to use the University's Squid
882 forward *. ssbcache.ukc.ac.uk:3128 # Use the proxy, except for:
883 forward .ukc.ac.uk . # Anything on the same domain as us
884 forward * . # Host with no domain specified
885 forward 129.12.*.* . # A dotted IP on our /16 network.
886 forward 127.*.*.* . # Loopback address
887 forward localhost.localdomain . # Loopback address
888 forward www.ukc.mirror.ac.uk . # Specific host
891 If you intend to chain Privoxy and squid locally, then chain as browser ->
892 squid -> privoxy is the recommended way.
894 Your squid configuration could then look like this:
896 # Define Privoxy as parent cache
898 cache_peer 127.0.0.1 parent 8118 0 no-query
900 # Define ACL for protocol FTP
903 # Do not forward ACL FTP to privoxy
904 always_direct allow FTP
906 # Do not forward ACL CONNECT (https) to privoxy
907 always_direct allow CONNECT
909 # Forward the rest to privoxy
910 never_direct allow all
913 -------------------------------------------------------------------------------
915 3.3.5. Windows GUI Options
917 Privoxy has a number of options specific to the Windows GUI interface:
919 If "activity-animation" is set to 1, the Privoxy icon will animate when
920 "Privoxy" is active. To turn off, set to 0.
925 If "log-messages" is set to 1, Privoxy will log messages to the console window:
930 If "log-buffer-size" is set to 1, the size of the log buffer, i.e. the amount
931 of memory used for the log messages displayed in the console window, will be
932 limited to "log-max-lines" (see below).
934 Warning: Setting this to 0 will result in the buffer to grow infinitely and eat
940 log-max-lines is the maximum number of lines held in the log buffer. See above.
945 If "log-highlight-messages" is set to 1, Privoxy will highlight portions of the
946 log messages with a bold-faced font:
948 log-highlight-messages 1
951 The font used in the console window:
953 log-font-name Comic Sans MS
956 Font size used in the console window:
961 "show-on-task-bar" controls whether or not Privoxy will appear as a button on
962 the Task bar when minimized:
967 If "close-button-minimizes" is set to 1, the Windows close button will minimize
968 Privoxy instead of closing the program (close with the exit option on the File
971 close-button-minimizes 1
974 The "hide-console" option is specific to the MS-Win console version of Privoxy.
975 If this option is used, Privoxy will disconnect from and hide the command
981 -------------------------------------------------------------------------------
983 3.4. The Actions File
985 The "default.action" file (formerly actionsfile or ijb.action) is used to
986 define what actions Privoxy takes, and thus determines how images, cookies and
987 various other aspects of HTTP content and transactions are handled. Images can
988 be anything you want, including ads, banners, or just some obnoxious URL that
989 you would rather not see. Cookies can be accepted or rejected, or accepted only
990 during the current browser session (i.e. not written to disk). Changes to
991 default.action should be immediately visible to Privoxy without the need to
994 The easiest way to edit "actions" file is with a browser by loading http://p.p/
995 , and then select "Edit Actions List". A text editor can also be used.
997 To determine which actions apply to a request, the URL of the request is
998 compared to all patterns in this file. Every time it matches, the list of
999 applicable actions for the URL is incrementally updated. You can trace this
1000 process by visiting http://p.p/show-url-info.
1002 There are four types of lines in this file: comments (begin with a "#"
1003 character), actions, aliases and patterns, all of which are explained below, as
1004 well as the configuration file syntax that Privoxy understands.
1006 -------------------------------------------------------------------------------
1008 3.4.1. URL Domain and Path Syntax
1010 Generally, a pattern has the form <domain>/<path>, where both the <domain> and
1011 <path> part are optional. If you only specify a domain part, the "/" can be
1014 www.example.com - is a domain only pattern and will match any request to
1017 www.example.com/ - means exactly the same.
1019 www.example.com/index.html - matches only the single document "/index.html" on
1022 /index.html - matches the document "/index.html", regardless of the domain.
1024 index.html - matches nothing, since it would be interpreted as a domain name
1025 and there is no top-level domain called ".html".
1027 The matching of the domain part offers some flexible options: if the domain
1028 starts or ends with a dot, it becomes unanchored at that end. For example:
1030 .example.com - matches any domain that ENDS in ".example.com".
1032 www. - matches any domain that STARTS with "www".
1034 Additionally, there are wild-cards that you can use in the domain names
1035 themselves. They work pretty similar to shell wild-cards: "*" stands for zero
1036 or more arbitrary characters, "?" stands for any single character. And you can
1037 define character classes in square brackets and they can be freely mixed:
1039 ad*.example.com - matches "adserver.example.com", "ads.example.com", etc but
1040 not "sfads.example.com".
1042 *ad*.example.com - matches all of the above, and then some.
1044 .?pix.com - matches "www.ipix.com", "pictures.epix.com", "a.b.c.d.e.upix.com",
1047 www[1-9a-ez].example.com - matches "www1.example.com", "www4.example.com",
1048 "wwwd.example.com", "wwwz.example.com", etc., but not "wwww.example.com".
1050 If Privoxy was compiled with "pcre" support (default), Perl compatible regular
1051 expressions can be used. See the pcre/docs/ directory or "man perlre" (also
1052 available on http://www.perldoc.com/perl5.6/pod/perlre.html) for details. A
1053 brief discussion of regular expressions is in the Appendix. For instance:
1055 /.*/advert[0-9]+\.jpe?g - would match a URL from any domain, with any path that
1056 includes "advert" followed immediately by one or more digits, then a "." and
1057 ending in either "jpeg" or "jpg". So we match "example.com/ads/advert2.jpg",
1058 and "www.example.com/ads/banners/advert39.jpeg", but not "www.example.com/ads/
1059 banners/advert39.gif" (no gifs in the example pattern).
1061 Please note that matching in the path is case INSENSITIVE by default, but you
1062 can switch to case sensitive at any point in the pattern by using the "(?-i)"
1065 www.example.com/(?-i)PaTtErN.* - will match only documents whose path starts
1066 with "PaTtErN" in exactly this capitalization.
1068 -------------------------------------------------------------------------------
1072 Actions are enabled if preceded with a "+", and disabled if preceded with a
1073 "-". Actions are invoked by enclosing the action name in curly braces (e.g.
1074 {+some_action}), followed by a list of URLs to which the action applies. There
1075 are three classes of actions:
1077 * Boolean (e.g. "+/-block"):
1079 {+name} # enable this action
1080 {-name} # disable this action
1083 * parameterized (e.g. "+/-hide-user-agent"):
1085 {+name{param}} # enable action and set parameter to "param"
1086 {-name} # disable action
1089 * Multi-value (e.g. "{+/-add-header{Name: value}}", "{+/-wafer{name=value}}
1092 {+name{param}} # enable action and add parameter "param"
1093 {-name{param}} # remove the parameter "param"
1094 {-name} # disable this action totally
1097 If nothing is specified in this file, no "actions" are taken. So in this case
1098 Privoxy would just be a normal, non-blocking, non-anonymizing proxy. You must
1099 specifically enable the privacy and blocking features you need (although the
1100 provided default default.action file will give a good starting point).
1102 Later defined actions always over-ride earlier ones. For multi-valued actions,
1103 the actions are applied in the order they are specified.
1105 The list of valid Privoxy "actions" are:
1107 * Add the specified HTTP header, which is not checked for validity. You may
1108 specify this many times to specify many different headers:
1110 +add-header{Name: value}
1113 * Block this URL totally. In a default installation, a "blocked" URL will
1114 result in bright red banner that says "BLOCKED", with a reason why it is
1120 * De-animate all animated GIF images, i.e. reduce them to their last frame.
1121 This will also shrink the images considerably (in bytes, not pixels!). If
1122 the option "first" is given, the first frame of the animation is used as
1123 the replacement. If "last" is given, the last frame of the animation is
1124 used instead, which probably makes more sense for most banner animations,
1125 but also has the risk of not showing the entire last frame (if it is only a
1126 delta to an earlier frame).
1128 +deanimate-gifs{last}
1129 +deanimate-gifs{first}
1132 * "+downgrade" will downgrade HTTP/1.1 client requests to HTTP/1.0 and
1133 downgrade the responses as well. Use this action for servers that use HTTP/
1134 1.1 protocol features that Privoxy doesn't handle well yet. HTTP/1.1 is
1135 only partially implemented. Default is not to downgrade requests.
1140 * Many sites, like yahoo.com, don't just link to other sites. Instead, they
1141 will link to some script on their own server, giving the destination as a
1142 parameter, which will then redirect you to the final target. URLs resulting
1143 from this scheme typically look like: http://some.place/some_script?http://
1146 Sometimes, there are even multiple consecutive redirects encoded in the
1147 URL. These redirections via scripts make your web browsing more traceable,
1148 since the server from which you follow such a link can see where you go to.
1149 Apart from that, valuable bandwidth and time is wasted, while your browser
1150 ask the server for one redirect after the other. Plus, it feeds the
1153 The "+fast-redirects" option enables interception of these types of
1154 requests by Privoxy, who will cut off all but the last valid URL in the
1155 request and send a local redirect back to your browser without contacting
1156 the intermediate site(s).
1161 * Apply the filters in the section_header section of the default.filter file
1162 to the site(s). default.filter sections are grouped according to like
1165 +filter{section_header}
1168 Filter sections that are pre-defined in the supplied default.filter
1171 html-annoyances: Get rid of particularly annoying HTML abuse.
1173 js-annoyances: Get rid of particularly annoying JavaScript abuse
1175 no-poups: Kill all popups in JS and HTML
1177 frameset-borders: Give frames a border
1179 webbugs: Squish WebBugs (1x1 invisible GIFs used for user tracking)
1181 no-refresh: Automatic refresh sucks on auto-dialup lines
1183 fun: Text replacements for subversive browsing fun!
1185 nimda: Remove (virus) Nimda code.
1187 banners-by-size: Kill banners by size
1189 crude-parental: Kill all web pages that contain the words "sex" or
1192 * Block any existing X-Forwarded-for header, and do not add a new one:
1197 * If the browser sends a "From:" header containing your e-mail address, this
1198 either completely removes the header ("block"), or changes it to the
1199 specified e-mail address.
1202 +hide-from{spam@sittingduck.xqq}
1205 * Don't send the "Referer:" (sic) header to the web site. You can block it,
1206 forge a URL to the same server as the request (which is preferred because
1207 some sites will not send images otherwise) or set it to a constant string
1210 +hide-referer{block}
1211 +hide-referer{forge}
1212 +hide-referer{http://nowhere.com}
1215 * Alternative spelling of "+hide-referer". It has the same parameters, and
1216 can be freely mixed with, "+hide-referer". ("referrer" is the correct
1217 English spelling, however the HTTP specification has a bug - it requires it
1218 to be spelled "referer".)
1223 * Change the "User-Agent:" header so web servers can't tell your browser
1224 type. Warning! This breaks many web sites. Specify the user-agent value you
1225 want. Example, pretend to be using Netscape on Linux:
1227 +hide-user-agent{Mozilla (X11; I; Linux 2.0.32 i586)}
1230 * Treat this URL as an image. This only matters if it's also "+block"ed, in
1231 which case a "blocked" image can be sent rather than a HTML page. See
1232 "+image-blocker{}" below for the control over what is actually sent. If you
1233 want invisible ads, they should be defined as images and blocked. And also,
1234 "image-blocker" should be set to "blank".
1239 * Decides what to do with URLs that end up tagged with "{+block +image}", e.g
1240 an advertizement. There are five options. "-image-blocker" will send a HTML
1241 "blocked" page, usually resulting in a "broken image" icon. "+image-blocker
1242 {blank}" will send a 1x1 transparent GIF image. And finally,
1243 "+image-blocker{http://xyz.com}" will send a HTTP temporary redirect to the
1244 specified image. This has the advantage of the icon being being cached by
1245 the browser, which will speed up the display. "+image-blocker{pattern}"
1246 will send a checkboard type pattern
1248 +image-blocker{blank}
1249 +image-blocker{pattern}
1250 +image-blocker{http://p.p/send-banner}
1253 * By default (i.e. in the absence of a "+limit-connect" action), Privoxy will
1254 only allow CONNECT requests to port 443, which is the standard port for
1255 https as a precaution.
1257 The CONNECT methods exists in HTTP to allow access to secure websites
1258 (https:// URLs) through proxies. It works very simply: the proxy connects
1259 to the server on the specified port, and then short-circuits its
1260 connections to the client and to the remote proxy. This can be a big
1261 security hole, since CONNECT-enabled proxies can be abused as TCP relays
1264 If you want to allow CONNECT for more ports than this, or want to forbid
1265 CONNECT altogether, you can specify a comma separated list of ports and
1266 port ranges (the latter using dashes, with the minimum defaulting to 0 and
1269 +limit-connect{443} # This is the default and need no be specified.
1270 +limit-connect{80,443} # Ports 80 and 443 are OK.
1271 +limit-connect{-3, 7, 20-100, 500-} # Port less than 3, 7, 20 to 100
1272 #and above 500 are OK.
1275 * "+no-compression" prevents the website from compressing the data. Some
1276 websites do this, which can be a problem for Privoxy, since "+filter",
1277 "+no-popup" and "+gif-deanimate" will not work on compressed data. This
1278 will slow down connections to those websites, though. Default is
1279 "nocompression" is turned on.
1284 * If the website sets cookies, "no-cookies-keep" will make sure they are
1285 erased when you exit and restart your web browser. This makes profiling
1286 cookies useless, but won't break sites which require cookies so that you
1287 can log in for transactions. Default: on.
1292 * Prevent the website from reading cookies:
1297 * Prevent the website from setting cookies:
1302 * Filter the website through a built-in filter to disable those obnoxious
1303 JavaScript pop-up windows via window.open(), etc. The two alternative
1304 spellings are equivalent.
1310 * This action only applies if you are using a jarfile for saving cookies. It
1311 sends a cookie to every site stating that you do not accept any copyright
1312 on cookies sent to you, and asking them not to track you. Of course, this
1313 is a (relatively) unique header they could use to track you.
1318 * This allows you to add an arbitrary cookie. It can be specified multiple
1319 times in order to add as many cookies as you like.
1324 The meaning of any of the above is reversed by preceding the action with a "-",
1325 in place of the "+".
1329 Turn off cookies by default, then allow a few through for specified sites:
1331 # Turn off all persistent cookies
1332 { +no-cookies-read }
1334 # Allow cookies for this browser session ONLY
1335 { +no-cookies-keep }
1337 # Exceptions to the above, sites that benefit from persistent cookies
1338 { -no-cookies-read }
1340 { -no-cookies-keep }
1347 # Alternative way of saying the same thing
1348 {-no-cookies-set -no-cookies-read -no-cookies-keep}
1353 Now turn off "fast redirects", and then we allow two exceptions:
1358 # Reverse it for these two sites, which don't work right without it.
1360 www.ukc.ac.uk/cgi-bin/wac\.cgi\?
1364 Turn on page filtering according to rules in the defined sections of
1365 refilterfile, and make one exception for sourceforge:
1367 # Run everything through the filter file, using only the
1368 # specified sections:
1369 +filter{html-annoyances} +filter{js-annoyances} +filter{no-popups}\
1370 +filter{webbugs} +filter{nimda} +filter{banners-by-size}
1372 # Then disable filtering of code from sourceforge!
1374 .cvs.sourceforge.net
1377 Now some URLs that we want "blocked", ie we won't see them. Many of these use
1378 regular expressions that will expand to match multiple URLs:
1382 /.*/(.*[-_.])?ads?[0-9]?(/|[-_.].*|\.(gif|jpe?g))
1383 /.*/(.*[-_.])?count(er)?(\.cgi|\.dll|\.exe|[?/])
1384 /.*/(ng)?adclient\.cgi
1385 /.*/(plain|live|rotate)[-_.]?ads?/
1386 /.*/(sponsor)s?[0-9]?/
1387 /.*/_?(plain|live)?ads?(-banners)?/
1389 /.*/ad(sdna_image|gifs?)/
1390 /.*/ad(server|stream|juggler)\.(cgi|pl|dll|exe)
1394 /.*/adv((er)?ts?|ertis(ing|ements?))?/
1398 /.*/cgi-bin/centralad/getimage
1399 /.*/images/addver\.gif
1400 /.*/images/marketing/.*\.(gif|jpe?g)
1404 /.*/sponsors?[0-9]?/
1405 /.*/advert[0-9]+\.jpg
1412 /graphics/defaultAd/
1414 /image\.ng/transactionID
1415 /images/.*/.*_anim\.gif # alvin brattli
1416 /ip_img/.*\.(gif|jpe?g)
1420 /cgi-bin/nph-adclick.exe/
1421 /.*/Image/BannerAdvertising/
1423 /.*/adlib/server\.cgi
1427 Note that many of these actions have the potential to cause a page to
1428 misbehave, possibly even not to display at all. There are many ways a site
1429 designer may choose to design his site, and what HTTP header content he may
1430 depend on. There is no way to have hard and fast rules for all sites. See the
1431 Appendix for a brief example on troubleshooting actions.
1433 -------------------------------------------------------------------------------
1437 Custom "actions", known to Privoxy as "aliases", can be defined by combining
1438 other "actions". These can in turn be invoked just like the built-in "actions".
1439 Currently, an alias can contain any character except space, tab, "=", "{" or "}
1440 ". But please use only "a"- "z", "0"-"9", "+", and "-". Alias names are not
1441 case sensitive, and must be defined before anything else in the
1442 default.actionfile ! And there can only be one set of "aliases" defined.
1444 Now let's define a few aliases:
1446 # Useful customer aliases we can use later. These must come first!
1448 +no-cookies = +no-cookies-set +no-cookies-read
1449 -no-cookies = -no-cookies-set -no-cookies-read
1451 -block -no-cookies -filter -fast-redirects -hide-referer -no-popups
1452 shop = -no-cookies -filter -fast-redirects
1453 +imageblock = +block +image
1455 #For people who don't like to type too much: ;-)
1458 c2 = -no-cookies-set +no-cookies-read
1459 c3 = +no-cookies-set -no-cookies-read
1460 #... etc. Customize to your heart's content.
1463 Some examples using our "shop" and "fragile" aliases from above:
1465 # These sites are very complex and require
1466 # minimal interference.
1468 .office.microsoft.com
1469 .windowsupdate.microsoft.com
1472 # Shopping sites - still want to block ads.
1475 .worldpay.com # for quietpc.com
1479 # These shops require pop-ups
1485 -------------------------------------------------------------------------------
1487 3.5. The Filter File
1489 Any web page can be dynamically modified with the filter file. This
1490 modification can be removal, or re-writing, of any web page content, including
1491 tags and non-visible content. The default filter file is default.filter,
1492 located in the config directory.
1494 The included example file is divided into sections. Each section begins with
1495 the FILTER keyword, followed by the identifier for that section, e.g. "FILTER:
1496 webbugs". Each section performs a similar type of filtering, such as
1499 This file uses regular expressions to alter or remove any string in the target
1500 page. The expressions can only operate on one line at a time. Some examples
1501 from the included default default.filter:
1503 Stop web pages from displaying annoying messages in the status bar by deleting
1506 FILTER: html-annoyances
1508 # New browser windows should be resizeable and have a location and status
1511 s/resizable="?(no|0)"?/resizable=1/ig s/noresize/yesresize/ig
1512 s/location="?(no|0)"?/location=1/ig s/status="?(no|0)"?/status=1/ig
1513 s/scrolling="?(no|0|Auto)"?/scrolling=1/ig
1514 s/menubar="?(no|0)"?/menubar=1/ig
1516 # The <BLINK> tag was a crime!
1518 s*<blink>|</blink>**ig
1522 #s/framespacing="?(no|0)"?//ig
1523 #s/margin(height|width)=[0-9]*//gi
1526 Just for kicks, replace any occurrence of "Microsoft" with "MicroSuck", and
1527 have a little fun with topical buzzwords:
1531 s/microsoft(?!.com)/MicroSuck/ig
1535 s/industry-leading|cutting-edge|award-winning/<font color=red><b>BINGO!</b></
1539 Kill those pesky little web-bugs:
1541 # webbugs: Squish WebBugs (1x1 invisible GIFs used for user tracking)
1544 s/<img\s+[^>]*?(width|height)\s*=\s*['"]?1\D[^>]*?(width|height)\s*=\s*['"]?1
1545 (\D[^>]*?)?>/<!-- Squished WebBug -->/sig
1548 -------------------------------------------------------------------------------
1552 When Privoxy displays one of its internal pages, such as a 404 Not Found error
1553 page, it uses the appropriate template. On Linux, BSD, and Unix, these are
1554 located in /etc/privoxy/templates by default. These may be customized, if
1557 -------------------------------------------------------------------------------
1559 4. Quickstart to Using Privoxy
1561 Install package, then run and enjoy! Privoxy is typically started by specifying
1562 the main configuration file to be used on the command line. Example Unix
1566 # /usr/sbin/privoxy /etc/privoxy/config
1570 An init script is provided for SuSE and Redhat.
1572 For for SuSE: /etc/rc.d/privoxy start
1574 For RedHat: /etc/rc.d/init.d/privoxy start
1576 If no configuration file is specified on the command line, Privoxy will look
1577 for a file named config in the current directory. Except on Win32 where it will
1578 try config.txt. If no file is specified on the command line and no default
1579 configuration file can be found, Privoxy will fail to start.
1581 Be sure your browser is set to use the proxy which is by default at localhost,
1582 port 8118. With Netscape (and Mozilla), this can be set under Edit ->
1583 Preferences -> Advanced -> Proxies -> HTTP Proxy. For Internet Explorer: Tools
1584 > Internet Properties -> Connections -> LAN Setting. Then, check "Use Proxy"
1585 and fill in the appropriate info (Address: localhost, Port: 8118). Include if
1586 HTTPS proxy support too.
1588 The included default configuration files should give a reasonable starting
1589 point, though may be somewhat aggressive in blocking junk. You will probably
1590 want to keep an eye out for sites that require persistent cookies, and add
1591 these to default.action as needed. By default, most of these will be accepted
1592 only during the current browser session, until you add them to the
1593 configuration. If you want the browser to handle this instead, you will need to
1594 edit default.action and disable this feature. If you use more than one browser,
1595 it would make more sense to let Privoxy handle this. In which case, the browser
1596 (s) should be set to accept all cookies.
1598 If a particular site shows problems loading properly, try adding it to the
1599 {fragile} section of default.action. This will turn off most actions for this
1602 Privoxy is HTTP/1.1 compliant, but not all 1.1 features are as yet implemented.
1603 If browsers that support HTTP/1.1 (like Mozilla or recent versions of I.E.)
1604 experience problems, you might try to force HTTP/1.0 compatibility. For
1605 Mozilla, look under Edit -> Preferences -> Debug -> Networking. Or set the
1606 "+downgrade" config option in default.action.
1608 After running Privoxy for a while, you can start to fine tune the configuration
1609 to suit your personal, or site, preferences and requirements. There are many,
1610 many aspects that can be customized. "Actions" (as specified in default.action)
1611 can be adjusted by pointing your browser to http://p.p/, and then follow the
1612 link to "edit the actions list". (This is an internal page and does not require
1615 In fact, various aspects of Privoxy configuration can be viewed from this page,
1616 including current configuration parameters, source code version numbers, the
1617 browser's request headers, and "actions" that apply to a given URL. In addition
1618 to the default.action file editor mentioned above, Privoxy can also be turned
1619 "on" and "off" from this page.
1621 If you encounter problems, please verify it is a Privoxy bug, by disabling
1622 Privoxy, and then trying the same page. Also, try another browser if possible
1623 to eliminate browser or site problems. Before reporting it as a bug, see if
1624 there is not a configuration option that is enabled that is causing the page
1625 not to load. You can then add an exception for that page or site. If a bug,
1626 please report it to the developers (see below).
1628 -------------------------------------------------------------------------------
1630 4.1. Command Line Options
1632 Privoxy may be invoked with the following command-line options:
1636 Print version info and exit, Unix only.
1640 Print a short usage info and exit, Unix only.
1644 Don't become a daemon, i.e. don't fork and become process group leader,
1645 don't detach from controlling tty. Unix only.
1649 On startup, write the process ID to FILE. Delete the FILE on exit. Failiure
1650 to create or delete the FILE is non-fatal. If no FILE option is given, no
1651 PID file will be used. Unix only.
1653 * --user USER[.GROUP]
1655 After (optionally) writing the PID file, assume the user ID of USER, and if
1656 included the GID of GROUP. Exit if the privileges are not sufficient to do
1661 If no configfile is included on the command line, Privoxy will look for a
1662 file named "config" in the current directory (except on Win32 where it will
1663 look for "config.txt" instead). Specify full path to avoid confusion.
1665 -------------------------------------------------------------------------------
1667 5. Contacting the Developers, Bug Reporting and Feature Requests
1669 We value your feedback. However, to provide you with the best support, please
1672 * Use the Sourceforge support forum to get help.
1674 * Submit bugs only thru our Sourceforge bug forum. Make sure that the bug has
1675 not already been submitted. Please try to verify that it is a Privoxy bug,
1676 and not a browser or site bug first. If you are using your own custom
1677 configuration, please try the stock configs to see if the problem is a
1678 configuration related bug. And if not using the latest development
1679 snapshot, please try the latest one. Or even better, CVS sources.
1681 * Submit feature requests only thru our Sourceforge feature request forum.
1685 For any other issues, feel free to use the mailing lists.
1687 Anyone interested in actively participating in development and related
1688 discussions can join the appropriate mailing list here. Archives are available
1691 -------------------------------------------------------------------------------
1693 6. Copyright and History
1697 Privoxy is free software; you can redistribute it and/or modify it under the
1698 terms of the GNU General Public License as published by the Free Software
1699 Foundation; either version 2 of the License, or (at your option) any later
1702 This program is distributed in the hope that it will be useful, but WITHOUT ANY
1703 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
1704 PARTICULAR PURPOSE. See the GNU General Public License for more details, which
1705 is available from the Free Software Foundation, Inc, 59 Temple Place - Suite
1706 330, Boston, MA 02111-1307, USA.
1708 -------------------------------------------------------------------------------
1712 Privoxy is evolved, and derived from, the Internet Junkbuster, with many
1713 improvments and enhancements over the original.
1715 Junkbuster was originally written by Anonymous Coders and Junkbuster's
1716 Corporation, and was released as free open-source software under the GNU GPL.
1717 Stefan Waldherr made many improvements, and started the SourceForge project
1718 Privoxy to rekindle development. There are now several active developers
1719 contributing. The last stable release of Junkbuster was v2.0.2, which has now
1722 -------------------------------------------------------------------------------
1726 http://sourceforge.net/projects/ijbswa, the Project Page for Privoxy.
1728 http://www.privoxy.org/
1732 http://www.junkbusters.com/ht/en/cookies.html
1734 http://www.waldherr.org/junkbuster/
1736 http://privacy.net/analyze/
1738 http://www.squid-cache.org/
1742 -------------------------------------------------------------------------------
1746 8.1. Regular Expressions
1748 Privoxy can use "regular expressions" in various config files. Assuming support
1749 for "pcre" (Perl Compatible Regular Expressions) is compiled in, which is the
1750 default. Such configuration directives do not require regular expressions, but
1751 they can be used to increase flexibility by matching a pattern with wild-cards
1754 If you are reading this, you probably don't understand what "regular
1755 expressions" are, or what they can do. So this will be a very brief
1756 introduction only. A full explanation would require a book ;-)
1758 "Regular expressions" is a way of matching one character expression against
1759 another to see if it matches or not. One of the "expressions" is a literal
1760 string of readable characters (letter, numbers, etc), and the other is a
1761 complex string of literal characters combined with wild-cards, and other
1762 special characters, called meta-characters. The "meta-characters" have special
1763 meanings and are used to build the complex pattern to be matched against. Perl
1764 Compatible Regular Expressions is an enhanced form of the regular expression
1765 language with backward compatibility.
1767 To make a simple analogy, we do something similar when we use wild-card
1768 characters when listing files with the dir command in DOS. *.* matches all
1769 filenames. The "special" character here is the asterisk which matches any and
1770 all characters. We can be more specific and use ? to match just individual
1771 characters. So "dir file?.text" would match "file1.txt", "file2.txt", etc. We
1772 are pattern matching, using a similar technique to "regular expressions"!
1774 Regular expressions do essentially the same thing, but are much, much more
1775 powerful. There are many more "special characters" and ways of building complex
1776 patterns however. Let's look at a few of the common ones, and then some
1779 . - Matches any single character, e.g. "a", "A", "4", ":", or "@".
1781 ? - The preceding character or expression is matched ZERO or ONE times. Either/
1784 + - The preceding character or expression is matched ONE or MORE times.
1786 * - The preceding character or expression is matched ZERO or MORE times.
1788 \ - The "escape" character denotes that the following character should be taken
1789 literally. This is used where one of the special characters (e.g. ".") needs to
1790 be taken literally and not as a special meta-character.
1792 [] - Characters enclosed in brackets will be matched if any of the enclosed
1793 characters are encountered.
1795 () - parentheses are used to group a sub-expression, or multiple
1798 | - The "bar" character works like an "or" conditional statement. A match is
1799 successful if the sub-expression on either side of "|" matches.
1801 s/string1/string2/g - This is used to rewrite strings of text. "string1" is
1802 replaced by "string2" in this example.
1804 These are just some of the ones you are likely to use when matching URLs with
1805 Privoxy, and is a long way from a definitive list. This is enough to get us
1806 started with a few simple examples which may be more illuminating:
1808 /.*/banners/.* - A simple example that uses the common combination of "." and "
1809 *" to denote any character, zero or more times. In other words, any string at
1810 all. So we start with a literal forward slash, then our regular expression
1811 pattern (".*") another literal forward slash, the string "banners", another
1812 forward slash, and lastly another ".*". We are building a directory path here.
1813 This will match any file with the path that has a directory named "banners" in
1814 it. The ".*" matches any characters, and this could conceivably be more forward
1815 slashes, so it might expand into a much longer looking path. For example, this
1816 could match: "/eye/hate/spammers/banners/annoy_me_please.gif", or just "/
1817 banners/annoying.html", or almost an infinite number of other possible
1818 combinations, just so it has "banners" in the path somewhere.
1820 A now something a little more complex:
1822 /.*/adv((er)?ts?|ertis(ing|ements?))?/ - We have several literal forward
1823 slashes again ("/"), so we are building another expression that is a file path
1824 statement. We have another ".*", so we are matching against any conceivable
1825 sub-path, just so it matches our expression. The only true literal that must
1826 match our pattern is adv, together with the forward slashes. What comes after
1827 the "adv" string is the interesting part.
1829 Remember the "?" means the preceding expression (either a literal character or
1830 anything grouped with "(...)" in this case) can exist or not, since this means
1831 either zero or one match. So "((er)?ts?|ertis(ing|ements?))" is optional, as
1832 are the individual sub-expressions: "(er)", "(ing|ements?)", and the "s". The "
1833 |" means "or". We have two of those. For instance, "(ing|ements?)", can expand
1834 to match either "ing" OR "ements?". What is being done here, is an attempt at
1835 matching as many variations of "advertisement", and similar, as possible. So
1836 this would expand to match just "adv", or "advert", or "adverts", or
1837 "advertising", or "advertisement", or "advertisements". You get the idea. But
1838 it would not match "advertizements" (with a "z"). We could fix that by changing
1839 our regular expression to: "/.*/adv((er)?ts?|erti(s|z)(ing|ements?))?/", which
1840 would then match either spelling.
1842 /.*/advert[0-9]+\.(gif|jpe?g) - Again another path statement with forward
1843 slashes. Anything in the square brackets "[]" can be matched. This is using
1844 "0-9" as a shorthand expression to mean any digit one through nine. It is the
1845 same as saying "0123456789". So any digit matches. The "+" means one or more of
1846 the preceding expression must be included. The preceding expression here is
1847 what is in the square brackets -- in this case, any digit one through nine.
1848 Then, at the end, we have a grouping: "(gif|jpe?g)". This includes a "|", so
1849 this needs to match the expression on either side of that bar character also. A
1850 simple "gif" on one side, and the other side will in turn match either "jpeg"
1851 or "jpg", since the "?" means the letter "e" is optional and can be matched
1852 once or not at all. So we are building an expression here to match image GIF or
1853 JPEG type image file. It must include the literal string "advert", then one or
1854 more digits, and a "." (which is now a literal, and not a special character,
1855 since it is escaped with "\"), and lastly either "gif", or "jpeg", or "jpg".
1856 Some possible matches would include: "//advert1.jpg", "/nasty/ads/
1857 advert1234.gif", "/banners/from/hell/advert99.jpg". It would not match
1858 "advert1.gif" (no leading slash), or "/adverts232.jpg" (the expression does not
1859 include an "s"), or "/advert1.jsp" ("jsp" is not in the expression anywhere).
1861 s/microsoft(?!.com)/MicroSuck/i - This is a substitution. "MicroSuck" will
1862 replace any occurrence of "microsoft". The "i" at the end of the expression
1863 means ignore case. The "(?!.com)" means the match should fail if "microsoft" is
1864 followed by ".com". In other words, this acts like a "NOT" modifier. In case
1865 this is a hyperlink, we don't want to break it ;-).
1867 We are barely scratching the surface of regular expressions here so that you
1868 can understand the default Privoxy configuration files, and maybe use this
1869 knowledge to customize your own installation. There is much, much more that can
1870 be done with regular expressions. Now that you know enough to get started, you
1871 can learn more on your own :/
1873 More reading on Perl Compatible Regular expressions: http://www.perldoc.com/
1874 perl5.6/pod/perlre.html
1876 -------------------------------------------------------------------------------
1878 8.2. Privoxy's Internal Pages
1880 Since Privoxy proxies each requested web page, it is easy for Privoxy to trap
1881 certain URLs. In this way, we can talk directly to Privoxy, and see how it is
1882 configured, see how our rules are being applied, change these rules and other
1883 configuration options, and even turn Privoxy's filtering off, all with a web
1886 The URLs listed below are the special ones that allow direct access to Privoxy.
1887 Of course, Privoxy must be running to access these. If not, you will get a
1888 friendly error message. Internet access is not necessary either.
1890 * Privoxy main page:
1892 http://www.privoxy.org/config/
1894 Alternately, this may be reached at http://p.p/, but this variation may not
1895 work as reliably as the above in some configurations.
1897 * Show information about the current configuration:
1899 http://www.privoxy.org/config/show-status
1901 * Show the source code version numbers:
1903 http://www.privoxy.org/config/show-version
1905 * Show the client's request headers:
1907 http://www.privoxy.org/config/show-request
1909 * Show which actions apply to a URL and why:
1911 http://www.privoxy.org/config/show-url-info
1913 * Toggle Privoxy on or off:
1915 http://www.privoxy.org/config/toggle
1917 Short cuts. Turn off, then on:
1919 http://www.privoxy.org/config/toggle?set=disable
1921 http://www.privoxy.org/config/toggle?set=enable
1923 * Edit the actions list file:
1925 http://www.privoxy.org/config/edit-actions
1927 These may be bookmarked for quick reference.
1929 -------------------------------------------------------------------------------
1931 8.3. Anatomy of an Action
1933 The way Privoxy applies "actions" to any given URL can be complex, and not
1934 always so easy to understand what is happening. And sometimes we need to be
1935 able to see just what Privoxy is doing. Especially, if something Privoxy is
1936 doing is causing us a problem inadvertantly. It can be a little daunting to
1937 look at the actions files themselves, since they tend to be filled with
1938 "regular expressions" whose consequences are not always so obvious. Privoxy
1939 provides the http://www.privoxy.org/config/show-url-info page that can show us
1940 very specifically how actions are being applied to any given URL. This is a big
1941 help for troubleshooting.
1943 First, enter one URL (or partial URL) at the prompt, and then Privoxy will tell
1944 us how the current configuration will handle it. This will not help with
1945 filtering effects from the default.filter file! It also will not tell you about
1946 any other URLs that may be embedded within the URL you are testing. For
1947 instance, images such as ads are expressed as URLs within the raw page source
1948 of HTML pages. So you will only get info for the actual URL that is pasted into
1949 the prompt area -- not any sub-URLs. If you want to know about embedded URLs
1950 like ads, you will have to dig those out of the HTML source. Use your browser's
1951 "View Page Source" option for this.
1953 Let's look at an example, google.com, one section at a time:
1955 System default actions:
1957 { -add-header -block -deanimate-gifs -downgrade -fast-redirects -filter
1958 -hide-forwarded -hide-from -hide-referer -hide-user-agent -image
1959 -image-blocker -limit-connect -no-compression -no-cookies-keep
1960 -no-cookies-read -no-cookies-set -no-popups -vanilla-wafer -wafer }
1964 This is the top section, and only tells us of the compiled in defaults. This is
1965 basically what Privoxy would do if there were not any "actions" defined, i.e.
1966 it does nothing. Every action is disabled. This is not particularly informative
1967 for our purposes here. OK, next section:
1969 Matches for http://google.com:
1971 { -add-header -block +deanimate-gifs -downgrade +fast-redirects
1972 +filter{html-annoyances} +filter{js-annoyances} +filter{no-popups}
1973 +filter{webbugs} +filter{nimda} +filter{banners-by-size} +filter{hal}
1974 +filter{fun} +hide-forwarded +hide-from{block} +hide-referer{forge}
1975 -hide-user-agent -image +image-blocker{blank} +no-compression
1976 +no-cookies-keep -no-cookies-read -no-cookies-set +no-popups
1977 -vanilla-wafer -wafer }
1980 { -no-cookies-keep -no-cookies-read -no-cookies-set }
1988 This is much more informative, and tells us how we have defined our "actions",
1989 and which ones match for our example, "google.com". The first grouping shows
1990 our default settings, which would apply to all URLs. If you look at your
1991 "actions" file, this would be the section just below the "aliases" section near
1992 the top. This applies to all URLs as signified by the single forward slash -- "
1995 These are the default actions we have enabled. But we can define additional
1996 actions that would be exceptions to these general rules, and then list specific
1997 URLs that these exceptions would apply to. Last match wins. Just below this
1998 then are two explict matches for ".google.com". The first is negating our
1999 various cookie blocking actions (i.e. we will allow cookies here). The second
2000 is allowing "fast-redirects". Note that there is a leading dot here --
2001 ".google.com". This will match any hosts and sub-domains, in the google.com
2002 domain also, such as "www.google.com". So, apparently, we have these actions
2003 defined somewhere in the lower part of our actions file, and "google.com" is
2004 referenced in these sections.
2006 And now we pull it altogether in the bottom section and summarize how Privoxy
2007 is appying all its "actions" to "google.com":
2011 -add-header -block -deanimate-gifs -downgrade -fast-redirects
2012 +filter{html-annoyances} +filter{js-annoyances} +filter{no-popups}
2013 +filter{webbugs} +filter{nimda} +filter{banners-by-size} +filter{hal}
2014 +filter{fun} +hide-forwarded +hide-from{block} +hide-referer{forge}
2015 -hide-user-agent -image +image-blocker{blank} -limit-connect +no-compression
2016 -no-cookies-keep -no-cookies-read -no-cookies-set +no-popups -vanilla-wafer
2021 Now another example, "ad.doubleclick.net":
2034 We'll just show the interesting part here, the explicit matches. It is matched
2035 three different times. Each as an "+block +image", which is the expanded form
2036 of one of our aliases that had been defined as: "+imageblock". ("Aliases" are
2037 defined in the first section of the actions file and typically used to combine
2038 more than one action.)
2040 Any one of these would have done the trick and blocked this as an unwanted
2041 image. This is unnecessarily redundant since the last case effectively would
2042 also cover the first. No point in taking chances with these guys though ;-)
2043 Note that if you want an ad or obnoxious URL to be invisible, it should be
2044 defined as "ad.doubleclick.net" is done here -- as both a "+block" and an
2045 "+image". The custom alias "+imageblock" does this for us.
2047 One last example. Let's try "http://www.rhapsodyk.net/adsl/HOWTO/". This one is
2048 giving us problems. We are getting a blank page. Hmmm...
2050 Matches for http://www.rhapsodyk.net/adsl/HOWTO/:
2052 { -add-header -block +deanimate-gifs -downgrade +fast-redirects
2053 +filter{html-annoyances} +filter{js-annoyances} +filter{no-popups}
2054 +filter{webbugs} +filter{nimda} +filter{banners-by-size} +filter{hal}
2055 +filter{fun} +hide-forwarded +hide-from{block} +hide-referer{forge}
2056 -hide-user-agent -image +image-blocker{blank} +no-compression
2057 +no-cookies-keep -no-cookies-read -no-cookies-set +no-popups
2058 -vanilla-wafer -wafer }
2066 Ooops, the "/adsl/" is matching "/ads"! But we did not want this at all! Now we
2067 see why we get the blank page. We could now add a new action below this that
2068 explictly does not block (-block) pages with "adsl". There are various ways to
2069 handle such exceptions. Example:
2076 Now the page displays ;-)
2078 But now what about a situation where we get no explicit matches like we did
2086 That actually was very telling and pointed us quickly to where the problem was.
2087 If you don't get this kind of match, then it means one of the default rules in
2088 the first section is causing the problem. This would require some guesswork,
2089 and maybe a little trial and error to isolate the offending rule. One likely
2090 cause would be one of the "{+filter}" actions. Try adding the URL for the site
2091 to one of aliases that turn off "+filter":
2095 .worldpay.com # for quietpc.com
2102 "{shop}" is an "alias" that expands to "{ -filter -no-cookies -no-cookies-keep
2103 }". Or you could do your own exception to negate filtering: