X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fuser-manual.sgml;h=672c9a28cc3b625289db5e8c3d05045e5f7ade21;hp=d599631e3ddf95a513f8b9c7926b7f3fe12be4b2;hb=7ee754dbd6237cdb224bc9cf5876c9dd6aa0be87;hpb=764090bd9b33279e6ffb040521b67620cdc33a70 diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml index d599631e..672c9a28 100644 --- a/doc/source/user-manual.sgml +++ b/doc/source/user-manual.sgml @@ -15,6 +15,7 @@ + ]> Introduction - This documentation is included with the current &p-status; version of Privoxy, v.&p-version;soon ;-)]]>. - + Since this is a &p-status; version, not all new features are well tested. This documentation may be slightly out of sync as a result (especially with @@ -130,7 +130,6 @@ features of ad and banner blocking and cookie management, Privoxy provides new features: - @@ -145,12 +144,14 @@ Installation + 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 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 @@ -166,36 +167,56 @@ Binary Packages + + + Note: If you have a previous Junkbuster or + Privoxy installation on your system, you + will need to remove it. Some platforms do this for you as part + of their installation procedure. (See below for your platform). + + - Binary packages can be downloaded from our Privoxy Project Page. + In any case be sure to backup your old configuration + if it is valuable to you. See the + note to upgraders. - How to install them depends on your operating system: + How to install the binary packages depends on your operating system: -Redhat and SuSE RPMs +Red Hat and SuSE RPMs + + + RPMs can be installed with rpm -Uvh privoxy-&p-version;-1.rpm, + and will use /etc/privoxy for the location + of configuration files. + - RPMs can be installed with rpm -Uvh <name-of-rpm.rpm>, - and will use /etc/privoxy for configuration files. + Note that on Red Hat, Privoxy will not be automatically started on system + boot. You will need to enable that using linuxconf. - Note that if you have a Junkbuster RPM installed + If you have problems with failed dependencies, try rebuilding the SRC RPM: + rpm --rebuild privoxy-&p-version;-1.src.rpm;. This + will use your locally installed libraries and RPM version. + + + + Also note that if you have a Junkbuster RPM installed on your system, you need to remove it first, because the packages conflict. + Otherwise, RPM will try to remove Junkbuster + automatically, before installing Privoxy. -Solaris, NetBSD, HP-UX - +Debian - Create a new directory, cd to it, then unzip and - untar the archive. For the most part, you'll have to figure out where - things go. FIXME. + FIXME. @@ -208,12 +229,29 @@ + +Solaris, NetBSD, FreeBSD, HP-UX + + + Create a new directory, cd to it, then unzip and + untar the archive. For the most part, you'll have to figure out where + things go. FIXME. + + + OS/2 - Just double-click the WarpIN self-installing archive, which will guide - you through the installation process. A shadow of the + First, make sure that no previous installations of + Junkbuster and / or + Privoxy are left on your + system. You can do this by + + + + Then, just double-click the WarpIN self-installing archive, which will + guide you through the installation process. A shadow of the Privoxy executable will be placed in your startup folder so it will start automatically whenever OS/2 starts. @@ -225,16 +263,36 @@ -Debian - - FIXME. +Max OSX + + Unzip the downloaded package (you can either double-click on the file + in the finder, or on the desktop if you downloaded it there). Then, + double-click on the package installer icon and follow the installation + process. + Privoxy will be installed in the subdirectory + /Applications/Privoxy.app. + Privoxy will set itself up to start + automatically on system bringup via + /System/Library/StartupItems/Privoxy. AmigaOS - Unpack the .lha archive, then FIXME. + Copy and then unpack the lha archive to a suitable location. + All necessary files will be installed into Privoxy + directory, including all configuration and log files. To uninstall, just + remove this directory. + + + Start Privoxy (with RUN <>NIL:) in your + startnet script (AmiTCP), in + s:user-startup (RoadShow), as startup program in your + startup script (Genesis), or as startup action (Miami and MiamiDx). + Privoxy will automatically quit when you quit your + TCP/IP stack (just ignore the harmless warning your TCP/IP stack may display that + Privoxy is still running). @@ -245,13 +303,6 @@ &buildsource; - - - For more detailed instructions, on how to build Redhat and SuSE RPMs, - Windows self-extracting installers etc, and for building from CVS sources, - please consult the developer - manual. - @@ -280,8 +331,8 @@ A filter file (typically default.filter) - is new with Privoxy 2.9.x, and provides some - of the new sophistication (explained below). config is + is new as of Privoxy 2.9.x, and provides some + of the new sophistication (explained below). config is much the same as before. @@ -289,9 +340,8 @@ files, and possibly adapt any personal rules from your older files. When porting personal rules over from the old blockfile to the new actions file, please note that even the pattern syntax has - changed. - If upgrading from 2.9.x development versions, it is still recommended - to use the new configuration files. + changed. If upgrading from 2.9.x development versions, it is still + recommended to use the new configuration files. A quick list of things to be aware of before upgrading: @@ -352,8 +402,8 @@ Before launching Privoxy for the first time, you will want to configure your browser(s) to use Privoxy as a HTTP and HTTPS proxy. The default is localhost for the proxy address, - and port 8118 (earlier versions used port 8000). This is the one required - configuration that must be done! + and port 8118 (earlier versions used port 8000). This is the one + configuration step that must be done! @@ -370,7 +420,7 @@ After doing this, flush your browser's disk and memory caches to force a re-reading of all pages and to get rid of any ads that may be cached. You are now ready to start enjoying the benefits of using - Privoxy. + Privoxy! @@ -389,7 +439,11 @@ - An init script is provided for SuSE and Redhat. + See below for other command line options. + + + + An init script is provided for SuSE and Red Hat. @@ -397,7 +451,7 @@ - For RedHat: /etc/rc.d/init.d/privoxy start + For Red Hat and Debian: /etc/rc.d/init.d/privoxy start @@ -500,7 +554,7 @@ - + Command Line Options Privoxy may be invoked with the following @@ -515,7 +569,7 @@ --version - Print version info and exit, Unix only. + Print version info and exit. Unix only. @@ -523,7 +577,7 @@ --help - Print a short usage info and exit, Unix only. + Print short usage info and exit. Unix only. @@ -532,7 +586,7 @@ Don't become a daemon, i.e. don't fork and become process group - leader, don't detach from controlling tty. Unix only. + leader, and don't detach from controlling tty. Unix only. @@ -567,7 +621,8 @@ Privoxy will look for a file named config in the current directory (except on Win32 where it will look for config.txt instead). Specify - full path to avoid confusion. + full path to avoid confusion. If no config file is found, + Privoxy will fail to start. @@ -636,9 +691,9 @@ Please choose from the following options: 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 filtering is disabled. There - is even a toggle Bookmarklet offered, so that you can toggle - Privoxy with one click from your browser. - + is even a toggle Bookmarklet offered, so + that you can toggle Privoxy with one click from + your browser. @@ -682,7 +737,7 @@ Please choose from the following options: default.action (the actions file) is used to define which of a set of various actions relating to images, banners, - pop-ups, access restrictions, banners and cookies are to be applied where. + pop-ups, access restrictions, banners and cookies are to be applied, and where. There is a web based editor for this file that can be accessed at http://config.privoxy.org/edit-actions/ (Shortcut: http://p.p/edit-actions/). @@ -715,7 +770,8 @@ Please choose from the following options: default.action and default.filter - can use Perl style regular expressions for maximum flexibility. + can use Perl style regular expressions for + maximum flexibility. @@ -775,7 +831,7 @@ Please choose from the following options: The main config file controls all aspects of Privoxy's - operation that are not location dependent (i.e. they apply to all URLs, no matter + operation that are not location dependent (i.e. they apply universally, no matter where you may be surfing). @@ -1022,7 +1078,7 @@ Please choose from the following options: Your logfile will grow indefinitely, and you will probably want to periodically remove it. On Unix systems, you can do this with a cron job - (see man cron). For Redhat, a logrotate + (see man cron). For Red Hat, a logrotate script has been included. @@ -2088,7 +2144,7 @@ Please choose from the following options: Now, your users can set their browser's proxy to use either host-a or host-b and be able to browse the internal content - on both isp-a or isp-b. + of both isp-a and isp-b. @@ -2134,9 +2190,6 @@ Please choose from the following options: Windows GUI Options - Privoxy has a number of options specific to the Windows GUI interface: @@ -2330,13 +2383,20 @@ Removed references to Win32. HB 09/23/01 See below for a complete list of available actions. + + An actions file typically has sections. At the top, aliases are + defined (discussed below), then the default set of rules which will apply + universally to all sites and pages. And then below that is generally a lengthy + set of exceptions to the defined universal policies. + + Finding the Right Mix Note that some actions like cookie suppression or script disabling may render some sites unusable, which rely on these techniques to work properly. - Finding the right mix of actions is not easy and a matter of personal + Finding the right mix of actions is not easy and certainly a matter of personal taste. In general, it can be said that the more aggressive your default settings (in the top section of the actions file) are, the more exceptions for trusted sites you will have to @@ -2404,26 +2464,27 @@ Removed references to Win32. HB 09/23/01 Patterns - Generally, a pattern has the form <domain>/<path>, where both the - <domain> and <path> part are optional. If you only specify a - domain part, the / can be left out: + Generally, a pattern has the form <domain>/<path>, + where both the <domain> and <path> + are optional. (This is why the pattern / matches all URLs). - www.example.com + www.example.com/ - is a domain only pattern and will match any request to www.example.com, + is a domain-only pattern and will match any request to www.example.com, regardless of which document on that server is requested. - www.example.com/ + www.example.com - means exactly the same. + means exactly the same. For domain-only patterns, the trailing / may + be omitted. @@ -2562,7 +2623,7 @@ Removed references to Win32. HB 09/23/01 - Note that the pattern is automatically left-anchored at the /, + Note that the path pattern is automatically left-anchored at the /, i.e. it matches as if it would start with a ^. @@ -2582,16 +2643,16 @@ Removed references to Win32. HB 09/23/01 - - + Actions Actions are enabled if preceded with a +, and disabled if preceded with a -. Actions are invoked by enclosing the action name in curly braces (e.g. {+some_action}), followed by a list of - URLs to which the action applies. There are three classes of actions: + URLs (or patterns that match URLs) to which the action applies. There are + three classes of actions: @@ -2599,8 +2660,9 @@ Removed references to Win32. HB 09/23/01 - Boolean (e.g. +/-block): - + Boolean, i.e the action can only be on or + off. Examples: + @@ -2616,14 +2678,16 @@ Removed references to Win32. HB 09/23/01 - parameterized (e.g. +/-hide-user-agent): + Parameterized, e.g. +/-hide-user-agent{ Mozilla 1.0 }, + where some value is required in order to enable this type of action. + Examples: {+name{param}} # enable action and set parameter to param - {-name} # disable action + {-name} # disable action (parameter) can be omitted @@ -2632,15 +2696,18 @@ Removed references to Win32. HB 09/23/01 - Multi-value (e.g. {+/-add-header{Name: value}}, {+/-wafer{name=value}}): + + Multi-value, e.g. {+/-add-header{Name: value}} ot + {+/-wafer{name=value}}), where some value needs to be defined + in addition to simply enabling the actino. Examples: - {+name{param}} # enable action and add parameter param - {-name{param}} # remove the parameter param - {-name} # disable this action totally + {+name{param=value}} # enable action and set param to value + {-name{param=value}} # remove the parameter param completely + {-name} # disable this action totally and remove param too @@ -2666,549 +2733,1296 @@ Removed references to Win32. HB 09/23/01 specified. + The list of valid Privoxy actions are: - - - - - - Add the specified HTTP header, which is not checked for validity. - You may specify this many times to specify many different headers: - - - - - - +add-header{Name: value} - - - - - - - - - - Block this URL totally. In a default installation, a blocked - URL will result in bright red banner that says BLOCKED, - with a reason why it is being blocked, and an option to see it anyway. - The page displayed for this is the blocked template - file. - - - - - - +block - - - - - - - - - - De-animate all animated GIF images, i.e. reduce them to their last frame. - This will also shrink the images considerably (in bytes, not pixels!). If - the option first is given, the first frame of the animation - is used as the replacement. If last is given, the last frame - of the animation is used instead, which probably makes more sense for most - banner animations, but also has the risk of not showing the entire last - frame (if it is only a delta to an earlier frame). - - - - - - +deanimate-gifs{last} - +deanimate-gifs{first} - - - - - + + + + + + + + + + + +<emphasis>+add-header{Name: value}</emphasis> + + + + Type: + + + Multi-value. + + - - - +downgrade will downgrade HTTP/1.1 client requests to - HTTP/1.0 and downgrade the responses as well. Use this action for servers - that use HTTP/1.1 protocol features that - Privoxy doesn't handle well yet. HTTP/1.1 - is only partially implemented. Default is not to downgrade requests. - - - - - - +downgrade - - - - - + + Typical uses: + + + Send a user defined HTTP header to the web server. + + + + + + Possible values: + + + Any value is possible. Validity of the defined HTTP headers is not checked. + + + - - - Many sites, like yahoo.com, don't just link to other sites. Instead, they - will link to some script on their own server, giving the destination as a - parameter, which will then redirect you to the final target. URLs resulting - from this scheme typically look like: - http://some.place/some_script?http://some.where-else. - - - Sometimes, there are even multiple consecutive redirects encoded in the - URL. These redirections via scripts make your web browsing more traceable, - since the server from which you follow such a link can see where you go to. - Apart from that, valuable bandwidth and time is wasted, while your browser - ask the server for one redirect after the other. Plus, it feeds the - advertisers. - - - The +fast-redirects option enables interception of these - types of requests by Privoxy, who will cut off - all but the last valid URL in the request and send a local redirect back to - your browser without contacting the intermediate site(s). - - - - - - +fast-redirects - - - - - + + Example usage: + + + {+add-header{X-User-Tracking: sucks}} + .example.com + + + - - - Apply the filters in the section_header - section of the default.filter file to the site(s). - default.filter sections are grouped according to like - functionality. Filters can be used to - re-write any of the raw page content. This is a potentially a - very powerful feature! - - - - - - - +filter{section_header} - - - - + + Notes: + + + This action may be specified multiple times, in order to define multiple + headers. This is rarely needed for the typical user. If you don't know what + HTTP headers are, you definitely don't need to worry about this + one. + + + + + - - Filter sections that are pre-defined in the supplied - default.filter include: - -
- - - html-annoyances: Get rid of particularly annoying HTML abuse. - - - - - js-annoyances: Get rid of particularly annoying JavaScript abuse - - - - - no-popups: Kill all popups in JS and HTML - - - - - frameset-borders: Give frames a border - - - - - webbugs: Squish WebBugs (1x1 invisible GIFs used for user tracking) - - - - - no-refresh: Automatic refresh sucks on auto-dialup lines - - - - - fun: Text replacements for subversive browsing fun! - - - - - nimda: Remove (virus) Nimda code. - - - - - banners-by-size: Kill banners by size - - - - - crude-parental: Kill all web pages that contain the words "sex" or "warez" - - -
+ + +<emphasis>+block</emphasis> - - Note: Filtering requires buffering the page content, which may appear to slow down - page rendering since nothing is displayed until all content has passed - the filters. (It does not really take longer, but seems that way since - the page is not incrementally displayed.) This effect will be more noticeable - on slower connections. - + + + Type: + + + Boolean. + + - + + Typical uses: + + + Used to block a URL from reaching your browser. The URL may be + anything, but is typically used to block ads or other obnoxious + content. + + + - - - Block any existing X-Forwarded-for header, and do not add a new one: - - - - - - +hide-forwarded - - - - - + + Possible values: + + N/A + + + + + Example usage: + + + {+block} + .example.com + .ads.r.us + + + - - - If the browser sends a From: header containing your e-mail - address, this either completely removes the header (block), or - changes it to the specified e-mail address. - - - - - - +hide-from{block} - +hide-from{spam@sittingduck.xqq} - - - + + Notes: + + + Privoxy will display its + special BLOCKED page if a URL matches one of the + blocked patterns. If there is sufficient space, a large red + banner will appear with a friendly message about why the page + was blocked, and a way to go there anyway. If there is insufficient + space a smaller blocked page will appear without the red banner. + One exception is if the URL matches both +block + and +image, then it can be handled by + +image-blocker (see below). + + + + + + + + + + +<emphasis>+deanimate-gifs</emphasis> + + + + Type: + + + Parameterized. + + + + + Typical uses: + + + To stop those annoying, distracting animated GIF images. + + + + + + Possible values: + + + last or first + + + + + + Example usage: + + + {+deanimate-gifs{last}} + .example.com + + + + + + Notes: + + + De-animate all animated GIF images, i.e. reduce them to their last frame. + This will also shrink the images considerably (in bytes, not pixels!). If + the option first is given, the first frame of the animation + is used as the replacement. If last is given, the last + frame of the animation is used instead, which probably makes more sense for + most banner animations, but also has the risk of not showing the entire + last frame (if it is only a delta to an earlier frame). + + + + + + + + + +<emphasis>+downgrade</emphasis> + + + + Type: + + + Boolean. + + + + + Typical uses: + + + +downgrade will downgrade HTTP/1.1 client requests to + HTTP/1.0 and downgrade the responses as well. + + + + + + Possible values: + + + N/A + + + + + + Example usage: + + + {+downgrade} + .example.com + + + + + + Notes: + + + Use this action for servers that use HTTP/1.1 protocol features that + Privoxy doesn't handle well yet. HTTP/1.1 is + only partially implemented. Default is not to downgrade requests. This is + an infrequently needed action, and is used to help with problem sites only. + + + + + + + + + +<emphasis>+fast-redirects</emphasis> + + + + Type: + + + Boolean. + + + + + Typical uses: + + + The +fast-redirects action enables interception of + redirect requests from one server to another, which + are used to track users.Privoxy can cut off + all but the last valid URL in redirect request and send a local redirect + back to your browser without contacting the intermediate site(s). + + + + + + Possible values: + + + N/A + + + + + + Example usage: + + + {+fast-redirects} + .example.com + + + + + + Notes: + + + Many sites, like yahoo.com, don't just link to other sites. Instead, they + will link to some script on their own server, giving the destination as a + parameter, which will then redirect you to the final target. URLs + resulting from this scheme typically look like: + http://some.place/some_script?http://some.where-else. - + + Sometimes, there are even multiple consecutive redirects encoded in the + URL. These redirections via scripts make your web browsing more traceable, + since the server from which you follow such a link can see where you go + to. Apart from that, valuable bandwidth and time is wasted, while your + browser ask the server for one redirect after the other. Plus, it feeds + the advertisers. + + + This is a normally on feature, and often requires exceptions for sites that + are sensitive to defeating this mechanism. + + + + + + + + + + +<emphasis>+filter</emphasis> + + + + Type: + + + Parameterized. + + + + + Typical uses: + + + Apply page filtering as defined by named sections of the + default.filter file to the specified site(s). + Filtering can be any modification of the raw + page content, including re-writing or deletion. + + + + + + Possible values: + + + +filter must include the name of one of the section identifiers + from default.filter (or whatever + filterfile is specified in config). + + + - + + Example usage (from the current default.filter): + + + + +filter{html-annoyances}: Get rid of particularly annoying HTML abuse. + + + + + +filter{js-annoyances}: Get rid of particularly annoying JavaScript abuse + + + + + +filter{content-cookies}: Kill cookies that come in the HTML or JS content + + + + + +filter{popups}: Kill all popups in JS and HTML + + + + + +filter{frameset-borders}: Give frames a border and make them resizable + + + + + +filter{webbugs}: Squish WebBugs (1x1 invisible GIFs used for user tracking) + + + + + +filter{refresh-tags}: Kill automatic refresh tags (for dial-on-demand setups) + + + + + +filter{fun}: Text replacements for subversive browsing fun! + + + + + +filter{nimda}: Remove Nimda (virus) code. + + + + + +filter{banners-by-size}: Kill banners by size (very efficient!) + + + + + +filter{shockwave-flash}: Kill embedded Shockwave Flash objects + + + + + +filter{crude-parental}: Kill all web pages that contain the words "sex" or "warez" + + + + + + + Notes: + + + This is potentially a very powerful feature! And requires a knowledge + of regular expressions if you want to roll your own. + + + Filtering requires buffering the page content, which may appear to + slow down page rendering since nothing is displayed until all content has + passed the filters. (It does not really take longer, but seems that way + since the page is not incrementally displayed.) This effect will be more + noticeable on slower connections. + + + + + + + + + + +<emphasis>+hide-forwarded</emphasis> + + + + Type: + + + Boolean. + + + + + Typical uses: + + + Block any existing X-Forwarded-for HTTP header, and do not add a new one. + + + + + + Possible values: + + + N/A + + + + + + Example usage: + + + {+hide-forwarded} + .example.com + + + + + + Notes: + + + It is fairly safe to leave this on. It does not seem to break many sites. + + + + + + + + + + +<emphasis>+hide-from</emphasis> + + + + Type: + + + Parameterized. + + + + + Typical uses: + + + To block the browser from sending your email address in a From: + header. + + + + + + Possible values: + + + Keyword: block, or any user defined value. + + + + + + Example usage: + + + {+hide-from{block}} + .example.com + + + + + + Notes: + + + The keyword block will completely remove the header. + Alternately, you can specify any value you prefer to send to the web + server. + + + + + + + + + + +<emphasis>+hide-referer</emphasis> + + + + + Type: + + + Parameterized. + + + + + Typical uses: + + + Don't send the Referer: (sic) HTTP header to the web site. + Or, alternately send a forged header instead. + + + + + + Possible values: + + + Prevent the header from being sent with the keyword, block. + Or, forge a URL to one from the same server as the request. + Or, set to user defined value of your choice. + + + + + + Example usage: + + + {+hide-referer{forge}} + .example.com + + + + + + Notes: + + + forge is the preferred option here, since some servers will + not send images back otherwise. + - Don't send the Referer: (sic) header to the web site. You - can block it, forge a URL to the same server as the request (which is - preferred because some sites will not send images otherwise) or set it to a - constant, user defined string of your choice. - - - - - - +hide-referer{block} - +hide-referer{forge} - +hide-referer{http://nowhere.com} - - - + +hide-referrer is an alternate spelling of + +hide-referer. It has the exact same parameters, and can be freely + mixed with, +hide-referer. (referrer is the + correct English spelling, however the HTTP specification has a bug - it + requires it to be spelled as referer.) - + + + + + + + + + +<emphasis>+hide-user-agent</emphasis> + + + + Type: + + + Parameterized. + + + + + Typical uses: + + + To change the User-Agent: header so web servers can't tell + your browser type. Who's business is it anyway? + + + + + + Possible values: + + + Any user defined string. + + + + + + Example usage: + + + {+hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)}} + .msn.com + + + + + + Notes: + + + Warning! This breaks many web sites that depend on this in order + to determine how the target browser will respond to various + requests. Use with caution. + + + + + + + + + +<emphasis>+image</emphasis> + + + + Type: + + + Boolean. + + + + + Typical uses: + + + To define what Privoxy should treat + automatically as an image. + + + + + + Possible values: + + + N/A + + + + + + Example usage: + + + {+image} + /.*\.(gif|jpg|jpeg|png|bmp|ico) + + + + + + Notes: + + + This only has meaning if the URL (or pattern) also is + +blocked, in which case a blocked image can + be sent rather than a HTML page. (See +image-blocker{} below + for the control over what is actually sent.) + + + There is little reason to change the default definition for this. + + + + + + + + + + +<emphasis>+image-blocker</emphasis> + + + + Type: + + + Parameterized. + + + + + Typical uses: + + + Decide what to do with URLs that end up tagged with both {+block} + and {+image}, e.g an advertisement. + + + + + + Possible values: + + + There are four available options: -image-blocker will send a HTML + blocked page, usually resulting in a broken + image icon. +image-blocker{blank} will send a 1x1 + transparent GIF image. +image-blocker{pattern} will send a + checkerboard type pattern (the default). And finally, + +image-blocker{http://xyz.com} will send a HTTP temporary + redirect to the specified image. This has the advantage of the icon being + being cached by the browser, which will speed up the display. + + + + + + Example usage: + + + {+image-blocker{blank}} + .example.com + + + + + + Notes: + + + If you want invisible ads, they need to be both + defined as images and blocked. + And then, image-blocker should be set to + blank for invisibility. Note you cannot treat HTML pages as + images in most cases. For instance, frames require an HTML page to display. + So a frame that is an ad, cannot be treated as an image. Forcing an + image in this situation just will not work. + + + + + + + + + +<emphasis>+limit-connect</emphasis> + + + + Type: + + + Parameterized. + + + + + Typical uses: + + + By default, Privoxy only allows HTTP CONNECT + requests to port 443 (the standard, secure HTTPS port). Use + +limit-connect to disable this altogether, or to allow + more ports. + + + + + + Possible values: + + + Any valid port number, or port number range. + + + - - - Alternative spelling of +hide-referer. It has the same - parameters, and can be freely mixed with, +hide-referer. - (referrer is the correct English spelling, however the HTTP - specification has a bug - it requires it to be spelled referer.) - - - - - - +hide-referrer{...} - - - - - + + Example usages: + + + + + +limit-connect{443} # This is the default and need not be specified. + +limit-connect{80,443} # Ports 80 and 443 are OK. + +limit-connect{-3, 7, 20-100, 500-} # Port less than 3, 7, 20 to 100 and above 500 are OK. + + + - - - Change the User-Agent: header so web servers can't tell your - browser type. Warning! This breaks many web sites. Specify the - user-agent value you want. Example, pretend to be using Netscape on - Linux: - - - - - - +hide-user-agent{Mozilla (X11; I; Linux 2.0.32 i586)} - - - - - - + + + + + + + + +<emphasis>+no-compression</emphasis> + + + + Type: + + + Boolean. + + + + + Typical uses: + + + Prevent the specified websites from compressing HTTP data. + + + + + + Possible values: + + + N/A + + + + + + Example usage: + + + {+no-compression} + .example.com + + + + + + Notes: + + + Some websites do this, which can be a problem for + Privoxy, since +filter, + +no-popup and +gif-deanimate will not work + on compressed data. This will slow down connections to those websites, + though. Default typically is to turn no-compression on. + + + + + + + + + +<emphasis>+no-cookies-keep</emphasis> + + + + Type: + + + Boolean. + + + + + Typical uses: + + + Allow cookies for the current browser session only. + + + + + + Possible values: + + + N/A + + + + + + Example usage: + + + {+no-cookies-keep} + .example.com + + + + + + Notes: + + + If websites set cookies, no-cookies-keep will make sure + they are erased when you exit and restart your web browser. This makes + profiling cookies useless, but won't break sites which require cookies so + that you can log in for transactions. This is generally turned on for all + sites. Sometimes referred to as session cookies. + + + + + + + + + + +<emphasis>+no-cookies-read</emphasis> + + + + Type: + + + Boolean. + + + + + Typical uses: + + + Explicitly prevent the web server from reading any cookies on your + system. + + + + + + Possible values: + + + N/A + + + + + + Example usage: + + + {+no-cookies-read} + .example.com + + + + + + Notes: + + + Often used in conjunction with +no-cookies-set to + disable persistant cookies completely. + + + + + + + + + + +<emphasis>+no-cookies-set</emphasis> + + + + Type: + + + Boolean. + + + + + Typical uses: + + + Explicitly block the web server from sending cookies to your + system. + + + + + + Possible values: + + + N/A + + + + + + Example usage: + + + {+no-cookies-set} + .example.com + + + + + + Notes: + + + Often used in conjunction with +no-cookies-read to + disable persistant cookies completely. + + + + + + + + + + +<emphasis>+no-popup</emphasis> + + + + + Type: + + + Boolean. + + + + + Typical uses: + + + Stop those annoying JavaScript pop-up windows! + + + - - - Treat this URL as an image. This only matters if it's also +blocked, - in which case a blocked image can be sent rather than a HTML page. - See +image-blocker{} below for the control over what is actually sent. - If you want invisible ads, they should be defined as - images and blocked. And also, - image-blocker should be set to blank. Note you - cannot treat HTML pages as images in most cases. For instance, frames - require an HTML page to display. So a frame that is an ad, cannot be - treated as an image. Forcing an image in this - situation just will not work. - - - - - - +image - - - - - - - - Decides what to do with URLs that end up tagged with {+block - +image}, e.g an advertisement. There are four options. - -image-blocker will send a HTML blocked page, - usually resulting in a broken image icon. - - - -+image-blocker{blank} will send a 1x1 transparent GIF -image. And finally, +image-blocker{http://xyz.com} will send a -HTTP temporary redirect to the specified image. This has the advantage of the -icon being being cached by the browser, which will speed up the display. -+image-blocker{pattern} will send a checkerboard type pattern: - - - - - - - - - - +image-blocker{blank} - +image-blocker{pattern} - +image-blocker{http://p.p/send-banner} - - - - - - - - - By default (i.e. in the absence of a +limit-connect - action), Privoxy will only allow CONNECT - requests to port 443, which is the standard port for https as a - precaution. - + + Possible values: + + + N/A + + + - - 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 proxy. - This can be a big security hole, since CONNECT-enabled proxies can - be abused as TCP relays very easily. - - - - If you want to allow CONNECT for more ports than this, or want to forbid - CONNECT altogether, you can specify a comma separated list of ports and - port ranges (the latter using dashes, with the minimum defaulting to 0 and - max to 65K): - + + Example usage: + + + {+no-popup} + .example.com + + + - - - - - +limit-connect{443} # This is the default and need no be specified. - +limit-connect{80,443} # Ports 80 and 443 are OK. - +limit-connect{-3, 7, 20-100, 500-} # Port less than 3, 7, 20 to 100 - #and above 500 are OK. - - - - + + Notes: + + + +no-popup uses a built in filter to disable pop-ups + that use the window.open() function, etc. + + + An alternate spelling is +no-popups, which is + interchangeable. + + + - - - - - +no-compression prevents the website from compressing the - data. Some websites do this, which can be a problem for - Privoxy, since +filter, - +no-popup and +gif-deanimate will not work on - compressed data. This will slow down connections to those websites, - though. Default is no-compression is turned on. - + + - - - - - +nocompression - - - - - - - - - If the website sets cookies, no-cookies-keep will make sure - they are erased when you exit and restart your web browser. This makes - profiling cookies useless, but won't break sites which require cookies so - that you can log in for transactions. Default: on. - - - - - - +no-cookies-keep - - - - - - - - - Prevent the website from reading cookies: - - - - - - +no-cookies-read - - - - - - - - - Prevent the website from setting cookies: - - - - - - +no-cookies-set - - - - - - - - - Filter the website through a built-in filter to disable those obnoxious - JavaScript pop-up windows via window.open(), etc. The two alternative - spellings are equivalent. - - - - - - +no-popup - +no-popups - - - - - + + + +<emphasis>+vanilla-wafer</emphasis> + + + + Type: + + + Boolean. + + + + + Typical uses: + + + Sends a cookie for every site stating that you do not accept any copyright + on cookies sent to you, and asking them not to track you. + + + + + + Possible values: + + + N/A + + + - - - This action only applies if you are using a jarfile - for saving cookies. It sends a cookie to every site stating that you do not - accept any copyright on cookies sent to you, and asking them not to track - you. Of course, this is a (relatively) unique header they could use to - track you. - - - - - - +vanilla-wafer - - - - - + + Example usage: + + + {+vanilla-wafer} + .example.com + + + + + + Notes: + + + This action only applies if you are using a jarfile + for saving cookies. Of course, this is a (relatively) unique header and + could be used to track you. + + + + + + + + + + +<emphasis>+wafer</emphasis> + + + + Type: + + + Multi-value. + + + + + Typical uses: + + + This allows you to send an arbitrary, user definable cookie. + + + + + + Possible values: + + + User specified cookie name and corresponding value. + + + - - - This allows you to add an arbitrary cookie. It can be specified multiple - times in order to add as many cookies as you like. - - - - - - +wafer{name=value} - - - - - + + Example usage: + + + {+wafer{name=value}} + .example.com + + + + + + Notes: + + + This can be specified multiple times in order to add as many cookies as you + like. + + + + + + - - + + +Actions Examples - The meaning of any of the above is reversed by preceding the action with a - -, in place of the +. + Note that the meaning of any of the above examples is reversed by preceding + the action with a -, in place of the +. Also, + that some actions are turned on in the default section of the actions file, + and require little to no additional configuration. These are just on. + Some actions that are turned on the default section do typically require + exceptions to be listed in the lower sections of actions file. @@ -3226,10 +4040,12 @@ icon being being cached by the browser, which will speed up the display. # Turn off all persistent cookies { +no-cookies-read } { +no-cookies-set } + # Allow cookies for this browser session ONLY { +no-cookies-keep } # Exceptions to the above, sites that benefit from persistent cookies + # that saved from one browser session to the next. { -no-cookies-read } { -no-cookies-set } { -no-cookies-keep } @@ -3293,9 +4109,9 @@ icon being being cached by the browser, which will speed up the display. Now some URLs that we want blocked (normally generates - the blocked banner). Many of these use regular expressions - that will expand to match multiple URLs: - + the blocked banner). Many of these use + regular expressions that will expand to match + multiple URLs: @@ -3359,6 +4175,7 @@ icon being being cached by the browser, which will speed up the display. for all sites. See the Appendix for a brief example on troubleshooting actions. + @@ -3424,14 +4241,14 @@ icon being being cached by the browser, which will speed up the display. .windowsupdate.microsoft.com .nytimes.com - # Shopping sites - still want to block ads. + # Shopping sites - but we still want to block ads. {shop} .quietpc.com .worldpay.com # for quietpc.com .jungle.com .scan.co.uk - # These shops require pop-ups + # These shops require pop-ups also {shop -no-popups} .dabs.com .overclockers.co.uk @@ -3743,14 +4560,18 @@ Requests \ - The escape character denotes that the following character should be taken literally. This is used where one of the special characters (e.g. .) needs to be taken literally and - not as a special meta-character. + not as a special meta-character. Example: example\.com, makes + sure the period is recognized only as a period (and not expanded to its + metacharacter meaning of any single character). [] - Characters enclosed in brackets will be matched if - any of the enclosed characters are encountered. + any of the enclosed characters are encountered. For instance, [0-9] + matches any numeric digit (zero through nine). As an example, we can combine + this with + to match any digit one of more times: [0-9]+. @@ -3765,7 +4586,10 @@ Requests | - The bar character works like an or conditional statement. A match is successful if the - sub-expression on either side of | matches. + sub-expression on either side of | matches. As an example: + /(this|that) example/ uses grouping and the bar character + and would match either this example or that + example, and nothing else. @@ -3773,7 +4597,7 @@ Requests s/string1/string2/g - This is used to rewrite strings of text. string1 is replaced by string2 in this - example. + example. There must of course be a match on string1 first. @@ -4022,7 +4846,7 @@ Requests - These may be bookmarked for quick reference. + These may be bookmarked for quick reference. See next. @@ -4108,11 +4932,22 @@ Requests is causing us a problem inadvertently. It can be a little daunting to look at the actions and filters files themselves, since they tend to be filled with regular expressions whose consequences are not always - so obvious. Privoxy provides the + so obvious. + + + + 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 afterwards!). + + + + Privoxy also provides the http://config.privoxy.org/show-url-info page that can show us very specifically how actions are being applied to any given URL. This is a big help for troubleshooting. - + First, enter one URL (or partial URL) at the prompt, and then @@ -4395,6 +5230,37 @@ Requests Temple Place - Suite 330, Boston, MA 02111-1307, USA. $Log: user-manual.sgml,v $ + Revision 1.88 2002/04/23 05:37:54 hal9 + Add AmigaOS install stuff. + + Revision 1.87 2002/04/23 02:53:15 david__schmidt + Updated OSX installation section + Added a few English tweaks here an there + + Revision 1.86 2002/04/21 01:46:32 hal9 + Re-write actions section. + + Revision 1.85 2002/04/18 21:23:23 hal9 + Fix ugly typo (mine). + + Revision 1.84 2002/04/18 21:17:13 hal9 + Spell Redhat correctly (ie Red Hat). A few minor grammar corrections. + + Revision 1.83 2002/04/18 18:21:12 oes + Added RPM install detail + + Revision 1.82 2002/04/18 12:04:50 oes + Cosmetics + + Revision 1.81 2002/04/18 11:50:24 oes + Extended Install section - needs fixing by packagers + + Revision 1.80 2002/04/18 10:45:19 oes + Moved text to buildsource.sgml, renamed some filters, details + + Revision 1.79 2002/04/18 03:18:06 hal9 + Spellcheck, and minor touchups. + Revision 1.78 2002/04/17 18:04:16 oes Proofreading part 2