X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fuser-manual.sgml;h=3928054806d7632931e33783789c7d3c035fad46;hp=ef133c0abd7647615049079674308be899d2f9b3;hb=1e978c46c5b5b21a8a283a9d62069cfc300ea0d1;hpb=c00b4ad9eb9ee9d9d023934a0c313fb54250fdc8
diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml
index ef133c0a..39280548 100644
--- a/doc/source/user-manual.sgml
+++ b/doc/source/user-manual.sgml
@@ -13,8 +13,8 @@
-
-
+
+
@@ -36,9 +36,9 @@
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: user-manual.sgml,v 2.192 2014/07/18 10:01:20 fabiankeil Exp $
+ $Id: user-manual.sgml,v 2.212 2016/05/25 10:50:55 fabiankeil Exp $
- Copyright (C) 2001-2014 Privoxy Developers http://www.privoxy.org/
+ Copyright (C) 2001-2016 Privoxy Developers https://www.privoxy.org/
See LICENSE.
========================================================================
@@ -57,12 +57,12 @@
- Copyright &my-copy; 2001-2014 by
- Privoxy Developers
+ Copyright &my-copy; 2001-2016 by
+ Privoxy Developers
-$Id: user-manual.sgml,v 2.192 2014/07/18 10:01:20 fabiankeil Exp $
+$Id: user-manual.sgml,v 2.212 2016/05/25 10:50:55 fabiankeil Exp $
@@ -101,14 +101,11 @@ Hal.
You can find the latest version of the Privoxy User Manual at http://www.privoxy.org/user-manual/.
+ url="https://www.privoxy.org/user-manual/">https://www.privoxy.org/user-manual/.
Please see the Contact section on how to
contact the developers.
-
-
-
@@ -162,7 +159,7 @@ Hal.
Privoxy is available both in convenient pre-compiled
packages for a wide range of operating systems, and as raw source code.
For most users, we recommend using the packages, which can be downloaded from our
- Privoxy Project
+ Privoxy Project
Page.
@@ -351,14 +348,14 @@ How to install the binary packages depends on your operating system:
The most convenient way to obtain the Privoxy sources
is to download the source tarball from our
- project download
+ project download
page.
If you like to live on the bleeding edge and are not afraid of using
possibly unstable development versions, you can check out the up-to-the-minute
- version directly from the
+ version directly from the
CVS repository.
-
Please see the section Contacting the
@@ -1078,6 +1063,29 @@ How to install the binary packages depends on your operating system:
+
+FreeBSD and ElectroBSD
+
+ To start Privoxy upon booting, add
+ "privoxy_enable='YES'" to /etc/rc.conf.
+ Privoxy will use
+ /usr/local/etc/privoxy/config as its main
+ configuration file.
+
+
+ If you installed Privoxy into a jail, the
+ paths above are relative to the jail root.
+
+
+ To start Privoxy manually, run:
+
+
+
+ # service privoxy onestart
+
+
+
+
Windows
@@ -1097,15 +1105,21 @@ Click on the &my-app; Icon to start Privoxy. If no co
-Solaris, NetBSD, FreeBSD, HP-UX and others
+Generic instructions for Unix derivates (Solaris, NetBSD, HP-UX etc.)
Example Unix startup command:
- # /usr/sbin/privoxy /etc/privoxy/config
+ # /usr/sbin/privoxy --user privoxy /etc/privoxy/config
+
+ Note that if you installed Privoxy through
+ a package manager, the package will probably contain a platform-specific
+ script or configuration file to start Privoxy
+ upon boot.
+
@@ -1121,32 +1135,21 @@ Example Unix startup command:
Mac OS X
- After downloading the privoxy software, unzip the downloaded file by
- double-clicking on the zip file icon. Then, double-click on the
- installer package icon and follow the installation process.
-
-
- The privoxy service will automatically start after a successful
- installation. In addition, the privoxy service will automatically
- start every time your computer starts up.
-
-
- To prevent the privoxy service from automatically starting when your
- computer starts up, remove or rename the folder named
- /Library/StartupItems/Privoxy.
-
-
- A simple application named Privoxy Utility has been created which
- enables administrators to easily start and stop the privoxy service.
+ The privoxy service will automatically start after a successful installation
+ (and thereafter every time your computer starts up) however you will need to
+ configure your web browser(s) to use it. To do so, configure them to use a
+ proxy for HTTP and HTTPS at the address 127.0.0.1:8118.
- In addition, the Privoxy Utility presents a simple way for
- administrators to edit the various privoxy config files. A method
- to uninstall the software is also available.
+ To prevent the privoxy service from automatically starting when your computer
+ starts up, remove or rename the file /Library/LaunchDaemons/org.ijbswa.privoxy.plist
+ (on OS X 10.5 and higher) or the folder named
+ /Library/StartupItems/Privoxy (on OS X 10.4 'Tiger').
- An administrator username and password must be supplied in order for
- the Privoxy Utility to perform any of the tasks.
+ To manually start or stop the privoxy service, use the scripts startPrivoxy.sh
+ and stopPrivoxy.sh supplied in /Applications/Privoxy. They must be run from an
+ administrator account, using sudo.
@@ -1402,7 +1405,7 @@ for details.
-
+Controlling Privoxy with Your Web BrowserPrivoxy's user interface can be reached through the special
@@ -1436,7 +1439,7 @@ for details.
▪ Documentation
+ url="https://www.privoxy.org/&p-version;/user-manual/">Documentation
@@ -1458,10 +1461,7 @@ for details.
it as a test to see whether it is Privoxy
causing the problem or not. Privoxy continues
to run as a proxy in this case, but all manipulation is disabled, i.e.
- Privoxy acts like a normal forwarding proxy. There
- is even a toggle Bookmarklet offered, so
- that you can toggle Privoxy with one click from
- your browser.
+ Privoxy acts like a normal forwarding proxy.
@@ -1870,7 +1870,7 @@ for details.
-
+Finding the Right Mix
Note that some actions, like cookie suppression
@@ -1895,7 +1895,7 @@ for details.
-
+How to Edit
The easiest way to edit the actions files is with a browser by
@@ -2216,7 +2216,7 @@ for details.
-The Path Pattern
+The Path PatternPrivoxy uses modern POSIX 1003.2
@@ -2316,18 +2316,18 @@ for details.
-The Tag Pattern
+The Request Tag Pattern
- Tag patterns are used to change the applying actions based on the
- request's tags. Tags can be created with either the
- client-header-tagger
+ Request tag patterns are used to change the applying actions based on the
+ request's tags. Tags can be created based on HTTP headers with either
+ the client-header-tagger
or the server-header-tagger action.
- Tag patterns have to start with TAG:, so &my-app;
- can tell them apart from URL patterns. Everything after the colon
+ Request tag patterns have to start with TAG:, so &my-app;
+ can tell them apart from other 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 (&my-app; doesn't silently add a ^,
@@ -2343,15 +2343,15 @@ for details.
- Sections can contain URL and tag patterns at the same time,
- but tag patterns are checked after the URL patterns and thus
+ Sections can contain URL and request tag patterns at the same time,
+ but request tag patterns are checked after the URL patterns and thus
always overrule them, even if they are located before the URL patterns.
- Once a new tag is added, Privoxy checks right away if it's matched by one
- of the tag patterns and updates the action settings accordingly. As a result
- tags can be used to activate other tagger actions, as long as these other
+ Once a new request tag is added, Privoxy checks right away if it's matched by one
+ of the request tag patterns and updates the action settings accordingly. As a result
+ request tags can be used to activate other tagger actions, as long as these other
taggers look for headers that haven't already be parsed.
@@ -2376,21 +2376,77 @@ for details.
-The Negative Tag Patterns
+The Negative Request Tag Patterns
- To match requests that do not have a certain tag, specify a negative tag pattern
+ To match requests that do not have a certain request tag, specify a negative tag pattern
by prefixing the tag pattern line with either NO-REQUEST-TAG:
or NO-RESPONSE-TAG: instead of TAG:.
- Negative tag patterns created with NO-REQUEST-TAG: are checked
+ Negative request tag patterns created with NO-REQUEST-TAG: are checked
after all client headers are scanned, the ones created with NO-RESPONSE-TAG:
are checked after all server headers are scanned. In both cases all the created
tags are considered.
+
+The Client Tag Pattern
+
+
+
+
+
+ This is an experimental feature. The syntax is likely to change in future versions.
+
+
+
+
+ Client tag patterns are not set based on HTTP headers but based on
+ the client's IP address. Users can enable them themselves, but the
+ Privoxy admin controls which tags are available and what their effect
+ is.
+
+
+
+ After a client-specific tag has been defined with the
+ client-specific-tag,
+ directive, action sections can be activated based on the tag by using a
+ CLIENT-TAG pattern. The CLIENT-TAG pattern is evaluated at the same priority
+ as URL patterns, as a result the last matching pattern wins. Tags that
+ are created based on client or server headers are evaluated later on
+ and can overrule CLIENT-TAG and URL patterns!
+
+
+ The tag is set for all requests that come from clients that requested
+ it to be set. Note that "clients" are differentiated by IP address,
+ if the IP address changes the tag has to be requested again.
+
+
+ Clients can request tags to be set by using the CGI interface http://config.privoxy.org/client-tags.
+
+
+
+ Example:
+
+
+
+
+# If the admin defined the client-specific-tag circumvent-blocks,
+# and the request comes from a client that previously requested
+# the tag to be set, overrule all previous +block actions that
+# are enabled based on URL to CLIENT-TAG patterns.
+{-block}
+CLIENT-TAG:^circumvent-blocks$
+
+# This section is not overruled because it's located after
+# the previous one.
+{+block{Nobody is supposed to request this.}}
+example.org/blocked-example-page
+
@@ -2583,7 +2639,16 @@ for details.
Example usage:
- +add-header{X-User-Tracking: sucks}
+ # Add a DNT ("Do not track") header to all requests,
+# event to those that already have one.
+#
+# This is just an example, not a recommendation.
+#
+# There is no reason to believe that user-tracking websites care
+# about the DNT header and depending on the User-Agent, adding the
+# header may make user-tracking easier.
+{+add-header{DNT: 1}}
+/
@@ -2793,7 +2858,7 @@ for details.
Type:
- Parameterized.
+ Multi-value.
@@ -2880,7 +2945,7 @@ for details.
Type:
- Parameterized.
+ Multi-value.
@@ -3631,7 +3696,7 @@ problem-host.example.com
Type:
- Parameterized.
+ Multi-value.
@@ -3843,7 +3908,7 @@ problem-host.example.com
Type:
- Parameterized.
+ Multi-value.
@@ -4160,7 +4225,7 @@ new action
Type:
- Multi-value.
+ Parameterized.
@@ -4193,6 +4258,32 @@ new action
for socks5 connections (with remote DNS resolution).
+
+
+ forward-webserver 127.0.0.1:80 to use the HTTP
+ server listening at 127.0.0.1 port 80 without adjusting the
+ request headers.
+
+
+ This makes it more convenient to use Privoxy to make
+ existing websites available as onion services as well.
+
+
+ Many websites serve content with hardcoded URLs and
+ can't be easily adjusted to change the domain based
+ on the one used by the client.
+
+
+ Putting Privoxy between Tor and the webserver (or an stunnel
+ that forwards to the webserver) allows to rewrite headers and
+ content to make client and server happy at the same time.
+
+
+ Using Privoxy for webservers that are only reachable through
+ onion addresses and whose location is supposed to be secret
+ is not recommended and should not be necessary anyway.
+
+
@@ -5405,7 +5496,7 @@ new action
# Create a short, easy to remember nickname for a favorite site
# (relies on the browser to accept and forward invalid URLs to &my-app;)
-{ +redirect{http://www.privoxy.org/user-manual/actions-file.html} }
+{ +redirect{https://www.privoxy.org/user-manual/actions-file.html} }
a
# Always use the expanded view for Undeadly.org articles
@@ -5475,7 +5566,7 @@ www.privoxy.org/user-manual/
Type:
- Parameterized.
+ Multi-value.
@@ -5558,7 +5649,7 @@ example.org/instance-that-is-delivered-as-xml-but-is-not
Type:
- Parameterized.
+ Multi-value.
@@ -5829,7 +5920,7 @@ TAG:^image/
-
+Summary
Note that many of these actions have the potential to cause a page to
@@ -5972,7 +6063,7 @@ hal stop here
and user.action file and see how all these pieces come together:
-
+match-all.action
Remember all actions are disabled when matching starts,
@@ -6015,7 +6106,7 @@ hal stop here
-
+default.action
@@ -6304,7 +6395,7 @@ wiki.
-user.action
+user.action
So far we are painting with a broad brush by setting general policies,
@@ -6682,8 +6773,10 @@ stupid-server.example.com/
The non-standard option letter D (dynamic) allows
to use the variables $host, $origin (the IP address the request came from),
- $path and $url. They will be replaced with the value they refer to before
- the filter is executed.
+ $path, $url and $listen-address (the address on which Privoxy accepted the
+ client request. Example: 127.0.0.1:8118).
+ They will be replaced with the value they refer to before the filter
+ is executed.
@@ -6718,7 +6811,7 @@ stupid-server.example.com/
-Filter File Tutorial
+Filter File Tutorial
Now, let's complete our foo content filter. We have already defined
the heading, but the jobs are still missing. Since all it does is to replace
@@ -7440,9 +7533,10 @@ pre-defined filters for your convenience:
External filters read the content from STDIN and write the rewritten
- content to STDOUT. The environment variables PRIVOXY_URL, PRIVOXY_PATH,
- PRIVOXY_HOST, PRIVOXY_ORIGIN can be used to get some details about the
- client request.
+ content to STDOUT.
+ The environment variables PRIVOXY_URL, PRIVOXY_PATH, PRIVOXY_HOST,
+ PRIVOXY_ORIGIN, PRIVOXY_LISTEN_ADDRESS can be used to get some details
+ about the client request.
&my-app; will temporary store the content to filter in the
@@ -7888,7 +7982,7 @@ Requests
-
+Privoxy's Internal Pages
@@ -8005,84 +8099,6 @@ Requests
-
- These may be bookmarked for quick reference. See next.
-
-
-
-
-Bookmarklets
-
- Below are some bookmarklets to allow you to easily access a
- mini version of some of Privoxy's
- special pages. 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 should work for testing).
-
-
- To save them, right-click the link and choose Add to Favorites
- (IE) or Add Bookmark (Netscape). You will get a warning that
- the bookmark may not be safe - just click OK. Then you can run the
- Bookmarklet directly from your favorites/bookmarks. For even faster access,
- you can put them on the Links bar (IE) or the Personal
- Toolbar (Netscape), and run them with a single click.
-
-
-
-
-
-
-
- Privoxy - Enable
-
-
-
-
-
- Privoxy - Disable
-
-
-
-
-
- Privoxy - Toggle Privoxy (Toggles between enabled and disabled)
-
-
-
-
-
- Privoxy- View Status
-
-
-
-
-
- Privoxy - Why?
-
-
-
-
-
-
- Credit: The site which gave us the general idea for these bookmarklets is
- www.bookmarklets.com. They
- have more information about bookmarklets.
-
-
-
-
-
@@ -8234,8 +8250,7 @@ Requests
One quick test to see if Privoxy is causing a problem
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
+ step (be sure to flush caches afterward!). Looking at the
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.)