X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;f=doc%2Fsource%2Fuser-manual.sgml;h=a94d1d29988dde207849f9c629c6f11a4e73e9f1;hb=f4107f65b676b63a199fe4230e58695757f9f199;hp=96e9dd6b445daa58ae82c38e7a53a1cfefe93df8;hpb=1c65b403497a33768a05385f5575437fd63370cb;p=privoxy.git
diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml
index 96e9dd6b..a94d1d29 100644
--- a/doc/source/user-manual.sgml
+++ b/doc/source/user-manual.sgml
@@ -11,11 +11,11 @@
-
-
+
+
-
-
+
+
@@ -33,7 +33,7 @@
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: user-manual.sgml,v 2.56 2008/01/31 19:11:35 fabiankeil 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.56 2008/01/31 19:11:35 fabiankeil Exp $
+$Id: user-manual.sgml,v 2.66 2008/03/06 16:33:47 fabiankeil Exp $
-Mac OSX
-
- Unzip the downloaded file (you can either double-click on the file
- from the finder, or from the desktop if you downloaded it there).
- Then, double-click on the package installer icon named
- Privoxy.pkg
- and follow the installation process.
- Privoxy will be installed in the folder
- /Library/Privoxy.
- It will start automatically whenever you start up. To prevent it from
- starting automatically, remove or rename the folder
- /Library/StartupItems/Privoxy.
-
+Mac OS X
- To start Privoxy by hand, double-click on
- StartPrivoxy.command in the
- /Library/Privoxy folder.
- Or, type this command in the Terminal:
+ 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.
-
- /Library/Privoxy/StartPrivoxy.command
-
+ 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
+ /Library/StartupItems/Privoxy.
- You will be prompted for the administrator password.
+ 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).
@@ -1349,7 +1341,35 @@ Example Unix startup command:
-Mac OSX
+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,
@@ -1436,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).
@@ -2188,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
@@ -2618,7 +2636,7 @@ for details.
-name # disable action name
- Example: +block
+ Example: +handle-as-image
@@ -2801,14 +2819,14 @@ for details.
Type:
- Boolean.
+ Parameterized.Parameter:
- N/A
+ A block reason that should be given to the user.
@@ -2817,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 bothblock and handle-as-image,
@@ -2854,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$
@@ -4291,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$
@@ -4378,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
@@ -5042,101 +5064,6 @@ new action
-
-
-kill-popups
-
-
-
- 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
@@ -5181,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
@@ -5197,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.
@@ -5211,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
@@ -5269,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
@@ -6024,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
@@ -6173,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 ;-)
#
@@ -6216,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
@@ -6287,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}
@@ -6407,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:
@@ -6418,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
@@ -6521,7 +6368,7 @@ bs*.gsanet.com
##########################################################################
# Block these fine banners:
##########################################################################
-{ +block }
+{ +block{Banner ads.} }
# Generic patterns:
#
@@ -6667,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:
@@ -6738,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:
@@ -6746,7 +6593,7 @@ stupid-server.example.com/
-{ +block }
+{ +block{Nasty ads.} }
www.example.com/nasty-ads/sponsor\.gif
another.example.net/more/junk/here/
@@ -8367,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
@@ -8628,7 +8468,6 @@ In file: user.action [ View ][ Edit ][ View ][ Edit ]
+ +set-image-blocker {pattern}
@@ -8656,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
@@ -8685,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
@@ -8752,7 +8590,6 @@ In file: user.action [ View ][ Edit ][ View ][ Edit ]
@@ -8807,7 +8643,7 @@ In file: user.action [ View ][ Edit ]
- { +block +handle-as-image }
+ { +block{Path starts with "ads".} +handle-as-image }
/ads
@@ -8923,6 +8759,37 @@ In file: user.action [ View ][ Edit ][ View ][ Edit ][ View ][ Edit ][ View ][ Edit ][ View ][ Edit ]