<!entity p-authors SYSTEM "p-authors.sgml">
<!entity config SYSTEM "p-config.sgml">
<!entity p-version "3.0.7">
-<!entity p-status "stable">
+<!entity p-status "beta">
<!entity % p-authors-formal "INCLUDE"> <!-- include additional text, etc -->
-<!entity % p-not-stable "IGNORE">
-<!entity % p-stable "INCLUDE">
+<!entity % p-not-stable "INCLUDE">
+<!entity % p-stable "IGNORE">
<!entity % p-text "IGNORE"> <!-- define we are not a text only doc -->
<!entity % p-doc "INCLUDE"> <!-- and we are a formal doc -->
<!entity % p-readme "IGNORE">
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: user-manual.sgml,v 2.37 2007/08/27 16:09:55 fabiankeil Exp $
+ $Id: user-manual.sgml,v 2.46 2007/11/17 17:24:44 fabiankeil Exp $
Copyright (C) 2001-2007 Privoxy Developers http://www.privoxy.org/
See LICENSE.
</subscript>
</pubdate>
-<pubdate>$Id: user-manual.sgml,v 2.37 2007/08/27 16:09:55 fabiankeil Exp $</pubdate>
+<pubdate>$Id: user-manual.sgml,v 2.46 2007/11/17 17:24:44 fabiankeil Exp $</pubdate>
<!--
</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 id="installation-deb"><title>Debian</title>
+<sect3 id="installation-deb"><title>Debian and Ubuntu</title>
<para>
DEBs can be installed with <literal>apt-get install privoxy</literal>,
and will use <filename>/etc/privoxy</filename> for the location of
in the same directory as you installed <application>Privoxy</application> in.
</para>
<para>
- Version 3.0.
4 introduced full <application>Windows</application> service
+ Version 3.0.
5 beta introduced full <application>Windows</application> service
functionality. On Windows only, the <application>Privoxy</application>
program has two new command line arguments to install and uninstall
<application>Privoxy</application> as a <emphasis>service</emphasis>.
</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 id="installation-pack-bintgz"><title>Solaris, NetBSD, HP-UX</title>
+<sect3 id="installation-pack-bintgz"><title>Solaris <!--, NetBSD, HP-UX--></title>
<para>
Create a new directory, <literal>cd</literal> to it, then unzip and
<para>
The port skeleton and the package can also be downloaded from the
<ulink url="https://sourceforge.net/project/showfiles.php?group_id=11118">File Release
- Page</ulink>, but if you're interested in stable releases only you don't
- gain anything by using them.
+ Page</ulink>, but there's no reason to use them unless you're interested in the
+ beta releases which are only available there.
</para>
</sect3>
<itemizedlist>
<listitem>
<para>
- Header filtering can be done with dedicated header filters now. As a result
+ Two new actions <link
+ linkend="server-header-tagger">server-header-tagger</link>
+ and <link
+ linkend="client-header-tagger">client-header-tagger</link>
+ that can be used to create arbitrary <quote>tags</quote>
+ based on client and server headers.
+ These <quote>tags</quote> can then subsequently be used
+ to control the other actions used for the current request,
+ greatly increasing &my-app;'s flexibility and selectivity. See <link
+ linkend="tag-pattern">tag patterns</link> for more information on tags.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Header filtering is done with dedicated header filters now. As a result
the actions <quote>filter-client-headers</quote> and <quote>filter-server-headers</quote>
that were introduced with <application>Privoxy 3.0.5</application> to apply
- the content filters to the headers as, well have been removed again.
+ content filters to the headers have been removed.
+ See the new actions <link
+ linkend="server-header-filter">server-header-filter</link>
+ and <link
+ linkend="client-header-filter">client-header-filter</link> for details.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ There are four new options for the main <filename>config</filename> file:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <link
+ linkend="allow-cgi-request-crunching">allow-cgi-request-crunching</link>
+ which allows requests for Privoxy's internal CGI pages to be
+ blocked, redirected or (un)trusted like ordinary requests.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link
+ linkend="split-large-forms">split-large-forms</link>
+ that will work around a browser bug that caused IE6 and IE7 to
+ ignore the Submit button on the Privoxy's edit-actions-for-url CGI
+ page.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link
+ linkend="accept-intercepted-requests">accept-intercepted-requests</link>
+ which allows to combine Privoxy with any packet filter to create an
+ intercepting proxy for HTTP/1.1 requests (and for HTTP/1.0 requests
+ with Host header set). This means clients can be forced to use
+ &my-app; even if their proxy settings are configured differently.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link
+ linkend="templdir">templdir</link>
+ to designate an alternate location for &my-app;'s
+ locally customized CGI templates so that
+ these are not overwritten during upgrades.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>
+ A new command line option <literal>--pre-chroot-nslookup hostname</literal> to
+ initialize the resolver library before chroot'ing. On some systems this
+ reduces the number of files that must be copied into the chroot tree.
+ (Patch provided by Stephen Gildea)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The <link
+ linkend="forward-override">forward-override</link> action
+ allows changing of the forwarding settings through the actions files.
+ Combined with tags, this allows to choose the forwarder based on
+ client headers like the <literal>User-Agent</literal>, or the request origin.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The <link
+ linkend="redirect">redirect</link> action can now use regular
+ expression substitutions against the original URL.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <application>zlib</application> support is now available as a compile
+ time option to filter compressed content. Patch provided by Wil Mahan.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Improve various filters, and add new ones.
+ </para>
+ </listitem>
+
+
+ <listitem>
+ <para>
+ Include support for RFC 3253 so that <filename>Subversion</filename> works
+ with &my-app;. Patch provided by Petr Kadlec.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Logging can be completely turned off by not specifying a logfile directive.
</para>
</listitem>
+
+ <listitem>
+ <para>
+ A number of improvements to Privoxy's internal CGI pages, including the
+ use of favicons for error and control pages.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Many bugfixes, memory leaks addressed, code improvements, and logging
+ improvements.
+ </para>
+ </listitem>
+
+
<!-- pre-3.0.6 changes:
<listitem>
<para>
</itemizedlist>
</para>
+<para>
+ For a more detailed list of changes please have a look at the ChangeLog.
+</para>
<!-- ~~~~~ New section ~~~~~ -->
<para>
<itemizedlist>
+ <listitem>
+ <para>
+ The recommended way to upgrade &my-app; is to backup your old
+ configuration files, install the new ones, verify that &my-app;
+ is working correctly and finally merge back your changes using
+ <application>diff</application> and maybe <application>patch</application>.
+ </para>
+ <para>
+ There are a number of new features in each &my-app; release and
+ most of them have to be explicitly enabled in the configuration
+ files. Old configuration files obviously don't do that and due
+ to syntax changes using old configuration files with a new
+ &my-app; isn't always possible anyway.
+ </para>
+ </listitem>
<listitem>
<para>
- Some installers may remove earlier versions completely, including
- configuration files. Save any important configuration files!
+ Note that some installers remove earlier versions completely,
+ including configuration files, therefore you should really save
+ any important configuration files!
</para>
</listitem>
<listitem>
<para>
- On the other hand, other installers may not overwrite any existing configuration
- files, thinking you will want to do that. You may want to manually check
- your saved files against the newer versions to see if the improvements have
- merit, or whether there are new options that you may want to consider.
- There are a number of new features, but most won't be available unless
- these features are incorporated into your configuration somehow.
+ On the other hand, other installers don't overwrite existing configuration
+ files, thinking you will want to do that yourself.
</para>
</listitem>
<listitem>
- <para>
- See the full documentation on
- <literal><link linkend="fast-redirects">fast-redirects</link></literal>
- which has changed syntax, and will require adjustments to local configs,
- such as <filename>user.action</filename>. You must reference the new
- syntax:
- </para>
- <para>
- <screen>
- { +fast-redirects{check-decoded-url} }
- .example.com
- mybank.com
- .google.</screen>
-</para>
+ <para>
+ <filename>standard.action</filename> now only includes the enabled actions.
+ Not all actions as before.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Logging is off by default now. If you need logging, it can be turned on
+ in the <link linkend="logfile">config file</link>. You may also want
+ to enable logging until you verified that the new &my-app; version
+ is working as expected.
+ </para>
+ </listitem>
- </listitem>
<listitem>
<para>
- The <filename>jarfile</filename>,
- <ulink url="http://en.wikipedia.org/wiki/Browser_cookie">cookie</ulink> logger, is off by default now.
+ Three other config file settings are now off by default:
+ <link linkend="enable-remote-toggle">enable-remote-toggle</link>,
+ <link linkend="enable-remote-http-toggle">enable-remote-http-toggle</link>,
+ and <link linkend="enable-edit-actions">enable-edit-actions</link>.
+ If you use or want these, you will need to explicitly enable them, and
+ be aware of the security issues involved.
</para>
</listitem>
+ <listitem>
+ <para>
+ The <quote>filter-client-headers</quote> and
+ <quote>filter-server-headers</quote> actions that were introduced with
+ <application>Privoxy 3.0.5</application> to apply content filters to
+ the headers have been removed and replaced with new actions.
+ See the <link
+ linkend="whatsnew">What's New section</link> above.
+ </para>
+ </listitem>
+
+
+<!--
<listitem>
<para>
What constitutes a <quote>default</quote> configuration has changed,
settings as yet (see above).
</para>
</listitem>
-
+-->
+<!--
<listitem>
<para>
The default actions setting is now <literal>Cautious</literal>. Previous
<listitem>
<para>
-<!-- I think it is best to keep this somewhat vague, in case -->
-<!-- the situation changes under our feet. -->
Some installers may not automatically start
<application>Privoxy</application> after installation.
</para>
</listitem>
-
+-->
</itemizedlist>
</para>
+
</sect2>
</sect1>
by setting the proxy configuration for address of
<literal>127.0.0.1</literal> and port <literal>8118</literal>.
<emphasis>DO NOT</emphasis> activate proxying for <literal>FTP</literal> or
- any protocols besides HTTP and HTTPS (SSL)! It won't work!
+ any protocols besides HTTP and HTTPS (SSL) unless you intend to prevent your
+ browser from using these protocols.
</para>
</listitem>
A default installation should provide a reasonable starting point for
most. There will undoubtedly be occasions where you will want to adjust the
configuration, but that can be dealt with as the need arises. Little
- to no initial configuration is required in most cases.
+ to no initial configuration is required in most cases, you may want
+ to enable the
+ <ulink url="config.html#ENABLE-EDIT-ACTIONS">web-based action editor</ulink> though.
+ Be sure to read the warnings first.
</para>
<para>
See the <link linkend="configuration">Configuration section</link> for more
</para>
</listitem>
+<!--
+ Did anyone test these lately?
+ fk 2007-11-10
<listitem>
<para>
For easy access to &my-app;'s most important controls, drag the provided
personal toolbar.
</para>
</listitem>
+-->
<listitem>
<para>
Now enjoy surfing with enhanced control, comfort and privacy!
</para>
</listitem>
-
+
</itemizedlist>
</para>
Secondly, a brief explanation of <application>Privoxy's </application>
<quote>actions</quote>. <quote>Actions</quote> in this context, are
the directives we use to tell <application>Privoxy</application> to perform
- some task relating to WWW transactions (i.e. web browsing). We tell
+ some task relating to HTTP transactions (i.e. web browsing). We tell
<application>Privoxy</application> to take some <quote>action</quote>. Each
action has a unique name and function. While there are many potential
<application>actions</application> in <application>Privoxy's</application>
</itemizedlist>
</para>
+<para>
+ Advanced users will eventually want to explore &my-app;
+ <literal><link linkend="filter">filters</link></literal> as well. Filters
+ are very different from <literal><link
+ linkend="block">blocks</link></literal>.
+ A <quote>block</quote> blocks a site, page, or unwanted contented. Filters
+ are a way of filtering or modifying what is actually on the page. An example
+ filter usage: a text replacement of <quote>no-no</quote> for
+ <quote>nasty-word</quote>. That is a very simple example. This process can be
+ used for ad blocking, but it is more in the realm of advanced usage and has
+ some pitfalls to be wary off.
+</para>
+
<para>
The quickest way to adjust any of these settings is with your browser through
the special <application>Privoxy</application> editor at <ulink
url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
(shortcut: <ulink url="http://p.p/">http://p.p/show-status</ulink>). This
- is an internal page, and does not require Internet access. Select the
- appropriate <quote>actions</quote> file, and click
+ is an internal page, and does not require Internet access.
+</para>
+
+<para>
+ Note that as of <application>Privoxy</application> 3.0.7 beta the
+ action editor is disabled by default. Check the
+ <ulink url="config.html#ENABLE-EDIT-ACTIONS">enable-edit-actions
+ section in the configuration file</ulink> to learn why and in which
+ cases it's safe to enable again.
+</para>
+
+<para>
+ If you decided to enable the action editor, select the appropriate
+ <quote>actions</quote> file, and click
<quote><guibutton>Edit</guibutton></quote>. It is best to put personal or
local preferences in <filename>user.action</filename> since this is not
meant to be overwritten during upgrades, and will over-ride the settings in
your browser.
</para>
+<para>
+ Note that several of the features described above are disabled by default
+ in <application>Privoxy</application> 3.0.7 beta and later.
+ Check the
+ <ulink url="config.html">configuration file</ulink> to learn why
+ and in which cases it's safe to enable them again.
+</para>
+
</sect2>
<!-- ~ End section ~ -->
The easiest way to edit the actions files is with a browser by
using our browser-based editor, which can be reached from <ulink
url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.
- The editor allows both fine-grained control over every single feature on a
- per-URL basis, and easy choosing from wholesale sets of defaults like
- <quote>Cautious</quote>, <quote>Medium</quote> or <quote>Advanced</quote>.
- Warning: the <quote>Advanced</quote> setting is more aggressive, and
- will be more likely to cause problems for some sites. Experienced users only!
-</para>
+ Note: the config file option <link
+ linkend="enable-edit-actions">enable-edit-actions</link> must be enabled for
+ this to work. The editor allows both fine-grained control over every single
+ feature on a per-URL basis, and easy choosing from wholesale sets of defaults
+ like <quote>Cautious</quote>, <quote>Medium</quote> or
+ <quote>Advanced</quote>. Warning: the <quote>Advanced</quote> setting is more
+ aggressive, and will be more likely to cause problems for some sites.
+ Experienced users only!
+ </para>
<para>
If you prefer plain text editing to GUIs, you can of course also directly edit the
can tell them apart from URL patterns. Everything after the colon
including white space, is interpreted as a regular expression with
path pattern syntax, except that tag patterns aren't left-anchored
- automatically (Privoxy doesn't silently add a <quote>^</quote>,
+ automatically (&my-app; doesn't silently add a <quote>^</quote>,
you have to do it yourself if you need it).
</para>
</para>
<para>
- For example you could tag client requests which use the POST method,
- use this tag to activate another tagger that adds a tag if cookies
- are send, and then block based on the cookie tag. However if you'd
- reverse the position of the described taggers, and activated the method
- tagger based on the cookie tagger, no method tags would be created.
+ For example you could tag client requests which use the
+ <literal>POST</literal> method,
+ then use this tag to activate another tagger that adds a tag if cookies
+ are sent, and then use a block action based on the cookie tag. This allows
+ the outcome of one action, to be input into a subsequent action. However if
+ you'd reverse the position of the described taggers, and activated the
+ method tagger based on the cookie tagger, no method tags would be created.
The method tagger would look for the request line, but at the time
- the cookie tag is created the request line has already been parsed.
+ the cookie tag is created, the request line has already been parsed.
</para>
<para>
<para>
<screen>
# Tag every request with the User-Agent header
-{+client-header-filter{user-agent}}
+{+client-header-tagger{user-agent}}
/
</screen>
</para>
<term>Typical use:</term>
<listitem>
<para>
- Disable or disable filters based on the Content-Type header.
+ Enable or disable filters based on the Content-Type header.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
<screen>
-# Tag every request with the declared content type
-{+client-header-filter{content-type}}
+# Tag every request with the content type declared by the server
+{+server-header-tagger{content-type}}
/
</screen>
</para>
<para>
Again, at the start of matching, all actions are disabled, so there is
- no real need to disable any actions here, but we will do that nonetheless,
- to have a complete listing for your reference. (Remember: a <quote>+</quote>
+ no need to disable any actions here. (Remember: a <quote>+</quote>
preceding the action name enables the action, a <quote>-</quote> disables!).
Also note how this long line has been made more readable by splitting it into
multiple lines with line continuation.
# "Defaults" section:
##########################################################################
{ \
- -<link linkend="ADD-HEADER">add-header</link> \
- -<link linkend="CLIENT-HEADER-FILTER">client-header-filter{hide-tor-exit-notation}</link> \
- -<link linkend="BLOCK">block</link> \
- -<link linkend="CONTENT-TYPE-OVERWRITE">content-type-overwrite</link> \
- -<link linkend="CRUNCH-CLIENT-HEADER">crunch-client-header</link> \
- -<link linkend="CRUNCH-IF-NONE-MATCH">crunch-if-none-match</link> \
- -<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> \
- -<link linkend="CRUNCH-SERVER-HEADER">crunch-server-header</link> \
- -<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link> \
+<link linkend="DEANIMATE-GIFS">deanimate-gifs</link> \
- -<link linkend="DOWNGRADE-HTTP-VERSION">downgrade-http-version</link> \
- -<link linkend="FAST-REDIRECTS">fast-redirects{check-decoded-url}</link> \
- -<link linkend="FILTER-JS-ANNOYANCES">filter{js-annoyances}</link> \
- -<link linkend="FILTER-JS-EVENTS">filter{js-events}</link> \
+<link linkend="FILTER-HTML-ANNOYANCES">filter{html-annoyances}</link> \
- -<link linkend="FILTER-CONTENT-COOKIES">filter{content-cookies}</link> \
+<link linkend="FILTER-REFRESH-TAGS">filter{refresh-tags}</link> \
- -<link linkend="FILTER-UNSOLICITED-POPUPS">filter{unsolicited-popups}</link> \
- -<link linkend="FILTER-ALL-POPUPS">filter{all-popups}</link> \
- -<link linkend="FILTER-IMG-REORDER">filter{img-reorder}</link> \
- -<link linkend="FILTER-BANNERS-BY-SIZE">filter{banners-by-size}</link> \
- -<link linkend="FILTER-BANNERS-BY-LINK">filter{banners-by-link}</link> \
+<link linkend="FILTER-WEBBUGS">filter{webbugs}</link> \
- -<link linkend="FILTER-TINY-TEXTFORMS">filter{tiny-textforms}</link> \
- -<link linkend="FILTER-JUMPING-WINDOWS">filter{jumping-windows}</link> \
- -<link linkend="FILTER-FRAMESET-BORDERS">filter{frameset-borders}</link> \
- -<link linkend="FILTER-DEMORONIZER">filter{demoronizer}</link> \
- -<link linkend="FILTER-SHOCKWAVE-FLASH">filter{shockwave-flash}</link> \
- -<link linkend="FILTER-QUICKTIME-KIOSKMODE">filter{quicktime-kioskmode}</link> \
- -<link linkend="FILTER-FUN">filter{fun}</link> \
- -<link linkend="FILTER-CRUDE-PARENTAL">filter{crude-parental}</link> \
+<link linkend="FILTER-IE-EXPLOITS">filter{ie-exploits}</link> \
- -<link linkend="FILTER-GOOGLE">filter{google}</link> \
- -<link linkend="FILTER-YAHOO">filter{yahoo}</link> \
- -<link linkend="FILTER-MSN">filter{msn}</link> \
- -<link linkend="FILTER-BLOGSPOT">filter{blogspot}</link> \
- -<link linkend="FILTER-NO-PING">filter{no-ping}</link> \
- -<link linkend="FORCE-TEXT-MODE">force-text-mode</link> \
- -<link linkend="HANDLE-AS-EMPTY-DOCUMENT">handle-as-empty-document</link> \
- -<link linkend="HANDLE-AS-IMAGE">handle-as-image</link> \
- -<link linkend="HIDE-ACCEPT-LANGUAGE">hide-accept-language</link> \
- -<link linkend="HIDE-CONTENT-DISPOSITION">hide-content-disposition</link> \
- -<link linkend="HIDE-IF-MODIFIED-SINCE">hide-if-modified-since</link> \
+<link linkend="HIDE-FORWARDED-FOR-HEADERS">hide-forwarded-for-headers</link> \
+<link linkend="HIDE-FROM-HEADER">hide-from-header{block}</link> \
+<link linkend="HIDE-REFERER">hide-referrer{forge}</link> \
- -<link linkend="HIDE-USER-AGENT">hide-user-agent</link> \
- -<link linkend="INSPECT-JPEGS">inspect-jpegs</link> \
- -<link linkend="KILL-POPUPS">kill-popups</link> \
- -<link linkend="LIMIT-CONNECT">limit-connect</link> \
+<link linkend="PREVENT-COMPRESSION">prevent-compression</link> \
- -<link linkend="OVERWRITE-LAST-MODIFIED">overwrite-last-modified</link> \
- -<link linkend="REDIRECT">redirect</link> \
- -<link linkend="SEND-VANILLA-WAFER">send-vanilla-wafer</link> \
- -<link linkend="SEND-WAFER">send-wafer</link> \
- -<link linkend="SERVER-HEADER-FILTER">server-header-filter{xml-to-html}</link> \
- -<link linkend="SERVER-HEADER-FILTER">server-header-filter{html-to-xml}</link> \
+<link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> \
+<link linkend="SET-IMAGE-BLOCKER">set-image-blocker{pattern}</link> \
- -<link linkend="TREAT-FORBIDDEN-CONNECTS-LIKE-BLOCKS">treat-forbidden-connects-like-blocks</link> \
}
/ # forward slash will match *all* potential URL patterns.</screen>
</para>
<para>
- The default behavior is now set. Note that some actions, like not hiding
+ The default behavior is now set.
+ <!--
+ This needs rewording, but it can wait for now.
+ fk 2007-11-17
+
+ Note that some actions, like not hiding
the user agent, are part of a <quote>general policy</quote> that applies
universally and won't get any exceptions defined later. Other choices,
like not blocking (which is <emphasis>understandably</emphasis> the
default!) need exceptions, i.e. we need to specify explicitly what we
want to block in later sections.
+ -->
</para>
<para>
<para>
<screen>
-# My user.action file. <fred@foobar.com></screen>
+# My user.action file. <fred@example.com></screen>
</para>
<para>
<screen>
{ +<link linkend="BLOCK">block</link> }
www.example.com/nasty-ads/sponsor\.gif
- another.popular.site.net/more/junk/here/</screen>
+ another.example.net/more/junk/here/</screen>
</para>
<para>
<para>
You like the <quote>fun</quote> text replacements in <filename>default.filter</filename>,
- but it is disabled in the distributed actions file. (My colleagues on the team just
- don't have a sense of humour, that's why! ;-). So you'd like to turn it on in your private,
+ but it is disabled in the distributed actions file.
+ So you'd like to turn it on in your private,
update-safe config, once and for all:
</para>
<literal><link linkend="client-header-filter">client-header-filter</link></literal>
to rewrite headers that are send by the client, and
<literal><link linkend="server-header-filter">server-header-filter</link></literal>
- to rewrite headers that are send by the server, and
+ to rewrite headers that are send by the server.
</para>
<para>
<literal><link linkend="client-header-tagger">client-header-tagger</link></literal>
and
<literal><link linkend="server-header-tagger">server-header-tagger</link></literal>.
- Taggers and filters use the same syntax in the filter files, the differnce
+ Taggers and filters use the same syntax in the filter files, the difference
is that taggers don't modify the text they are filtering, but use a rewritten
version of the filtered text as tag. The tags can then be used to change the
applying actions through sections with <link linkend="tag-pattern">tag-patterns</link>.
<para>
Multiple filter files can be defined through the <literal> <link
linkend="filterfile">filterfile</link></literal> config directive. The filters
- as supplied by the developers will be found in
+ as supplied by the developers are located in
<filename>default.filter</filename>. It is recommended that any locally
defined or modified filters go in a separately defined file such as
<filename>user.filter</filename>.
-
-</para>
+ </para>
<para>
- Command tasks for content filters are to eliminate common annoyances in
+ Common tasks for content filters are to eliminate common annoyances in
HTML and JavaScript, such as pop-up windows,
exit consoles, crippled windows without navigation tools, the
infamous <BLINK> tag etc, to suppress images with certain
</para>
<para>
- Content filtering works on any text-based document type, including
- HTML, JavaScript, CSS etc. (all <literal>text/*</literal>
- MIME types, <emphasis>except</emphasis> <literal>text/plain</literal>).
+ Enabled content filters are applied to any content whose
+ <quote>Content Type</quote> header is recognised as a sign
+ of text-based content, with the exception of <literal>text/plain</literal>.
+ Use the <link linkend="FORCE-TEXT-MODE">force-text-mode</link> action
+ to also filter other content.
+</para>
+
+<para>
Substitutions are made at the source level, so if you want to <quote>roll
your own</quote> filters, you should first be familiar with HTML syntax,
and, of course, regular expressions.
<para>
The templates are basically normal HTML files, but with place-holders (called symbols
- or exports), which <application>Privoxy</application> fills at run time. You can
- edit the templates with a normal text editor, should you want to customize them.
- (<emphasis>Not recommended for the casual user</emphasis>). Note that
- just like in configuration files, lines starting with <literal>#</literal> are
- ignored when the templates are filled in.
+ or exports), which <application>Privoxy</application> fills at run time. It
+ is possible to edit the templates with a normal text editor, should you want
+ to customize them. (<emphasis>Not recommended for the casual
+ user</emphasis>). Should you create your own custom templates, you should use
+ the <filename>config</filename> setting <link linkend="templdir">templdir</link>
+ to specify an alternate location, so your templates do not get overwritten
+ during upgrades.
+ </para>
+ <para>
+ Note that just like in configuration files, lines starting
+ with <literal>#</literal> are ignored when the templates are filled in.
</para>
<para>
<listitem>
<para>
- 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:
+ Toggle Privoxy on or off. This feature can be turned off/on in the main
+ <filename>config</filename> file. When toggled <quote>off</quote>, <quote>Privoxy</quote>
+ continues to run, but only as a pass-through proxy, with no actions taking
+ place:
</para>
<blockquote>
<para>
or not, is to disable it temporarily. This should be the first troubleshooting
step. See <link linkend="bookmarklets">the Bookmarklets</link> section on a quick
and easy way to do this (be sure to flush caches afterward!). Looking at the
- logs is a good idea too.
+ logs is a good idea too. (Note that both the toggle feature and logging are
+ enabled via <filename>config</filename> file settings, and may need to be
+ turned <quote>on</quote>.)
</para>
<para>
Another easy troubleshooting step to try is if you have done any
<para>
<emphasis>Remember to flush caches!</emphasis> Note that the
<literal>mail.google</literal> reference lacks the TLD portion (e.g.
- <quote>.com</quote>. This will effectively match any TLD with
- <literal>google</literal> in it, such as <literal>mail.google.de</literal>,
+ <quote>.com</quote>). This will effectively match any TLD with
+ <literal>google</literal> in it, such as <literal>mail.google.de.</literal>,
just as an example.
</para>
<para>
USA
$Log: user-manual.sgml,v $
+ Revision 2.46 2007/11/17 17:24:44 fabiankeil
+ - Use new action defaults.
+ - Minor fixes and rewordings.
+
+ Revision 2.45 2007/11/16 11:48:46 hal9
+ Fix one typo, and add a couple of small refinements.
+
+ Revision 2.44 2007/11/15 03:30:20 hal9
+ Results of spell check.
+
+ Revision 2.43 2007/11/14 18:45:39 fabiankeil
+ - Mention some more contributors in the "New in this Release" list.
+ - Minor rewordings.
+
+ Revision 2.42 2007/11/12 03:32:40 hal9
+ Updates for "What's New" and "Notes to Upgraders". Various other changes in
+ preparation for new release. User Manual is almost ready.
+
+ Revision 2.41 2007/11/11 16:32:11 hal9
+ This is primarily syncing What's New and Note to Upgraders sections with the many
+ new features and changes (gleaned from memory but mostly from ChangeLog).
+
+ Revision 2.40 2007/11/10 17:10:59 fabiankeil
+ In the first third of the file, mention several times that
+ the action editor is disabled by default in 3.0.7 beta and later.
+
+ Revision 2.39 2007/11/05 02:34:49 hal9
+ Various changes in preparation for the upcoming release. Much yet to be done.
+
+ Revision 2.38 2007/09/22 16:01:42 fabiankeil
+ Update embedded show-url-info output.
+
Revision 2.37 2007/08/27 16:09:55 fabiankeil
- Fix --pre-chroot-nslookup description which I failed to
+ Fix pre-chroot-nslookup description which I failed to
copy and paste properly. Reported by Stephen Gildea.
Revision 2.36 2007/08/26 16:47:14 fabiankeil
- Add Stephen Gildea's --pre-chroot-nslookup patch [#1276666],
+ Add Stephen Gildea's pre-chroot-nslookup patch [#1276666],
extensive comments moved to user manual.
Revision 2.35 2007/08/26 14:59:49 fabiankeil
projects / privoxy.git / blobdiff