From 286e1eb8ecd11eb8cff1d14cdf8883b5b8934992 Mon Sep 17 00:00:00 2001 From: Fabian Keil Date: Fri, 23 May 2008 16:46:02 +0000 Subject: [PATCH] Sync with user-manual.sgml 2.73. --- doc/webserver/user-manual/actions-file.html | 784 +++---------------- doc/webserver/user-manual/appendix.html | 67 +- doc/webserver/user-manual/config.html | 68 +- doc/webserver/user-manual/configuration.html | 4 +- doc/webserver/user-manual/contact.html | 15 +- doc/webserver/user-manual/copyright.html | 27 +- doc/webserver/user-manual/filter-file.html | 2 +- doc/webserver/user-manual/index.html | 73 +- doc/webserver/user-manual/installation.html | 15 +- doc/webserver/user-manual/quickstart.html | 2 +- doc/webserver/user-manual/seealso.html | 2 +- doc/webserver/user-manual/startup.html | 26 +- 12 files changed, 279 insertions(+), 806 deletions(-) diff --git a/doc/webserver/user-manual/actions-file.html b/doc/webserver/user-manual/actions-file.html index 56f49678..12d3ac3a 100644 --- a/doc/webserver/user-manual/actions-file.html +++ b/doc/webserver/user-manual/actions-file.html @@ -262,7 +262,7 @@ CLASS="FILENAME" >

8.1. Finding the Right Mix

8.2. How to Edit

handle-as-image +blockblock{Banner ads.} } # Block these as if they were images. Send no block page. banners.example.com @@ -772,16 +772,16 @@ CLASS="EMPHASIS" >

The pattern matching syntax is different for the domain and path parts of the URL. The domain part uses a simple globbing type matching technique, - while the path part uses a more flexible + while the path part uses more flexible "Regular - Expressions (PCRE)" based syntax.

(POSIX 1003.2).

8.4.1. The Domain Pattern

8.4.2. The Path Pattern

Privoxy uses Perl compatible (PCRE) +> uses "modern" POSIX 1003.2 "Regular - Expression" based syntax - (through the PCRE library) for - matching the path portion (after the slash), and is thus more flexible.

for matching the path portion (after the slash), + and is thus more flexible.

There is an Appendix with a brief quick-start into regular - expressions, and full (very technical) documentation on PCRE regex syntax is available on-line - at http://www.pcre.org/man.txt. - You might also find the Perl man page on regular expressions (man perlre) - useful, which is available on-line at http://perldoc.perl.org/perlre.html.

man re_format).

Note that the path pattern is automatically left-anchored at the Example: +block+handle-as-image

Type:

Boolean.

Parameterized.

Parameter:

N/A

A block reason that should be given to the user.

Notes:
"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 - screen space -- it displays full-blown if space allows, or miniaturized and text-only - if loaded into a small frame or window. If you are using Privoxy - right now, you can take a look at the - "BLOCKED" - page. + 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).

@@ -2000,18 +1971,18 @@ WIDTH="90%" >

{+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$
# Tag every request with the User-Agent header {+client-header-tagger{user-agent}} / + +# Tagging itself doesn't change the action +# settings, sections with TAG patterns do: +# +# If it's a download agent, use a different forwarding proxy, +# show the real User-Agent and make sure resume works. +{+forward-override{forward-socks5 10.0.0.2:2222 .} \ + -hide-if-modified-since \ + -overwrite-last-modified \ + -hide-user-agent \ + -filter \ + -deanimate-gifs \ +} +TAG:^User-Agent: NetBSD-ftp/ +TAG:^User-Agent: Novell ZYPP Installer +TAG:^User-Agent: RPM APT-HTTP/ +TAG:^User-Agent: fetch libfetch/ +TAG:^User-Agent: Ubuntu APT-HTTP/ +TAG:^User-Agent: MPlayer/ 
+filter{js-annoyances}       # Get rid of particularly annoying JavaScript abuse
+filter{js-annoyances} # Get rid of particularly annoying JavaScript abuse.
+filter{js-events}           # Kill all JS event bindings (Radically destructive! Only for extra nasty sites)
+filter{js-events} # Kill all JS event bindings and timers (Radically destructive! Only for extra nasty sites).
+filter{html-annoyances}     # Get rid of particularly annoying HTML abuse
+filter{html-annoyances} # Get rid of particularly annoying HTML abuse.
+filter{content-cookies}     # Kill cookies that come in the HTML or JS content
+filter{content-cookies} # Kill cookies that come in the HTML or JS content.
+filter{refresh-tags}        # Kill automatic refresh tags (for dial-on-demand setups)
+filter{refresh-tags} # Kill automatic refresh tags (for dial-on-demand setups).
+filter{img-reorder}         # Reorder attributes in <img> tags to make the banners-by-* filters more effective
+filter{img-reorder} # Reorder attributes in <img> tags to make the banners-by-* filters more effective.
+filter{banners-by-size}     # Kill banners by size
+filter{banners-by-size} # Kill banners by size.
+filter{banners-by-link}     # Kill banners by their links to known clicktrackers
+filter{banners-by-link} # Kill banners by their links to known clicktrackers.
+filter{webbugs}             # Squish WebBugs (1x1 invisible GIFs used for user tracking)
+filter{webbugs} # Squish WebBugs (1x1 invisible GIFs used for user tracking).
+filter{tiny-textforms}      # Extend those tiny textareas up to 40x80 and kill the hard wrap
+filter{tiny-textforms} # Extend those tiny textareas up to 40x80 and kill the hard wrap.
+filter{jumping-windows}     # Prevent windows from resizing and moving themselves
+filter{jumping-windows} # Prevent windows from resizing and moving themselves.
+filter{frameset-borders}    # Give frames a border and make them resizeable
+filter{frameset-borders} # Give frames a border and make them resizable.
+filter{demoronizer}         # Fix MS's non-standard use of standard charsets
+filter{demoronizer} # Fix MS's non-standard use of standard charsets.
+filter{shockwave-flash}     # Kill embedded Shockwave Flash objects
+filter{shockwave-flash} # Kill embedded Shockwave Flash objects.
+filter{quicktime-kioskmode} # Make Quicktime movies savable
+filter{quicktime-kioskmode} # Make Quicktime movies saveable.
+filter{crude-parental}      # Crude parental filtering (demo only)
+filter{crude-parental} # Crude parental filtering. Note that this filter doesn't work reliable.
+filter{ie-exploits}         # Disable a known Internet Explorer bug exploits
+filter{ie-exploits} # Disable some known Internet Explorer bug exploits.
+filter{site-specifics}      # Custom filters for specific site related problems
+filter{site-specifics} # Cure for site-specific problems. Don't apply generally!

+filter{google}              # Removes text ads and other Google specific improvements
+filter{no-ping} # Removes non-standard ping attributes in <a> and <area> tags.

+filter{yahoo}               # Removes text ads and other Yahoo specific improvements
+filter{google} # CSS-based block for Google text ads. Also removes a width limitation and the toolbar advertisement.

+filter{msn}                 # Removes text ads and other MSN specific improvements
+filter{yahoo} # CSS-based block for Yahoo text ads. Also removes a width limitation.

+filter{blogspot}            # Cleans up Blogspot blogs
+filter{msn} # CSS-based block for MSN text ads. Also removes tracking URLs and a width limitation.

+filter{no-ping}             # Removes non-standard ping attributes from anchor and area tags
+filter{blogspot} # Cleans up some Blogspot blogs. Read the fine print before using this.
# 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$

8.5.26. inspect-jpegs

Typical use:

Try to protect against a MS buffer over-run in JPEG processing

Effect:

Protect against a known exploit -

Type:

Boolean.

Parameter:

N/A -

Notes:

See Microsoft Security Bulletin MS04-028. JPEG images are one of the most - common image types found across the Internet. The exploit as described can - allow execution of code on the target system, giving an attacker access - to the system in question by merely planting an altered JPEG image, which - would have no obvious indications of what lurks inside. This action - tries to prevent this exploit if delivered through unencrypted HTTP. -

Note that the exploit mentioned is several years old - and it's unlikely that your client is still vulnerable - against it. This action may be removed in one of the - next releases. -

Example usage:

+inspect-jpegs

8.5.27. 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

8.5.28. limit-connect8.5.26. limit-connect

Privoxy only allows HTTP CONNECT - requests to port 443 (the standard, secure HTTPS port). Use - allows HTTP CONNECT requests to all + ports. Use limit-connect if more fine-grained control is desired - for some or all destinations. +> if fine-grained control + is desired for some or all destinations.

The CONNECT methods exists in HTTP to allow access to secure websites @@ -5853,15 +5586,6 @@ CLASS="APPLICATION" >Privoxy'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. 

+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
@@ -5896,7 +5620,7 @@ CLASS="SECT3"
 CLASS="SECT3"
 >8.5.29. prevent-compression8.5.27. prevent-compression
filter,  and
+    deanimate-gifs
-    and kill-popups actions need
-    access to the uncompressed data.
+    actions need access to the uncompressed data.
    
    When compiled with zlib support (available since 8.5.30. overwrite-last-modified8.5.28. overwrite-last-modified
8.5.31. redirect8.5.29. redirect
8.5.32. send-vanilla-wafer
Typical use:
    Feed log analysis scripts with useless data.
-   
Effect:
    Sends a cookie with each request stating that you do not accept any copyright
-    on cookies sent to you, and asking the site operator not to track you.
-   
Type:
Boolean.
Parameter:
    N/A
-   
Notes:
    The vanilla wafer is a (relatively) unique header and could conceivably be used to track you.
-   
    This action is rarely used and not enabled in the default configuration.
-   
Example usage:
     
+send-vanilla-wafer

-

8.5.33. send-wafer

Typical use:

Send custom cookies or feed log analysis scripts with even more useless data. -

Effect:

Sends a custom, user-defined cookie with each request. -

Type:

Multi-value.

Parameter:

A string of the form "name=value". -

Notes:

Being multi-valued, multiple instances of this action can apply to the same request, - resulting in multiple cookies being sent. -

This action is rarely used and not enabled in the default configuration. -

Example usage (section):

{+send-wafer{UsingPrivoxy=true}}
-my-internal-testing-server.void
-

8.5.34. server-header-filter8.5.30. server-header-filter

8.5.35. server-header-tagger8.5.31. server-header-tagger

8.5.36. session-cookies-only8.5.32. session-cookies-only

8.5.37. set-image-blocker8.5.33. set-image-blocker

8.5.38. 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
-

8.5.39. Summary8.5.34. Summary

Note that many of these actions have the potential to cause a page to @@ -7371,7 +6819,7 @@ HREF="actions-file.html#CRUNCH-INCOMING-COOKIES" HREF="actions-file.html#CRUNCH-OUTGOING-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-onlyhide-referrer -kill-popups -prevent-compression @@ -7406,9 +6851,6 @@ HREF="actions-file.html#PREVENT-COMPRESSION" shop = -crunch-all-cookies -filter{all-popups} -kill-popups # Short names for other aliases, for really lazy people ;-) @@ -7454,7 +6896,7 @@ CLASS="SCREEN" # These shops require pop-ups: # - {-kill-popups -filter{all-popups} -filter{unsolicited-popups}} + {-filter{all-popups} -filter{unsolicited-popups}} .dabs.com .overclockers.co.uk

8.7.1. default.action

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 -hide-referrer -kill-popups shop = -crunch-all-cookies -filter{all-popups} -kill-popups+block+block{Banner ads.} } # Generic patterns: @@ -8237,7 +7673,7 @@ CLASS="SECT3" >

8.7.2. user.action

{ +block }{ +block{} } section. Note that { +handle-as-image @@ -8463,7 +7899,7 @@ CLASS="SCREEN" >{ +block } +>{Nasty ads.} } www.example.com/nasty-ads/sponsor\.gif another.example.net/more/junk/here/

14.2. Privoxy's Internal Pages

Short cuts. Turn off, then on:

  • Privoxy - Enable @@ -1030,7 +1030,7 @@ TARGET="_top" >

  • Privoxy - Disable @@ -1039,7 +1039,7 @@ TARGET="_top" >

  • Privoxy - Toggle Privoxy (Toggles between enabled and disabled) @@ -1236,19 +1236,6 @@ CLASS="QUOTE" >

  • 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 

    
 { +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""+block{}" sections, and a "+block +handle-as-image""+block{} +handle-as-image", which is the expanded form of one of our aliases that had been defined as: "+block""+block{}" 
    
 { +block +handle-as-image }
+>
 { +block{Path starts with "ads".} +handle-as-image }
  /ads

    • 7.3.3. hostname

    Specifies:

    The hostname shown on the CGI pages. +

    Type of value:

    Text

    Default value:

    Unset

    Effect if unset:

    The hostname provided by the operating system is used. +

    Notes:

    On some misconfigured systems resolving the hostname fails or + takes too much time and slows Privoxy down. Setting a fixed hostname + works around the problem. +

    In other circumstances it might be desirable to show a hostname + other than the one returned by the operating system. For example + if the system has several different hostnames and you don't want + to use the first one. +

    Note that Privoxy does not validate the specified hostname value. +

    6.1. Controlling Privoxy with Your Web Browser

        Privoxy Menu

    For casual users, our support forum at SourceForge is probably best suited: http://sourceforge.net/tracker/?group_id=11118&atid=211118

    , where the developers also hang around.

    Please don't sent private support requests to individual Privoxy + developers, either use the mailing lists or the support trackers.

    Note that the Privoxy mailing lists are moderated. Posts from unsubscribed addresses have to be accepted manually by a moderator. This may cause a delay of several days and if you use a subject that doesn't clearly @@ -192,7 +195,7 @@ CLASS="FILENAME" >default.action file, to http://sourceforge.net/tracker/?group_id=11118&atid=460288, @@ -229,7 +232,7 @@ NAME="CONTACT-BUGS" >

    Please report all bugs through our bug tracker: http://sourceforge.net/tracker/?group_id=11118&atid=111118.

    and observe the additional hints at the top of the submit form You are welcome to submit ideas on new features or other proposals for improvement through our feature request tracker at http://sourceforge.net/tracker/?atid=361118&group_id=11118.

    12.1. License

    GNU General Public - License, version 2, as published by the Free Software Foundation.

    GNU General Public License, version 2, + as published by the Free Software Foundation.

    This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or - FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for - - more details, which is available from the Free Software Foundation, Inc, -51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA

    You should have received a copy of the GNU General Public License for details.

    You should have received a copy of the GNU GPL along with this program; if not, write to the

     
     Hal Burgiss
    + Mark Miller
     Gerry Murphy
     Roland Rosenfeld
     Jörg Strohmayer

    9.1. Filter File Tutorial


    $Id: user-manual.sgml,v 2.61 2008/02/11 03:41:47 markm68k Exp $

    $Id: user-manual.sgml,v 2.73 2008/05/23 14:43:18 fabiankeil Exp $

    6.1. Controlling Privoxy with Your Web Browser
    single-threaded
    7.3.3. hostname
    8.1. Finding the Right Mix
    8.2. How to Edit
    8.4.1. The Domain Pattern
    8.4.2. The Path Pattern
    8.5.26. inspect-jpegs
    8.5.27. kill-popups
    8.5.28. limit-connect
    8.5.29. 8.5.27. prevent-compression
    8.5.30. 8.5.28. overwrite-last-modified
    8.5.31. 8.5.29. redirect
    8.5.32. send-vanilla-wafer
    8.5.33. send-wafer
    8.5.34. 8.5.30. server-header-filter
    8.5.35. 8.5.31. server-header-tagger
    8.5.36. 8.5.32. session-cookies-only
    8.5.37. 8.5.33. set-image-blocker
    8.5.38. treat-forbidden-connects-like-blocks
    8.5.39. 8.5.34. Summary
    8.7.1. default.action
    8.7.2. user.action
    9.1. Filter File Tutorial
    12.1. License
    14.2. Privoxy's Internal Pages
    /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).

    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).

    sources is to download the source tarball from our project download pageactions file (as a separate package

    http://sourceforge.net/tracker/?group_id=11118&atid=460288, to submit

    5.6. 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