- The default actions setting is now <literal>Cautious</literal>. Previous
- releases had a default setting of <literal>Medium</literal>. Experienced
- users may want to adjust this, as it is fairly conservative by &my-app;
- standards and past practices. See <ulink
- url="http://config.privoxy.org/edit-actions-list?f=default">
- http://config.privoxy.org/edit-actions-list?f=default</ulink>. New users
- should try the default settings for a while before turning up the volume.
- </para>
- </listitem>
-
- <listitem>
- <para>
- The default setting has filtering turned <emphasis>off</emphasis>, which
- subsequently means that compression is <emphasis>on</emphasis>. Remember
- that filtering does not work on compressed pages, so if you use, or want to
- use, filtering, you will need to force compression off. Example:
- </para>
- <para>
- <screen>
- { +<link linkend="filter">filter</link>{google} +<link linkend="prevent-compression">prevent-compression</link> }
- .google.</screen>
- </para>
- <para>
- Or if you use a number of filters, or filter many sites, you may just want
- to turn off compression for all sites in
- <filename>default.action</filename> (or
- <filename>user.action</filename>).
- </para>
-
- </listitem>
-
- <listitem>
- <para>
- Also, <link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> is
- off by default now. If you've liked this feature in the past, you may want
- to turn it back on in <filename>user.action</filename> now.
- </para>
- </listitem>
-
-
- <listitem>
- <para>
- Some installers may not automatically start
- <application>Privoxy</application> after installation.
- </para>
- </listitem>
--->
-
- </itemizedlist>
-</para>
-
-</sect2>
-</sect1>
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="quickstart"><title>Quickstart to Using Privoxy</title>
-<para>
- <itemizedlist>
-
- <listitem>
- <para>
- Install <application>Privoxy</application>. See the <link
- linkend="installation">Installation Section</link> below for platform specific
- information.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Advanced users and those who want to offer <application>Privoxy</application>
- service to more than just their local machine should check the <link
- linkend="config">main config file</link>, especially the <link
- linkend="access-control">security-relevant</link> options. These are
- off by default.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Start <application>Privoxy</application>, if the installation program has
- not done this already (may vary according to platform). See the section
- <link linkend="startup">Starting <application>Privoxy</application></link>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Set your browser to use <application>Privoxy</application> as HTTP and
- HTTPS (SSL) <ulink url="http://en.wikipedia.org/wiki/Proxy_server">proxy</ulink>
- by setting the proxy configuration for address of
- <literal>127.0.0.1</literal> and port <literal>8118</literal>.
- <emphasis>DO NOT</emphasis> activate proxying for <literal>FTP</literal> or
- any protocols besides HTTP and HTTPS (SSL) unless you intend to prevent your
- browser from using these protocols.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Flush your browser's disk and memory caches, to remove any cached ad images.
- If using <application>Privoxy</application> to manage
- <ulink url="http://en.wikipedia.org/wiki/Browser_cookie">cookies</ulink>,
- you should remove any currently stored cookies too.
- </para>
- </listitem>
-
- <listitem>
- <para>
- A default installation should provide a reasonable starting point for
- most. There will undoubtedly be occasions where you will want to adjust the
- configuration, but that can be dealt with as the need arises. Little
- to no initial configuration is required in most cases, you may want
- to enable the
- <ulink url="config.html#ENABLE-EDIT-ACTIONS">web-based action editor</ulink> though.
- Be sure to read the warnings first.
- </para>
- <para>
- See the <link linkend="configuration">Configuration section</link> for more
- configuration options, and how to customize your installation.
- You might also want to look at the <link
- linkend="quickstart-ad-blocking">next section</link> for a quick
- introduction to how <application>Privoxy</application> blocks ads and
- banners.
-</para>
- </listitem>
-
- <listitem>
- <para>
- If you experience ads that slip through, innocent images that are
- blocked, or otherwise feel the need to fine-tune
- <application>Privoxy's</application> behavior, take a look at the <link
- linkend="actions-file">actions files</link>. As a quick start, you might
- find the <link linkend="act-examples">richly commented examples</link>
- helpful. You can also view and edit the actions files through the <ulink
- url="http://config.privoxy.org">web-based user interface</ulink>. The
- Appendix <quote><link linkend="actionsanat">Troubleshooting: Anatomy of an
- Action</link></quote> has hints on how to understand and debug actions that
- <quote>misbehave</quote>.
- </para>
- </listitem>
-
-<!--
- Did anyone test these lately?
- fk 2007-11-10
- <listitem>
- <para>
- For easy access to &my-app;'s most important controls, drag the provided
- <link linkend="bookmarklets">Bookmarklets</link> into your browser's
- personal toolbar.
- </para>
- </listitem>
--->
-
- <listitem>
- <para>
- Please see the section <link linkend="contact">Contacting the
- Developers</link> on how to report bugs, problems with websites or to get
- help.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Now enjoy surfing with enhanced control, comfort and privacy!
- </para>
- </listitem>
-
- </itemizedlist>
-</para>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-
-<sect2 id="quickstart-ad-blocking">
-<title>Quickstart to Ad Blocking</title>
-<!--
- NOTE: This section is deliberately redundant for those that don't
- want to read the whole thing (which is getting lengthy).
--->
-<para>
- Ad blocking is but one of <application>Privoxy's</application>
- array of features. Many of these features are for the technically minded advanced
- user. But, ad and banner blocking is surely common ground for everybody.
-</para>
-<para>
- This section will provide a quick summary of ad blocking so
- you can get up to speed quickly without having to read the more extensive
- information provided below, though this is highly recommended.
-</para>
-<para>
- First a bit of a warning ... blocking ads is much like blocking SPAM: the
- more aggressive you are about it, the more likely you are to block
- things that were not intended. And the more likely that some things
- may not work as intended. So there is a trade off here. If you want
- extreme ad free browsing, be prepared to deal with more
- <quote>problem</quote> sites, and to spend more time adjusting the
- configuration to solve these unintended consequences. In short, there is
- not an easy way to eliminate <emphasis>all</emphasis> ads. Either take
- the easy way and settle for <emphasis>most</emphasis> ads blocked with the
- default configuration, or jump in and tweak it for your personal surfing
- habits and preferences.
-</para>
-<para>
- Secondly, a brief explanation of <application>Privoxy's </application>
- <quote>actions</quote>. <quote>Actions</quote> in this context, are
- the directives we use to tell <application>Privoxy</application> to perform
- some task relating to HTTP transactions (i.e. web browsing). We tell
- <application>Privoxy</application> to take some <quote>action</quote>. Each
- action has a unique name and function. While there are many potential
- <application>actions</application> in <application>Privoxy's</application>
- arsenal, only a few are used for ad blocking. <link
- linkend="actions">Actions</link>, and <link linkend="actions-file">action
- configuration files</link>, are explained in depth below.
-</para>
-<para>
- Actions are specified in <application>Privoxy's</application> configuration,
- followed by one or more URLs to which the action should apply. URLs
- can actually be URL type <link linkend="af-patterns">patterns</link> that use
- wildcards so they can apply potentially to a range of similar URLs. The
- actions, together with the URL patterns are called a section.
-</para>
-<para>
- When you connect to a website, the full URL will either match one or more
- of the sections as defined in <application>Privoxy's</application> configuration,
- or not. If so, then <application>Privoxy</application> will perform the
- respective actions. If not, then nothing special happens. Furthermore, web
- pages may contain embedded, secondary URLs that your web browser will
- use to load additional components of the page, as it parses the
- original page's HTML content. An ad image for instance, is just an URL
- embedded in the page somewhere. The image itself may be on the same server,
- or a server somewhere else on the Internet. Complex web pages will have many
- such embedded URLs. &my-app; can deal with each URL individually, so, for
- instance, the main page text is not touched, but images from such-and-such
- server are blocked.
-</para>
-
-<para>
- The most important actions for basic ad blocking are: <literal><link
- linkend="block">block</link></literal>, <literal><link
- linkend="handle-as-image">handle-as-image</link></literal>,
- <literal><link
- linkend="handle-as-empty-document">handle-as-empty-document</link></literal>,and
- <literal><link linkend="set-image-blocker">set-image-blocker</link></literal>:
-</para>
-
-<para>
- <itemizedlist>
-
- <listitem>
- <para>
- <literal><link linkend="block">block</link></literal> - this is perhaps
- the single most used action, and is particularly important for ad blocking.
- This action stops any contact between your browser and any URL patterns
- that match this action's configuration. It can be used for blocking ads,
- but also anything that is determined to be unwanted. By itself, it simply
- stops any communication with the remote server and sends
- <application>Privoxy</application>'s own built-in BLOCKED page instead to
- let you now what has happened (with some exceptions, see below).
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal><link linkend="handle-as-image">handle-as-image</link></literal> -
- tells <application>Privoxy</application> to treat this URL as an image.
- <application>Privoxy</application>'s default configuration already does this
- for all common image types (e.g. GIF), but there are many situations where this
- is not so easy to determine. So we'll force it in these cases. This is particularly
- important for ad blocking, since only if we know that it's an image of
- some kind, can we replace it with an image of our choosing, instead of the
- <application>Privoxy</application> BLOCKED page (which would only result in
- a <quote>broken image</quote> icon). There are some limitations to this
- though. For instance, you can't just brute-force an image substitution for
- an entire HTML page in most situations.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal><link linkend="handle-as-empty-document">handle-as-empty-document</link></literal> -
- sends an empty document instead of <application>Privoxy's</application>
- normal BLOCKED HTML page. This is useful for file types that are neither
- HTML nor images, such as blocking JavaScript files.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal><link
- linkend="set-image-blocker">set-image-blocker</link></literal> - tells
- <application>Privoxy</application> what to display in place of an ad image that
- has hit a block rule. For this to come into play, the URL must match a
- <literal><link linkend="block">block</link></literal> action somewhere in the
- configuration, <emphasis>and</emphasis>, it must also match an
- <literal><link linkend="handle-as-image">handle-as-image</link></literal> action.
- </para>
- <para>
- The configuration options on what to display instead of the ad are:
- </para>
- <simplelist>
- <member>
- <emphasis>pattern</emphasis> - a checkerboard pattern, so that an ad
- replacement is obvious. This is the default.
- </member>
- </simplelist>
- <simplelist>
- <member>
- <emphasis>blank</emphasis> - A very small empty GIF image is displayed.
- This is the so-called <quote>invisible</quote> configuration option.
- </member>
- </simplelist>
- <simplelist>
- <member>
- <emphasis>http://<URL></emphasis> - A redirect to any image anywhere
- of the user's choosing (advanced usage).
- </member>
- </simplelist>
- </listitem>
-
-</itemizedlist>
-</para>
-
-<para>
- Advanced users will eventually want to explore &my-app;
- <literal><link linkend="filter">filters</link></literal> as well. Filters
- are very different from <literal><link
- linkend="block">blocks</link></literal>.
- A <quote>block</quote> blocks a site, page, or unwanted contented. Filters
- are a way of filtering or modifying what is actually on the page. An example
- filter usage: a text replacement of <quote>no-no</quote> for
- <quote>nasty-word</quote>. That is a very simple example. This process can be
- used for ad blocking, but it is more in the realm of advanced usage and has
- some pitfalls to be wary off.
-</para>
-
-<para>
- The quickest way to adjust any of these settings is with your browser through
- the special <application>Privoxy</application> editor at <ulink
- url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
- (shortcut: <ulink url="http://p.p/">http://p.p/show-status</ulink>). This
- is an internal page, and does not require Internet access.
-</para>
-
-<para>
- Note that as of <application>Privoxy</application> 3.0.7 beta the
- action editor is disabled by default. Check the
- <ulink url="config.html#ENABLE-EDIT-ACTIONS">enable-edit-actions
- section in the configuration file</ulink> to learn why and in which
- cases it's safe to enable again.
-</para>
-
-<para>
- If you decided to enable the action editor, select the appropriate
- <quote>actions</quote> file, and click
- <quote><guibutton>Edit</guibutton></quote>. It is best to put personal or
- local preferences in <filename>user.action</filename> since this is not
- meant to be overwritten during upgrades, and will over-ride the settings in
- other files. Here you can insert new <quote>actions</quote>, and URLs for ad
- blocking or other purposes, and make other adjustments to the configuration.
- <application>Privoxy</application> will detect these changes automatically.
-</para>
-
-<para>
- A quick and simple step by step example:
-</para>
-
-<para>
- <itemizedlist>
-
- <listitem>
- <para>
- Right click on the ad image to be blocked, then select
- <quote><guimenuitem>Copy Link Location</guimenuitem></quote> from the
- pop-up menu.
- </para>
- </listitem>
- <listitem>
- <para>
- Set your browser to
- <ulink
- url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
- </para>
- </listitem>
- <listitem>
- <para>
- Find <filename>user.action</filename> in the top section, and click
- on <quote><guibutton>Edit</guibutton></quote>:
- </para>
-
- <!-- image of editor and actions files selections -->
- <para>
- <figure pgwide="0" float="0"><title>Actions Files in Use</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="files-in-use.jpg" format="jpg">
- </imageobject>
- <textobject>
- <phrase>[ Screenshot of Actions Files in Use ]</phrase>
- </textobject>
- </mediaobject>
- </figure>
- </para>
- </listitem>
-
- <listitem>
- <para>
- You should have a section with only
- <literal><link linkend="block">block</link></literal> listed under
- <quote>Actions:</quote>.
- If not, click a <quote><guibutton>Insert new section below</guibutton></quote>
- button, and in the new section that just appeared, click the
- <guibutton>Edit</guibutton> button right under the word <quote>Actions:</quote>.
- This will bring up a list of all actions. Find
- <literal><link linkend="block">block</link></literal> near the top, and click
- in the <quote>Enabled</quote> column, then <quote><guibutton>Submit</guibutton></quote>
- just below the list.
- </para>
- </listitem>
- <listitem>
- <para>
- Now, in the <literal><link linkend="block">block</link></literal> actions section,
- click the <quote><guibutton>Add</guibutton></quote> button, and paste the URL the
- browser got from <quote><guimenuitem>Copy Link Location</guimenuitem></quote>.
- Remove the <literal>http://</literal> at the beginning of the URL. Then, click
- <quote><guibutton>Submit</guibutton></quote> (or
- <quote><guibutton>OK</guibutton></quote> if in a pop-up window).
- </para>
- </listitem>
- <listitem>
- <para>
- Now go back to the original page, and press <keycap>SHIFT-Reload</keycap>
- (or flush all browser caches). The image should be gone now.
- </para>
- </listitem>
-
- </itemizedlist>
-</para>
-
-<para>
- This is a very crude and simple example. There might be good reasons to use a
- wildcard pattern match to include potentially similar images from the same
- site. For a more extensive explanation of <quote>patterns</quote>, and
- the entire actions concept, see <link linkend="actions-file">the Actions
- section</link>.
-</para>
-
-<para>
- For advanced users who want to hand edit their config files, you might want
- to now go to the <link linkend="act-examples">Actions Files Tutorial</link>.
- The ideas explained therein also apply to the web-based editor.
-</para>
-<para>
- There are also various
- <link linkend="filter">filters</link> that can be used for ad blocking
- (filters are a special subset of actions). These
- fall into the <quote>advanced</quote> usage category, and are explained in
- depth in later sections.
-</para>
-
-</sect2>
-
-</sect1>
-
-<!-- ~ End section ~ -->
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="startup">
-<title>Starting Privoxy</title>
-<para>
- Before launching <application>Privoxy</application> for the first time, you
- will want to configure your browser(s) to use
- <application>Privoxy</application> as a HTTP and HTTPS (SSL)
- <ulink url="http://en.wikipedia.org/wiki/Proxy_server">proxy</ulink>. 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 <emphasis>that must be done
-</emphasis>!
-</para>
-<para>
- Please note that <application>Privoxy</application> can only proxy HTTP and
- HTTPS traffic. It will not work with FTP or other protocols.
-</para>
-
- <!-- image of Mozilla Proxy configuration -->
- <para>
- <figure pgwide="0" float="0"><title>Proxy Configuration Showing
- Mozilla/Netscape HTTP and HTTPS (SSL) Settings</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="proxy_setup.jpg" format="jpg">
- </imageobject>
- <textobject>
- <phrase>[ Screenshot of Mozilla Proxy Configuration ]</phrase>
- </textobject>
- </mediaobject>
- </figure>
- </para>
-
-
-<para>
- With <application>Firefox</application>, this is typically set under:
-</para>
-
-<literallayout>
- <guibutton>Tools</guibutton> -> <guibutton>Options</guibutton> -> <guibutton>Advanced</guibutton> -> <guibutton>Network</guibutton> -><guibutton>Connection</guibutton> -> <guibutton>Settings</guibutton>
-
-</literallayout>
-
-<para>
- Or optionally on some platforms:
-</para>
-
-<literallayout>
- <guibutton>Edit</guibutton> -> <guibutton>Preferences</guibutton> -> <guibutton>General</guibutton> -> <guibutton>Connection Settings</guibutton> -> <guibutton>Manual Proxy Configuration</guibutton>
-
-</literallayout>
-
-
-<para>
- With <application>Netscape</application> (and
- <application>Mozilla</application>), this can be set under:
-</para>
-
-
-<literallayout>
-<!-- Mix ascii and gui art, something for everybody -->
-<!-- spacing on this is tricky -->
- <guibutton>Edit</guibutton> -> <guibutton>Preferences</guibutton> -> <guibutton>Advanced</guibutton> -> <guibutton>Proxies</guibutton> -> <guibutton>HTTP Proxy</guibutton>
-
-</literallayout>
-
-<para>
- For <application>Internet Explorer v.5-7</application>:
-</para>
-
-<literallayout>
- <guibutton>Tools</guibutton> -> <guibutton>Internet Options</guibutton> -> <guibutton>Connections</guibutton> -> <guibutton>LAN Settings</guibutton>
-</literallayout>
-
-<para>
- Then, check <quote>Use Proxy</quote> and fill in the appropriate info
- (Address: 127.0.0.1, Port: 8118). Include HTTPS (SSL), if you want HTTPS
- proxy support too (sometimes labeled <quote>Secure</quote>). Make sure any
- checkboxes like <quote>Use the same proxy server for all protocols</quote> is
- <emphasis>UNCHECKED</emphasis>. You want only HTTP and HTTPS (SSL)!
-</para>
-
- <!-- image of IE Proxy configuration -->
- <para>
- <figure pgwide="0" float="0"><title>Proxy Configuration Showing
- Internet Explorer HTTP and HTTPS (Secure) Settings</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="proxy2.jpg" format="jpg">
- </imageobject>
- <textobject>
- <phrase>[ Screenshot of IE Proxy Configuration ]</phrase>
- </textobject>
- </mediaobject>
- </figure>
- </para>
-
-
-<para>
- 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. Remove
- any <ulink url="http://en.wikipedia.org/wiki/Browser_cookie">cookies</ulink>,
- if you want <application>Privoxy</application> to manage that. You are now
- ready to start enjoying the benefits of using
- <application>Privoxy</application>!
-</para>
-
-<para>
- <application>Privoxy</application> itself 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, <application>Privoxy</application>
- will look for a file named <filename>config</filename> in the current
- directory. Except on Win32 where it will try <filename>config.txt</filename>.
-</para>
-
-<sect2 id="start-redhat">
-<title>Red Hat and Fedora</title>
-<para>
- A default Red Hat installation may not start &my-app; upon boot. It will use
- the file <filename>/etc/privoxy/config</filename> as its main configuration
- file.
-</para>
-<para>
- <screen>
- # /etc/rc.d/init.d/privoxy start
-</screen>
-</para>
-<para>
- Or ...
-</para>
-<para>
- <screen>
- # service privoxy start
-</screen>
-</para>
-</sect2>
-
-<sect2 id="start-debian">
-<title>Debian</title>
-<para>
- We use a script. Note that Debian typically starts &my-app; upon booting per
- default. It will use the file
- <filename>/etc/privoxy/config</filename> as its main configuration
- file.
-</para>
-<para>
- <screen>
- # /etc/init.d/privoxy start
-</screen>
-</para>
-</sect2>
-
-<sect2 id="start-windows">
-<title>Windows</title>
-<para>
-Click on the &my-app; Icon to start <application>Privoxy</application>. If no configuration file is
- specified on the command line, <application>Privoxy</application> will look
- for a file named <filename>config.txt</filename>. Note that Windows will
- automatically start &my-app; when the system starts if you chose that option
- when installing.
-</para>
-<para>
- <application>Privoxy</application> can run with full Windows service functionality.
- On Windows only, the &my-app; program has two new command line arguments
- to install and uninstall &my-app; as a service. See the
- <link linkend="installation-pack-win">Windows Installation
- instructions</link> for details.
-</para>
-</sect2>
-
-<sect2 id="start-unices">
-<title>Solaris, NetBSD, FreeBSD, HP-UX and others</title>
-<para>
-Example Unix startup command:
-</para>
-<para>
- <screen>
- # /usr/sbin/privoxy /etc/privoxy/config
-</screen>
-</para>
-</sect2>
-
-<sect2 id="start-os2">
-<title>OS/2</title>
-<para>
- During installation, <application>Privoxy</application> is configured to
- start automatically when the system restarts. You can start it manually by
- double-clicking on the <application>Privoxy</application> icon in the
- <application>Privoxy</application> folder.
-</para>
-</sect2>
-
-<sect2 id="start-macosx">
-<title>Mac OS X</title>
-<para>
- After downloading the privoxy software, unzip the downloaded file by
- double-clicking on the zip file icon. Then, double-click on the
- installer package icon and follow the installation process.
-</para>
-<para>
- The privoxy service will automatically start after a successful
- installation. In addition, the privoxy service will automatically
- start every time your computer starts up.
-</para>
-<para>
- To prevent the privoxy service from automatically starting when your
- computer starts up, remove or rename the folder named
- /Library/StartupItems/Privoxy.
-</para>
-<para>
- A simple application named Privoxy Utility has been created which
- enables administrators to easily start and stop the privoxy service.
-</para>
-<para>
- In addition, the Privoxy Utility presents a simple way for
- administrators to edit the various privoxy config files. A method
- to uninstall the software is also available.
-</para>
-<para>
- An administrator username and password must be supplied in order for
- the Privoxy Utility to perform any of the tasks.
-</para>
-</sect2>
-
-
-<sect2 id="start-amigaos">
-<title>AmigaOS</title>
-<para>
- Start <application>Privoxy</application> (with RUN <>NIL:) in your
- <filename>startnet</filename> script (AmiTCP), in
- <filename>s:user-startup</filename> (RoadShow), as startup program in your
- startup script (Genesis), or as startup action (Miami and MiamiDx).
- <application>Privoxy</application> will automatically quit when you quit your
- TCP/IP stack (just ignore the harmless warning your TCP/IP stack may display that
- <application>Privoxy</application> is still running).
-</para>
-</sect2>
-
-<sect2 id="start-gentoo">
-<title>Gentoo</title>
-<para>
- A script is again used. It will use the file <filename>/etc/privoxy/config
- </filename> as its main configuration file.
-</para>
-<para>
- <screen>
- /etc/init.d/privoxy start
- </screen>
-</para>
-<para>
- Note that <application>Privoxy</application> is not automatically started at
- boot time by default. You can change this with the <literal>rc-update</literal>
- command.
-</para>
-<para>
- <screen>
- rc-update add privoxy default
- </screen>
-</para>
-</sect2>
-
-<!--
-
-<para>
- See the section <link linkend="cmdoptions">Command line options</link> for
- further info.
-</para>
-
-must find a better place for this paragraph
-
-<para>
- The included default configuration files should give a reasonable starting
- point. Most of the per site configuration is done in the
- <ulink url="actions-file.html"><quote>actions</quote></ulink> files. These are
- where various cookie actions are defined, ad and banner blocking, and other
- aspects of <application>Privoxy</application> configuration. There are several
- such files included, with varying levels of aggressiveness.
-</para>
-
-<para>
- 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 <quote>session cookies</quote>), unless you add them to the
- configuration. If you want the browser to handle this instead, you will need
- to edit <filename>user.action</filename> (or through the web based interface)
- and disable this feature. If you use more than one browser, it would make
- more sense to let <application>Privoxy</application> handle this. In which
- case, the browser(s) should be set to accept all cookies.
-</para>
-
-<para>
- Another feature where you will probably want to define exceptions for trusted
- sites is the popup-killing (through <ulink
- url="actions-file.html#FILTER-POPUPS"><quote>+filter{popups}</quote></ulink>),
- because your favorite shopping, banking, or leisure site may need
- popups (explained below).
-</para>
-
-<para>
- <application>Privoxy</application> does not support all of the optional HTTP/1.1
- features yet. In the unlikely event that you experience inexplicable problems
- with browsers that use HTTP/1.1 per default
- (like <application>Mozilla</application> or recent versions of I.E.), you might
- try to force HTTP/1.0 compatibility. For Mozilla, look under <literal>Edit ->
- Preferences -> Debug -> Networking</literal>.
- Alternatively, set the <quote>+downgrade-http-version</quote> config option in
- <filename>default.action</filename> which will downgrade your browser's HTTP
- requests from HTTP/1.1 to HTTP/1.0 before processing them.
-</para>
-
-<para>
- After running <application>Privoxy</application> 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. <quote>Actions</quote>
- can be adjusted by pointing your browser to
- <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
- (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>),
- and then follow the link to <quote>View & Change the Current Configuration</quote>.
- (This is an internal page and does not require Internet access.)
-</para>
-
-<para>
- In fact, various aspects of <application>Privoxy</application>
- configuration can be viewed from this page, including
- current configuration parameters, source code version numbers,
- the browser's request headers, and <quote>actions</quote> that apply
- to a given URL. In addition to the actions file
- editor mentioned above, <application>Privoxy</application> can also
- be turned <quote>on</quote> and <quote>off</quote> (toggled) from this page.
-</para>
-
-<para>
- If you encounter problems, try loading the page without
- <application>Privoxy</application>. If that helps, enter the URL where
- you have the problems into <ulink url="http://p.p/show-url-info">the browser
- based rule tracing utility</ulink>. 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.
-</para>
-
-<para>
- If the above paragraph sounds gibberish to you, you might want to <link
- linkend="actions-file">read more about the actions concept</link>
- or even dive deep into the <link linkend="actionsanat">Appendix
- on actions</link>.
-</para>
-
-<para>
- 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 <link linkend="contact"><quote>Contacting the
- Developers</quote></link> below.
-</para>
-
--->
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="cmdoptions">
-<title>Command Line Options</title>
-<para>
- <application>Privoxy</application> may be invoked with the following
- command-line options:
-</para>
-
-<para>
- <itemizedlist>
-
- <listitem>
- <para>
- <emphasis>--version</emphasis>
- </para>
- <para>
- Print version info and exit. Unix only.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>--help</emphasis>
- </para>
- <para>
- Print short usage info and exit. Unix only.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>--no-daemon</emphasis>
- </para>
- <para>
- Don't become a daemon, i.e. don't fork and become process group
- leader, and don't detach from controlling tty. Unix only.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>--pidfile FILE</emphasis>
- </para>
- <para>
- On startup, write the process ID to <emphasis>FILE</emphasis>. Delete the
- <emphasis>FILE</emphasis> on exit. Failure to create or delete the
- <emphasis>FILE</emphasis> is non-fatal. If no <emphasis>FILE</emphasis>
- option is given, no PID file will be used. Unix only.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>--user USER[.GROUP]</emphasis>
- </para>
- <para>
- After (optionally) writing the PID file, assume the user ID of
- <emphasis>USER</emphasis>, and if included the GID of GROUP. Exit if the
- privileges are not sufficient to do so. Unix only.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>--chroot</emphasis>
- </para>
- <para>
- Before changing to the user ID given in the <emphasis>--user</emphasis> option,
- chroot to that user's home directory, i.e. make the kernel pretend to the &my-app;
- process that the directory tree starts there. If set up carefully, this can limit
- the impact of possible vulnerabilities in &my-app; to the files contained in that hierarchy.
- Unix only.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>--pre-chroot-nslookup hostname</emphasis>
- </para>
- <para>
- Specifies a hostname to look up before doing a chroot. On some systems, initializing the
- resolver library involves reading config files from /etc and/or loading additional shared
- libraries from /lib. On these systems, doing a hostname lookup before the chroot reduces
- the number of files that must be copied into the chroot tree.
- </para>
- <para>
- For fastest startup speed, a good value is a hostname that is not in /etc/hosts but that
- your local name server (listed in /etc/resolv.conf) can resolve without recursion
- (that is, without having to ask any other name servers). The hostname need not exist,
- but if it doesn't, an error message (which can be ignored) will be output.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <emphasis>configfile</emphasis>
- </para>
- <para>
- If no <emphasis>configfile</emphasis> is included on the command line,
- <application>Privoxy</application> will look for a file named
- <quote>config</quote> in the current directory (except on Win32
- where it will look for <quote>config.txt</quote> instead). Specify
- full path to avoid confusion. If no config file is found,
- <application>Privoxy</application> will fail to start.
- </para>
- </listitem>
-
- </itemizedlist>
-</para>
-
-<para>
- On <application>MS Windows</application> only there are two additional
- command-line options to allow <application>Privoxy</application> to install and
- run as a <emphasis>service</emphasis>. See the
-<link linkend="installation-pack-win">Window Installation section</link>
-for details.
-</para>
-
-</sect2>
-
-</sect1>
-
-<!-- ~ End section ~ -->
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="configuration"><title>Privoxy Configuration</title>
- <para>
- All <application>Privoxy</application> configuration is stored
- in text files. These files can be edited with a text editor.
- Many important aspects of <application>Privoxy</application> can
- also be controlled easily with a web browser.
- </para>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-
-<sect2>
-<title>Controlling Privoxy with Your Web Browser</title>
-<para>
- <application>Privoxy</application>'s user interface can be reached through the special
- URL <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
- (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>),
- which is a built-in page and works without Internet access.
- You will see the following section:
-
-</para>
-
-<!-- Needs to be put in a table and colorized -->
-<screen>
- <msgtext>
- <bridgehead renderas="sect2"> Privoxy Menu</bridgehead>
-
- <simplelist>
- <member>
- ▪ <ulink url="http://config.privoxy.org/show-status">View & change the current configuration</ulink>
- </member>
- <member>
- ▪ <ulink url="http://config.privoxy.org/show-version">View the source code version numbers</ulink>
- </member>
- <member>
- ▪ <ulink url="http://config.privoxy.org/show-request">View the request headers.</ulink>
- </member>
- <member>
- ▪ <ulink url="http://config.privoxy.org/show-url-info">Look up which actions apply to a URL and why</ulink>
- </member>
- <member>
- ▪ <ulink url="http://config.privoxy.org/toggle">Toggle Privoxy on or off</ulink>
- </member>
- <member>
- ▪ <ulink
- url="http://www.privoxy.org/&p-version;/user-manual/">Documentation</ulink>
- </member>
- </simplelist>
- </msgtext>
-</screen>
-
-
-<para>
- This should be self-explanatory. Note the first item leads to an editor for the
- <link linkend="actions-file">actions files</link>, which is where the ad, banner,
- cookie, and URL blocking magic is configured as well as other advanced features of
- <application>Privoxy</application>. This is an easy way to adjust various
- aspects of <application>Privoxy</application> configuration. The actions
- file, and other configuration files, are explained in detail below.
-</para>
-
-<para>
- <quote>Toggle Privoxy On or Off</quote> 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 <application>Privoxy</application>
- causing the problem or not. <application>Privoxy</application> continues
- to run as a proxy in this case, but all manipulation is disabled, i.e.
- <application>Privoxy</application> acts like a normal forwarding proxy. There
- is even a toggle <link linkend="bookmarklets">Bookmarklet</link> offered, so
- that you can toggle <application>Privoxy</application> with one click from
- your browser.
-</para>
-
-<para>
- Note that several of the features described above are disabled by default
- in <application>Privoxy</application> 3.0.7 beta and later.
- Check the
- <ulink url="config.html">configuration file</ulink> to learn why
- and in which cases it's safe to enable them again.
-</para>
-
-</sect2>
-
-<!-- ~ End section ~ -->
-
-
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-
-<sect2 id="confoverview">
-<title>Configuration Files Overview</title>
-<para>
- For Unix, *BSD and Linux, all configuration files are located in
- <filename>/etc/privoxy/</filename> by default. For MS Windows, OS/2, and
- AmigaOS these are all in the same directory as the
- <application>Privoxy</application> executable. <![%p-not-stable;[ The name
- and number of configuration files has changed from previous versions, and is
- subject to change as development progresses.]]>
-</para>
-
-<para>
- 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:
-</para>
-
-<para>
- <itemizedlist>
-
- <listitem>
- <para>
- The <link linkend="config">main configuration file</link> is named <filename>config</filename>
- on Linux, Unix, BSD, OS/2, and AmigaOS and <filename>config.txt</filename>
- on Windows. This is a required file.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <filename>match-all.action</filename> is used to define which <quote>actions</quote>
- relating to banner-blocking, images, pop-ups, content modification, cookie handling
- etc should be applied by default. It should be the first actions file loaded.
- </para>
- <para>
- <filename>default.action</filename> defines many exceptions (both positive and negative)
- from the default set of actions that's configured in <filename>match-all.action</filename>.
- It should be the second actions file loaded and shouldn't be edited by the user.
- </para>
- <para>
- Multiple actions files may be defined in <filename>config</filename>. These
- are processed in the order they are defined. Local customizations and locally
- preferred exceptions to the default policies as defined in
- <filename>match-all.action</filename> (which you will most probably want
- to define sooner or later) are best applied in <filename>user.action</filename>,
- where you can preserve them across upgrades. The file isn't installed by all
- installers, but you can easily create it yourself with a text editor.
- </para>
- <para>
- There is also a web based editor that can be accessed from
- <ulink
- url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
- (Shortcut: <ulink
- url="http://p.p/show-status">http://p.p/show-status</ulink>) for the
- various actions files.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <quote>Filter files</quote> (the <link linkend="filter-file">filter
- file</link>) 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.
- <filename>default.filter</filename> includes various filters made
- available for use by the developers. Some are much more intrusive than
- others, and all should be used with caution. You may define additional
- filter files in <filename>config</filename> as you can with
- actions files. We suggest <filename>user.filter</filename> for any
- locally defined filters or customizations.
- </para>
- </listitem>
-
- </itemizedlist>
-</para>
-
-<para>
- The syntax of the configuration and filter files may change between different
- Privoxy versions, unfortunately some enhancements cost backwards compatibility.
- <!-- Add link to documentation-->
-</para>
-
-<para>
- All files use the <quote><literal>#</literal></quote> character to denote a
- comment (the rest of the line will be ignored) and understand line continuation
- through placing a backslash ("<literal>\</literal>") as the very last character
- in a line. If the <literal>#</literal> is preceded by a backslash, it looses
- its special function. Placing a <literal>#</literal> in front of an otherwise
- valid configuration line to prevent it from being interpreted is called "commenting
- out" that line. Blank lines are ignored.
-</para>
-
-<para>
- The actions files and filter files
- can use Perl style <link linkend="regex">regular expressions</link> for
- maximum flexibility.
-</para>
-
-<para>
- After making any changes, there is no need to restart
- <application>Privoxy</application> in order for the changes to take
- effect. <application>Privoxy</application> 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 <application>Privoxy</application>, these <quote>wake up</quote> requests
- must obviously be sent to the <emphasis>old</emphasis> listening address.
-</para>
-
-<![%p-not-stable;[
-<para>
- 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 <quote>default</quote> setting, may change, so
- please check all your configuration files on important issues.
-</para>
-]]>
-
-</sect2>
-</sect1>
-<!-- ~ End section ~ -->
-
-
-<!-- ~~~~~~~~ New section Header ~~~~~~~~~ -->
-
-<!-- **************************************************** -->
-<!-- Include config.sgml here -->
-<!-- This is where the entire config file is detailed. -->
- &config;
-<!-- end include -->
-
-
-<!-- ~ End section ~ -->
-
-
-
-<!-- ~~~~~~~~ New section Header ~~~~~~~~~ -->
-
-<sect1 id="actions-file"><title>Actions Files</title>
-
-
-<!--
- XXX: similar descriptions are in the Configuration Files sections.
- We should only describe them at one place.
--->
-<para>
- The actions files are used to define what <emphasis>actions</emphasis>
- <application>Privoxy</application> 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 a number of such actions, with a wide range of functionality.
- Each action does something a little different.
- These actions give us a veritable arsenal of tools with which to exert
- our control, preferences and independence. Actions can be combined so that
- their effects are aggregated when applied against a given set of URLs.
-</para>
-<para>
- There
- are three action files included with <application>Privoxy</application> with
- differing purposes:
-</para>
-<para>
- <itemizedlist>
- <listitem>
- <para>
- <filename>match-all.action</filename> - is used to define which
- <quote>actions</quote> relating to banner-blocking, images, pop-ups,
- content modification, cookie handling etc should be applied by default.
- It should be the first actions file loaded
- </para>
- </listitem>
- <listitem>
- <para>
- <filename>default.action</filename> - defines many exceptions (both
- positive and negative) from the default set of actions that's configured
- in <filename>match-all.action</filename>. It is a set of rules that should
- work reasonably well as-is for most users. This file is only supposed to
- be edited by the developers. It should be the second actions file loaded.
- </para>
- </listitem>
- <listitem>
- <para>
- <filename>user.action</filename> - is intended to be for local site
- preferences and exceptions. As an example, if your ISP or your bank
- has specific requirements, and need special handling, this kind of
- thing should go here. This file will not be upgraded.
- </para>
- </listitem>
- <listitem>
- <para>
- <guibutton>Edit</guibutton> <guibutton>Set to Cautious</guibutton> <guibutton>Set to Medium</guibutton> <guibutton>Set to Advanced</guibutton>
- </para>
- <para>
- These have increasing levels of aggressiveness <emphasis>and have no
- influence on your browsing unless you select them explicitly in the
- editor</emphasis>. A default installation should be pre-set to
- <literal>Cautious</literal>. New users should try this for a while before
- adjusting the settings to more aggressive levels. The more aggressive
- the settings, then the more likelihood there is of problems such as sites
- not working as they should.
- </para>
- <para>
- The <guibutton>Edit</guibutton> button allows you to turn each
- action on/off individually for fine-tuning. The <guibutton>Cautious</guibutton>
- button changes the actions list to low/safe settings which will activate
- ad blocking and a minimal set of &my-app;'s features, and subsequently
- there will be less of a chance for accidental problems. The
- <guibutton>Medium</guibutton> button sets the list to a medium level of
- other features and a low level set of privacy features. The
- <guibutton>Advanced</guibutton> button sets the list to a high level of
- ad blocking and medium level of privacy. See the chart below. The latter
- three buttons over-ride any changes via with the
- <guibutton>Edit</guibutton> button. More fine-tuning can be done in the
- lower sections of this internal page.
- </para>
- <para>
- While the actions file editor allows to enable these settings in all
- actions files, they are only supposed to be enabled in the first one
- to make sure you don't unintentionally overrule earlier rules.
- </para>
- <para>
- The default profiles, and their associated actions, as pre-defined in
- <filename>default.action</filename> are:
- </para>
- <para>
- <table frame=all><title>Default Configurations</title>
- <tgroup cols=4 align=left colsep=1 rowsep=1>
- <colspec colname=c1>
- <colspec colname=c2>
- <colspec colname=c3>
- <colspec colname=c4>
- <thead>
- <row>
- <entry>Feature</entry>
- <entry>Cautious</entry>
- <entry>Medium</entry>
- <entry>Advanced</entry>
- </row>
- </thead>
- <!-- <tfoot> -->
- <!-- <row> -->
- <!-- <entry>f1</entry> -->
- <!-- <entry>f2</entry> -->
- <!-- <entry>f3</entry> -->
- <!-- <entry>f4</entry> -->
- <!-- </row> -->
- <!-- </tfoot> -->
- <tbody>
-
- <row>
- <entry>Ad-blocking Aggressiveness</entry>
- <entry>medium</entry>
- <entry>high</entry>
- <entry>high</entry>
- </row>
-
- <row>
- <entry>Ad-filtering by size</entry>
- <entry>no</entry>
- <entry>yes</entry>
- <entry>yes</entry>
- </row>
-
- <row>
- <entry>Ad-filtering by link</entry>
- <entry>no</entry>
- <entry>no</entry>
- <entry>yes</entry>
- </row>
- <row>
- <entry>Pop-up killing</entry>
- <entry>blocks only</entry>
- <entry>blocks only</entry>
- <entry>blocks only</entry>
- </row>
-
- <row>
- <entry>Privacy Features</entry>
- <entry>low</entry>
- <entry>medium</entry>
- <entry>medium/high</entry>
- </row>
-
- <row>
- <entry>Cookie handling</entry>
- <entry>none</entry>
- <entry>session-only</entry>
- <entry>kill</entry>
- </row>
-
- <row>
- <entry>Referer forging</entry>
- <entry>no</entry>
- <entry>yes</entry>
- <entry>yes</entry>
- </row>
-
- <row>
- <entry>GIF de-animation</entry>
- <entry>no</entry>
- <entry>yes</entry>
- <entry>yes</entry>
- </row>
-
- <row>
- <entry>Fast redirects</entry>
- <entry>no</entry>
- <entry>no</entry>
- <entry>yes</entry>
- </row>
-
- <row>
- <entry>HTML taming</entry>
- <entry>no</entry>
- <entry>no</entry>
- <entry>yes</entry>
- </row>
-
- <row>
- <entry>JavaScript taming</entry>
- <entry>no</entry>
- <entry>no</entry>
- <entry>yes</entry>
- </row>
-
- <row>
- <entry>Web-bug killing</entry>
- <entry>no</entry>
- <entry>yes</entry>
- <entry>yes</entry>
- </row>
-
- <row>
- <entry>Image tag reordering</entry>
- <entry>no</entry>
- <entry>yes</entry>
- <entry>yes</entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
- </para>
-
- </listitem>
- </itemizedlist>
-</para>
-
-<para>
- The list of actions files to be used are defined in the main configuration
- file, and are processed in the order they are defined (e.g.
- <filename>default.action</filename> is typically processed before
- <filename>user.action</filename>). The content of these can all be viewed and
- edited from <ulink
- url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.
- The over-riding principle when applying actions, is that the last action that
- matches a given URL wins. The broadest, most general rules go first
- (defined in <filename>default.action</filename>),
- followed by any exceptions (typically also in
- <filename>default.action</filename>), which are then followed lastly by any
- local preferences (typically in <emphasis>user</emphasis><filename>.action</filename>).
- Generally, <filename>user.action</filename> has the last word.
- </para>
-
-<para>
- An actions file typically has multiple sections. If you want to use
- <quote>aliases</quote> in an actions file, you have to place the (optional)
- <link linkend="aliases">alias section</link> at the top of that file.
- Then comes the default set of rules which will apply universally to all
- sites and pages (be <emphasis>very careful</emphasis> with using such a
- universal set in <filename>user.action</filename> or any other actions file after
- <filename>default.action</filename>, because it will override the result
- from consulting any previous file). And then below that,
- exceptions to the defined universal policies. You can regard
- <filename>user.action</filename> as an appendix to <filename>default.action</filename>,
- with the advantage that it is a separate file, which makes preserving your
- personal settings across <application>Privoxy</application> upgrades easier.
-</para>
-
-<para>
- Actions can be used to block anything you want, including ads, banners, or
- just some obnoxious URL whose content you would rather not see. Cookies can be accepted
- or rejected, or accepted only during the current browser session (i.e. not
- written to disk), content can be modified, some JavaScripts tamed, user-tracking
- fooled, and much more. See below for a <link linkend="actions">complete list
- of actions</link>.
-</para>
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect2>
-<title>Finding the Right Mix</title>
-<para>
- Note that some <link linkend="actions">actions</link>, like cookie suppression
- or script disabling, may render some sites unusable that rely on these
- techniques to work properly. Finding the right mix of actions is not always easy and
- certainly a matter of personal taste. And, things can always change, requiring
- refinements in the configuration. In general, it can be said that the more
- <quote>aggressive</quote> your default settings (in the top section of the
- actions file) are, the more exceptions for <quote>trusted</quote> sites you
- will have to make later. If, for example, you want to crunch all cookies per
- default, you'll have to make exceptions from that rule for sites that you
- regularly use and that require cookies for actually useful purposes, like maybe
- your bank, favorite shop, or newspaper.
-</para>
-
-<para>
- 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 :).
-</para>
-</sect2>
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect2>
-<title>How to Edit</title>
-<para>
- The easiest way to edit the actions files is with a browser by
- using our browser-based editor, which can be reached from <ulink
- url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.
- Note: the config file option <link
- linkend="enable-edit-actions">enable-edit-actions</link> must be enabled for
- this to work. The editor allows both fine-grained control over every single
- feature on a per-URL basis, and easy choosing from wholesale sets of defaults
- like <quote>Cautious</quote>, <quote>Medium</quote> or
- <quote>Advanced</quote>. Warning: the <quote>Advanced</quote> setting is more
- aggressive, and will be more likely to cause problems for some sites.
- Experienced users only!
- </para>
-
-<para>
- If you prefer plain text editing to GUIs, you can of course also directly edit the
- the actions files with your favorite text editor. Look at
- <filename>default.action</filename> which is richly commented with many
- good examples.
-</para>
-</sect2>
-
-
-<sect2 id="actions-apply">
-<title>How Actions are Applied to Requests</title>
-<para>
- Actions files are divided into sections. There are special sections,
- like the <quote><link linkend="aliases">alias</link></quote> 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 and tag patterns, each on a separate line.
-</para>
-
-<para>
- To determine which actions apply to a request, the URL of the request is
- compared to all URL patterns in each <quote>action file</quote>.
- Every time it matches, the list of applicable actions for the request is
- incrementally updated, using the heading of the section in which the
- pattern is located. The same is done again for tags and tag patterns later on.
-</para>
-
-<para>
- If multiple applying sections set the same action differently,
- the last match wins. If not, the effects are aggregated.
- E.g. a URL might match a regular section with a heading line of <literal>{
- +<link linkend="handle-as-image">handle-as-image</link> }</literal>,
- then later another one with just <literal>{
- +<link linkend="block">block</link> }</literal>, resulting
- in <emphasis>both</emphasis> actions to apply. And there may well be
- cases where you will want to combine actions together. Such a section then
- might look like:
-</para>
-
- <para>
- <screen>
- { +<literal>handle-as-image</literal> +<literal>block{Banner ads.}</literal> }
- # Block these as if they were images. Send no block page.
- banners.example.com
- media.example.com/.*banners
- .example.com/images/ads/</screen>
- </para>
-
-<para>
- You can trace this process for URL patterns and any given URL by visiting <ulink
- url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>.
-</para>
-
-<para>
- Examples and more detail on this is provided in the Appendix, <link linkend="ACTIONSANAT">
- Troubleshooting: Anatomy of an Action</link> section.
-</para>
-</sect2>
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="af-patterns">
-<title>Patterns</title>
-<para>
- As mentioned, <application>Privoxy</application> uses <quote>patterns</quote>
- to determine what <emphasis>actions</emphasis> might apply to which sites and
- pages your browser attempts to access. These <quote>patterns</quote> use wild
- card type <emphasis>pattern</emphasis> matching to achieve a high degree of
- flexibility. This allows one expression to be expanded and potentially match
- against many similar patterns.
-</para>
-
-<para>
- Generally, an URL pattern has the form
- <literal><domain><port>/<path></literal>, where the
- <literal><domain></literal>, the <literal><port></literal>
- and the <literal><path></literal> are optional. (This is why the special
- <literal>/</literal> pattern matches all URLs). Note that the protocol
- portion of the URL pattern (e.g. <literal>http://</literal>) should
- <emphasis>not</emphasis> be included in the pattern. This is assumed already!
-</para>
-<para>
- The pattern matching syntax is different for the domain and path parts of
- the URL. The domain part uses a simple globbing type matching technique,
- while the path part uses more flexible
- <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
- Expressions</quote></ulink> (POSIX 1003.2).
-</para>
-<para>
- The port part of a pattern is a decimal port number preceded by a colon
- (<literal>:</literal>). If the domain part contains a numerical IPv6 address,
- it has to be put into angle brackets
- (<literal><</literal>, <literal>></literal>).
-</para>
-
-<variablelist>
- <varlistentry>
- <term><literal>www.example.com/</literal></term>