Sync with sgml.
[privoxy.git] / doc / text / user-manual.txt
1 Privoxy User Manual
2
3 Copyright © 2001, 2002 by Privoxy Developers
4
5 $Id: user-manual.sgml,v 1.111 2002/05/14 23:01:36 oes Exp $
6
7 The user manual gives users information on how to install, configure and use 
8 Privoxy.
9
10 Privoxy is a web proxy with advanced filtering capabilities for protecting
11 privacy, filtering web page content, managing cookies, controlling access, and
12 removing ads, banners, pop-ups and other obnoxious Internet junk. Privoxy has a
13 very flexible configuration and can be customized to suit individual needs and
14 tastes. Privoxy has application for both stand-alone systems and multi-user
15 networks.
16
17 Privoxy is based on Internet Junkbuster (tm).
18
19 You can find the latest version of the user manual at http://www.privoxy.org/
20 user-manual/. Please see the Contact section on how to contact the developers.
21
22 -------------------------------------------------------------------------------
23
24 Table of Contents
25 1. Introduction
26    
27     1.1. Features
28    
29 2. Installation
30    
31     2.1. Binary Packages
32        
33         2.1.1. Red Hat, SuSE RPMs and Conectiva
34         2.1.2. Debian
35         2.1.3. Windows
36         2.1.4. Solaris, NetBSD, FreeBSD, HP-UX
37         2.1.5. OS/2
38         2.1.6. Max OSX
39         2.1.7. AmigaOS
40        
41     2.2. Building from Source
42    
43 3. Note to Upgraders
44 4. Quickstart to Using Privoxy
45 5. Starting Privoxy
46    
47     5.1. RedHat, Conectiva and Debian
48     5.2. SuSE
49     5.3. Windows
50     5.4. Solaris, NetBSD, FreeBSD, HP-UX and others
51     5.5. OS/2
52     5.6. MAX OSX
53     5.7. AmigaOS
54     5.8. Command Line Options
55    
56 6. Privoxy Configuration
57    
58     6.1. Controlling Privoxy with Your Web Browser
59     6.2. Configuration Files Overview
60    
61 7. The Main Configuration File
62    
63     7.1. Configuration and Log File Locations
64        
65         7.1.1. confdir
66         7.1.2. logdir
67         7.1.3. actionsfile
68         7.1.4. filterfile
69         7.1.5. logfile
70         7.1.6. jarfile
71         7.1.7. trustfile
72        
73     7.2. Local Set-up Documentation
74        
75         7.2.1. user-manual
76         7.2.2. trust-info-url
77         7.2.3. admin-address
78         7.2.4. proxy-info-url
79        
80     7.3. Debugging
81        
82         7.3.1. debug
83         7.3.2. single-threaded
84        
85     7.4. Access Control and Security
86        
87         7.4.1. listen-address
88         7.4.2. toggle
89         7.4.3. enable-remote-toggle
90         7.4.4. enable-edit-actions
91         7.4.5. ACLs: permit-access and deny-access
92         7.4.6. buffer-limit
93        
94     7.5. Forwarding
95        
96         7.5.1. forward
97         7.5.2. forward-socks4 and forward-socks4a
98         7.5.3. Advanced Forwarding Examples
99        
100     7.6. Windows GUI Options
101    
102 8. Actions Files
103    
104     8.1. Finding the Right Mix
105     8.2. How to Edit
106     8.3. How Actions are Applied to URLs
107     8.4. Patterns
108        
109         8.4.1. The Domain Pattern
110         8.4.2. The Path Pattern
111        
112     8.5. Actions
113        
114         8.5.1. add-header
115         8.5.2. block
116         8.5.3. crunch-incoming-cookies
117         8.5.4. crunch-outgoing-cookies
118         8.5.5. deanimate-gifs
119         8.5.6. downgrade-http-version
120         8.5.7. fast-redirects
121         8.5.8. filter
122         8.5.9. handle-as-image
123         8.5.10. hide-forwarded-for-headers
124         8.5.11. hide-from-header
125         8.5.12. hide-referrer
126         8.5.13. hide-user-agent
127         8.5.14. kill-popups
128         8.5.15. limit-connect
129         8.5.16. prevent-compression
130         8.5.17. send-vanilla-wafer
131         8.5.18. send-wafer
132         8.5.19. session-cookies-only
133         8.5.20. set-image-blocker
134         8.5.21. Summary
135        
136     8.6. Aliases
137     8.7. Sample Actions Files
138    
139 9. The Filter File
140    
141     9.1. The +filter Action
142    
143 10. Templates
144 11. Contacting the Developers, Bug Reporting and Feature Requests
145    
146     11.1. Get Support
147     11.2. Report bugs
148     11.3. Request new features
149     11.4. Report ads or other filter problems
150     11.5. Other
151    
152 12. Privoxy Copyright, License and History
153    
154     12.1. License
155     12.2. History
156    
157 13. See Also
158 14. Appendix
159    
160     14.1. Regular Expressions
161     14.2. Privoxy's Internal Pages
162        
163         14.2.1. Bookmarklets
164        
165     14.3. Chain of Events
166     14.4. Anatomy of an Action
167    
168 1. Introduction
169
170 This documentation is included with the current beta version of Privoxy,
171 v.2.9.15, and is mostly complete at this point. The most up to date reference
172 for the time being is still the comments in the source files and in the
173 individual configuration files. Development of version 3.0 is currently nearing
174 completion, and includes many significant changes and enhancements over earlier
175 versions. The target release date for stable v3.0 is "soon" ;-).
176
177 Since this is a beta version, not all new features are well tested. This
178 documentation may be slightly out of sync as a result (especially with CVS
179 sources). And there may be bugs, though hopefully not many!
180
181 -------------------------------------------------------------------------------
182
183 1.1. Features
184
185 In addition to Internet Junkbuster's traditional features of ad and banner
186 blocking and cookie management, Privoxy provides new features, some of them
187 currently under development:
188
189   * Integrated browser based configuration and control utility at http://
190     config.privoxy.org/ (shortcut: http://p.p/). Browser-based tracing of rule
191     and filter effects. Remote toggling.
192    
193   * Web page content filtering (removes banners based on size, invisible
194     "web-bugs", JavaScript and HTML annoyances, pop-up windows, etc.)
195    
196   * Modularized configuration that allows for standard settings and user
197     settings to reside in separate files, so that installing updated actions
198     files won't overwrite individual user settings.
199    
200   * HTTP/1.1 compliant (but not all optional 1.1 features are supported).
201    
202   * Support for Perl Compatible Regular Expressions in the configuration files,
203     and generally a more sophisticated and flexible configuration syntax over
204     previous versions.
205    
206   * Improved cookie management features (e.g. session based cookies).
207    
208   * GIF de-animation.
209    
210   * Bypass many click-tracking scripts (avoids script redirection).
211    
212   * Multi-threaded (POSIX and native threads).
213    
214   * User-customizable HTML templates for all proxy-generated pages (e.g.
215     "blocked" page).
216    
217   * Auto-detection and re-reading of config file changes.
218    
219   * Improved signal handling, and a true daemon mode (Unix).
220    
221   * Every feature now controllable on a per-site or per-location basis,
222     configuration more powerful and versatile over-all.
223    
224   * Many smaller new features added, limitations and bugs removed, and security
225     holes fixed.
226    
227 -------------------------------------------------------------------------------
228
229 2. Installation
230
231 Privoxy is available both in convenient pre-compiled packages for a wide range
232 of operating systems, and as raw source code. For most users, we recommend
233 using the packages, which can be downloaded from our Privoxy Project Page.
234
235 Note: If you have a previous Junkbuster or Privoxy installation on your system,
236 you will need to remove it. On some platforms, this may be done for you as part
237 of their installation procedure. (See below for your platform). In any case be
238 sure to backup your old configuration if it is valuable to you. See the note to
239 upgraders section below.
240
241 -------------------------------------------------------------------------------
242
243 2.1. Binary Packages
244
245 How to install the binary packages depends on your operating system:
246
247 -------------------------------------------------------------------------------
248
249 2.1.1. Red Hat, SuSE RPMs and Conectiva
250
251 RPMs can be installed with rpm -Uvh privoxy-2.9.15-1.rpm, and will use /etc/
252 privoxy for the location of configuration files.
253
254 Note that on Red Hat, Privoxy will not be automatically started on system boot.
255 You will need to enable that using chkconfig, ntsysv, or similar methods. Note
256 that SuSE will automatically start Privoxy in the boot process.
257
258 If you have problems with failed dependencies, try rebuilding the SRC RPM: rpm
259 --rebuild privoxy-2.9.15-1.src.rpm;. This will use your locally installed
260 libraries and RPM version.
261
262 Also note that if you have a Junkbuster RPM installed on your system, you need
263 to remove it first, because the packages conflict. Otherwise, RPM will try to
264 remove Junkbuster automatically, before installing Privoxy.
265
266 -------------------------------------------------------------------------------
267
268 2.1.2. Debian
269
270 FIXME.
271
272 -------------------------------------------------------------------------------
273
274 2.1.3. Windows
275
276 Just double-click the installer, which will guide you through the installation
277 process. You will find the configuration files in the same directory as you
278 installed Privoxy in. We do not use the registry of Windows.
279
280 -------------------------------------------------------------------------------
281
282 2.1.4. Solaris, NetBSD, FreeBSD, HP-UX
283
284 Create a new directory, cd to it, then unzip and untar the archive. For the
285 most part, you'll have to figure out where things go. FIXME.
286
287 -------------------------------------------------------------------------------
288
289 2.1.5. OS/2
290
291 First, make sure that no previous installations of Junkbuster and / or Privoxy
292 are left on your system. You can do this by
293
294 Then, just double-click the WarpIN self-installing archive, which will guide
295 you through the installation process. A shadow of the Privoxy executable will
296 be placed in your startup folder so it will start automatically whenever OS/2
297 starts.
298
299 The directory you choose to install Privoxy into will contain all of the
300 configuration files.
301
302 -------------------------------------------------------------------------------
303
304 2.1.6. Max OSX
305
306 Unzip the downloaded package (you can either double-click on the file in the
307 finder, or on the desktop if you downloaded it there). Then, double-click on
308 the package installer icon and follow the installation process. Privoxy will be
309 installed in the subdirectory /Applications/Privoxy.app. Privoxy will set
310 itself up to start automatically on system bring-up via /System/Library/
311 StartupItems/Privoxy.
312
313 -------------------------------------------------------------------------------
314
315 2.1.7. AmigaOS
316
317 Copy and then unpack the lha archive to a suitable location. All necessary
318 files will be installed into Privoxy directory, including all configuration and
319 log files. To uninstall, just remove this directory.
320
321 Start Privoxy (with RUN <>NIL:) in your startnet script (AmiTCP), in s:
322 user-startup (RoadShow), as startup program in your startup script (Genesis),
323 or as startup action (Miami and MiamiDx). Privoxy will automatically quit when
324 you quit your TCP/IP stack (just ignore the harmless warning your TCP/IP stack
325 may display that Privoxy is still running).
326
327 -------------------------------------------------------------------------------
328
329 2.2. Building from Source
330
331 The most convenient way to obtain the Privoxy sources is to download the source
332 tarball from our project page.
333
334 If you like to live on the bleeding edge and are not afraid of using possibly
335 unstable development versions, you can check out the up-to-the-minute version
336 directly from the CVS repository or simply download the nightly CVS tarball.
337
338 To build Privoxy from source, autoconf, GNU make (gmake), and, of course, a C
339 compiler like gcc are required.
340
341 When building from a source tarball (either release version or nightly CVS
342 tarball), first unpack the source:
343
344  tar xzvf privoxy-2.9.15-beta-src* [.tgz or .tar.gz]                           
345  cd privoxy-2.9.15-beta                                                        
346
347 For retrieving the current CVS sources, you'll need CVS installed. Note that
348 sources from CVS are development quality, and may not be stable, or well
349 tested. To download CVS source:
350
351   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login          
352   cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co current 
353   cd current                                                                         
354
355 This will create a directory named current/, which will contain the source
356 tree.
357
358 Then, in either case, to build from unpacked tarball or CVS source:
359
360  autoheader                                                                    
361  autoconf                                                                      
362  ./configure      # (--help to see options)                                    
363  make             # (the make from gnu, gmake for *BSD)                        
364  su                                                                            
365  make -n install  # (to see where all the files will go)                       
366  make install     # (to really install)                                        
367
368 If you have gnu make, you can have the first four steps automatically done for
369 you by just typing:
370
371   make                                                                         
372
373 in the freshly downloaded or unpacked source directory.
374
375 For more detailed instructions on how to build Redhat and SuSE RPMs, Windows
376 self-extracting installers, building on platforms with special requirements
377 etc, please consult the developer manual.
378
379 -------------------------------------------------------------------------------
380
381 3. Note to Upgraders
382
383 There are very significant changes from earlier Junkbuster versions to the
384 current Privoxy. The number, names, syntax, and purposes of configuration files
385 have substantially changed. Junkbuster 2.0.x configuration files will not
386 migrate, Junkbuster 2.9.x and Privoxy configurations will need to be ported.
387 The functionalities of the old blockfile, cookiefile and imagelist are now
388 combined into the "actions files". default.action, is the main actions file.
389 Local exceptions should best be put into user.action.
390
391 A "filter file" (typically default.filter) is new as of Privoxy 2.9.x, and
392 provides some of the new sophistication (explained below). config is much the
393 same as before.
394
395 If upgrading from a 2.0.x version, you will have to use the new config files,
396 and possibly adapt any personal rules from your older files. When porting
397 personal rules over from the old blockfile to the new actions files, please
398 note that even the pattern syntax has changed. If upgrading from 2.9.x
399 development versions, it is still recommended to use the new configuration
400 files.
401
402 A quick list of things to be aware of before upgrading:
403
404   * The default listening port is now 8118 due to a conflict with another
405     service (NAS).
406    
407   * Some installers may remove earlier versions completely. Save any important
408     configuration files!
409    
410   * Privoxy is controllable with a web browser at the special URL: http://
411     config.privoxy.org/ (Shortcut: http://p.p/). Many aspects of configuration
412     can be done here, including temporarily disabling Privoxy.
413    
414   * The primary configuration file for cookie management, ad and banner
415     blocking, and many other aspects of Privoxy configuration is in the actions
416     files. It is strongly recommended to become familiar with the new actions
417     concept below, before modifying these files. Locally defined rules should
418     go into user.action.
419    
420   * Some installers may not automatically start Privoxy after installation.
421    
422 -------------------------------------------------------------------------------
423
424 4. Quickstart to Using Privoxy
425
426   * If upgrading, please back up any configuration files. See the Note to
427     Upgraders Section.
428    
429   * Install Privoxy. See the Installation Section for platform specific
430     information.
431    
432   * Start Privoxy, if the installation program has not done this already. See
433     the section Starting Privoxy.
434    
435   * Set your browser to use Privoxy as HTTP and HTTPS proxy by setting the
436     proxy configuration for address of 127.0.0.1 and port 8118. (Junkbuster and
437     earlier versions of Privoxy used port 8000.) See the section Starting
438     Privoxy.
439    
440   * Flush your browser's caches, to remove any cached ad images.
441    
442   * Enjoy surfing with enhanced comfort and privacy. You may want to customize
443     the user.action file to personalize your new browsing experience. See the 
444     Configuration section for more configuration options, and how to further
445     customize your installation.
446    
447   * If you experience problems with sites that "misbehave", see the Anatomy of
448     an Action section in the Appendix.
449    
450   * Please see the section Contacting the Developers on how to report bugs or
451     problems with websites or to get help.
452    
453 -------------------------------------------------------------------------------
454
455 5. Starting Privoxy
456
457 Before launching Privoxy for the first time, you will want to configure your
458 browser(s) to use Privoxy as a HTTP and HTTPS proxy. The default is 127.0.0.1
459 (or localhost) for the proxy address, and port 8118 (earlier versions used port
460 8000). This is the one configuration step that must be done!
461
462 With Netscape (and Mozilla), this can be set under Edit -> Preferences ->
463 Advanced -> Proxies -> HTTP Proxy. For Internet Explorer: Tools -> Internet
464 Properties -> Connections -> LAN Setting. Then, check "Use Proxy" and fill in
465 the appropriate info (Address: 127.0.0.1, Port: 8118). Include if HTTPS proxy
466 support too.
467
468 After doing this, flush your browser's disk and memory caches to force a
469 re-reading of all pages and to get rid of any ads that may be cached. You are
470 now ready to start enjoying the benefits of using Privoxy!
471
472 Privoxy is typically started by specifying the main configuration file to be
473 used on the command line. If no configuration file is specified on the command
474 line, Privoxy will look for a file named config in the current directory.
475 Except on Win32 where it will try config.txt.
476
477 -------------------------------------------------------------------------------
478
479 5.1. RedHat, Conectiva and Debian
480
481 We use a script. Note that RedHat does not start Privoxy upon booting per
482 default. It will use the file /etc/privoxy/config as its main configuration
483 file. FIXME: Debian??
484
485  # /etc/rc.d/init.d/privoxy start                                              
486
487 -------------------------------------------------------------------------------
488
489 5.2. SuSE
490
491 We use a script. It will use the file /etc/privoxy/config as its main
492 configuration file. Note that SuSE starts Privoxy upon booting your PC.
493
494  # rcprivoxy start                                                             
495
496 -------------------------------------------------------------------------------
497
498 5.3. Windows
499
500 Click on the Privoxy Icon to start Privoxy. If no configuration file is
501 specified on the command line, Privoxy will look for a file named config.txt.
502 Note that Windows will automatically start Privoxy upon booting you PC.
503
504 -------------------------------------------------------------------------------
505
506 5.4. Solaris, NetBSD, FreeBSD, HP-UX and others
507
508 Example Unix startup command:
509
510  # /usr/sbin/privoxy /etc/privoxy/config                                       
511
512 -------------------------------------------------------------------------------
513
514 5.5. OS/2
515
516 FIXME.
517
518 -------------------------------------------------------------------------------
519
520 5.6. MAX OSX
521
522 FIXME.
523
524 -------------------------------------------------------------------------------
525
526 5.7. AmigaOS
527
528 FIXME.
529
530 -------------------------------------------------------------------------------
531
532 5.8. Command Line Options
533
534 Privoxy may be invoked with the following command-line options:
535
536   * --version
537    
538     Print version info and exit. Unix only.
539    
540   * --help
541    
542     Print short usage info and exit. Unix only.
543    
544   * --no-daemon
545    
546     Don't become a daemon, i.e. don't fork and become process group leader, and
547     don't detach from controlling tty. Unix only.
548    
549   * --pidfile FILE
550    
551     On startup, write the process ID to FILE. Delete the FILE on exit. Failure
552     to create or delete the FILE is non-fatal. If no FILE option is given, no
553     PID file will be used. Unix only.
554    
555   * --user USER[.GROUP]
556    
557     After (optionally) writing the PID file, assume the user ID of USER, and if
558     included the GID of GROUP. Exit if the privileges are not sufficient to do
559     so. Unix only.
560    
561   * configfile
562    
563     If no configfile is included on the command line, Privoxy will look for a
564     file named "config" in the current directory (except on Win32 where it will
565     look for "config.txt" instead). Specify full path to avoid confusion. If no
566     config file is found, Privoxy will fail to start.
567    
568 -------------------------------------------------------------------------------
569
570 6. Privoxy Configuration
571
572 All Privoxy configuration is stored in text files. These files can be edited
573 with a text editor. Many important aspects of Privoxy can also be controlled
574 easily with a web browser.
575
576 -------------------------------------------------------------------------------
577
578 6.1. Controlling Privoxy with Your Web Browser
579
580 Privoxy's user interface can be reached through the special URL http://
581 config.privoxy.org/ (shortcut: http://p.p/), which is a built-in page and works
582 without Internet access. You will see the following section: 
583
584  Privoxy Menu                                                                  
585         ?  View & change the current configuration                             
586         ?  View the source code version numbers                                
587         ?  View the request headers.                                           
588         ?  Look up which actions apply to a URL and why                        
589         ?  Toggle Privoxy on or off                                            
590                                                                                
591
592 This should be self-explanatory. Note the first item leads to an editor for the
593 actions files, which is where the ad, banner, cookie, and URL blocking magic is
594 configured as well as other advanced features of Privoxy. This is an easy way
595 to adjust various aspects of Privoxy configuration. The actions file, and other
596 configuration files, are explained in detail below.
597
598 "Toggle Privoxy On or Off" is handy for sites that might have problems with
599 your current actions and filters. You can in fact use it as a test to see
600 whether it is Privoxy causing the problem or not. Privoxy continues to run as a
601 proxy in this case, but all manipulation is disabled, i.e. Privoxy acts like a
602 normal forwarding proxy. There is even a toggle Bookmarklet offered, so that
603 you can toggle Privoxy with one click from your browser.
604
605 -------------------------------------------------------------------------------
606
607 6.2. Configuration Files Overview
608
609 For Unix, *BSD and Linux, all configuration files are located in /etc/privoxy/
610 by default. For MS Windows, OS/2, and AmigaOS these are all in the same
611 directory as the Privoxy executable. The name and number of configuration files
612 has changed from previous versions, and is subject to change as development
613 progresses.
614
615 The installed defaults provide a reasonable starting point, though some
616 settings may be aggressive by some standards. For the time being, the principle
617 configuration files are:
618
619   * The main configuration file is named config on Linux, Unix, BSD, OS/2, and
620     AmigaOS and config.txt on Windows. This is a required file.
621    
622   * default.action (the main actions file) is used to define which "actions"
623     relating to banner-blocking, images, pop-ups, content modification, cookie
624     handling etc should be applied by default. It also defines many exceptions
625     (both positive and negative) from this default set of actions that enable
626     Privoxy to selectively eliminate the junk, and only the junk, on as many
627     websites as possible.
628    
629     Multiple actions files may be defined in config. These are processed in the
630     order they are defined. Local customizations and locally preferred
631     exceptions to the default policies as defined in default.action (which you
632     will most probably want to define sooner or later) are probably best
633     applied in user.action, where you can preserve them across upgrades.
634     standard.action is for Privoxy's internal use.
635    
636     There is also a web based editor that can be accessed from http://
637     config.privoxy.org/show-status (Shortcut: http://p.p/show-status) for the
638     various actions files.
639    
640   * default.filter (the filter file) can be used to re-write the raw page
641     content, including viewable text as well as embedded HTML and JavaScript,
642     and whatever else lurks on any given web page. The filtering jobs are only
643     pre-defined here; whether to apply them or not is up to the actions files.
644    
645 All files use the "#" character to denote a comment (the rest of the line will
646 be ignored) and understand line continuation through placing a backslash ("\")
647 as the very last character in a line. If the # is preceded by a backslash, it
648 looses its special function. Placing a # in front of an otherwise valid
649 configuration line to prevent it from being interpreted is called "commenting
650 out" that line.
651
652 The actions files and default.filter can use Perl style regular expressions for
653 maximum flexibility.
654
655 After making any changes, there is no need to restart Privoxy in order for the
656 changes to take effect. Privoxy detects such changes automatically. Note,
657 however, that it may take one or two additional requests for the change to take
658 effect. When changing the listening address of Privoxy, these "wake up"
659 requests must obviously be sent to the old listening address.
660
661 While under development, the configuration content is subject to change. The
662 below documentation may not be accurate by the time you read this. Also, what
663 constitutes a "default" setting, may change, so please check all your
664 configuration files on important issues.
665
666 -------------------------------------------------------------------------------
667
668 7. The Main Configuration File
669
670 Again, the main configuration file is named config on Linux/Unix/BSD and OS/2,
671 and config.txt on Windows. Configuration lines consist of an initial keyword
672 followed by a list of values, all separated by whitespace (any number of spaces
673 or tabs). For example:
674
675   confdir /etc/privoxy
676
677 Assigns the value /etc/privoxy to the option confdir and thus indicates that
678 the configuration directory is named "/etc/privoxy/".
679
680 All options in the config file except for confdir and logdir are optional.
681 Watch out in the below description for what happens if you leave them unset.
682
683 The main config file controls all aspects of Privoxy's operation that are not
684 location dependent (i.e. they apply universally, no matter where you may be
685 surfing).
686
687 -------------------------------------------------------------------------------
688
689 7.1. Configuration and Log File Locations
690
691 Privoxy can (and normally does) use a number of other files for additional
692 configuration, help and logging. This section of the configuration file tells
693 Privoxy where to find those other files.
694
695 The user running Privoxy, must have read permission for all configuration
696 files, and write permission to any files that would be modified, such as log
697 files.
698
699 -------------------------------------------------------------------------------
700
701 7.1.1. confdir
702
703 Specifies:
704    
705     The directory where the other configuration files are located
706    
707 Type of value:
708    
709     Path name
710    
711 Default value:
712    
713     /etc/privoxy (Unix) or Privoxy installation dir (Windows)
714    
715 Effect if unset:
716    
717     Mandatory
718    
719 Notes:
720    
721     No trailing "/", please
722    
723     When development goes modular and multi-user, the blocker, filter, and
724     per-user config will be stored in subdirectories of "confdir". For now, the
725     configuration directory structure is flat, except for confdir/templates,
726     where the HTML templates for CGI output reside (e.g. Privoxy's 404 error
727     page).
728    
729 -------------------------------------------------------------------------------
730
731 7.1.2. logdir
732
733 Specifies:
734    
735     The directory where all logging takes place (i.e. where logfile and jarfile
736     are located)
737    
738 Type of value:
739    
740     Path name
741    
742 Default value:
743    
744     /var/log/privoxy (Unix) or Privoxy installation dir (Windows)
745    
746 Effect if unset:
747    
748     Mandatory
749    
750 Notes:
751    
752     No trailing "/", please
753    
754 -------------------------------------------------------------------------------
755
756 7.1.3. actionsfile
757
758 Specifies:
759    
760     The actions file(s) to use
761    
762 Type of value:
763    
764     File name, relative to confdir, without the .action suffix
765    
766 Default value:
767    
768       standard     # Internal purposes, no editing recommended
769                                                               
770       default      # Main actions file                        
771                                                               
772       user         # User customizations                      
773    
774 Effect if unset:
775    
776     No actions are taken at all. Simple neutral proxying.
777    
778 Notes:
779    
780     Multiple actionsfile lines are permitted, and are in fact recommended!
781    
782     The default values include standard.action, which is used for internal
783     purposes and should be loaded, default.action, which is the "main" actions
784     file maintained by the developers, and user.action, where you can make your
785     personal additions.
786    
787     Actions files are where all the per site and per URL configuration is done
788     for ad blocking, cookie management, privacy considerations, etc. There is
789     no point in using Privoxy without at least one actions file.
790    
791 -------------------------------------------------------------------------------
792
793 7.1.4. filterfile
794
795 Specifies:
796    
797     The filter file to use
798    
799 Type of value:
800    
801     File name, relative to confdir
802    
803 Default value:
804    
805     default.filter (Unix) or default.filter.txt (Windows)
806    
807 Effect if unset:
808    
809     No textual content filtering takes place, i.e. all +filter{name} actions in
810     the actions files are turned neutral.
811    
812 Notes:
813    
814     The "default.filter" file contains content modification rules that use
815     "regular expressions". These rules permit powerful changes on the content
816     of Web pages, e.g., you could disable your favorite JavaScript annoyances,
817     re-write the actual displayed text, or just have some fun replacing
818     "Microsoft" with "MicroSuck" wherever it appears on a Web page.
819    
820 -------------------------------------------------------------------------------
821
822 7.1.5. logfile
823
824 Specifies:
825    
826     The log file to use
827    
828 Type of value:
829    
830     File name, relative to logdir
831    
832 Default value:
833    
834     logfile (Unix) or privoxy.log (Windows)
835    
836 Effect if unset:
837    
838     No log file is used, all log messages go to the console (stderr).
839    
840 Notes:
841    
842     The windows version will additionally log to the console.
843    
844     The logfile is where all logging and error messages are written. The level
845     of detail and number of messages are set with the debug option (see below).
846     The logfile can be useful for tracking down a problem with Privoxy (e.g.,
847     it's not blocking an ad you think it should block) but in most cases you
848     probably will never look at it.
849    
850     Your logfile will grow indefinitely, and you will probably want to
851     periodically remove it. On Unix systems, you can do this with a cron job
852     (see "man cron"). For Red Hat, a logrotate script has been included.
853    
854     On SuSE Linux systems, you can place a line like "/var/log/privoxy.* +1024k
855     644 nobody.nogroup" in /etc/logfiles, with the effect that cron.daily will
856     automatically archive, gzip, and empty the log, when it exceeds 1M size.
857    
858     Any log files must be writable by whatever user Privoxy is being run as
859     (default on UNIX, user id is "privoxy").
860    
861 -------------------------------------------------------------------------------
862
863 7.1.6. jarfile
864
865 Specifies:
866    
867     The file to store intercepted cookies in
868    
869 Type of value:
870    
871     File name, relative to logdir
872    
873 Default value:
874    
875     jarfile (Unix) or privoxy.jar (Windows)
876    
877 Effect if unset:
878    
879     Intercepted cookies are not stored at all.
880    
881 Notes:
882    
883     The jarfile may grow to ridiculous sizes over time.
884    
885 -------------------------------------------------------------------------------
886
887 7.1.7. trustfile
888
889 Specifies:
890    
891     The trust file to use
892    
893 Type of value:
894    
895     File name, relative to confdir
896    
897 Default value:
898    
899     Unset (commented out). When activated: trust (Unix) or trust.txt (Windows)
900    
901 Effect if unset:
902    
903     The whole trust mechanism is turned off.
904    
905 Notes:
906    
907     The trust mechanism is an experimental feature for building white-lists and
908     should be used with care. It is NOT recommended for the casual user.
909    
910     If you specify a trust file, Privoxy will only allow access to sites that
911     are named in the trustfile. You can also mark sites as trusted referrers
912     (with +), with the effect that access to untrusted sites will be granted,
913     if a link from a trusted referrer was used. The link target will then be
914     added to the "trustfile". Possible applications include limiting Internet
915     access for children.
916    
917     If you use + operator in the trust file, it may grow considerably over
918     time.
919    
920 -------------------------------------------------------------------------------
921
922 7.2. Local Set-up Documentation
923
924 If you intend to operate Privoxy for more users than just yourself, it might be
925 a good idea to let them know how to reach you, what you block and why you do
926 that, your policies, etc.
927
928 -------------------------------------------------------------------------------
929
930 7.2.1. user-manual
931
932 Specifies:
933    
934     Location of the Privoxy User Manual.
935    
936 Type of value:
937    
938     A fully qualified URI
939    
940 Default value:
941    
942     Unset
943    
944 Effect if unset:
945    
946     http://www.privoxy.org/version/user-manual/ will be used, where version is
947     the Privoxy version.
948    
949 Notes:
950    
951     The User Manual URI is used for help links from some of the internal CGI
952     pages. The manual itself is normally packaged with the binary
953     distributions, so you probably want to set this to a locally installed
954     copy. For multi-user setups, you could provide a copy on a local webserver
955     for all your users and use the corresponding URL here.
956    
957     Examples:
958    
959     Unix, in local filesystem:
960    
961     user-manual  file:///usr/share/doc/privoxy-2.9.15/user-manual/     
962    
963     Any platform, on local webserver (called "local-webserver"):
964    
965     user-manual  http://local-webserver/privoxy-user-manual/           
966    
967     +-----------------------------------------------------------------+
968     |                             Warning                             |
969     |-----------------------------------------------------------------|
970     |If set, this option should be the first option in the config     |
971     |file, because it is used while the config file is being read.    |
972     +-----------------------------------------------------------------+
973
974 -------------------------------------------------------------------------------
975
976 7.2.2. trust-info-url
977
978 Specifies:
979    
980     A URL to be displayed in the error page that users will see if access to an
981     untrusted page is denied.
982    
983 Type of value:
984    
985     URL
986    
987 Default value:
988    
989     Two example URL are provided
990    
991 Effect if unset:
992    
993     No links are displayed on the "untrusted" error page.
994    
995 Notes:
996    
997     The value of this option only matters if the experimental trust mechanism
998     has been activated. (See trustfile above.)
999    
1000     If you use the trust mechanism, it is a good idea to write up some on-line
1001     documentation about your trust policy and to specify the URL(s) here. Use
1002     multiple times for multiple URLs.
1003    
1004     The URL(s) should be added to the trustfile as well, so users don't end up
1005     locked out from the information on why they were locked out in the first
1006     place!
1007    
1008 -------------------------------------------------------------------------------
1009
1010 7.2.3. admin-address
1011
1012 Specifies:
1013    
1014     An email address to reach the proxy administrator.
1015    
1016 Type of value:
1017    
1018     Email address
1019    
1020 Default value:
1021    
1022     Unset
1023    
1024 Effect if unset:
1025    
1026     No email address is displayed on error pages and the CGI user interface.
1027    
1028 Notes:
1029    
1030     If both admin-address and proxy-info-url are unset, the whole "Local
1031     Privoxy Support" box on all generated pages will not be shown.
1032    
1033 -------------------------------------------------------------------------------
1034
1035 7.2.4. proxy-info-url
1036
1037 Specifies:
1038    
1039     A URL to documentation about the local Privoxy setup, configuration or
1040     policies.
1041    
1042 Type of value:
1043    
1044     URL
1045    
1046 Default value:
1047    
1048     Unset
1049    
1050 Effect if unset:
1051    
1052     No link to local documentation is displayed on error pages and the CGI user
1053     interface.
1054    
1055 Notes:
1056    
1057     If both admin-address and proxy-info-url are unset, the whole "Local
1058     Privoxy Support" box on all generated pages will not be shown.
1059    
1060     This URL shouldn't be blocked ;-)
1061    
1062 -------------------------------------------------------------------------------
1063
1064 7.3. Debugging
1065
1066 These options are mainly useful when tracing a problem. Note that you might
1067 also want to invoke Privoxy with the --no-daemon command line option when
1068 debugging.
1069
1070 -------------------------------------------------------------------------------
1071
1072 7.3.1. debug
1073
1074 Specifies:
1075    
1076     Key values that determine what information gets logged to the logfile.
1077    
1078 Type of value:
1079    
1080     Integer values
1081    
1082 Default value:
1083    
1084     12289 (i.e.: URLs plus informational and warning messages)
1085    
1086 Effect if unset:
1087    
1088     Nothing gets logged.
1089    
1090 Notes:
1091    
1092     The available debug levels are:
1093    
1094       debug         1 # show each GET/POST/CONNECT request             
1095       debug         2 # show each connection status                    
1096       debug         4 # show I/O status                                
1097       debug         8 # show header parsing                            
1098       debug        16 # log all data into the logfile                  
1099       debug        32 # debug force feature                            
1100       debug        64 # debug regular expression filter                
1101       debug       128 # debug fast redirects                           
1102       debug       256 # debug GIF de-animation                         
1103       debug       512 # Common Log Format                              
1104       debug      1024 # debug kill pop-ups                             
1105       debug      4096 # Startup banner and warnings.                   
1106       debug      8192 # Non-fatal errors                               
1107    
1108     To select multiple debug levels, you can either add them or use multiple
1109     debug lines.
1110    
1111     A debug level of 1 is informative because it will show you each request as
1112     it happens. 1, 4096 and 8192 are highly recommended so that you will notice
1113     when things go wrong. The other levels are probably only of interest if you
1114     are hunting down a specific problem. They can produce a hell of an output
1115     (especially 16).
1116    
1117     The reporting of fatal errors (i.e. ones which crash Privoxy) is always on
1118     and cannot be disabled.
1119    
1120     If you want to use CLF (Common Log Format), you should set "debug 512" ONLY
1121     and not enable anything else.
1122    
1123 -------------------------------------------------------------------------------
1124
1125 7.3.2. single-threaded
1126
1127 Specifies:
1128    
1129     Whether to run only one server thread
1130    
1131 Type of value:
1132    
1133     None
1134    
1135 Default value:
1136    
1137     Unset
1138    
1139 Effect if unset:
1140    
1141     Multi-threaded (or, where unavailable: forked) operation, i.e. the ability
1142     to serve multiple requests simultaneously.
1143    
1144 Notes:
1145    
1146     This option is only there for debug purposes and you should never need to
1147     use it. It will drastically reduce performance.
1148    
1149 -------------------------------------------------------------------------------
1150
1151 7.4. Access Control and Security
1152
1153 This section of the config file controls the security-relevant aspects of
1154 Privoxy's configuration.
1155
1156 -------------------------------------------------------------------------------
1157
1158 7.4.1. listen-address
1159
1160 Specifies:
1161    
1162     The IP address and TCP port on which Privoxy will listen for client
1163     requests.
1164    
1165 Type of value:
1166    
1167     [IP-Address]:Port
1168    
1169 Default value:
1170    
1171     127.0.0.1:8118
1172    
1173 Effect if unset:
1174    
1175     Bind to 127.0.0.1 (localhost), port 8118. This is suitable and recommended
1176     for home users who run Privoxy on the same machine as their browser.
1177    
1178 Notes:
1179    
1180     You will need to configure your browser(s) to this proxy address and port.
1181    
1182     If you already have another service running on port 8118, or if you want to
1183     serve requests from other machines (e.g. on your local network) as well,
1184     you will need to override the default.
1185    
1186     If you leave out the IP address, Privoxy will bind to all interfaces
1187     (addresses) on your machine and may become reachable from the Internet. In
1188     that case, consider using access control lists (ACL's) (see "ACLs" below),
1189     or a firewall.
1190    
1191 Example:
1192    
1193     Suppose you are running Privoxy on a machine which has the address
1194     192.168.0.1 on your local private network (192.168.0.0) and has another
1195     outside connection with a different address. You want it to serve requests
1196     from inside only:
1197    
1198       listen-address  192.168.0.1:8118                                 
1199    
1200 -------------------------------------------------------------------------------
1201
1202 7.4.2. toggle
1203
1204 Specifies:
1205    
1206     Initial state of "toggle" status
1207    
1208 Type of value:
1209    
1210     1 or 0
1211    
1212 Default value:
1213    
1214     1
1215    
1216 Effect if unset:
1217    
1218     Act as if toggled on
1219    
1220 Notes:
1221    
1222     If set to 0, Privoxy will start in "toggled off" mode, i.e. behave like a
1223     normal, content-neutral proxy where all ad blocking, filtering, etc are
1224     disabled. See enable-remote-toggle below. This is not really useful
1225     anymore, since toggling is much easier via the web interface than via
1226     editing the conf file.
1227    
1228     The windows version will only display the toggle icon in the system tray if
1229     this option is present.
1230    
1231 -------------------------------------------------------------------------------
1232
1233 7.4.3. enable-remote-toggle
1234
1235 Specifies:
1236    
1237     Whether or not the web-based toggle feature may be used
1238    
1239 Type of value:
1240    
1241     0 or 1
1242    
1243 Default value:
1244    
1245     1
1246    
1247 Effect if unset:
1248    
1249     The web-based toggle feature is disabled.
1250    
1251 Notes:
1252    
1253     When toggled off, Privoxy acts like a normal, content-neutral proxy, i.e.
1254     it acts as if none of the actions applied to any URL.
1255    
1256     For the time being, access to the toggle feature can not be controlled
1257     separately by "ACLs" or HTTP authentication, so that everybody who can
1258     access Privoxy (see "ACLs" and listen-address above) can toggle it for all
1259     users. So this option is not recommended for multi-user environments with
1260     untrusted users.
1261    
1262     Note that you must have compiled Privoxy with support for this feature,
1263     otherwise this option has no effect.
1264    
1265 -------------------------------------------------------------------------------
1266
1267 7.4.4. enable-edit-actions
1268
1269 Specifies:
1270    
1271     Whether or not the web-based actions file editor may be used
1272    
1273 Type of value:
1274    
1275     0 or 1
1276    
1277 Default value:
1278    
1279     1
1280    
1281 Effect if unset:
1282    
1283     The web-based actions file editor is disabled.
1284    
1285 Notes:
1286    
1287     For the time being, access to the editor can not be controlled separately
1288     by "ACLs" or HTTP authentication, so that everybody who can access Privoxy
1289     (see "ACLs" and listen-address above) can modify its configuration for all
1290     users. So this option is not recommended for multi-user environments with
1291     untrusted users.
1292    
1293     Note that you must have compiled Privoxy with support for this feature,
1294     otherwise this option has no effect.
1295    
1296 -------------------------------------------------------------------------------
1297
1298 7.4.5. ACLs: permit-access and deny-access
1299
1300 Specifies:
1301    
1302     Who can access what.
1303    
1304 Type of value:
1305    
1306     src_addr[/src_masklen] [dst_addr[/dst_masklen]]
1307    
1308     Where src_addr and dst_addr are IP addresses in dotted decimal notation or
1309     valid DNS names, and src_masklen and dst_masklen are subnet masks in CIDR
1310     notation, i.e. integer values from 2 to 30 representing the length (in
1311     bits) of the network address. The masks and the whole destination part are
1312     optional.
1313    
1314 Default value:
1315    
1316     Unset
1317    
1318 Effect if unset:
1319    
1320     Don't restrict access further than implied by listen-address
1321    
1322 Notes:
1323    
1324     Access controls are included at the request of ISPs and systems
1325     administrators, and are not usually needed by individual users. For a
1326     typical home user, it will normally suffice to ensure that Privoxy only
1327     listens on the localhost (127.0.0.1) or internal (home) network address by
1328     means of the listen-address option.
1329    
1330     Please see the warnings in the FAQ that this proxy is not intended to be a
1331     substitute for a firewall or to encourage anyone to defer addressing basic
1332     security weaknesses.
1333    
1334     Multiple ACL lines are OK. If any ACLs are specified, then the Privoxy
1335     talks only to IP addresses that match at least one permit-access line and
1336     don't match any subsequent deny-access line. In other words, the last match
1337     wins, with the default being deny-access.
1338    
1339     If Privoxy is using a forwarder (see forward below) for a particular
1340     destination URL, the dst_addr that is examined is the address of the
1341     forwarder and NOT the address of the ultimate target. This is necessary
1342     because it may be impossible for the local Privoxy to determine the IP
1343     address of the ultimate target (that's often what gateways are used for).
1344    
1345     You should prefer using IP addresses over DNS names, because the address
1346     lookups take time. All DNS names must resolve! You can not use domain
1347     patterns like "*.org" or partial domain names. If a DNS name resolves to
1348     multiple IP addresses, only the first one is used.
1349    
1350     Denying access to particular sites by ACL may have undesired side effects
1351     if the site in question is hosted on a machine which also hosts other
1352     sites.
1353    
1354 Examples:
1355    
1356     Explicitly define the default behavior if no ACL and listen-address are
1357     set: "localhost" is OK. The absence of a dst_addr implies that all
1358     destination addresses are OK:
1359    
1360       permit-access  localhost                                         
1361    
1362     Allow any host on the same class C subnet as www.privoxy.org access to
1363     nothing but www.example.com:
1364    
1365       permit-access  www.privoxy.org/24 www.example.com/32             
1366    
1367     Allow access from any host on the 26-bit subnet 192.168.45.64 to anywhere,
1368     with the exception that 192.168.45.73 may not access
1369     www.dirty-stuff.example.com:
1370    
1371       permit-access  192.168.45.64/26                                  
1372       deny-access    192.168.45.73    www.dirty-stuff.example.com      
1373    
1374 -------------------------------------------------------------------------------
1375
1376 7.4.6. buffer-limit
1377
1378 Specifies:
1379    
1380     Maximum size of the buffer for content filtering.
1381    
1382 Type of value:
1383    
1384     Size in Kbytes
1385    
1386 Default value:
1387    
1388     4096
1389    
1390 Effect if unset:
1391    
1392     Use a 4MB (4096 KB) limit.
1393    
1394 Notes:
1395    
1396     For content filtering, i.e. the +filter and +deanimate-gif actions, it is
1397     necessary that Privoxy buffers the entire document body. This can be
1398     potentially dangerous, since a server could just keep sending data
1399     indefinitely and wait for your RAM to exhaust -- with nasty consequences.
1400     Hence this option.
1401    
1402     When a document buffer size reaches the buffer-limit, it is flushed to the
1403     client unfiltered and no further attempt to filter the rest of the document
1404     is made. Remember that there may be multiple threads running, which might
1405     require up to buffer-limit Kbytes each, unless you have enabled
1406     "single-threaded" above.
1407    
1408 -------------------------------------------------------------------------------
1409
1410 7.5. Forwarding
1411
1412 This feature allows routing of HTTP requests through a chain of multiple
1413 proxies. It can be used to better protect privacy and confidentiality when
1414 accessing specific domains by routing requests to those domains through an
1415 anonymous public proxy (see e.g. http://www.multiproxy.org/anon_list.htm) Or to
1416 use a caching proxy to speed up browsing. Or chaining to a parent proxy may be
1417 necessary because the machine that Privoxy runs on has no direct Internet
1418 access.
1419
1420 Also specified here are SOCKS proxies. Privoxy supports the SOCKS 4 and SOCKS
1421 4A protocols.
1422
1423 -------------------------------------------------------------------------------
1424
1425 7.5.1. forward
1426
1427 Specifies:
1428    
1429     To which parent HTTP proxy specific requests should be routed.
1430    
1431 Type of value:
1432    
1433     target_domain[:port] http_parent[/port]
1434    
1435     Where target_domain is a domain name pattern (see the chapter on domain
1436     matching in the default.action file), http_parent is the address of the
1437     parent HTTP proxy as an IP addresses in dotted decimal notation or as a
1438     valid DNS name (or "." to denote "no forwarding", and the optional port
1439     parameters are TCP ports, i.e. integer values from 1 to 64535
1440    
1441 Default value:
1442    
1443     Unset
1444    
1445 Effect if unset:
1446    
1447     Don't use parent HTTP proxies.
1448    
1449 Notes:
1450    
1451     If http_parent is ".", then requests are not forwarded to another HTTP
1452     proxy but are made directly to the web servers.
1453    
1454     Multiple lines are OK, they are checked in sequence, and the last match
1455     wins.
1456    
1457 Examples:
1458    
1459     Everything goes to an example anonymizing proxy, except SSL on port 443
1460     (which it doesn't handle):
1461    
1462       forward   .*     anon-proxy.example.org:8080                     
1463       forward   :443   .                                               
1464    
1465     Everything goes to our example ISP's caching proxy, except for requests to
1466     that ISP's sites:
1467    
1468       forward   .*.                caching-proxy.example-isp.net:8000  
1469       forward   .example-isp.net   .                                   
1470    
1471 -------------------------------------------------------------------------------
1472
1473 7.5.2. forward-socks4 and forward-socks4a
1474
1475 Specifies:
1476    
1477     Through which SOCKS proxy (and to which parent HTTP proxy) specific
1478     requests should be routed.
1479    
1480 Type of value:
1481    
1482     target_domain[:port] socks_proxy[/port] http_parent[/port]
1483    
1484     Where target_domain is a domain name pattern (see the chapter on domain
1485     matching in the default.action file), http_parent and socks_proxy are IP
1486     addresses in dotted decimal notation or valid DNS names (http_parent may be
1487     "." to denote "no HTTP forwarding"), and the optional port parameters are
1488     TCP ports, i.e. integer values from 1 to 64535
1489    
1490 Default value:
1491    
1492     Unset
1493    
1494 Effect if unset:
1495    
1496     Don't use SOCKS proxies.
1497    
1498 Notes:
1499    
1500     Multiple lines are OK, they are checked in sequence, and the last match
1501     wins.
1502    
1503     The difference between forward-socks4 and forward-socks4a is that in the
1504     SOCKS 4A protocol, the DNS resolution of the target hostname happens on the
1505     SOCKS server, while in SOCKS 4 it happens locally.
1506    
1507     If http_parent is ".", then requests are not forwarded to another HTTP
1508     proxy but are made (HTTP-wise) directly to the web servers, albeit through
1509     a SOCKS proxy.
1510    
1511 Examples:
1512    
1513     From the company example.com, direct connections are made to all "internal"
1514     domains, but everything outbound goes through their ISP's proxy by way of
1515     example.com's corporate SOCKS 4A gateway to the Internet.
1516    
1517       forward-socks4a   .*.            socks-gw.example.com:1080  www-cache.example-isp.net:8080 
1518       forward           .example.com   .                                                         
1519    
1520     A rule that uses a SOCKS 4 gateway for all destinations but no HTTP parent
1521     looks like this:
1522    
1523       forward-socks4   .*.            socks-gw.example.com:1080  .     
1524    
1525 -------------------------------------------------------------------------------
1526
1527 7.5.3. Advanced Forwarding Examples
1528
1529 If you have links to multiple ISPs that provide various special content only to
1530 their subscribers, you can configure multiple Privoxies which have connections
1531 to the respective ISPs to act as forwarders to each other, so that your users
1532 can see the internal content of all ISPs.
1533
1534 Assume that host-a has a PPP connection to isp-a.net. And host-b has a PPP
1535 connection to isp-b.net. Both run Privoxy. Their forwarding configuration can
1536 look like this:
1537
1538 host-a:
1539
1540   forward    .*.         .                                                     
1541   forward    .isp-b.net  host-b:8118                                           
1542
1543 host-b:
1544
1545   forward    .*.         .                                                     
1546   forward    .isp-a.net  host-a:8118                                           
1547
1548 Now, your users can set their browser's proxy to use either host-a or host-b
1549 and be able to browse the internal content of both isp-a and isp-b.
1550
1551 If you intend to chain Privoxy and squid locally, then chain as browser ->
1552 squid -> privoxy is the recommended way.
1553
1554 Assuming that Privoxy and squid run on the same box, your squid configuration
1555 could then look like this:
1556
1557   # Define Privoxy as parent proxy (without ICP)                               
1558   cache_peer 127.0.0.1 parent 8118 7 no-query                                  
1559                                                                                
1560   # Define ACL for protocol FTP                                                
1561   acl ftp proto FTP                                                            
1562                                                                                
1563   # Do not forward FTP requests to Privoxy                                     
1564   always_direct allow ftp                                                      
1565                                                                                
1566   # Forward all the rest to Privoxy                                            
1567   never_direct allow all                                                       
1568
1569 You would then need to change your browser's proxy settings to squid's address
1570 and port. Squid normally uses port 3128. If unsure consult http_port in
1571 squid.conf.
1572
1573 -------------------------------------------------------------------------------
1574
1575 7.6. Windows GUI Options
1576
1577 Privoxy has a number of options specific to the Windows GUI interface:
1578
1579 If "activity-animation" is set to 1, the Privoxy icon will animate when
1580 "Privoxy" is active. To turn off, set to 0.
1581
1582   activity-animation 1
1583    
1584
1585 If "log-messages" is set to 1, Privoxy will log messages to the console window:
1586
1587   log-messages 1
1588    
1589
1590 If "log-buffer-size" is set to 1, the size of the log buffer, i.e. the amount
1591 of memory used for the log messages displayed in the console window, will be
1592 limited to "log-max-lines" (see below).
1593
1594 Warning: Setting this to 0 will result in the buffer to grow infinitely and eat
1595 up all your memory!
1596
1597   log-buffer-size 1
1598    
1599
1600 log-max-lines is the maximum number of lines held in the log buffer. See above.
1601
1602   log-max-lines 200
1603    
1604
1605 If "log-highlight-messages" is set to 1, Privoxy will highlight portions of the
1606 log messages with a bold-faced font:
1607
1608   log-highlight-messages 1
1609    
1610
1611 The font used in the console window:
1612
1613   log-font-name Comic Sans MS
1614    
1615
1616 Font size used in the console window:
1617
1618   log-font-size 8
1619    
1620
1621 "show-on-task-bar" controls whether or not Privoxy will appear as a button on
1622 the Task bar when minimized:
1623
1624   show-on-task-bar 0
1625    
1626
1627 If "close-button-minimizes" is set to 1, the Windows close button will minimize
1628 Privoxy instead of closing the program (close with the exit option on the File
1629 menu).
1630
1631   close-button-minimizes 1
1632    
1633
1634 The "hide-console" option is specific to the MS-Win console version of Privoxy.
1635 If this option is used, Privoxy will disconnect from and hide the command
1636 console.
1637
1638   #hide-console
1639    
1640
1641 -------------------------------------------------------------------------------
1642
1643 8. Actions Files
1644
1645 The actions files are used to define what actions Privoxy takes for which URLs,
1646 and thus determine how ad images, cookies and various other aspects of HTTP
1647 content and transactions are handled, and on which sites (or even parts
1648 thereof). There are three such files included with Privoxy (as of version
1649 2.9.15), with differing purposes:
1650
1651   * standard.action - is used by the web based editor, to set various
1652     pre-defined sets of rules for the default actions section in
1653     default.action. These have increasing levels of aggressiveness and have no
1654     influence on your browsing unless you select them explicitly in the editor.
1655     It is not recommend to edit this file.
1656    
1657   * default.action - is the primary action file that sets the initial values
1658     for all actions. It is intended to provide a base level of functionality
1659     for Privoxy's array of features. So it is a set of broad rules that should
1660     work reasonably well for users everywhere. This is the file that the
1661     developers are keeping updated, and making available to users.
1662    
1663   * user.action - is intended to be for local site preferences and exceptions.
1664     As an example, if your ISP or your bank has specific requirements, and need
1665     special handling, this kind of thing should go here. This file will not be
1666     upgraded.
1667    
1668 The list of actions files to be used are defined in the main configuration
1669 file, and are processed in the order they are defined. The content of these can
1670 all be viewed and edited from http://config.privoxy.org/show-status.
1671
1672 An actions file typically has multiple sections. If you want to use "aliases"
1673 in an actions file, you have to place the (optional) alias section at the top
1674 of that file. Then comes the default set of rules which will apply universally
1675 to all sites and pages (be very careful with using such a universal set in
1676 user.action or any other actions file after default.action, because it will
1677 override the result from consulting any previous file). And then below that,
1678 exceptions to the defined universal policies. You can regard user.action as an
1679 appendix to default.action, with the advantage that is a separate file, which
1680 makes preserving your personal settings across Privoxy upgrades easier.
1681
1682 Actions can be used to block anything you want, including ads, banners, or just
1683 some obnoxious URL that you would rather not see. Cookies can be accepted or
1684 rejected, or accepted only during the current browser session (i.e. not written
1685 to disk), content can be modified, JavaScripts tamed, user-tracking fooled, and
1686 much more. See below for a complete list of actions.
1687
1688 -------------------------------------------------------------------------------
1689
1690 8.1. Finding the Right Mix
1691
1692 Note that some actions, like cookie suppression or script disabling, may render
1693 some sites unusable that rely on these techniques to work properly. Finding the
1694 right mix of actions is not always easy and certainly a matter of personal
1695 taste. In general, it can be said that the more "aggressive" your default
1696 settings (in the top section of the actions file) are, the more exceptions for
1697 "trusted" sites you will have to make later. If, for example, you want to kill
1698 popup windows per default, you'll have to make exceptions from that rule for
1699 sites that you regularly use and that require popups for actually useful
1700 content, like maybe your bank, favorite shop, or newspaper.
1701
1702 We have tried to provide you with reasonable rules to start from in the
1703 distribution actions files. But there is no general rule of thumb on these
1704 things. There just are too many variables, and sites are constantly changing.
1705 Sooner or later you will want to change the rules (and read this chapter again
1706 :).
1707
1708 -------------------------------------------------------------------------------
1709
1710 8.2. How to Edit
1711
1712 The easiest way to edit the actions files is with a browser by using our
1713 browser-based editor, which can be reached from http://config.privoxy.org/
1714 show-status. The editor allows both fine-grained control over every single
1715 feature on a per-URL basis, and easy choosing from wholesale sets of defaults
1716 like "Cautious", "Medium" or "Advanced".
1717
1718 If you prefer plain text editing to GUIs, you can of course also directly edit
1719 the the actions files. Look at default.action which is richly commented.
1720
1721 -------------------------------------------------------------------------------
1722
1723 8.3. How Actions are Applied to URLs
1724
1725 Actions files are divided into sections. There are special sections, like the "
1726 alias" sections which will be discussed later. For now let's concentrate on
1727 regular sections: They have a heading line (often split up to multiple lines
1728 for readability) which consist of a list of actions, separated by whitespace
1729 and enclosed in curly braces. Below that, there is a list of URL patterns, each
1730 on a separate line.
1731
1732 To determine which actions apply to a request, the URL of the request is
1733 compared to all patterns in each action file file. Every time it matches, the
1734 list of applicable actions for the URL is incrementally updated, using the
1735 heading of the section in which the pattern is located. If multiple matches for
1736 the same URL set the same action differently, the last match wins. If not, the
1737 effects are aggregated (e.g. a URL might match both the "+handle-as-image" and 
1738 "+block" actions).
1739
1740 You can trace this process for any given URL by visiting http://
1741 config.privoxy.org/show-url-info.
1742
1743 More detail on this is provided in the Appendix, Anatomy of an Action.
1744
1745 -------------------------------------------------------------------------------
1746
1747 8.4. Patterns
1748
1749 Generally, a pattern has the form <domain>/<path>, where both the <domain> and
1750 <path> are optional. (This is why the pattern / matches all URLs).
1751
1752 www.example.com/
1753    
1754     is a domain-only pattern and will match any request to www.example.com,
1755     regardless of which document on that server is requested.
1756    
1757 www.example.com
1758    
1759     means exactly the same. For domain-only patterns, the trailing / may be
1760     omitted.
1761    
1762 www.example.com/index.html
1763    
1764     matches only the single document /index.html on www.example.com.
1765    
1766 /index.html
1767    
1768     matches the document /index.html, regardless of the domain, i.e. on any web
1769     server.
1770    
1771 index.html
1772    
1773     matches nothing, since it would be interpreted as a domain name and there
1774     is no top-level domain called .html.
1775    
1776 -------------------------------------------------------------------------------
1777
1778 8.4.1. The Domain Pattern
1779
1780 The matching of the domain part offers some flexible options: if the domain
1781 starts or ends with a dot, it becomes unanchored at that end. For example:
1782
1783 .example.com
1784    
1785     matches any domain that ENDS in .example.com
1786    
1787 www.
1788    
1789     matches any domain that STARTS with www.
1790    
1791 .example.
1792    
1793     matches any domain that CONTAINS .example. (Correctly speaking: It matches
1794     any FQDN that contains example as a domain.)
1795    
1796 Additionally, there are wild-cards that you can use in the domain names
1797 themselves. They work pretty similar to shell wild-cards: "*" stands for zero
1798 or more arbitrary characters, "?" stands for any single character, you can
1799 define character classes in square brackets and all of that can be freely
1800 mixed:
1801
1802 ad*.example.com
1803    
1804     matches "adserver.example.com", "ads.example.com", etc but not
1805     "sfads.example.com"
1806    
1807 *ad*.example.com
1808    
1809     matches all of the above, and then some.
1810    
1811 .?pix.com
1812    
1813     matches www.ipix.com, pictures.epix.com, a.b.c.d.e.upix.com etc.
1814    
1815 www[1-9a-ez].example.c*
1816    
1817     matches www1.example.com, www4.example.cc, wwwd.example.cy,
1818     wwwz.example.com etc., but not wwww.example.com.
1819    
1820 -------------------------------------------------------------------------------
1821
1822 8.4.2. The Path Pattern
1823
1824 Privoxy uses Perl compatible regular expressions (through the PCRE library) for
1825 matching the path.
1826
1827 There is an Appendix with a brief quick-start into regular expressions, and
1828 full (very technical) documentation on PCRE regex syntax is available on-line
1829 at http://www.pcre.org/man.txt. You might also find the Perl man page on
1830 regular expressions (man perlre) useful, which is available on-line at http://
1831 www.perldoc.com/perl5.6/pod/perlre.html.
1832
1833 Note that the path pattern is automatically left-anchored at the "/", i.e. it
1834 matches as if it would start with a "^" (regular expression speak for the
1835 beginning of a line).
1836
1837 Please also note that matching in the path is case INSENSITIVE by default, but
1838 you can switch to case sensitive at any point in the pattern by using the "(?
1839 -i)" switch: www.example.com/(?-i)PaTtErN.* will match only documents whose
1840 path starts with PaTtErN in exactly this capitalization.
1841
1842 -------------------------------------------------------------------------------
1843
1844 8.5. Actions
1845
1846 All actions are disabled by default, until they are explicitly enabled
1847 somewhere in an actions file. Actions are turned on if preceded with a "+", and
1848 turned off if preceded with a "-". So a +action means "do that action", e.g.
1849 +block means "please block URLs that match the following patterns", and -block
1850 means "don't block URLs that match the following patterns, even if +block
1851 previously applied." 
1852
1853 Again, actions are invoked by placing them on a line, enclosed in curly braces
1854 and separated by whitespace, like in {+some-action -some-other-action
1855 {some-parameter}}, followed by a list of URL patterns, one per line, to which
1856 they apply. Together, the actions line and the following pattern lines make up
1857 a section of the actions file.
1858
1859 There are three classes of actions:
1860
1861   * Boolean, i.e the action can only be "enabled" or "disabled". Syntax:
1862    
1863       +name        # enable action name                                
1864       -name        # disable action name                               
1865    
1866     Example: +block
1867    
1868   * Parameterized, where some value is required in order to enable this type of
1869     action. Syntax:
1870    
1871       +name{param}  # enable action and set parameter to param,             
1872                    # overwriting parameter from previous match if necessary 
1873       -name         # disable action. The parameter can be omitted          
1874    
1875     Note that if the URL matches multiple positive forms of a parameterized
1876     action, the last match wins, i.e. the params from earlier matches are
1877     simply ignored.
1878    
1879     Example: +hide-user-agent{ Mozilla 1.0 }
1880    
1881   * Multi-value. These look exactly like parameterized actions, but they behave
1882     differently: If the action applies multiple times to the same URL, but with
1883     different parameters, all the parameters from all matches are remembered.
1884     This is used for actions that can be executed for the same request
1885     repeatedly, like adding multiple headers, or filtering through multiple
1886     filters. Syntax:
1887    
1888       +name{param}   # enable action and add param to the list of parameters                 
1889       -name{param}   # remove the parameter param from the list of parameters                
1890                     # If it was the last one left, disable the action.                       
1891       -name          # disable this action completely and remove all parameters from the list
1892    
1893     Examples: +add-header{X-Fun-Header: Some text} and +filter{html-annoyances}
1894    
1895 If nothing is specified in any actions file, no "actions" are taken. So in this
1896 case Privoxy would just be a normal, non-blocking, non-anonymizing proxy. You
1897 must specifically enable the privacy and blocking features you need (although
1898 the provided default actions files will give a good starting point).
1899
1900 Later defined actions always over-ride earlier ones. So exceptions to any rules
1901 you make, should come in the latter part of the file (or in a file that is
1902 processed later when using multiple actions files). For multi-valued actions,
1903 the actions are applied in the order they are specified. Actions files are
1904 processed in the order they are defined in config (the default installation has
1905 three actions files). It also quite possible for any given URL pattern to match
1906 more than one pattern and thus more than one set of actions!
1907
1908 The list of valid Privoxy actions are:
1909
1910 -------------------------------------------------------------------------------
1911
1912 8.5.1. add-header
1913
1914 Typical use:
1915    
1916     Confuse log analysis, custom applications
1917    
1918 Effect:
1919    
1920     Sends a user defined HTTP header to the web server.
1921    
1922 Type:
1923    
1924     Multi-value.
1925    
1926 Parameter:
1927    
1928     Any string value is possible. Validity of the defined HTTP headers is not
1929     checked. It is recommended that you use the "X-" prefix for custom headers.
1930    
1931 Notes:
1932    
1933     This action may be specified multiple times, in order to define multiple
1934     headers. This is rarely needed for the typical user. If you don't know what
1935     "HTTP headers" are, you definitely don't need to worry about this one.
1936    
1937 Example usage:
1938    
1939     +add-header{X-User-Tracking: sucks}                                
1940    
1941 -------------------------------------------------------------------------------
1942
1943 8.5.2. block
1944
1945 Typical use:
1946    
1947     Block ads or other obnoxious content
1948    
1949 Effect:
1950    
1951     Requests for URLs to which this action applies are blocked, i.e. the
1952     requests are not forwarded to the remote server, but answered locally with
1953     a substitute page or image, as determined by the handle-as-image and 
1954     set-image-blocker actions.
1955    
1956 Type:
1957    
1958     Boolean.
1959    
1960 Parameter:
1961    
1962     N/A
1963    
1964 Notes:
1965    
1966     Privoxy sends a special "BLOCKED" page for requests to blocked pages. This
1967     page contains links to find out why the request was blocked, and a
1968     click-through to the blocked content (the latter only if compiled with the
1969     force feature enabled). The "BLOCKED" page adapts to the available screen
1970     space -- it displays full-blown if space allows, or miniaturized and
1971     text-only if loaded into a small frame or window. If you are using Privoxy
1972     right now, you can take a look at the "BLOCKED" page.
1973    
1974     A very important exception occurs if both block and handle-as-image, apply
1975     to the same request: it will then be replaced by an image. If 
1976     set-image-blocker (see below) also applies, the type of image will be
1977     determined by its parameter, if not, the standard checkerboard pattern is
1978     sent.
1979    
1980     It is important to understand this process, in order to understand how
1981     Privoxy deals with ads and other unwanted content.
1982    
1983     The filter action can perform a very similar task, by "blocking" banner
1984     images and other content through rewriting the relevant URLs in the
1985     document's HTML source, so they don't get requested in the first place.
1986     Note that this is a totally different technique, and it's easy to confuse
1987     the two.
1988    
1989 Example usage (section):
1990    
1991     {+block}      # Block and replace with "blocked" page              
1992     .nasty-stuff.example.com                                           
1993                                                                        
1994     {+block +handle-as-image} # Block and replace with image           
1995     .ad.doubleclick.net                                                
1996     .ads.r.us                                                          
1997    
1998 -------------------------------------------------------------------------------
1999
2000 8.5.3. crunch-incoming-cookies
2001
2002 Typical use:
2003    
2004     Prevent the web server from setting any cookies on your system
2005    
2006 Effect:
2007    
2008     Deletes any "Set-Cookie:" HTTP headers from server replies.
2009    
2010 Type:
2011    
2012     Boolean.
2013    
2014 Parameter:
2015    
2016     N/A
2017    
2018 Notes:
2019    
2020     This action is only concerned with incoming cookies. For outgoing cookies,
2021     use crunch-outgoing-cookies. Use both to disable cookies completely.
2022    
2023     It makes no sense at all to use this action in conjunction with the 
2024     session-cookies-only action, since it would prevent the session cookies
2025     from being set.
2026    
2027 Example usage:
2028    
2029     +crunch-incoming-cookies                                           
2030    
2031 -------------------------------------------------------------------------------
2032
2033 8.5.4. crunch-outgoing-cookies
2034
2035 Typical use:
2036    
2037     Prevent the web server from reading any cookies from your system
2038    
2039 Effect:
2040    
2041     Deletes any "Cookie:" HTTP headers from client requests.
2042    
2043 Type:
2044    
2045     Boolean.
2046    
2047 Parameter:
2048    
2049     N/A
2050    
2051 Notes:
2052    
2053     This action is only concerned with outgoing cookies. For incoming cookies,
2054     use crunch-incoming-cookies. Use both to disable cookies completely.
2055    
2056     It makes no sense at all to use this action in conjunction with the 
2057     session-cookies-only action, since it would prevent the session cookies
2058     from being read.
2059    
2060 Example usage:
2061    
2062     +crunch-outgoing-cookies                                           
2063    
2064 -------------------------------------------------------------------------------
2065
2066 8.5.5. deanimate-gifs
2067
2068 Typical use:
2069    
2070     Stop those annoying, distracting animated GIF images.
2071    
2072 Effect:
2073    
2074     De-animate GIF animations, i.e. reduce them to their first or last image.
2075    
2076 Type:
2077    
2078     Parameterized.
2079    
2080 Parameter:
2081    
2082     "last" or "first"
2083    
2084 Notes:
2085    
2086     This will also shrink the images considerably (in bytes, not pixels!). If
2087     the option "first" is given, the first frame of the animation is used as
2088     the replacement. If "last" is given, the last frame of the animation is
2089     used instead, which probably makes more sense for most banner animations,
2090     but also has the risk of not showing the entire last frame (if it is only a
2091     delta to an earlier frame).
2092    
2093     You can safely use this action with patterns that will also match non-GIF
2094     objects, because no attempt will be made at anything that doesn't look like
2095     a GIF.
2096    
2097 Example usage:
2098    
2099     +deanimate-gifs{last}                                              
2100    
2101 -------------------------------------------------------------------------------
2102
2103 8.5.6. downgrade-http-version
2104
2105 Typical use:
2106    
2107     Work around (very rare) problems with HTTP/1.1
2108    
2109 Effect:
2110    
2111     Downgrades HTTP/1.1 client requests and server replies to HTTP/1.0.
2112    
2113 Type:
2114    
2115     Boolean.
2116    
2117 Parameter:
2118    
2119     N/A
2120    
2121 Notes:
2122    
2123     This is a left-over from the time when Privoxy didn't support important
2124     HTTP/1.1 features well. It is left here for the unlikely case that you
2125     experience HTTP/1.1 related problems with some server out there. Not all
2126     (optional) HTTP/1.1 features are supported yet, so there is a chance you
2127     might need this action.
2128    
2129 Example usage (section):
2130    
2131     {+downgrade-http-version}                                          
2132     problem-host.example.com                                           
2133    
2134 -------------------------------------------------------------------------------
2135
2136 8.5.7. fast-redirects
2137
2138 Typical use:
2139    
2140     Fool some click-tracking scripts and speed up indirect links
2141    
2142 Effect:
2143    
2144     Cut off all but the last valid URL from requests.
2145    
2146 Type:
2147    
2148     Boolean.
2149    
2150 Parameter:
2151    
2152     N/A
2153    
2154 Notes:
2155    
2156     Many sites, like yahoo.com, don't just link to other sites. Instead, they
2157     will link to some script on their own servers, giving the destination as a
2158     parameter, which will then redirect you to the final target. URLs resulting
2159     from this scheme typically look like: http://some.place/click-tracker.cgi?
2160     target=http://some.where.else.
2161    
2162     Sometimes, there are even multiple consecutive redirects encoded in the
2163     URL. These redirections via scripts make your web browsing more traceable,
2164     since the server from which you follow such a link can see where you go to.
2165     Apart from that, valuable bandwidth and time is wasted, while your browser
2166     ask the server for one redirect after the other. Plus, it feeds the
2167     advertisers.
2168    
2169     This feature is currently not very smart and is scheduled for improvement.
2170     It is likely to break some sites. You should expect to need possibly many
2171     exceptions to this action, if it is enabled by default in default.action.
2172     Some sites just don't work without it.
2173    
2174 Example usage:
2175    
2176     {+fast-redirects}                                                  
2177    
2178 -------------------------------------------------------------------------------
2179
2180 8.5.8. filter
2181
2182 Typical use:
2183    
2184     Get rid of HTML and JavaScript annoyances, banner advertisements (by size),
2185     do fun text replacements, etc.
2186    
2187 Effect:
2188    
2189     Text documents, including HTML and JavaScript, to which this action
2190     applies, are filtered on-the-fly through the specified regular expression
2191     based substitutions.
2192    
2193 Type:
2194    
2195     Parameterized.
2196    
2197 Parameter:
2198    
2199     The name of a filter, as defined in the filter file (typically
2200     default.filter, set by the filterfile option in the config file)
2201    
2202 Notes:
2203    
2204     For your convenience, there are a bunch of pre-defined filters available in
2205     the distribution filter file that you can use. See the example below for a
2206     list.
2207    
2208     This is potentially a very powerful feature! But "rolling your own" filters
2209     requires a knowledge of regular expressions and HTML.
2210    
2211     Filtering requires buffering the page content, which may appear to slow
2212     down page rendering since nothing is displayed until all content has passed
2213     the filters. (It does not really take longer, but seems that way since the
2214     page is not incrementally displayed.) This effect will be more noticeable
2215     on slower connections.
2216    
2217     At this time, Privoxy cannot (yet!) uncompress compressed documents. If you
2218     want filtering to work on all documents, even those that would normally be
2219     sent compressed, use the prevent-compression action in conjunction with
2220     filter.
2221    
2222     Filtering can achieve some of the effects as the block action, i.e. it can
2223     be used to block ads and banners.
2224    
2225     Feedback with suggestions for new or improved filters is particularly
2226     welcome!
2227    
2228 Example usage (with filters from the distribution default.filter file):
2229    
2230     +filter{html-annoyances}     # Get rid of particularly annoying HTML abuse.
2231    
2232     +filter{js-annoyances}       # Get rid of particularly annoying JavaScript abuse
2233    
2234     +filter{banners-by-size}     # Kill banners by size (very efficient!)
2235    
2236     +filter{content-cookies}     # Kill cookies that come sneaking in the HTML or JS content
2237    
2238     +filter{popups}              # Kill all popups in JS and HTML      
2239    
2240     +filter{webbugs}             # Squish WebBugs (1x1 invisible GIFs used for user tracking)
2241    
2242     +filter{fun}                 # Text replacements for subversive browsing fun!
2243    
2244     +filter{frameset-borders}    # Give frames a border and make them resizeable
2245    
2246     +filter{refresh-tags}        # Kill automatic refresh tags (for dial-on-demand setups)
2247    
2248     +filter{nimda}               # Remove Nimda (virus) code.          
2249    
2250     +filter{shockwave-flash}     # Kill embedded Shockwave Flash objects
2251    
2252     +filter{crude-parental}      # Kill all web pages that contain the words "sex" or "warez"
2253    
2254 -------------------------------------------------------------------------------
2255
2256 8.5.9. handle-as-image
2257
2258 Typical use:
2259    
2260     Mark URLs as belonging to images (so they'll be replaced by images if they
2261     get blocked)
2262    
2263 Effect:
2264    
2265     This action alone doesn't do anything noticeable. It just marks URLs as
2266     images. If the block action also applies, the presence or absence of this
2267     mark decides whether an HTML "blocked" page, or a replacement image (as
2268     determined by the set-image-blocker action) will be sent to the client as a
2269     substitute for the blocked content.
2270    
2271 Type:
2272    
2273     Boolean.
2274    
2275 Parameter:
2276    
2277     N/A
2278    
2279 Notes:
2280    
2281     The below generic example section is actually part of default.action. It
2282     marks all URLs with well-known image file name extensions as images and
2283     should be left intact.
2284    
2285     Users will probably only want to use the handle-as-image action in
2286     conjunction with block, to block sources of banners, whose URLs don't
2287     reflect the file type, like in the second example section.
2288    
2289     Note that you cannot treat HTML pages as images in most cases. For
2290     instance, (inline) ad frames require an HTML page to be sent, or they won't
2291     display properly. Forcing handle-as-image in this situation will not
2292     replace the ad frame with an image, but lead to error messages.
2293    
2294 Example usage (sections):
2295    
2296     # Generic image extensions:                                        
2297     #                                                                  
2298     {+handle-as-image}                                                 
2299     /.*\.(gif|jpg|jpeg|png|bmp|ico)$                                   
2300                                                                        
2301     # These don't look like images, but they're banners and should be  
2302     # blocked as images:                                               
2303     #                                                                  
2304     {+block +handle-as-image}                                          
2305     some.nasty-banner-server.com/junk.cgi?output=trash                 
2306                                                                        
2307     # Banner source! Who cares if they also have non-image content?    
2308     ad.doubleclick.net                                                 
2309    
2310 -------------------------------------------------------------------------------
2311
2312 8.5.10. hide-forwarded-for-headers
2313
2314 Typical use:
2315    
2316     Improve privacy by hiding the true source of the request
2317    
2318 Effect:
2319    
2320     Deletes any existing "X-Forwarded-for:" HTTP header from client requests,
2321     and prevents adding a new one.
2322    
2323 Type:
2324    
2325     Boolean.
2326    
2327 Parameter:
2328    
2329     N/A
2330    
2331 Notes:
2332    
2333     It is fairly safe to leave this on.
2334    
2335     This action is scheduled for improvement: It should be able to generate
2336     forged "X-Forwarded-for:" headers using random IP addresses from a
2337     specified network, to make successive requests from the same client look
2338     like requests from a pool of different users sharing the same proxy.
2339    
2340 Example usage:
2341    
2342     +hide-forwarded-for-headers                                        
2343    
2344 -------------------------------------------------------------------------------
2345
2346 8.5.11. hide-from-header
2347
2348 Typical use:
2349    
2350     Keep your (old and ill) browser from telling web servers your email address
2351    
2352 Effect:
2353    
2354     Deletes any existing "From:" HTTP header, or replaces it with the specified
2355     string.
2356    
2357 Type:
2358    
2359     Parameterized.
2360    
2361 Parameter:
2362    
2363     Keyword: "block", or any user defined value.
2364    
2365 Notes:
2366    
2367     The keyword "block" will completely remove the header (not to be confused
2368     with the block action).
2369    
2370     Alternately, you can specify any value you prefer to be sent to the web
2371     server. If you do, it is a matter of fairness not to use any address that
2372     is actually used by a real person.
2373    
2374     This action is rarely needed, as modern web browsers don't send "From:"
2375     headers anymore.
2376    
2377 Example usage:
2378    
2379     +hide-from-header{block}                                           
2380    
2381     or
2382    
2383     +hide-from-header{spam-me-senseless@sittingduck.example.com}       
2384    
2385 -------------------------------------------------------------------------------
2386
2387 8.5.12. hide-referrer
2388
2389 Typical use:
2390    
2391     Conceal which link you followed to get to a particular site
2392    
2393 Effect:
2394    
2395     Deletes the "Referer:" (sic) HTTP header from the client request, or
2396     replaces it with a forged one.
2397    
2398 Type:
2399    
2400     Parameterized.
2401    
2402 Parameter:
2403    
2404       + "block" to delete the header completely.
2405        
2406       + "forge" to pretend to be coming from the homepage of the server we are
2407         talking to.
2408        
2409       + Any other string to set a user defined referrer.
2410        
2411 Notes:
2412    
2413     "forge" is the preferred option here, since some servers will not send
2414     images back otherwise, in an attempt to prevent their valuable content from
2415     being embedded elsewhere (and hence, without being surrounded by their
2416     banners).
2417    
2418     hide-referer is an alternate spelling of hide-referrer and the two can be
2419     can be freely substituted with each other. ("referrer" is the correct
2420     English spelling, however the HTTP specification has a bug - it requires it
2421     to be spelled as "referer".)
2422    
2423 Example usage:
2424    
2425     +hide-referrer{forge}                                              
2426    
2427     or
2428    
2429     +hide-referrer{http://www.yahoo.com/}                              
2430    
2431 -------------------------------------------------------------------------------
2432
2433 8.5.13. hide-user-agent
2434
2435 Typical use:
2436    
2437     Conceal your type of browser and client operating system
2438    
2439 Effect:
2440    
2441     Replaces the value of the "User-Agent:" HTTP header in client requests with
2442     the specified value.
2443    
2444 Type:
2445    
2446     Parameterized.
2447    
2448 Parameter:
2449    
2450     Any user-defined string.
2451    
2452 Notes:
2453    
2454     +-----------------------------------------------------------------+
2455     |                             Warning                             |
2456     |-----------------------------------------------------------------|
2457     |This breaks many web sites that depend on looking at this header |
2458     |in order to customize their content for different browsers       |
2459     |(which, by the way, is NOT a smart way to do that!).             |
2460     +-----------------------------------------------------------------+
2461    
2462     Using this action in multi-user setups or wherever different types of
2463     browsers will access the same Privoxy is not recommended. In single-user,
2464     single-browser setups, you might use it to delete your OS version
2465     information from the headers, because it is an invitation to exploit known
2466     bugs for your OS. It is also occasionally useful to forge this in order to
2467     access sites that won't let you in otherwise (though there may be a good
2468     reason in some cases). Example of this: some MSN sites will not let Mozilla
2469     enter, yet forging to a Netscape 6.1 user-agent works just fine. (Must be
2470     just a silly MS goof, I'm sure :-).
2471    
2472     This action is scheduled for improvement.
2473    
2474 Example usage:
2475    
2476     +hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)}         
2477    
2478 -------------------------------------------------------------------------------
2479
2480 8.5.14. kill-popups
2481
2482 Typical use:
2483    
2484     Eliminate those annoying pop-up windows
2485    
2486 Effect:
2487    
2488     While loading the document, replace JavaScript code that opens pop-up
2489     windows with (syntactically neutral) dummy code on the fly.
2490    
2491 Type:
2492    
2493     Boolean.
2494    
2495 Parameter:
2496    
2497     N/A
2498    
2499 Notes:
2500    
2501     This action is easily confused with the built-in, hardwired filter action,
2502     but there are important differences: For kill-popups, the document need not
2503     be buffered, so it can be incrementally rendered while downloading. But
2504     kill-popups doesn't catch as many pop-ups as filter{popups} does.
2505    
2506     Think of it as a fast and efficient replacement for a filter that you can
2507     use if you don't want any filtering at all. Note that it doesn't make sense
2508     to combine it with any filter action, since as soon as one filter applies,
2509     the whole document needs to be buffered anyway, which destroys the
2510     advantage of the kill-popups action over it's filter equivalent.
2511    
2512     Killing all pop-ups is a dangerous business. Many shops and banks rely on
2513     pop-ups to display forms, shopping carts etc, and killing only the unwanted
2514     pop-ups would require artificial intelligence in Privoxy. If the only kind
2515     of pop-ups that you want to kill are exit consoles (those really nasty
2516     windows that appear when you close an other one), you might want to use 
2517     filter{js-annoyances} instead.
2518    
2519 Example usage:
2520    
2521     +kill-popups                                                       
2522    
2523 -------------------------------------------------------------------------------
2524
2525 8.5.15. limit-connect
2526
2527 Typical use:
2528    
2529     Prevent abuse of Privoxy as a TCP proxy relay
2530    
2531 Effect:
2532    
2533     Specifies to which ports HTTP CONNECT requests are allowable.
2534    
2535 Type:
2536    
2537     Parameterized.
2538    
2539 Parameter:
2540    
2541     A comma-separated list of ports or port ranges (the latter using dashes,
2542     with the minimum defaulting to 0 and the maximum to 65K).
2543    
2544 Notes:
2545    
2546     By default, i.e. if no limit-connect action applies, Privoxy only allows
2547     HTTP CONNECT requests to port 443 (the standard, secure HTTPS port). Use
2548     limit-connect if more fine-grained control is desired for some or all
2549     destinations.
2550    
2551     The CONNECT methods exists in HTTP to allow access to secure websites
2552     ("https://" URLs) through proxies. It works very simply: the proxy connects
2553     to the server on the specified port, and then short-circuits its
2554     connections to the client and to the remote server. This can be a big
2555     security hole, since CONNECT-enabled proxies can be abused as TCP relays
2556     very easily.
2557    
2558     If you don't know what any of this means, there probably is no reason to
2559     change this one, since the default is already very restrictive.
2560    
2561 Example usages:
2562    
2563     +limit-connect{443}                   # This is the default and need not be specified.        
2564     +limit-connect{80,443}                # Ports 80 and 443 are OK.                              
2565     +limit-connect{-3, 7, 20-100, 500-}   # Ports less than 3, 7, 20 to 100 and above 500 are OK. 
2566     +limit-connect{-}                     # All ports are OK (gaping security hole!)              
2567    
2568 -------------------------------------------------------------------------------
2569
2570 8.5.16. prevent-compression
2571
2572 Typical use:
2573    
2574     Ensure that servers send the content uncompressed, so it can be passed
2575     through filters
2576    
2577 Effect:
2578    
2579     Adds a header to the request that asks for uncompressed transfer.
2580    
2581 Type:
2582    
2583     Boolean.
2584    
2585 Parameter:
2586    
2587     N/A
2588    
2589 Notes:
2590    
2591     More and more websites send their content compressed by default, which is
2592     generally a good idea and saves bandwidth. But for the filter, 
2593     deanimate-gifs and kill-popups actions to work, Privoxy needs access to the
2594     uncompressed data. Unfortunately, Privoxy can't yet(!) uncompress, filter,
2595     and re-compress the content on the fly. So if you want to ensure that all
2596     websites, including those that normally compress, can be filtered, you need
2597     to use this action.
2598    
2599     This will slow down transfers from those websites, though. If you use any
2600     of the above-mentioned actions, you will typically want to use
2601     prevent-compression in conjunction with them.
2602    
2603     Note that some (rare) ill-configured sites don't handle requests for
2604     uncompressed documents correctly (they send an empty document body). If you
2605     use prevent-compression per default, you'll have to add exceptions for
2606     those sites. See the example for how to do that.
2607    
2608 Example usage (sections):
2609    
2610     # Set default:                                                     
2611     #                                                                  
2612     {+prevent-compression}                                             
2613     / # Match all sites                                                
2614                                                                        
2615     # Make exceptions for ill sites:                                   
2616     #                                                                  
2617     {-prevent-compression}                                             
2618     www.debianhelp.org                                                 
2619     www.pclinuxonline.com                                              
2620    
2621 -------------------------------------------------------------------------------
2622
2623 8.5.17. send-vanilla-wafer
2624
2625 Typical use:
2626    
2627     Feed log analysis scripts with useless data.
2628    
2629 Effect:
2630    
2631     Sends a cookie with each request stating that you do not accept any
2632     copyright on cookies sent to you, and asking the site operator not to track
2633     you.
2634    
2635 Type:
2636    
2637     Boolean.
2638    
2639 Parameter:
2640    
2641     N/A
2642    
2643 Notes:
2644    
2645     The vanilla wafer is a (relatively) unique header and could conceivably be
2646     used to track you.
2647    
2648     This action is rarely used and not enabled in the default configuration.
2649    
2650 Example usage:
2651    
2652     +send-vanilla-wafer                                                
2653    
2654 -------------------------------------------------------------------------------
2655
2656 8.5.18. send-wafer
2657
2658 Typical use:
2659    
2660     Send custom cookies or feed log analysis scripts with even more useless
2661     data.
2662    
2663 Effect:
2664    
2665     Sends a custom, user-defined cookie with each request.
2666    
2667 Type:
2668    
2669     Multi-value.
2670    
2671 Parameter:
2672    
2673     A string of the form "name=value".
2674    
2675 Notes:
2676    
2677     Being multi-valued, multiple instances of this action can apply to the same
2678     request, resulting in multiple cookies being sent.
2679    
2680     This action is rarely used and not enabled in the default configuration.
2681    
2682 Example usage (section):
2683    
2684     {+send-wafer{UsingPrivoxy=true}}                                   
2685     my-internal-testing-server.void                                    
2686    
2687 -------------------------------------------------------------------------------
2688
2689 8.5.19. session-cookies-only
2690
2691 Typical use:
2692    
2693     Allow only temporary "session" cookies (for the current browser session
2694     only).
2695    
2696 Effect:
2697    
2698     Deletes the "expires" field from "Set-Cookie:" server headers. Most
2699     browsers will not store such cookies permanently and forget them in between
2700     sessions.
2701    
2702 Type:
2703    
2704     Boolean.
2705    
2706 Parameter:
2707    
2708     N/A
2709    
2710 Notes:
2711    
2712     This is less strict than crunch-incoming-cookies / crunch-outgoing-cookies
2713     and allows you to browse websites that insist or rely on setting cookies,
2714     without compromising your privacy too badly.
2715    
2716     Most browsers will not permanently store cookies that have been processed
2717     by session-cookies-only and will forget about them between sessions. This
2718     makes profiling cookies useless, but won't break sites which require
2719     cookies so that you can log in for transactions. This is generally turned
2720     on for all sites, and is the recommended setting.
2721    
2722     It makes no sense at all to use session-cookies-only together with 
2723     crunch-incoming-cookies or crunch-outgoing-cookies. If you do, cookies will
2724     be plainly killed.
2725    
2726     Note that it is up to the browser how it handles such cookies without an
2727     "expires" field. If you use an exotic browser, you might want to try it out
2728     to be sure.
2729    
2730 Example usage:
2731    
2732     +session-cookies-only                                              
2733    
2734 -------------------------------------------------------------------------------
2735
2736 8.5.20. set-image-blocker
2737
2738 Typical use:
2739    
2740     Choose the replacement for blocked images
2741    
2742 Effect:
2743    
2744     This action alone doesn't do anything noticeable. If both block and 
2745     handle-as-image also apply, i.e. if the request is to be blocked as an
2746     image, then the parameter of this action decides what will be sent as a
2747     replacement.
2748    
2749 Type:
2750    
2751     Parameterized.
2752    
2753 Parameter:
2754    
2755       + "pattern" to send a built-in checkerboard pattern image. The image is
2756         visually decent, scales very well, and makes it obvious where banners
2757         were busted.
2758        
2759       + "blank" to send a built-in transparent image. This makes banners
2760         disappear completely, but makes it hard to detect where Privoxy has
2761         blocked images on a given page and complicates troubleshooting if
2762         Privoxy has blocked innocent images, like navigation icons.
2763        
2764       + "target-url" to send a redirect to target-url. You can redirect to any
2765         image anywhere, even in your local filesystem (via "file:///" URL).
2766        
2767         A good application of redirects is to use special Privoxy-built-in
2768         URLs, which send the built-in images, as target-url. This has the same
2769         visual effect as specifying "blank" or "pattern" in the first place,
2770         but enables your browser to cache the replacement image, instead of
2771         requesting it over and over again.
2772        
2773 Notes:
2774    
2775     The URLs for the built-in images are "http://config.privoxy.org/
2776     send-banner?type=type", where type is either "blank" or "pattern".
2777    
2778     There is a third (advanced) type, called "auto". It is NOT to be used in
2779     set-image-blocker, but meant for use from filters. Auto will select the
2780     type of image that would have applied to the referring page, had it been an
2781     image.
2782    
2783 Example usage:
2784    
2785     Built-in pattern:
2786    
2787     +set-image-blocker{pattern}                                        
2788    
2789     Redirect to the BSD devil:
2790    
2791     +set-image-blocker{http://www.freebsd.org/gifs/dae_up3.gif}        
2792    
2793     Redirect to the built-in pattern for better caching:
2794    
2795     +set-image-blocker{http://config.privoxy.org/send-banner?type=pattern}
2796    
2797 -------------------------------------------------------------------------------
2798
2799 8.5.21. Summary
2800
2801 Note that many of these actions have the potential to cause a page to
2802 misbehave, possibly even not to display at all. There are many ways a site
2803 designer may choose to design his site, and what HTTP header content, and other
2804 criteria, he may depend on. There is no way to have hard and fast rules for all
2805 sites. See the Appendix for a brief example on troubleshooting actions.
2806
2807 -------------------------------------------------------------------------------
2808
2809 8.6. Aliases
2810
2811 Custom "actions", known to Privoxy as "aliases", can be defined by combining
2812 other actions. These can in turn be invoked just like the built-in actions.
2813 Currently, an alias name can contain any character except space, tab, "=", "{"
2814 and "}", but we strongly recommend that you only use "a" to "z", "0" to "9",
2815 "+", and "-". Alias names are not case sensitive, and are not required to start
2816 with a "+" or "-" sign, since they are merely textually expanded.
2817
2818 Aliases can be used throughout the actions file, but they must be defined in a
2819 special section at the top of the file! And there can only be one such section
2820 per actions file. Each actions file may have its own alias section, and the
2821 aliases defined in it are only visible within that file.
2822
2823 There are two main reasons to use aliases: One is to save typing for frequently
2824 used combinations of actions, the other one is a gain in flexibility: If you
2825 decide once how you want to handle shops by defining an alias called "shop",
2826 you can later change your policy on shops in one place, and your changes will
2827 take effect everywhere in the actions file where the "shop" alias is used.
2828 Calling aliases by their purpose also makes your actions files more readable.
2829
2830 Currently, there is one big drawback to using aliases, though: Privoxy's
2831 built-in web-based action file editor honors aliases when reading the actions
2832 files, but it expands them before writing. So the effects of your aliases are
2833 of course preserved, but the aliases themselves are lost when you edit sections
2834 that use aliases with it. This is likely to change in future versions of
2835 Privoxy.
2836
2837 Now let's define some aliases...
2838
2839  # Useful custom aliases we can use later.                                                   
2840  #                                                                                           
2841  # Note the (required!) section header line and that this section                            
2842  # must be at the top of the actions file!                                                   
2843  #                                                                                           
2844  {{alias}}                                                                                   
2845                                                                                              
2846  # These aliases just save typing later:                                                     
2847  #                                                                                           
2848  +crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies                     
2849  -crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies                     
2850  +imageblock = +block +handle-as-image                                                       
2851                                                                                              
2852  # These aliases define combinations of actions                                              
2853  # that are useful for certain types of sites:                                               
2854  #                                                                                           
2855  fragile     = -block -crunch-all-cookies -filter -fast-redirects -hide-referer -kill-popups 
2856  shop        = -crunch-all-cookies -fast-redirects                                           
2857                                                                                              
2858  # Aliases defined from other aliases, for really lazy people ;-)                            
2859  #                                                                                           
2860  c0 = +crunch-all-cookies                                                                    
2861  c1 = -crunch-all-cookies                                                                    
2862
2863 ...and put them to use. These sections would appear in the lower part of an
2864 actions file and define exceptions to the default actions (as specified further
2865 up for the "/" pattern):
2866
2867  # These sites are either very complex or very keen on                         
2868  # user data and require minimal interference to work:                         
2869  #                                                                             
2870  {fragile}                                                                     
2871  .office.microsoft.com                                                         
2872  .windowsupdate.microsoft.com                                                  
2873  .nytimes.com                                                                  
2874                                                                                
2875  # Shopping sites:                                                             
2876  # Allow cookies (for setting and retrieving your customer data)               
2877  #                                                                             
2878  {shop}                                                                        
2879  .quietpc.com                                                                  
2880  .worldpay.com   # for quietpc.com                                             
2881  .scan.co.uk                                                                   
2882                                                                                
2883  # These shops require pop-ups:                                                
2884  #                                                                             
2885  {shop -kill-popups -filter{popups}}                                           
2886   .dabs.com                                                                    
2887   .overclockers.co.uk                                                          
2888
2889 Aliases like "shop" and "fragile" are often used for "problem" sites that
2890 require some actions to be disabled in order to function properly.
2891
2892 -------------------------------------------------------------------------------
2893
2894 8.7. Sample Actions Files
2895
2896 Remember that the meaning of each action is reversed by preceding the action
2897 with a "-", in place of the "+". Also, that some actions are turned on in the
2898 default section of the actions file, and require little to no additional
2899 configuration. These are just "on".
2900
2901 But, other actions that are turned on in the default section do typically
2902 require exceptions to be listed in the latter sections of one of our actions
2903 file. For instance, by default no URLs are "blocked" (i.e. in the default
2904 definitions of default.action). We need exceptions to this in order to enable
2905 ad blocking in the lower sections. But we need to be very selective about what
2906 we do block. Thus, the default is "off" for blocking.
2907
2908 Below is a liberally commented sample default.action file to demonstrate how
2909 all the pieces come together. And to show how exceptions to the default
2910 policies can be handled. This is followed by a brief user.action with similar
2911 examples.
2912
2913 # Sample default.action file <developers@privoxy.org>
2914
2915 # Settings -- Don't change! For internal Privoxy use ONLY.
2916 {{settings}}
2917 for-privoxy-version=3.0
2918
2919
2920 ##########################################################################
2921 # Aliases must be defined *before* they are used. These are
2922 # easier to remember, and can combine several actions into one. Once 
2923 # defined they can be used just like any built-in action -- but within 
2924 # this file only! Aliases do not require a + or - sign.
2925 ##########################################################################
2926 {{alias}}
2927
2928 # Some useful aliases.
2929 # Alias to turn off cookie handling, ie allow all cookies unmolested.
2930 #
2931 mercy-for-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies \
2932                     -session-cookies-only
2933
2934 # Alias to both block and treat as if an image for ad blocking
2935 # purposes.
2936 #
2937 +block-as-image   = +block +handle-as-image
2938
2939 # Shops should be allowed to set persistent cookies
2940 #
2941 shop        = -filter mercy-for-cookies
2942
2943 # Fragile sites should receive minimum interference:
2944 #
2945 fragile     = -block -deanimate-gifs -fast-redirects -filter -hide-referer \
2946               mercy-for-cookies -kill-popups
2947
2948 ##########################################################################
2949 # Matching starts here. Remember that at this time, all actions are
2950 # disabled, so we need to explicitly enable the ones we want. 
2951 #
2952 # We begin with "default" action settings, i.e. we define a set of actions
2953 # for a pattern ("/") that matches all URLs. This default set will be
2954 # applied to all requests as a start, and can be partly or wholly overridden
2955 # by later matches further down this file, or in user.action.
2956 #
2957 # We will show all potential actions here whether they are enabled
2958 # or not. We could omit any disabled action if we wanted, since all 
2959 # actions are 'off' by default anyway. Shown for completeness only.
2960 # Actions are enabled if preceded by a '+', otherwise they are disabled 
2961 # (unless an alias has been defined without this).
2962 ##########################################################################
2963  { \
2964  -add-header \
2965  -block \
2966  -deanimate-gifs \
2967  -downgrade-http-version \
2968  +fast-redirects \
2969  +filter{html-annoyances} \
2970  +filter{js-annoyances} \
2971  -filter{content-cookies} \
2972  -filter{popups} \
2973  +filter{webbugs} \
2974  -filter{refresh-tags} \
2975  -filter{fun} \
2976  +filter{nimda} \
2977  +filter{banners-by-size} \
2978  -filter{shockwave-flash} \
2979  -filter{crude-parental} \
2980  +hide-forwarded-for-headers \
2981  +hide-from-header{block} \
2982  -hide-referrer \
2983  -hide-user-agent \
2984  -handle-as-image \
2985  +set-image-blocker{pattern} \
2986  -limit-connect \
2987  +prevent-compression \
2988  -session-cookies-only \
2989  -crunch-outgoing-cookies \
2990  -crunch-incoming-cookies \
2991  -kill-popups \
2992  -send-vanilla-wafer \
2993  -send-wafer \
2994  }
2995  / # forward slash will match *all* potential URL patterns. 
2996
2997 ##########################################################################
2998 # Default behavior is now set. Now we will define some exceptions to our 
2999 # default action policies.
3000 ##########################################################################
3001
3002 # These sites are very complex and require very minimal interference.
3003 # We'll disable most actions with our 'fragile' alias:
3004  { fragile }
3005  .office.microsoft.com           # surprise, surprise!
3006  .windowsupdate.microsoft.com
3007
3008
3009 # Shopping sites - not as fragile but require some special 
3010 # handling. We still want to block ads, and we will allow 
3011 # persistent cookies via the 'shop' alias:
3012  { shop }
3013  .quietpc.com 
3014  .worldpay.com   # for quietpc.com
3015  .jungle.com
3016  .scan.co.uk
3017
3018
3019 # These sites require pop-ups too :(  We'll combine our 'shop' 
3020 # alias with two other actions into one rule to allow all popups.
3021  { shop -kill-popups -filter{popups} }
3022  .dabs.com
3023  .overclockers.co.uk
3024
3025
3026 # The 'Fast-redirects' action breaks some sites. Disable this action
3027 # for these known sensitive sites:
3028  { -fast-redirects }
3029  login.yahoo.com
3030  edit.europe.yahoo.com
3031  .google.com
3032  .altavista.com/.*(like|url|link):http
3033  .altavista.com/trans.*urltext=http
3034  .nytimes.com
3035
3036
3037 # Define which file types will be treated as images. Important
3038 # for ad blocking.
3039  { +handle-as-image }
3040  /.*\.(gif|jpe?g|png|bmp|ico)
3041
3042
3043 # Now lets list some domains that are known ad generators. And
3044 # our alias that we use here will block these as well as force 
3045 # them to be treated as images. This combination of actions is 
3046 # important for ad blocking. What the browser will show instead is 
3047 # determined by the setting of "+set-image-blocker"
3048  { +imageblock }
3049  ar.atwola.com 
3050  .ad.doubleclick.net
3051  .a.yimg.com/(?:(?!/i/).)*$
3052  .a[0-9].yimg.com/(?:(?!/i/).)*$
3053  bs*.gsanet.com
3054  bs*.einets.com
3055  .qkimg.net
3056  ad.*.doubleclick.net
3057
3058
3059 # These will just simply be blocked. They will generate the BLOCKED
3060 # banner page, if matched. Heavy use of wildcards and regular 
3061 # expressions in this example. Enable block action:
3062  { +block }
3063  ad*.
3064  .*ads.
3065  banner?.
3066  count*.
3067  /.*count(er)?\.(pl|cgi|exe|dll|asp|php[34]?)
3068  /(?:.*/)?(publicite|werbung|rekla(ma|me|am)|annonse|maino(kset|nta|s)?)/
3069  .hitbox.com 
3070
3071
3072 # The above block section will probably inadvertently catch some 
3073 # sites we DO NOT want blocked via the wildcards and regular expressions. 
3074 # Now let's set exceptions to the exceptions so the good guys get better 
3075 # treatment. Disable block action:
3076  { -block }
3077  advogato.org
3078  adsl.
3079  ad[ud]*.
3080  advice.
3081 # Let's just trust all .edu top level domains.
3082  .edu
3083  www.ugu.com/sui/ugu/adv
3084 # We'll need to access to path names containing 'download' 
3085  .*downloads.
3086  /downloads/
3087 # 'adv' is for globalintersec and means advanced, not advertisement
3088  www.globalintersec.com/adv
3089
3090
3091 # Don't filter *anything* from our friends at sourceforge.
3092 # Notice we don't have to name the individual filter 
3093 # identifiers -- we just turn them all off in one fell swoop.
3094 # Disable all filters for this one site:
3095  { -filter }
3096  .sourceforge.net
3097    
3098
3099 So far we are painting with a broad brush by setting general policies. The
3100 above would be a reasonable starting point for many situations. Now, we want to
3101 be more specific and have customized rules that are more suitable to our
3102 personal habits and preferences. These would be for narrowly defined situations
3103 like your ISP or your bank, and should be placed in user.action, which is
3104 parsed after all other actions files and should not be clobbered by upgrades.
3105 So any settings here, will have the last word and over-ride any previously
3106 defined actions.
3107
3108 Now a few examples of some things that one might do with a user.action file.
3109
3110 # Sample user.action file.
3111
3112 # Any aliases you want to use need to be re-defined here.
3113 # Alias to turn off cookie handling, ie allow all cookies unmolested.
3114  -crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies \
3115                        -session-cookies-only
3116
3117 # Fragile sites should have the minimum changes:
3118  fragile     = -block -deanimate-gifs -fast-redirects -filter -hide-referer \
3119                -crunch-all-cookies -kill-popups
3120
3121 # Allow persistent cookies for a few regular sites that we 
3122 # trust via our above alias. These will be saved from one browser session 
3123 # to the next. We are explicitly turning off any and all cookie handling, 
3124 # even though the crunch-*-cookies settings were disabled in our above 
3125 # default.action anyway. So cookies from these domains will come through 
3126 # unmolested.
3127  { -crunch-all-cookies }
3128  .sun.com
3129  .yahoo.com
3130  .msdn.microsoft.com
3131  .redhat.com
3132
3133
3134 # My ISP uses obnoxious self promoting images on many pages.
3135 # Nuke them :) Note that "+handle-as-image" need not be specified,
3136 # since all URLs ending in .gif will be tagged as images by the
3137 # general rules in default.action anyway.
3138  { +block }
3139  www.my-isp-example.com/logo[0-9].gif
3140
3141
3142 # Say the site where you do your home banking needs to open
3143 # popup windows, but you have chosen to kill popups by
3144 # default. This will allow it for your-example-bank.com:
3145 #
3146  { -filter{popups} -kill-popups }
3147  .my-example-bank.com
3148
3149
3150 # This site is delicate, and requires kid-glove 
3151 # treatment.
3152  { fragile }
3153  .forbes.com
3154    
3155
3156 -------------------------------------------------------------------------------
3157
3158 9. The Filter File
3159
3160 Any web page can be dynamically modified with the filter file. This
3161 modification can be removal, or re-writing, of any web page content, including
3162 tags and non-visible content. The default filter file is oddly enough
3163 default.filter, located in the config directory.
3164
3165 This is potentially a very powerful feature, and requires knowledge of both
3166 "regular expression" and HTML in order create custom filters. But, there are a
3167 number of useful filters included with Privoxy for many common situations.
3168
3169 The included example file is divided into sections. Each section begins with
3170 the FILTER keyword, followed by the identifier for that section, e.g. "FILTER:
3171 webbugs". Each section performs a similar type of filtering, such as
3172 "html-annoyances".
3173
3174 This file uses regular expressions to alter or remove any string in the target
3175 page. The expressions can only operate on one line at a time. Some examples
3176 from the included default default.filter:
3177
3178 Stop web pages from displaying annoying messages in the status bar by deleting
3179 such references:
3180
3181  FILTER: html-annoyances
3182
3183  # New browser windows should be resizeable and have a location and status
3184  # bar. Make it so.
3185  #
3186  s/resizable="?(no|0)"?/resizable=1/ig s/noresize/yesresize/ig
3187  s/location="?(no|0)"?/location=1/ig s/status="?(no|0)"?/status=1/ig
3188  s/scrolling="?(no|0|Auto)"?/scrolling=1/ig
3189  s/menubar="?(no|0)"?/menubar=1/ig 
3190
3191  # The <BLINK> tag was a crime!
3192  #
3193  s*<blink>|</blink>**ig
3194
3195  # Is this evil? 
3196  #
3197  #s/framespacing="?(no|0)"?//ig
3198  #s/margin(height|width)=[0-9]*//gi
3199    
3200
3201 Just for kicks, replace any occurrence of "Microsoft" with "MicroSuck", and
3202 have a little fun with topical buzzwords:
3203
3204  FILTER: fun
3205
3206  s/microsoft(?!.com)/MicroSuck/ig
3207
3208  # Buzzword Bingo:
3209  #
3210  s/industry-leading|cutting-edge|award-winning/<font color=red><b>BINGO!</b></
3211 font>/ig
3212    
3213
3214 Kill those pesky little web-bugs:
3215
3216  # webbugs: Squish WebBugs (1x1 invisible GIFs used for user tracking)
3217  FILTER: webbugs
3218
3219  s/<img\s+[^>]*?(width|height)\s*=\s*['"]?1\D[^>]*?(width|height)\s*=\s*['"]?1
3220 (\D[^>]*?)?>/<!-- Squished WebBug -->/sig
3221    
3222
3223 -------------------------------------------------------------------------------
3224
3225 9.1. The +filter Action
3226
3227 Filters are enabled with the "+filter" action from within one of the actions
3228 files. "+filter" requires one parameter, which should match one of the section
3229 identifiers in the filter file itself. Example:
3230
3231   +filter{html-annoyances}                                                     
3232
3233 This would activate that particular filter. Similarly, "+filter" can be turned
3234 off for selected sites as: "-filter{html-annoyances}". Remember too, all
3235 actions are off by default, unless they are explicitly enabled in one of the
3236 actions files.
3237
3238 -------------------------------------------------------------------------------
3239
3240 10. Templates
3241
3242 When Privoxy displays one of its internal pages, such as a 404 Not Found error
3243 page (Privoxy must be running for link to work as intended), it uses the
3244 appropriate template. On Linux, BSD, and Unix, these are located in /etc/
3245 privoxy/templates by default. These may be customized, if desired.
3246 cgi-style.css is used to control the HTML attributes (fonts, etc).
3247
3248 The default Blocked (Privoxy needs to be running for page to display) banner
3249 page with the bright red top banner, is called just "blocked". This may be
3250 customized or replaced with something else if desired (not recommended for the
3251 casual user).
3252
3253 -------------------------------------------------------------------------------
3254
3255 11. Contacting the Developers, Bug Reporting and Feature Requests
3256
3257 We value your feedback. However, to provide you with the best support, please
3258 note the following sections.
3259
3260 -------------------------------------------------------------------------------
3261
3262 11.1. Get Support
3263
3264 To get support, use the Sourceforge Support Forum:
3265
3266     http://sourceforge.net/tracker/?group_id=11118&atid=211118
3267
3268 -------------------------------------------------------------------------------
3269
3270 11.2. Report bugs
3271
3272 To submit bugs, use the Sourceforge Bug Forum:
3273
3274     http://sourceforge.net/tracker/?group_id=11118&atid=111118. 
3275
3276 Make sure that the bug has not already been submitted. Please try to verify
3277 that it is a Privoxy bug, and not a browser or site bug first. If you are using
3278 your own custom configuration, please try the stock configs to see if the
3279 problem is a configuration related bug. And if not using the latest development
3280 snapshot, please try the latest one. Or even better, CVS sources. Please be
3281 sure to include the Privoxy version, platform, browser, any pertinent log data,
3282 any other relevant details (please be specific) and, if possible, some way to
3283 reproduce the bug.
3284
3285 -------------------------------------------------------------------------------
3286
3287 11.3. Request new features
3288
3289 To submit ideas on new features, use the Sourceforge feature request forum:
3290
3291     http://sourceforge.net/tracker/?atid=361118&group_id=11118&func=browse.
3292
3293 -------------------------------------------------------------------------------
3294
3295 11.4. Report ads or other filter problems
3296
3297 You can also send feedback on websites that Privoxy has problems with. Please
3298 bookmark the following link: "Privoxy - Submit Filter Feedback". Once you surf
3299 to a page with problems, use the bookmark to send us feedback. We will look
3300 into the issue as soon as possible.
3301
3302 New, improved default.action files will occasionally be made available based on
3303 your feedback. These will be announced on the ijbswa-announce list.
3304
3305 -------------------------------------------------------------------------------
3306
3307 11.5. Other
3308
3309 For any other issues, feel free to use the mailing lists:
3310  
3311     http://sourceforge.net/mail/?group_id=11118.
3312
3313 Anyone interested in actively participating in development and related
3314 discussions can also join the appropriate mailing list. Archives are available,
3315 too. See the page on Sourceforge.
3316
3317 -------------------------------------------------------------------------------
3318
3319 12. Privoxy Copyright, License and History
3320
3321 Copyright © 2001, 2002 by Privoxy Developers <developers@privoxy.org>
3322
3323 Some source code is based on code Copyright © 1997 by Anonymous Coders and
3324 Junkbusters, Inc. and licensed under the GNU General Public License.
3325
3326 -------------------------------------------------------------------------------
3327
3328 12.1. License
3329
3330 Privoxy is free software; you can redistribute it and/or modify it under the
3331 terms of the GNU General Public License, version 2, as published by the Free
3332 Software Foundation.
3333
3334 This program is distributed in the hope that it will be useful, but WITHOUT ANY
3335 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
3336 PARTICULAR PURPOSE. See the GNU General Public License for more details, which
3337 is available from the Free Software Foundation, Inc, 59 Temple Place - Suite
3338 330, Boston, MA 02111-1307, USA.
3339
3340 You should have received a copy of the GNU General Public License along with
3341 this program; if not, write to the
3342
3343  Free Software
3344  Foundation, Inc. 59 Temple Place - Suite 330
3345  Boston, MA 02111-1307
3346  USA 
3347
3348 -------------------------------------------------------------------------------
3349
3350 12.2. History
3351
3352 Privoxy is evolved, and derived from, the Internet Junkbuster, with many
3353 improvements and enhancements over the original.
3354
3355 Junkbuster was originally written by Anonymous Coders and Junkbusters
3356 Corporation, and was released as free open-source software under the GNU GPL. 
3357 Stefan Waldherr made many improvements, and started the SourceForge project
3358 Privoxy to rekindle development. There are now several active developers
3359 contributing. The last stable release of Junkbuster was v2.0.2, which has now
3360 grown whiskers ;-).
3361
3362 -------------------------------------------------------------------------------
3363
3364 13. See Also
3365
3366 Other references and sites of interest to Privoxy users:
3367
3368 http://www.privoxy.org/, The Privoxy Home page.
3369
3370 http://sourceforge.net/projects/ijbswa, the Project Page for Privoxy on        
3371 Sourceforge.                                                                   
3372
3373 http://p.p/, access Privoxy from your browser. Alternately, http://            
3374 config.privoxy.org may work in some situations where the first does not.       
3375
3376 http://p.p/, and select "Privoxy - Submit Filter Feedback" to submit "misses"  
3377 to the developers.                                                             
3378
3379 http://www.junkbusters.com/ht/en/cookies.html
3380
3381 http://www.waldherr.org/junkbuster/
3382
3383 http://privacy.net/analyze/
3384
3385 http://www.squid-cache.org/
3386
3387  
3388
3389 -------------------------------------------------------------------------------
3390
3391 14. Appendix
3392
3393 14.1. Regular Expressions
3394
3395 Privoxy can use "regular expressions" in various config files. Assuming support
3396 for "pcre" (Perl Compatible Regular Expressions) is compiled in, which is the
3397 default. Such configuration directives do not require regular expressions, but
3398 they can be used to increase flexibility by matching a pattern with wild-cards
3399 against URLs.
3400
3401 If you are reading this, you probably don't understand what "regular
3402 expressions" are, or what they can do. So this will be a very brief
3403 introduction only. A full explanation would require a book ;-)
3404
3405 "Regular expressions" is a way of matching one character expression against
3406 another to see if it matches or not. One of the "expressions" is a literal
3407 string of readable characters (letter, numbers, etc), and the other is a
3408 complex string of literal characters combined with wild-cards, and other
3409 special characters, called meta-characters. The "meta-characters" have special
3410 meanings and are used to build the complex pattern to be matched against. Perl
3411 Compatible Regular Expressions is an enhanced form of the regular expression
3412 language with backward compatibility.
3413
3414 To make a simple analogy, we do something similar when we use wild-card
3415 characters when listing files with the dir command in DOS. *.* matches all
3416 filenames. The "special" character here is the asterisk which matches any and
3417 all characters. We can be more specific and use ? to match just individual
3418 characters. So "dir file?.text" would match "file1.txt", "file2.txt", etc. We
3419 are pattern matching, using a similar technique to "regular expressions"!
3420
3421 Regular expressions do essentially the same thing, but are much, much more
3422 powerful. There are many more "special characters" and ways of building complex
3423 patterns however. Let's look at a few of the common ones, and then some
3424 examples:
3425
3426 . - Matches any single character, e.g. "a", "A", "4", ":", or "@".
3427
3428 ? - The preceding character or expression is matched ZERO or ONE times. Either/
3429 or.                                                                            
3430
3431 + - The preceding character or expression is matched ONE or MORE times.
3432
3433 * - The preceding character or expression is matched ZERO or MORE times.
3434
3435 \ - The "escape" character denotes that the following character should be taken
3436 literally. This is used where one of the special characters (e.g. ".") needs to
3437 be taken literally and not as a special meta-character. Example: "example      
3438 \.com", makes sure the period is recognized only as a period (and not expanded 
3439 to its meta-character meaning of any single character).                        
3440
3441 [] - Characters enclosed in brackets will be matched if any of the enclosed    
3442 characters are encountered. For instance, "[0-9]" matches any numeric digit    
3443 (zero through nine). As an example, we can combine this with "+" to match any  
3444 digit one of more times: "[0-9]+".                                             
3445
3446 () - parentheses are used to group a sub-expression, or multiple               
3447 sub-expressions.                                                               
3448
3449 | - The "bar" character works like an "or" conditional statement. A match is   
3450 successful if the sub-expression on either side of "|" matches. As an example: 
3451 "/(this|that) example/" uses grouping and the bar character and would match    
3452 either "this example" or "that example", and nothing else.                     
3453
3454 s/string1/string2/g - This is used to rewrite strings of text. "string1" is    
3455 replaced by "string2" in this example. There must of course be a match on      
3456 "string1" first.                                                               
3457
3458 These are just some of the ones you are likely to use when matching URLs with
3459 Privoxy, and is a long way from a definitive list. This is enough to get us
3460 started with a few simple examples which may be more illuminating:
3461
3462 /.*/banners/.* - A simple example that uses the common combination of "." and "
3463 *" to denote any character, zero or more times. In other words, any string at
3464 all. So we start with a literal forward slash, then our regular expression
3465 pattern (".*") another literal forward slash, the string "banners", another
3466 forward slash, and lastly another ".*". We are building a directory path here.
3467 This will match any file with the path that has a directory named "banners" in
3468 it. The ".*" matches any characters, and this could conceivably be more forward
3469 slashes, so it might expand into a much longer looking path. For example, this
3470 could match: "/eye/hate/spammers/banners/annoy_me_please.gif", or just "/
3471 banners/annoying.html", or almost an infinite number of other possible
3472 combinations, just so it has "banners" in the path somewhere.
3473
3474 A now something a little more complex:
3475
3476 /.*/adv((er)?ts?|ertis(ing|ements?))?/ - We have several literal forward
3477 slashes again ("/"), so we are building another expression that is a file path
3478 statement. We have another ".*", so we are matching against any conceivable
3479 sub-path, just so it matches our expression. The only true literal that must
3480 match our pattern is adv, together with the forward slashes. What comes after
3481 the "adv" string is the interesting part.
3482
3483 Remember the "?" means the preceding expression (either a literal character or
3484 anything grouped with "(...)" in this case) can exist or not, since this means
3485 either zero or one match. So "((er)?ts?|ertis(ing|ements?))" is optional, as
3486 are the individual sub-expressions: "(er)", "(ing|ements?)", and the "s". The "
3487 |" means "or". We have two of those. For instance, "(ing|ements?)", can expand
3488 to match either "ing" OR "ements?". What is being done here, is an attempt at
3489 matching as many variations of "advertisement", and similar, as possible. So
3490 this would expand to match just "adv", or "advert", or "adverts", or
3491 "advertising", or "advertisement", or "advertisements". You get the idea. But
3492 it would not match "advertizements" (with a "z"). We could fix that by changing
3493 our regular expression to: "/.*/adv((er)?ts?|erti(s|z)(ing|ements?))?/", which
3494 would then match either spelling.
3495
3496 /.*/advert[0-9]+\.(gif|jpe?g) - Again another path statement with forward
3497 slashes. Anything in the square brackets "[]" can be matched. This is using
3498 "0-9" as a shorthand expression to mean any digit one through nine. It is the
3499 same as saying "0123456789". So any digit matches. The "+" means one or more of
3500 the preceding expression must be included. The preceding expression here is
3501 what is in the square brackets -- in this case, any digit one through nine.
3502 Then, at the end, we have a grouping: "(gif|jpe?g)". This includes a "|", so
3503 this needs to match the expression on either side of that bar character also. A
3504 simple "gif" on one side, and the other side will in turn match either "jpeg"
3505 or "jpg", since the "?" means the letter "e" is optional and can be matched
3506 once or not at all. So we are building an expression here to match image GIF or
3507 JPEG type image file. It must include the literal string "advert", then one or
3508 more digits, and a "." (which is now a literal, and not a special character,
3509 since it is escaped with "\"), and lastly either "gif", or "jpeg", or "jpg".
3510 Some possible matches would include: "//advert1.jpg", "/nasty/ads/
3511 advert1234.gif", "/banners/from/hell/advert99.jpg". It would not match
3512 "advert1.gif" (no leading slash), or "/adverts232.jpg" (the expression does not
3513 include an "s"), or "/advert1.jsp" ("jsp" is not in the expression anywhere).
3514
3515 s/microsoft(?!.com)/MicroSuck/i - This is a substitution. "MicroSuck" will
3516 replace any occurrence of "microsoft". The "i" at the end of the expression
3517 means ignore case. The "(?!.com)" means the match should fail if "microsoft" is
3518 followed by ".com". In other words, this acts like a "NOT" modifier. In case
3519 this is a hyperlink, we don't want to break it ;-).
3520
3521 We are barely scratching the surface of regular expressions here so that you
3522 can understand the default Privoxy configuration files, and maybe use this
3523 knowledge to customize your own installation. There is much, much more that can
3524 be done with regular expressions. Now that you know enough to get started, you
3525 can learn more on your own :/
3526
3527 More reading on Perl Compatible Regular expressions: http://www.perldoc.com/
3528 perl5.6/pod/perlre.html
3529
3530 -------------------------------------------------------------------------------
3531
3532 14.2. Privoxy's Internal Pages
3533
3534 Since Privoxy proxies each requested web page, it is easy for Privoxy to trap
3535 certain special URLs. In this way, we can talk directly to Privoxy, and see how
3536 it is configured, see how our rules are being applied, change these rules and
3537 other configuration options, and even turn Privoxy's filtering off, all with a
3538 web browser. 
3539
3540 The URLs listed below are the special ones that allow direct access to Privoxy.
3541 Of course, Privoxy must be running to access these. If not, you will get a
3542 friendly error message. Internet access is not necessary either.
3543
3544   * Privoxy main page:
3545    
3546         http://config.privoxy.org/
3547        
3548     Alternately, this may be reached at http://p.p/, but this variation may not
3549     work as reliably as the above in some configurations.
3550    
3551   * Show information about the current configuration, including viewing and
3552     editing of actions files:
3553    
3554         http://config.privoxy.org/show-status
3555        
3556   * Show the source code version numbers:
3557    
3558         http://config.privoxy.org/show-version
3559        
3560   * Show the browser's request headers:
3561    
3562         http://config.privoxy.org/show-request
3563        
3564   * Show which actions apply to a URL and why:
3565    
3566         http://config.privoxy.org/show-url-info
3567        
3568   * Toggle Privoxy on or off. In this case, "Privoxy" continues to run, but
3569     only as a pass-through proxy, with no actions taking place:
3570    
3571         http://config.privoxy.org/toggle
3572        
3573     Short cuts. Turn off, then on:
3574    
3575         http://config.privoxy.org/toggle?set=disable
3576        
3577         http://config.privoxy.org/toggle?set=enable
3578        
3579 These may be bookmarked for quick reference. See next. 
3580
3581 -------------------------------------------------------------------------------
3582
3583 14.2.1. Bookmarklets
3584
3585 Below are some "bookmarklets" to allow you to easily access a "mini" version of
3586 some of Privoxy's special pages. They are designed for MS Internet Explorer,
3587 but should work equally well in Netscape, Mozilla, and other browsers which
3588 support JavaScript. They are designed to run directly from your bookmarks - not
3589 by clicking the links below (although that should work for testing).
3590
3591 To save them, right-click the link and choose "Add to Favorites" (IE) or "Add
3592 Bookmark" (Netscape). You will get a warning that the bookmark "may not be
3593 safe" - just click OK. Then you can run the Bookmarklet directly from your
3594 favorites/bookmarks. For even faster access, you can put them on the "Links"
3595 bar (IE) or the "Personal Toolbar" (Netscape), and run them with a single
3596 click.
3597
3598   * Privoxy - Enable
3599    
3600   * Privoxy - Disable
3601    
3602   * Privoxy - Toggle Privoxy (Toggles between enabled and disabled)
3603    
3604   * Privoxy- View Status
3605    
3606   * Privoxy - Submit Filter Feedback
3607    
3608 Credit: The site which gave me the general idea for these bookmarklets is 
3609 www.bookmarklets.com. They have more information about bookmarklets.
3610
3611 -------------------------------------------------------------------------------
3612
3613 14.3. Chain of Events
3614
3615 Let's take a quick look at the basic sequence of events when a web page is
3616 requested by your browser and Privoxy is on duty:
3617
3618   * First, your web browser requests a web page. The browser knows to send the
3619     request to Privoxy, which will in turn, relay the request to the remote web
3620     server after passing the following tests:
3621    
3622   * Privoxy traps any request for its own internal CGI pages (e.g http://p.p/)
3623     and sends the CGI page back to the browser.
3624    
3625   * Next, Privoxy checks to see if the URL matches any "+block" patterns. If
3626     so, the URL is then blocked, and the remote web server will not be
3627     contacted. "+handle-as-image" is then checked and if it does not match, an
3628     HTML "BLOCKED" page is sent back. Otherwise, if it does match, an image is
3629     returned. The type of image depends on the setting of "+set-image-blocker"
3630     (blank, checkerboard pattern, or an HTTP redirect to an image elsewhere).
3631    
3632   * Untrusted URLs are blocked. If URLs are being added to the trust file, then
3633     that is done.
3634    
3635   * If the URL pattern matches the "+fast-redirects" action, it is then
3636     processed. Unwanted parts of the requested URL are stripped.
3637    
3638   * Now the rest of the client browser's request headers are processed. If any
3639     of these match any of the relevant actions (e.g. "+hide-user-agent", etc.),
3640     headers are suppressed or forged as determined by these actions and their
3641     parameters.
3642    
3643   * Now the web server starts sending its response back (i.e. typically a web
3644     page and related data).
3645    
3646   * First, the server headers are read and processed to determine, among other
3647     things, the MIME type (document type) and encoding. The headers are then
3648     filtered as determined by the "+crunch-incoming-cookies", 
3649     "+session-cookies-only", and "+downgrade-http-version" actions.
3650    
3651   * If the "+kill-popups" action applies, and it is an HTML or JavaScript
3652     document, the popup-code in the response is filtered on-the-fly as it is
3653     received.
3654    
3655   * If a "+filter" or "+deanimate-gifs" action applies (and the document type
3656     fits the action), the rest of the page is read into memory (up to a
3657     configurable limit). Then the filter rules (from default.filter) are
3658     processed against the buffered content. Filters are applied in the order
3659     they are specified in the default.filter file. Animated GIFs, if present,
3660     are reduced to either the first or last frame, depending on the action
3661     setting.The entire page, which is now filtered, is then sent by Privoxy
3662     back to your browser.
3663    
3664     If neither "+filter" or "+deanimate-gifs" matches, then Privoxy passes the
3665     raw data through to the client browser as it becomes available.
3666    
3667   * As the browser receives the now (probably filtered) page content, it reads
3668     and then requests any URLs that may be embedded within the page source,
3669     e.g. ad images, stylesheets, JavaScript, other HTML documents (e.g.
3670     frames), sounds, etc. For each of these objects, the browser issues a new
3671     request. And each such request is in turn processed as above. Note that a
3672     complex web page may have many such embedded URLs.
3673    
3674 -------------------------------------------------------------------------------
3675
3676 14.4. Anatomy of an Action
3677
3678 The way Privoxy applies "actions" and "filters" to any given URL can be
3679 complex, and not always so easy to understand what is happening. And sometimes
3680 we need to be able to see just what Privoxy is doing. Especially, if something
3681 Privoxy is doing is causing us a problem inadvertently. It can be a little
3682 daunting to look at the actions and filters files themselves, since they tend
3683 to be filled with "regular expressions" whose consequences are not always so
3684 obvious.
3685
3686 One quick test to see if Privoxy is causing a problem or not, is to disable it
3687 temporarily. This should be the first troubleshooting step. See the
3688 Bookmarklets section on a quick and easy way to do this (be sure to flush
3689 caches afterward!).
3690
3691 Privoxy also provides the http://config.privoxy.org/show-url-info page that can
3692 show us very specifically how actions are being applied to any given URL. This
3693 is a big help for troubleshooting.
3694
3695 First, enter one URL (or partial URL) at the prompt, and then Privoxy will tell
3696 us how the current configuration will handle it. This will not help with
3697 filtering effects (i.e. the "+filter" action) from the default.filter file
3698 since this is handled very differently and not so easy to trap! It also will
3699 not tell you about any other URLs that may be embedded within the URL you are
3700 testing. For instance, images such as ads are expressed as URLs within the raw
3701 page source of HTML pages. So you will only get info for the actual URL that is
3702 pasted into the prompt area -- not any sub-URLs. If you want to know about
3703 embedded URLs like ads, you will have to dig those out of the HTML source. Use
3704 your browser's "View Page Source" option for this. Or right click on the ad,
3705 and grab the URL.
3706
3707 Let's try an example, google.com, and look at it one section at a time:
3708
3709  Matches for http://google.com:                                                     
3710                                                                                     
3711 --- File standard ---                                                               
3712 (no matches in this file)                                                           
3713                                                                                     
3714 --- File default ---                                                                
3715                                                                                     
3716 { -add-header -block +deanimate-gifs{last} -downgrade-http-version +fast-redirects  
3717  -filter{popups} -filter{fun} -filter{shockwave-flash} -filter{crude-parental}      
3718  +filter{html-annoyances} +filter{js-annoyances} +filter{content-cookies}           
3719  +filter{webbugs} +filter{refresh-tags} +filter{nimda} +filter{banners-by-size}     
3720  +hide-forwarded-for-headers +hide-from-header{block} +hide-referer{forge}          
3721  -hide-user-agent -handle-as-image +set-image-blocker{pattern} -limit-connect       
3722  +prevent-compression +session-cookies-only -crunch-outgoing-cookies                
3723  -crunch-incoming-cookies -kill-popups -send-vanilla-wafer -send-wafer }            
3724 /                                                                                   
3725                                                                                     
3726  { -session-cookies-only }                                                          
3727  .google.com                                                                        
3728                                                                                     
3729  { -fast-redirects }                                                                
3730  .google.com                                                                        
3731                                                                                     
3732 --- File user ---                                                                   
3733 (no matches in this file)                                                           
3734
3735 This tells us how we have defined our "actions", and which ones match for our
3736 example, "google.com". The first listing is any matches for the standard.action
3737 file. No hits at all here on "standard". Then next is "default", or our
3738 default.action file. The large, multi-line listing, is how the actions are set
3739 to match for all URLs, i.e. our default settings. If you look at your "actions"
3740 file, this would be the section just below the "aliases" section near the top.
3741 This will apply to all URLs as signified by the single forward slash at the end
3742 of the listing -- "/".
3743
3744 But we can define additional actions that would be exceptions to these general
3745 rules, and then list specific URLs (or patterns) that these exceptions would
3746 apply to. Last match wins. Just below this then are two explicit matches for
3747 ".google.com". The first is negating our previous cookie setting, which was for
3748 "+session-cookies-only" (i.e. not persistent). So we will allow persistent
3749 cookies for google. The second turns off any "+fast-redirects" action, allowing
3750 this to take place unmolested. Note that there is a leading dot here --
3751 ".google.com". This will match any hosts and sub-domains, in the google.com
3752 domain also, such as "www.google.com". So, apparently, we have these two
3753 actions defined somewhere in the lower part of our default.action file, and
3754 "google.com" is referenced somewhere in these latter sections.
3755
3756 Then, for our user.action file, we again have no hits.
3757
3758 And finally we pull it all together in the bottom section and summarize how
3759 Privoxy is applying all its "actions" to "google.com": 
3760
3761  Final results:                                                                    
3762  -add-header -block +deanimate-gifs{last} -downgrade-http-version -fast-redirects  
3763  -filter{popups} -filter{fun} -filter{shockwave-flash} -filter{crude-parental}     
3764  +filter{html-annoyances} +filter{js-annoyances} +filter{content-cookies}          
3765  +filter{webbugs} +filter{refresh-tags} +filter{nimda} +filter{banners-by-size}    
3766  +hide-forwarded-for-headers +hide-from-header{block} +hide-referer{forge}         
3767  -hide-user-agent -handle-as-image +set-image-blocker{pattern} -limit-connect      
3768  +prevent-compression -session-cookies-only -crunch-outgoing-cookies               
3769  -crunch-incoming-cookies -kill-popups -send-vanilla-wafer -send-wafer             
3770
3771 Notice the only difference here to the previous listing, is to "fast-redirects"
3772 and "session-cookies-only".
3773
3774 Now another example, "ad.doubleclick.net":
3775
3776  { +block +handle-as-image }                                                   
3777   .ad.doubleclick.net                                                          
3778                                                                                
3779  { +block +handle-as-image }                                                   
3780   ad*.                                                                         
3781                                                                                
3782  { +block +handle-as-image }                                                   
3783   .doubleclick.net                                                             
3784
3785 We'll just show the interesting part here, the explicit matches. It is matched
3786 three different times. Each as an "+block +handle-as-image", which is the
3787 expanded form of one of our aliases that had been defined as: "+imageblock". (
3788 "Aliases" are defined in the first section of the actions file and typically
3789 used to combine more than one action.)
3790
3791 Any one of these would have done the trick and blocked this as an unwanted
3792 image. This is unnecessarily redundant since the last case effectively would
3793 also cover the first. No point in taking chances with these guys though ;-)
3794 Note that if you want an ad or obnoxious URL to be invisible, it should be
3795 defined as "ad.doubleclick.net" is done here -- as both a "+block" and an 
3796 "+handle-as-image". The custom alias "+imageblock" just simplifies the process
3797 and make it more readable.
3798
3799 One last example. Let's try "http://www.rhapsodyk.net/adsl/HOWTO/". This one is
3800 giving us problems. We are getting a blank page. Hmmm...
3801
3802  Matches for http://www.rhapsodyk.net/adsl/HOWTO/:                                   
3803                                                                                      
3804  { -add-header -block +deanimate-gifs -downgrade-http-version +fast-redirects        
3805    +filter{html-annoyances} +filter{js-annoyances} +filter{kill-popups}              
3806    +filter{webbugs} +filter{nimda} +filter{banners-by-size} +filter{hal}             
3807    +filter{fun} +hide-forwarded-for-headers +hide-from-header{block}                 
3808    +hide-referer{forge} -hide-user-agent -handle-as-image +set-image-blocker{blank}  
3809    +prevent-compression +session-cookies-only -crunch-incoming-cookies               
3810    -crunch-outgoing-cookies +kill-popups -send-vanilla-wafer -send-wafer }           
3811    /                                                                                 
3812                                                                                      
3813  { +block +handle-as-image }                                                         
3814   /ads                                                                               
3815
3816 Ooops, the "/adsl/" is matching "/ads"! But we did not want this at all! Now we
3817 see why we get the blank page. We could now add a new action below this that
3818 explicitly does not block ("{-block}") paths with "adsl". There are various
3819 ways to handle such exceptions. Example:
3820
3821  { -block }                                                                    
3822   /adsl                                                                        
3823
3824 Now the page displays ;-) Be sure to flush your browser's caches when making
3825 such changes. Or, try using Shift+Reload.
3826
3827 But now what about a situation where we get no explicit matches like we did
3828 with:
3829
3830  { +block +handle-as-image }                                                   
3831  /ads                                                                          
3832
3833 That actually was very telling and pointed us quickly to where the problem was.
3834 If you don't get this kind of match, then it means one of the default rules in
3835 the first section is causing the problem. This would require some guesswork,
3836 and maybe a little trial and error to isolate the offending rule. One likely
3837 cause would be one of the "{+filter}" actions. Try adding the URL for the site
3838 to one of aliases that turn off "+filter":
3839
3840  {shop}                                                                        
3841  .quietpc.com                                                                  
3842  .worldpay.com   # for quietpc.com                                             
3843  .jungle.com                                                                   
3844  .scan.co.uk                                                                   
3845  .forbes.com                                                                   
3846
3847 "{shop}" is an "alias" that expands to "{ -filter -session-cookies-only }". Or
3848 you could do your own exception to negate filtering: 
3849
3850  {-filter}                                                                     
3851  .forbes.com                                                                   
3852
3853 This would probably be most appropriately put in user.action, for local site
3854 exceptions.
3855
3856 "{fragile}" is an alias that disables most actions. This can be used as a last
3857 resort for problem sites. Remember to flush caches! If this still does not
3858 work, you will have to go through the remaining actions one by one to find
3859 which one(s) is causing the problem.
3860