This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: user-manual.sgml,v 1.60 2002/03/27 01:57:34 hal9 Exp $
+ $Id: user-manual.sgml,v 1.61 2002/03/29 01:31:08 hal9 Exp $
Written by and Copyright (C) 2001 the SourceForge
Privoxy team. http://www.privoxy.org/
<artheader>
<title>Privoxy User Manual</title>
-<pubdate>$Id: user-manual.sgml,v 1.60 2002/03/27 01:57:34 hal9 Exp $</pubdate>
+<pubdate>$Id: user-manual.sgml,v 1.61 2002/03/29 01:31:08 hal9 Exp $</pubdate>
<authorgroup>
<author>
Improved cookie management features (e.g. session based cookies).
</para>
</listitem>
+
+ <listitem>
+ <para>
+ Improved signal handling, and a true daemon mode (Unix).
+ </para>
+</listitem>
<listitem>
<para>
<!-- ~ End section ~ -->
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect1 id="quickstart"><title>Quickstart to Using <application>Privoxy</application></title>
+<para>
+ Before launching <application>Privoxy</application> for the first time, you
+ will want to configure your browser(s) to use <application>Privoxy</application>
+ and the HTTP and HTTPS proxy. The default is localhost for the proxy address,
+ and port 8118 (earlier versions used port 800). This is the one required
+ configuration that must be done!
+</para>
+
+<para>
+ With <application>Netscape</application> (and
+ <application>Mozilla</application>), this can be set under <literal>Edit
+ -> Preferences -> Advanced -> Proxies -> HTTP Proxy</literal>.
+ For <application>Internet Explorer</application>: <literal>Tools >
+ Internet Properties -> Connections -> LAN Setting</literal>. Then,
+ check <quote>Use Proxy</quote> and fill in the appropriate info (Address:
+ localhost, Port: 8118). Include if HTTPS proxy support too.
+</para>
+
+<para>
+ After doing this, flush your browser's disk and memory caches to force a
+ re-reading of all pages and get rid of any ads that may be cached. You
+ are now ready to start enjoying the benefits of using
+ <application>Privoxy</application>.
+</para>
+
+
+<para>
+ <application>Privoxy</application> is typically started by specifying the
+ main configuration file to be used on the command line. Example Unix startup
+ command:
+</para>
+
+<para>
+ <screen>
+
+ # /usr/sbin/privoxy /etc/privoxy/config
+
+ </screen>
+</para>
+
+<para>
+ An init script is provided for SuSE and Redhat.
+</para>
+
+<para>
+For for SuSE: /etc/rc.d/privoxy start
+</para>
+
+<para>
+For RedHat: /etc/rc.d/init.d/privoxy start
+</para>
+
+
+<para>
+ 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>. If no file is specified on the
+ command line and no default configuration file can be found,
+ <application>Privoxy</application> will fail to start.
+</para>
+
+
+<para>
+ The included default configuration files should give a reasonable starting
+ point, though may be somewhat aggressive in blocking junk. Most of the
+ per site configuration is done in the <quote>actions</quote> 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 that require persistent
+ cookies, and add these to <filename>default.action</filename> as needed. By
+ default, most of these will be accepted only during the current browser
+ session, until you add them to the configuration. If you want the browser to
+ handle this instead, you will need to edit
+ <filename>default.action</filename> 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>
+ <application>Privoxy</application> is HTTP/1.1 compliant, but not all 1.1
+ features are as yet implemented. If browsers that support HTTP/1.1 (like
+ <application>Mozilla</application> or recent versions of I.E.) experience
+ problems, you might try to force HTTP/1.0 compatibility. For Mozilla, look
+ under <literal>Edit -> Preferences -> Debug -> Networking</literal>.
+ Or set the <quote>+downgrade</quote> config option in
+ <filename>default.action</filename>.
+</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> (as specified in <filename>default.action</filename>)
+ can be adjusted by pointing your browser to
+ <ulink url="http://p.p/">http://p.p/</ulink>,
+ and then follow the link to <quote>edit the actions list</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 <filename>default.action</filename> file
+ editor mentioned above, <application>Privoxy</application> can also
+ be turned <quote>on</quote> and <quote>off</quote> from this page.
+</para>
+
+<para>
+ If you encounter problems, please verify it is a
+ <application>Privoxy</application> bug, by disabling
+ <application>Privoxy</application>, and then trying the same page.
+ Also, try another browser if possible to eliminate browser or site
+ problems. Before reporting it as a bug, see if there is not a configuration
+ option that is enabled that is causing the page not to load. You can then add
+ an exception for that page or site. For instance, try adding it to the
+ <literal>{fragile}</literal> section of <filename>default.action</filename>.
+ This will turn off most actions for this site. For more on troubleshooting
+ problem sites, see the <ulink
+ url="appendix.html#ACTIONSANAT">Appendix</ulink>. If a bug, please report it
+ to the developers (see below).
+</para>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect2>
+<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 a 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, 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. Failiure 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>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.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+</para>
+
+</sect2>
+
+</sect1>
+
+<!-- ~ End section ~ -->
+
+
<!-- ~~~~~ New section ~~~~~ -->
<sect1 id="configuration"><title><application>Privoxy</application> Configuration</title>
<para>
<para>
<application>Privoxy</application> can be reached by the special
URL <ulink url="http://p.p/">http://p.p/</ulink> (or alternately
- <ulink url="http://www.privoxy.org/config/">http://www.privoxy.org/config/</ulink>),
+ <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>),
which is an internal page. You will see the following section:
</para>
-<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="quickstart"><title>Quickstart to Using <application>Privoxy</application></title>
-<para>
- Install package, then run and enjoy! <application>Privoxy</application>
- is typically started by specifying the main configuration file to be
- used on the command line. Example Unix startup command:
-</para>
-
-<para>
- <screen>
-
- # /usr/sbin/privoxy /etc/privoxy/config
-
- </screen>
-</para>
-
-<para>
- An init script is provided for SuSE and Redhat.
-</para>
-
-<para>
-For for SuSE: /etc/rc.d/privoxy start
-</para>
-
-<para>
-For RedHat: /etc/rc.d/init.d/privoxy start
-</para>
-
-
-<para>
- 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>. If no file is specified on the
- command line and no default configuration file can be found,
- <application>Privoxy</application> will fail to start.
-</para>
-
-<para>
- Be sure your browser is set to use the proxy which is by default at
- localhost, port 8118. With <application>Netscape</application> (and
- <application>Mozilla</application>), this can be set under <literal>Edit
- -> Preferences -> Advanced -> Proxies -> HTTP Proxy</literal>.
- For <application>Internet Explorer</application>: <literal>Tools >
- Internet Properties -> Connections -> LAN Setting</literal>. Then,
- check <quote>Use Proxy</quote> and fill in the appropriate info (Address:
- localhost, Port: 8118). Include if HTTPS proxy support too.
-</para>
-
-<para>
- The included default configuration files should give a reasonable starting
- point, though may be somewhat aggressive in blocking junk. You will probably
- want to keep an eye out for sites that require persistent cookies, and add these to
- <filename>default.action</filename> as needed. By default, most of these will
- be accepted only during the current browser session, until you add them to
- the configuration. If you want the browser to handle this instead, you will
- need to edit <filename>default.action</filename> 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>
- If a particular site shows problems loading properly, try adding it
- to the <literal>{fragile}</literal> section of
- <filename>default.action</filename>. This will turn off most actions for
- this site.
-</para>
-
-<para>
- <application>Privoxy</application> is HTTP/1.1 compliant, but not all 1.1
- features are as yet implemented. If browsers that support HTTP/1.1 (like
- <application>Mozilla</application> or recent versions of I.E.) experience
- problems, you might try to force HTTP/1.0 compatibility. For Mozilla, look
- under <literal>Edit -> Preferences -> Debug -> Networking</literal>.
- Or set the <quote>+downgrade</quote> config option in
- <filename>default.action</filename>.
-</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> (as specified in <filename>default.action</filename>)
- can be adjusted by pointing your browser to
- <ulink url="http://p.p/">http://p.p/</ulink>,
- and then follow the link to <quote>edit the actions list</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 <filename>default.action</filename> file
- editor mentioned above, <application>Privoxy</application> can also
- be turned <quote>on</quote> and <quote>off</quote> from this page.
-</para>
-
-<para>
- If you encounter problems, please verify it is a
- <application>Privoxy</application> bug, by disabling
- <application>Privoxy</application>, and then trying the same page.
- Also, try another browser if possible to eliminate browser or site
- problems. Before reporting it as a bug, see if there is not a configuration
- option that is enabled that is causing the page not to load. You can
- then add an exception for that page or site. If a bug, please report it to
- the developers (see below).
-</para>
-
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-
-<sect2>
-<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 a 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, 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. Failiure 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>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.
- </para>
- </listitem>
-
- </itemizedlist>
-</para>
-
-</sect2>
-
-</sect1>
-
-<!-- ~ End section ~ -->
-
-
-
<!-- ~~~~~ New section ~~~~~ -->
<sect1 id="contact"><title>Contacting the Developers, Bug Reporting and Feature
<para>
Since <application>Privoxy</application> proxies each requested
web page, it is easy for <application>Privoxy</application> to
- trap certain URLs. In this way, we can talk directly to
+ trap certain special URLs. In this way, we can talk directly to
<application>Privoxy</application>, and see how it is
configured, see how our rules are being applied, change these
rules and other configuration options, and even turn
</para>
<blockquote>
<para>
- <ulink url="http://www.privoxy.org/config/">http://www.privoxy.org/config/</ulink>
+ <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
</para>
</blockquote>
<para>
</para>
<blockquote>
<para>
- <ulink url="http://www.privoxy.org/config/show-status">http://www.privoxy.org/config/show-status</ulink>
+ <ulink url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
</para>
</blockquote>
</listitem>
</para>
<blockquote>
<para>
- <ulink url="http://www.privoxy.org/config/show-version">http://www.privoxy.org/config/show-version</ulink>
+ <ulink url="http://config.privoxy.org/show-version">http://config.privoxy.org/show-version</ulink>
</para>
</blockquote>
</listitem>
</para>
<blockquote>
<para>
- <ulink url="http://www.privoxy.org/config/show-request">http://www.privoxy.org/config/show-request</ulink>
+ <ulink url="http://config.privoxy.org/show-request">http://config.privoxy.org/show-request</ulink>
</para>
</blockquote>
</listitem>
</para>
<blockquote>
<para>
- <ulink url="http://www.privoxy.org/config/show-url-info">http://www.privoxy.org/config/show-url-info</ulink>
+ <ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
</para>
</blockquote>
</listitem>
<listitem>
<para>
- Toggle Privoxy on or off:
+ Toggle Privoxy on or off. In this case, <quote>Privoxy</quote> continues
+ to run, but only as a pass-through proxy, with no actions taking place:
</para>
<blockquote>
<para>
- <ulink url="http://www.privoxy.org/config/toggle">http://www.privoxy.org/config/toggle</ulink>
+ <ulink url="http://config.privoxy.org/toggle">http://config.privoxy.org/toggle</ulink>
</para>
</blockquote>
<para>
</para>
<blockquote>
<para>
- <ulink url="http://www.privoxy.org/config/toggle?set=disable">http://www.privoxy.org/config/toggle?set=disable</ulink>
+ <ulink url="http://config.privoxy.org/toggle?set=disable">http://config.privoxy.org/toggle?set=disable</ulink>
</para>
</blockquote>
<blockquote>
<para>
- <ulink url="http://www.privoxy.org/config/toggle?set=enable">http://www.privoxy.org/config/toggle?set=enable</ulink>
+ <ulink url="http://config.privoxy.org/toggle?set=enable">http://config.privoxy.org/toggle?set=enable</ulink>
</para>
</blockquote>
</listitem>
</para>
<blockquote>
<para>
- <ulink url="http://www.privoxy.org/config/edit-actions">http://www.privoxy.org/config/edit-actions</ulink>
+ <ulink url="http://config.privoxy.org/edit-actions">http://config.privoxy.org/edit-actions</ulink>
</para>
</blockquote>
</listitem>
</para>
+<sect3 id="bookmarklets">
+<title>Bookmarklets</title>
+<para>
+ Here are some bookmarklets to allow you to easily access a
+ <quote>mini</quote> version of this page. They are designed for MS Internet
+ Explorer, but should work equally well in Netscape, Mozilla, and other
+ browsers which support JavaScript. They are designed to run directly from
+ your bookmarks - not by clicking the links below (although that will work for
+ testing).
+</para>
+<para>
+ To save them, right-click the link and choose <quote>Add to Favorites</quote>
+ (IE) or <quote>Add Bookmark</quote> (Netscape). You will get a warning that
+ the bookmark <quote>may not be safe</quote> - just click OK. Then you can run the
+ Bookmarklet directly from your favourites/bookmarks. For even faster access,
+ you can put them on the <quote>Links</quote> bar (IE) or the <quote>Personal
+ Toolbar</quote> (Netscape), and run them with a single click.
+</para>
+
+<para>
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <ulink url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&set=enabled','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Enable Privoxy</ulink>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <ulink url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&set=disabled','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Disable Privoxy</ulink>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <ulink url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&set=toggle','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Toggle Privoxy</ulink> (Toggles between enabled and disabled)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <ulink url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y','ijbstatus','width=250,height=2,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">View Privoxy Status</ulink>
+ </para>
+ </listitem>
+
+ </itemizedlist>
+</para>
+
+<para>
+ Credit: The site which gave me the general idea for these bookmarklets is
+ <ulink url="http://www.bookmarklets.com">www.bookmarklets.com</ulink>. They
+ have more information about bookmarklets.
+</para>
+
+
+</sect3>
+
</sect2>
the actions files themselves, since they tend to be filled with
<quote>regular expressions</quote> whose consequences are not always
so obvious. <application>Privoxy</application> provides the
- <ulink url="http://www.privoxy.org/config/show-url-info">http://www.privoxy.org/config/show-url-info</ulink>
+ <ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
page that can show us very specifically how <application>actions</application>
are being applied to any given URL. This is a big help for troubleshooting.
</para>
Temple Place - Suite 330, Boston, MA 02111-1307, USA.
$Log: user-manual.sgml,v $
+ Revision 1.61 2002/03/29 01:31:08 hal9
+ Minor update.
+
Revision 1.60 2002/03/27 01:57:34 hal9
Added more to Anatomy section.
projects / privoxy.git / commitdiff