X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fuser-manual.sgml;h=a94d1d29988dde207849f9c629c6f11a4e73e9f1;hp=21c08ca0038dca941d109b0ef0eba90c793be0cc;hb=f4107f65b676b63a199fe4230e58695757f9f199;hpb=5efac2fb70ba4e83dfb50f24bebb22939e5b2fe9 diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml index 21c08ca0..a94d1d29 100644 --- a/doc/source/user-manual.sgml +++ b/doc/source/user-manual.sgml @@ -33,7 +33,7 @@ This file belongs into ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/ - $Id: user-manual.sgml,v 2.59 2008/02/11 00:52:34 markm68k Exp $ + $Id: user-manual.sgml,v 2.66 2008/03/06 16:33:47 fabiankeil Exp $ Copyright (C) 2001-2008 Privoxy Developers http://www.privoxy.org/ See LICENSE. @@ -59,7 +59,7 @@ -$Id: user-manual.sgml,v 2.59 2008/02/11 00:52:34 markm68k Exp $ +$Id: user-manual.sgml,v 2.66 2008/03/06 16:33:47 fabiankeil Exp $ Mac OS X - Unzip the downloaded file (you can either double-click on the zipe file + Unzip the downloaded file (you can either double-click on the zip file icon from the Finder, or from the desktop if you downloaded it there). Then, double-click on the package installer icon and follow the installation process. @@ -309,17 +309,13 @@ How to install the binary packages depends on your operating system: The privoxy service will automatically start after a successful installation (in addition to 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 + computer starts up, remove or rename the folder named /Library/StartupItems/Privoxy. - To manually start or stop the privoxy service, download and install the - Privoxy Utility for Mac OS X. - This application controls the privoxy service (e.g. starting and - stopping the service as well as uninstalling the software). - - - The Privoxy Utility also provides an option to uninstall the software. + To manually start or stop the privoxy service, use the Privoxy Utility + for Mac OS X. This application controls the privoxy service (e.g. + starting and stopping the service as well as uninstalling the software). @@ -1346,6 +1342,34 @@ 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. + + + 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. + + + An administrator username and password must be supplied in order for + the Privoxy Utility to perform any of the tasks. + During installation, Privoxy is configured to start automatically when the system restarts. To start &my-app; manually, @@ -1432,11 +1456,9 @@ must find a better place for this paragraph Another feature where you will probably want to define exceptions for trusted - sites is the popup-killing (through the +kill-popups and - +filter{popups} - actions), because your favorite shopping, banking, or leisure site may need + sites is the popup-killing (through +filter{popups}), + because your favorite shopping, banking, or leisure site may need popups (explained below). @@ -2184,7 +2206,7 @@ for details. - { +handle-as-image +block } + { +handle-as-image +block{Banner ads.} } # Block these as if they were images. Send no block page. banners.example.com media.example.com/.*banners @@ -2614,7 +2636,7 @@ for details. -name # disable action name - Example: +block + Example: +handle-as-image @@ -2797,14 +2819,14 @@ for details. Type: - Boolean. + Parameterized. Parameter: - N/A + A block reason that should be given to the user. @@ -2813,15 +2835,22 @@ for details. Privoxy sends a special BLOCKED page - for requests to blocked pages. This page contains links to find out why the request - was blocked, and a click-through to the blocked content (the latter only if compiled with the - force feature enabled). The BLOCKED page adapts to the available + for requests to blocked pages. This page contains the block reason given as + parameter, a link to find out why the block action applies, and a click-through + to the blocked content (the latter only if the force feature is available and + enabled). + + A very important exception occurs if both block and handle-as-image, @@ -2850,18 +2879,18 @@ for details. Example usage (section): - {+block} + {+block{No nasty stuff for you.}} # Block and replace with "blocked" page .nasty-stuff.example.com -{+block +handle-as-image} +{+block{Doubleclick banners.} +handle-as-image} # Block and replace with image .ad.doubleclick.net .ads.r.us/banners/ -{+block +handle-as-empty-document} +{+block{Layered ads.} +handle-as-empty-document} # Block and then ignore - adserver.exampleclick.net/.*\.js$ + adserver.example.net/.*\.js$ @@ -4287,7 +4316,7 @@ new action # Block all documents on example.org that end with ".js", # but send an empty document instead of the usual HTML message. -{+block +handle-as-empty-document} +{+block{Blocked JavaScript} +handle-as-empty-document} example.org/.*\.js$ @@ -4374,11 +4403,8 @@ example.org/.*\.js$ # These don't look like images, but they're banners and should be # blocked as images: # -{+block +handle-as-image} -some.nasty-banner-server.com/junk.cgi\?output=trash - -# Banner source! Who cares if they also have non-image content? -ad.doubleclick.net +{+block{Nasty banners.} +handle-as-image} +nasty-banner-server.example.com/junk.cgi\?output=trash @@ -5038,101 +5064,6 @@ new action - - -kill-popups<anchor id="kill-popup"> - - - - Typical use: - - Eliminate those annoying pop-up windows (deprecated) - - - - - Effect: - - - While loading the document, replace JavaScript code that opens - pop-up windows with (syntactically neutral) dummy code on the fly. - - - - - - Type: - - - Boolean. - - - - - Parameter: - - - N/A - - - - - - Notes: - - - This action is basically a built-in, hardwired special-purpose filter - action, but there are important differences: For kill-popups, - the document need not be buffered, so it can be incrementally rendered while - downloading. But kill-popups doesn't catch as many pop-ups as - filter{all-popups} - does and is not as smart as filter{unsolicited-popups} - is. - - - Think of it as a fast and efficient replacement for a filter that you - can use if you don't want any filtering at all. Note that it doesn't make - sense to combine it with any filter action, - since as soon as one filter applies, - the whole document needs to be buffered anyway, which destroys the advantage of - the kill-popups action over its filter equivalent. - - - Killing all pop-ups unconditionally is problematic. Many shops and banks rely on - pop-ups to display forms, shopping carts etc, and the filter{unsolicited-popups} - does a better job of catching only the unwanted ones. - - - If the only kind of pop-ups that you want to kill are exit consoles (those - really nasty windows that appear when you close an other - one), you might want to use - filter{js-annoyances} - instead. - - - 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 - - - - - - limit-connect @@ -5177,10 +5108,9 @@ new action By default, i.e. if no limit-connect action applies, - Privoxy only allows HTTP CONNECT - requests to port 443 (the standard, secure HTTPS port). Use - limit-connect if more fine-grained control is desired - for some or all destinations. + Privoxy allows HTTP CONNECT requests to all + ports. Use limit-connect if fine-grained control + is desired for some or all destinations. The CONNECT methods exists in HTTP to allow access to secure websites @@ -5193,9 +5123,6 @@ new action Privoxy relays HTTPS traffic without seeing the decoded content. Websites can leverage this limitation to circumvent &my-app;'s filters. By specifying an invalid port range you can disable HTTPS entirely. - If you plan to disable SSL by default, consider enabling - treat-forbidden-connects-like-blocks - as well, to be able to quickly create exceptions. @@ -5207,7 +5134,7 @@ new action - +limit-connect{443} # This is the default and need not be specified. + +limit-connect{443} # Port 443 is OK. +limit-connect{80,443} # Ports 80 and 443 are OK. +limit-connect{-3, 7, 20-100, 500-} # Ports less than 3, 7, 20 to 100 and above 500 are OK. +limit-connect{-} # All ports are OK @@ -5265,9 +5192,9 @@ new action More and more websites send their content compressed by default, which is generally a good idea and saves bandwidth. But the filter, deanimate-gifs - and kill-popups actions need - access to the uncompressed data. + linkend="filter">filter and + deanimate-gifs + actions need access to the uncompressed data. When compiled with zlib support (available since &my-app; 3.0.7), content that should be @@ -6020,81 +5947,6 @@ example.org/instance-that-is-delivered-as-xml-but-is-not - - -treat-forbidden-connects-like-blocks - - - - Typical use: - - Block forbidden connects with an easy to find error message. - - - - - Effect: - - - If this action is enabled, Privoxy no longer - makes a difference between forbidden connects and ordinary blocks. - - - - - - Type: - - - Boolean - - - - - Parameter: - - N/A - - - - - Notes: - - - By default Privoxy answers - forbidden Connect requests - with a short error message inside the headers. If the browser doesn't display - headers (most don't), you just see an empty page. - - - With this action enabled, Privoxy displays - the message that is used for ordinary blocks instead. If you decide - to make an exception for the page in question, you can do so by - following the See why link. - - - For Connect requests the clients tell - Privoxy which host they are interested - in, but not which document they plan to get later. As a result, the - Go there anyway wouldn't work and is therefore suppressed. - - - - - - Example usage: - - - +treat-forbidden-connects-like-blocks - - - - - - - Summary @@ -6169,15 +6021,15 @@ new action # +crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies -crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies - +block-as-image = +block +handle-as-image + +block-as-image = +block{Blocked image.} +handle-as-image allow-all-cookies = -crunch-all-cookies -session-cookies-only -filter{content-cookies} # These aliases define combinations of actions # that are useful for certain types of sites: # - fragile = -block -filter -crunch-all-cookies -fast-redirects -hide-referrer -kill-popups -prevent-compression + fragile = -block -filter -crunch-all-cookies -fast-redirects -hide-referrer -prevent-compression - shop = -crunch-all-cookies -filter{all-popups} -kill-popups + shop = -crunch-all-cookies -filter{all-popups} # Short names for other aliases, for really lazy people ;-) # @@ -6212,7 +6064,7 @@ new action # These shops require pop-ups: # - {-kill-popups -filter{all-popups} -filter{unsolicited-popups}} + {-filter{all-popups} -filter{unsolicited-popups}} .dabs.com .overclockers.co.uk @@ -6283,14 +6135,14 @@ that also explains why and how aliases are used: # +crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies -crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies - +block-as-image = +block +handle-as-image + +block-as-image = +block{Blocked image.} +handle-as-image mercy-for-cookies = -crunch-all-cookies -session-cookies-only -filter{content-cookies} # These aliases define combinations of actions # that are useful for certain types of sites: # - fragile = -block -filter -crunch-all-cookies -fast-redirects -hide-referrer -kill-popups - shop = -crunch-all-cookies -filter{all-popups} -kill-popups + fragile = -block -filter -crunch-all-cookies -fast-redirects -hide-referrer + shop = -crunch-all-cookies -filter{all-popups} @@ -6403,8 +6255,7 @@ mail.google.com now. Mozilla users, who can turn on smart handling of unwanted pop-ups in their browsers, can safely choose - -filter{popups} (and - -kill-popups) above + -filter{popups} above and hence don't need this section. Anyway, disabling an already disabled action doesn't hurt, so we'll define our exceptions regardless of what was chosen in the defaults section: @@ -6414,7 +6265,7 @@ mail.google.com # These sites require pop-ups too :( # -{ -kill-popups -filter{popups} } +{ -filter{popups} } .dabs.com .overclockers.co.uk .deutsche-bank-24.de @@ -6517,7 +6368,7 @@ bs*.gsanet.com ########################################################################## # Block these fine banners: ########################################################################## -{ +block } +{ +block{Banner ads.} } # Generic patterns: # @@ -6663,14 +6514,14 @@ wiki. +crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies -crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies allow-all-cookies = -crunch-all-cookies -session-cookies-only - allow-popups = -filter{all-popups} -kill-popups -+block-as-image = +block +handle-as-image + allow-popups = -filter{all-popups} ++block-as-image = +block{Blocked as image.} +handle-as-image -block-as-image = -block # These aliases define combinations of actions that are useful for # certain types of sites: # -fragile = -block -crunch-all-cookies -filter -fast-redirects -hide-referrer -kill-popups +fragile = -block -crunch-all-cookies -filter -fast-redirects -hide-referrer shop = -crunch-all-cookies allow-popups # Allow ads for selected useful free sites: @@ -6734,7 +6585,7 @@ stupid-server.example.com/ seen an ad on your favourite page on example.com that you want to get rid of. You have right-clicked the image, selected copy image location and pasted the URL below while removing the leading http://, into a - { +block } section. Note that { +handle-as-image + { +block{} } section. Note that { +handle-as-image } need not be specified, since all URLs ending in .gif will be tagged as images by the general rules as set in default.action anyway: @@ -6742,7 +6593,7 @@ stupid-server.example.com/ -{ +block } +{ +block{Nasty ads.} } www.example.com/nasty-ads/sponsor\.gif another.example.net/more/junk/here/ @@ -8363,13 +8214,6 @@ Requests actions. - - - If the +kill-popups - action applies, and it is an HTML or JavaScript document, the popup-code in the - response is filtered on-the-fly as it is received. - - If any +filter action @@ -8624,7 +8468,6 @@ In file: user.action [ View ] [ Edit ][ View ] [ Edit ] + +set-image-blocker {pattern} @@ -8652,21 +8494,21 @@ In file: user.action [ View ] [ Edit ] - { +block } + { +block{Domains starts with "ad"} } ad*. - { +block } + { +block{Domain contains "ad"} } .ad. - { +block +handle-as-image } + { +block{Doubleclick banner server} +handle-as-image } .[a-vx-z]*.doubleclick.net We'll just show the interesting part here - the explicit matches. It is - matched three different times. Two +block sections, - and a +block +handle-as-image, + matched three different times. Two +block{} sections, + and a +block{} +handle-as-image, which is the expanded form of one of our aliases that had been defined as: +block-as-image. (Aliases are defined in @@ -8681,7 +8523,7 @@ In file: user.action [ View ] [ Edit ]ad.doubleclick.net is done here -- as both a +block + linkend="BLOCK">+block{} and an +handle-as-image. The custom alias +block-as-image just @@ -8748,7 +8590,6 @@ In file: user.action [ View ] [ Edit ][ View ] [ Edit ] @@ -8803,7 +8643,7 @@ In file: user.action [ View ] [ Edit ] - { +block +handle-as-image } + { +block{Path starts with "ads".} +handle-as-image } /ads @@ -8919,6 +8759,28 @@ In file: user.action [ View ] [ Edit ]