[ Copyright 2001 - 2007 by Privoxy Developers ]
-$Id: user-manual.sgml,v 2.44 2007/11/15 03:30:20 hal9 Exp $
+$Id: user-manual.sgml,v 2.49 2007/12/06 18:21:55 fabiankeil Exp $
The Privoxy User Manual gives users information on how to install, configure
and use Privoxy.
2.1. Binary Packages
2.1.1. Red Hat and Fedora RPMs
- 2.1.2. Debian
+ 2.1.2. Debian and Ubuntu
2.1.3. Windows
2.1.4. Solaris
2.1.5. OS/2
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-2.1.2. Debian
+2.1.2. Debian and Ubuntu
DEBs can be installed with apt-get install privoxy, and will use /etc/privoxy
for the location of configuration files.
will not be overwritten, and the new ones will be installed with a "new"
extension. default.action, default.filter, and standard.action will be
overwritten. You will then need to manually update the other installed
-configuration files as needed. All template files will be overwritten. If you
-have customized, local templates, you should save these first, and in fact it
-is wise to always save any important configuration files "just in case". If a
-previous version of Privoxy is already running, you will have to restart it
-manually.
+configuration files as needed. The default template files will be overwritten.
+If you have customized, local templates, these should be stored safely in a
+separate directory and defined in config by the "templdir" directive. It is of
+course wise to always back-up any important configuration files "just in case".
+If a previous version of Privoxy is already running, you will have to restart
+it manually.
For more detailed instructions on how to build Redhat RPMs, Windows
self-extracting installers, building on platforms with special requirements
A quick list of things to be aware of before upgrading from earlier versions of
Privoxy:
- • Some installers may remove earlier versions completely, including
- configuration files. Save any important configuration files!
+ • The recommended way to upgrade Privoxy is to backup your old configuration
+ files, install the new ones, verify that Privoxy is working correctly and
+ finally merge back your changes using diff and maybe patch.
- • 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.
+ There are a number of new features in each Privoxy 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 Privoxy isn't always possible anyway.
+
+ • Note that some installers remove earlier versions completely, including
+ configuration files, therefore you should really save any important
+ configuration files!
+
+ • On the other hand, other installers don't overwrite existing configuration
+ files, thinking you will want to do that yourself.
• standard.action now only includes the enabled actions. Not all actions as
before.
• Logging is off by default now. If you need logging, it can be turned on in
- the config file.
+ the config file. You may also want to enable logging until you verified
+ that the new Privoxy version is working as expected.
• Three other config file settings are now off by default:
enable-remote-toggle, enable-remote-http-toggle, and enable-edit-actions.
http://<URL> - A redirect to any image anywhere of the user's choosing
(advanced usage).
+Advanced users will eventually want to explore Privoxy filters as well. Filters
+are very different from blocks. A "block" 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 "no-no" for "nasty-word".
+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.
+
The quickest way to adjust any of these settings is with your browser through
the special Privoxy editor at http://config.privoxy.org/show-status (shortcut:
http://p.p/show-status). This is an internal page, and does not require
Client-header filters are executed after the other header actions have
finished and use their output as input.
+ If the request URL gets changed, Privoxy will detect that and use the new
+ one. This can be used to rewrite the request destination behind the
+ client's back, for example to specify a Tor exit relay for certain
+ requests.
+
Please refer to the filter file chapter to learn which client-header
filters are available by default, and how to create your own.
# This way you can continue to use Tor for your normal browsing,
# without overloading the Tor network with your FreeBSD ports updates
# or downloads of bigger files like ISOs.
+ # Note that HTTP headers are easy to fake and therefore their
+ # values are as (un)trustworthy as your clients and users.
{+forward-override{forward .} \
-hide-if-modified-since \
-overwrite-last-modified \
range of minutes where the random factor should be chosen from and Privoxy
does the rest. A negative value means subtracting, a positive value adding.
- Randomizing the value of the "If-Modified-Since:" makes sure it isn't used
- as a cookie replacement, but you will run into caching problems if the
- random range is too high.
+ Randomizing the value of the "If-Modified-Since:" makes it less likely that
+ the server can use the time as a cookie replacement, but you will run into
+ caching problems if the random range is too high.
It is a good idea to only use a small negative value and let
overwrite-last-modified handle the greater changes.
It is also recommended to use this action together with
- crunch-if-none-match.
+ crunch-if-none-match, otherwise it's more or less pointless.
Example usage (section):
- # Let the browser revalidate without being tracked across sessions
- { +hide-if-modified-since{-60} \
+ # Let the browser revalidate but make tracking based on the time less likely.
+ {+hide-if-modified-since{-60} \
+overwrite-last-modified{randomize} \
+crunch-if-none-match}
/
Typical use:
- Improve privacy by not embedding the source of the request in the HTTP
+ Improve privacy by not forwarding the source of the request in the HTTP
headers.
Effect:
- Deletes any existing "X-Forwarded-for:" HTTP header from client requests,
- and prevents adding a new one.
+ Deletes any existing "X-Forwarded-for:" HTTP header from client requests.
Type:
Notes:
- It is safe to leave this on.
+ It is safe and recommended to leave this on.
Example usage:
□ "conditional-block" to delete the header completely if the host has
changed.
+ □ "conditional-forge" to forge the header if the host has changed.
+
□ "block" to delete the header unconditionally.
□ "forge" to pretend to be coming from the homepage of the server we are
Always blocking the referrer, or using a custom one, can lead to failures
on servers that check the referrer before they answer any requests, in an
- attempt to prevent their valuable content from being embedded or linked to
+ attempt to prevent their content from being embedded or linked to
elsewhere.
Both conditional-block and forge will work with referrer checks, as long as
Typical use:
- Conceal your type of browser and client operating system
+ Try to conceal your type of browser and client operating system
Effect:
Typical use:
- To protect against the MS buffer over-run in JPEG processing
+ Try to protect against a MS buffer over-run in JPEG processing
Effect:
common image types found across the Internet. The exploit as described can
allow execution of code on the target system, giving an attacker access to
the system in question by merely planting an altered JPEG image, which
- would have no obvious indications of what lurks inside. This action
- prevents this exploit.
+ would have no obvious indications of what lurks inside. This action tries
+ to prevent this exploit if delivered through unencrypted HTTP.
- Note that the described exploit is only one of many, using this action does
- not mean that you no longer have to patch the client.
+ Note that the exploit mentioned is several years old and it's unlikely that
+ your client is still vulnerable against it. This action may be removed in
+ one of the next releases.
Example usage:
This action is most appropriate for browsers that don't have any controls
for unwanted pop-ups. Not recommended for general usage.
+ This action doesn't work very reliable and may be removed in future
+ releases.
+
Example usage:
+kill-popups
The CONNECT methods exists in HTTP to allow access to secure websites
("https://" URLs) through proxies. It works very simply: the proxy connects
to the server on the specified port, and then short-circuits its
- connections to the client and to the remote server. This can be a big
- security hole, since CONNECT-enabled proxies can be abused as TCP relays
- very easily.
+ connections to the client and to the remote server. This means
+ CONNECT-enabled proxies can be used as TCP relays very easily.
Privoxy relays HTTPS traffic without seeing the decoded content. Websites
can leverage this limitation to circumvent Privoxy's filters. By specifying
in user.action, but it will still be largely responsible for your overall
browsing experience.
-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 "+" preceding the action name
-enables the action, a "-" disables!). Also note how this long line has been
-made more readable by splitting it into multiple lines with line continuation.
+Again, at the start of matching, all actions are disabled, so there is no need
+to disable any actions here. (Remember: a "+" preceding the action name enables
+the action, a "-" disables!). Also note how this long line has been made more
+readable by splitting it into multiple lines with line continuation.
##########################################################################
# "Defaults" section:
##########################################################################
{ \
- -add-header \
- -client-header-filter{hide-tor-exit-notation} \
- -block \
- -content-type-overwrite \
- -crunch-client-header \
- -crunch-if-none-match \
- -crunch-incoming-cookies \
- -crunch-server-header \
- -crunch-outgoing-cookies \
+deanimate-gifs \
- -downgrade-http-version \
- -fast-redirects{check-decoded-url} \
- -filter{js-annoyances} \
- -filter{js-events} \
+filter{html-annoyances} \
- -filter{content-cookies} \
+filter{refresh-tags} \
- -filter{unsolicited-popups} \
- -filter{all-popups} \
- -filter{img-reorder} \
- -filter{banners-by-size} \
- -filter{banners-by-link} \
+filter{webbugs} \
- -filter{tiny-textforms} \
- -filter{jumping-windows} \
- -filter{frameset-borders} \
- -filter{demoronizer} \
- -filter{shockwave-flash} \
- -filter{quicktime-kioskmode} \
- -filter{fun} \
- -filter{crude-parental} \
+filter{ie-exploits} \
- -filter{google} \
- -filter{yahoo} \
- -filter{msn} \
- -filter{blogspot} \
- -filter{no-ping} \
- -force-text-mode \
- -handle-as-empty-document \
- -handle-as-image \
- -hide-accept-language \
- -hide-content-disposition \
- -hide-if-modified-since \
+hide-forwarded-for-headers \
+hide-from-header{block} \
+hide-referrer{forge} \
- -hide-user-agent \
- -inspect-jpegs \
- -kill-popups \
- -limit-connect \
+prevent-compression \
- -overwrite-last-modified \
- -redirect \
- -send-vanilla-wafer \
- -send-wafer \
- -server-header-filter{xml-to-html} \
- -server-header-filter{html-to-xml} \
+session-cookies-only \
+set-image-blocker{pattern} \
- -treat-forbidden-connects-like-blocks \
}
/ # forward slash will match *all* potential URL patterns.
-The default behavior is now set. Note that some actions, like not hiding the
-user agent, are part of a "general policy" that applies universally and won't
-get any exceptions defined later. Other choices, like not blocking (which is
-understandably the default!) need exceptions, i.e. we need to specify
-explicitly what we want to block in later sections.
+The default behavior is now set.
The first of our specialized sections is concerned with "fragile" sites, i.e.
sites that require minimum interference, because they are either very complex
So let's look at a few examples of things that one might typically do in
user.action:
-# My user.action file. <fred@foobar.com>
+# My user.action file. <fred@example.com>
As aliases are local to the actions file that they are defined in, you can't
{ +block }
www.example.com/nasty-ads/sponsor\.gif
- another.popular.site.net/more/junk/here/
+ another.example.net/more/junk/here/
The URLs of dynamically generated banners, especially from large banner farms,
You like the "fun" text replacements in default.filter, 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,
+the distributed actions file. So you'd like to turn it on in your private,
update-safe config, once and for all:
{ +filter{fun} }
Privoxy supports three different filter actions: filter to rewrite the content
that is send to the client, client-header-filter to rewrite headers that are
send by the client, and server-header-filter to rewrite headers that are send
-by the server, and
+by the server.
Privoxy also supports two tagger actions: client-header-tagger and
server-header-tagger. Taggers and filters use the same syntax in the filter
used to change the applying actions through sections with tag-patterns.
Multiple filter files can be defined through the filterfile config directive.
-The filters as supplied by the developers will be found in default.filter. It
-is recommended that any locally defined or modified filters go in a separately
+The filters as supplied by the developers are located in default.filter. It is
+recommended that any locally defined or modified filters go in a separately
defined file such as user.filter.
-Command tasks for content filters are to eliminate common annoyances in HTML
-and JavaScript, such as pop-up windows, exit consoles, crippled windows without
+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
width and height attributes (standard banner sizes or web-bugs), or just to
have fun.
-Content filtering works on any text-based document type, including HTML,
-JavaScript, CSS etc. (all text/* MIME types, except text/plain). Substitutions
-are made at the source level, so if you want to "roll your own" filters, you
-should first be familiar with HTML syntax, and, of course, regular expressions.
+Enabled content filters are applied to any content whose "Content Type" header
+is recognised as a sign of text-based content, with the exception of text/
+plain. Use the force-text-mode action to also filter other content.
+
+Substitutions are made at the source level, so if you want to "roll your own"
+filters, you should first be familiar with HTML syntax, and, of course, regular
+expressions.
Just like the actions files, the filter file is organized in sections, which
are called filters here. Each filter consists of a heading line, that starts
12. Privoxy Copyright, License and History
-Copyright 2001 - 2007 by Privoxy Developers <
+Copyright 2001-2007 by Privoxy Developers <
ijbswa-developers@lists.sourceforge.net>
Some source code is based on code Copyright 1997 by Anonymous Coders and
Remember to flush caches! Note that the mail.google reference lacks the TLD
-portion (e.g. ".com". This will effectively match any TLD with google in it,
-such as mail.google.de, just as an example.
+portion (e.g. ".com"). This will effectively match any TLD with google in it,
+such as mail.google.de., just as an example.
If this still does not work, you will have to go through the remaining actions
one by one to find which one(s) is causing the problem.
projects / privoxy.git / blobdiff