X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fwebserver%2Fuser-manual%2Factions-file.html;h=5a20e52d22844281839947d46191e92f6e3161a3;hp=72b9a064357bde67447ccedb2fa08972b5ddf4d9;hb=594da2fb0547a6325317ff12476f400622bb6cf5;hpb=e61fdec519cef582a2dc5507543a006b539ad3f4 diff --git a/doc/webserver/user-manual/actions-file.html b/doc/webserver/user-manual/actions-file.html index 72b9a064..5a20e52d 100644 --- a/doc/webserver/user-manual/actions-file.html +++ b/doc/webserver/user-manual/actions-file.html @@ -1,13 +1,13 @@ + Actions Files +HREF="../p_doc.css"> Privoxy 3.0.7 User ManualPrivoxy 3.0.13 User Manual8. Actions Files8. Actions Files

The actions files are used to define what Privoxy with - differing purposes: -

Notes:

This action takes parameters similar to the +> This action takes parameters similar to the forward8.5.17. handle-as-empty-document8.5.18. handle-as-empty-document

# 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.18. handle-as-image8.5.19. handle-as-image

8.5.19. hide-accept-language8.5.20. hide-accept-language

8.5.20. hide-content-disposition8.5.21. hide-content-disposition

This action will probably be removed in the future, + use server-header filters instead. +

Example usage:
8.5.21. hide-if-modified-since8.5.22. hide-if-modified-since

"If-Modified-Since:" makes - sure it isn't used as a cookie replacement, but you will run into - caching problems if the random range is too high. + it less likely that the server can use the time as a cookie replacement, + but you will run into caching problems if the random range is too high.

It is a good idea to only use a small negative value and let @@ -5066,7 +5080,8 @@ CLASS="LITERAL" HREF="actions-file.html#CRUNCH-IF-NONE-MATCH" >crunch-if-none-match. +>, + otherwise it's more or less pointless. 

# Let the browser revalidate without being tracked across sessions
-{ +hide-if-modified-since{-60} \
+># Let the browser revalidate but make tracking based on the time less likely.
+{+hide-if-modified-since{-60} \
  +overwrite-last-modified{randomize} \
  +crunch-if-none-match}
 /

8.5.22. hide-forwarded-for-headers

Typical use:

Improve privacy by hiding the true source of the request

Effect:

Deletes any existing "X-Forwarded-for:" HTTP header from client requests, - and prevents adding a new one. -

Type:

Boolean.

Parameter:

N/A -

Notes:

It is fairly safe to leave this on. -

This action is scheduled for improvement: It should be able to generate forged - "X-Forwarded-for:" headers using random IP addresses from a specified network, - to make successive requests from the same client look like requests from a pool of different - users sharing the same proxy. -

Example usage:

+hide-forwarded-for-headers
-

8.5.23. hide-from-header

8.5.23. hide-from-header

8.5.24. hide-referrer8.5.24. hide-referrer

"conditional-forge" to forge the header if the host has changed.

  • "block" to delete the header unconditionally.

    • Always blocking the referrer, or using a custom one, can lead to failures on servers that check the referrer before they answer any - requests, in an attempt to prevent their valuable content from being + requests, in an attempt to prevent their content from being embedded or linked to elsewhere.

    8.5.25. hide-user-agent8.5.25. hide-user-agent

    Typical use:

    Conceal your type of browser and client operating system

    Try to conceal your type of browser and client operating system

    Effect:
    the right thing to do: good web sites work browser-independently). -

    This action is scheduled for improvement. +> More information on known user-agent strings can be found at + http://www.user-agents.org/ + and + http://en.wikipedia.org/wiki/User_agent.

    8.5.26. inspect-jpegs

    8.5.26. limit-connect

    Typical use:

    To protect against the MS buffer over-run in JPEG processing

    Prevent abuse of Privoxy as a TCP proxy relay or disable SSL for untrusted sites

    Effect:

    Protect against a known exploit +> Specifies to which ports HTTP CONNECT requests are allowable.

    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 - prevents unwanted intrusion. -

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

    Example usage:

    +kill-popups

    8.5.28. limit-connect

    Typical use:

    Prevent abuse of Privoxy as a TCP proxy relay or disable SSL for untrusted sites

    Effect:

    Specifies to which ports HTTP CONNECT requests are allowable. -

    Type:

    Parameterized.

    Parameterized.

    Parameter:
    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 @@ -5904,8 +5610,7 @@ CLASS="QUOTE" > 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 server. - This can be a big security hole, since CONNECT-enabled proxies can be - abused as TCP relays very easily. + This means CONNECT-enabled proxies can be used as TCP relays very easily.

    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
@@ -5960,8 +5656,8 @@ 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
    hided-if-modified-sincehide-if-modified-since
     to further customize your random range.
@@ -6272,8 +5962,8 @@ CLASS="SECT3"
 CLASS="SECT3"
 >8.5.31. redirect8.5.29. redirect
        In case of problems with your redirects, or simply to watch
+    them working, enable debug 128.
+   
    Example usages:
    
-

    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

    Typical use:

    Disable or disable filters based on the Content-Type header. +> Enable or disable filters based on the Content-Type header. 

    # Tag every request with the declared content type
-{+client-header-filter{content-type}}
+># Tag every request with the content type declared by the server
+{+server-header-tagger{content-type}}
 /
    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. Summary

    8.5.34. Summary

    Note that many of these actions have the potential to cause a page to misbehave, possibly even not to display at all. There are many ways @@ -7296,8 +6736,8 @@ CLASS="SECT2" CLASS="SECT2" >8.6. Aliases8.6. Aliases

    Custom 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 @@ -7470,9 +6907,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 ;-) @@ -7518,7 +6952,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.uk8.7. Actions Files Tutorial8.7. Actions Files Tutorial

    The above chapters have shown . Now, let's look at an example match-all.action, default.action + and user.action file and see how all these pieces come together:

    8.7.1. match-all.action

    Remember all actions are disabled when matching starts, + so we have to explicitly enable the ones we want.

    While the match-all.action file only contains a + single section, it is probably the most important one. It has only one + pattern, "/", but this pattern + matches all URLs. Therefore, the set of + actions used in this "default" section will + be applied to all requests as a start. It can be partly or + wholly overridden by other actions files like default.action and + and user.action - file and see how all these pieces come together:

    8.7.1. default.action

    , but it will still be largely responsible + for your overall browsing experience.

    Every config file should start with a short comment stating its purpose:

    Again, at the start of matching, all actions are disabled, so there is + no need to disable any actions here. (Remember: a "+" + preceding the action name enables the action, a "-" disables!). + Also note how this long line has been made more readable by splitting it into + multiple lines with line continuation.

    # Sample default.action file <ijbswa-developers@lists.sourceforge.net>
    { \ + +change-x-forwarded-for{block} \ + +hide-from-header{block} \ + +set-image-blocker{pattern} \ +} +/ # Match all URLs +

    Then, since this is the The default behavior is now set.

    8.7.2. default.action

    If you aren't a developer, there's no need for you to edit the + default.action file. It is maintained by + the Privoxy developers and if you disagree with some of the + sections, you should overrule them in your user.action.

    Understanding the default.action file, the -first section is a special section for internal use that you needn't -change or worry about:

    file can + help you with your user.action, though.

    The first section in this file is a special section for internal use + that prevents older Privoxy versions from reading the file:

    ########################################################################## # Settings -- Don't change! For internal Privoxy use ONLY. ########################################################################## - {{settings}} -for-privoxy-version=3.0

    After that comes the (optional) alias section. We'll use the example -section from the above After that comes the (optional) alias section. We'll use the example + section from the above chapter on aliases, -that also explains why and how aliases are used:

    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

    Now come the regular sections, i.e. sets of actions, accompanied - by URL patterns to which they apply. Remember all actions - are disabled when matching starts, so we have to explicitly - enable the ones we want.

    The first regular section is probably the most important. It has only - one pattern, "/", but this pattern - matches all URLs. Therefore, the - set of actions used in this "default" section will - be applied to all requests as a start. It can be partly or - wholly overridden by later matches further down this file, or in user.action, - but it will still be largely responsible for your overall browsing - experience.

    Again, at the start of matching, all actions are disabled, so there is - no real need to disable any actions here, but we will do that nonetheless, - to have a complete listing for your reference. (Remember: a "+" - preceding the action name enables the action, a "-" disables!). - Also note how this long line has been made more readable by splitting it into - multiple lines with line continuation.

    ##########################################################################
-# "Defaults" section:
-##########################################################################
- { \
- -add-header \
- -client-header-filter{hide-tor-exit-notation} \
- -block \
- -content-type-overwrite \
- -crunch-client-header \
- -crunch-if-none-match \
- -crunch-incoming-cookies \
- -crunch-server-header \
- -crunch-outgoing-cookies \
- +deanimate-gifs \
- -downgrade-http-version \
- -fast-redirects{check-decoded-url} \
- -filter{js-annoyances} \
- -filter{js-events} \
- +filter{html-annoyances} \
- -filter{content-cookies} \
- +filter{refresh-tags} \
- -filter{unsolicited-popups} \
- -filter{all-popups} \
- -filter{img-reorder} \
- -filter{banners-by-size} \
- -filter{banners-by-link} \
- +filter{webbugs} \
- -filter{tiny-textforms} \
- -filter{jumping-windows} \
- -filter{frameset-borders} \
- -filter{demoronizer} \
- -filter{shockwave-flash} \
- -filter{quicktime-kioskmode} \
- -filter{fun} \
- -filter{crude-parental} \
- +filter{ie-exploits} \     
- -filter{google} \
- -filter{yahoo} \
- -filter{msn} \
- -filter{blogspot} \
- -filter{no-ping} \
- -force-text-mode \
- -handle-as-empty-document \
- -handle-as-image \
- -hide-accept-language \
- -hide-content-disposition \
- -hide-if-modified-since \
- +hide-forwarded-for-headers \
- +hide-from-header{block} \
- +hide-referrer{forge} \
- -hide-user-agent \
- -inspect-jpegs \
- -kill-popups \
- -limit-connect \
- +prevent-compression \
- -overwrite-last-modified \
- -redirect \
- -send-vanilla-wafer \
- -send-wafer \
- -server-header-filter{xml-to-html} \
- -server-header-filter{html-to-xml} \
- +session-cookies-only \
- +set-image-blocker{pattern} \
- -treat-forbidden-connects-like-blocks \
- }
- / # forward slash will match *all* potential URL patterns.

    The default behavior is now set. Note that some actions, like not hiding - the user agent, are part of a "general policy" that applies - universally and won't get any exceptions defined later. Other choices, - like not blocking (which is understandably the - default!) need exceptions, i.e. we need to specify explicitly what we - want to block in later sections.

    The first of our specialized sections is concerned with "fragile"fast-redirects - action, which we enabled per default above, breaks some sites. So disable - it for popular sites where we know it misbehaves:

    match-all.action    , + breaks some sites. So disable it for popular sites where we know it misbehaves:

    and - information). We can mark any URL as an image with the +block+block{Banner ads.} } # Generic patterns: @@ -8511,9 +7716,9 @@ CLASS="SECT3" >

    8.7.2. user.action

    8.7.3. user.action

    So far we are painting with a broad brush by setting general policies, which would be a reasonable starting point for many people. Now, @@ -8560,7 +7765,7 @@ WIDTH="100%" >

    # My user.action file. <fred@foobar.com>
    # My user.action file. <fred@example.com>
    { +block }{ +block{} } section. Note that { +handle-as-image @@ -8737,9 +7942,9 @@ CLASS="SCREEN" >{ +block } +>{Nasty ads.} } www.example.com/nasty-ads/sponsor\.gif - another.popular.site.net/more/junk/here/default.filter, - but it is disabled in the distributed actions file. (My colleagues on the team just - don't have a sense of humour, that's why! ;-). So you'd like to turn it on in your private, + but it is disabled in the distributed actions file. + So you'd like to turn it on in your private, update-safe config, once and for all: