generated
[privoxy.git] / doc / text / user-manual.txt
1 Privoxy User Manual
2
3 By: Privoxy Developers
4
5 $Id: user-manual.sgml,v 1.103 2002/05/04 00:40:53 hal9 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 and SuSE RPMs
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 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. +deanimate-gifs
117         8.5.4. +downgrade-http-version
118         8.5.5. +fast-redirects
119         8.5.6. +filter
120         8.5.7. +hide-forwarded-for-headers
121         8.5.8. +hide-from-header
122         8.5.9. +hide-referer
123         8.5.10. +hide-user-agent
124         8.5.11. +handle-as-image
125         8.5.12. +set-image-blocker
126         8.5.13. +limit-connect
127         8.5.14. +prevent-compression
128         8.5.15. +session-cookies-only
129         8.5.16. +prevent-reading-cookies
130         8.5.17. +prevent-setting-cookies
131         8.5.18. +kill-popups
132         8.5.19. +send-vanilla-wafer
133         8.5.20. +send-wafer
134         8.5.21. Summary
135         8.5.22. Sample Actions Files
136        
137     8.6. Aliases
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. Copyright and History
153    
154     12.1. Copyright
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 idividual 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. Some platforms do this for you as part of their
237 installation procedure. (See below for your platform). In any case be sure to
238 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 and SuSE RPMs
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 localhost 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 localhost
459 for the proxy address, and port 8118 (earlier versions used port 8000). This is
460 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: localhost, 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 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 propably 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 that 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 propably 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.
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     localhost:8118
1172    
1173 Effect if unset:
1174    
1175     Bind to localhost (127.0.0.1), 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. See enable-remote-toggle below. This is not
1224     really useful anymore, since toggling is much easier via the web interface
1225     than via editing the conf file.
1226    
1227     The windows version will only display the toggle icon in the system tray if
1228     this option is present.
1229    
1230 -------------------------------------------------------------------------------
1231
1232 7.4.3. enable-remote-toggle
1233
1234 Specifies:
1235    
1236     Whether or not the web-based toggle feature may be used
1237    
1238 Type of value:
1239    
1240     0 or 1
1241    
1242 Default value:
1243    
1244     1
1245    
1246 Effect if unset:
1247    
1248     The web-based toggle feature is disabled.
1249    
1250 Notes:
1251    
1252     When toggled off, Privoxy acts like a normal, content-neutral proxy, i.e.
1253     it acts as if none of the actions applied to any URL.
1254    
1255     For the time being, access to the toggle feature can not be controlled
1256     separately by "ACLs" or HTTP authentication, so that everybody who can
1257     access Privoxy (see "ACLs" and listen-address above) can toggle it for all
1258     users. So this option is not recommended for multi-user environments with
1259     untrusted users.
1260    
1261     Note that you must have compiled Privoxy with support for this feature,
1262     otherwise this option has no effect.
1263    
1264 -------------------------------------------------------------------------------
1265
1266 7.4.4. enable-edit-actions
1267
1268 Specifies:
1269    
1270     Whether or not the web-based actions file editor may be used
1271    
1272 Type of value:
1273    
1274     0 or 1
1275    
1276 Default value:
1277    
1278     1
1279    
1280 Effect if unset:
1281    
1282     The web-based actions file editor is disabled.
1283    
1284 Notes:
1285    
1286     For the time being, access to the editor can not be controlled separately
1287     by "ACLs" or HTTP authentication, so that everybody who can access Privoxy
1288     (see "ACLs" and listen-address above) can modify its configuration for all
1289     users. So this option is not recommended for multi-user environments with
1290     untrusted users.
1291    
1292     Note that you must have compiled Privoxy with support for this feature,
1293     otherwise this option has no effect.
1294    
1295 -------------------------------------------------------------------------------
1296
1297 7.4.5. ACLs: permit-access and deny-access
1298
1299 Specifies:
1300    
1301     Who can access what.
1302    
1303 Type of value:
1304    
1305     src_addr[/src_masklen] [dst_addr[/dst_masklen]]
1306    
1307     Where src_addr and dst_addr are IP addresses in dotted decimal notation or
1308     valid DNS names, and src_masklen and dst_masklen are subnet masks in CIDR
1309     notation, i.e. integer values from 2 to 30 representing the length (in
1310     bits) of the network address. The masks and the whole destination part are
1311     optional.
1312    
1313 Default value:
1314    
1315     Unset
1316    
1317 Effect if unset:
1318    
1319     Don't restrict access further than implied by listen-address
1320    
1321 Notes:
1322    
1323     Access controls are included at the request of ISPs and systems
1324     administrators, and are not usually needed by individual users. For a
1325     typical home user, it will normally suffice to ensure that Privoxy only
1326     listens on the localhost or internal (home) network address by means of the
1327     listen-address option.
1328    
1329     Please see the warnings in the FAQ that this proxy is not intended to be a
1330     substitute for a firewall or to encourage anyone to defer addressing basic
1331     security weaknesses.
1332    
1333     Multiple ACL lines are OK. If any ACLs are specified, then the Privoxy
1334     talks only to IP addresses that match at least one permit-access line and
1335     don't match any subsequent deny-access line. In other words, the last match
1336     wins, with the default being deny-access.
1337    
1338     If Privoxy is using a forwarder (see forward below) for a particular
1339     destination URL, the dst_addr that is examined is the address of the
1340     forwarder and NOT the address of the ultimate target. This is necessary
1341     because it may be impossible for the local Privoxy to determine the IP
1342     address of the ultimate target (that's often what gateways are used for).
1343    
1344     You should prefer using IP addresses over DNS names, because the address
1345     lookups take time. All DNS names must resolve! You can not use domain
1346     patterns like "*.org" or partial domain names. If a DNS name resolves to
1347     multiple IP addresses, only the first one is used.
1348    
1349     Denying access to particular sites by ACL may have undesired side effects
1350     if the site in question is hosted on a machine which also hosts other
1351     sites.
1352    
1353 Examples:
1354    
1355     Explicitly define the default behavior if no ACL and listen-address are
1356     set: "localhost" is OK. The absence of a dst_addr implies that all
1357     destination addresses are OK:
1358    
1359       permit-access  localhost                                         
1360    
1361     Allow any host on the same class C subnet as www.privoxy.org access to
1362     nothing but www.example.com:
1363    
1364       permit-access  www.privoxy.org/24 www.example.com/32             
1365    
1366     Allow access from any host on the 26-bit subnet 192.168.45.64 to anywhere,
1367     with the exception that 192.168.45.73 may not access
1368     www.dirty-stuff.example.com:
1369    
1370       permit-access  192.168.45.64/26                                  
1371       deny-access    192.168.45.73    www.dirty-stuff.example.com      
1372    
1373 -------------------------------------------------------------------------------
1374
1375 7.4.6. buffer-limit
1376
1377 Specifies:
1378    
1379     Maximum size of the buffer for content filtering.
1380    
1381 Type of value:
1382    
1383     Size in Kbytes
1384    
1385 Default value:
1386    
1387     4096
1388    
1389 Effect if unset:
1390    
1391     Use a 4MB (4096 KB) limit.
1392    
1393 Notes:
1394    
1395     For content filtering, i.e. the +filter and +deanimate-gif actions, it is
1396     necessary that Privoxy buffers the entire document body. This can be
1397     potentially dangerous, since a server could just keep sending data
1398     indefinitely and wait for your RAM to exhaust -- with nasty consequences.
1399     Hence this option.
1400    
1401     When a document buffer size reaches the buffer-limit, it is flushed to the
1402     client unfiltered and no further attempt to filter the rest of the document
1403     is made. Remember that there may be multiple threads running, which might
1404     require up to buffer-limit Kbytes each, unless you have enabled
1405     "single-threaded" above.
1406    
1407 -------------------------------------------------------------------------------
1408
1409 7.5. Forwarding
1410
1411 This feature allows routing of HTTP requests through a chain of multiple
1412 proxies. It can be used to better protect privacy and confidentiality when
1413 accessing specific domains by routing requests to those domains through an
1414 anonymous public proxy (see e.g. http://www.multiproxy.org/anon_list.htm) Or to
1415 use a caching proxy to speed up browsing. Or chaining to a parent proxy may be
1416 necessary because the machine that Privoxy runs on has no direct Internet
1417 access.
1418
1419 Also specified here are SOCKS proxies. Privoxy supports the SOCKS 4 and SOCKS
1420 4A protocols.
1421
1422 -------------------------------------------------------------------------------
1423
1424 7.5.1. forward
1425
1426 Specifies:
1427    
1428     To which parent HTTP proxy specific requests should be routed.
1429    
1430 Type of value:
1431    
1432     target_domain[:port] http_parent[/port]
1433    
1434     Where target_domain is a domain name pattern (see the chapter on domain
1435     matching in the default.action file), http_parent is the address of the
1436     parent HTTP proxy as an IP addresses in dotted decimal notation or as a
1437     valid DNS name (or "." to denote "no forwarding", and the optional port
1438     parameters are TCP ports, i.e. integer values from 1 to 64535
1439    
1440 Default value:
1441    
1442     Unset
1443    
1444 Effect if unset:
1445    
1446     Don't use parent HTTP proxies.
1447    
1448 Notes:
1449    
1450     If http_parent is ".", then requests are not forwarded to another HTTP
1451     proxy but are made directly to the web servers.
1452    
1453     Multiple lines are OK, they are checked in sequence, and the last match
1454     wins.
1455    
1456 Examples:
1457    
1458     Everything goes to an example anonymizing proxy, except SSL on port 443
1459     (which it doesn't handle):
1460    
1461       forward   .*     anon-proxy.example.org:8080                     
1462       forward   :443   .                                               
1463    
1464     Everything goes to our example ISP's caching proxy, except for requests to
1465     that ISP's sites:
1466    
1467       forward   .*.                caching-proxy.example-isp.net:8000  
1468       forward   .example-isp.net   .                                   
1469    
1470 -------------------------------------------------------------------------------
1471
1472 7.5.2. forward-socks4 and forward-socks4a
1473
1474 Specifies:
1475    
1476     Through which SOCKS proxy (and to which parent HTTP proxy) specific
1477     requests should be routed.
1478    
1479 Type of value:
1480    
1481     target_domain[:port] socks_proxy[/port] http_parent[/port]
1482    
1483     Where target_domain is a domain name pattern (see the chapter on domain
1484     matching in the default.action file), http_parent and socks_proxy are IP
1485     addresses in dotted decimal notation or valid DNS names (http_parent may be
1486     "." to denote "no HTTP forwarding"), and the optional port parameters are
1487     TCP ports, i.e. integer values from 1 to 64535
1488    
1489 Default value:
1490    
1491     Unset
1492    
1493 Effect if unset:
1494    
1495     Don't use SOCKS proxies.
1496    
1497 Notes:
1498    
1499     Multiple lines are OK, they are checked in sequence, and the last match
1500     wins.
1501    
1502     The difference between forward-socks4 and forward-socks4a is that in the
1503     SOCKS 4A protocol, the DNS resolution of the target hostname happens on the
1504     SOCKS server, while in SOCKS 4 it happens locally.
1505    
1506     If http_parent is ".", then requests are not forwarded to another HTTP
1507     proxy but are made (HTTP-wise) directly to the web servers, albeit through
1508     a SOCKS proxy.
1509    
1510 Examples:
1511    
1512     From the company example.com, direct connections are made to all "internal"
1513     domains, but everything outbound goes through their ISP's proxy by way of
1514     example.com's corporate SOCKS 4A gateway to the Internet.
1515    
1516       forward-socks4a   .*.            socks-gw.example.com:1080  www-cache.example-isp.net:8080 
1517       forward           .example.com   .                                                         
1518    
1519     A rule that uses a SOCKS 4 gateway for all destinations but no HTTP parent
1520     looks like this:
1521    
1522       forward-socks4   .*.            socks-gw.example.com:1080  .     
1523    
1524 -------------------------------------------------------------------------------
1525
1526 7.5.3. Advanced Forwarding Examples
1527
1528 If you have links to multiple ISPs that provide various special content only to
1529 their subscribers, you can configure multiple Privoxies which have connections
1530 to the respective ISPs to act as forwarders to each other, so that your users
1531 can see the internal content of all ISPs.
1532
1533 Assume that host-a has a PPP connection to isp-a.net. And host-b has a PPP
1534 connection to isp-b.net. Both run Privoxy. Their forwarding configuration can
1535 look like this:
1536
1537 host-a:
1538
1539   forward    .*.         .                                                     
1540   forward    .isp-b.net  host-b:8118                                           
1541
1542 host-b:
1543
1544   forward    .*.         .                                                     
1545   forward    .isp-a.net  host-a:8118                                           
1546
1547 Now, your users can set their browser's proxy to use either host-a or host-b
1548 and be able to browse the internal content of both isp-a and isp-b.
1549
1550 If you intend to chain Privoxy and squid locally, then chain as browser ->
1551 squid -> privoxy is the recommended way.
1552
1553 Assuming that Privoxy and squid run on the same box, your squid configuration
1554 could then look like this:
1555
1556   # Define Privoxy as parent proxy (without ICP)                               
1557   cache_peer 127.0.0.1 parent 8118 7 no-query                                  
1558                                                                                
1559   # Define ACL for protocol FTP                                                
1560   acl ftp proto FTP                                                            
1561                                                                                
1562   # Do not forward FTP requests to Privoxy                                     
1563   always_direct allow ftp                                                      
1564                                                                                
1565   # Forward all the rest to Privoxy                                            
1566   never_direct allow all                                                       
1567
1568 You would then need to change your browser's proxy settings to squid's address
1569 and port. Squid normally uses port 3128. If unsure consult http_port in
1570 squid.conf.
1571
1572 -------------------------------------------------------------------------------
1573
1574 7.6. Windows GUI Options
1575
1576 Privoxy has a number of options specific to the Windows GUI interface:
1577
1578 If "activity-animation" is set to 1, the Privoxy icon will animate when
1579 "Privoxy" is active. To turn off, set to 0.
1580
1581   activity-animation 1
1582    
1583
1584 If "log-messages" is set to 1, Privoxy will log messages to the console window:
1585
1586   log-messages 1
1587    
1588
1589 If "log-buffer-size" is set to 1, the size of the log buffer, i.e. the amount
1590 of memory used for the log messages displayed in the console window, will be
1591 limited to "log-max-lines" (see below).
1592
1593 Warning: Setting this to 0 will result in the buffer to grow infinitely and eat
1594 up all your memory!
1595
1596   log-buffer-size 1
1597    
1598
1599 log-max-lines is the maximum number of lines held in the log buffer. See above.
1600
1601   log-max-lines 200
1602    
1603
1604 If "log-highlight-messages" is set to 1, Privoxy will highlight portions of the
1605 log messages with a bold-faced font:
1606
1607   log-highlight-messages 1
1608    
1609
1610 The font used in the console window:
1611
1612   log-font-name Comic Sans MS
1613    
1614
1615 Font size used in the console window:
1616
1617   log-font-size 8
1618    
1619
1620 "show-on-task-bar" controls whether or not Privoxy will appear as a button on
1621 the Task bar when minimized:
1622
1623   show-on-task-bar 0
1624    
1625
1626 If "close-button-minimizes" is set to 1, the Windows close button will minimize
1627 Privoxy instead of closing the program (close with the exit option on the File
1628 menu).
1629
1630   close-button-minimizes 1
1631    
1632
1633 The "hide-console" option is specific to the MS-Win console version of Privoxy.
1634 If this option is used, Privoxy will disconnect from and hide the command
1635 console.
1636
1637   #hide-console
1638    
1639
1640 -------------------------------------------------------------------------------
1641
1642 8. Actions Files
1643
1644 The actions files are used to define what actions Privoxy takes for which URLs,
1645 and thus determine how ad images, cookies and various other aspects of HTTP
1646 content and transactions are handled, and on which sites (or even parts
1647 thereof). There are three such files included with Privoxy (as of version
1648 2.9.15), with differing purposes:
1649
1650   * standard.action - is used by the web based editor, to set various
1651     pre-defined sets of rules for the default actions section in
1652     default.action. These have increasing levels of aggressiveness and have no
1653     influence on your browsing unless you select them explicitly in the editor.
1654     It is not recommend to edit this file.
1655    
1656   * default.action - is the primary action file that sets the initial values
1657     for all actions. It is intended to provide a base level of functionality
1658     for Privoxy's array of features. So it is a set of broad rules that should
1659     work reasonably well for users everywhere. This is the file that the
1660     developers are keeping updated, and making available to users.
1661    
1662   * user.action - is intended to be for local site preferences and exceptions.
1663     As an example, if your ISP or your bank has specific requirements, and need
1664     special handling, this kind of thing should go here. This file will not be
1665     upgraded.
1666    
1667 The list of actions files to be used are defined in the main configuration
1668 file, and are processed in the order they are defined. The content of these can
1669 all be viewed and edited from http://config.privoxy.org/show-status.
1670
1671 An actions file typically has multiple sections. If you want to use "aliases"
1672 in an actions file, you have to place the (optional) alias section at the top
1673 of that file. Then comes the default set of rules which will apply universally
1674 to all sites and pages (be very careful with using such a universal set in
1675 user.action or any other actions file after default.action, because it will
1676 override the result from consulting any previous file). And then below that,
1677 exceptions to the defined universal policies. You can regard user.action as an
1678 appendix to default.action, with the advantage that is a separate file, which
1679 makes preserving your personal settings across Privoxy upgrades easier.
1680
1681 Actions can be used to block anything you want, including ads, banners, or just
1682 some obnoxious URL that you would rather not see. Cookies can be accepted or
1683 rejected, or accepted only during the current browser session (i.e. not written
1684 to disk), content can be modified, JavaScripts tamed, user-tracking fooled, and
1685 much more. See below for a complete list of actions.
1686
1687 -------------------------------------------------------------------------------
1688
1689 8.1. Finding the Right Mix
1690
1691 Note that some actions, like cookie suppression or script disabling, may render
1692 some sites unusable that rely on these techniques to work properly. Finding the
1693 right mix of actions is not always easy and certainly a matter of personal
1694 taste. In general, it can be said that the more "aggressive" your default
1695 settings (in the top section of the actions file) are, the more exceptions for
1696 "trusted" sites you will have to make later. If, for example, you want to kill
1697 popup windows per default, you'll have to make exceptions from that rule for
1698 sites that you regularly use and that require popups for actually useful
1699 content, like maybe your bank, favorite shop, or newspaper.
1700
1701 We have tried to provide you with reasonable rules to start from in the
1702 distribution actions files. But there is no general rule of thumb on these
1703 things. There just are too many variables, and sites are constantly changing.
1704 Sooner or later you will want to change the rules (and read this chapter again
1705 :).
1706
1707 -------------------------------------------------------------------------------
1708
1709 8.2. How to Edit
1710
1711 The easiest way to edit the actions files is with a browser by using our
1712 browser-based editor, which can be reached from http://config.privoxy.org/
1713 show-status. The editor allows both fine-grained control over every single
1714 feature on a per-URL basis, and easy choosing from wholesale sets of defaults
1715 like "Cautious", "Medium" or "Advanced".
1716
1717 If you prefer plain text editing to GUIs, you can of course also directly edit
1718 the the actions files. Look at default.action which is richly commented.
1719
1720 -------------------------------------------------------------------------------
1721
1722 8.3. How Actions are Applied to URLs
1723
1724 Actions files are divided into sections. There are special sections, like the "
1725 alias" sections which will be discussed later. For now let's concentrate on
1726 regular sections: They have a heading line (often split up to multiple lines
1727 for readability) which consist of a list of actions, separated by whitespace
1728 and enclosed in curly braces. Below that, there is a list of URL patterns, each
1729 on a separate line.
1730
1731 To determine which actions apply to a request, the URL of the request is
1732 compared to all patterns in each action file file. Every time it matches, the
1733 list of applicable actions for the URL is incrementally updated, using the
1734 heading of the section in which the pattern is located. If multiple matches for
1735 the same URL set the same action differently, the last match wins. If not, the
1736 effects are aggregated (e.g. a URL might match both the "+handle-as-image" and 
1737 "+block" actions).
1738
1739 You can trace this process for any given URL by visiting http://
1740 config.privoxy.org/show-url-info.
1741
1742 More detail on this is provided in the Appendix, Anatomy of an Action.
1743
1744 -------------------------------------------------------------------------------
1745
1746 8.4. Patterns
1747
1748 Generally, a pattern has the form <domain>/<path>, where both the <domain> and
1749 <path> are optional. (This is why the pattern / matches all URLs).
1750
1751 www.example.com/
1752    
1753     is a domain-only pattern and will match any request to www.example.com,
1754     regardless of which document on that server is requested.
1755    
1756 www.example.com
1757    
1758     means exactly the same. For domain-only patterns, the trailing / may be
1759     omitted.
1760    
1761 www.example.com/index.html
1762    
1763     matches only the single document /index.html on www.example.com.
1764    
1765 /index.html
1766    
1767     matches the document /index.html, regardless of the domain, i.e. on any web
1768     server.
1769    
1770 index.html
1771    
1772     matches nothing, since it would be interpreted as a domain name and there
1773     is no top-level domain called .html.
1774    
1775 -------------------------------------------------------------------------------
1776
1777 8.4.1. The Domain Pattern
1778
1779 The matching of the domain part offers some flexible options: if the domain
1780 starts or ends with a dot, it becomes unanchored at that end. For example:
1781
1782 .example.com
1783    
1784     matches any domain that ENDS in .example.com
1785    
1786 www.
1787    
1788     matches any domain that STARTS with www.
1789    
1790 .example.
1791    
1792     matches any domain that CONTAINS .example. (Correctly speaking: It matches
1793     any FQDN that contains example as a domain.)
1794    
1795 Additionally, there are wild-cards that you can use in the domain names
1796 themselves. They work pretty similar to shell wild-cards: "*" stands for zero
1797 or more arbitrary characters, "?" stands for any single character, you can
1798 define character classes in square brackets and all of that can be freely
1799 mixed:
1800
1801 ad*.example.com
1802    
1803     matches "adserver.example.com", "ads.example.com", etc but not
1804     "sfads.example.com"
1805    
1806 *ad*.example.com
1807    
1808     matches all of the above, and then some.
1809    
1810 .?pix.com
1811    
1812     matches www.ipix.com, pictures.epix.com, a.b.c.d.e.upix.com etc.
1813    
1814 www[1-9a-ez].example.c*
1815    
1816     matches www1.example.com, www4.example.cc, wwwd.example.cy,
1817     wwwz.example.com etc., but not wwww.example.com.
1818    
1819 -------------------------------------------------------------------------------
1820
1821 8.4.2. The Path Pattern
1822
1823 Privoxy uses Perl compatible regular expressions (through the PCRE library) for
1824 matching the path.
1825
1826 There is an Appendix with a brief quick-start into regular expressions, and
1827 full (very technical) documentation on PCRE regex syntax is available on-line
1828 at http://www.pcre.org/man.txt. You might also find the Perl man page on
1829 regular expressions (man perlre) useful, which is available on-line at http://
1830 www.perldoc.com/perl5.6/pod/perlre.html.
1831
1832 Note that the path pattern is automatically left-anchored at the "/", i.e. it
1833 matches as if it would start with a "^" (regular expression speak for the
1834 beginning of a line).
1835
1836 Please also note that matching in the path is case INSENSITIVE by default, but
1837 you can switch to case sensitive at any point in the pattern by using the "(?
1838 -i)" switch: www.example.com/(?-i)PaTtErN.* will match only documents whose
1839 path starts with PaTtErN in exactly this capitalization.
1840
1841 -------------------------------------------------------------------------------
1842
1843 8.5. Actions
1844
1845 All actions are disabled by default, until they are explicitly enabled
1846 somewhere in an actions file. Actions are turned on if preceded with a "+", and
1847 turned off if preceded with a "-". So a +action means "do that action", e.g.
1848 +block means "please block URLs that match the following patterns", and -block
1849 means "don't block URLs that match the following patterns, even if +block
1850 previously applied." 
1851
1852 Again, actions are invoked by placing them on a line, enclosed in curly braces
1853 and separated by whitespace, like in {+some-action -some-other-action
1854 {some-parameter}}, followed by a list of URL patterns, one per line, to which
1855 they apply. Together, the actions line and the following pattern lines make up
1856 a section of the actions file.
1857
1858 There are three classes of actions:
1859
1860   * Boolean, i.e the action can only be "enabled" or "disabled". Syntax:
1861    
1862       +name        # enable action name                                
1863       -name        # disable action name                               
1864    
1865     Example: +block
1866    
1867   * Parameterized, where some value is required in order to enable this type of
1868     action. Syntax:
1869    
1870       +name{param}  # enable action and set parameter to param,             
1871                    # overwriting parameter from previous match if necessary 
1872       -name         # disable action. The parameter can be omitted          
1873    
1874     Note that if the URL matches multiple positive forms of a parameterized
1875     action, the last match wins, i.e. the params from earlier matches are
1876     simply ignored.
1877    
1878     Example: +hide-user-agent{ Mozilla 1.0 }
1879    
1880   * Multi-value. These look exactly like parameterized actions, but they behave
1881     differently: If the action applies multiple times to the same URL, but with
1882     different parameters, all the parameters from all matches are remembered.
1883     This is used for actions that can be executed for the same request
1884     repeatedly, like adding multiple headers, or filtering through multiple
1885     filters. Syntax:
1886    
1887       +name{param}   # enable action and add param to the list of parameters                 
1888       -name{param}   # remove the parameter param from the list of parameters                
1889                     # If it was the last one left, disable the action.                       
1890       -name          # disable this action completely and remove all parameters from the list
1891    
1892     Examples: +add-header{X-Fun-Header: Some text} and +filter{html-annoyances}
1893    
1894 If nothing is specified in any actions file, no "actions" are taken. So in this
1895 case Privoxy would just be a normal, non-blocking, non-anonymizing proxy. You
1896 must specifically enable the privacy and blocking features you need (although
1897 the provided default actions files will give a good starting point).
1898
1899 Later defined actions always over-ride earlier ones. So exceptions to any rules
1900 you make, should come in the latter part of the file (or in a file that is
1901 processed later when using multiple actions files). For multi-valued actions,
1902 the actions are applied in the order they are specified. Actions files are
1903 processed in the order they are defined in config (the default installation has
1904 three actions files). It also quite possible for any given URL pattern to match
1905 more than one pattern and thus more than one set of actions!
1906
1907 The list of valid Privoxy actions are:
1908
1909 -------------------------------------------------------------------------------
1910
1911 8.5.1. +add-header
1912
1913 Type:
1914    
1915     Multi-value.
1916    
1917 Purpose and typical uses:
1918    
1919     Send a user defined HTTP header to the web server. Can be used to confuse
1920     log analysis.
1921    
1922 Possible values:
1923    
1924     Any value is possible. Validity of the defined HTTP headers is not checked.
1925     It is recommended that you use the "X-" prefix for custom headers.
1926    
1927 Example usage:
1928    
1929          {+add-header{X-User-Tracking: sucks}}
1930          .example.com
1931    
1932 Notes:
1933    
1934     This action may be specified multiple times, in order to define multiple
1935     headers. This is rarely needed for the typical user. If you don't know what
1936     "HTTP headers" are, you definitely don't need to worry about this one.
1937    
1938 -------------------------------------------------------------------------------
1939
1940 8.5.2. +block
1941
1942 Type:
1943    
1944     Boolean.
1945    
1946 Purpose and typical uses:
1947    
1948     Requests for URLs to which this action applies are blocked, i.e. the
1949     requests are not forwarded to the remote server, but answered locally with
1950     a substitute page or image, as determined by the handle-as-image and 
1951     set-image-blocker actions. It is typically used to block ads or other
1952     obnoxious content.
1953    
1954 Possible values:
1955    
1956     N/A
1957    
1958 Example usage:
1959    
1960          {+block}
1961          .banners.example.com
1962          .ads.r.us
1963         
1964    
1965 Notes:
1966    
1967     If a URL matches one of the blocked patterns, Privoxy will intercept the
1968     URL and display its special "BLOCKED" page instead. If there is sufficient
1969     space, a large red banner will appear with a friendly message about why the
1970     page was blocked, and a way to go there anyway. If there is insufficient
1971     space a smaller "BLOCKED" page will appear without the red banner. Click
1972     here to view the default blocked HTML page (Privoxy must be running for
1973     this to work as intended!).
1974    
1975     A very important exception is if the URL matches both "+block" and 
1976     "+handle-as-image", then it will be handled by "+set-image-blocker" (see
1977     below). It is important to understand this process, in order to understand
1978     how Privoxy is able to deal with ads and other objectionable content.
1979    
1980     The "+filter" action can also perform some of the same functionality as
1981     "+block", but by virtue of very different programming techniques, and is
1982     most often used for different reasons.
1983    
1984 -------------------------------------------------------------------------------
1985
1986 8.5.3. +deanimate-gifs
1987
1988 Type:
1989    
1990     Parameterized.
1991    
1992 Typical uses:
1993    
1994     To stop those annoying, distracting animated GIF images.
1995    
1996 Possible values:
1997    
1998     "last" or "first"
1999    
2000 Example usage:
2001    
2002           {+deanimate-gifs{last}}
2003           .example.com
2004         
2005    
2006 Notes:
2007    
2008     De-animate all animated GIF images, i.e. reduce them to their last frame.
2009     This will also shrink the images considerably (in bytes, not pixels!). If
2010     the option "first" is given, the first frame of the animation is used as
2011     the replacement. If "last" is given, the last frame of the animation is
2012     used instead, which probably makes more sense for most banner animations,
2013     but also has the risk of not showing the entire last frame (if it is only a
2014     delta to an earlier frame).
2015    
2016 -------------------------------------------------------------------------------
2017
2018 8.5.4. +downgrade-http-version
2019
2020 Type:
2021    
2022     Boolean.
2023    
2024 Typical uses:
2025    
2026     "+downgrade-http-version" will downgrade HTTP/1.1 client requests to HTTP/
2027     1.0 and downgrade the responses as well.
2028    
2029 Possible values:
2030    
2031     N/A
2032    
2033 Example usage:
2034    
2035          {+downgrade-http-version}
2036          .example.com
2037         
2038    
2039 Notes:
2040    
2041     Use this action for servers that use HTTP/1.1 protocol features that
2042     Privoxy doesn't handle well yet. HTTP/1.1 is only partially implemented.
2043     Default is not to downgrade requests. This is an infrequently needed
2044     action, and is used to help with rare problem sites only.
2045    
2046 -------------------------------------------------------------------------------
2047
2048 8.5.5. +fast-redirects
2049
2050 Type:
2051    
2052     Boolean.
2053    
2054 Typical uses:
2055    
2056     The "+fast-redirects" action enables interception of "redirect" requests
2057     from one server to another, which are used to track users.Privoxy can cut
2058     off all but the last valid URL in a redirect request and send a local
2059     redirect back to your browser without contacting the intermediate site(s).
2060    
2061 Possible values:
2062    
2063     N/A
2064    
2065 Example usage:
2066    
2067          {+fast-redirects}
2068          .example.com
2069         
2070    
2071 Notes:
2072    
2073     Many sites, like yahoo.com, don't just link to other sites. Instead, they
2074     will link to some script on their own server, giving the destination as a
2075     parameter, which will then redirect you to the final target. URLs resulting
2076     from this scheme typically look like: http://some.place/some_script?http://
2077     some.where-else.
2078    
2079     Sometimes, there are even multiple consecutive redirects encoded in the
2080     URL. These redirections via scripts make your web browsing more traceable,
2081     since the server from which you follow such a link can see where you go to.
2082     Apart from that, valuable bandwidth and time is wasted, while your browser
2083     ask the server for one redirect after the other. Plus, it feeds the
2084     advertisers.
2085    
2086     This is a normally "on" feature, and often requires exceptions for sites
2087     that are sensitive to defeating this mechanism.
2088    
2089 -------------------------------------------------------------------------------
2090
2091 8.5.6. +filter
2092
2093 Type:
2094    
2095     Parameterized.
2096    
2097 Typical uses:
2098    
2099     Apply page filtering as defined by named sections of the default.filter
2100     file to the specified site(s). "Filtering" can be any modification of the
2101     raw page content, including re-writing or deletion of content.
2102    
2103 Possible values:
2104    
2105     "+filter" must include the name of one of the section identifiers from
2106     default.filter (or whatever filterfile is specified in config).
2107    
2108 Example usage (from the current default.filter):
2109    
2110     +filter{html-annoyances}: Get rid of particularly annoying HTML abuse.
2111    
2112     +filter{js-annoyances}: Get rid of particularly annoying JavaScript abuse
2113    
2114     +filter{content-cookies}: Kill cookies that come in the HTML or JS content
2115    
2116     +filter{popups}: Kill all popups in JS and HTML
2117    
2118     +filter{frameset-borders}: Give frames a border and make them resizable
2119    
2120     +filter{webbugs}: Squish WebBugs (1x1 invisible GIFs used for user         
2121     tracking)                                                                  
2122    
2123     +filter{refresh-tags}: Kill automatic refresh tags (for dial-on-demand     
2124     setups)                                                                    
2125    
2126     +filter{fun}: Text replacements for subversive browsing fun!
2127    
2128     +filter{nimda}: Remove Nimda (virus) code.
2129    
2130     +filter{banners-by-size}: Kill banners by size (very efficient!)
2131    
2132     +filter{shockwave-flash}: Kill embedded Shockwave Flash objects
2133    
2134     +filter{crude-parental}: Kill all web pages that contain the words "sex" or
2135     "warez"                                                                    
2136    
2137 Notes:
2138    
2139     This is potentially a very powerful feature! And requires a knowledge of
2140     regular expressions if you want to "roll your own". Filtering operates on a
2141     line by line basis throughout the entire page.
2142    
2143     Filtering requires buffering the page content, which may appear to slow
2144     down page rendering since nothing is displayed until all content has passed
2145     the filters. (It does not really take longer, but seems that way since the
2146     page is not incrementally displayed.) This effect will be more noticeable
2147     on slower connections.
2148    
2149     Filtering can achieve some of the effects as the "+block" action, i.e. it
2150     can be used to block ads and banners. In the overall scheme of things,
2151     filtering is one of the first things "Privoxy" does with a web page. So
2152     other most other actions are applied to the already "filtered" page.
2153    
2154 -------------------------------------------------------------------------------
2155
2156 8.5.7. +hide-forwarded-for-headers
2157
2158 Type:
2159    
2160     Boolean.
2161    
2162 Typical uses:
2163    
2164     Block any existing X-Forwarded-for HTTP header, and do not add a new one.
2165    
2166 Possible values:
2167    
2168     N/A
2169    
2170 Example usage:
2171    
2172          {+hide-forwarded-for-headers}
2173          .example.com
2174         
2175    
2176 Notes:
2177    
2178     It is fairly safe to leave this on. It does not seem to break many sites.
2179    
2180 -------------------------------------------------------------------------------
2181
2182 8.5.8. +hide-from-header
2183
2184 Type:
2185    
2186     Parameterized.
2187    
2188 Typical uses:
2189    
2190     To block the browser from sending your email address in a "From:" header.
2191    
2192 Possible values:
2193    
2194     Keyword: "block", or any user defined value.
2195    
2196 Example usage:
2197    
2198          {+hide-from-header{block}}
2199          .example.com
2200         
2201    
2202 Notes:
2203    
2204     The keyword "block" will completely remove the header (not to be confused
2205     with the "+block" action). Alternately, you can specify any value you
2206     prefer to send to the web server.
2207    
2208 -------------------------------------------------------------------------------
2209
2210 8.5.9. +hide-referer
2211
2212 Type:
2213    
2214     Parameterized.
2215    
2216 Typical uses:
2217    
2218     Don't send the "Referer:" (sic) HTTP header to the web site. Or,
2219     alternately send a forged header instead.
2220    
2221 Possible values:
2222    
2223     Prevent the header from being sent with the keyword, "block". Or, "forge" a
2224     URL to one from the same server as the request. Or, set to user defined
2225     value of your choice.
2226    
2227 Example usage:
2228    
2229          {+hide-referer{forge}}
2230          .example.com
2231         
2232    
2233 Notes:
2234    
2235     "forge" is the preferred option here, since some servers will not send
2236     images back otherwise.
2237    
2238     "+hide-referrer" is an alternate spelling of "+hide-referer". It has the
2239     exact same parameters, and can be freely mixed with, "+hide-referer".
2240     ("referrer" is the correct English spelling, however the HTTP specification
2241     has a bug - it requires it to be spelled as "referer".)
2242    
2243 -------------------------------------------------------------------------------
2244
2245 8.5.10. +hide-user-agent
2246
2247 Type:
2248    
2249     Parameterized.
2250    
2251 Typical uses:
2252    
2253     To change the "User-Agent:" header so web servers can't tell your browser
2254     type. Who's business is it anyway?
2255    
2256 Possible values:
2257    
2258     Any user defined string.
2259    
2260 Example usage:
2261    
2262          {+hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)}}
2263          .msn.com
2264         
2265    
2266 Notes:
2267    
2268     Warning! This breaks many web sites that depend on this in order to
2269     determine how the target browser will respond to various requests. Use with
2270     caution.
2271    
2272 -------------------------------------------------------------------------------
2273
2274 8.5.11. +handle-as-image
2275
2276 Type:
2277    
2278     Boolean.
2279    
2280 Typical uses:
2281    
2282     To define what Privoxy should treat automatically as an image, and is an
2283     important ingredient of how ads are handled.
2284    
2285 Possible values:
2286    
2287     N/A
2288    
2289 Example usage:
2290    
2291          {+handle-as-image}
2292          /.*\.(gif|jpg|jpeg|png|bmp|ico)
2293         
2294    
2295 Notes:
2296    
2297     This only has meaning if the URL (or pattern) also is "+block"ed, in which
2298     case a user definable image can be sent rather than a HTML page. This is
2299     integral to the whole concept of ad blocking: the URL must match both a 
2300     "+block" rule, and "+handle-as-image". (See "+set-image-blocker" below for
2301     control over what will actually be displayed by the browser.)
2302    
2303     There is little reason to change the default definition for this action.
2304    
2305 -------------------------------------------------------------------------------
2306
2307 8.5.12. +set-image-blocker
2308
2309 Type:
2310    
2311     Parameterized.
2312    
2313 Typical uses:
2314    
2315     Decide what to do with URLs that end up tagged with both "+block" and 
2316     "+handle-as-image", e.g an advertisement.
2317    
2318 Possible values:
2319    
2320     There are four available options: "-set-image-blocker" will send a HTML
2321     "blocked" page, usually resulting in a "broken image" icon.
2322     "+set-image-blocker{blank}" will send a 1x1 transparent GIF image.
2323     "+set-image-blocker{pattern}" will send a checkerboard type pattern (the
2324     default). And finally, "+set-image-blocker{http://xyz.com}" will send a
2325     HTTP temporary redirect to the specified image. This has the advantage of
2326     the icon being being cached by the browser, which will speed up the
2327     display.
2328    
2329 Example usage:
2330    
2331          {+set-image-blocker{blank}}
2332          .example.com
2333         
2334    
2335 Notes:
2336    
2337     If you want invisible ads, they need to meet criteria as matching both
2338     images and blocked actions. And then, "image-blocker" should be set to
2339     "blank" for invisibility. Note you cannot treat HTML pages as images in
2340     most cases. For instance, frames require an HTML page to display. So a
2341     frame that is an ad, typically cannot be treated as an image. Forcing an
2342     "image" in this situation just will not work reliably.
2343    
2344 -------------------------------------------------------------------------------
2345
2346 8.5.13. +limit-connect
2347
2348 Type:
2349    
2350     Parameterized.
2351    
2352 Typical uses:
2353    
2354     By default, Privoxy only allows HTTP CONNECT requests to port 443 (the
2355     standard, secure HTTPS port). Use "+limit-connect" to disable this
2356     altogether, or to allow more ports.
2357    
2358 Possible values:
2359    
2360     Any valid port number, or port number range.
2361    
2362 Example usages:
2363    
2364          +limit-connect{443}                       #
2365      This is the default and need not be specified.
2366          +limit-connect{80,443}                  # Ports 80 and 443 are OK.
2367          +limit-connect{-3, 7, 20-100, 500-}   #
2368      Port less than 3, 7, 20 to 100 and above 500 are OK.
2369         
2370    
2371 Notes:
2372    
2373     The CONNECT methods exists in HTTP to allow access to secure websites
2374     (https:// URLs) through proxies. It works very simply: the proxy connects
2375     to the server on the specified port, and then short-circuits its
2376     connections to the client and to the remote proxy. This can be a big
2377     security hole, since CONNECT-enabled proxies can be abused as TCP relays
2378     very easily.
2379    
2380     If you want to allow CONNECT for more ports than this, or want to forbid
2381     CONNECT altogether, you can specify a comma separated list of ports and
2382     port ranges (the latter using dashes, with the minimum defaulting to 0 and
2383     max to 65K).
2384    
2385     If you don't know what any of this means, there probably is no reason to
2386     change this one.
2387    
2388 -------------------------------------------------------------------------------
2389
2390 8.5.14. +prevent-compression
2391
2392 Type:
2393    
2394     Boolean.
2395    
2396 Typical uses:
2397    
2398     Prevent the specified websites from compressing HTTP data.
2399    
2400 Possible values:
2401    
2402     N/A
2403    
2404 Example usage:
2405    
2406          {+prevent-compression}
2407          .example.com
2408         
2409    
2410 Notes:
2411    
2412     Some websites do this, which can be a problem for Privoxy, since "+filter",
2413     "+kill-popups" and "+gif-deanimate" will not work on compressed data. This
2414     will slow down connections to those websites, though. Default typically is
2415     to turn "prevent-compression" on.
2416    
2417 -------------------------------------------------------------------------------
2418
2419 8.5.15. +session-cookies-only
2420
2421 Type:
2422    
2423     Boolean.
2424    
2425 Typical uses:
2426    
2427     Allow cookies for the current browser session only.
2428    
2429 Possible values:
2430    
2431     N/A
2432    
2433 Example usage (disabling):
2434    
2435          {-session-cookies-only}
2436          .example.com
2437         
2438    
2439 Notes:
2440    
2441     If websites set cookies, "+session-cookies-only" will make sure they are
2442     erased when you exit and restart your web browser. This makes profiling
2443     cookies useless, but won't break sites which require cookies so that you
2444     can log in for transactions. This is generally turned on for all sites, and
2445     is the recommended setting.
2446    
2447     "+prevent-*-cookies" actions should be turned off as well (see below), for
2448     "+session-cookies-only" to work. Or, else no cookies will get through at
2449     all. For, "persistent" cookies that survive across browser sessions, see
2450     below as well.
2451    
2452 -------------------------------------------------------------------------------
2453
2454 8.5.16. +prevent-reading-cookies
2455
2456 Type:
2457    
2458     Boolean.
2459    
2460 Typical uses:
2461    
2462     Explicitly prevent the web server from reading any cookies on your system.
2463    
2464 Possible values:
2465    
2466     N/A
2467    
2468 Example usage:
2469    
2470          {+prevent-reading-cookies}
2471          .example.com
2472         
2473    
2474 Notes:
2475    
2476     Often used in conjunction with "+prevent-setting-cookies" to disable
2477     cookies completely. Note that "+session-cookies-only" requires these to
2478     both be disabled (or else it never gets any cookies to cache).
2479    
2480     For "persistent" cookies to work (i.e. they survive across browser sessions
2481     and reboots), all three cookie settings should be "off" for the specified
2482     sites.
2483    
2484 -------------------------------------------------------------------------------
2485
2486 8.5.17. +prevent-setting-cookies
2487
2488 Type:
2489    
2490     Boolean.
2491    
2492 Typical uses:
2493    
2494     Explicitly block the web server from storing cookies on your system.
2495    
2496 Possible values:
2497    
2498     N/A
2499    
2500 Example usage:
2501    
2502          {+prevent-setting-cookies}
2503          .example.com
2504         
2505    
2506 Notes:
2507    
2508     Often used in conjunction with "+prevent-reading-cookies" to disable
2509     cookies completely (see above).
2510    
2511 -------------------------------------------------------------------------------
2512
2513 8.5.18. +kill-popups
2514
2515 Type:
2516    
2517     Boolean.
2518    
2519 Typical uses:
2520    
2521     Stop those annoying JavaScript pop-up windows!
2522    
2523 Possible values:
2524    
2525     N/A
2526    
2527 Example usage:
2528    
2529          {+kill-popups}
2530          .example.com
2531         
2532    
2533 Notes:
2534    
2535     "+kill-popups" uses a built in filter to disable pop-ups that use the
2536     window.open() function, etc. This is one of the first actions processed by
2537     Privoxy as it contacts the remote web server. This action is not always
2538     100% reliable, and is supplemented by "+filter{popups}".
2539    
2540 -------------------------------------------------------------------------------
2541
2542 8.5.19. +send-vanilla-wafer
2543
2544 Type:
2545    
2546     Boolean.
2547    
2548 Typical uses:
2549    
2550     Sends a cookie for every site stating that you do not accept any copyright
2551     on cookies sent to you, and asking them not to track you.
2552    
2553 Possible values:
2554    
2555     N/A
2556    
2557 Example usage:
2558    
2559          {+send-vanilla-wafer}
2560          .example.com
2561         
2562    
2563 Notes:
2564    
2565     This action only applies if you are using a jarfile for saving cookies. Of
2566     course, this is a (relatively) unique header and could conceivably be used
2567     to track you.
2568    
2569 -------------------------------------------------------------------------------
2570
2571 8.5.20. +send-wafer
2572
2573 Type:
2574    
2575     Multi-value.
2576    
2577 Typical uses:
2578    
2579     This allows you to send an arbitrary, user definable cookie.
2580    
2581 Possible values:
2582    
2583     User specified cookie name and corresponding value.
2584    
2585 Example usage:
2586    
2587          {+send-wafer{name=value}}
2588          .example.com
2589         
2590    
2591 Notes:
2592    
2593     This can be specified multiple times in order to add as many cookies as you
2594     like.
2595    
2596 -------------------------------------------------------------------------------
2597
2598 8.5.21. Summary
2599
2600 Note that many of these actions have the potential to cause a page to
2601 misbehave, possibly even not to display at all. There are many ways a site
2602 designer may choose to design his site, and what HTTP header content, and other
2603 criteria, he may depend on. There is no way to have hard and fast rules for all
2604 sites. See the Appendix for a brief example on troubleshooting actions.
2605
2606 -------------------------------------------------------------------------------
2607
2608 8.5.22. Sample Actions Files
2609
2610 Remember that the meaning of any of the above references is reversed by
2611 preceding the action with a "-", in place of the "+". Also, that some actions
2612 are turned on in the default section of the actions file, and require little to
2613 no additional configuration. These are just "on".
2614
2615 But, other actions that are turned on in the default section do typically
2616 require exceptions to be listed in the latter sections of one of our actions
2617 file. For instance, by default no URLs are "blocked" (i.e. in the default
2618 definitions of default.action). We need exceptions to this in order to enable
2619 ad blocking in the lower sections. But we need to be very selective about what
2620 we do block. Thus, the default is "off" for blocking.
2621
2622 Below is a liberally commented sample default.action file to demonstrate how
2623 all the pieces come together. And to show how exceptions to the default
2624 policies can be handled. This is followed by a brief user.action with similar
2625 examples.
2626
2627 # Sample default.action file <developers@privoxy.org>
2628
2629 # Settings -- Don't change! For internal Privoxy use ONLY.
2630 {{settings}}
2631 for-privoxy-version=3.0
2632
2633
2634 ##########################################################################
2635 # Aliases must be defined *before* they are used. These are
2636 # easier to remember, and can combine several actions into one. Once 
2637 # defined they can be used just like any built-in action -- but within 
2638 # this file only! Aliases do not require a + or - sign.
2639 ##########################################################################
2640
2641 # Some useful aliases.
2642 # Alias to turn off cookie handling, ie allow all cookies unmolested.
2643  -prevent-cookies = -prevent-setting-cookies -prevent-reading-cookies \
2644                     -session-cookies-only
2645
2646 # Alias to both block and treat as if an image for ad blocking
2647 # purposes.
2648  +imageblock      = +block +handle-as-image
2649
2650 # Fragile sites should have the minimum changes:
2651  fragile     = -block -deanimate-gifs -fast-redirects -filter -hide-referer \
2652                -prevent-cookies -kill-popups
2653
2654 # Shops should be allowed to set persistent cookies
2655  shop        = -filter -prevent-cookies -session-cookies-only
2656
2657
2658 ##########################################################################
2659 # Begin default action settings. Anything in this section will match 
2660 # all URLs -- UNLESS we have exceptions that also match, defined below this 
2661 # section. We will show all potential actions here whether they are on 
2662 # or off. We could omit any disabled action if we wanted, since all 
2663 # actions are 'off' by default anyway. Shown for completeness only.
2664 # Actions are enabled if preceded by a '+', otherwise they are disabled 
2665 # (unless an alias has been defined without this).
2666 ##########################################################################
2667  { \
2668  -add-header \
2669  -block \
2670  -deanimate-gifs \
2671  -downgrade-http-version \
2672  +fast-redirects \
2673  +filter{html-annoyances} \
2674  +filter{js-annoyances} \
2675  -filter{content-cookies} \
2676  -filter{popups} \
2677  +filter{webbugs} \
2678  -filter{refresh-tags} \
2679  -filter{fun} \
2680  +filter{nimda} \
2681  +filter{banners-by-size} \
2682  -filter{shockwave-flash} \
2683  -filter{crude-prental} \
2684  +hide-forwarded-for-headers \
2685  +hide-from-header{block} \
2686  -hide-referrer \
2687  -hide-user-agent \
2688  -handle-as-image \
2689  +set-image-blocker{pattern} \
2690  -limit-connect \
2691  +prevent-compression \
2692  -session-cookies-only \
2693  -prevent-reading-cookies \
2694  -prevent-setting-cookies \
2695  -kill-popups \
2696  -send-vanilla-wafer \
2697  -send-wafer \
2698  }
2699  / # forward slash will match *all* potential URL patterns. 
2700
2701 ##########################################################################
2702 # Default behavior is now set. Now we will define some exceptions to our 
2703 # default action policies.
2704 ##########################################################################
2705
2706 # These sites are very complex and require very minimal interference.
2707 # We'll disable most actions with our 'fragile' alias:
2708  { fragile }
2709  .office.microsoft.com           # surprise, surprise!
2710  .windowsupdate.microsoft.com
2711
2712
2713 # Shopping sites - not as fragile but require some special 
2714 # handling. We still want to block ads, and we will allow 
2715 # persistant cookies via the 'shop' alias:
2716  { shop }
2717  .quietpc.com 
2718  .worldpay.com   # for quietpc.com
2719  .jungle.com
2720  .scan.co.uk
2721
2722
2723 # These sites require pop-ups too :(  We'll combine our 'shop' 
2724 # alias with two other actions into one rule to allow all popups.
2725  { shop -kill-popups -filter{popups} }
2726  .dabs.com
2727  .overclockers.co.uk
2728
2729
2730 # The 'Fast-redirects' action breaks some sites. Disable this action
2731 # for these known sensitive sites:
2732  { -fast-redirects }
2733  login.yahoo.com
2734  edit.europe.yahoo.com
2735  .google.com
2736  .altavista.com/.*(like|url|link):http
2737  .altavista.com/trans.*urltext=http
2738  .nytimes.com
2739
2740
2741 # Define which file types will be treated as images. Important
2742 # for ad blocking.
2743  { +handle-as-image }
2744  /.*\.(gif|jpe?g|png|bmp|ico)
2745
2746
2747 # Now lets list some domains that are known ad generators. And
2748 # our alias that we use here will block these as well as force 
2749 # them to be treated as images. This combination of actions is 
2750 # important for ad blocking. What the browser will show instead is 
2751 # determined by the setting of "+set-image-blocker"
2752  { +imageblock }
2753  ar.atwola.com 
2754  .ad.doubleclick.net
2755  .a.yimg.com/(?:(?!/i/).)*$
2756  .a[0-9].yimg.com/(?:(?!/i/).)*$
2757  bs*.gsanet.com
2758  bs*.einets.com
2759  .qkimg.net
2760  ad.*.doubleclick.net
2761
2762
2763 # These will just simply be blocked. They will generate the BLOCKED
2764 # banner page, if matched. Heavy use of wildcards and regular 
2765 # expressions in this example. Enable block action:
2766  { +block }
2767  ad*.
2768  .*ads.
2769  banner?.
2770  count*.
2771  /.*count(er)?\.(pl|cgi|exe|dll|asp|php[34]?)
2772  /(?:.*/)?(publicite|werbung|rekla(ma|me|am)|annonse|maino(kset|nta|s)?)/
2773  .hitbox.com 
2774
2775
2776 # The above block section will probably inadvertantly catch some 
2777 # sites we DO NOT want blocked via the wildcards and regular expressions. 
2778 # Now let's set exceptions to the exceptions so the good guys get better 
2779 # treatment. Disable block action:
2780  { -block }
2781  advogato.org
2782  adsl.
2783  ad[ud]*.
2784  advice.
2785 # Let's just trust all .edu top level domains.
2786  .edu
2787  www.ugu.com/sui/ugu/adv
2788 # We'll need to access to path names containing 'download' 
2789  .*downloads.
2790  /downloads/
2791 # 'adv' is for globalintersec and means advanced, not advertisement
2792  www.globalintersec.com/adv
2793
2794
2795 # Don't filter *anything* from our friends at sourceforge.
2796 # Notice we don't have to name the individual filter 
2797 # identifiers -- we just turn them all off in one fell swoop.
2798 # Disable all filters for this one site:
2799  { -filter }
2800  .sourceforge.net
2801    
2802
2803 So far we are painting with a broad brush by setting general policies. The
2804 above would be a reasonable starting point for many situations. Now, we want to
2805 be more specific and have customized rules that are more suitable to our
2806 personal habits and preferences. These would be for narrowly defined situations
2807 like your ISP or your bank, and should be placed in user.action, which is
2808 parsed after all other actions files and should not be clobbered by upgrades.
2809 So any settings here, will have the last word and over-ride any previously
2810 defined actions.
2811
2812 Now a few examples of some things that one might do with a user.action file.
2813
2814 # Sample user.action file.
2815
2816 # Any aliases you want to use need to be re-defined here.
2817 # Alias to turn off cookie handling, ie allow all cookies unmolested.
2818  -prevent-cookies = -prevent-setting-cookies -prevent-reading-cookies \
2819                     -session-cookies-only
2820
2821 # Fragile sites should have the minimum changes:
2822  fragile     = -block -deanimate-gifs -fast-redirects -filter -hide-referer \
2823                -prevent-cookies -kill-popups
2824
2825 # Allow persistent cookies for a few regular sites that we 
2826 # trust via our above alias. These will be saved from one browser session 
2827 # to the next. We are explicity turning off any and all cookie handling, 
2828 # even though the prevent-*-cookie settings were disabled in our above 
2829 # default.action anyway. So cookies from these domains will come through 
2830 # unmolested.
2831  { -prevent-cookies }
2832  .sun.com
2833  .yahoo.com
2834  .msdn.microsoft.com
2835  .redhat.com
2836
2837
2838 # My ISP uses obnoxious self promoting images on many pages.
2839 # Nuke them :) Note that "+handle-as-image" need not be specified,
2840 # since all URLs ending in .gif will be tagged as images by the
2841 # general rules in default.action anyway.
2842  { +block }
2843  www.my-isp-example.com/logo[0-9].gif
2844
2845
2846 # Say the site where you do your homebanking needs to open
2847 # popup windows, but you have chosen to kill popups by
2848 # default. This will allow it for your-example-bank.com:
2849 #
2850  { -filter{popups} -kill-popups }
2851  .my-example-bank.com
2852
2853
2854 # This site is delicate, and requires kid-glove 
2855 # treatment.
2856  { fragile }
2857  .forbes.com
2858    
2859
2860 -------------------------------------------------------------------------------
2861
2862 8.6. Aliases
2863
2864 Custom "actions", known to Privoxy as "aliases", can be defined by combining
2865 other "actions". These can in turn be invoked just like the built-in "actions".
2866 Currently, an alias can contain any character except space, tab, "=", "{" or "}
2867 ". But please use only "a"- "z", "0"-"9", "+", and "-". Alias names are not
2868 case sensitive, and must be defined before other actions in the actions file!
2869 And there can only be one set of "aliases" defined per file. Each actions file
2870 may have its own aliases, but they are only visible within that file. Aliases
2871 do not requir a "+" or "-" sign in front, since they are merely expanded.
2872
2873 Now let's define a few aliases:
2874
2875  # Useful custom aliases we can use later. These must come first!
2876  {{alias}}
2877  +prevent-cookies = +prevent-setting-cookies +prevent-reading-cookies
2878  -prevent-cookies = -prevent-setting-cookies -prevent-reading-cookies
2879  fragile     =
2880  -block -prevent-cookies -filter -fast-redirects -hide-referer -kill-popups
2881  shop        = -prevent-cookies -filter -fast-redirects
2882  +imageblock = +block +handle-as-image
2883
2884  # Aliases defined from other aliases, for people who don't like to type 
2885  # too much:  ;-)
2886  c0 = +prevent-cookies
2887  c1 = -prevent-cookies
2888  #... etc.  Customize to your heart's content.
2889    
2890
2891 Some examples using our "shop" and "fragile" aliases from above. These would
2892 appear in the lower sections of an actions file as exceptions to the default
2893 actions (as defined in the upper section):
2894
2895  # These sites are very complex and require
2896  # minimal interference.
2897  {fragile}
2898   .office.microsoft.com
2899   .windowsupdate.microsoft.com
2900   .nytimes.com
2901
2902  # Shopping sites - but we still want to block ads.
2903  {shop}
2904   .quietpc.com
2905   .worldpay.com   # for quietpc.com
2906   .scan.co.uk
2907
2908  # These shops require pop-ups also 
2909  {shop -kill-popups}
2910   .dabs.com
2911   .overclockers.co.uk
2912    
2913
2914 The "shop" and "fragile" aliases are often used for "problem" sites that
2915 require most actions to be disabled in order to function properly. 
2916
2917 -------------------------------------------------------------------------------
2918
2919 9. The Filter File
2920
2921 Any web page can be dynamically modified with the filter file. This
2922 modification can be removal, or re-writing, of any web page content, including
2923 tags and non-visible content. The default filter file is oddly enough
2924 default.filter, located in the config directory.
2925
2926 This is potentially a very powerful feature, and requires knowledge of both
2927 "regular expression" and HTML in order create custom filters. But, there are a
2928 number of useful filters included with Privoxy for many common situations.
2929
2930 The included example file is divided into sections. Each section begins with
2931 the FILTER keyword, followed by the identifier for that section, e.g. "FILTER:
2932 webbugs". Each section performs a similar type of filtering, such as
2933 "html-annoyances".
2934
2935 This file uses regular expressions to alter or remove any string in the target
2936 page. The expressions can only operate on one line at a time. Some examples
2937 from the included default default.filter:
2938
2939 Stop web pages from displaying annoying messages in the status bar by deleting
2940 such references:
2941
2942  FILTER: html-annoyances
2943
2944  # New browser windows should be resizeable and have a location and status
2945  # bar. Make it so.
2946  #
2947  s/resizable="?(no|0)"?/resizable=1/ig s/noresize/yesresize/ig
2948  s/location="?(no|0)"?/location=1/ig s/status="?(no|0)"?/status=1/ig
2949  s/scrolling="?(no|0|Auto)"?/scrolling=1/ig
2950  s/menubar="?(no|0)"?/menubar=1/ig 
2951
2952  # The <BLINK> tag was a crime!
2953  #
2954  s*<blink>|</blink>**ig
2955
2956  # Is this evil? 
2957  #
2958  #s/framespacing="?(no|0)"?//ig
2959  #s/margin(height|width)=[0-9]*//gi
2960    
2961
2962 Just for kicks, replace any occurrence of "Microsoft" with "MicroSuck", and
2963 have a little fun with topical buzzwords:
2964
2965  FILTER: fun
2966
2967  s/microsoft(?!.com)/MicroSuck/ig
2968
2969  # Buzzword Bingo:
2970  #
2971  s/industry-leading|cutting-edge|award-winning/<font color=red><b>BINGO!</b></
2972 font>/ig
2973    
2974
2975 Kill those pesky little web-bugs:
2976
2977  # webbugs: Squish WebBugs (1x1 invisible GIFs used for user tracking)
2978  FILTER: webbugs
2979
2980  s/<img\s+[^>]*?(width|height)\s*=\s*['"]?1\D[^>]*?(width|height)\s*=\s*['"]?1
2981 (\D[^>]*?)?>/<!-- Squished WebBug -->/sig
2982    
2983
2984 -------------------------------------------------------------------------------
2985
2986 9.1. The +filter Action
2987
2988 Filters are enabled with the "+filter" action from within one of the actions
2989 files. "+filter" requires one parameter, which should match one of the section
2990 identifiers in the filter file itself. Example:
2991
2992   +filter{html-annoyances}                                                     
2993
2994 This would activate that particular filter. Similarly, "+filter" can be turned
2995 off for selected sites as: "-filter{html-annoyances}". Remember too, all
2996 actions are off by default, unless they are explicity enabled in one of the
2997 actions files.
2998
2999 -------------------------------------------------------------------------------
3000
3001 10. Templates
3002
3003 When Privoxy displays one of its internal pages, such as a 404 Not Found error
3004 page (Privoxy must be running for link to work as intended), it uses the
3005 appropriate template. On Linux, BSD, and Unix, these are located in /etc/
3006 privoxy/templates by default. These may be customized, if desired.
3007 cgi-style.css is used to control the HTML attributes (fonts, etc).
3008
3009 The default Blocked (Privoxy needs to be running for page to display) banner
3010 page with the bright red top banner, is called just "blocked". This may be
3011 customized or replaced with something else if desired. 
3012
3013 -------------------------------------------------------------------------------
3014
3015 11. Contacting the Developers, Bug Reporting and Feature Requests
3016
3017 We value your feedback. However, to provide you with the best support, please
3018 note the following sections.
3019
3020 -------------------------------------------------------------------------------
3021
3022 11.1. Get Support
3023
3024 To get support, use the Sourceforge Support Forum:
3025
3026     http://sourceforge.net/tracker/?group_id=11118&atid=211118
3027
3028 -------------------------------------------------------------------------------
3029
3030 11.2. Report bugs
3031
3032 To submit bugs, use the Sourceforge Bug Forum:
3033
3034     http://sourceforge.net/tracker/?group_id=11118&atid=111118. 
3035
3036 Make sure that the bug has not already been submitted. Please try to verify
3037 that it is a Privoxy bug, and not a browser or site bug first. If you are using
3038 your own custom configuration, please try the stock configs to see if the
3039 problem is a configuration related bug. And if not using the latest development
3040 snapshot, please try the latest one. Or even better, CVS sources. Please be
3041 sure to include the Privoxy version, platform, browser, any pertinent log data,
3042 any other relevant details (please be specific) and, if possible, some way to
3043 reproduce the bug.
3044
3045 -------------------------------------------------------------------------------
3046
3047 11.3. Request new features
3048
3049 To submit ideas on new features, use the Sourceforge feature request forum:
3050
3051     http://sourceforge.net/tracker/?atid=361118&group_id=11118&func=browse.
3052
3053 -------------------------------------------------------------------------------
3054
3055 11.4. Report ads or other filter problems
3056
3057 You can also send feedback on websites that Privoxy has problems with. Please
3058 bookmark the following link: "Privoxy - Submit Filter Feedback". Once you surf
3059 to a page with problems, use the bookmark to send us feedback. We will look
3060 into the issue as soon as possible.
3061
3062 New, improved default.action files will occasionally be made available based on
3063 your feedback. These will be announced on the ijbswa-announce list.
3064
3065 -------------------------------------------------------------------------------
3066
3067 11.5. Other
3068
3069 For any other issues, feel free to use the mailing lists:
3070  
3071     http://sourceforge.net/mail/?group_id=11118.
3072
3073 Anyone interested in actively participating in development and related
3074 discussions can also join the appropriate mailing list. Archives are available,
3075 too. See the page on Sourceforge.
3076
3077 -------------------------------------------------------------------------------
3078
3079 12. Copyright and History
3080
3081 12.1. Copyright
3082
3083 Privoxy is free software; you can redistribute it and/or modify it under the
3084 terms of the GNU General Public License as published by the Free Software
3085 Foundation; either version 2 of the License, or (at your option) any later
3086 version.
3087
3088 This program is distributed in the hope that it will be useful, but WITHOUT ANY
3089 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
3090 PARTICULAR PURPOSE. See the GNU General Public License for more details, which
3091 is available from the Free Software Foundation, Inc, 59 Temple Place - Suite
3092 330, Boston, MA 02111-1307, USA.
3093
3094 You should have received a copy of the GNU General Public License along with
3095 this program; if not, write to the Free Software Foundation, Inc., 59 Temple
3096 Place, Suite 330, Boston, MA 02111-1307 USA.
3097
3098 -------------------------------------------------------------------------------
3099
3100 12.2. History
3101
3102 Privoxy is evolved, and derived from, the Internet Junkbuster, with many
3103 improvments and enhancements over the original.
3104
3105 Junkbuster was originally written by Anonymous Coders and Junkbusters
3106 Corporation, and was released as free open-source software under the GNU GPL. 
3107 Stefan Waldherr made many improvements, and started the SourceForge project
3108 Privoxy to rekindle development. There are now several active developers
3109 contributing. The last stable release of Junkbuster was v2.0.2, which has now
3110 grown whiskers ;-).
3111
3112 -------------------------------------------------------------------------------
3113
3114 13. See Also
3115
3116 Other references and sites of interest to Privoxy users:
3117
3118 http://www.privoxy.org/, The Privoxy Home page.
3119
3120 http://sourceforge.net/projects/ijbswa, the Project Page for Privoxy on        
3121 Sourceforge.                                                                   
3122
3123 http://p.p/, access Privoxy from your browser. Alternately, http://            
3124 config.privoxy.org may work in some situations where the first does not.       
3125
3126 http://p.p/, and select "Privoxy - Submit Filter Feedback" to submit "misses"  
3127 to the developers.                                                             
3128
3129 http://www.junkbusters.com/ht/en/cookies.html
3130
3131 http://www.waldherr.org/junkbuster/
3132
3133 http://privacy.net/analyze/
3134
3135 http://www.squid-cache.org/
3136
3137  
3138
3139 -------------------------------------------------------------------------------
3140
3141 14. Appendix
3142
3143 14.1. Regular Expressions
3144
3145 Privoxy can use "regular expressions" in various config files. Assuming support
3146 for "pcre" (Perl Compatible Regular Expressions) is compiled in, which is the
3147 default. Such configuration directives do not require regular expressions, but
3148 they can be used to increase flexibility by matching a pattern with wild-cards
3149 against URLs.
3150
3151 If you are reading this, you probably don't understand what "regular
3152 expressions" are, or what they can do. So this will be a very brief
3153 introduction only. A full explanation would require a book ;-)
3154
3155 "Regular expressions" is a way of matching one character expression against
3156 another to see if it matches or not. One of the "expressions" is a literal
3157 string of readable characters (letter, numbers, etc), and the other is a
3158 complex string of literal characters combined with wild-cards, and other
3159 special characters, called meta-characters. The "meta-characters" have special
3160 meanings and are used to build the complex pattern to be matched against. Perl
3161 Compatible Regular Expressions is an enhanced form of the regular expression
3162 language with backward compatibility.
3163
3164 To make a simple analogy, we do something similar when we use wild-card
3165 characters when listing files with the dir command in DOS. *.* matches all
3166 filenames. The "special" character here is the asterisk which matches any and
3167 all characters. We can be more specific and use ? to match just individual
3168 characters. So "dir file?.text" would match "file1.txt", "file2.txt", etc. We
3169 are pattern matching, using a similar technique to "regular expressions"!
3170
3171 Regular expressions do essentially the same thing, but are much, much more
3172 powerful. There are many more "special characters" and ways of building complex
3173 patterns however. Let's look at a few of the common ones, and then some
3174 examples:
3175
3176 . - Matches any single character, e.g. "a", "A", "4", ":", or "@".
3177
3178 ? - The preceding character or expression is matched ZERO or ONE times. Either/
3179 or.                                                                            
3180
3181 + - The preceding character or expression is matched ONE or MORE times.
3182
3183 * - The preceding character or expression is matched ZERO or MORE times.
3184
3185 \ - The "escape" character denotes that the following character should be taken
3186 literally. This is used where one of the special characters (e.g. ".") needs to
3187 be taken literally and not as a special meta-character. Example: "example      
3188 \.com", makes sure the period is recognized only as a period (and not expanded 
3189 to its meta-character meaning of any single character).                        
3190
3191 [] - Characters enclosed in brackets will be matched if any of the enclosed    
3192 characters are encountered. For instance, "[0-9]" matches any numeric digit    
3193 (zero through nine). As an example, we can combine this with "+" to match any  
3194 digit one of more times: "[0-9]+".                                             
3195
3196 () - parentheses are used to group a sub-expression, or multiple               
3197 sub-expressions.                                                               
3198
3199 | - The "bar" character works like an "or" conditional statement. A match is   
3200 successful if the sub-expression on either side of "|" matches. As an example: 
3201 "/(this|that) example/" uses grouping and the bar character and would match    
3202 either "this example" or "that example", and nothing else.                     
3203
3204 s/string1/string2/g - This is used to rewrite strings of text. "string1" is    
3205 replaced by "string2" in this example. There must of course be a match on      
3206 "string1" first.                                                               
3207
3208 These are just some of the ones you are likely to use when matching URLs with
3209 Privoxy, and is a long way from a definitive list. This is enough to get us
3210 started with a few simple examples which may be more illuminating:
3211
3212 /.*/banners/.* - A simple example that uses the common combination of "." and "
3213 *" to denote any character, zero or more times. In other words, any string at
3214 all. So we start with a literal forward slash, then our regular expression
3215 pattern (".*") another literal forward slash, the string "banners", another
3216 forward slash, and lastly another ".*". We are building a directory path here.
3217 This will match any file with the path that has a directory named "banners" in
3218 it. The ".*" matches any characters, and this could conceivably be more forward
3219 slashes, so it might expand into a much longer looking path. For example, this
3220 could match: "/eye/hate/spammers/banners/annoy_me_please.gif", or just "/
3221 banners/annoying.html", or almost an infinite number of other possible
3222 combinations, just so it has "banners" in the path somewhere.
3223
3224 A now something a little more complex:
3225
3226 /.*/adv((er)?ts?|ertis(ing|ements?))?/ - We have several literal forward
3227 slashes again ("/"), so we are building another expression that is a file path
3228 statement. We have another ".*", so we are matching against any conceivable
3229 sub-path, just so it matches our expression. The only true literal that must
3230 match our pattern is adv, together with the forward slashes. What comes after
3231 the "adv" string is the interesting part.
3232
3233 Remember the "?" means the preceding expression (either a literal character or
3234 anything grouped with "(...)" in this case) can exist or not, since this means
3235 either zero or one match. So "((er)?ts?|ertis(ing|ements?))" is optional, as
3236 are the individual sub-expressions: "(er)", "(ing|ements?)", and the "s". The "
3237 |" means "or". We have two of those. For instance, "(ing|ements?)", can expand
3238 to match either "ing" OR "ements?". What is being done here, is an attempt at
3239 matching as many variations of "advertisement", and similar, as possible. So
3240 this would expand to match just "adv", or "advert", or "adverts", or
3241 "advertising", or "advertisement", or "advertisements". You get the idea. But
3242 it would not match "advertizements" (with a "z"). We could fix that by changing
3243 our regular expression to: "/.*/adv((er)?ts?|erti(s|z)(ing|ements?))?/", which
3244 would then match either spelling.
3245
3246 /.*/advert[0-9]+\.(gif|jpe?g) - Again another path statement with forward
3247 slashes. Anything in the square brackets "[]" can be matched. This is using
3248 "0-9" as a shorthand expression to mean any digit one through nine. It is the
3249 same as saying "0123456789". So any digit matches. The "+" means one or more of
3250 the preceding expression must be included. The preceding expression here is
3251 what is in the square brackets -- in this case, any digit one through nine.
3252 Then, at the end, we have a grouping: "(gif|jpe?g)". This includes a "|", so
3253 this needs to match the expression on either side of that bar character also. A
3254 simple "gif" on one side, and the other side will in turn match either "jpeg"
3255 or "jpg", since the "?" means the letter "e" is optional and can be matched
3256 once or not at all. So we are building an expression here to match image GIF or
3257 JPEG type image file. It must include the literal string "advert", then one or
3258 more digits, and a "." (which is now a literal, and not a special character,
3259 since it is escaped with "\"), and lastly either "gif", or "jpeg", or "jpg".
3260 Some possible matches would include: "//advert1.jpg", "/nasty/ads/
3261 advert1234.gif", "/banners/from/hell/advert99.jpg". It would not match
3262 "advert1.gif" (no leading slash), or "/adverts232.jpg" (the expression does not
3263 include an "s"), or "/advert1.jsp" ("jsp" is not in the expression anywhere).
3264
3265 s/microsoft(?!.com)/MicroSuck/i - This is a substitution. "MicroSuck" will
3266 replace any occurrence of "microsoft". The "i" at the end of the expression
3267 means ignore case. The "(?!.com)" means the match should fail if "microsoft" is
3268 followed by ".com". In other words, this acts like a "NOT" modifier. In case
3269 this is a hyperlink, we don't want to break it ;-).
3270
3271 We are barely scratching the surface of regular expressions here so that you
3272 can understand the default Privoxy configuration files, and maybe use this
3273 knowledge to customize your own installation. There is much, much more that can
3274 be done with regular expressions. Now that you know enough to get started, you
3275 can learn more on your own :/
3276
3277 More reading on Perl Compatible Regular expressions: http://www.perldoc.com/
3278 perl5.6/pod/perlre.html
3279
3280 -------------------------------------------------------------------------------
3281
3282 14.2. Privoxy's Internal Pages
3283
3284 Since Privoxy proxies each requested web page, it is easy for Privoxy to trap
3285 certain special URLs. In this way, we can talk directly to Privoxy, and see how
3286 it is configured, see how our rules are being applied, change these rules and
3287 other configuration options, and even turn Privoxy's filtering off, all with a
3288 web browser. 
3289
3290 The URLs listed below are the special ones that allow direct access to Privoxy.
3291 Of course, Privoxy must be running to access these. If not, you will get a
3292 friendly error message. Internet access is not necessary either.
3293
3294   * Privoxy main page:
3295    
3296         http://config.privoxy.org/
3297        
3298     Alternately, this may be reached at http://p.p/, but this variation may not
3299     work as reliably as the above in some configurations.
3300    
3301   * Show information about the current configuration, including viewing and
3302     editing of actions files:
3303    
3304         http://config.privoxy.org/show-status
3305        
3306   * Show the source code version numbers:
3307    
3308         http://config.privoxy.org/show-version
3309        
3310   * Show the browser's request headers:
3311    
3312         http://config.privoxy.org/show-request
3313        
3314   * Show which actions apply to a URL and why:
3315    
3316         http://config.privoxy.org/show-url-info
3317        
3318   * Toggle Privoxy on or off. In this case, "Privoxy" continues to run, but
3319     only as a pass-through proxy, with no actions taking place:
3320    
3321         http://config.privoxy.org/toggle
3322        
3323     Short cuts. Turn off, then on:
3324    
3325         http://config.privoxy.org/toggle?set=disable
3326        
3327         http://config.privoxy.org/toggle?set=enable
3328        
3329 These may be bookmarked for quick reference. See next. 
3330
3331 -------------------------------------------------------------------------------
3332
3333 14.2.1. Bookmarklets
3334
3335 Below are some "bookmarklets" to allow you to easily access a "mini" version of
3336 some of Privoxy's special pages. They are designed for MS Internet Explorer,
3337 but should work equally well in Netscape, Mozilla, and other browsers which
3338 support JavaScript. They are designed to run directly from your bookmarks - not
3339 by clicking the links below (although that should work for testing).
3340
3341 To save them, right-click the link and choose "Add to Favorites" (IE) or "Add
3342 Bookmark" (Netscape). You will get a warning that the bookmark "may not be
3343 safe" - just click OK. Then you can run the Bookmarklet directly from your
3344 favorites/bookmarks. For even faster access, you can put them on the "Links"
3345 bar (IE) or the "Personal Toolbar" (Netscape), and run them with a single
3346 click.
3347
3348   * Privoxy - Enable
3349    
3350   * Privoxy - Disable
3351    
3352   * Privoxy - Toggle Privoxy (Toggles between enabled and disabled)
3353    
3354   * Privoxy- View Status
3355    
3356   * Privoxy - Submit Filter Feedback
3357    
3358 Credit: The site which gave me the general idea for these bookmarklets is 
3359 www.bookmarklets.com. They have more information about bookmarklets.
3360
3361 -------------------------------------------------------------------------------
3362
3363 14.3. Chain of Events
3364
3365 Let's take a quick look at the basic sequence of events when a web page is
3366 requested by your browser and Privoxy is on duty:
3367
3368   * First, your web browser requests a web page. The browser knows to send the
3369     request to Privoxy, which will in turn, relay the request to the remote web
3370     server after passing the following tests:
3371    
3372   * Privoxy traps any request for its own internal CGI pages (e.g http://p.p/)
3373     and sends the CGI page back to the browser.
3374    
3375   * Next, Privoxy checks to see if the URL matches any "+block" patterns. If
3376     so, the URL is then blocked, and the remote web server will not be
3377     contacted. "+handle-as-image" is then checked and if it does not match, an
3378     HTML "BLOCKED" page is sent back. Otherwise, if it does match, an image is
3379     returned. The type of image depends on the setting of "+set-image-blocker"
3380     (blank, checkerboard pattern, or an HTTP redirect to an image elsewhere).
3381    
3382   * Untrusted URLs are blocked. If URLs are being added to the trust file, then
3383     that is done.
3384    
3385   * If the URL pattern matches the "+fast-redirects" action, it is then
3386     processed. Unwanted parts of the requested URL are stripped.
3387    
3388   * Now the rest of the client browser's request headers are processed. If any
3389     of these match any of the relevant actions (e.g. "+hide-user-agent", etc.),
3390     headers are suppressed or forged as determined by these actions and their
3391     parameters.
3392    
3393   * Now the web server starts sending its response back (i.e. typically a web
3394     page and related data).
3395    
3396   * First, the server headers are read and processed to determine, among other
3397     things, the MIME type (document type) and encoding. The headers are then
3398     filtered as deterimed by the "+prevent-setting-cookies", 
3399     "+session-cookies-only", and "+downgrade-http-version" actions.
3400    
3401   * If the "+kill-popups" action applies, and it is an HTML or JavaScript
3402     document, the popup-code in the response is filtered on-the-fly as it is
3403     received.
3404    
3405   * If a "+filter" or "+deanimate-gifs" action applies (and the document type
3406     fits the action), the rest of the page is read into memory (up to a
3407     configurable limit). Then the filter rules (from default.filter) are
3408     processed against the buffered content. Filters are applied in the order
3409     they are specified in the default.filter file. Animated GIFs, if present,
3410     are reduced to either the first or last frame, depending on the action
3411     setting.The entire page, which is now filtered, is then sent by Privoxy
3412     back to your browser.
3413    
3414     If neither "+filter" or "+deanimate-gifs" matches, then Privoxy passes the
3415     raw data through to the client browser as it becomes available.
3416    
3417   * As the browser receives the now (probably filtered) page content, it reads
3418     and then requests any URLs that may be embedded within the page source,
3419     e.g. ad images, stylesheets, JavaScript, other HTML documents (e.g.
3420     frames), sounds, etc. For each of these objects, the browser issues a new
3421     request. And each such request is in turn processed as above. Note that a
3422     complex web page may have many such embedded URLs.
3423    
3424 -------------------------------------------------------------------------------
3425
3426 14.4. Anatomy of an Action
3427
3428 The way Privoxy applies "actions" and "filters" to any given URL can be
3429 complex, and not always so easy to understand what is happening. And sometimes
3430 we need to be able to see just what Privoxy is doing. Especially, if something
3431 Privoxy is doing is causing us a problem inadvertently. It can be a little
3432 daunting to look at the actions and filters files themselves, since they tend
3433 to be filled with "regular expressions" whose consequences are not always so
3434 obvious.
3435
3436 One quick test to see if Privoxy is causing a problem or not, is to disable it
3437 temporarily. This should be the first troubleshooting step. See the
3438 Bookmarklets section on a quick and easy way to do this (be sure to flush
3439 caches afterward!).
3440
3441 Privoxy also provides the http://config.privoxy.org/show-url-info page that can
3442 show us very specifically how actions are being applied to any given URL. This
3443 is a big help for troubleshooting.
3444
3445 First, enter one URL (or partial URL) at the prompt, and then Privoxy will tell
3446 us how the current configuration will handle it. This will not help with
3447 filtering effects (i.e. the "+filter" action) from the default.filter file
3448 since this is handled very differently and not so easy to trap! It also will
3449 not tell you about any other URLs that may be embedded within the URL you are
3450 testing. For instance, images such as ads are expressed as URLs within the raw
3451 page source of HTML pages. So you will only get info for the actual URL that is
3452 pasted into the prompt area -- not any sub-URLs. If you want to know about
3453 embedded URLs like ads, you will have to dig those out of the HTML source. Use
3454 your browser's "View Page Source" option for this. Or right click on the ad,
3455 and grab the URL.
3456
3457 Let's try an example, google.com, and look at it one section at a time:
3458
3459  Matches for http://google.com:                                                     
3460                                                                                     
3461 --- File standard ---                                                               
3462 (no matches in this file)                                                           
3463                                                                                     
3464 --- File default ---                                                                
3465                                                                                     
3466 { -add-header -block +deanimate-gifs{last} -downgrade-http-version +fast-redirects  
3467  -filter{popups} -filter{fun} -filter{shockwave-flash} -filter{crude-parental}      
3468  +filter{html-annoyances} +filter{js-annoyances} +filter{content-cookies}           
3469  +filter{webbugs} +filter{refresh-tags} +filter{nimda} +filter{banners-by-size}     
3470  +hide-forwarded-for-headers +hide-from-header{block} +hide-referer{forge}          
3471  -hide-user-agent -handle-as-image +set-image-blocker{pattern} -limit-connect       
3472  +prevent-compression +session-cookies-only -prevent-reading-cookies                
3473  -prevent-setting-cookies -kill-popups -send-vanilla-wafer -send-wafer }            
3474 /                                                                                   
3475                                                                                     
3476  { -session-cookies-only }                                                          
3477  .google.com                                                                        
3478                                                                                     
3479  { -fast-redirects }                                                                
3480  .google.com                                                                        
3481                                                                                     
3482 --- File user ---                                                                   
3483 (no matches in this file)                                                           
3484
3485 This tells us how we have defined our "actions", and which ones match for our
3486 example, "google.com". The first listing is any matches for the standard.action
3487 file. No hits at all here on "standard". Then next is "default", or our
3488 default.action file. The large, multi-line listing, is how the actions are set
3489 to match for all URLs, i.e. our default settings. If you look at your "actions"
3490 file, this would be the section just below the "aliases" section near the top.
3491 This will apply to all URLs as signified by the single forward slash at the end
3492 of the listing -- "/".
3493
3494 But we can define additional actions that would be exceptions to these general
3495 rules, and then list specific URLs (or patterns) that these exceptions would
3496 apply to. Last match wins. Just below this then are two explicit matches for
3497 ".google.com". The first is negating our previous cookie setting, which was for
3498 "+session-cookies-only" (i.e. not persistent). So we will allow persistent
3499 cookies for google. The second turns off any "+fast-redirects" action, allowing
3500 this to take place unmolested. Note that there is a leading dot here --
3501 ".google.com". This will match any hosts and sub-domains, in the google.com
3502 domain also, such as "www.google.com". So, apparently, we have these two
3503 actions defined somewhere in the lower part of our default.action file, and
3504 "google.com" is referenced somewhere in these latter sections.
3505
3506 Then, for our user.action file, we again have no hits.
3507
3508 And finally we pull it all together in the bottom section and summarize how
3509 Privoxy is applying all its "actions" to "google.com": 
3510
3511   Final results:                                                                   
3512  -add-header -block +deanimate-gifs{last} -downgrade-http-version -fast-redirects  
3513  -filter{popups} -filter{fun} -filter{shockwave-flash} -filter{crude-parental}     
3514  +filter{html-annoyances} +filter{js-annoyances} +filter{content-cookies}          
3515  +filter{webbugs} +filter{refresh-tags} +filter{nimda} +filter{banners-by-size}    
3516  +hide-forwarded-for-headers +hide-from-header{block} +hide-referer{forge}         
3517  -hide-user-agent -handle-as-image +set-image-blocker{pattern} -limit-connect      
3518  +prevent-compression -session-cookies-only -prevent-reading-cookies               
3519  -prevent-setting-cookies -kill-popups -send-vanilla-wafer -send-wafer             
3520
3521 Notice the only difference here to the previous listing, is to "fast-redirects"
3522 and "session-cookies-only".
3523
3524 Now another example, "ad.doubleclick.net":
3525
3526   { +block +handle-as-image }                                                  
3527   .ad.doubleclick.net                                                          
3528                                                                                
3529  { +block +handle-as-image }                                                   
3530   ad*.                                                                         
3531                                                                                
3532  { +block +handle-as-image }                                                   
3533   .doubleclick.net                                                             
3534
3535 We'll just show the interesting part here, the explicit matches. It is matched
3536 three different times. Each as an "+block +handle-as-image", which is the
3537 expanded form of one of our aliases that had been defined as: "+imageblock". (
3538 "Aliases" are defined in the first section of the actions file and typically
3539 used to combine more than one action.)
3540
3541 Any one of these would have done the trick and blocked this as an unwanted
3542 image. This is unnecessarily redundant since the last case effectively would
3543 also cover the first. No point in taking chances with these guys though ;-)
3544 Note that if you want an ad or obnoxious URL to be invisible, it should be
3545 defined as "ad.doubleclick.net" is done here -- as both a "+block" and an 
3546 "+handle-as-image". The custom alias "+imageblock" just simplifies the process
3547 and make it more readable.
3548
3549 One last example. Let's try "http://www.rhapsodyk.net/adsl/HOWTO/". This one is
3550 giving us problems. We are getting a blank page. Hmmm...
3551
3552   Matches for http://www.rhapsodyk.net/adsl/HOWTO/:                                  
3553                                                                                      
3554  { -add-header -block +deanimate-gifs -downgrade-http-version +fast-redirects        
3555    +filter{html-annoyances} +filter{js-annoyances} +filter{kill-popups}              
3556    +filter{webbugs} +filter{nimda} +filter{banners-by-size} +filter{hal}             
3557    +filter{fun} +hide-forwarded-for-headers +hide-from-header{block}                 
3558    +hide-referer{forge} -hide-user-agent -handle-as-image +set-image-blocker{blank}  
3559    +prevent-compression +session-cookies-only -prevent-setting-cookies               
3560    -prevent-reading-cookies +kill-popups -send-vanilla-wafer -send-wafer }           
3561    /                                                                                 
3562                                                                                      
3563  { +block +handle-as-image }                                                         
3564   /ads                                                                               
3565
3566 Ooops, the "/adsl/" is matching "/ads"! But we did not want this at all! Now we
3567 see why we get the blank page. We could now add a new action below this that
3568 explicitly does not block ("{-block}") paths with "adsl". There are various
3569 ways to handle such exceptions. Example:
3570
3571   { -block }                                                                   
3572   /adsl                                                                        
3573
3574 Now the page displays ;-) Be sure to flush your browser's caches when making
3575 such changes. Or, try using Shift+Reload.
3576
3577 But now what about a situation where we get no explicit matches like we did
3578 with:
3579
3580   { +block +handle-as-image }                                                  
3581  /ads                                                                          
3582
3583 That actually was very telling and pointed us quickly to where the problem was.
3584 If you don't get this kind of match, then it means one of the default rules in
3585 the first section is causing the problem. This would require some guesswork,
3586 and maybe a little trial and error to isolate the offending rule. One likely
3587 cause would be one of the "{+filter}" actions. Try adding the URL for the site
3588 to one of aliases that turn off "+filter":
3589
3590   {shop}                                                                       
3591  .quietpc.com                                                                  
3592  .worldpay.com   # for quietpc.com                                             
3593  .jungle.com                                                                   
3594  .scan.co.uk                                                                   
3595  .forbes.com                                                                   
3596
3597 "{shop}" is an "alias" that expands to "{ -filter -session-cookies-only }". Or
3598 you could do your own exception to negate filtering: 
3599
3600   {-filter}                                                                    
3601  .forbes.com                                                                   
3602
3603 This would probably be most appropriately put in user.action, for local site
3604 exceptions.
3605
3606 "{fragile}" is an alias that disables most actions. This can be used as a last
3607 resort for problem sites. Remember to flush caches! If this still does not
3608 work, you will have to go through the remaining actions one by one to find
3609 which one(s) is causing the problem.
3610