By: Privoxy Developers
-$Id: user-manual.sgml,v 1.60 2002/03/27 01:57:34 hal9 Exp $
+$Id: user-manual.sgml,v 1.61 2002/03/29 01:31:08 hal9 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
2.5. Windows
2.6. Other
-3. Privoxy Configuration
+3. Quickstart to Using Privoxy
- 3.1. Controlling Privoxy with Your Web Browser
- 3.2. Configuration Files Overview
- 3.3. The Main Configuration File
+ 3.1. Command Line Options
+
+4. Privoxy Configuration
+
+ 4.1. Controlling Privoxy with Your Web Browser
+ 4.2. Configuration Files Overview
+ 4.3. The Main Configuration File
- 3.3.1. Defining Other Configuration Files
- 3.3.2. Other Configuration Options
- 3.3.3. Access Control List (ACL)
- 3.3.4. Forwarding
- 3.3.5. Windows GUI Options
+ 4.3.1. Defining Other Configuration Files
+ 4.3.2. Other Configuration Options
+ 4.3.3. Access Control List (ACL)
+ 4.3.4. Forwarding
+ 4.3.5. Windows GUI Options
- 3.4. The Actions File
+ 4.4. The Actions File
- 3.4.1. URL Domain and Path Syntax
- 3.4.2. Actions
- 3.4.3. Aliases
+ 4.4.1. URL Domain and Path Syntax
+ 4.4.2. Actions
+ 4.4.3. Aliases
- 3.5. The Filter File
- 3.6. Templates
-
-4. Quickstart to Using Privoxy
-
- 4.1. Command Line Options
+ 4.5. The Filter File
+ 4.6. Templates
5. Contacting the Developers, Bug Reporting and Feature Requests
6. Copyright and History
8.1. Regular Expressions
8.2. Privoxy's Internal Pages
+
+ 8.2.1. Bookmarklets
+
8.3. Anatomy of an Action
1. Introduction
* 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
and AmigaOS.
-------------------------------------------------------------------------------
-3. Privoxy Configuration
+3. Quickstart to Using Privoxy
+
+Before launching Privoxy for the first time, you will want to configure your
+browser(s) to use Privoxy and the HTTP and HTTPS proxy. The default is
+localhost for the proxy address, and port 8118 (earlier versions used port
+800). This is the one required configuration 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 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
+
+
+
+An init script is provided for SuSE and Redhat.
+
+For for SuSE: /etc/rc.d/privoxy start
+
+For RedHat: /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, though may be somewhat aggressive in blocking junk. 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 that require persistent
+cookies, and add these to default.action as needed. By default, most of these
+will be accepted only during the current browser session, until you add them to
+the configuration. If you want the browser to handle this instead, you will
+need to edit default.action 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.
+
+Privoxy is HTTP/1.1 compliant, but not all 1.1 features are as yet implemented.
+If browsers that support HTTP/1.1 (like Mozilla or recent versions of I.E.)
+experience problems, you might try to force HTTP/1.0 compatibility. For
+Mozilla, look under Edit -> Preferences -> Debug -> Networking. Or set the
+"+downgrade" config option in default.action.
+
+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" (as specified in default.action)
+can be adjusted by pointing your browser to http://p.p/, and then follow the
+link to "edit the actions list". (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 default.action file editor mentioned above, Privoxy can also be turned
+"on" and "off" from this page.
+
+If you encounter problems, please verify it is a Privoxy bug, by disabling
+Privoxy, and then trying the same page. Also, try another browser if possible
+to eliminate browser or site problems. Before reporting it as a bug, see if
+there is not a configuration option that is enabled that is causing the page
+not to load. You can then add an exception for that page or site. For instance,
+try adding it to the {fragile} section of default.action. This will turn off
+most actions for this site. For more on troubleshooting problem sites, see the
+Appendix. If a bug, please report it to the developers (see below).
+
+-------------------------------------------------------------------------------
+
+3.1. Command Line Options
+
+Privoxy may be invoked with the following command-line options:
+
+ * --version
+
+ Print version info and exit, Unix only.
+
+ * --help
+
+ Print a short usage info and exit, Unix only.
+
+ * --no-daemon
+
+ Don't become a daemon, i.e. don't fork and become process group leader,
+ don't detach from controlling tty. Unix only.
+
+ * --pidfile FILE
+
+ On startup, write the process ID to FILE. Delete the FILE on exit. Failiure
+ 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.
+
+-------------------------------------------------------------------------------
+
+4. Privoxy Configuration
All Privoxy configuration is kept in text files. These files can be edited with
a text editor. Many important aspects of Privoxy can also be controlled easily
-------------------------------------------------------------------------------
-3.1. Controlling Privoxy with Your Web Browser
+4.1. Controlling Privoxy with Your Web Browser
Privoxy can be reached by the special URL http://p.p/ (or alternately http://
-www.privoxy.org/config/), which is an internal page. You will see the following
+config.privoxy.org/), which is an internal page. You will see the following
section:
Please choose from the following options:
-------------------------------------------------------------------------------
-3.2. Configuration Files Overview
+4.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
-------------------------------------------------------------------------------
-3.3. The Main Configuration File
+4.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
-------------------------------------------------------------------------------
-3.3.1. Defining Other Configuration Files
+4.3.1. Defining Other Configuration Files
Privoxy can use a number of other files to tell it what ads to block, what
cookies to accept, etc. This section of the configuration file tells Privoxy
-------------------------------------------------------------------------------
-3.3.2. Other Configuration Options
+4.3.2. Other Configuration Options
This part of the configuration file contains options that control how Privoxy
operates.
-------------------------------------------------------------------------------
-3.3.3. Access Control List (ACL)
+4.3.3. Access Control List (ACL)
Access controls are included at the request of some ISPs and systems
administrators, and are not usually needed by individual users. Please note the
-------------------------------------------------------------------------------
-3.3.4. Forwarding
+4.3.4. Forwarding
This feature allows chaining of HTTP requests via multiple proxies. It can be
used to better protect privacy and confidentiality when accessing specific
-------------------------------------------------------------------------------
-3.3.5. Windows GUI Options
+4.3.5. Windows GUI Options
Privoxy has a number of options specific to the Windows GUI interface:
-------------------------------------------------------------------------------
-3.4. The Actions File
+4.4. The Actions File
The "default.action" file (formerly actionsfile or ijb.action) is used to
define what actions Privoxy takes, and thus determines how images, cookies and
-------------------------------------------------------------------------------
-3.4.1. URL Domain and Path Syntax
+4.4.1. URL Domain and Path Syntax
Generally, a pattern has the form <domain>/<path>, where both the <domain> and
<path> part are optional. If you only specify a domain part, the "/" can be
-------------------------------------------------------------------------------
-3.4.2. Actions
+4.4.2. Actions
Actions are enabled if preceded with a "+", and disabled if preceded with a
"-". Actions are invoked by enclosing the action name in curly braces (e.g.
-------------------------------------------------------------------------------
-3.4.3. Aliases
+4.4.3. Aliases
Custom "actions", known to Privoxy as "aliases", can be defined by combining
other "actions". These can in turn be invoked just like the built-in "actions".
-------------------------------------------------------------------------------
-3.5. The Filter File
+4.5. The Filter File
Any web page can be dynamically modified with the filter file. This
modification can be removal, or re-writing, of any web page content, including
-------------------------------------------------------------------------------
-3.6. Templates
+4.6. Templates
When Privoxy displays one of its internal pages, such as a 404 Not Found error
page, it uses the appropriate template. On Linux, BSD, and Unix, these are
-------------------------------------------------------------------------------
-4. Quickstart to Using Privoxy
-
-Install package, then run and enjoy! 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
-
-
-
-An init script is provided for SuSE and Redhat.
-
-For for SuSE: /etc/rc.d/privoxy start
-
-For RedHat: /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.
-
-Be sure your browser is set to use the proxy which is by default at localhost,
-port 8118. 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.
-
-The included default configuration files should give a reasonable starting
-point, though may be somewhat aggressive in blocking junk. You will probably
-want to keep an eye out for sites that require persistent cookies, and add
-these to default.action as needed. By default, most of these will be accepted
-only during the current browser session, until you add them to the
-configuration. If you want the browser to handle this instead, you will need to
-edit default.action 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.
-
-If a particular site shows problems loading properly, try adding it to the
-{fragile} section of default.action. This will turn off most actions for this
-site.
-
-Privoxy is HTTP/1.1 compliant, but not all 1.1 features are as yet implemented.
-If browsers that support HTTP/1.1 (like Mozilla or recent versions of I.E.)
-experience problems, you might try to force HTTP/1.0 compatibility. For
-Mozilla, look under Edit -> Preferences -> Debug -> Networking. Or set the
-"+downgrade" config option in default.action.
-
-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" (as specified in default.action)
-can be adjusted by pointing your browser to http://p.p/, and then follow the
-link to "edit the actions list". (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 default.action file editor mentioned above, Privoxy can also be turned
-"on" and "off" from this page.
-
-If you encounter problems, please verify it is a Privoxy bug, by disabling
-Privoxy, and then trying the same page. Also, try another browser if possible
-to eliminate browser or site problems. Before reporting it as a bug, see if
-there is not a configuration option that is enabled that is causing the page
-not to load. You can then add an exception for that page or site. If a bug,
-please report it to the developers (see below).
-
--------------------------------------------------------------------------------
-
-4.1. Command Line Options
-
-Privoxy may be invoked with the following command-line options:
-
- * --version
-
- Print version info and exit, Unix only.
-
- * --help
-
- Print a short usage info and exit, Unix only.
-
- * --no-daemon
-
- Don't become a daemon, i.e. don't fork and become process group leader,
- don't detach from controlling tty. Unix only.
-
- * --pidfile FILE
-
- On startup, write the process ID to FILE. Delete the FILE on exit. Failiure
- 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.
-
--------------------------------------------------------------------------------
-
5. Contacting the Developers, Bug Reporting and Feature Requests
We value your feedback. However, to provide you with the best support, please
8.2. Privoxy's Internal Pages
Since Privoxy proxies each requested web page, it is easy for Privoxy to trap
-certain URLs. In this way, we can talk directly to Privoxy, and see how it is
-configured, see how our rules are being applied, change these rules and other
-configuration options, and even turn Privoxy's filtering off, all with a web
-browser.
+certain special URLs. In this way, we can talk directly to Privoxy, and see how
+it is configured, see how our rules are being applied, change these rules and
+other configuration options, and even turn Privoxy's filtering off, all with a
+web browser.
The URLs listed below are the special ones that allow direct access to Privoxy.
Of course, Privoxy must be running to access these. If not, you will get a
* Privoxy main page:
- http://www.privoxy.org/config/
+ http://config.privoxy.org/
Alternately, this may be reached at http://p.p/, but this variation may not
work as reliably as the above in some configurations.
* Show information about the current configuration:
- http://www.privoxy.org/config/show-status
+ http://config.privoxy.org/show-status
* Show the source code version numbers:
- http://www.privoxy.org/config/show-version
+ http://config.privoxy.org/show-version
* Show the client's request headers:
- http://www.privoxy.org/config/show-request
+ http://config.privoxy.org/show-request
* Show which actions apply to a URL and why:
- http://www.privoxy.org/config/show-url-info
+ http://config.privoxy.org/show-url-info
- * Toggle Privoxy on or off:
+ * Toggle Privoxy on or off. In this case, "Privoxy" continues to run, but
+ only as a pass-through proxy, with no actions taking place:
- http://www.privoxy.org/config/toggle
+ http://config.privoxy.org/toggle
Short cuts. Turn off, then on:
- http://www.privoxy.org/config/toggle?set=disable
+ http://config.privoxy.org/toggle?set=disable
- http://www.privoxy.org/config/toggle?set=enable
+ http://config.privoxy.org/toggle?set=enable
* Edit the actions list file:
- http://www.privoxy.org/config/edit-actions
+ http://config.privoxy.org/edit-actions
These may be bookmarked for quick reference.
-------------------------------------------------------------------------------
+8.2.1. Bookmarklets
+
+Here are some bookmarklets to allow you to easily access a "mini" version of
+this page. They are designed for MS Internet Explorer, but should work equally
+well in Netscape, Mozilla, and other browsers which support JavaScript. They
+are designed to run directly from your bookmarks - not by clicking the links
+below (although that will work for testing).
+
+To save them, right-click the link and choose "Add to Favorites" (IE) or "Add
+Bookmark" (Netscape). You will get a warning that the bookmark "may not be
+safe" - just click OK. Then you can run the Bookmarklet directly from your
+favourites/bookmarks. For even faster access, you can put them on the "Links"
+bar (IE) or the "Personal Toolbar" (Netscape), and run them with a single
+click.
+
+ * Enable Privoxy
+
+ * Disable Privoxy
+
+ * Toggle Privoxy (Toggles between enabled and disabled)
+
+ * View Privoxy Status
+
+Credit: The site which gave me the general idea for these bookmarklets is
+www.bookmarklets.com. They have more information about bookmarklets.
+
+-------------------------------------------------------------------------------
+
8.3. Anatomy of an Action
The way Privoxy applies "actions" to any given URL can be complex, and not
doing is causing us a problem inadvertantly. It can be a little daunting to
look at the actions files themselves, since they tend to be filled with
"regular expressions" whose consequences are not always so obvious. Privoxy
-provides the http://www.privoxy.org/config/show-url-info page that can show us
-very specifically how actions are being applied to any given URL. This is a big
-help for troubleshooting.
+provides the http://config.privoxy.org/show-url-info page that can show us very
+specifically how actions are being applied to any given URL. This is a big help
+for troubleshooting.
First, enter one URL (or partial URL) at the prompt, and then Privoxy will tell
us how the current configuration will handle it. This will not help with
projects / privoxy.git / blobdiff