TITLE="Privoxy User Manual"
HREF="index.html"><LINK
REL="PREVIOUS"
-TITLE="Quickstart to Using Privoxy"
-HREF="quickstart.html"><LINK
+TITLE="Starting Privoxy"
+HREF="startup.html"><LINK
REL="NEXT"
TITLE="Contacting the Developers, Bug Reporting and Feature
Requests"
ALIGN="left"
VALIGN="bottom"
><A
-HREF="quickstart.html"
+HREF="startup.html"
>Prev</A
></TD
><TD
CLASS="SECT1"
><A
NAME="CONFIGURATION"
->5. <SPAN
+>7. <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
> Configuration</A
>Privoxy</SPAN
> can
also be controlled easily with a web browser.
-
</P
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
-NAME="AEN324"
->5.1. Controlling <SPAN
+NAME="AEN320"
+>7.1. Controlling <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
> with Your Web Browser</A
>),
which is a built-in page and works without Internet access.
You will see the following section: </P
-><P
-> <TABLE
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TD
><PRE
CLASS="SCREEN"
-> Please choose from the following options:
-
- * Privoxy main page
- * Show information about the current configuration
- * Show the source code version numbers
- * Show the request headers.
- * Show which actions apply to a URL and why
- * Toggle Privoxy on or off
- * Edit the actions list
-
- </PRE
-></TD
+> <H3
+CLASS="BRIDGEHEAD"
+>Privoxy Menu</H3
+><P
+></P
+><TABLE
+BORDER="0"
+><TBODY
+><TR
+><TD
+> ▪ <A
+HREF="http://config.privoxy.org/show-status"
+TARGET="_top"
+>View & change the current configuration</A
+>
+ </TD
+></TR
+><TR
+><TD
+> ▪ <A
+HREF="http://config.privoxy.org/show-version"
+TARGET="_top"
+>View the source code version numbers</A
+>
+ </TD
></TR
+><TR
+><TD
+> ▪ <A
+HREF="http://config.privoxy.org/show-request"
+TARGET="_top"
+>View the request headers.</A
+>
+ </TD
+></TR
+><TR
+><TD
+> ▪ <A
+HREF="http://config.privoxy.org/show-url-info"
+TARGET="_top"
+>Look up which actions apply to a URL and why</A
+>
+ </TD
+></TR
+><TR
+><TD
+> ▪ <A
+HREF="http://config.privoxy.org/toggle"
+TARGET="_top"
+>Toggle Privoxy on or off</A
+>
+ </TD
+></TR
+></TBODY
></TABLE
+><P
></P
+></PRE
+></TD
+></TR
+></TABLE
><P
-> This should be self-explanatory. Note the last item is an editor for the
+> This should be self-explanatory. Note the first item leads to an editor for the
<SPAN
CLASS="QUOTE"
>"actions list"</SPAN
->, which is where much of the ad, banner, cookie,
+>, which is where the ad, banner, cookie,
and URL blocking magic is configured as well as other advanced features of
<SPAN
CLASS="APPLICATION"
><H2
CLASS="SECT2"
><A
-NAME="AEN343"
->5.2. Configuration Files Overview</A
+NAME="CONFOVERVIEW"
+>7.2. Configuration Files Overview</A
></H2
><P
> For Unix, *BSD and Linux, all configuration files are located in
and number of configuration files has changed from previous versions, and is
subject to change as development progresses.</P
><P
-> The installed defaults provide a reasonable starting point, though possibly
- aggressive by some standards. For the time being, there are only three
- default configuration files (this may change in time):</P
+> 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:</P
><P
> <P
></P
><UL
><LI
><P
-> The main configuration file is named <TT
-CLASS="FILENAME"
->config</TT
+> The main configuration file is named <A
+HREF="configuration.html#CONFIG"
+>config</A
>
on Linux, Unix, BSD, OS/2, and AmigaOS and <TT
CLASS="FILENAME"
>config.txt</TT
>
- on Windows.
+ on Windows. This is a required file.
</P
></LI
><LI
> <TT
CLASS="FILENAME"
>default.action</TT
-> (the actions file) is used to define
- which of a set of various <SPAN
+> (the main <A
+HREF="configuration.html#ACTIONS-FILE"
+>actions file</A
+>) is used to define
+ the default settings for various <SPAN
CLASS="QUOTE"
>"actions"</SPAN
> relating to images, banners,
- pop-ups, access restrictions, banners and cookies are to be applied, and where.
- There is a web based editor for this file that can be accessed at <A
-HREF="http://config.privoxy.org/edit-actions/"
+ pop-ups, access restrictions, banners and cookies.
+ </P
+><P
+> Multiple actions files may be defined in <TT
+CLASS="FILENAME"
+>config</TT
+>. These
+ are processed in the order they are defined. Local customizations and locally
+ preferred exceptions to the default policies as defined in
+ <TT
+CLASS="FILENAME"
+>default.action</TT
+> are probably best applied in
+ <TT
+CLASS="FILENAME"
+>user.action</TT
+>, which should be preserved across
+ upgrades. <TT
+CLASS="FILENAME"
+>standard.action</TT
+> is also included. This is mostly
+ for <SPAN
+CLASS="APPLICATION"
+>Privoxy's</SPAN
+> internal use.
+ </P
+><P
+>
+ There is also a web based editor that can be accessed from
+ <A
+HREF="http://config.privoxy.org/show-status/"
TARGET="_top"
->http://config.privoxy.org/edit-actions/</A
+>http://config.privoxy.org/show-status/</A
>
(Shortcut: <A
-HREF="http://p.p/edit-actions/"
+HREF="http://p.p/show-status/"
TARGET="_top"
->http://p.p/edit-actions/</A
->).
- (Other actions files are included as well with differing levels of filtering
- and blocking, e.g. <TT
-CLASS="FILENAME"
->basic.action</TT
->.)
+>http://p.p/show-status/</A
+>) for the
+ various actions files.
</P
></LI
><LI
> <TT
CLASS="FILENAME"
>default.filter</TT
-> (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 file.
+> (the <A
+HREF="configuration.html#FILTER-FILE"
+>filter
+ file</A
+>) 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.
</P
></LI
></UL
>#</TT
>"</SPAN
> character to denote a
- comment (the rest of the line will be ignored) and understand line continuation
+ comment (the rest of the line will be ignored) angd understand line continuation
through placing a backslash ("<TT
CLASS="LITERAL"
>\</TT
valid configuration line to prevent it from being interpreted is called "commenting
out" that line.</P
><P
-> <TT
-CLASS="FILENAME"
->default.action</TT
-> and <TT
+> The actions files and <TT
CLASS="FILENAME"
>default.filter</TT
>
><H2
CLASS="SECT2"
><A
-NAME="AEN383"
->5.3. The Main Configuration File</A
+NAME="CONFIG"
+>7.3. The Main Configuration File</A
></H2
><P
> Again, the main configuration file is named <TT
><H3
CLASS="SECT3"
><A
-NAME="AEN402"
->5.3.1. Configuration and Log File Locations</A
+NAME="CONF-LOG-LOC"
+>7.3.1. Configuration and Log File Locations</A
></H3
><P
> <SPAN
><H4
CLASS="SECT4"
><A
-NAME="AEN407"
->5.3.1.1. confdir</A
+NAME="CONFDIR"
+>7.3.1.1. confdir</A
></H4
><P
></P
><H4
CLASS="SECT4"
><A
-NAME="AEN439"
->5.3.1.2. logdir</A
+NAME="LOGDIR"
+>7.3.1.2. logdir</A
></H4
><P
></P
><H4
CLASS="SECT4"
><A
-NAME="AEN469"
->5.3.1.3. actionsfile</A
+NAME="ACTIONSFILE"
+>7.3.1.3. <A
+NAME="DEFAULT.ACTION"
+></A
+>
+<A
+NAME="STANDARD.ACTION"
+></A
+>
+<A
+NAME="USER.ACTION"
+></A
+>
+actionsfile</A
></H4
><P
></P
>Specifies:</DT
><DD
><P
-> The actions file to use
+> The <A
+HREF="configuration.html#ACTIONS"
+>actions</A
+> file(s) to use
</P
></DD
><DT
>Default value:</DT
><DD
><P
->default.action (Unix) <I
-CLASS="EMPHASIS"
->or</I
-> default.action.txt (Windows)</P
+></P
+><TABLE
+BORDER="0"
+><TBODY
+><TR
+><TD
+> <P
+CLASS="LITERALLAYOUT"
+> standard # Internal purposes, recommended not editing</P
+>
+ </TD
+></TR
+><TR
+><TD
+> <P
+CLASS="LITERALLAYOUT"
+> default # Main actions file</P
+>
+ </TD
+></TR
+><TR
+><TD
+> <P
+CLASS="LITERALLAYOUT"
+> user # User customizations</P
+>
+ </TD
+></TR
+></TBODY
+></TABLE
+><P
+></P
></DD
><DT
>Effect if unset:</DT
><DD
><P
-> No action is taken at all. Simple neutral proxying.
+> No actions are taken at all. Simple neutral proxying.
</P
></DD
><DT
>Notes:</DT
><DD
><P
-> There is no point in using <SPAN
-CLASS="APPLICATION"
->Privoxy</SPAN
-> without
- an actions file. There are three different actions files included in the
- distribution, with varying degrees of aggressiveness:
- <TT
-CLASS="FILENAME"
->default.action</TT
->, <TT
-CLASS="FILENAME"
->intermediate.action</TT
-> and
+> Multiple <TT
+CLASS="LITERAL"
+>actionsfile</TT
+> lines are OK and are in fact recommended!
+ </P
+><P
+>
+ The default values include standard.action, which is used for internal
+ purposes and should be loaded, default.action, which is the
+ <SPAN
+CLASS="QUOTE"
+>"main"</SPAN
+> actions file maintained by the developers, and
<TT
CLASS="FILENAME"
->advanced.action</TT
->.
+>user.action</TT
+>, where you can make your personal additions.
+ </P
+><P
+>
+ There is no point in using <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+> without an actions file.
</P
></DD
></DL
><H4
CLASS="SECT4"
><A
-NAME="AEN498"
->5.3.1.4. filterfile</A
+NAME="FILTERFILE"
+>7.3.1.4. <A
+NAME="DEFAULT.FILTER"
+></A
+>filterfile</A
></H4
><P
></P
>Specifies:</DT
><DD
><P
-> The filter file to use
+> The <A
+HREF="configuration.html#FILTER"
+>filter</A
+> file to use
</P
></DD
><DT
></TT
>}</TT
>
- actions in the actions file are turned off
+ actions in the actions files are turned off
</P
></DD
><DT
><H4
CLASS="SECT4"
><A
-NAME="AEN529"
->5.3.1.5. logfile</A
+NAME="LOGFILE"
+>7.3.1.5. logfile</A
></H4
><P
></P
><H4
CLASS="SECT4"
><A
-NAME="AEN564"
->5.3.1.6. jarfile</A
+NAME="JARFILE"
+>7.3.1.6. jarfile</A
></H4
><P
></P
><H4
CLASS="SECT4"
><A
-NAME="AEN589"
->5.3.1.7. trustfile</A
+NAME="TRUSTFILE"
+>7.3.1.7. trustfile</A
></H4
><P
></P
><H3
CLASS="SECT3"
><A
-NAME="AEN622"
->5.3.2. Local Set-up Documentation</A
+NAME="LOCAL-SET-UP"
+>7.3.2. Local Set-up Documentation</A
></H3
><P
> If you intend to operate <SPAN
><H4
CLASS="SECT4"
><A
-NAME="AEN626"
->5.3.2.1. trust-info-url</A
+NAME="TRUST-INFO-URL"
+>7.3.2.1. trust-info-url</A
></H4
><P
></P
><H4
CLASS="SECT4"
><A
-NAME="AEN652"
->5.3.2.2. admin-address</A
+NAME="ADMIN-ADDRESS"
+>7.3.2.2. admin-address</A
></H4
><P
></P
><H4
CLASS="SECT4"
><A
-NAME="AEN678"
->5.3.2.3. proxy-info-url</A
+NAME="PROXY-INFO-URL"
+>7.3.2.3. proxy-info-url</A
></H4
><P
></P
><H3
CLASS="SECT3"
><A
-NAME="AEN706"
->5.3.3. Debugging</A
+NAME="DEBUGGING"
+>7.3.3. Debugging</A
></H3
><P
> These options are mainly useful when tracing a problem.
><H4
CLASS="SECT4"
><A
-NAME="AEN711"
->5.3.3.1. debug</A
+NAME="DEBUG"
+>7.3.3.1. debug</A
></H4
><P
></P
debug 512 # Common Log Format
debug 1024 # debug kill pop-ups
debug 4096 # Startup banner and warnings.
- debug 8192 # Non-fatal errors
- </PRE
+ debug 8192 # Non-fatal errors</PRE
></TD
></TR
></TABLE
><H4
CLASS="SECT4"
><A
-NAME="AEN746"
->5.3.3.2. single-threaded</A
+NAME="SINGLE-THREADED"
+>7.3.3.2. single-threaded</A
></H4
><P
></P
><H3
CLASS="SECT3"
><A
-NAME="AEN772"
->5.3.4. Access Control and Security</A
+NAME="ACCESS-CONTROL"
+>7.3.4. Access Control and Security</A
></H3
><P
> This section of the config file controls the security-relevant aspects
><H4
CLASS="SECT4"
><A
-NAME="AEN776"
->5.3.4.1. listen-address</A
+NAME="LISTEN-ADDRESS"
+>7.3.4.1. listen-address</A
></H4
><P
></P
>Privoxy</SPAN
> 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)
+ from the Internet. In that case, consider using access control lists (ACL's)
(see <SPAN
CLASS="QUOTE"
>"ACLs"</SPAN
><TD
><PRE
CLASS="PROGRAMLISTING"
-> listen-address 192.168.0.1:8118
- </PRE
+> listen-address 192.168.0.1:8118</PRE
></TD
></TR
></TABLE
><H4
CLASS="SECT4"
><A
-NAME="AEN814"
->5.3.4.2. toggle</A
+NAME="TOGGLE"
+>7.3.4.2. toggle</A
></H4
><P
></P
><H4
CLASS="SECT4"
><A
-NAME="AEN843"
->5.3.4.3. enable-remote-toggle</A
+NAME="ENABLE-REMOTE-TOGGLE"
+>7.3.4.3. enable-remote-toggle</A
></H4
><P
></P
><H4
CLASS="SECT4"
><A
-NAME="AEN877"
->5.3.4.4. enable-edit-actions</A
+NAME="ENABLE-EDIT-ACTIONS"
+>7.3.4.4. enable-edit-actions</A
></H4
><P
></P
><DD
><P
> Whether or not the <A
-HREF="http://config.privoxy.org/edit-actions"
+HREF="http://config.privoxy.org/show-status"
TARGET="_top"
>web-based actions
file editor</A
><H4
CLASS="SECT4"
><A
-NAME="AEN909"
->5.3.4.5. ACLs: permit-access and deny-access</A
+NAME="ACLS"
+>7.3.4.5. <A
+NAME="PERMIT-ACCES"
+></A
+>
+<A
+NAME="DENY-ACCES"
+></A
+>
+ACLs: permit-access and deny-access</A
></H4
><P
></P
><TD
><PRE
CLASS="SCREEN"
-> permit-access localhost
- </PRE
+> permit-access localhost</PRE
></TD
></TR
></TABLE
><TD
><PRE
CLASS="SCREEN"
-> permit-access www.privoxy.org/24 www.example.com/32
- </PRE
+> permit-access www.privoxy.org/24 www.example.com/32</PRE
></TD
></TR
></TABLE
><PRE
CLASS="SCREEN"
> permit-access 192.168.45.64/26
- deny-access 192.168.45.73 www.dirty-stuff.example.com
- </PRE
+ deny-access 192.168.45.73 www.dirty-stuff.example.com</PRE
></TD
></TR
></TABLE
><H4
CLASS="SECT4"
><A
-NAME="AEN978"
->5.3.4.6. buffer-limit</A
+NAME="BUFFER-LIMIT"
+>7.3.4.6. buffer-limit</A
></H4
><P
></P
CLASS="SECT3"
><A
NAME="FORWARDING"
->5.3.5. Forwarding</A
+>7.3.5. Forwarding</A
></H3
><P
> This feature allows routing of HTTP requests through a chain of
><H4
CLASS="SECT4"
><A
-NAME="AEN1016"
->5.3.5.1. forward</A
+NAME="FORWARD"
+>7.3.5.1. forward</A
></H4
><P
></P
>target_domain</I
></TT
> is a domain name pattern (see the
- chapter on domain matching in the actions file),
+ chapter on domain matching in the <TT
+CLASS="FILENAME"
+>default.action</TT
+> file),
<TT
CLASS="REPLACEABLE"
><I
><PRE
CLASS="SCREEN"
> forward .* anon-proxy.example.org:8080
- forward :443 .
- </PRE
+ forward :443 .</PRE
></TD
></TR
></TABLE
><PRE
CLASS="SCREEN"
> forward .*. caching-proxy.example-isp.net:8000
- forward .example-isp.net .
- </PRE
+ forward .example-isp.net .</PRE
></TD
></TR
></TABLE
><H4
CLASS="SECT4"
><A
-NAME="AEN1062"
->5.3.5.2. forward-socks4 and forward-socks4a</A
+NAME="SOCKS"
+>7.3.5.2. <A
+NAME="FORWARD-SOCKS4"
+></A
+>
+<A
+NAME="FORWARD-SOCKS4A"
+></A
+>
+forward-socks4 and forward-socks4a</A
></H4
><P
></P
>target_domain</I
></TT
> is a domain name pattern (see the
- chapter on domain matching in the actions file),
+ chapter on domain matching in the <TT
+CLASS="FILENAME"
+>default.action</TT
+> file),
<TT
CLASS="REPLACEABLE"
><I
><PRE
CLASS="SCREEN"
> forward-socks4a .*. socks-gw.example.com:1080 www-cache.example-isp.net:8080
- forward .example.com .
- </PRE
+ forward .example.com .</PRE
></TD
></TR
></TABLE
><TD
><PRE
CLASS="SCREEN"
-> forward-socks4 .*. socks-gw.example.com:1080 .
- </PRE
+> forward-socks4 .*. socks-gw.example.com:1080 .</PRE
></TD
></TR
></TABLE
><H4
CLASS="SECT4"
><A
-NAME="AEN1116"
->5.3.5.3. Advanced Forwarding Examples</A
+NAME="ADVANCED-FORWARDING-EXAMPLES"
+>7.3.5.3. Advanced Forwarding Examples</A
></H4
><P
> If you have links to multiple ISPs that provide various special content
><PRE
CLASS="SCREEN"
> forward .*. .
- forward .isp-b.net host-b:8118
- </PRE
+ forward .isp-b.net host-b:8118</PRE
></TD
></TR
></TABLE
><PRE
CLASS="SCREEN"
> forward .*. .
- forward .isp-a.net host-a:8118
- </PRE
+ forward .isp-a.net host-a:8118</PRE
></TD
></TR
></TABLE
always_direct allow ftp
# Forward all the rest to Privoxy
- never_direct allow all
- </PRE
+ never_direct allow all</PRE
></TD
></TR
></TABLE
><H3
CLASS="SECT3"
><A
-NAME="AEN1143"
->5.3.6. Windows GUI Options</A
+NAME="WINDOWS-GUI"
+>7.3.6. Windows GUI Options</A
></H3
><P
> <SPAN
>Privoxy</SPAN
> has a number of options specific to the
Windows GUI interface:</P
+><A
+NAME="ACTIVITY-ANIMATION"
+></A
><P
> If <SPAN
CLASS="QUOTE"
>
</TT
></P
+><A
+NAME="LOG-MESSAGES"
+></A
><P
> If <SPAN
CLASS="QUOTE"
>
</TT
></P
+><A
+NAME="LOG-BUFFER-SIZE"
+></A
><P
>
If <SPAN
>
</TT
></P
+><A
+NAME="LOG-MAX-LINES"
+></A
><P
> <SPAN
CLASS="APPLICATION"
>
</TT
></P
+><A
+NAME="LOG-HIGHLIGHT-MESSAGES"
+></A
><P
> If <SPAN
CLASS="QUOTE"
>
</TT
></P
+><A
+NAME="LOG-FONT-NAME"
+></A
><P
> The font used in the console window:</P
><P
>
</TT
></P
+><A
+NAME="LOG-FONT-SIZE"
+></A
><P
> Font size used in the console window:</P
><P
>
</TT
></P
+><A
+NAME="SHOW-ON-TASK-BAR"
+></A
><P
>
<SPAN
>
</TT
></P
+><A
+NAME="CLOSE-BUTTON-MINIMIZES"
+></A
><P
> If <SPAN
CLASS="QUOTE"
>
</TT
></P
+><A
+NAME="HIDE-CONSOLE"
+></A
><P
> The <SPAN
CLASS="QUOTE"
><H2
CLASS="SECT2"
><A
-NAME="ACTIONSFILE"
->5.4. The Actions File</A
+NAME="ACTIONS-FILE"
+>7.4. Actions Files</A
></H2
><P
-> The actions file (<TT
+> The actions files are used to define what actions
+ <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+> takes for which URLs, and thus determines
+ how ad images, cookies and various other aspects of HTTP content and
+ transactions are handled, and on which sites (or even parts thereof). There
+ are three such files included with <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+>,
+ with slightly different purposes. <TT
CLASS="FILENAME"
>default.action</TT
->, formerly:
- <TT
-CLASS="FILENAME"
->actionsfile</TT
-> or <TT
+> sets
+ the default policies. <TT
CLASS="FILENAME"
->ijb.action</TT
->) is used
- to define what actions <SPAN
+>standard.action</TT
+> is used by
+ <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
-> takes for which
- URLs, and thus determines how ad images, cookies and various other aspects
- of HTTP content and transactions are handled on which sites (or even parts
- thereof).</P
+> and the web based editor to set
+ pre-defined values (and normally should not be edited). Local exceptions
+ are best done in <TT
+CLASS="FILENAME"
+>user.action</TT
+>. The content of these
+ can all be viewed and edited from <A
+HREF="http://config.privoxy.org/show-status"
+TARGET="_top"
+>http://config.privoxy.org/show-status</A
+>.
+ </P
><P
>
Anything you want can blocked, including ads, banners, or just some obnoxious
- URL that you would rather not see. Cookies can be accepted or rejected, or
+ URL that you would rather not see is done here. Cookies can be accepted or rejected, or
accepted only during the current browser session (i.e. not written to disk),
content can be modified, JavaScripts tamed, user-tracking fooled, and much more.
See below for a complete list of available actions.</P
><P
-> An actions file typically has sections. At the top, <SPAN
+> An actions file typically has sections. Near the top, <SPAN
CLASS="QUOTE"
>"aliases"</SPAN
> are
- defined (discussed below), then the default set of rules which will apply
- universally to all sites and pages. And then below that is generally a lengthy
- set of exceptions to the defined universal policies.</P
+ optionally defined (discussed <A
+HREF="configuration.html#ALIASES"
+TARGET="_top"
+>below</A
+>), then the default set of rules
+ which will apply universally to all sites and pages. And then below that,
+ exceptions to the defined universal policies. </P
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
-NAME="AEN1234"
->5.4.1. Finding the Right Mix</A
+NAME="AEN1285"
+>7.4.1. Finding the Right Mix</A
></H3
><P
-> Note that some actions like cookie suppression or script disabling may
- render some sites unusable, which rely on these techniques to work properly.
- Finding the right mix of actions is not easy and certainly a matter of personal
- taste. In general, it can be said that the more <SPAN
+> Note that some <A
+HREF="configuration.html#ACTIONS"
+>actions</A
+> like cookie suppression
+ or script disabling may render some sites unusable, which rely on these
+ techniques to work properly. Finding the right mix of actions is not easy and
+ certainly a matter of personal taste. In general, it can be said that the more
+ <SPAN
CLASS="QUOTE"
>"aggressive"</SPAN
->
- your default settings (in the top section of the actions file) are,
- the more exceptions for <SPAN
+> your default settings (in the top section of the
+ actions file) are, the more exceptions for <SPAN
CLASS="QUOTE"
>"trusted"</SPAN
-> sites you will have to
- make later. If, for example, you want to kill popup windows per default, you'll
- have to make exceptions from that rule for sites that you regularly use
- and that require popups for actually useful content, like maybe your bank,
- favorite shop, or newspaper.</P
+> sites you
+ will have to make later. If, for example, you want to kill popup windows per
+ default, you'll have to make exceptions from that rule for sites that you
+ regularly use and that require popups for actually useful content, like maybe
+ your bank, favorite shop, or newspaper.</P
><P
> We have tried to provide you with reasonable rules to start from in the
- distribution actions file. But there is no general rule of thumb on these
+ 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).</P
+ Sooner or later you will want to change the rules (and read this chapter again :).</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
-NAME="AEN1240"
->5.4.2. How to Edit</A
+NAME="AEN1292"
+>7.4.2. How to Edit</A
></H3
><P
> The easiest way to edit the <SPAN
CLASS="QUOTE"
>"actions"</SPAN
-> file is with a browser by
- using our browser-based editor, which
is available at <A
-HREF="http://config.privoxy.org/edit-actions"
+> files is with a browser by
+ using our browser-based editor, which
can be reached from <A
+HREF="http://config.privoxy.org/show-status"
TARGET="_top"
->http://config.privoxy.org/edit-actions</A
+>http://config.privoxy.org/show-status</A
>.</P
><P
> If you prefer plain text editing to GUIs, you can of course also directly edit the
- <TT
-CLASS="FILENAME"
->default.action</TT
-> file.</P
+ the actions files.</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
-NAME="AEN1247"
->5.4.3. How Actions are Applied to URLs</A
+NAME="AEN1298"
+>7.4.3. How Actions are Applied to URLs</A
></H3
><P
-> The actions file is divided into sections. There are special sections,
+> Actions files are divided into sections. There are special sections,
like the <SPAN
CLASS="QUOTE"
->"alias"</SPAN
+>"<A
+HREF="configuration.html#ALIASES"
+>alias</A
+>"</SPAN
> 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,
compared to all patterns in this file. Every time it matches, the list of
applicable actions for the URL is incrementally updated, using the heading
of the section in which the pattern is located. If multiple matches for
- the same URL set the same action differently, the last match wins.</P
+ the same URL set the same action differently, the last match wins. If not,
+ the effects are aggregated (e.g. a URL might match both the
+ <A
+HREF="configuration.html#HANDLE-AS-IMAGE"
+TARGET="_top"
+><SPAN
+CLASS="QUOTE"
+>"+handle-as-image"</SPAN
+></A
+>
+ and <A
+HREF="configuration.html#BLOCK"
+TARGET="_top"
+><SPAN
+CLASS="QUOTE"
+>"+block"</SPAN
+></A
+> actions).
+ </P
><P
> You can trace this process by visiting <A
HREF="http://config.privoxy.org/show-url-info"
><H3
CLASS="SECT3"
><A
-NAME="AEN1256"
->5.4.4. Patterns</A
+NAME="AEN1312"
+>7.4.4. Patterns</A
></H3
><P
> Generally, a pattern has the form <TT
><H4
CLASS="SECT4"
><A
-NAME="AEN1296"
->5.4.4.1. The Domain Pattern</A
+NAME="AEN1352"
+>7.4.4.1. The Domain Pattern</A
></H4
><P
> The matching of the domain part offers some flexible options: if the
><H4
CLASS="SECT4"
><A
-NAME="AEN1358"
->5.4.4.2. The Path Pattern</A
+NAME="AEN1414"
+>7.4.4.2. The Path Pattern</A
></H4
><P
> <SPAN
i.e. it matches as if it would start with a <SPAN
CLASS="QUOTE"
>"^"</SPAN
->.</P
+> (regular expression speak
+ for the beginning of a line).</P
><P
> Please also note that matching in the path is case
<I
CLASS="SECT3"
><A
NAME="ACTIONS"
->5.4.5. Actions</A
+>7.4.5. Actions</A
></H3
><P
-> Actions are enabled if preceded with a <SPAN
+> All actions are disabled by default, until they are explicitly enabled
+ somewhere in an actions file. Actions are turned on if preceded with a
+ <SPAN
CLASS="QUOTE"
>"+"</SPAN
->, and disabled if
- preceded with a <SPAN
+>, and turned off if preceded with a <SPAN
CLASS="QUOTE"
>"-"</SPAN
->. So a <SPAN
+>. So a
+ <SPAN
CLASS="QUOTE"
>"+action"</SPAN
-> means
- <SPAN
+> means <SPAN
CLASS="QUOTE"
>"do that action"</SPAN
->, e.g. <SPAN
+>, e.g.
+ <SPAN
CLASS="QUOTE"
>"+block"</SPAN
-> means please
- <SPAN
+> means please <SPAN
CLASS="QUOTE"
->"block the following URLs and/or patterns"</SPAN
->. All actions are
- disabled by default, until they are explicitly enabled somewhere in an actions
- file.</P
+>"block the following URL
+ patterns"</SPAN
+>. </P
><P
>
Actions are invoked by enclosing the action name in curly braces (e.g.
Multi-value, e.g. <SPAN
CLASS="QUOTE"
>"{+/-add-header{Name: value}}"</SPAN
-> ot
+> or
<SPAN
CLASS="QUOTE"
->"{+/-wafer{name=value}}"</SPAN
+>"{+/-send-wafer{name=value}}"</SPAN
>), where some value needs to be defined
- in addition to simply enabling the actino. Examples:
+ in addition to simply enabling the action. Examples:
</P
><P
> <TT
></UL
></P
><P
-> If nothing is specified in this file, no <SPAN
+> If nothing is specified in any actions file, no <SPAN
CLASS="QUOTE"
>"actions"</SPAN
-> are taken.
- So in this case <SPAN
+> are
+ taken. So in this case <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
> would just be a
- normal, non-blocking, non-anonymizing proxy. You must specifically
- enable the privacy and blocking features you need (although the
- provided default <TT
-CLASS="FILENAME"
->default.action</TT
-> file will
- give a good starting point).</P
+ normal, non-blocking, non-anonymizing proxy. You must specifically enable the
+ privacy and blocking features you need (although the provided default actions
+ files will give a good starting point).</P
><P
> Later defined actions always over-ride earlier ones. So exceptions
to any rules you make, should come in the latter part of the file. For
multi-valued actions, the actions are applied in the order they are
- specified.</P
+ specified. Actions files are processed in the order they are defined
+ in <TT
+CLASS="FILENAME"
+>config</TT
+> (the default installation has three
+ actions files). It also quite possible for any given URL pattern to
+ match more than one action!</P
><P
> The list of valid <SPAN
CLASS="APPLICATION"
CLASS="SECT4"
><A
NAME="ADD-HEADER"
->5.4.5.1. <I
+>7.4.5.1. <I
CLASS="EMPHASIS"
>+add-header{Name: value}</I
></A
CLASS="SECT4"
><A
NAME="BLOCK"
->5.4.5.2. <I
+>7.4.5.2. <I
CLASS="EMPHASIS"
>+block</I
></A
><br>
<I
CLASS="EMPHASIS"
->.example.com</I
+>.banners.example.com</I
><br>
<I
CLASS="EMPHASIS"
>Notes:</DT
><DD
><P
-> <SPAN
+> If a URL matches one of the blocked patterns, <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
-> will display its
- special <SPAN
+>
+ will intercept the URL and display its special <SPAN
CLASS="QUOTE"
>"BLOCKED"</SPAN
-> page if a URL matches one of the
- blocked patterns. If there is sufficient space, a large red
- banner will appear with a friendly message about why the page
- was blocked, and a way to go there anyway. If there is insufficient
- space a smaller blocked page will appear without the red banner.
- One exception is if the URL matches both <SPAN
+> page
+ instead. If there is sufficient space, a large red banner will appear with
+ a friendly message about why the page was blocked, and a way to go there
+ anyway. If there is insufficient space a smaller blocked page will appear
+ without the red banner.
+ <A
+HREF="http://ads.bannerserver.example.com/nasty-ads/sponsor.html"
+TARGET="_top"
+>Click here</A
+>
+ to view the default blocked HTML page (<SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+> must be running
+ for this to work as intended!).
+ </P
+><P
+>
+ A very important exception is if the URL <I
+CLASS="EMPHASIS"
+>matches both</I
+>
+ <SPAN
CLASS="QUOTE"
>"+block"</SPAN
->
- and <SPAN
+> and <A
+HREF="configuration.html#HANDLE-AS-IMAGE"
+TARGET="_top"
+><SPAN
CLASS="QUOTE"
->"+image"</SPAN
->, then it can be handled by
- <SPAN
+>"+handle-as-image"</SPAN
+></A
+>,
+ then it will be handled by
+ <A
+HREF="configuration.html#SET-IMAGE-BLOCKER"
+TARGET="_top"
+><SPAN
CLASS="QUOTE"
->"+image-blocker"</SPAN
-> (see below).
+>"+set-image-blocker"</SPAN
+></A
+>
+ (see below). It is important to understand this process, in order
+ to understand how <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+> is able to deal with
+ ads and other objectionable content.
</P
><P
-> The <SPAN
+> The <A
+HREF="configuration.html#FILTER"
+TARGET="_top"
+><SPAN
CLASS="QUOTE"
>"+filter"</SPAN
-> action can also perform some of the
+></A
+>
+ action can also perform some of the
same functionality as <SPAN
CLASS="QUOTE"
>"+block"</SPAN
>, but by virtue of very
- different programming techniques, and is typically used for different
+ different programming techniques, and is most often used for different
reasons.
</P
></DD
CLASS="SECT4"
><A
NAME="DEANIMATE-GIFS"
->5.4.5.3. <I
+>7.4.5.3. <I
CLASS="EMPHASIS"
>+deanimate-gifs</I
></A
><H4
CLASS="SECT4"
><A
-NAME="DOWNGRADE"
->5.4.5.4. <I
+NAME="DOWNGRADE-HTTP-VERSION"
+>7.4.5.4. <I
CLASS="EMPHASIS"
->+downgrade</I
+>+downgrade-http-version</I
></A
></H4
><P
><P
> <SPAN
CLASS="QUOTE"
->"+downgrade"</SPAN
+>"+downgrade-http-version"</SPAN
> will downgrade HTTP/1.1 client requests to
HTTP/1.0 and downgrade the responses as well.
</P
CLASS="LITERALLAYOUT"
> <I
CLASS="EMPHASIS"
->{+downgrade}</I
+>{+downgrade-http-version}</I
><br>
<I
CLASS="EMPHASIS"
>Privoxy</SPAN
> doesn't handle well yet. HTTP/1.1 is
only partially implemented. Default is not to downgrade requests. This is
- an infrequently needed action, and is used to help with problem sites only.
+ an infrequently needed action, and is used to help with rare problem sites only.
</P
></DD
></DL
CLASS="SECT4"
><A
NAME="FAST-REDIRECTS"
->5.4.5.5. <I
+>7.4.5.5. <I
CLASS="EMPHASIS"
>+fast-redirects</I
></A
CLASS="APPLICATION"
>Privoxy</SPAN
> can cut off
- all but the last valid URL in redirect request and send a local redirect
+ all but the last valid URL in a redirect request and send a local redirect
back to your browser without contacting the intermediate site(s).
</P
></DD
the advertisers.
</P
><P
-> This is a normally on feature, and often requires exceptions for sites that
- are sensitive to defeating this mechanism.
+> This is a normally <SPAN
+CLASS="QUOTE"
+>"on"</SPAN
+> feature, and often requires exceptions
+ for sites that are sensitive to defeating this mechanism.
</P
></DD
></DL
CLASS="SECT4"
><A
NAME="FILTER"
->5.4.5.6. <I
+>7.4.5.6. <I
CLASS="EMPHASIS"
>+filter</I
></A
CLASS="QUOTE"
>"roll your own"</SPAN
>.
- Filtering operates on a line by line basis.
+ Filtering operates on a line by line basis throughout the entire page.
</P
><P
> Filtering requires buffering the page content, which may appear to
noticeable on slower connections.
</P
><P
-> Filtering can achieve some of the effects as the <SPAN
+> Filtering can achieve some of the effects as the
+ <A
+HREF="configuration.html#BLOCK"
+TARGET="_top"
+><SPAN
CLASS="QUOTE"
>"+block"</SPAN
->
+></A
+>
action, i.e. it can be used to block ads and banners. In the overall
- scheme of things, filtering is one of the last things <SPAN
+ scheme of things, filtering is one of the first things <SPAN
CLASS="QUOTE"
>"Privoxy"</SPAN
>
- does with a web page. So other actions are applied first.
+ does with a web page. So other most other actions are applied to the
+ already <SPAN
+CLASS="QUOTE"
+>"filtered"</SPAN
+> page.
</P
></DD
></DL
><H4
CLASS="SECT4"
><A
-NAME="HIDE-FORWARDED"
->5.4.5.7. <I
+NAME="HIDE-FORWARDED-FOR-HEADERS"
+>7.4.5.7. <I
CLASS="EMPHASIS"
->+hide-forwarded</I
+>+hide-forwarded-for-headers</I
></A
></H4
><P
CLASS="LITERALLAYOUT"
> <I
CLASS="EMPHASIS"
->{+hide-forwarded}</I
+>{+hide-forwarded-for-headers}</I
><br>
<I
CLASS="EMPHASIS"
><H4
CLASS="SECT4"
><A
-NAME="HIDE-FROM"
->5.4.5.8. <I
+NAME="HIDE-FROM-HEADER"
+>7.4.5.8. <I
CLASS="EMPHASIS"
->+hide-from</I
+>+hide-from-header</I
></A
></H4
><P
CLASS="LITERALLAYOUT"
> <I
CLASS="EMPHASIS"
->{+hide-from{block}}</I
+>{+hide-from-header{block}}</I
><br>
<I
CLASS="EMPHASIS"
> The keyword <SPAN
CLASS="QUOTE"
>"block"</SPAN
-> will completely remove the header.
+> will completely remove the header
+ (not to be confused with the <A
+HREF="configuration.html#BLOCK"
+TARGET="_top"
+><SPAN
+CLASS="QUOTE"
+>"+block"</SPAN
+></A
+> action).
Alternately, you can specify any value you prefer to send to the web
server.
</P
CLASS="SECT4"
><A
NAME="HIDE-REFERER"
->5.4.5.9. <I
+>7.4.5.9. <I
CLASS="EMPHASIS"
->+hide-referer</I
-></A
-></H4
><A
NAME="HIDE-REFERRER"
></A
+>+hide-referer</I
+></A
+></H4
><P
></P
><DIV
CLASS="SECT4"
><A
NAME="HIDE-USER-AGENT"
->5.4.5.10. <I
+>7.4.5.10. <I
CLASS="EMPHASIS"
>+hide-user-agent</I
></A
><H4
CLASS="SECT4"
><A
-NAME="IMAGE"
->5.4.5.11. <I
+NAME="HANDLE-AS-IMAGE"
+>7.4.5.11. <I
CLASS="EMPHASIS"
->+image</I
+>+handle-as-image</I
></A
></H4
><P
CLASS="APPLICATION"
>Privoxy</SPAN
> should treat
- automatically as an image.
+ automatically as an image, and is an important ingredient of how
+ ads are handled.
</P
></DD
><DT
CLASS="LITERALLAYOUT"
> <I
CLASS="EMPHASIS"
->{+image}</I
+>{+handle-as-image}</I
><br>
<I
CLASS="EMPHASIS"
<SPAN
CLASS="QUOTE"
>"+block"</SPAN
->ed, in which case a <SPAN
+>ed, in which case a user definable image can
+ be sent rather than a HTML page. This is integral to the whole concept of
+ ad blocking: the URL must match <I
+CLASS="EMPHASIS"
+>both</I
+> a <A
+HREF="configuration.html#BLOCK"
+TARGET="_top"
+><SPAN
CLASS="QUOTE"
->"blocked"</SPAN
-> image can
- be sent rather than a HTML page. (See <SPAN
+>"+block"</SPAN
+></A
+> rule,
+ <I
+CLASS="EMPHASIS"
+>and</I
+> <SPAN
CLASS="QUOTE"
->"+image-blocker{}"</SPAN
-> below
- for the control over what is actually sent.)
+>"+handle-as-image"</SPAN
+>.
+ (See <A
+HREF="configuration.html#SET-IMAGE-BLOCKER"
+TARGET="_top"
+><SPAN
+CLASS="QUOTE"
+>"+set-image-blocker"</SPAN
+></A
+>
+ below for control over what will actually be displayed by the browser.)
</P
><P
-> There is little reason to change the default definition for this.
+> There is little reason to change the default definition for this action.
</P
></DD
></DL
><H4
CLASS="SECT4"
><A
-NAME="IMAGE-BLOCKER"
->5.4.5.12. <I
+NAME="SET-IMAGE-BLOCKER"
+>7.4.5.12. <I
CLASS="EMPHASIS"
->+image-blocker</I
+>+set-image-blocker</I
></A
></H4
><P
>Typical uses:</DT
><DD
><P
-> Decide what to do with URLs that end up tagged with both <SPAN
+> Decide what to do with URLs that end up tagged with <I
+CLASS="EMPHASIS"
+>both</I
+>
+ <A
+HREF="configuration.html#BLOCK"
+TARGET="_top"
+><SPAN
CLASS="QUOTE"
->"{+block}"</SPAN
+>"+block"</SPAN
+></A
>
- and <SPAN
+ and <A
+HREF="configuration.html#HANDLE-AS-IMAGE"
+TARGET="_top"
+><SPAN
CLASS="QUOTE"
->"{+image}"</SPAN
->, e.g an advertisement.
+>"+handle-as-image"</SPAN
+></A
+>,
+ e.g an advertisement.
</P
></DD
><DT
><P
> There are four available options: <SPAN
CLASS="QUOTE"
->"-image-blocker"</SPAN
+>"-set-image-blocker"</SPAN
> will send a HTML
<SPAN
CLASS="QUOTE"
CLASS="QUOTE"
>"broken
image"</SPAN
-> icon. <SPAN
+> icon.
+ <SPAN
CLASS="QUOTE"
->"+image-blocker{blank}"</SPAN
-> will send a 1x1
- transparent GIF image. <SPAN
+>"+set-image-blocker{<I
+CLASS="EMPHASIS"
+>blank</I
+>}"</SPAN
+> will send a
+ 1x1 transparent GIF image.
+ <SPAN
CLASS="QUOTE"
->"+image-blocker{pattern}"</SPAN
+>"+set-image-blocker{<I
+CLASS="EMPHASIS"
+>pattern</I
+>}"</SPAN
> will send a
checkerboard type pattern (the default). And finally,
<SPAN
CLASS="QUOTE"
->"+image-blocker{http://xyz.com}"</SPAN
-> will send a HTTP temporary
- redirect to the specified image. This has the advantage of the icon being
- being cached by the browser, which will speed up the display.
+>"+set-image-blocker{<I
+CLASS="EMPHASIS"
+>http://xyz.com</I
+>}"</SPAN
+> will
+ send a HTTP temporary redirect to the specified image. This has the
+ advantage of the icon being being cached by the browser, which will speed
+ up the display.
</P
></DD
><DT
CLASS="LITERALLAYOUT"
> <I
CLASS="EMPHASIS"
->{+image-blocker{blank}}</I
+>{+set-image-blocker{blank}}</I
><br>
<I
CLASS="EMPHASIS"
> If you want <I
CLASS="EMPHASIS"
>invisible</I
-> ads, they need to be both
- defined as <I
+> ads, they need to meet
+ criteria as matching both <I
CLASS="EMPHASIS"
>images</I
> and <I
CLASS="EMPHASIS"
>blocked</I
->.
- And then, <SPAN
+>
+ actions. And then, <SPAN
CLASS="QUOTE"
>"image-blocker"</SPAN
> should be set to
CLASS="QUOTE"
>"blank"</SPAN
> for invisibility. Note you cannot treat HTML pages as
- images in most cases. For instance, frames require an HTML page to display.
- So a frame that is an ad, cannot be treated as an image. Forcing an
- <SPAN
+ images in most cases. For instance, frames require an HTML page to
+ display. So a frame that is an ad, typically cannot be treated as an image.
+ Forcing an <SPAN
CLASS="QUOTE"
>"image"</SPAN
-> in this situation just will not work.
+> in this situation just will not work
+ reliably.
</P
></DD
></DL
CLASS="SECT4"
><A
NAME="LIMIT-CONNECT"
->5.4.5.13. <I
+>7.4.5.13. <I
CLASS="EMPHASIS"
>+limit-connect</I
></A
> <I
CLASS="EMPHASIS"
>+limit-connect{443}</I
-> # This is the default and need not be specified.<br>
+> # This is the default and need not be specified.<br>
<I
CLASS="EMPHASIS"
>+limit-connect{80,443}</I
-> # Ports 80 and 443 are OK.<br>
+> # Ports 80 and 443 are OK.<br>
<I
CLASS="EMPHASIS"
>+limit-connect{-3, 7, 20-100, 500-}</I
-> # Port less than 3, 7, 20 to 100 and above 500 are OK.<br>
+> # Port less than 3, 7, 20 to 100 and above 500 are OK.<br>
</P
></DD
><DT
><H4
CLASS="SECT4"
><A
-NAME="NO-COMPRESSION"
->5.4.5.14. <I
+NAME="PREVENT-COMPRESSION"
+>7.4.5.14. <I
CLASS="EMPHASIS"
->+no-compression</I
+>+prevent-compression</I
></A
></H4
><P
CLASS="LITERALLAYOUT"
> <I
CLASS="EMPHASIS"
->{+no-compression}</I
+>{+prevent-compression}</I
><br>
<I
CLASS="EMPHASIS"
<SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
->, since <SPAN
+>, since
+ <A
+HREF="configuration.html#FILTER"
+TARGET="_top"
+><SPAN
CLASS="QUOTE"
>"+filter"</SPAN
+></A
>,
- <SPAN
+ <A
+HREF="configuration.html#KILL-POPUPS"
+TARGET="_top"
+><SPAN
CLASS="QUOTE"
->"+no-popup"</SPAN
-> and <SPAN
+>"+kill-popups"</SPAN
+></A
+>
+ and <A
+HREF="configuration.html#GIF-DEANIMATE"
+TARGET="_top"
+><SPAN
CLASS="QUOTE"
>"+gif-deanimate"</SPAN
-> will not work
- on compressed data. This will slow down connections to those websites,
- though. Default typically is to turn <SPAN
+></A
+>
+ will not work on compressed data. This will slow down connections to those
+ websites, though. Default typically is to turn
+ <SPAN
CLASS="QUOTE"
->"no-compression"</SPAN
+>"prevent-compression"</SPAN
> on.
</P
></DD
><H4
CLASS="SECT4"
><A
-NAME="NO-COOKIES-KEEP"
->5.4.5.15. <I
+NAME="SESSION-COOKIES-ONLY"
+>7.4.5.15. <I
CLASS="EMPHASIS"
->+no-cookies-keep</I
+>+session-cookies-only</I
></A
></H4
><P
>Typical uses:</DT
><DD
><P
-> Allow cookies for the current browser session only.
+> Allow cookies for the current browser session <I
+CLASS="EMPHASIS"
+>only</I
+>.
</P
></DD
><DT
</P
></DD
><DT
->Example usage:</DT
+>Example usage (disabling):</DT
><DD
><P
CLASS="LITERALLAYOUT"
> <I
CLASS="EMPHASIS"
->{+no-cookies-keep}</I
+>{-session-cookies-only}</I
><br>
<I
CLASS="EMPHASIS"
><P
> If websites set cookies, <SPAN
CLASS="QUOTE"
->"no-cookies-keep"</SPAN
+>"+session-cookies-only"</SPAN
> will make sure
they are erased when you exit and restart your web browser. This makes
profiling cookies useless, but won't break sites which require cookies so
that you can log in for transactions. This is generally turned on for all
- sites. Sometimes referred to as <SPAN
+ sites, and is the recommended setting.
+ </P
+><P
+> <SPAN
CLASS="QUOTE"
->"session cookies"</SPAN
->.
+>"+prevent-*-cookies"</SPAN
+> actions should be turned off as well (see
+ below), for <SPAN
+CLASS="QUOTE"
+>"+session-cookies-only"</SPAN
+> to work. Or, else no cookies
+ will get through at all. For, <SPAN
+CLASS="QUOTE"
+>"persistent"</SPAN
+> cookies that survive
+ across browser sessions, see below as well.
</P
></DD
></DL
><H4
CLASS="SECT4"
><A
-NAME="NO-COOKIES-READ"
->5.4.5.16. <I
+NAME="PREVENT-READING-COOKIES"
+>7.4.5.16. <I
CLASS="EMPHASIS"
->+no-cookies-read</I
+>+prevent-reading-cookies</I
></A
></H4
><P
CLASS="LITERALLAYOUT"
> <I
CLASS="EMPHASIS"
->{+no-cookies-read}</I
+>{+prevent-reading-cookies}</I
><br>
<I
CLASS="EMPHASIS"
><P
> Often used in conjunction with <SPAN
CLASS="QUOTE"
->"+no-cookies-set"</SPAN
+>"+prevent-setting-cookies"</SPAN
> to
- disable persistant cookies completely.
+ disable cookies completely. Note that
+ <A
+HREF="configuration.html#SESSION-COOKIES-ONLY"
+TARGET="_top"
+><SPAN
+CLASS="QUOTE"
+>"+session-cookies-only"</SPAN
+></A
+>
+ requires these to both be disabled (or else it never gets any cookies to cache).
+ </P
+><P
+> For <SPAN
+CLASS="QUOTE"
+>"persistent"</SPAN
+> cookies to work (i.e. they survive across browser
+ sessions and reboots), all three cookie settings should be <SPAN
+CLASS="QUOTE"
+>"off"</SPAN
+>
+ for the specified sites.
</P
></DD
></DL
><H4
CLASS="SECT4"
><A
-NAME="NO-COOKIES-SET"
->5.4.5.17. <I
+NAME="PREVENT-SETTING-COOKIES"
+>7.4.5.17. <I
CLASS="EMPHASIS"
->+no-cookies-set</I
+>+prevent-setting-cookies</I
></A
></H4
><P
>Typical uses:</DT
><DD
><P
-> Explicitly block the web server from sending cookies to your
+> Explicitly block the web server from storing cookies on your
system.
</P
></DD
CLASS="LITERALLAYOUT"
> <I
CLASS="EMPHASIS"
->{+no-cookies-set}</I
+>{+prevent-setting-cookies}</I
><br>
<I
CLASS="EMPHASIS"
><P
> Often used in conjunction with <SPAN
CLASS="QUOTE"
->"+no-cookies-read"</SPAN
+>"+prevent-reading-cookies"</SPAN
> to
- disable persistant cookies completely.
+ disable cookies completely (see above).
</P
></DD
></DL
><H4
CLASS="SECT4"
><A
-NAME="NO-POPUP"
->5.4.5.18. <I
+NAME="KILL-POPUP"
+>7.4.5.18. <I
CLASS="EMPHASIS"
->+no-popup</I
+>+kill-popups<A
+NAME="KILL-POPUPS"
></A
-></H4
-><A
-NAME="NO-POPUPS"
+></I
></A
+></H4
><P
></P
><DIV
CLASS="LITERALLAYOUT"
> <I
CLASS="EMPHASIS"
->{+no-popup}</I
+>{+kill-popups}</I
><br>
<I
CLASS="EMPHASIS"
><P
> <SPAN
CLASS="QUOTE"
->"+no-popup"</SPAN
+>"+kill-popups"</SPAN
> uses a built in filter to disable pop-ups
that use the <TT
CLASS="LITERAL"
>window.open()</TT
-> function, etc.
- </P
-><P
-> An alternate spelling is <SPAN
+> function, etc. This is
+ one of the first actions processed by <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+>
+ as it contacts the remote web server. This action is not always 100% reliable,
+ and is supplemented by <SPAN
CLASS="QUOTE"
->"+no-popups"</SPAN
->, which is
- interchangeable.
- </P
+>"+filter{<I
+CLASS="EMPHASIS"
+>popups</I
+>}"</SPAN
+>.
+ </P
></DD
></DL
></DIV
><H4
CLASS="SECT4"
><A
-NAME="VANILLA-WAFER"
->5.4.5.19. <I
+NAME="SEND-VANILLA-WAFER"
+>7.4.5.19. <I
CLASS="EMPHASIS"
->+vanilla-wafer</I
+>+send-vanilla-wafer</I
></A
></H4
><P
CLASS="LITERALLAYOUT"
> <I
CLASS="EMPHASIS"
->{+vanilla-wafer}</I
+>{+send-vanilla-wafer}</I
><br>
<I
CLASS="EMPHASIS"
>jarfile</TT
>
for saving cookies. Of course, this is a (relatively) unique header and
- could be used to track you.
+ could conceivably be used to track you.
</P
></DD
></DL
><H4
CLASS="SECT4"
><A
-NAME="WAFER"
->5.4.5.20. <I
+NAME="SEND-WAFER"
+>7.4.5.20. <I
CLASS="EMPHASIS"
->+wafer</I
+>+send-wafer</I
></A
></H4
><P
CLASS="LITERALLAYOUT"
> <I
CLASS="EMPHASIS"
->{+wafer{name=value}}</I
+>{+send-wafer{name=value}}</I
><br>
<I
CLASS="EMPHASIS"
CLASS="SECT4"
><A
NAME="ACT-EXAMPLES"
->5.4.5.21. Actions Examples</A
+>7.4.5.21. Actions Examples</A
></H3
><P
> Note that the meaning of any of the above examples is reversed by preceding
CLASS="QUOTE"
>"on"</SPAN
>.
- Some actions that are turned on the default section do typically require
- exceptions to be listed in the lower sections of actions file.</P
+ But, other actions that are turned on the default section <I
+CLASS="EMPHASIS"
+>do
+ typically require</I
+> exceptions to be listed in the lower sections of
+ actions file. E.g. by default no URLs are <SPAN
+CLASS="QUOTE"
+>"blocked"</SPAN
+> (i.e. in
+ the default definitions of <TT
+CLASS="FILENAME"
+>default.action</TT
+>). We need
+ exceptions to this in order to enable ad blocking.</P
><P
> Some examples:</P
><P
-> Turn off cookies by default, then allow a few through for specified sites:</P
+> Turn off cookies by default, then allow a few through for specified sites
+ (showing an excerpt from the <SPAN
+CLASS="QUOTE"
+>"default"</SPAN
+> section of an actions
+ file ONLY):</P
><P
> <TT
CLASS="LITERAL"
> <P
CLASS="LITERALLAYOUT"
-> # Turn off all persistent cookies<br>
- { +no-cookies-read }<br>
- { +no-cookies-set }<br>
- <br>
- # Allow cookies for this browser session ONLY<br>
- { +no-cookies-keep }<br>
+> # Excerpt only:<br>
+ # Allow cookies to and from the server, but<br>
+ # for this browser session ONLY<br>
+ { <br>
+ # other actions normally listed here...<br>
+ -prevent-setting-cookies \<br>
+ -prevent-reading-cookies \<br>
+ +session-cookies-only \ <br>
+ }<br>
+ / # match all URLs<br>
<br>
# Exceptions to the above, sites that benefit from persistent cookies<br>
- # that saved from one browser session to the next.<br>
- { -no-cookies-read }<br>
- { -no-cookies-set }<br>
- { -no-cookies-keep }<br>
- .javasoft.com<br>
- .sun.com<br>
- .yahoo.com<br>
- .msdn.microsoft.com<br>
- .redhat.com<br>
+ # that are saved from one browser session to the next.<br>
+ { -session-cookies-only }<br>
+ .javasoft.com<br>
+ .sun.com<br>
+ .yahoo.com<br>
+ .msdn.microsoft.com<br>
+ .redhat.com<br>
<br>
- # Alternative way of saying the same thing<br>
- {-no-cookies-set -no-cookies-read -no-cookies-keep}<br>
- .sourceforge.net<br>
- .sf.net<br>
</P
>
</TT
CLASS="LITERAL"
> <P
CLASS="LITERALLAYOUT"
-> # Turn them off!<br>
- {+fast-redirects}<br>
+> # Turn them off (excerpt only)!<br>
+ {<br>
+ # other actions normally listed here...<br>
+ +fast-redirects<br>
+ }<br>
+ / # match all URLs<br>
<br>
# Reverse it for these two sites, which don't work right without it.<br>
{-fast-redirects}<br>
- www.ukc.ac.uk/cgi-bin/wac\.cgi\?<br>
- login.yahoo.com<br>
+ www.ukc.ac.uk/cgi-bin/wac\.cgi\?<br>
+ login.yahoo.com<br>
</P
>
</TT
CLASS="LITERAL"
> <P
CLASS="LITERALLAYOUT"
-> # Run everything through the filter file, using only the<br>
+> # Run everything through the filter file, using only certain<br>
# specified sections:<br>
- +filter{html-annoyances} +filter{js-annoyances} +filter{no-popups}\<br>
- +filter{webbugs} +filter{nimda} +filter{banners-by-size}<br>
+ {<br>
+ # other actions normally listed here...<br>
+ +filter{html-annoyances} +filter{js-annoyances} +filter{kill-popups}\<br>
+ +filter{webbugs} +filter{nimda} +filter{banners-by-size}<br>
+ }<br>
+ / #match all URLs<br>
<br>
- # Then disable filtering of code from sourceforge!<br>
+ # Then disable filtering of code from all sourceforge domains!<br>
{-filter}<br>
- .cvs.sourceforge.net<br>
+ .sourceforge.net<br>
</P
>
</TT
the <SPAN
CLASS="QUOTE"
>"blocked"</SPAN
-> banner). Many of these use
- <A
+> banner). Typically, the <SPAN
+CLASS="QUOTE"
+>"block"</SPAN
+>
+ action is off by default in the upper section of an actions file, then enabled
+ against certain URLs and patterns in the lower part of the file. Many of these use <A
HREF="appendix.html#REGEX"
>regular expressions</A
-> that will expand to match
- multiple URLs: </P
+> that will expand to match multiple
+ URLs: </P
><P
> <TT
CLASS="LITERAL"
CLASS="LITERALLAYOUT"
> # Blocklist:<br>
{+block}<br>
- /.*/(.*[-_.])?ads?[0-9]?(/|[-_.].*|\.(gif|jpe?g))<br>
- /.*/(.*[-_.])?count(er)?(\.cgi|\.dll|\.exe|[?/])<br>
+ ad*.<br>
+ .*ads.<br>
+ banner?.<br>
+ count*.<br>
+ /.*count(er)?\.(pl|cgi|exe|dll|asp|php[34]?)<br>
+ /(?:.*/)?(publicite|werbung|rekla(ma|me|am)|annonse|maino(kset|nta|s)?)/<br>
+ .hitbox.com <br>
/.*/(ng)?adclient\.cgi<br>
/.*/(plain|live|rotate)[-_.]?ads?/<br>
- /.*/(sponsor)s?[0-9]?/<br>
- /.*/_?(plain|live)?ads?(-banners)?/<br>
/.*/abanners/<br>
- /.*/ad(sdna_image|gifs?)/<br>
- /.*/ad(server|stream|juggler)\.(cgi|pl|dll|exe)<br>
- /.*/adbanners/<br>
- /.*/adserver<br>
- /.*/adstream\.cgi<br>
- /.*/adv((er)?ts?|ertis(ing|ements?))?/<br>
- /.*/banner_?ads/<br>
- /.*/banners?/<br>
- /.*/banners?\.cgi/<br>
- /.*/cgi-bin/centralad/getimage<br>
- /.*/images/addver\.gif<br>
- /.*/images/marketing/.*\.(gif|jpe?g)<br>
- /.*/popupads/<br>
- /.*/siteads/<br>
- /.*/sponsor.*\.gif<br>
- /.*/sponsors?[0-9]?/<br>
- /.*/advert[0-9]+\.jpg<br>
- /Media/Images/Adds/<br>
- /ad_images/<br>
- /adimages/<br>
- /.*/ads/<br>
- /bannerfarm/<br>
- /grafikk/annonse/<br>
- /graphics/defaultAd/<br>
- /image\.ng/AdType<br>
- /image\.ng/transactionID<br>
- /images/.*/.*_anim\.gif # alvin brattli<br>
- /ip_img/.*\.(gif|jpe?g)<br>
- /rotateads/<br>
- /rotations/ <br>
- /worldnet/ad\.cgi<br>
- /cgi-bin/nph-adclick.exe/<br>
- /.*/Image/BannerAdvertising/<br>
- /.*/ad-bin/<br>
- /.*/adlib/server\.cgi<br>
/autoads/<br>
</P
>
> Note that many of these actions have the potential to cause a page to
misbehave, possibly even not to display at all. There are many ways
a site designer may choose to design his site, and what HTTP header
- content he may depend on. There is no way to have hard and fast rules
- for all sites. See the <A
+ content, and other criteria, he may depend on. There is no way to have hard
+
and fast rules for all sites. See the <A
HREF="appendix.html#ACTIONSANAT"
>Appendix</A
->
- for a brief example on troubleshooting actions.</P
+> for a brief example on troubleshooting
+ actions.</P
></DIV
></DIV
><DIV
><H3
CLASS="SECT3"
><A
-NAME="AEN2110"
->5.4.6. Aliases</A
+NAME="ALIASES"
+>7.4.6. Aliases</A
></H3
><P
> Custom <SPAN
>. Alias names are not case sensitive, and
<I
CLASS="EMPHASIS"
->must be defined before anything</I
-> else in the
- <TT
-CLASS="FILENAME"
->default.action</TT
->file! And there can only be one set of
- <SPAN
+>must be defined before other actions</I
+> in the
+ actions file! And there can only be one set of <SPAN
CLASS="QUOTE"
>"aliases"</SPAN
-> defined.</P
+>
+ defined per file. Each actions file may have its own aliases, but they are
+ only visible within that file.</P
><P
> Now let's define a few aliases:</P
><P
CLASS="LITERALLAYOUT"
> # Useful custom aliases we can use later. These must come first!<br>
{{alias}}<br>
- +no-cookies = +no-cookies-set +no-cookies-read<br>
- -no-cookies = -no-cookies-set -no-cookies-read<br>
- fragile = -block -no-cookies -filter -fast-redirects -hide-referer -no-popups<br>
- shop = -no-cookies -filter -fast-redirects<br>
- +imageblock = +block +image<br>
+ +prevent-cookies = +prevent-setting-cookies +prevent-reading-cookies<br>
+ -prevent-cookies = -prevent-setting-cookies -prevent-reading-cookies<br>
+ fragile = -block -prevent-cookies -filter -fast-redirects -hide-referer -kill-popups<br>
+ shop = -prevent-cookies -filter -fast-redirects<br>
+ +imageblock = +block +handle-as-image<br>
<br>
- #For people who don't like to type too much: ;-)<br>
- c0 = +no-cookies<br>
- c1 = -no-cookies<br>
- c2 = -no-cookies-set +no-cookies-read<br>
- c3 = +no-cookies-set -no-cookies-read<br>
+ # Aliases defined from other aliases, for people who don't like to type <br>
+ # too much: ;-)<br>
+ c0 = +prevent-cookies<br>
+ c1 = -prevent-cookies<br>
#... etc. Customize to your heart's content.<br>
</P
>
CLASS="QUOTE"
>"fragile"</SPAN
>
- aliases from above:</P
+ aliases from above. These would appear in the lower sections of an
+ actions file as exceptions to the default actions (as defined in the
+ upper section):</P
><P
> <TT
CLASS="LITERAL"
> # These sites are very complex and require<br>
# minimal interference.<br>
{fragile}<br>
- .office.microsoft.com<br>
- .windowsupdate.microsoft.com<br>
- .nytimes.com<br>
+ .office.microsoft.com<br>
+ .windowsupdate.microsoft.com<br>
+ .nytimes.com<br>
<br>
# Shopping sites - but we still want to block ads.<br>
{shop}<br>
- .quietpc.com<br>
- .worldpay.com # for quietpc.com<br>
- .jungle.com<br>
- .scan.co.uk<br>
+ .quietpc.com<br>
+ .worldpay.com # for quietpc.com<br>
+ .scan.co.uk<br>
<br>
# These shops require pop-ups also <br>
- {shop -no-popups}<br>
- .dabs.com<br>
- .overclockers.co.uk<br>
+ {shop -kill-popups}<br>
+ .dabs.com<br>
+ .overclockers.co.uk<br>
</P
>
</TT
><H2
CLASS="SECT2"
><A
-NAME="FILTERFILE"
->5.5. The Filter File</A
+NAME="FILTER-FILE"
+>7.5. The Filter File</A
></H2
><P
> Any web page can be dynamically modified with the filter file. This
><H2
CLASS="SECT2"
><A
-NAME="AEN2176"
->5.6. Templates</A
+NAME="AEN2273"
+>7.6. Templates</A
></H2
><P
> When <SPAN
ALIGN="left"
VALIGN="top"
><A
-HREF="quickstart.html"
+HREF="startup.html"
>Prev</A
></TD
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
->Quickstart to Using <SPAN
+>Starting <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
></TD
projects / privoxy.git / blobdiff