+Privoxy User Manual
+
+Copyright © 2001, 2002 by Privoxy Developers
+
+$Id: user-manual.sgml,v 1.111 2002/05/14 23:01:36 oes Exp $
+
+The user manual gives users information on how to install, configure and use
+Privoxy.
+
+Privoxy is a web proxy with advanced filtering capabilities for protecting
+privacy, filtering web page content, managing cookies, controlling access, and
+removing ads, banners, pop-ups and other obnoxious Internet junk. Privoxy has a
+very flexible configuration and can be customized to suit individual needs and
+tastes. Privoxy has application for both stand-alone systems and multi-user
+networks.
+
+Privoxy is based on Internet Junkbuster (tm).
+
+You can find the latest version of the user manual at http://www.privoxy.org/
+user-manual/. Please see the Contact section on how to contact the developers.
+
+-------------------------------------------------------------------------------
+
+Table of Contents
+1. Introduction
+
+ 1.1. Features
+
+2. Installation
+
+ 2.1. Binary Packages
+
+ 2.1.1. Red Hat, SuSE RPMs and Conectiva
+ 2.1.2. Debian
+ 2.1.3. Windows
+ 2.1.4. Solaris, NetBSD, FreeBSD, HP-UX
+ 2.1.5. OS/2
+ 2.1.6. Max OSX
+ 2.1.7. AmigaOS
+
+ 2.2. Building from Source
+
+3. Note to Upgraders
+4. Quickstart to Using Privoxy
+5. Starting Privoxy
+
+ 5.1. RedHat, Conectiva and Debian
+ 5.2. SuSE
+ 5.3. Windows
+ 5.4. Solaris, NetBSD, FreeBSD, HP-UX and others
+ 5.5. OS/2
+ 5.6. MAX OSX
+ 5.7. AmigaOS
+ 5.8. Command Line Options
+
+6. Privoxy Configuration
+
+ 6.1. Controlling Privoxy with Your Web Browser
+ 6.2. Configuration Files Overview
+
+7. The Main Configuration File
+
+ 7.1. Configuration and Log File Locations
+
+ 7.1.1. confdir
+ 7.1.2. logdir
+ 7.1.3. actionsfile
+ 7.1.4. filterfile
+ 7.1.5. logfile
+ 7.1.6. jarfile
+ 7.1.7. trustfile
+
+ 7.2. Local Set-up Documentation
+
+ 7.2.1. user-manual
+ 7.2.2. trust-info-url
+ 7.2.3. admin-address
+ 7.2.4. proxy-info-url
+
+ 7.3. Debugging
+
+ 7.3.1. debug
+ 7.3.2. single-threaded
+
+ 7.4. Access Control and Security
+
+ 7.4.1. listen-address
+ 7.4.2. toggle
+ 7.4.3. enable-remote-toggle
+ 7.4.4. enable-edit-actions
+ 7.4.5. ACLs: permit-access and deny-access
+ 7.4.6. buffer-limit
+
+ 7.5. Forwarding
+
+ 7.5.1. forward
+ 7.5.2. forward-socks4 and forward-socks4a
+ 7.5.3. Advanced Forwarding Examples
+
+ 7.6. Windows GUI Options
+
+8. Actions Files
+
+ 8.1. Finding the Right Mix
+ 8.2. How to Edit
+ 8.3. How Actions are Applied to URLs
+ 8.4. Patterns
+
+ 8.4.1. The Domain Pattern
+ 8.4.2. The Path Pattern
+
+ 8.5. Actions
+
+ 8.5.1. add-header
+ 8.5.2. block
+ 8.5.3. crunch-incoming-cookies
+ 8.5.4. crunch-outgoing-cookies
+ 8.5.5. deanimate-gifs
+ 8.5.6. downgrade-http-version
+ 8.5.7. fast-redirects
+ 8.5.8. filter
+ 8.5.9. handle-as-image
+ 8.5.10. hide-forwarded-for-headers
+ 8.5.11. hide-from-header
+ 8.5.12. hide-referrer
+ 8.5.13. hide-user-agent
+ 8.5.14. kill-popups
+ 8.5.15. limit-connect
+ 8.5.16. prevent-compression
+ 8.5.17. send-vanilla-wafer
+ 8.5.18. send-wafer
+ 8.5.19. session-cookies-only
+ 8.5.20. set-image-blocker
+ 8.5.21. Summary
+
+ 8.6. Aliases
+ 8.7. Sample Actions Files
+
+9. The Filter File
+
+ 9.1. The +filter Action
+
+10. Templates
+11. Contacting the Developers, Bug Reporting and Feature Requests
+
+ 11.1. Get Support
+ 11.2. Report bugs
+ 11.3. Request new features
+ 11.4. Report ads or other filter problems
+ 11.5. Other
+
+12. Privoxy Copyright, License and History
+
+ 12.1. License
+ 12.2. History
+
+13. See Also
+14. Appendix
+
+ 14.1. Regular Expressions
+ 14.2. Privoxy's Internal Pages
+
+ 14.2.1. Bookmarklets
+
+ 14.3. Chain of Events
+ 14.4. Anatomy of an Action
+
+1. Introduction
+
+This documentation is included with the current beta version of Privoxy,
+v.2.9.15, 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. 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.
+
+ * Web page content filtering (removes banners based on size, invisible
+ "web-bugs", JavaScript and HTML annoyances, pop-up windows, etc.)
+
+ * Modularized configuration that allows for standard settings and user
+ settings to reside in separate files, so that installing updated actions
+ files won't overwrite individual user settings.
+
+ * 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.
+
+ * Improved cookie management features (e.g. session based cookies).
+
+ * GIF de-animation.
+
+ * Bypass many click-tracking scripts (avoids script redirection).
+
+ * Multi-threaded (POSIX and native threads).
+
+ * User-customizable HTML templates for all proxy-generated pages (e.g.
+ "blocked" page).
+
+ * Auto-detection and re-reading of config file changes.
+
+ * Improved signal handling, and a true daemon mode (Unix).
+
+ * 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.
+
+-------------------------------------------------------------------------------
+
+2. 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.
+
+Note: If you have a previous Junkbuster or Privoxy installation on your system,
+you will need to remove it. On some platforms, this may be done 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 section below.
+
+-------------------------------------------------------------------------------
+
+2.1. Binary Packages
+
+How to install the binary packages depends on your operating system:
+
+-------------------------------------------------------------------------------
+
+2.1.1. Red Hat, SuSE RPMs and Conectiva
+
+RPMs can be installed with rpm -Uvh privoxy-2.9.15-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 methods. Note
+that SuSE will automatically start Privoxy in the boot process.
+
+If you have problems with failed dependencies, try rebuilding the SRC RPM: rpm
+--rebuild privoxy-2.9.15-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.
+
+-------------------------------------------------------------------------------
+
+2.1.2. Debian
+
+FIXME.
+
+-------------------------------------------------------------------------------
+
+2.1.3. Windows
+
+Just double-click the installer, which will guide you through the installation
+process. You will find the configuration files in the same directory as you
+installed Privoxy in. We do not use the registry of Windows.
+
+-------------------------------------------------------------------------------
+
+2.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.
+
+-------------------------------------------------------------------------------
+
+2.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.
+
+-------------------------------------------------------------------------------
+
+2.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.
+
+-------------------------------------------------------------------------------
+
+2.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).
+
+-------------------------------------------------------------------------------
+
+2.2. Building from Source
+
+The most convenient way to obtain the Privoxy sources is to download the source
+tarball from our 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.
+
+To build Privoxy from source, autoconf, GNU make (gmake), and, of course, a C
+compiler like gcc are required.
+
+When building from a source tarball (either release version or nightly CVS
+tarball), first unpack the source:
+
+ tar xzvf privoxy-2.9.15-beta-src* [.tgz or .tar.gz]
+ cd privoxy-2.9.15-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.
+
+-------------------------------------------------------------------------------
+
+3. Note to Upgraders
+
+There are very significant changes from earlier Junkbuster versions to the
+current Privoxy. The number, names, syntax, and purposes of configuration files
+have substantially changed. Junkbuster 2.0.x configuration files will not
+migrate, Junkbuster 2.9.x and Privoxy configurations will need to be ported.
+The functionalities 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. Quickstart to Using Privoxy
+
+ * If upgrading, please back up any configuration files. See the Note to
+ Upgraders Section.
+
+ * Install Privoxy. See the Installation Section for platform specific
+ information.
+
+ * Start Privoxy, if the installation program has not done this already. See
+ the section Starting Privoxy.
+
+ * Set your browser to use Privoxy as HTTP and HTTPS proxy by setting the
+ proxy configuration for address of 127.0.0.1 and port 8118. (Junkbuster and
+ earlier versions of Privoxy used port 8000.) See the section Starting
+ Privoxy.
+
+ * Flush your browser's caches, to remove any cached ad images.
+
+ * Enjoy surfing with enhanced comfort and privacy. You may want to customize
+ the user.action file to personalize your new browsing experience. See the
+ Configuration section for more configuration options, and how to further
+ customize your installation.
+
+ * If you experience problems with sites that "misbehave", see the Anatomy of
+ an Action section in the Appendix.
+
+ * Please see the section Contacting the Developers on how to report bugs or
+ problems with websites or to get help.
+
+-------------------------------------------------------------------------------
+
+5. 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 127.0.0.1
+(or 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: 127.0.0.1, 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. 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.
+
+-------------------------------------------------------------------------------
+
+5.1. RedHat, Conectiva and Debian
+
+We use a script. Note that RedHat does not start Privoxy upon booting per
+default. It will use the file /etc/privoxy/config as its main configuration
+file. FIXME: Debian??
+
+ # /etc/rc.d/init.d/privoxy start
+
+-------------------------------------------------------------------------------
+
+5.2. SuSE
+
+We use a script. It will use the file /etc/privoxy/config as its main
+configuration file. Note that SuSE starts Privoxy upon booting your PC.
+
+ # rcprivoxy start
+
+-------------------------------------------------------------------------------
+
+5.3. Windows
+
+Click on the Privoxy Icon to start Privoxy. If no configuration file is
+specified on the command line, Privoxy will look for a file named config.txt.
+Note that Windows will automatically start Privoxy upon booting you PC.
+
+-------------------------------------------------------------------------------
+
+5.4. Solaris, NetBSD, FreeBSD, HP-UX and others
+
+Example Unix startup command:
+
+ # /usr/sbin/privoxy /etc/privoxy/config
+
+-------------------------------------------------------------------------------
+
+5.5. OS/2
+
+FIXME.
+
+-------------------------------------------------------------------------------
+
+5.6. MAX OSX
+
+FIXME.
+
+-------------------------------------------------------------------------------
+
+5.7. AmigaOS
+
+FIXME.
+
+-------------------------------------------------------------------------------
+
+5.8. 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.
+
+-------------------------------------------------------------------------------
+
+6. 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.
+
+-------------------------------------------------------------------------------
+
+6.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 files, 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 manipulation is disabled, i.e. Privoxy acts like a
+normal forwarding proxy. There is even a toggle Bookmarklet offered, so that
+you can toggle Privoxy with one click from your browser.
+
+-------------------------------------------------------------------------------
+
+6.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 which "actions"
+ relating to banner-blocking, images, pop-ups, content modification, cookie
+ handling etc should be applied by default. It also defines many exceptions
+ (both positive and negative) from this default set of actions that enable
+ Privoxy to selectively eliminate the junk, and only the junk, on as many
+ websites as possible.
+
+ 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 (which you
+ will most probably want to define sooner or later) are probably best
+ applied in user.action, where you can preserve them across upgrades.
+ standard.action is 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.
+
+-------------------------------------------------------------------------------
+
+7. 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).
+
+-------------------------------------------------------------------------------
+
+7.1. Configuration and Log File Locations
+
+Privoxy can (and normally does) use a number of other files for additional
+configuration, help and logging. This section of the configuration file tells
+Privoxy where to find those other files.
+
+The user running Privoxy, must have read permission for all configuration
+files, and write permission to any files that would be modified, such as log
+files.
+
+-------------------------------------------------------------------------------
+
+7.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).
+
+-------------------------------------------------------------------------------
+
+7.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
+
+-------------------------------------------------------------------------------
+
+7.1.3. actionsfile
+
+Specifies:
+
+ The actions file(s) to use
+
+Type of value:
+
+ File name, relative to confdir, without the .action suffix
+
+Default value:
+
+ standard # Internal purposes, no editing recommended
+
+ default # Main actions file
+
+ user # User customizations
+
+Effect if unset:
+
+ No actions are taken at all. Simple neutral proxying.
+
+Notes:
+
+ Multiple actionsfile lines are permitted, 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.
+
+ Actions files are where all the per site and per URL configuration is done
+ for ad blocking, cookie management, privacy considerations, etc. There is
+ no point in using Privoxy without at least one actions file.
+
+-------------------------------------------------------------------------------
+
+7.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 neutral.
+
+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.
+
+-------------------------------------------------------------------------------
+
+7.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.
+
+ Any log files must be writable by whatever user Privoxy is being run as
+ (default on UNIX, user id is "privoxy").
+
+-------------------------------------------------------------------------------
+
+7.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.
+
+-------------------------------------------------------------------------------
+
+7.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.
+
+-------------------------------------------------------------------------------
+
+7.2. Local Set-up Documentation
+
+If you intend to operate Privoxy for more users than 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.
+
+-------------------------------------------------------------------------------
+
+7.2.1. user-manual
+
+Specifies:
+
+ Location of the Privoxy User Manual.
+
+Type of value:
+
+ A fully qualified URI
+
+Default value:
+
+ Unset
+
+Effect if unset:
+
+ http://www.privoxy.org/version/user-manual/ will be used, where version is
+ the Privoxy version.
+
+Notes:
+
+ The User Manual URI is used for help links from some of the internal CGI
+ pages. The manual itself is normally packaged with the binary
+ distributions, so you probably want to set this to a locally installed
+ copy. For multi-user setups, you could provide a copy on a local webserver
+ for all your users and use the corresponding URL here.
+
+ Examples:
+
+ Unix, in local filesystem:
+
+ user-manual file:///usr/share/doc/privoxy-2.9.15/user-manual/
+
+ Any platform, on local webserver (called "local-webserver"):
+
+ user-manual http://local-webserver/privoxy-user-manual/
+
+ +-----------------------------------------------------------------+
+ | Warning |
+ |-----------------------------------------------------------------|
+ |If set, this option should be the first option in the config |
+ |file, because it is used while the config file is being read. |
+ +-----------------------------------------------------------------+
+
+-------------------------------------------------------------------------------
+
+7.2.2. 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!
+
+-------------------------------------------------------------------------------
+
+7.2.3. 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.
+
+-------------------------------------------------------------------------------
+
+7.2.4. 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 ;-)
+
+-------------------------------------------------------------------------------
+
+7.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.
+
+-------------------------------------------------------------------------------
+
+7.3.1. debug
+
+Specifies:
+
+ Key values that determine what information gets logged to the logfile.
+
+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.
+
+-------------------------------------------------------------------------------
+
+7.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.
+
+-------------------------------------------------------------------------------
+
+7.4. Access Control and Security
+
+This section of the config file controls the security-relevant aspects of
+Privoxy's configuration.
+
+-------------------------------------------------------------------------------
+
+7.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:
+
+ 127.0.0.1:8118
+
+Effect if unset:
+
+ Bind to 127.0.0.1 (localhost), 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
+
+-------------------------------------------------------------------------------
+
+7.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 where all ad blocking, filtering, etc are
+ disabled. See enable-remote-toggle below. This is not really useful
+ anymore, since toggling is much easier via the web interface than via
+ editing the conf file.
+
+ The windows version will only display the toggle icon in the system tray if
+ this option is present.
+
+-------------------------------------------------------------------------------