X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fuser-manual.sgml;h=f50a10bfc073f719f43d79a5a483ca6d49d5805c;hp=b503ef44e26c7aa6b095db40627208c7c594e310;hb=9c113a4c0231441c0005cae73bc9e1cf32a71596;hpb=889bfbf7dae3d8e1e105c055fc05d61344913685
diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml
index b503ef44..f50a10bf 100644
--- a/doc/source/user-manual.sgml
+++ b/doc/source/user-manual.sgml
@@ -12,10 +12,10 @@
-
+
-
-
+
+
@@ -33,7 +33,7 @@
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: user-manual.sgml,v 2.34 2007/08/05 15:19:50 fabiankeil Exp $
+ $Id: user-manual.sgml,v 2.44 2007/11/15 03:30:20 hal9 Exp $
Copyright (C) 2001-2007 Privoxy Developers http://www.privoxy.org/
See LICENSE.
@@ -59,7 +59,7 @@
-$Id: user-manual.sgml,v 2.34 2007/08/05 15:19:50 fabiankeil Exp $
+$Id: user-manual.sgml,v 2.44 2007/11/15 03:30:20 hal9 Exp $
-Debian
+Debian and Ubuntu
DEBs can be installed with apt-get install privoxy,
and will use /etc/privoxy for the location of
@@ -227,7 +227,7 @@ How to install the binary packages depends on your operating system:
in the same directory as you installed Privoxy in.
- Version 3.0.4 introduced full Windows service
+ Version 3.0.5 beta introduced full Windows service
functionality. On Windows only, the Privoxy
program has two new command line arguments to install and uninstall
Privoxy as a service.
@@ -262,7 +262,7 @@ How to install the binary packages depends on your operating system:
-Solaris, NetBSD, HP-UX
+Solaris <!--, NetBSD, HP-UX-->
Create a new directory, cd to it, then unzip and
@@ -351,8 +351,8 @@ How to install the binary packages depends on your operating system:
The port skeleton and the package can also be downloaded from the
File Release
- Page, but if you're interested in stable releases only you don't
- gain anything by using them.
+ Page, but there's no reason to use them unless you're interested in the
+ beta releases which are only available there.
@@ -451,13 +451,145 @@ How to install the binary packages depends on your operating system:
- Header filtering can be done with dedicated header filters now. As a result
+ Two new actions server-header-tagger
+ and client-header-tagger
+ that can be used to create arbitrary tags
+ based on client and server headers.
+ These tags can then subsequently be used
+ to control the other actions used for the current request,
+ greatly increasing &my-app;'s flexibility and selectivity. See tag patterns for more information on tags.
+
+
+
+
+
+ Header filtering is done with dedicated header filters now. As a result
the actions filter-client-headers and filter-server-headers
that were introduced with Privoxy 3.0.5 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 server-header-filter
+ and client-header-filter for details.
+
+
+
+
+ There are four new options for the main config file:
+
+
+
+
+
+ allow-cgi-request-crunching
+ which allows requests for Privoxy's internal CGI pages to be
+ blocked, redirected or (un)trusted like ordinary requests.
+
+
+
+
+ split-large-forms
+ 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.
+
+
+
+
+ accept-intercepted-requests
+ 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.
+
+
+
+
+ templdir
+ to designate an alternate location for &my-app;'s
+ locally customized CGI templates so that
+ these are not overwritten during upgrades.
+
+
+
+
+
+
+
+ A new command line option --pre-chroot-nslookup hostname 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)
+
+
+
+
+
+ The forward-override 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 User-Agent, or the request origin.
+
+
+
+
+
+ The redirect action can now use regular
+ expression substitutions against the original URL.
+
+
+
+
+
+ zlib support is now available as a compile
+ time option to filter compressed content. Patch provided by Wil Mahan.
+
+
+
+
+ Improve various filters, and add new ones.
+
+
+
+
+
+
+ Include support for RFC 3253 so that Subversion works
+ with &my-app;. Patch provided by Petr Kadlec.
+
+
+
+
+
+ Logging can be completely turned off by not specifying a logfile directive.
+
+
+
+
+
+
+ A number of improvements to Privoxy's internal CGI pages, including the
+ use of favicons for error and control pages.
+
+
+ Many bugfixes, memory leaks addressed, code improvements, and logging
+ improvements.
+
+
+
+
@@ -638,6 +773,13 @@ How to install the binary packages depends on your operating system:
these features are incorporated into your configuration somehow.
+
+
+ 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 jarfile,
- cookie logger, is off by default now.
+ Three other config file settings are now off by default:
+ enable-remote-toggle,
+ enable-remote-http-toggle,
+ and enable-edit-actions.
+ If you use or want these, you will need to explicitly enable them, and
+ be aware of the security issues involved.
+
+
+ The filter-client-headers and
+ filter-server-headers actions that were introduced with
+ Privoxy 3.0.5 to apply content filters to
+ the headers have been removed and replaced with new actions.
+ See the What's New section above.
+
+
+
+
+
+
-
Some installers may not automatically start
Privoxy after installation.
-
+-->
+
@@ -769,7 +936,8 @@ How to install the binary packages depends on your operating system:
by setting the proxy configuration for address of
127.0.0.1 and port 8118.
DO NOT activate proxying for FTP 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.
@@ -787,7 +955,10 @@ How to install the binary packages depends on your operating system:
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
+ web-based action editor though.
+ Be sure to read the warnings first.
See the Configuration section for more
@@ -814,6 +985,9 @@ How to install the binary packages depends on your operating system:
+
@@ -835,7 +1010,7 @@ How to install the binary packages depends on your operating system:
Now enjoy surfing with enhanced control, comfort and privacy!
-
+
@@ -875,7 +1050,7 @@ How to install the binary packages depends on your operating system:
Secondly, a brief explanation of Privoxy's actions. Actions in this context, are
the directives we use to tell Privoxy 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
Privoxy to take some action. Each
action has a unique name and function. While there are many potential
actions in Privoxy's
@@ -991,13 +1166,38 @@ How to install the binary packages depends on your operating system:
+
+ Advanced users will eventually want to explore &my-app;
+ 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 Internet access. Select the
- appropriate actions file, and click
+ is an internal page, and does not require Internet access.
+
+
+
+ Note that as of Privoxy 3.0.7 beta the
+ action editor is disabled by default. Check the
+ enable-edit-actions
+ section in the configuration file to learn why and in which
+ cases it's safe to enable again.
+
+
+
+ If you decided to enable the action editor, select the appropriate
+ actions file, and click
Edit. It is best to put personal or
local preferences in user.action since this is not
meant to be overwritten during upgrades, and will over-ride the settings in
@@ -1513,7 +1713,6 @@ must find a better place for this paragraph
--pidfile FILE
-
On startup, write the process ID to FILE. Delete the
@@ -1525,7 +1724,6 @@ must find a better place for this paragraph
--user USER[.GROUP]
-
After (optionally) writing the PID file, assume the user ID of
@@ -1533,10 +1731,9 @@ must find a better place for this paragraph
privileges are not sufficient to do so. Unix only.
-
+ --chroot
-
Before changing to the user ID given in the --user option,
@@ -1546,6 +1743,24 @@ must find a better place for this paragraph
Unix only.
+
+
+ --pre-chroot-nslookup hostname
+
+
+ Specifies a hostname to look up before doing a chroot. On some systems, initializing the
+ resolver library involves reading config files from /etc and/or loading additional shared
+ libraries from /lib. On these systems, doing a hostname lookup before the chroot reduces
+ the number of files that must be copied into the chroot tree.
+
+
+ For fastest startup speed, a good value is a hostname that is not in /etc/hosts but that
+ your local name server (listed in /etc/resolv.conf) can resolve without recursion
+ (that is, without having to ask any other name servers). The hostname need not exist,
+ but if it doesn't, an error message (which can be ignored) will be output.
+
+
+
configfile
@@ -1652,6 +1867,14 @@ for details.
your browser.
+
+ Note that several of the features described above are disabled by default
+ in Privoxy 3.0.7 beta and later.
+ Check the
+ configuration file to learn why
+ and in which cases it's safe to enable them again.
+
+
@@ -2083,12 +2306,15 @@ for details.
The easiest way to edit the actions files is with a browser by
using our browser-based editor, which can be reached from http://config.privoxy.org/show-status.
- 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
- Cautious, Medium or Advanced.
- Warning: the Advanced setting is more aggressive, and
- will be more likely to cause problems for some sites. Experienced users only!
-
+ Note: the config file option enable-edit-actions 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 Cautious, Medium or
+ Advanced. Warning: the Advanced setting is more
+ aggressive, and will be more likely to cause problems for some sites.
+ Experienced users only!
+
If you prefer plain text editing to GUIs, you can of course also directly edit the
@@ -2466,7 +2692,7 @@ for details.
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 ^,
+ automatically (&my-app; doesn't silently add a ^,
you have to do it yourself if you need it).
@@ -2492,13 +2718,15 @@ for details.
- 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
+ POST 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.
@@ -2957,7 +3185,7 @@ for details.
# Tag every request with the User-Agent header
-{+client-header-filter{user-agent}}
+{+client-header-tagger{user-agent}}
/
@@ -5683,7 +5911,7 @@ example.org/instance-that-is-delivered-as-xml-but-is-not
Typical use:
- Disable or disable filters based on the Content-Type header.
+ Enable or disable filters based on the Content-Type header.
@@ -5745,8 +5973,8 @@ example.org/instance-that-is-delivered-as-xml-but-is-not
-# 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}}
/
@@ -6884,7 +7112,7 @@ stupid-server.example.com/
client-header-tagger
and
server-header-tagger.
- 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 tag-patterns.
@@ -7708,11 +7936,17 @@ pre-defined filters for your convenience:
The templates are basically normal HTML files, but with place-holders (called symbols
- or exports), which Privoxy fills at run time. You can
- edit the templates with a normal text editor, should you want to customize them.
- (Not recommended for the casual user). Note that
- just like in configuration files, lines starting with # are
- ignored when the templates are filled in.
+ or exports), which Privoxy fills at run time. It
+ is possible to edit the templates with a normal text editor, should you want
+ to customize them. (Not recommended for the casual
+ user). Should you create your own custom templates, you should use
+ the config setting templdir
+ to specify an alternate location, so your templates do not get overwritten
+ during upgrades.
+
+
+ Note that just like in configuration files, lines starting
+ with # are ignored when the templates are filled in.
@@ -8152,8 +8386,10 @@ Requests
- Toggle Privoxy on or off. In this case, Privoxy 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
+ config file. When toggled off, Privoxy
+ continues to run, but only as a pass-through proxy, with no actions taking
+ place:
@@ -8416,7 +8652,9 @@ Requests
or not, is to disable it temporarily. This should be the first troubleshooting
step. See the Bookmarklets 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 config file settings, and may need to be
+ turned on.)
Another easy troubleshooting step to try is if you have done any
@@ -8458,71 +8696,23 @@ Requests
- Matches for http://google.com:
+ Matches for http://www.google.com:
In file: default.action [ View ][ Edit ]
- {-add-header
- -block
- -client-header-filter{hide-tor-exit-notation}
- -content-type-overwrite
- -crunch-client-header
- -crunch-if-none-match
- -crunch-incoming-cookies
- -crunch-outgoing-cookies
- -crunch-server-header
- +deanimate-gifs {last}
- -downgrade-http-version
+ {+deanimate-gifs {last}
+fast-redirects {check-decoded-url}
- -filter {js-events}
- -filter {content-cookies}
- -filter {all-popups}
- -filter {banners-by-link}
- -filter {tiny-textforms}
- -filter {frameset-borders}
- -filter {demoronizer}
- -filter {shockwave-flash}
- -filter {quicktime-kioskmode}
- -filter {fun}
- -filter {crude-parental}
- -filter {site-specifics}
- -filter {js-annoyances}
- -filter {html-annoyances}
+filter {refresh-tags}
- -filter {unsolicited-popups}
+filter {img-reorder}
+filter {banners-by-size}
+filter {webbugs}
+filter {jumping-windows}
+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-forwarded-for-headers
+hide-from-header {block}
- -hide-if-modified-since
+hide-referrer {forge}
- -hide-user-agent
- -inspect-jpegs
- -kill-popups
- -limit-connect
- -overwrite-last-modified
- +prevent-compression
- -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 }
/
{ -session-cookies-only }
@@ -8609,7 +8799,7 @@ In file: user.action [ View ][ Edit ][ View ][ Edit ][ View ][ Edit ]
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,
+ .com). This will effectively match any TLD with
+ google in it, such as mail.google.de.,
just as an example.
@@ -8942,6 +9132,42 @@ In file: user.action [ View ][ Edit ]