Remove kill-popups action.

[privoxy.git] / doc / source / privoxy-man-page.sgml

diff --git a/doc/source/privoxy-man-page.sgml b/doc/source/privoxy-man-page.sgml
index 5b62dc8..3cd29fe 100644 (file)
--- a/doc/source/privoxy-man-page.sgml
+++ b/doc/source/privoxy-man-page.sgml
@@ -5,14 +5,10 @@
                 This file belongs into
                 ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
                 
                 This file belongs into
                 ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
                 

- $Id: privoxy-man-page.sgml,v 1.6 2002/04/12 01:55:43 hal9 Exp $
+ $Id: privoxy-man-page.sgml,v 2.17 2008/01/19 15:03:05 hal9 Exp $

 
 

- Written by and Copyright (C) 2001 the SourceForge
- Privoxy team. http://www.privoxy.org/
-
- Based on the Internet Junkbuster originally written
- by and Copyright (C) 1997 Anonymous Coders and 
- Junkbusters Corporation.  http://www.junkbusters.com
+ Copyright (C) 2001-2008 Privoxy Developers http://www.privoxy.org/
+ See LICENSE.

 
  ========================================================================
  NOTE: Please read developer-manual/documentation.html before touching 
 
  ========================================================================
  NOTE: Please read developer-manual/documentation.html before touching 


@@ -40,28 +36,31 @@
 
 -->
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"[
 
 -->
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"[

-<!entity % dummy "INCLUDE"> 
+<!entity % dummy "IGNORE"> 

 <!entity p-intro SYSTEM "privoxy.sgml">
 <!entity seealso SYSTEM "seealso.sgml">
 <!entity copyright SYSTEM "copyright.sgml">
 <!entity p-intro SYSTEM "privoxy.sgml">
 <!entity seealso SYSTEM "seealso.sgml">
 <!entity copyright SYSTEM "copyright.sgml">

+<!entity license SYSTEM "license.sgml">

 <!entity authors SYSTEM "p-authors.sgml">
 <!entity authors SYSTEM "p-authors.sgml">

-<!entity p-version "2.9.14">
-<!entity p-status "beta">
-<!entity % p-not-stable "INCLUDE">
-<!entity % p-stable "IGNORE">
+<!entity p-version "3.0.8">
+<!entity p-status "stable">
+<!entity % p-not-stable "IGNORE">
+<!entity % p-stable "INCLUDE">

 <!entity % p-text "IGNORE">           <!-- define we are not a text only doc -->
 <!entity % p-authors-formal "IGNORE"> <!-- exclude additional formating      -->
 <!entity % p-text "IGNORE">           <!-- define we are not a text only doc -->
 <!entity % p-authors-formal "IGNORE"> <!-- exclude additional formating      -->

+<!entity my-copy "(C)">               <!-- db2man barfs on copyright symbol  -->

 ]>
 
 <refentry id="privoxy">
 <refentryinfo>
 ]>
 
 <refentry id="privoxy">
 <refentryinfo>

- <date>2002-04-11</date>
+ <date>2007-04-12</date>

 </refentryinfo>
 </refentryinfo>

-

 <refmeta>
  <refentrytitle>privoxy</refentrytitle> 
  <manvolnum>1</manvolnum>
 <refmeta>
  <refentrytitle>privoxy</refentrytitle> 
  <manvolnum>1</manvolnum>

- <refmiscinfo>Privoxy &p-version;<![%p-not-stable;[ &p-status;]]></refmiscinfo>
+ <refmiscinfo>
+  Privoxy &p-version;<![%p-not-stable;[ &p-status;]]>
+ </refmiscinfo>

 </refmeta>
 
 <refnamediv>
 </refmeta>
 
 <refnamediv>


@@ -77,15 +76,11 @@
   <arg><option>--no-daemon</option></arg>
   <arg><option>--pidfile </option><replaceable class="parameter">pidfile</replaceable></arg>  
   <arg><option>--user </option><replaceable class="parameter">user[.group]</replaceable></arg> 
   <arg><option>--no-daemon</option></arg>
   <arg><option>--pidfile </option><replaceable class="parameter">pidfile</replaceable></arg>  
   <arg><option>--user </option><replaceable class="parameter">user[.group]</replaceable></arg> 

+  <arg><option>--chroot</option></arg>
+  <arg><option>--pre-chroot-nslookup </option><replaceable class="parameter">hostname</replaceable></arg> 

   <arg><replaceable class="parameter">configfile</replaceable></arg>        
   <arg><replaceable class="parameter">configfile</replaceable></arg>        

-  <command>(UNIX)</command>

  </cmdsynopsis>
 
  </cmdsynopsis>
 

- <cmdsynopsis> 
-  <command>privoxy.exe</command>              
-  <arg><replaceable class="parameter">configfile</replaceable></arg>
-  <command>(Windows)</command>
- </cmdsynopsis>                                      

 </refsynopsisdiv>
 
 
 </refsynopsisdiv>
 
 


@@ -131,7 +126,7 @@
       <para>
         On startup, write the process ID to <replaceable class="parameter">pidfile</replaceable>.
         Delete the <replaceable class="parameter">pidfile</replaceable> on exit.
       <para>
         On startup, write the process ID to <replaceable class="parameter">pidfile</replaceable>.
         Delete the <replaceable class="parameter">pidfile</replaceable> on exit.

-        Failiure to create or delete the <replaceable class="parameter">pidfile</replaceable>
+        Failure to create or delete the <replaceable class="parameter">pidfile</replaceable>

         is non-fatal. If no <command>--pidfile</command> option is given, no PID file will be used.
       </para>
     </listitem>
         is non-fatal. If no <command>--pidfile</command> option is given, no PID file will be used.
       </para>
     </listitem>


@@ -152,13 +147,35 @@
      </para>
     </listitem>
   </varlistentry>
      </para>
     </listitem>
   </varlistentry>

+  <varlistentry>
+    <term>--chroot</term>
+     <listitem>
+      <para>
+       Before changing to the user ID given in the --user option, chroot to
+       that user's home directory, i.e. make the kernel pretend to the
+       <command>Privoxy</command> process that the directory tree starts
+       there. If set up carefully, this can limit the impact of possible
+       vulnerabilities in <command>Privoxy</command> to the files contained in
+       that hierarchy. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>--pre-chroot-nslookup <replaceable class="parameter">hostname</replaceable></term>
+     <listitem>
+      <para>
+        Initialize the resolver library using <replaceable class="parameter">hostname</replaceable>
+        before chroot'ing. On some systems this reduces the number of files
+        that must be copied into the chroot tree.
+     </para>
+    </listitem>
+  </varlistentry>

  </variablelist>
  </variablelist>

- 
+

  <para>
   If the <filename>configfile</filename> is not specified on  the  command  line,
   <command>Privoxy</command>  will  look for a file named
  <para>
   If the <filename>configfile</filename> is not specified on  the  command  line,
   <command>Privoxy</command>  will  look for a file named

-  <filename>config</filename> in the current directory (except on Win32 where
-  it will try <filename>config.txt</filename>). If no
+  <filename>config</filename> in the current directory . If no

   <filename>configfile</filename> is found, <command>Privoxy</command> will 
   fail to start.
  </para>
   <filename>configfile</filename> is found, <command>Privoxy</command> will 
   fail to start.
  </para>


@@ -177,14 +194,23 @@
 <!--   ~~~~~       New section      ~~~~~     -->
 <refsect1><title>Installation and Usage</title>
 <para>
 <!--   ~~~~~       New section      ~~~~~     -->
 <refsect1><title>Installation and Usage</title>
 <para>

- Browsers must be individually configured to use <command>Privoxy</command> as
- a HTTP proxy.  The default setting is  for  localhost,  on port  8118
- (configurable in the main config file).  To set the HTTP proxy in Netscape
- and Mozilla, go through:  <command>Edit</command>;
+ Browsers can either be individually configured to use
+ <command>Privoxy</command> as a HTTP proxy (recommended),
+ or <command>Privoxy</command> can be combined with a packet
+ filter to build an intercepting proxy
+ (see <filename>config</filename>).  The default setting is  for
+ localhost,  on port  8118 (configurable in the main config file).  To set the
+ HTTP proxy in Netscape and Mozilla, go through:  <command>Edit</command>;

  <command>Preferences</command>;  <command>Advanced</command>;
  <command>Proxies</command>;  <command>Manual Proxy Configuration</command>;
  <command>View</command>. 
 </para>
  <command>Preferences</command>;  <command>Advanced</command>;
  <command>Proxies</command>;  <command>Manual Proxy Configuration</command>;
  <command>View</command>. 
 </para>

+<para>
+ For Firefox, go through: <command>Tools</command>; 
+ <command>Options</command>; <command>General</command>;
+ <command>Connection Settings</command>;
+ <command>Manual Proxy Configuration</command>. 
+</para>

 <para>
  For Internet Explorer, go through: <command>Tools</command>; 
  <command>Internet Properties</command>; <command>Connections</command>;
 <para>
  For Internet Explorer, go through: <command>Tools</command>; 
  <command>Internet Properties</command>; <command>Connections</command>;


@@ -192,8 +218,12 @@
 </para>
 <para>
  The Secure (SSL) Proxy should also be set to the same values, otherwise
 </para>
 <para>
  The Secure (SSL) Proxy should also be set to the same values, otherwise

- https: URLs will not be proxied. 
+ https: URLs will not be proxied. Note: <command>Privoxy</command> can only
+ proxy HTTP and HTTPS traffic. Do not try it with FTP or other protocols.
+ HTTPS presents some limitations, and not all features will work with HTTPS 
+ connections.

 </para>
 </para>

+

 <para>
  For other browsers, check the documentation.
 </para>
 <para>
  For other browsers, check the documentation.
 </para>


@@ -205,25 +235,36 @@
 <para>
  <command>Privoxy</command> can be configured with the various configuration
  files. The default configuration files are: <filename>config</filename>,
 <para>
  <command>Privoxy</command> can be configured with the various configuration
  files. The default configuration files are: <filename>config</filename>,

- <filename>default.action</filename>, and
- <filename>default.filter</filename>. These are well commented.  On Unix and
- Unix-like systems, these are located in <filename>/etc/privoxy/</filename> by
- default. On Windows, OS/2 and AmigaOS, these files are in the same directory
- as the <command>Privoxy</command> executable.
+ <filename>default.filter</filename>, and
+ <filename>default.action</filename>. <filename>user.action</filename> should 
+ be used for locally defined exceptions to the default rules of
+ <filename>default.action</filename>, and <filename>user.filter</filename> for 
+ locally defined filters. These are well commented.  On Unix
+ and Unix-like systems, these are located in
+ <filename>/etc/privoxy/</filename> by default. 

 </para>
 </para>

-<para>
- The name and number of configuration files has changed from previous
- versions, and is subject to change as development progresses. In fact, the
- configuration itself is changed  and  much more sophisticated. See the
- <ulink url="http://www.privoxy.org/user-manual/">user-manual</ulink> for a
- brief explanation of all configuration options. 
+<para> 
+ <command>Privoxy</command> uses the concept of <command>actions</command> 
+ in order to manipulate the data stream between the browser and remote sites.
+ There are various actions available with specific functions for such things 
+ as blocking web sites, managing cookies, etc. These actions can be invoked
+ individually or combined, and used against individual URLs, or groups of URLs 
+ that can be defined using wildcards and regular expressions. The result is
+ that the user has greatly enhanced control and freedom.

 </para>
 <para>
  The actions list (ad blocks, etc) can also be configured with your
 </para>
 <para>
  The actions list (ad blocks, etc) can also be configured with your

- web browser at <ulink url="http://ijbswa.sourceforge.net/config">http://ijbswa.sourceforge.net/config</ulink>.
+ web browser at <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink> 
+ (assuming the configuration allows it).

  <command>Privoxy's</command> configuration parameters  can also  be viewed at
  the same page. In addition, <command>Privoxy</command> can be toggled on/off.
  <command>Privoxy's</command> configuration parameters  can also  be viewed at
  the same page. In addition, <command>Privoxy</command> can be toggled on/off.

- This is an internal page.
+ This is an internal page, and does not require Internet access.
+</para>
+<para>
+ See the <ulink
+ url="http://www.privoxy.org/user-manual/"><citetitle>User Manual</citetitle></ulink> for a detailed
+ explanation of installation, general usage, all configuration options, new
+ features and notes on upgrading.

 </para>
 </refsect1>
 
 </para>
 </refsect1>
 


@@ -231,108 +272,107 @@
 <!--   ~~~~~       New section      ~~~~~     -->
 <refsect1><title>Sample Configuration</title>
 <para>
 <!--   ~~~~~       New section      ~~~~~     -->
 <refsect1><title>Sample Configuration</title>
 <para>

- A brief example of what a <filename>default.action</filename> configuration
- might look like:
+ A brief example of what a simple <filename>default.action</filename>
+ configuration might look like:

 </para>
 
 <literallayout>
 </para>
 
 <literallayout>

-

  # Define a few useful custom aliases for later use
  {{alias}}
 
  # Define a few useful custom aliases for later use
  {{alias}}
 

- # Don't accept cookies
- +no-cookies = +no-cookies-set +no-cookies-read
-
- # Do accept cookies
- -no-cookies = -no-cookies-set -no-cookies-read
-
- # Treat these blocked URLs as images.
- +imageblock = +block +image
-
- # Define page filters we want to use.
- myfilters = +filter{html-annoyances} +filter{js-annoyances}\
-             +filter{no-popups} +filter{webbugs}
-
- ## Default Policies (actions) ############################
- { \
-  -block \
-  -downgrade \
-  +fast-redirects \
-  myfilters \
-  +no-compression \
-  +hide-forwarded \
-  +hide-from{block} \
-  +hide-referer{forge} \
-  -hide-user-agent \
-  -image \
-  +image-blocker{blank} \
-  +no-cookies-keep \
-  -no-cookies-read \
-  -no-cookies-set \
-  +no-popups \
-  -vanilla-wafer \
-  -wafer \
- }
- /
-
- # Now set exceptions to the above defined policies #######
-
- # Sites where we want persistant cookies
- {-no-cookies -no-cookies-keep}
+ # Useful aliases that combine more than one action
+ +crunch-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies
+ -crunch-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies
+ +block-as-image = +block +handle-as-image
+
+ # Fragile sites should have the minimum changes
+ fragile     = -block -deanimate-gifs -fast-redirects -filter \
+               -hide-referer -prevent-cookies
+
+ ## Turn some actions on ################################
+ ## NOTE: Actions are off by default, unless explictily turned on 
+ ## otherwise with the '+' operator.
+
+{ \
++deanimate-gifs{last} \
++filter{refresh-tags} \
++filter{img-reorder} \
++filter{banners-by-size} \
++filter{webbugs} \
++filter{jumping-windows} \
++filter{ie-exploits} \
++hide-forwarded-for-headers \
++hide-from-header{block} \
++hide-referrer{conditional-block} \
++session-cookies-only \
++set-image-blocker{pattern} \
+}
+/ # '/' Match *all* URL patterns
+
+ 
+ # Block all URLs that match these patterns
+ { +block }
+  ad.
+  ad[sv].
+  .*ads.
+  banner?.
+  /.*count(er)?\.(pl|cgi|exe|dll|asp|php[34]?)
+  .hitbox.com 
+  media./.*(ads|banner)
+
+ # Block, and treat these URL patterns as if they were 'images'.
+ # We would expect these to be ads.
+ { +block-as-image }
+  .ad.doubleclick.net
+  .a[0-9].yimg.com/(?:(?!/i/).)*$
+  ad.*.doubleclick.net
+
+ # Make exceptions for these harmless ones that would be 
+ # caught by our +block patterns just above.
+ { -block }
+  adsl.
+  adobe.
+  advice.
+  .*downloads.
+  # uploads or downloads
+  /.*loads
+</literallayout>
+
+<para>
+ Then for a <filename>user.action</filename>, we would put local,
+ narrowly defined exceptions:
+</para>
+
+<literallayout>
+ # Re-define aliases as needed here
+ {{alias}}
+
+ # Useful aliases
+ -crunch-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies
+ 
+ # Set personal exceptions to the policies in default.action #######
+
+ # Sites where we want persistent cookies, so allow *all* cookies
+ { -crunch-cookies -session-cookies-only }

   .redhat.com
   .sun.com
   .redhat.com
   .sun.com

-  .yahoo.com

   .msdn.microsoft.com
   .msdn.microsoft.com

+ 
+ # These sites break easily. Use our "fragile" alias here.
+ { fragile }
+  .forbes.com
+  mybank.example.com

 
 

- # This site requires cookies AND 'fast-redirects' on
- {-no-cookies -no-cookies-keep -fast-redirects}
-  .nytimes.com
-
- # Add custom headers, and turn off filtering of page source
- {+add-header{X-Privacy: Yes please} #-add-header{*} \
-  +add-header{X-User-Tracking: No thanks!} -filter}
-  privacy.net
-
- # Block, and treat these URLs as 'images'.
- {+imageblock}
-  .adforce.imgis.com
-  .ad.preferences.com/image.*
-  .ads.web.aol.com
-  .ad-adex3.flycast.com
-  .ad.doubleclick.net
-  .ln.doubleclick.net
-  .ad.de.doubleclick.net
-  /.*/count\.cgi\?.*df=
-  194.221.183.22[1-7]
-  a196.g.akamai.net/7/196/2670/000[12]/images.gmx.net/i4/images/.*/
-
- # Block any URLs that match these patterns
- {+block}
-  /.*/(.*[-_.])?ads?[0-9]?(/|[-_.].*|\.(gif|jpe?g))
-  /.*/(plain|live|rotate)[-_.]?ads?/
-  /.*/(sponsor)s?[0-9]?/
-  /.*/ad(server|stream|juggler)\.(cgi|pl|dll|exe)
-  /.*/adbanners/
-  /.*/adv((er)?ts?|ertis(ing|ements?))?/
-  /.*/banners?/
-  /.*/popupads/
-  /.*/advert[0-9]+\.jpg
-  /ad_images/
-  /.*/ads/
-  /images/.*/.*_anim\.gif
-  /rotations/ 
-  /.*(ms)?backoff(ice)?.*\.(gif|jpe?g)
-  195.63.104.*/(inbox|log|meld|folderlu|folderru|log(in|out)[lmr]u|)
-  .images.nytimes.com
-  .images.yahoo.com/adv/
-  /.*cnnstore\.gif
+ # Replace example.com's style sheet with one of my choosing
+ { +redirect{http://localhost/css-replacements/example.com.css} }
+  .example.com/stylesheet.css

 
 </literallayout>
 
 <para>
  See the comments in the configuration files themselves, or the 
 
 </literallayout>
 
 <para>
  See the comments in the configuration files themselves, or the 

- <citetitle>user-manual</citetitle>
- for explanations of the above syntax, and other <command>Privoxy</command>
+ <citetitle>User Manual</citetitle>
+ for full explanations of the above syntax, and other <command>Privoxy</command>

  configuration options.
 </para>
 
  configuration options.
 </para>
 


@@ -346,10 +386,10 @@
  <filename>/usr/sbin/privoxy</filename>
  <filename>/etc/privoxy/config</filename>
  <filename>/etc/privoxy/default.action</filename>
  <filename>/usr/sbin/privoxy</filename>
  <filename>/etc/privoxy/config</filename>
  <filename>/etc/privoxy/default.action</filename>

- <filename>/etc/privoxy/advanced.action</filename>
- <filename>/etc/privoxy/basic.action</filename>
- <filename>/etc/privoxy/intermediate.action</filename>
+ <filename>/etc/privoxy/standard.action</filename>
+ <filename>/etc/privoxy/user.action</filename>

  <filename>/etc/privoxy/default.filter</filename>
  <filename>/etc/privoxy/default.filter</filename>

+ <filename>/etc/privoxy/user.filter</filename>

  <filename>/etc/privoxy/trust</filename>
  <filename>/etc/privoxy/templates/*</filename>
  <filename>/var/log/privoxy/logfile</filename>
  <filename>/etc/privoxy/trust</filename>
  <filename>/etc/privoxy/templates/*</filename>
  <filename>/var/log/privoxy/logfile</filename>


@@ -357,8 +397,8 @@
 
 <para>
  Various other files should be included, but may vary depending on platform
 
 <para>
  Various other files should be included, but may vary depending on platform

- and build configuration. More documentation should be included in the local
- documentation directory, though is not complete at this time.
+ and build configuration. Additional documentation should be included in the local
+ documentation directory.

 </para>
 
 </refsect1>
 </para>
 
 </refsect1>


@@ -387,8 +427,8 @@
  all features are well tested.
 </para>]]>
 <para>
  all features are well tested.
 </para>]]>
 <para>

- Please see the <citetitle>user-manual</citetitle> on how to contact the
- developers for feature requests, reporting problems, and other questions.
+ Please see the <citetitle>User Manual</citetitle> on how to contact the
+ developers, for feature requests, reporting problems, and other questions.

 </para>
 
 </refsect1>
 </para>
 
 </refsect1>


@@ -409,9 +449,18 @@
 
 <!--   ~~~~~       New section      ~~~~~     -->
 <refsect1><title>Copyright and License</title>
 
 <!--   ~~~~~       New section      ~~~~~     -->
 <refsect1><title>Copyright and License</title>

-<!-- Include seealso.sgml boilerplate: -->
+
+<refsect2><title>Copyright</title>
+<!-- Include copyright.sgml boilerplate: -->

  &copyright;
 <!-- end boilerplate -->
  &copyright;
 <!-- end boilerplate -->

+</refsect2>
+
+<refsect2><title>License</title>
+<!-- Include license.sgml boilerplate: -->
+ &license;
+<!-- end boilerplate -->
+</refsect2>

 </refsect1>
 
 </refentry>
 </refsect1>
 
 </refentry>