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 Browser Privoxy'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 Pattern Privoxy 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.)