+This documentation is included with the current beta version of Privoxy,
+v.2.9.14, and is mostly complete at this point. The most up to date reference
+for the time being is still the comments in the source files and in the
+individual configuration files. Development of version 3.0 is currently nearing
+completion, and includes many significant changes and enhancements over earlier
+versions. The target release date for stable v3.0 is "soon" ;-).
+
+Since this is a beta version, not all new features are well tested. This
+documentation may be slightly out of sync as a result (especially with CVS
+sources). And there may be bugs, though hopefully not many!
+
+-------------------------------------------------------------------------------
+
+1.1. New Features
+
+In addition to Internet Junkbuster's traditional features of ad and banner
+blocking and cookie management, Privoxy provides new features, some of them
+currently under development:
+
+ * Integrated browser based configuration and control utility at http://
+ config.privoxy.org/ (shortcut: http://p.p/). Browser-based tracing of rule
+ and filter effects. Remote toggling.
+
+ * Blocking of annoying pop-up browser windows.
+
+ * HTTP/1.1 compliant (but not all optional 1.1 features are supported).
+
+ * Support for Perl Compatible Regular Expressions in the configuration files,
+ and generally a more sophisticated and flexible configuration syntax over
+ previous versions.
+
+ * GIF de-animation.
+
+ * Web page content filtering (removes banners based on size, invisible
+ "web-bugs", JavaScript and HTML annoyances, pop-ups, etc.)
+
+ * Bypass many click-tracking scripts (avoids script redirection).
+
+ * Multi-threaded (POSIX and native threads).
+
+ * Auto-detection and re-reading of config file changes.
+
+ * User-customizable HTML templates (e.g. 404 error page).
+
+ * Improved cookie management features (e.g. session based cookies).
+
+ * Improved signal handling, and a true daemon mode (Unix).
+
+ * Builds from source on most UNIX-like systems. Packages available for: Linux
+ (RedHat, SuSE, or Debian), Windows, Sun Solaris, Mac OSX, OS/2, HP-UX 11,
+ NetBSD and AmigaOS.
+
+ * Every feature now controllable on a per-site or per-location basis,
+ configuration more powerful and versatile over-all.
+
+ * Many smaller new features added, limitations and bugs removed, and security
+ holes fixed.
+
+-------------------------------------------------------------------------------
+
+3. Installation
+
+Privoxy is available both in convenient pre-compiled packages for a wide range
+of operating systems, and as raw source code. For most users, we recommend
+using the packages, which can be downloaded from our Privoxy Project Page.
+
+If you like to live on the bleeding edge and are not afraid of using possibly
+unstable development versions, you can check out the up-to-the-minute version
+directly from the CVS repository or simply download the nightly CVS tarball.
+
+At present, Privoxy is known to run on Win32, Mac OSX, OS/2, AmigaOS, Linux
+(RedHat, Suse, Debian), FreeBSD, NetBSD, BeOS, and many flavors of Unix.
+
+-------------------------------------------------------------------------------
+
+3.1. Binary Packages
+
+Note: If you have a previous Junkbuster or Privoxy installation on your system,
+you will need to remove it. Some platforms do this for you as part of their
+installation procedure. (See below for your platform).
+
+In any case be sure to backup your old configuration if it is valuable to you.
+See the note to upgraders.
+
+How to install the binary packages depends on your operating system:
+
+-------------------------------------------------------------------------------
+
+3.1.1. Red Hat and SuSE RPMs
+
+RPMs can be installed with rpm -Uvh privoxy-2.9.14-1.rpm, and will use /etc/
+privoxy for the location of configuration files.
+
+Note that on Red Hat, Privoxy will not be automatically started on system boot.
+You will need to enable that using chkconfig, ntsysv, or similar method.
+
+If you have problems with failed dependencies, try rebuilding the SRC RPM: rpm
+--rebuild privoxy-2.9.14-1.src.rpm;. This will use your locally installed
+libraries and RPM version.
+
+Also note that if you have a Junkbuster RPM installed on your system, you need
+to remove it first, because the packages conflict. Otherwise, RPM will try to
+remove Junkbuster automatically, before installing Privoxy.
+
+-------------------------------------------------------------------------------
+
+3.1.2. Debian
+
+FIXME.
+
+-------------------------------------------------------------------------------
+
+3.1.3. Windows
+
+Just double-click the installer, which will guide you through the installation
+process.
+
+-------------------------------------------------------------------------------
+
+3.1.4. Solaris, NetBSD, FreeBSD, HP-UX
+
+Create a new directory, cd to it, then unzip and untar the archive. For the
+most part, you'll have to figure out where things go. FIXME.
+
+-------------------------------------------------------------------------------
+
+3.1.5. OS/2
+
+First, make sure that no previous installations of Junkbuster and / or Privoxy
+are left on your system. You can do this by
+
+Then, just double-click the WarpIN self-installing archive, which will guide
+you through the installation process. A shadow of the Privoxy executable will
+be placed in your startup folder so it will start automatically whenever OS/2
+starts.
+
+The directory you choose to install Privoxy into will contain all of the
+configuration files.
+
+-------------------------------------------------------------------------------
+
+3.1.6. Max OSX
+
+Unzip the downloaded package (you can either double-click on the file in the
+finder, or on the desktop if you downloaded it there). Then, double-click on
+the package installer icon and follow the installation process. Privoxy will be
+installed in the subdirectory /Applications/Privoxy.app. Privoxy will set
+itself up to start automatically on system bring-up via /System/Library/
+StartupItems/Privoxy.
+
+-------------------------------------------------------------------------------
+
+3.1.7. AmigaOS
+
+Copy and then unpack the lha archive to a suitable location. All necessary
+files will be installed into Privoxy directory, including all configuration and
+log files. To uninstall, just remove this directory.
+
+Start Privoxy (with RUN <>NIL:) in your startnet script (AmiTCP), in s:
+user-startup (RoadShow), as startup program in your startup script (Genesis),
+or as startup action (Miami and MiamiDx). Privoxy will automatically quit when
+you quit your TCP/IP stack (just ignore the harmless warning your TCP/IP stack
+may display that Privoxy is still running).
+
+-------------------------------------------------------------------------------
+
+3.2. Building from Source
+
+To build Privoxy from source, autoheader, autoconf, GNU make (gmake), and, of
+course, a C compiler are required.
+
+When building from a source tarball (either release version or nightly CVS
+tarball), first unpack the source:
+
+ tar xzvf privoxy-2.9.14-beta-src* [.tgz or .tar.gz]
+ cd privoxy-2.9.14-beta
+
+
+For retrieving the current CVS sources, you'll need CVS installed. Note that
+sources from CVS are development quality, and may not be stable, or well
+tested. To download CVS source:
+
+ cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
+ cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co current
+ cd current
+
+
+This will create a directory named current/, which will contain the source
+tree.
+
+Then, in either case, to build from unpacked tarball or CVS source:
+
+ autoheader
+ autoconf
+ ./configure # (--help to see options)
+ make # (the make from gnu, gmake for *BSD)
+ su
+ make -n install # (to see where all the files will go)
+ make install # (to really install)
+
+
+If you have gnu make, you can have the first four steps automatically done for
+you by just typing:
+
+ make
+
+
+in the freshly downloaded or unpacked source directory.
+
+For more detailed instructions on how to build Redhat and SuSE RPMs, Windows
+self-extracting installers, building on platforms with special requirements
+etc, please consult the developer manual.
+
+-------------------------------------------------------------------------------
+
+4. Quickstart to Using Privoxy
+
+4.1. Note to Upgraders
+
+There are very significant changes from older versions of Junkbuster to the
+current Privoxy. Configuration is substantially changed. Junkbuster 2.0.x and
+earlier configuration files will not migrate. The functionality of the old
+blockfile, cookiefile and imagelist, are now combined into the "actions files".
+default.action, is the main actions file. Local exceptions should best be put
+into user.action.
+
+A "filter file" (typically default.filter) is new as of Privoxy 2.9.x, and
+provides some of the new sophistication (explained below). config is much the
+same as before.
+
+If upgrading from a 2.0.x version, you will have to use the new config files,
+and possibly adapt any personal rules from your older files. When porting
+personal rules over from the old blockfile to the new actions files, please
+note that even the pattern syntax has changed. If upgrading from 2.9.x
+development versions, it is still recommended to use the new configuration
+files.
+
+A quick list of things to be aware of before upgrading:
+
+ * The default listening port is now 8118 due to a conflict with another
+ service (NAS).
+
+ * Some installers may remove earlier versions completely. Save any important
+ configuration files!
+
+ * Privoxy is controllable with a web browser at the special URL: http://
+ config.privoxy.org/ (Shortcut: http://p.p/). Many aspects of configuration
+ can be done here, including temporarily disabling Privoxy.
+
+ * The primary configuration file for cookie management, ad and banner
+ blocking, and many other aspects of Privoxy configuration is in the
+ "actions" files. It is strongly recommended to become familiar with the new
+ actions concept below, before modifying these files. Locally defined rules
+ should go into user.action.
+
+ * Some installers may not automatically start Privoxy after installation.
+
+-------------------------------------------------------------------------------
+
+4.2. Starting Privoxy
+
+Before launching Privoxy for the first time, you will want to configure your
+browser(s) to use Privoxy as a HTTP and HTTPS proxy. The default is localhost
+for the proxy address, and port 8118 (earlier versions used port 8000). This is
+the one configuration step that must be done!
+
+With Netscape (and Mozilla), this can be set under Edit -> Preferences ->
+Advanced -> Proxies -> HTTP Proxy. For Internet Explorer: Tools -> Internet
+Properties -> Connections -> LAN Setting. Then, check "Use Proxy" and fill in
+the appropriate info (Address: localhost, Port: 8118). Include if HTTPS proxy
+support too.
+
+After doing this, flush your browser's disk and memory caches to force a
+re-reading of all pages and to get rid of any ads that may be cached. You are
+now ready to start enjoying the benefits of using Privoxy!
+
+Privoxy is typically started by specifying the main configuration file to be
+used on the command line. Example Unix startup command:
+
+
+ # /usr/sbin/privoxy /etc/privoxy/config
+
+
+
+See below for other command line options.
+
+An init script is provided for SuSE and Red Hat.
+
+For for SuSE: rcprivoxy start
+
+For Red Hat and Debian: /etc/rc.d/init.d/privoxy start
+
+If no configuration file is specified on the command line, Privoxy will look
+for a file named config in the current directory. Except on Win32 where it will
+try config.txt. If no file is specified on the command line and no default
+configuration file can be found, Privoxy will fail to start.
+
+The included default configuration files should give a reasonable starting
+point. Most of the per site configuration is done in the "actions" files. These
+are where various cookie actions are defined, ad and banner blocking, and other
+aspects of Privoxy configuration. There are several such files included, with
+varying levels of aggressiveness.
+
+You will probably want to keep an eye out for sites for which you may prefer
+persistent cookies, and add these to your actions configuration as needed. By
+default, most of these will be accepted only during the current browser session
+(aka "session cookies"), unless you add them to the configuration. If you want
+the browser to handle this instead, you will need to edit user.action (or
+through the web based interface) and disable this feature. If you use more than
+one browser, it would make more sense to let Privoxy handle this. In which
+case, the browser(s) should be set to accept all cookies.
+
+Another feature where you will probably want to define exceptions for trusted
+sites is the popup-killing (through the +popup and +filter{popups} actions),
+because your favorite shopping, banking, or leisure site may need popups
+(explained below).
+
+Privoxy is HTTP/1.1 compliant, but not all of the optional 1.1 features are as
+yet supported. In the unlikely event that you experience inexplicable problems
+with browsers that use HTTP/1.1 per default (like Mozilla or recent versions of
+I.E.), you might try to force HTTP/1.0 compatibility. For Mozilla, look under
+Edit -> Preferences -> Debug -> Networking. Alternatively, set the
+"+downgrade-http-version" config option in default.action which will downgrade
+your browser's HTTP requests from HTTP/1.1 to HTTP/1.0 before processing them.
+
+After running Privoxy for a while, you can start to fine tune the configuration
+to suit your personal, or site, preferences and requirements. There are many,
+many aspects that can be customized. "Actions" can be adjusted by pointing your
+browser to http://config.privoxy.org/ (shortcut: http://p.p/), and then follow
+the link to "View & Change the Current Configuration". (This is an internal
+page and does not require Internet access.)
+
+In fact, various aspects of Privoxy configuration can be viewed from this page,
+including current configuration parameters, source code version numbers, the
+browser's request headers, and "actions" that apply to a given URL. In addition
+to the actions file editor mentioned above, Privoxy can also be turned "on" and
+"off" (toggled) from this page.
+
+If you encounter problems, try loading the page without Privoxy. If that helps,
+enter the URL where you have the problems into the browser based rule tracing
+utility. See which rules apply and why, and then try turning them off for that
+site one after the other, until the problem is gone. When you have found the
+culprit, you might want to turn the rest on again.
+
+If the above paragraph sounds gibberish to you, you might want to read more
+about the actions concept or even dive deep into the Appendix on actions.
+
+If you can't get rid of the problem at all, think you've found a bug in
+Privoxy, want to propose a new feature or smarter rules, please see the section
+"Contacting the Developers" below.
+
+-------------------------------------------------------------------------------
+
+4.3. Command Line Options
+
+Privoxy may be invoked with the following command-line options:
+
+ * --version
+
+ Print version info and exit. Unix only.
+
+ * --help
+
+ Print short usage info and exit. Unix only.
+
+ * --no-daemon
+
+ Don't become a daemon, i.e. don't fork and become process group leader, and
+ don't detach from controlling tty. Unix only.
+
+ * --pidfile FILE
+
+ On startup, write the process ID to FILE. Delete the FILE on exit. Failure
+ to create or delete the FILE is non-fatal. If no FILE option is given, no
+ PID file will be used. Unix only.
+
+ * --user USER[.GROUP]
+
+ After (optionally) writing the PID file, assume the user ID of USER, and if
+ included the GID of GROUP. Exit if the privileges are not sufficient to do
+ so. Unix only.
+
+ * configfile
+
+ If no configfile is included on the command line, Privoxy will look for a
+ file named "config" in the current directory (except on Win32 where it will
+ look for "config.txt" instead). Specify full path to avoid confusion. If no
+ config file is found, Privoxy will fail to start.
+
+-------------------------------------------------------------------------------
+
+5. Privoxy Configuration
+
+All Privoxy configuration is stored in text files. These files can be edited
+with a text editor. Many important aspects of Privoxy can also be controlled
+easily with a web browser.
+
+-------------------------------------------------------------------------------
+
+5.1. Controlling Privoxy with Your Web Browser
+
+Privoxy's user interface can be reached through the special URL http://
+config.privoxy.org/ (shortcut: http://p.p/), which is a built-in page and works
+without Internet access. You will see the following section:
+
+ Privoxy Menu
+ ? View & change the current configuration
+ ? View the source code version numbers
+ ? View the request headers.
+ ? Look up which actions apply to a URL and why
+ ? Toggle Privoxy on or off
+
+
+This should be self-explanatory. Note the first item leads to an editor for the
+"actions list", which is where the ad, banner, cookie, and URL blocking magic
+is configured as well as other advanced features of Privoxy. This is an easy
+way to adjust various aspects of Privoxy configuration. The actions file, and
+other configuration files, are explained in detail below.
+
+"Toggle Privoxy On or Off" is handy for sites that might have problems with
+your current actions and filters. You can in fact use it as a test to see
+whether it is Privoxy causing the problem or not. Privoxy continues to run as a
+proxy in this case, but all filtering is disabled. There is even a toggle
+Bookmarklet offered, so that you can toggle Privoxy with one click from your
+browser.
+
+-------------------------------------------------------------------------------
+
+5.2. Configuration Files Overview
+
+For Unix, *BSD and Linux, all configuration files are located in /etc/privoxy/
+by default. For MS Windows, OS/2, and AmigaOS these are all in the same
+directory as the Privoxy executable. The name and number of configuration files
+has changed from previous versions, and is subject to change as development
+progresses.
+
+The installed defaults provide a reasonable starting point, though some
+settings may be aggressive by some standards. For the time being, the principle
+configuration files are:
+
+ * The main configuration file is named config on Linux, Unix, BSD, OS/2, and
+ AmigaOS and config.txt on Windows. This is a required file.
+
+ * default.action (the main actions file) is used to define the default
+ settings for various "actions" relating to images, banners, pop-ups, access
+ restrictions, banners and cookies.
+
+ Multiple actions files may be defined in config. These are processed in the
+ order they are defined. Local customizations and locally preferred
+ exceptions to the default policies as defined in default.action are
+ probably best applied in user.action, which should be preserved across
+ upgrades. standard.action is also included. This is mostly for Privoxy's
+ internal use.
+
+ There is also a web based editor that can be accessed from http://
+ config.privoxy.org/show-status/ (Shortcut: http://p.p/show-status/) for the
+ various actions files.
+
+ * default.filter (the filter file) can be used to re-write the raw page
+ content, including viewable text as well as embedded HTML and JavaScript,
+ and whatever else lurks on any given web page. The filtering jobs are only
+ pre-defined here; whether to apply them or not is up to the actions files.
+
+All files use the "#" character to denote a comment (the rest of the line will
+be ignored) and understand line continuation through placing a backslash ("\")
+as the very last character in a line. If the # is preceded by a backslash, it
+looses its special function. Placing a # in front of an otherwise valid
+configuration line to prevent it from being interpreted is called "commenting
+out" that line.
+
+The actions files and default.filter can use Perl style regular expressions for
+maximum flexibility.
+
+After making any changes, there is no need to restart Privoxy in order for the
+changes to take effect. Privoxy detects such changes automatically. Note,
+however, that it may take one or two additional requests for the change to take
+effect. When changing the listening address of Privoxy, these "wake up"
+requests must obviously be sent to the old listening address.
+
+While under development, the configuration content is subject to change. The
+below documentation may not be accurate by the time you read this. Also, what
+constitutes a "default" setting, may change, so please check all your
+configuration files on important issues.
+
+-------------------------------------------------------------------------------
+
+5.3. The Main Configuration File
+
+Again, the main configuration file is named config on Linux/Unix/BSD and OS/2,
+and config.txt on Windows. Configuration lines consist of an initial keyword
+followed by a list of values, all separated by whitespace (any number of spaces
+or tabs). For example:
+
+ confdir /etc/privoxy
+
+
+Assigns the value /etc/privoxy to the option confdir and thus indicates that
+the configuration directory is named "/etc/privoxy/".
+
+All options in the config file except for confdir and logdir are optional.
+Watch out in the below description for what happens if you leave them unset.
+
+The main config file controls all aspects of Privoxy's operation that are not
+location dependent (i.e. they apply universally, no matter where you may be
+surfing).
+
+-------------------------------------------------------------------------------
+
+5.3.1. Configuration and Log File Locations
+
+Privoxy can (and normally does) use a number of other files for additional
+configuration and logging. This section of the configuration file tells Privoxy
+where to find those other files.
+
+-------------------------------------------------------------------------------
+
+5.3.1.1. confdir
+
+Specifies:
+
+ The directory where the other configuration files are located
+
+Type of value:
+
+ Path name
+
+Default value:
+
+ /etc/privoxy (Unix) or Privoxy installation dir (Windows)
+
+Effect if unset:
+
+ Mandatory
+
+Notes:
+
+ No trailing "/", please
+
+ When development goes modular and multi-user, the blocker, filter, and
+ per-user config will be stored in subdirectories of "confdir". For now, the
+ configuration directory structure is flat, except for confdir/templates,
+ where the HTML templates for CGI output reside (e.g. Privoxy's 404 error
+ page).
+
+-------------------------------------------------------------------------------
+
+5.3.1.2. logdir
+
+Specifies:
+
+ The directory where all logging takes place (i.e. where logfile and jarfile
+ are located)
+
+Type of value:
+
+ Path name
+
+Default value:
+
+ /var/log/privoxy (Unix) or Privoxy installation dir (Windows)
+
+Effect if unset:
+
+ Mandatory
+
+Notes:
+
+ No trailing "/", please
+
+-------------------------------------------------------------------------------
+
+5.3.1.3. actionsfile
+
+Specifies:
+
+ The actions file(s) to use
+
+Type of value:
+
+ File name, relative to confdir
+
+Default value:
+
+ standard # Internal purposes, recommended not editing
+
+ default # Main actions file
+
+ user # User customizations
+
+Effect if unset:
+
+ No actions are taken at all. Simple neutral proxying.
+
+Notes:
+
+ Multiple actionsfile lines are OK and are in fact recommended!
+
+ The default values include standard.action, which is used for internal
+ purposes and should be loaded, default.action, which is the "main" actions
+ file maintained by the developers, and user.action, where you can make your
+ personal additions.
+
+ There is no point in using Privoxy without an actions file.
+
+-------------------------------------------------------------------------------
+
+5.3.1.4. filterfile
+
+Specifies:
+
+ The filter file to use
+
+Type of value:
+
+ File name, relative to confdir
+
+Default value:
+
+ default.filter (Unix) or default.filter.txt (Windows)
+
+Effect if unset:
+
+ No textual content filtering takes place, i.e. all +filter{name} actions in
+ the actions files are turned off
+
+Notes:
+
+ The "default.filter" file contains content modification rules that use
+ "regular expressions". These rules permit powerful changes on the content
+ of Web pages, e.g., you could disable your favorite JavaScript annoyances,
+ re-write the actual displayed text, or just have some fun replacing
+ "Microsoft" with "MicroSuck" wherever it appears on a Web page.
+
+-------------------------------------------------------------------------------
+
+5.3.1.5. logfile
+
+Specifies:
+
+ The log file to use
+
+Type of value:
+
+ File name, relative to logdir
+
+Default value:
+
+ logfile (Unix) or privoxy.log (Windows)
+
+Effect if unset:
+
+ No log file is used, all log messages go to the console (stderr).
+
+Notes:
+
+ The windows version will additionally log to the console.
+
+ The logfile is where all logging and error messages are written. The level
+ of detail and number of messages are set with the debug option (see below).
+ The logfile can be useful for tracking down a problem with Privoxy (e.g.,
+ it's not blocking an ad you think it should block) but in most cases you
+ probably will never look at it.
+
+ Your logfile will grow indefinitely, and you will probably want to
+ periodically remove it. On Unix systems, you can do this with a cron job
+ (see "man cron"). For Red Hat, a logrotate script has been included.
+
+ On SuSE Linux systems, you can place a line like "/var/log/privoxy.* +1024k
+ 644 nobody.nogroup" in /etc/logfiles, with the effect that cron.daily will
+ automatically archive, gzip, and empty the log, when it exceeds 1M size.
+
+-------------------------------------------------------------------------------
+
+5.3.1.6. jarfile
+
+Specifies:
+
+ The file to store intercepted cookies in
+
+Type of value:
+
+ File name, relative to logdir
+
+Default value:
+
+ jarfile (Unix) or privoxy.jar (Windows)
+
+Effect if unset:
+
+ Intercepted cookies are not stored at all.
+
+Notes:
+
+ The jarfile may grow to ridiculous sizes over time.
+
+-------------------------------------------------------------------------------
+
+5.3.1.7. trustfile
+
+Specifies:
+
+ The trust file to use
+
+Type of value:
+
+ File name, relative to confdir
+
+Default value:
+
+ Unset (commented out). When activated: trust (Unix) or trust.txt (Windows)
+
+Effect if unset:
+
+ The whole trust mechanism is turned off.
+
+Notes:
+
+ The trust mechanism is an experimental feature for building white-lists and
+ should be used with care. It is NOT recommended for the casual user.
+
+ If you specify a trust file, Privoxy will only allow access to sites that
+ are named in the trustfile. You can also mark sites as trusted referrers
+ (with +), with the effect that access to untrusted sites will be granted,
+ if a link from a trusted referrer was used. The link target will then be
+ added to the "trustfile". Possible applications include limiting Internet
+ access for children.
+
+ If you use + operator in the trust file, it may grow considerably over
+ time.
+
+-------------------------------------------------------------------------------
+
+5.3.2. Local Set-up Documentation
+
+If you intend to operate Privoxy for more users that just yourself, it might be
+a good idea to let them know how to reach you, what you block and why you do
+that, your policies etc.
+
+-------------------------------------------------------------------------------
+
+5.3.2.1. trust-info-url
+
+Specifies:
+
+ A URL to be displayed in the error page that users will see if access to an
+ untrusted page is denied.
+
+Type of value:
+
+ URL
+
+Default value:
+
+ Two example URL are provided
+
+Effect if unset:
+
+ No links are displayed on the "untrusted" error page.
+
+Notes:
+
+ The value of this option only matters if the experimental trust mechanism
+ has been activated. (See trustfile above.)
+
+ If you use the trust mechanism, it is a good idea to write up some on-line
+ documentation about your trust policy and to specify the URL(s) here. Use
+ multiple times for multiple URLs.
+
+ The URL(s) should be added to the trustfile as well, so users don't end up
+ locked out from the information on why they were locked out in the first
+ place!
+
+-------------------------------------------------------------------------------
+
+5.3.2.2. admin-address
+
+Specifies:
+
+ An email address to reach the proxy administrator.
+
+Type of value:
+
+ Email address
+
+Default value:
+
+ Unset
+
+Effect if unset:
+
+ No email address is displayed on error pages and the CGI user interface.
+
+Notes:
+
+ If both admin-address and proxy-info-url are unset, the whole "Local
+ Privoxy Support" box on all generated pages will not be shown.
+
+-------------------------------------------------------------------------------
+
+5.3.2.3. proxy-info-url
+
+Specifies:
+
+ A URL to documentation about the local Privoxy setup, configuration or
+ policies.
+
+Type of value:
+
+ URL
+
+Default value:
+
+ Unset
+
+Effect if unset:
+
+ No link to local documentation is displayed on error pages and the CGI user
+ interface.
+
+Notes:
+
+ If both admin-address and proxy-info-url are unset, the whole "Local
+ Privoxy Support" box on all generated pages will not be shown.
+
+ This URL shouldn't be blocked ;-)
+
+-------------------------------------------------------------------------------
+
+5.3.3. Debugging
+
+These options are mainly useful when tracing a problem. Note that you might
+also want to invoke Privoxy with the --no-daemon command line option when
+debugging.
+
+-------------------------------------------------------------------------------
+
+5.3.3.1. debug
+
+Specifies:
+
+ Key values that determine what information gets logged.
+
+Type of value:
+
+ Integer values
+
+Default value:
+
+ 12289 (i.e.: URLs plus informational and warning messages)
+
+Effect if unset:
+
+ Nothing gets logged.
+
+Notes:
+
+ The available debug levels are:
+
+ debug 1 # show each GET/POST/CONNECT request
+ debug 2 # show each connection status
+ debug 4 # show I/O status
+ debug 8 # show header parsing
+ debug 16 # log all data into the logfile
+ debug 32 # debug force feature
+ debug 64 # debug regular expression filter
+ debug 128 # debug fast redirects
+ debug 256 # debug GIF de-animation
+ debug 512 # Common Log Format
+ debug 1024 # debug kill pop-ups
+ debug 4096 # Startup banner and warnings.
+ debug 8192 # Non-fatal errors
+
+
+ To select multiple debug levels, you can either add them or use multiple
+ debug lines.
+
+ A debug level of 1 is informative because it will show you each request as
+ it happens. 1, 4096 and 8192 are highly recommended so that you will notice
+ when things go wrong. The other levels are probably only of interest if you
+ are hunting down a specific problem. They can produce a hell of an output
+ (especially 16).
+
+ The reporting of fatal errors (i.e. ones which crash Privoxy) is always on
+ and cannot be disabled.
+
+ If you want to use CLF (Common Log Format), you should set "debug 512" ONLY
+ and not enable anything else.
+
+-------------------------------------------------------------------------------
+
+5.3.3.2. single-threaded
+
+Specifies:
+
+ Whether to run only one server thread
+
+Type of value:
+
+ None
+
+Default value:
+
+ Unset
+
+Effect if unset:
+
+ Multi-threaded (or, where unavailable: forked) operation, i.e. the ability
+ to serve multiple requests simultaneously.
+
+Notes:
+
+ This option is only there for debug purposes and you should never need to
+ use it. It will drastically reduce performance.
+
+-------------------------------------------------------------------------------
+
+5.3.4. Access Control and Security
+
+This section of the config file controls the security-relevant aspects of
+Privoxy's configuration.
+
+-------------------------------------------------------------------------------
+
+5.3.4.1. listen-address
+
+Specifies:
+
+ The IP address and TCP port on which Privoxy will listen for client
+ requests.
+
+Type of value:
+
+ [IP-Address]:Port
+
+Default value:
+
+ localhost:8118
+
+Effect if unset:
+
+ Bind to localhost (127.0.0.1), port 8118. This is suitable and recommended
+ for home users who run Privoxy on the same machine as their browser.
+
+Notes:
+
+ You will need to configure your browser(s) to this proxy address and port.
+
+ If you already have another service running on port 8118, or if you want to
+ serve requests from other machines (e.g. on your local network) as well,
+ you will need to override the default.
+
+ If you leave out the IP address, Privoxy will bind to all interfaces
+ (addresses) on your machine and may become reachable from the Internet. In
+ that case, consider using access control lists (ACL's) (see "ACLs" below),
+ or a firewall.
+
+Example:
+
+ Suppose you are running Privoxy on a machine which has the address
+ 192.168.0.1 on your local private network (192.168.0.0) and has another
+ outside connection with a different address. You want it to serve requests
+ from inside only:
+
+ listen-address 192.168.0.1:8118
+
+
+-------------------------------------------------------------------------------
+
+5.3.4.2. toggle
+
+Specifies:
+
+ Initial state of "toggle" status
+
+Type of value:
+
+ 1 or 0
+
+Default value:
+
+ 1
+
+Effect if unset:
+
+ Act as if toggled on
+
+Notes:
+
+ If set to 0, Privoxy will start in "toggled off" mode, i.e. behave like a
+ normal, content-neutral proxy. See enable-remote-toggle below. This is not
+ really useful anymore, since toggling is much easier via the web interface
+ then via editing the conf file.
+
+ The windows version will only display the toggle icon in the system tray if
+ this option is present.
+
+-------------------------------------------------------------------------------
+
+5.3.4.3. enable-remote-toggle
+
+Specifies:
+
+ Whether or not the web-based toggle feature may be used
+
+Type of value:
+
+ 0 or 1
+
+Default value:
+
+ 1
+
+Effect if unset:
+
+ The web-based toggle feature is disabled.
+
+Notes:
+
+ When toggled off, Privoxy acts like a normal, content-neutral proxy, i.e.
+ it acts as if none of the actions applied to any URL.
+
+ For the time being, access to the toggle feature can not be controlled
+ separately by "ACLs" or HTTP authentication, so that everybody who can
+ access Privoxy (see "ACLs" and listen-address above) can toggle it for all
+ users. So this option is not recommended for multi-user environments with
+ untrusted users.
+
+ Note that you must have compiled Privoxy with support for this feature,
+ otherwise this option has no effect.
+
+-------------------------------------------------------------------------------
+
+5.3.4.4. enable-edit-actions
+
+Specifies:
+
+ Whether or not the web-based actions file editor may be used
+
+Type of value:
+
+ 0 or 1
+
+Default value:
+
+ 1
+
+Effect if unset:
+
+ The web-based actions file editor is disabled.
+
+Notes:
+
+ For the time being, access to the editor can not be controlled separately
+ by "ACLs" or HTTP authentication, so that everybody who can access Privoxy
+ (see "ACLs" and listen-address above) can modify its configuration for all
+ users. So this option is not recommended for multi-user environments with
+ untrusted users.
+
+ Note that you must have compiled Privoxy with support for this feature,
+ otherwise this option has no effect.
+
+-------------------------------------------------------------------------------
+
+5.3.4.5. ACLs: permit-access and deny-access
+
+Specifies:
+
+ Who can access what.
+
+Type of value:
+
+ src_addr[/src_masklen] [dst_addr[/dst_masklen]]
+
+ Where src_addr and dst_addr are IP addresses in dotted decimal notation or
+ valid DNS names, and src_masklen and dst_masklen are subnet masks in CIDR
+ notation, i.e. integer values from 2 to 30 representing the length (in
+ bits) of the network address. The masks and the whole destination part are
+ optional.
+
+Default value:
+
+ Unset
+
+Effect if unset:
+
+ Don't restrict access further than implied by listen-address
+
+Notes:
+
+ Access controls are included at the request of ISPs and systems
+ administrators, and are not usually needed by individual users. For a
+ typical home user, it will normally suffice to ensure that Privoxy only
+ listens on the localhost or internal (home) network address by means of the
+ listen-address option.
+
+ Please see the warnings in the FAQ that this proxy is not intended to be a
+ substitute for a firewall or to encourage anyone to defer addressing basic
+ security weaknesses.
+
+ Multiple ACL lines are OK. If any ACLs are specified, then the Privoxy
+ talks only to IP addresses that match at least one permit-access line and
+ don't match any subsequent deny-access line. In other words, the last match
+ wins, with the default being deny-access.
+
+ If Privoxy is using a forwarder (see forward below) for a particular
+ destination URL, the dst_addr that is examined is the address of the
+ forwarder and NOT the address of the ultimate target. This is necessary
+ because it may be impossible for the local Privoxy to determine the IP
+ address of the ultimate target (that's often what gateways are used for).
+
+ You should prefer using IP addresses over DNS names, because the address
+ lookups take time. All DNS names must resolve! You can not use domain
+ patterns like "*.org" or partial domain names. If a DNS name resolves to
+ multiple IP addresses, only the first one is used.
+
+ Denying access to particular sites by ACL may have undesired side effects
+ if the site in question is hosted on a machine which also hosts other
+ sites.
+
+Examples:
+
+ Explicitly define the default behavior if no ACL and listen-address are
+ set: "localhost" is OK. The absence of a dst_addr implies that all
+ destination addresses are OK:
+
+ permit-access localhost
+
+
+ Allow any host on the same class C subnet as www.privoxy.org access to
+ nothing but www.example.com:
+
+ permit-access www.privoxy.org/24 www.example.com/32
+
+
+ Allow access from any host on the 26-bit subnet 192.168.45.64 to anywhere,
+ with the exception that 192.168.45.73 may not access
+ www.dirty-stuff.example.com:
+
+ permit-access 192.168.45.64/26
+ deny-access 192.168.45.73 www.dirty-stuff.example.com
+
+
+-------------------------------------------------------------------------------
+
+5.3.4.6. buffer-limit
+
+Specifies:
+
+ Maximum size of the buffer for content filtering.
+
+Type of value:
+
+ Size in Kbytes
+
+Default value:
+
+ 4096
+
+Effect if unset:
+
+ Use a 4MB (4096 KB) limit.
+
+Notes:
+
+ For content filtering, i.e. the +filter and +deanimate-gif actions, it is
+ necessary that Privoxy buffers the entire document body. This can be
+ potentially dangerous, since a server could just keep sending data
+ indefinitely and wait for your RAM to exhaust -- with nasty consequences.
+ Hence this option.
+
+ When a document buffer size reaches the buffer-limit, it is flushed to the
+ client unfiltered and no further attempt to filter the rest of the document
+ is made. Remember that there may be multiple threads running, which might
+ require up to buffer-limit Kbytes each, unless you have enabled
+ "single-threaded" above.
+
+-------------------------------------------------------------------------------
+
+5.3.5. Forwarding
+
+This feature allows routing of HTTP requests through a chain of multiple
+proxies. It can be used to better protect privacy and confidentiality when
+accessing specific domains by routing requests to those domains through an
+anonymous public proxy (see e.g. http://www.multiproxy.org/anon_list.htm) Or to
+use a caching proxy to speed up browsing. Or chaining to a parent proxy may be
+necessary because the machine that Privoxy runs on has no direct Internet
+access.
+
+Also specified here are SOCKS proxies. Privoxy supports the SOCKS 4 and SOCKS
+4A protocols.
+
+-------------------------------------------------------------------------------
+
+5.3.5.1. forward
+
+Specifies:
+
+ To which parent HTTP proxy specific requests should be routed.
+
+Type of value:
+
+ target_domain[:port] http_parent[/port]
+
+ Where target_domain is a domain name pattern (see the chapter on domain
+ matching in the default.action file), http_parent is the address of the
+ parent HTTP proxy as an IP addresses in dotted decimal notation or as a
+ valid DNS name (or "." to denote "no forwarding", and the optional port
+ parameters are TCP ports, i.e. integer values from 1 to 64535
+
+Default value:
+
+ Unset
+
+Effect if unset:
+
+ Don't use parent HTTP proxies.
+
+Notes:
+
+ If http_parent is ".", then requests are not forwarded to another HTTP
+ proxy but are made directly to the web servers.
+
+ Multiple lines are OK, they are checked in sequence, and the last match
+ wins.
+
+Examples:
+
+ Everything goes to an example anonymizing proxy, except SSL on port 443
+ (which it doesn't handle):
+
+ forward .* anon-proxy.example.org:8080
+ forward :443 .
+
+
+ Everything goes to our example ISP's caching proxy, except for requests to
+ that ISP's sites:
+
+ forward .*. caching-proxy.example-isp.net:8000
+ forward .example-isp.net .
+
+
+-------------------------------------------------------------------------------
+
+5.3.5.2. forward-socks4 and forward-socks4a
+
+Specifies:
+
+ Through which SOCKS proxy (and to which parent HTTP proxy) specific
+ requests should be routed.
+
+Type of value:
+
+ target_domain[:port] socks_proxy[/port] http_parent[/port]
+
+ Where target_domain is a domain name pattern (see the chapter on domain
+ matching in the default.action file), http_parent and socks_proxy are IP
+ addresses in dotted decimal notation or valid DNS names (http_parent may be
+ "." to denote "no HTTP forwarding"), and the optional port parameters are
+ TCP ports, i.e. integer values from 1 to 64535
+
+Default value:
+
+ Unset
+
+Effect if unset:
+
+ Don't use SOCKS proxies.
+
+Notes:
+
+ Multiple lines are OK, they are checked in sequence, and the last match
+ wins.
+
+ The difference between forward-socks4 and forward-socks4a is that in the
+ SOCKS 4A protocol, the DNS resolution of the target hostname happens on the
+ SOCKS server, while in SOCKS 4 it happens locally.
+
+ If http_parent is ".", then requests are not forwarded to another HTTP
+ proxy but are made (HTTP-wise) directly to the web servers, albeit through
+ a SOCKS proxy.
+
+Examples:
+
+ From the company example.com, direct connections are made to all "internal"
+ domains, but everything outbound goes through their ISP's proxy by way of
+ example.com's corporate SOCKS 4A gateway to the Internet.
+
+ forward-socks4a .*. socks-gw.example.com:1080 www-cache.example-isp.net:8080
+ forward .example.com .
+
+
+ A rule that uses a SOCKS 4 gateway for all destinations but no HTTP parent
+ looks like this:
+
+ forward-socks4 .*. socks-gw.example.com:1080 .
+
+
+-------------------------------------------------------------------------------
+
+5.3.5.3. Advanced Forwarding Examples
+
+If you have links to multiple ISPs that provide various special content only to
+their subscribers, you can configure multiple Privoxies which have connections
+to the respective ISPs to act as forwarders to each other, so that your users
+can see the internal content of all ISPs.
+
+Assume that host-a has a PPP connection to isp-a.net. And host-b has a PPP
+connection to isp-b.net. Both run Privoxy. Their forwarding configuration can
+look like this:
+
+host-a:
+
+ forward .*. .
+ forward .isp-b.net host-b:8118
+
+
+host-b:
+
+ forward .*. .
+ forward .isp-a.net host-a:8118
+
+
+Now, your users can set their browser's proxy to use either host-a or host-b
+and be able to browse the internal content of both isp-a and isp-b.
+
+If you intend to chain Privoxy and squid locally, then chain as browser ->
+squid -> privoxy is the recommended way.
+
+Assuming that Privoxy and squid run on the same box, your squid configuration
+could then look like this:
+
+ # Define Privoxy as parent proxy (without ICP)
+ cache_peer 127.0.0.1 parent 8118 7 no-query
+
+ # Define ACL for protocol FTP
+ acl ftp proto FTP
+
+ # Do not forward FTP requests to Privoxy
+ always_direct allow ftp
+
+ # Forward all the rest to Privoxy
+ never_direct allow all
+
+
+You would then need to change your browser's proxy settings to squid's address
+and port. Squid normally uses port 3128. If unsure consult http_port in
+squid.conf.
+
+-------------------------------------------------------------------------------
+
+5.3.6. Windows GUI Options
+
+Privoxy has a number of options specific to the Windows GUI interface:
+
+If "activity-animation" is set to 1, the Privoxy icon will animate when
+"Privoxy" is active. To turn off, set to 0.
+
+ activity-animation 1
+
+
+If "log-messages" is set to 1, Privoxy will log messages to the console window:
+
+ log-messages 1
+
+
+If "log-buffer-size" is set to 1, the size of the log buffer, i.e. the amount
+of memory used for the log messages displayed in the console window, will be
+limited to "log-max-lines" (see below).
+
+Warning: Setting this to 0 will result in the buffer to grow infinitely and eat
+up all your memory!
+
+ log-buffer-size 1
+
+
+log-max-lines is the maximum number of lines held in the log buffer. See above.
+
+ log-max-lines 200
+
+
+If "log-highlight-messages" is set to 1, Privoxy will highlight portions of the
+log messages with a bold-faced font:
+
+ log-highlight-messages 1
+
+
+The font used in the console window:
+
+ log-font-name Comic Sans MS
+
+
+Font size used in the console window:
+
+ log-font-size 8
+
+
+"show-on-task-bar" controls whether or not Privoxy will appear as a button on
+the Task bar when minimized:
+
+ show-on-task-bar 0
+
+
+If "close-button-minimizes" is set to 1, the Windows close button will minimize
+Privoxy instead of closing the program (close with the exit option on the File
+menu).
+
+ close-button-minimizes 1
+
+
+The "hide-console" option is specific to the MS-Win console version of Privoxy.
+If this option is used, Privoxy will disconnect from and hide the command
+console.
+
+ #hide-console
+
+
+-------------------------------------------------------------------------------
+
+5.4. Actions Files
+
+The actions files are used to define what actions Privoxy takes for which URLs,
+and thus determines how ad images, cookies and various other aspects of HTTP
+content and transactions are handled, and on which sites (or even parts
+thereof). There are three such files included with Privoxy, with slightly
+different purposes. default.action sets the default policies. standard.action
+is used by Privoxy and the web based editor to set pre-defined values (and
+normally should not be edited). Local exceptions are best done in user.action.
+The content of these can all be viewed and edited from http://
+config.privoxy.org/show-status.
+
+Anything you want can blocked, including ads, banners, or just some obnoxious
+URL that you would rather not see is done here. Cookies can be accepted or
+rejected, or accepted only during the current browser session (i.e. not written
+to disk), content can be modified, JavaScripts tamed, user-tracking fooled, and
+much more. See below for a complete list of available actions.
+
+An actions file typically has sections. Near the top, "aliases" are optionally
+defined (discussed below), then the default set of rules which will apply
+universally to all sites and pages. And then below that, exceptions to the
+defined universal policies.
+
+-------------------------------------------------------------------------------
+
+5.4.1. Finding the Right Mix
+
+Note that some actions like cookie suppression or script disabling may render
+some sites unusable, which rely on these techniques to work properly. Finding
+the right mix of actions is not easy and certainly a matter of personal taste.
+In general, it can be said that the more "aggressive" your default settings (in
+the top section of the actions file) are, the more exceptions for "trusted"
+sites you will have to make later. If, for example, you want to kill popup
+windows per default, you'll have to make exceptions from that rule for sites
+that you regularly use and that require popups for actually useful content,
+like maybe your bank, favorite shop, or newspaper.
+
+We have tried to provide you with reasonable rules to start from in the
+distribution actions files. But there is no general rule of thumb on these
+things. There just are too many variables, and sites are constantly changing.
+Sooner or later you will want to change the rules (and read this chapter again
+:).
+
+-------------------------------------------------------------------------------
+
+5.4.2. How to Edit
+
+The easiest way to edit the "actions" files is with a browser by using our
+browser-based editor, which can be reached from http://config.privoxy.org/
+show-status.
+
+If you prefer plain text editing to GUIs, you can of course also directly edit
+the the actions files.
+
+-------------------------------------------------------------------------------
+
+5.4.3. How Actions are Applied to URLs
+
+Actions files are divided into sections. There are special sections, like the "
+alias" sections which will be discussed later. For now let's concentrate on
+regular sections: They have a heading line (often split up to multiple lines
+for readability) which consist of a list of actions, separated by whitespace
+and enclosed in curly braces. Below that, there is a list of URL patterns, each
+on a separate line.
+
+To determine which actions apply to a request, the URL of the request is
+compared to all patterns in this file. Every time it matches, the list of
+applicable actions for the URL is incrementally updated, using the heading of
+the section in which the pattern is located. If multiple matches for the same
+URL set the same action differently, the last match wins. If not, the effects
+are aggregated (e.g. a URL might match both the "+handle-as-image" and "+block"
+actions).
+
+You can trace this process by visiting http://config.privoxy.org/show-url-info.
+
+More detail on this is provided in the Appendix, Anatomy of an Action.
+
+-------------------------------------------------------------------------------
+
+5.4.4. Patterns
+
+Generally, a pattern has the form <domain>/<path>, where both the <domain> and
+<path> are optional. (This is why the pattern / matches all URLs).
+
+www.example.com/
+
+ is a domain-only pattern and will match any request to www.example.com,
+ regardless of which document on that server is requested.
+
+www.example.com
+
+ means exactly the same. For domain-only patterns, the trailing / may be
+ omitted.
+
+www.example.com/index.html
+
+ matches only the single document /index.html on www.example.com.
+
+/index.html
+
+ matches the document /index.html, regardless of the domain, i.e. on any web
+ server.
+
+index.html
+
+ matches nothing, since it would be interpreted as a domain name and there
+ is no top-level domain called .html.
+
+-------------------------------------------------------------------------------
+
+5.4.4.1. The Domain Pattern
+
+The matching of the domain part offers some flexible options: if the domain
+starts or ends with a dot, it becomes unanchored at that end. For example:
+
+.example.com
+
+ matches any domain that ENDS in .example.com
+
+www.
+
+ matches any domain that STARTS with www.
+
+.example.
+
+ matches any domain that CONTAINS .example. (Correctly speaking: It matches
+ any FQDN that contains example as a domain.)
+
+Additionally, there are wild-cards that you can use in the domain names
+themselves. They work pretty similar to shell wild-cards: "*" stands for zero
+or more arbitrary characters, "?" stands for any single character, you can
+define character classes in square brackets and all of that can be freely
+mixed:
+
+ad*.example.com
+
+ matches "adserver.example.com", "ads.example.com", etc but not
+ "sfads.example.com"
+
+*ad*.example.com
+
+ matches all of the above, and then some.
+
+.?pix.com
+
+ matches www.ipix.com, pictures.epix.com, a.b.c.d.e.upix.com etc.
+
+www[1-9a-ez].example.c*
+
+ matches www1.example.com, www4.example.cc, wwwd.example.cy,
+ wwwz.example.com etc., but not wwww.example.com.
+
+-------------------------------------------------------------------------------
+
+5.4.4.2. The Path Pattern
+
+Privoxy uses Perl compatible regular expressions (through the PCRE library) for
+matching the path.
+
+There is an Appendix with a brief quick-start into regular expressions, and
+full (very technical) documentation on PCRE regex syntax is available on-line
+at http://www.pcre.org/man.txt. You might also find the Perl man page on
+regular expressions (man perlre) useful, which is available on-line at http://
+www.perldoc.com/perl5.6/pod/perlre.html.
+
+Note that the path pattern is automatically left-anchored at the "/", i.e. it
+matches as if it would start with a "^" (regular expression speak for the
+beginning of a line).
+
+Please also note that matching in the path is case INSENSITIVE by default, but
+you can switch to case sensitive at any point in the pattern by using the "(?
+-i)" switch: www.example.com/(?-i)PaTtErN.* will match only documents whose
+path starts with PaTtErN in exactly this capitalization.
+
+-------------------------------------------------------------------------------
+
+5.4.5. Actions
+
+All actions are disabled by default, until they are explicitly enabled
+somewhere in an actions file. Actions are turned on if preceded with a "+", and
+turned off if preceded with a "-". So a "+action" means "do that action", e.g.
+"+block" means please "block the following URL patterns".
+
+Actions are invoked by enclosing the action name in curly braces (e.g.
+{+some_action}), followed by a list of URLs (or patterns that match URLs) to
+which the action applies. There are three classes of actions:
+
+ * Boolean, i.e the action can only be "on" or "off". Examples: