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