doc/source/privoxy-man-page.sgml

   1 <!--
   2  File        :  $Source: /cvsroot/ijbswa/current/doc/source/privoxy-man-page.sgml,v $
   3
   4  Purpose     :  Manual Page
   5                 This file belongs into
   6                 ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
   7
   8  $Id: privoxy-man-page.sgml,v 1.0 2002/04/04 21:59:53 hal9 Exp $
   9
  10  Written by and Copyright (C) 2001 the SourceForge
  11  Privoxy team. http://www.privoxy.org/
  12
  13  Based on the Internet Junkbuster originally written
  14  by and Copyright (C) 1997 Anonymous Coders and
  15  Junkbusters Corporation.  http://www.junkbusters.com
  16
  17  ========================================================================
  18  NOTE: Please read developer-manual/documentation.html before touching
  19  anything in this, or other Privoxy documentation. You have been warned!
  20  Failure to abide by this rule will result in the revocation of your license
  21  to live a peaceful existence!
  22  ========================================================================
  23
  24  Doc NOTES: This is some tricky stuff! There are some quirks
  25  to how this markup is handled. It is not always so co-operative.
  26  Please don't change the markup, unless you are willing to
  27  un-do your changes!
  28
  29  literallayout tags are particularly sensitive to where they are placed.
  30  The 'replaceable' and 'command' tags are used here somewhat unconventionally,
  31  since it seems to generate the proper formatting (at least for me :).
  32
  33  Create man page: 'docbook2man privoxy-man-page.sgml'
  34
  35  For man page references, see:
  36  http://www.linuxdoc.org/HOWTO/mini/DocBook-Install/using.html
  37  http://docbook.org/tdg/en/html/ch02.html#making-refentry
  38
  39 -->
  40 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"[
  41 <!entity % dummy "INCLUDE">
  42 <!entity p-intro SYSTEM "privoxy.sgml">
  43 <!entity seealso SYSTEM "seealso.sgml">
  44 <!entity copyright SYSTEM "copyright.sgml">
  45 <!entity authors SYSTEM "p-authors.sgml">
  46 <!entity p-version "2.9.13">
  47 <!entity p-status "BETA">
  48 <!entity % p-not-stable "INCLUDE">    <!-- set to IGNORE for stable release  -->
  49 <!entity % p-stable "IGNORE">         <!-- set INCLUDE for stable release    -->
  50 <!entity % p-text "IGNORE">           <!-- define we are not a text only doc -->
  51 <!entity % p-authors-formal "IGNORE"> <!-- exclude additional formating      -->
  52 ]>
  53
  54 <refentry id="privoxy">
  55 <refentryinfo>
  56  <date>2002-04-04</date>
  57 </refentryinfo>
  58
  59 <refmeta>
  60  <refentrytitle>privoxy</refentrytitle>
  61  <manvolnum>1</manvolnum>
  62  <refmiscinfo>Privoxy &p-version;<![%p-not-stable;[ &p-status;]]></refmiscinfo>
  63 </refmeta>
  64
  65 <refnamediv>
  66  <refname><application>privoxy</application></refname>
  67  <refpurpose>Privacy Enhancing Proxy</refpurpose>
  68 </refnamediv>
  69
  70 <refsynopsisdiv>
  71  <cmdsynopsis>
  72   <command>privoxy</command>
  73   <arg><option>--help</option></arg>
  74   <arg><option>--version</option></arg>
  75   <arg><option>--no-daemon</option></arg>
  76   <arg><option>--pidfile </option><replaceable class="parameter">pidfile</replaceable></arg>
  77   <arg><option>--user </option><replaceable class="parameter">user[.group]</replaceable></arg>
  78   <arg><replaceable class="parameter">configfile</replaceable></arg>
  79   <command>(UNIX)</command>
  80  </cmdsynopsis>
  81
  82  <cmdsynopsis>
  83   <command>privoxy.exe</command>
  84   <arg><replaceable class="parameter">configfile</replaceable></arg>
  85   <command>(Windows)</command>
  86  </cmdsynopsis>
  87 </refsynopsisdiv>
  88
  89
  90 <!--   ~~~~~       New section      ~~~~~     -->
  91 <refsect1><title>Options</title>
  92  <para>
  93   <command>Privoxy</command> may be invoked with the following command line
  94   options:
  95  </para>
  96
  97  <variablelist>
  98   <varlistentry>
  99     <term>--help</term>
 100       <listitem>
 101        <para>
 102          Print brief usage info and exit.
 103         </para>
 104       </listitem>
 105   </varlistentry>
 106
 107   <varlistentry>
 108     <term>--version</term>
 109       <listitem>
 110        <para>
 111          Print version info and exit.
 112         </para>
 113       </listitem>
 114   </varlistentry>
 115
 116   <varlistentry>
 117     <term>--no-daemon</term>
 118      <listitem>
 119       <para>
 120         Don't  become  a daemon, i.e. don't fork and become process group
 121         leader, don't detach from controlling tty, and do all logging there.
 122       </para>
 123     </listitem>
 124   </varlistentry>
 125
 126   <varlistentry>
 127     <term>--pidfile <replaceable class="parameter">pidfile</replaceable></term>
 128      <listitem>
 129       <para>
 130        After (optionally) writing the PID file, assume the user  ID  of  user
 131        and the GID of group, or, if the optional group was not given, the
 132        default group  of user.  Exit if the privileges are not sufficient to
 133        do so.
 134       </para>
 135     </listitem>
 136   </varlistentry>
 137   <varlistentry>
 138     <term>--user <replaceable class="parameter">user[.group]</replaceable></term>
 139      <listitem>
 140       <para>
 141        <!-- Note: replaceable is maybe the wrong tag, but generates  -->
 142        <!-- correct looking man output.                              -->
 143        After (optionally) writing the PID file, assume the user ID of
 144        <replaceable>user</replaceable> and the GID of
 145        <replaceable>group</replaceable>, or, if the optional
 146        <replaceable>group</replaceable> was not given, the default group of
 147        <replaceable>user</replaceable>. Exit if the privileges are not
 148        sufficient to do so.
 149      </para>
 150     </listitem>
 151   </varlistentry>
 152  </variablelist>
 153
 154  <para>
 155   If the <filename>configfile</filename> is not specified on  the  command  line,
 156   <command>Privoxy</command>  will  look for a file named
 157   <filename>config</filename> in the current directory (except on Win32 where
 158   it will try <filename>config.txt</filename>). If no
 159   <filename>configfile</filename> is found, <command>Privoxy</command> will
 160   fail to start.
 161  </para>
 162
 163 </refsect1>
 164
 165
 166 <!--   ~~~~~       New section      ~~~~~     -->
 167 <refsect1><title>Description</title>
 168 <!-- Include privoxy.sgml boilerplate: -->
 169  &p-intro;
 170 <!-- end boilerplate -->
 171 </refsect1>
 172
 173
 174 <!--   ~~~~~       New section      ~~~~~     -->
 175 <refsect1><title>Installation and Usage</title>
 176 <para>
 177  Browsers must be individually configured to use <command>Privoxy</command> as
 178  a HTTP proxy.  The default setting is  for  localhost,  on port  8118
 179  (configurable in the main config file).  To set the HTTP proxy in Netscape
 180  and Mozilla, go through:  <command>Edit</command>;
 181  <command>Preferences</command>;  <command>Advanced</command>;
 182  <command>Proxies</command>;  <command>Manual Proxy Configuration</command>;
 183  <command>View</command>.
 184 </para>
 185 <para>
 186  For Internet Explorer, go through: <command>Tools</command>;
 187  <command>Internet Properties</command>; <command>Connections</command>;
 188  <command>LAN Settings</command>.
 189 </para>
 190 <para>
 191  The Secure (SSL) Proxy should also be set to the same values, otherwise
 192  https: URLs will not be proxied.
 193 </para>
 194 <para>
 195  For other browsers, check the documentation.
 196 </para>
 197 </refsect1>
 198
 199
 200 <!--   ~~~~~       New section      ~~~~~     -->
 201 <refsect1><title>Configuration</title>
 202 <para>
 203  <command>Privoxy</command> can be configured with the various configuration
 204  files. The default configuration files are: <filename>config</filename>,
 205  <filename>default.action</filename>, and
 206  <filename>default.filter</filename>. These are well commented.  On Unix and
 207  Unix-like systems, these are located in <filename>/etc/privoxy/</filename> by
 208  default. On Windows, OS/2 and AmigaOS, these files are in the same directory
 209  as the <command>Privoxy</command> executable.
 210 </para>
 211 <para>
 212  The name and number of configuration files has changed from previous
 213  versions, and is subject to change as development progresses. In fact, the
 214  configuration itself is changed  and  much more sophisticated. See the
 215  <ulink url="http://www.privoxy.org/user-manual/">user-manual</ulink> for a
 216  brief explanation of all configuration options.
 217 </para>
 218 <para>
 219  The actions list (ad blocks, etc) can also be configured with your
 220  web browser at <ulink url="http://ijbswa.sourceforge.net/config">http://ijbswa.sourceforge.net/config</ulink>.
 221  <command>Privoxy's</command> configuration parameters  can also  be viewed at
 222  the same page. In addition, <command>Privoxy</command> can be toggled on/off.
 223  This is an internal page.
 224 </para>
 225 </refsect1>
 226
 227
 228 <!--   ~~~~~       New section      ~~~~~     -->
 229 <refsect1><title>Sample Configuration</title>
 230 <para>
 231  A brief example of what a <filename>default.action</filename> configuration
 232  might look like:
 233 </para>
 234
 235 <literallayout>
 236
 237  # Define a few useful custom aliases for later use
 238  {{alias}}
 239
 240  # Don't accept cookies
 241  +no-cookies = +no-cookies-set +no-cookies-read
 242
 243  # Do accept cookies
 244  -no-cookies = -no-cookies-set -no-cookies-read
 245
 246  # Treat these blocked URLs as images.
 247  +imageblock = +block +image
 248
 249  # Define page filters we want to use.
 250  myfilters = +filter{html-annoyances} +filter{js-annoyances}\
 251              +filter{no-popups} +filter{webbugs}
 252
 253  ## Default Policies (actions) ############################
 254  { \
 255   -block \
 256   -downgrade \
 257   +fast-redirects \
 258   myfilters \
 259   +no-compression \
 260   +hide-forwarded \
 261   +hide-from{block} \
 262   +hide-referer{forge} \
 263   -hide-user-agent \
 264   -image \
 265   +image-blocker{blank} \
 266   +no-cookies-keep \
 267   -no-cookies-read \
 268   -no-cookies-set \
 269   +no-popups \
 270   -vanilla-wafer \
 271   -wafer \
 272  }
 273  /
 274
 275  # Now set exceptions to the above defined policies #######
 276
 277  # Sites where we want persistant cookies
 278  {-no-cookies -no-cookies-keep}
 279   .redhat.com
 280   .sun.com
 281   .yahoo.com
 282   .msdn.microsoft.com
 283
 284  # This site requires cookies AND 'fast-redirects' on
 285  {-no-cookies -no-cookies-keep -fast-redirects}
 286   .nytimes.com
 287
 288  # Add custom headers, and turn off filtering of page source
 289  {+add-header{X-Privacy: Yes please} #-add-header{*} \
 290   +add-header{X-User-Tracking: No thanks!} -filter}
 291   privacy.net
 292
 293  # Block, and treat these URLs as 'images'.
 294  {+imageblock}
 295   .adforce.imgis.com
 296   .ad.preferences.com/image.*
 297   .ads.web.aol.com
 298   .ad-adex3.flycast.com
 299   .ad.doubleclick.net
 300   .ln.doubleclick.net
 301   .ad.de.doubleclick.net
 302   /.*/count\.cgi\?.*df=
 303   194.221.183.22[1-7]
 304   a196.g.akamai.net/7/196/2670/000[12]/images.gmx.net/i4/images/.*/
 305
 306  # Block any URLs that match these patterns
 307  {+block}
 308   /.*/(.*[-_.])?ads?[0-9]?(/|[-_.].*|\.(gif|jpe?g))
 309   /.*/(plain|live|rotate)[-_.]?ads?/
 310   /.*/(sponsor)s?[0-9]?/
 311   /.*/ad(server|stream|juggler)\.(cgi|pl|dll|exe)
 312   /.*/adbanners/
 313   /.*/adv((er)?ts?|ertis(ing|ements?))?/
 314   /.*/banners?/
 315   /.*/popupads/
 316   /.*/advert[0-9]+\.jpg
 317   /ad_images/
 318   /.*/ads/
 319   /images/.*/.*_anim\.gif
 320   /rotations/
 321   /.*(ms)?backoff(ice)?.*\.(gif|jpe?g)
 322   195.63.104.*/(inbox|log|meld|folderlu|folderru|log(in|out)[lmr]u|)
 323   .images.nytimes.com
 324   .images.yahoo.com/adv/
 325   /.*cnnstore\.gif
 326
 327 </literallayout>
 328
 329 <para>
 330  See the comments in the configuration files themselves, or the
 331  <citetitle>user-manual</citetitle>
 332  for explanations of the above syntax, and other <command>Privoxy</command>
 333  configuration options.
 334 </para>
 335
 336 </refsect1>
 337
 338
 339 <!--   ~~~~~       New section      ~~~~~     -->
 340 <refsect1><title>Files</title>
 341 <!-- this is a cheesy way to do this, but WTF. -->
 342 <literallayout>
 343  <filename>/usr/sbin/privoxy</filename>
 344  <filename>/etc/privoxy/config</filename>
 345  <filename>/etc/privoxy/default.action</filename>
 346  <filename>/etc/privoxy/advanced.action</filename>
 347  <filename>/etc/privoxy/basic.action</filename>
 348  <filename>/etc/privoxy/intermediate.action</filename>
 349  <filename>/etc/privoxy/default.filter</filename>
 350  <filename>/etc/privoxy/trust</filename>
 351  <filename>/etc/privoxy/templates/*</filename>
 352  <filename>/var/log/privoxy/logfile</filename>
 353 </literallayout>
 354
 355 <para>
 356  Various other files should be included, but may vary depending on platform
 357  and build configuration. More documentation should be included in the local
 358  documentation directory, though is not complete at this time.
 359 </para>
 360
 361 </refsect1>
 362
 363
 364 <!--   ~~~~~       New section      ~~~~~     -->
 365 <refsect1><title>Signals</title>
 366 <para>
 367  <!-- command tag is used here to get proper looking format  -->
 368  <command>Privoxy</command> terminates on the <command>SIGINT</command>,
 369  <command>SIGTERM</command> and <command>SIGABRT</command> signals. Log
 370  rotation scripts may cause a re-opening of the logfile by sending a
 371  <command>SIGHUP</command> to <command>Privoxy</command>. Note that unlike
 372  other daemons,  <command>Privoxy</command> does not need to be made aware of
 373  config file changes by <command>SIGHUP</command> -- it will detect them
 374  automatically.
 375 </para>
 376
 377 </refsect1>
 378
 379 <!--   ~~~~~       New section      ~~~~~     -->
 380 <refsect1><title>Notes</title>
 381 <![%p-not-stable;[
 382 <para>
 383  This is a &p-status; version of <command>Privoxy</command>. Not
 384  all features are well tested.
 385 </para>]]>
 386 <para>
 387  Please see the <citetitle>user-manual</citetitle> on how to contact the
 388  developers for feature requests, reporting problems, and other questions.
 389 </para>
 390
 391 </refsect1>
 392
 393 <!--   ~~~~~       New section      ~~~~~     -->
 394 <refsect1><title>See Also</title>
 395 <!-- Include seealso.sgml boilerplate: -->
 396  &seealso;
 397 <!-- end boilerplate -->
 398 </refsect1>
 399
 400 <!--   ~~~~~       New section      ~~~~~     -->
 401 <refsect1><title>Development Team</title>
 402 <!-- Include p-authors.sgml boilerplate: -->
 403  &authors;
 404 <!-- end boilerplate -->
 405 </refsect1>
 406
 407 <!--   ~~~~~       New section      ~~~~~     -->
 408 <refsect1><title>Copyright and License</title>
 409 <!-- Include seealso.sgml boilerplate: -->
 410  &copyright;
 411 <!-- end boilerplate -->
 412 </refsect1>
 413
 414 </refentry>