- <para>
- General improvements:
- <itemizedlist>
- <listitem>
- <para>
- Privoxy can (re)compress buffered content before delivering
- it to the client. Disabled by default as most users wouldn't
- benefit from it.
- </para>
- </listitem>
- <listitem>
- <para>
- The +fast-redirects{check-decoded-url} action checks URL
- segments separately. If there are other parameters behind
- the redirect URL, this makes it unnecessary to cut them off
- by additionally using a +redirect{} pcrs command.
- Initial patch submitted by Jamie Zawinski in #3429848.
- </para>
- </listitem>
- <listitem>
- <para>
- When loading action sections, verify that the referenced filters
- exist. Currently missing filters only result in an error message,
- but eventually the severity will be upgraded to fatal.
- </para>
- </listitem>
- <listitem>
- <para>
- Allow to bind to multiple separate addresses.
- Patch set submitted by Petr Pisar in #3354485.
- </para>
- </listitem>
- <listitem>
- <para>
- Set socket_error to errno if connecting fails in rfc2553_connect_to().
- Previously rejected direct connections could be incorrectly reported
- as DNS issues if Privoxy was compiled with IPv6 support.
- </para>
- </listitem>
- <listitem>
- <para>
- Adjust url_code_map[] so spaces are replaced with %20 instead of '+'
- While '+' can be used by client's submitting form data, this is not
- actually what Privoxy is using the lookups for. This is more of a
- cosmetic issue and doesn't fix any known problems.
- </para>
- </listitem>
- <listitem>
- <para>
- When compiled without FEATURE_FAST_REDIRECTS, do not silently
- ignore +fast-redirect{} directives
- </para>
- </listitem>
- <listitem>
- <para>
- Added a workaround for GNU libc's strptime() reporting negative
- year values when the parsed year is only specified with two digits.
- On affected systems cookies with such a date would not be turned
- into session cookies by the +session-cookies-only action.
- Reported by Vaeinoe in #3403560
- </para>
- </listitem>
- <listitem>
- <para>
- Fixed bind failures with certain GNU libc versions if no non-loopback
- IP address has been configured on the system. This is mainly an issue
- if the system is using DHCP and Privoxy is started before the network
- is completely configured.
- Reported by Raphael Marichez in #3349356.
- Additional insight from Petr Pisar.
- </para>
- </listitem>
- <listitem>
- <para>
- Privoxy log messages now use the ISO 8601 date format %Y-%m-%d.
- It's only slightly longer than the old format, but contains
- the full date including the year and allows sorting by date
- (when grepping in multiple log files) without hassle.
- </para>
- </listitem>
- <listitem>
- <para>
- In get_last_url(), do not bother trying to decode URLs that do
- not contain at least one '%' sign. It reduces the log noise and
- a number of unnecessary memory allocations.
- </para>
- </listitem>
- <listitem>
- <para>
- In case of SOCKS5 failures, dump the socks response in the log message.
- </para>
- </listitem>
- <listitem>
- <para>
- Simplify the signal setup in main().
- </para>
- </listitem>
- <listitem>
- <para>
- Streamline socks5_connect() slightly.
- </para>
- </listitem>
- <listitem>
- <para>
- In socks5_connect(), require a complete socks response from the server.
- Previously Privoxy didn't care how much data the server response
- contained as long as the first two bytes contained the expected
- values. While at it, shrink the buffer size so Privoxy can't read
- more than a whole socks response.
- </para>
- </listitem>
- <listitem>
- <para>
- In chat(), do not bother to generate a client request in case of
- direct CONNECT requests. It will not be used anyway.
- </para>
- </listitem>
- <listitem>
- <para>
- Reduce server_last_modified()'s stack size.
- </para>
- </listitem>
- <listitem>
- <para>
- Shorten get_http_time() by using strftime().
- </para>
- </listitem>
- <listitem>
- <para>
- Constify the known_http_methods pointers in unknown_method().
- </para>
- </listitem>
- <listitem>
- <para>
- Constify the time_formats pointers in parse_header_time().
- </para>
- </listitem>
- <listitem>
- <para>
- Constify the formerly_valid_actions pointers in action_used_to_be_valid().
- </para>
- </listitem>
- <listitem>
- <para>
- Introduce a GNUMakefile MAN_PAGE variable that defaults to privoxy.1.
- The Debian package uses section 8 for the man page and this
- should simplify the patch.
- </para>
- </listitem>
- <listitem>
- <para>
- Deduplicate the INADDR_NONE definition for Solaris by moving it to jbsockets.h
- </para>
- </listitem>
- <listitem>
- <para>
- In block_url(), ditch the obsolete workaround for ancient Netscape versions
- that supposedly couldn't properly deal with status code 403.
- </para>
- </listitem>
- <listitem>
- <para>
- Remove a useless NULL pointer check in load_trustfile().
- </para>
- </listitem>
- <listitem>
- <para>
- Remove two useless NULL pointer checks in load_one_re_filterfile().
- </para>
- </listitem>
- <listitem>
- <para>
- Change url_code_map[] from an array of pointers to an array of arrays
- It removes an unnecessary layer of indirection and on 64bit system reduces
- the size of the binary a bit.
- </para>
- </listitem>
- <listitem>
- <para>
- Fix various typos. Fixes taken from Debian's 29_typos.dpatch by Roland Rosenfeld.
- </para>
- </listitem>
- <listitem>
- <para>
- Add a dok-tidy GNUMakefile target to clean up the messy HTML
- generated by the other dok targets.
- </para>
- </listitem>
- <listitem>
- <para>
- GNUisms in the GNUMakefile have been removed.
- </para>
- </listitem>
- <listitem>
- <para>
- Change the HTTP version in static responses to 1.1
- </para>
- </listitem>
- <listitem>
- <para>
- Synced config.sub and config.guess with upstream
- 2011-11-11/386c7218162c145f5f9e1ff7f558a3fbb66c37c5.
- </para>
- </listitem>
- <listitem>
- <para>
- Add a dedicated function to parse the values of toggles. Reduces duplicated
- code in load_config() and provides better error handling. Invalid or missing
- toggle values are now a fatal error instead of being silently ignored.
- </para>
- </listitem>
- <listitem>
- <para>
- Terminate HTML lines in static error messages with \n instead of \r\n.
- </para>
- </listitem>
- <listitem>
- <para>
- Simplify cgi_error_unknown() a bit.
- </para>
- </listitem>
- <listitem>
- <para>
- In LogPutString(), don't bother looking at pszText when not
- actually logging anything.
- </para>
- </listitem>
- <listitem>
- <para>
- Change ssplit()'s fourth parameter from int to size_t.
- Fixes a clang complaint.
- </para>
- </listitem>
- <listitem>
- <para>
- Add a warning that the statistics currently can't be trusted.
- Mention Privoxy-Log-Parser's --statistics option as
- an alternative for the time being.
- </para>
- </listitem>
- <listitem>
- <para>
- In rfc2553_connect_to(), start setting cgi->error_message on error.
- </para>
- </listitem>
- <listitem>
- <para>
- Change the expected status code returned for http://p.p/die depending
- on whether or not FEATURE_GRACEFUL_TERMINATION is available.
- </para>
- </listitem>
- <listitem>
- <para>
- In cgi_die(), mark the client connection for closing.
- If the client will fetch the style sheet through another connection
- it gets the main thread out of the accept() state and should thus
- trigger the actual shutdown.
- </para>
- </listitem>
- <listitem>
- <para>
- Add a proper CGI message for cgi_die().
- </para>
- </listitem>
- <listitem>
- <para>
- Don't enforce a logical line length limit in read_config_line().
- </para>
- </listitem>
- <listitem>
- <para>
- Slightly refactor server_last_modified() to remove useless gmtime*() calls.
- </para>
- </listitem>
- <listitem>
- <para>
- In get_content_type(), also recognize '.jpeg' as JPEG extension.
- </para>
- </listitem>
- <listitem>
- <para>
- Add '.png' to the list of recognized file extensions in get_content_type().
- </para>
- </listitem>
- <listitem>
- <para>
- In block_url(), consistently use the block reason "Request blocked by Privoxy"
- In two places the reason was "Request for blocked URL" which hides the
- fact that the request got blocked by Privoxy and isn't necessarily
- correct as the block may be due to tags.
- </para>
- </listitem>
- <listitem>
- <para>
- In listen_loop(), reload the configuration files after accepting
- a new connection instead of before.
- Previously the first connection that arrived after a configuration
- change would still be handled with the old configuration.
- </para>
- </listitem>
- <listitem>
- <para>
- In chat()'s receive-data loop, skip a client socket check if
- the socket will be written to right away anyway. This can
- increase the transfer speed for unfiltered content on fast
- network connections.
- </para>
- </listitem>
- <listitem>
- <para>
- The socket timeout is used for SOCKS negotiations as well which
- previously couldn't timeout.
- </para>
- </listitem>
- <listitem>
- <para>
- Don't keep the client connection alive if any configuration file
- changed since the time the connection came in. This is closer to
- Privoxy's behaviour before keep-alive support for client connection
- has been added and also less confusing in general.
- </para>
- </listitem>
- <listitem>
- <para>
- Treat all Content-Type header values containing the pattern
- 'script' as a sign of text. Reported by pribog in #3134970.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- Action file improvements:
- <itemizedlist>
- <listitem>
- <para>
- Moved the site-specific block pattern section below the one for the
- generic patterns so for requests that are matched in both, the block
- reason for the domain is shown which is usually more useful than showing
- the one for the generic pattern.
- </para>
- </listitem>
- <listitem>
- <para>
- Remove -prevent-compression from the fragile alias. It's no longer
- used anywhere by default and isn't known to break stuff anyway.
- </para>
- </listitem>
- <listitem>
- <para>
- Add a (disabled) section to block various Facebook tracking URLs.
- Reported by Dan Stahlke in #3421764.
- </para>
- </listitem>
- <listitem>
- <para>
- Add a (disabled) section to rewrite and redirect click-tracking
- URLs used on news.google.com.
- Reported by Dan Stahlke in #3421755.
- </para>
- </listitem>
- <listitem>
- <para>
- Unblock linuxcounter.net/.
- Reported by Dan Stahlke in #3422612.
- </para>
- </listitem>
- <listitem>
- <para>
- Block 'www91.intel.com/' which is used by Omniture.
- Reported by Adam Piggott in #3167370.
- </para>
- </listitem>
- <listitem>
- <para>
- Disable the handle-as-empty-doc-returns-ok option and mark it as deprecated.
- Reminded by tceverling in #2790091.
- </para>
- </listitem>
- <listitem>
- <para>
- Add ".ivwbox.de/" to the "Cross-site user tracking" section.
- Reported by Nettozahler in #3172525.
- </para>
- </listitem>
- <listitem>
- <para>
- Unblock and fast-redirect ".awin1.com/.*=http://".
- Reported by Adam Piggott in #3170921.
- </para>
- </listitem>
- <listitem>
- <para>
- Block "b.collective-media.net/".
- </para>
- </listitem>
- <listitem>
- <para>
- Widen the Debian popcon exception to "qa.debian.org/popcon".
- Seen in Debian's 05_default_action.dpatch by Roland Rosenfeld.
- </para>
- </listitem>
- <listitem>
- <para>
- Block ".gemius.pl/" which only seems to be used for user tracking.
- Reported by johnd16 in #3002731. Additional input from Lee and movax.
- </para>
- </listitem>
- <listitem>
- <para>
- Disable banners-by-size filters for '.thinkgeek.com/'.
- The filter only seems to catch pictures of the inventory.
- </para>
- </listitem>
- <listitem>
- <para>
- Block requests for 'go.idmnet.bbelements.com/please/showit/'.
- Reported by kacperdominik in #3372959.
- </para>
- </listitem>
- <listitem>
- <para>
- Unblock adainitiative.org/.
- </para>
- </listitem>
- <listitem>
- <para>
- Add a fast-redirects exception for '.googleusercontent.com/.*=cache'.
- </para>
- </listitem>
- <listitem>
- <para>
- Add a fast-redirects exception for webcache.googleusercontent.com/.
- </para>
- </listitem>
- <listitem>
- <para>
- Unblock http://adassier.wordpress.com/ and http://adassier.files.wordpress.com/.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- Filter file improvements:
- <itemizedlist>
- <listitem>
- <para>
- Let the yahoo filter hide '.ads'.
- </para>
- </listitem>
- <listitem>
- <para>
- Let the msn filter hide overlay ads for Facebook 'likes' in search
- results and elements with the id 's_notf_div'. They only seem to be
- used to advertise site 'enhancements'.
- </para>
- </listitem>
- <listitem>
- <para>
- Let the js-events filter additionally disarm setInterval().
- Suggested by dg1727 in #3423775.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- Documentation improvements:
- <itemizedlist>
- <listitem>
- <para>
- Clarify the effect of compiling Privoxy with zlib support.
- Suggested by dg1727 in #3423782.
- </para>
- </listitem>
- <listitem>
- <para>
- Point out that the SourceForge messaging system works like a black
- hole and should thus not be used to contact individual developers.
- </para>
- </listitem>
- <listitem>
- <para>
- Mention some of the problems one can experience when not explicitly
- configuring an IP addresses as listen address.
- </para>
- </listitem>
- <listitem>
- <para>
- Explicitly mention that hostnames can be used instead of IP addresses
- for the listen-address, that only the first address returned will be
- used and what happens if the address is invalid.
- Requested by Calestyo in #3302213.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- Log message improvements:
- <itemizedlist>
- <listitem>
- <para>
- If only the server connection is kept alive, do not pretend to
- wait for a new client request.
- </para>
- </listitem>
- <listitem>
- <para>
- Remove a superfluous log message in forget_connection().
- </para>
- </listitem>
- <listitem>
- <para>
- In chat(), properly report missing server responses as such
- instead of calling them empty.
- </para>
- </listitem>
- <listitem>
- <para>
- In forwarded_connect(), fix a log message nobody should ever see.
- </para>
- </listitem>
- <listitem>
- <para>
- Fix a log message in socks5_connect(), a failed write operation
- was logged as failed read operation.
- </para>
- </listitem>
- <listitem>
- <para>
- Let load_one_actions_file() properly complain about a missing
- '{' at the beginning of the file.
- Simply stating that a line is invalid isn't particularly helpful.
- </para>
- </listitem>
- <listitem>
- <para>
- Do not claim to listen on a socket until Privoxy actually does.
- Patch submitted by Petr Pisar #3354485
- </para>
- </listitem>
- <listitem>
- <para>
- Prevent a duplicated LOG_LEVEL_CLF message when sending out
- the "no-server-data" response.
- </para>
- </listitem>
- <listitem>
- <para>
- Also log the client socket when dropping a connection.
- </para>
- </listitem>
- <listitem>
- <para>
- Include the destination host in the 'Request ... marked for
- blocking. limit-connect{...} doesn't allow CONNECT ...' message
- Patch submitted by Saperski in #3296250.
- </para>
- </listitem>
- <listitem>
- <para>
- Prevent a duplicated log message if none of the resolved IP
- addresses were reachable.
- </para>
- </listitem>
- <listitem>
- <para>
- In connect_to(), do not pretend to retry if forwarded-connect-retries
- is zero or unset.
- </para>
- </listitem>
- <listitem>
- <para>
- When a specified user or group can't be found, put the name in
- single-quotes when logging it.
- </para>
- </listitem>
- <listitem>
- <para>
- In rfc2553_connect_to(), explain getnameinfo() errors better.
- </para>
- </listitem>
- <listitem>
- <para>
- Remove a useless log message in chat().
- </para>
- </listitem>
- <listitem>
- <para>
- When retrying to connect, also log the maximum number of connection
- attempts.
- </para>
- </listitem>
- <listitem>
- <para>
- Rephrase a log message in compile_dynamic_pcrs_job_list().
- Divide the error code and its meaning with a colon. Call the pcrs
- job dynamic and not the filter. Filters may contain dynamic and
- non-dynamic pcrs jobs at the same time. Only mention the name of
- the filter or tagger, but don't claim it's a filter when it could
- be a tagger.
- </para>
- </listitem>
- <listitem>
- <para>
- In a fatal error message in load_one_actions_file(), cover both
- URL and TAG patterns.
- </para>
- </listitem>
- <listitem>
- <para>
- In pcrs_strerror(), properly report unknown positive error code
- values as such. Previously they were handled like 0 (no error).
- </para>
- </listitem>
- <listitem>
- <para>
- In compile_dynamic_pcrs_job_list(), also log the actual error code as
- pcrs_strerror() doesn't handle all errors reported by pcre.
- </para>
- </listitem>
- <listitem>
- <para>
- Don't bother trying to continue chatting if the client didn't ask for it.
- Reduces log noise a bit.
- </para>
- </listitem>
- <listitem>
- <para>
- Make two fatal error message in load_one_actions_file() more descriptive.
- </para>
- </listitem>
- <listitem>
- <para>
- In cgi_send_user_manual(), log when rejecting a file name due to '/' or '..'.
- </para>
- </listitem>
- <listitem>
- <para>
- In load_file(), log a message if opening a file failed.
- The CGI error message alone isn't too helpful.
- </para>
- </listitem>
- <listitem>
- <para>
- In connection_destination_matches(), improve two log messages
- to help understand why the destinations don't match.
- </para>
- </listitem>
- <listitem>
- <para>
- Rephrase a log message in serve(). Client request arrival
- should be differentiated from closed client connections now.
- </para>
- </listitem>
- <listitem>
- <para>
- In serve(), log if a client connection isn't reused due to a
- configuration file change.
- </para>
- </listitem>
- <listitem>
- <para>
- Let mark_server_socket_tainted() always mark the server socket tainted,
- just don't talk about it in cases where it has no effect. It doesn't change
- Privoxy's behaviour, but makes understanding the log file easier.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- configure:
- <itemizedlist>
- <listitem>
- <para>
- Added a --disable-ipv6-support switch for platforms where support
- is detected but doesn't actually work.
- </para>
- </listitem>
- <listitem>
- <para>
- Do not check for the existence of strerror() and memmove() twice
- </para>
- </listitem>
- <listitem>
- <para>
- Remove a useless test for setpgrp(2). Privoxy doesn't need it and
- it can cause problems when cross-compiling.
- </para>
- </listitem>
- <listitem>
- <para>
- Rename the --disable-acl-files switch to --disable-acl-support.
- Since about 2001, ACL directives are specified in the standard
- config file.
- </para>
- </listitem>
- <listitem>
- <para>
- Update the URL of the 'Removing outdated PCRE version after the
- next stable release' posting. The old URL stopped working after
- one of SF's recent site "optimizations". Reported by Han Liu.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- Privoxy-Regression-Test:
- <itemizedlist>
- <listitem>
- <para>
- Added --shuffle-tests option to increase the chances of detection race conditions.
- </para>
- </listitem>
- <listitem>
- <para>
- Added a --local-test-file option that allows to use Privoxy-Regression-Test without Privoxy.
- </para>
- </listitem>
- <listitem>
- <para>
- Added tests for missing socks4 and socks4a forwarders.
- </para>
- </listitem>
- <listitem>
- <para>
- The --privoxy-address option now works with IPv6 addresses containing brackets, too.
- </para>
- </listitem>
- <listitem>
- <para>
- Perform limited sanity checks for parameters that are supposed to have numerical values.
- </para>
- </listitem>
- <listitem>
- <para>
- Added a --sleep-time option to specify a number of seconds to
- sleep between tests, defaults to 0.
- </para>
- </listitem>
- <listitem>
- <para>
- Disable the range-requests tagger for tests that break if it's enabled.
- </para>
- </listitem>
- <listitem>
- <para>
- Log messages use the ISO 8601 date format %Y-%m-%d.
- </para>
- </listitem>
- <listitem>
- <para>
- Fix spelling in two error messages.
- </para>
- </listitem>
- <listitem>
- <para>
- In the --help output, include a list of supported tests and their default levels.
- </para>
- </listitem>
- <listitem>
- <para>
- Adjust the tests to properly deal with FEATURE_TOGGLE being disabled.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- Privoxy-Log-Parser:
- <itemizedlist>
- <listitem>
- <para>
- Perform limited sanity checks for command line parameters that
- are supposed to have numerical values.
- </para>
- </listitem>
- <listitem>
- <para>
- Implement a --unbreak-lines-only option to try to revert MUA breakage.
- </para>
- </listitem>
- <listitem>
- <para>
- Accept and highlight: Added header: Content-Encoding: deflate
- </para>
- </listitem>
- <listitem>
- <para>
- Accept and highlight: Compressed content from 29258 to 8630 bytes.
- </para>
- </listitem>
- <listitem>
- <para>
- Accept and highlight: Client request arrived in time on socket 21.
- </para>
- </listitem>
- <listitem>
- <para>
- Highlight: Didn't receive data in time: a.fsdn.com:443
- </para>
- </listitem>
- <listitem>
- <para>
- Accept log messages with ISO 8601 time stamps, too.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- uagen:
- <itemizedlist>
- <listitem>
- <para>
- Bump generated Firefox version to 8.0.
- </para>
- </listitem>
- <listitem>
- <para>
- Only randomize the release date if the new --randomize-release-date
- option is enabled. Firefox versions after 4 use a fixed date string
- without meaning.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- </itemizedlist>
-</para>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-
-<sect2 id="upgradersnote">
-<title>Note to Upgraders</title>
-
-<para>
- A quick list of things to be aware of before upgrading from earlier
- versions of <application>Privoxy</application>:
-</para>
-
-<para>
- <itemizedlist>
-
- <listitem>
- <para>
- The recommended way to upgrade &my-app; is to backup your old
- configuration files, install the new ones, verify that &my-app;
- is working correctly and finally merge back your changes using
- <application>diff</application> and maybe <application>patch</application>.
- </para>
- <para>
- There are a number of new features in each &my-app; release and
- most of them have to be explicitly enabled in the configuration
- files. Old configuration files obviously don't do that and due
- to syntax changes using old configuration files with a new
- &my-app; isn't always possible anyway.
- </para>
- </listitem>
- <listitem>
- <para>
- Note that some installers remove earlier versions completely,
- including configuration files, therefore you should really save
- any important configuration files!
- </para>
- </listitem>
- <listitem>
- <para>
- On the other hand, other installers don't overwrite existing configuration
- files, thinking you will want to do that yourself.
- </para>
- </listitem>
- <listitem>
- <para>
- <filename>standard.action</filename> has been merged into
- the <filename>default.action</filename> file.
- </para>
- </listitem>
- <listitem>
- <para>
- In the default configuration only fatal errors are logged now.
- You can change that in the <link linkend="DEBUG">debug section</link>
- of the configuration file. You may also want to enable more verbose
- logging until you verified that the new &my-app; version is working
- as expected.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Three other config file settings are now off by default:
- <link linkend="enable-remote-toggle">enable-remote-toggle</link>,
- <link linkend="enable-remote-http-toggle">enable-remote-http-toggle</link>,
- and <link linkend="enable-edit-actions">enable-edit-actions</link>.
- If you use or want these, you will need to explicitly enable them, and
- be aware of the security issues involved.
- </para>
- </listitem>
-
-<!--
- <listitem>
- <para>
- What constitutes a <quote>default</quote> configuration has changed,
- and you may want to review which actions are <quote>on</quote> by
- default. This is primarily a matter of emphasis, but some features
- you may have been used to, may now be <quote>off</quote> by default.
- There are also a number of new actions and filters you may want to
- consider, most of which are not fully incorporated into the default
- settings as yet (see above).
- </para>
- </listitem>
--->
-<!--
- <listitem>
- <para>
- The default actions setting is now <literal>Cautious</literal>. Previous
- releases had a default setting of <literal>Medium</literal>. Experienced
- users may want to adjust this, as it is fairly conservative by &my-app;
- standards and past practices. See <ulink
- url="http://config.privoxy.org/edit-actions-list?f=default">
- http://config.privoxy.org/edit-actions-list?f=default</ulink>. New users
- should try the default settings for a while before turning up the volume.
- </para>
- </listitem>
-
- <listitem>
- <para>
- The default setting has filtering turned <emphasis>off</emphasis>, which
- subsequently means that compression is <emphasis>on</emphasis>. Remember
- that filtering does not work on compressed pages, so if you use, or want to
- use, filtering, you will need to force compression off. Example:
- </para>
- <para>
- <screen>
- { +<link linkend="filter">filter</link>{google} +<link linkend="prevent-compression">prevent-compression</link> }
- .google.</screen>
- </para>
- <para>
- Or if you use a number of filters, or filter many sites, you may just want
- to turn off compression for all sites in
- <filename>default.action</filename> (or
- <filename>user.action</filename>).
- </para>
-
- </listitem>
-
- <listitem>
- <para>
- Also, <link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> is
- off by default now. If you've liked this feature in the past, you may want
- to turn it back on in <filename>user.action</filename> now.
- </para>
- </listitem>
-
-
- <listitem>
- <para>
- Some installers may not automatically start
- <application>Privoxy</application> after installation.
- </para>
- </listitem>
--->
-
- </itemizedlist>
-</para>
-
-</sect2>
-</sect1>
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="quickstart"><title>Quickstart to Using Privoxy</title>
-<para>
- <itemizedlist>
-
- <listitem>
- <para>
- Install <application>Privoxy</application>. See the <link
- linkend="installation">Installation Section</link> below for platform specific
- information.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Advanced users and those who want to offer <application>Privoxy</application>
- service to more than just their local machine should check the <link
- linkend="config">main config file</link>, especially the <link
- linkend="access-control">security-relevant</link> options. These are
- off by default.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Start <application>Privoxy</application>, if the installation program has
- not done this already (may vary according to platform). See the section
- <link linkend="startup">Starting <application>Privoxy</application></link>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Set your browser to use <application>Privoxy</application> as HTTP and
- HTTPS (SSL) <ulink url="http://en.wikipedia.org/wiki/Proxy_server">proxy</ulink>
- by setting the proxy configuration for address of
- <literal>127.0.0.1</literal> and port <literal>8118</literal>.
- <emphasis>DO NOT</emphasis> activate proxying for <literal>FTP</literal> or
- any protocols besides HTTP and HTTPS (SSL) unless you intend to prevent your
- browser from using these protocols.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Flush your browser's disk and memory caches, to remove any cached ad images.
- If using <application>Privoxy</application> to manage
- <ulink url="http://en.wikipedia.org/wiki/Browser_cookie">cookies</ulink>,
- you should remove any currently stored cookies too.
- </para>
- </listitem>
-
- <listitem>
- <para>
- A default installation should provide a reasonable starting point for
- most. There will undoubtedly be occasions where you will want to adjust the
- configuration, but that can be dealt with as the need arises. Little
- to no initial configuration is required in most cases, you may want
- to enable the
- <ulink url="config.html#ENABLE-EDIT-ACTIONS">web-based action editor</ulink> though.
- Be sure to read the warnings first.
- </para>
- <para>
- See the <link linkend="configuration">Configuration section</link> for more
- configuration options, and how to customize your installation.
- You might also want to look at the <link
- linkend="quickstart-ad-blocking">next section</link> for a quick
- introduction to how <application>Privoxy</application> blocks ads and
- banners.
-</para>
- </listitem>
-
- <listitem>
- <para>
- If you experience ads that slip through, innocent images that are
- blocked, or otherwise feel the need to fine-tune
- <application>Privoxy's</application> behavior, take a look at the <link
- linkend="actions-file">actions files</link>. As a quick start, you might
- find the <link linkend="act-examples">richly commented examples</link>
- helpful. You can also view and edit the actions files through the <ulink
- url="http://config.privoxy.org">web-based user interface</ulink>. The
- Appendix <quote><link linkend="actionsanat">Troubleshooting: Anatomy of an
- Action</link></quote> has hints on how to understand and debug actions that
- <quote>misbehave</quote>.
- </para>
- </listitem>
-
-<!--
- Did anyone test these lately?
- fk 2007-11-10
- <listitem>
- <para>
- For easy access to &my-app;'s most important controls, drag the provided
- <link linkend="bookmarklets">Bookmarklets</link> into your browser's
- personal toolbar.
- </para>
- </listitem>
--->
-
- <listitem>
- <para>
- Please see the section <link linkend="contact">Contacting the
- Developers</link> on how to report bugs, problems with websites or to get
- help.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Now enjoy surfing with enhanced control, comfort and privacy!
- </para>
- </listitem>
-
- </itemizedlist>
-</para>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-
-<sect2 id="quickstart-ad-blocking">
-<title>Quickstart to Ad Blocking</title>
-<!--
- NOTE: This section is deliberately redundant for those that don't
- want to read the whole thing (which is getting lengthy).
--->
-<para>
- Ad blocking is but one of <application>Privoxy's</application>
- array of features. Many of these features are for the technically minded advanced
- user. But, ad and banner blocking is surely common ground for everybody.
-</para>
-<para>
- This section will provide a quick summary of ad blocking so
- you can get up to speed quickly without having to read the more extensive
- information provided below, though this is highly recommended.
-</para>
-<para>
- First a bit of a warning ... blocking ads is much like blocking SPAM: the
- more aggressive you are about it, the more likely you are to block
- things that were not intended. And the more likely that some things
- may not work as intended. So there is a trade off here. If you want
- extreme ad free browsing, be prepared to deal with more
- <quote>problem</quote> sites, and to spend more time adjusting the
- configuration to solve these unintended consequences. In short, there is
- not an easy way to eliminate <emphasis>all</emphasis> ads. Either take
- the easy way and settle for <emphasis>most</emphasis> ads blocked with the
- default configuration, or jump in and tweak it for your personal surfing
- habits and preferences.
-</para>
-<para>
- Secondly, a brief explanation of <application>Privoxy's </application>
- <quote>actions</quote>. <quote>Actions</quote> in this context, are
- the directives we use to tell <application>Privoxy</application> to perform
- some task relating to HTTP transactions (i.e. web browsing). We tell
- <application>Privoxy</application> to take some <quote>action</quote>. Each
- action has a unique name and function. While there are many potential
- <application>actions</application> in <application>Privoxy's</application>
- arsenal, only a few are used for ad blocking. <link
- linkend="actions">Actions</link>, and <link linkend="actions-file">action
- configuration files</link>, are explained in depth below.
-</para>
-<para>
- Actions are specified in <application>Privoxy's</application> configuration,
- followed by one or more URLs to which the action should apply. URLs
- can actually be URL type <link linkend="af-patterns">patterns</link> that use
- wildcards so they can apply potentially to a range of similar URLs. The
- actions, together with the URL patterns are called a section.
-</para>
-<para>
- When you connect to a website, the full URL will either match one or more
- of the sections as defined in <application>Privoxy's</application> configuration,
- or not. If so, then <application>Privoxy</application> will perform the
- respective actions. If not, then nothing special happens. Furthermore, web
- pages may contain embedded, secondary URLs that your web browser will
- use to load additional components of the page, as it parses the
- original page's HTML content. An ad image for instance, is just an URL
- embedded in the page somewhere. The image itself may be on the same server,
- or a server somewhere else on the Internet. Complex web pages will have many
- such embedded URLs. &my-app; can deal with each URL individually, so, for
- instance, the main page text is not touched, but images from such-and-such
- server are blocked.
-</para>
-
-<para>
- The most important actions for basic ad blocking are: <literal><link
- linkend="block">block</link></literal>, <literal><link
- linkend="handle-as-image">handle-as-image</link></literal>,
- <literal><link
- linkend="handle-as-empty-document">handle-as-empty-document</link></literal>,and
- <literal><link linkend="set-image-blocker">set-image-blocker</link></literal>:
-</para>
-
-<para>
- <itemizedlist>
-
- <listitem>
- <para>
- <literal><link linkend="block">block</link></literal> - this is perhaps
- the single most used action, and is particularly important for ad blocking.
- This action stops any contact between your browser and any URL patterns
- that match this action's configuration. It can be used for blocking ads,
- but also anything that is determined to be unwanted. By itself, it simply
- stops any communication with the remote server and sends
- <application>Privoxy</application>'s own built-in BLOCKED page instead to
- let you now what has happened (with some exceptions, see below).
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal><link linkend="handle-as-image">handle-as-image</link></literal> -
- tells <application>Privoxy</application> to treat this URL as an image.
- <application>Privoxy</application>'s default configuration already does this
- for all common image types (e.g. GIF), but there are many situations where this
- is not so easy to determine. So we'll force it in these cases. This is particularly
- important for ad blocking, since only if we know that it's an image of
- some kind, can we replace it with an image of our choosing, instead of the
- <application>Privoxy</application> BLOCKED page (which would only result in
- a <quote>broken image</quote> icon). There are some limitations to this
- though. For instance, you can't just brute-force an image substitution for
- an entire HTML page in most situations.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal><link linkend="handle-as-empty-document">handle-as-empty-document</link></literal> -
- sends an empty document instead of <application>Privoxy's</application>
- normal BLOCKED HTML page. This is useful for file types that are neither
- HTML nor images, such as blocking JavaScript files.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal><link
- linkend="set-image-blocker">set-image-blocker</link></literal> - tells
- <application>Privoxy</application> what to display in place of an ad image that
- has hit a block rule. For this to come into play, the URL must match a
- <literal><link linkend="block">block</link></literal> action somewhere in the
- configuration, <emphasis>and</emphasis>, it must also match an
- <literal><link linkend="handle-as-image">handle-as-image</link></literal> action.
- </para>
- <para>
- The configuration options on what to display instead of the ad are:
- </para>
- <simplelist>
- <member>
- <emphasis>pattern</emphasis> - a checkerboard pattern, so that an ad
- replacement is obvious. This is the default.
- </member>
- </simplelist>
- <simplelist>
- <member>
- <emphasis>blank</emphasis> - A very small empty GIF image is displayed.
- This is the so-called <quote>invisible</quote> configuration option.
- </member>
- </simplelist>
- <simplelist>
- <member>
- <emphasis>http://<URL></emphasis> - A redirect to any image anywhere
- of the user's choosing (advanced usage).
- </member>
- </simplelist>
- </listitem>
-
-</itemizedlist>
-</para>
-
-<para>
- Advanced users will eventually want to explore &my-app;
- <literal><link linkend="filter">filters</link></literal> as well. Filters
- are very different from <literal><link
- linkend="block">blocks</link></literal>.
- A <quote>block</quote> blocks a site, page, or unwanted contented. Filters
- are a way of filtering or modifying what is actually on the page. An example
- filter usage: a text replacement of <quote>no-no</quote> for
- <quote>nasty-word</quote>. That is a very simple example. This process can be
- used for ad blocking, but it is more in the realm of advanced usage and has
- some pitfalls to be wary off.
-</para>
-
-<para>
- The quickest way to adjust any of these settings is with your browser through
- the special <application>Privoxy</application> editor at <ulink
- url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
- (shortcut: <ulink url="http://p.p/">http://p.p/show-status</ulink>). This
- is an internal page, and does not require Internet access.
-</para>
-
-<para>
- Note that as of <application>Privoxy</application> 3.0.7 beta the
- action editor is disabled by default. Check the
- <ulink url="config.html#ENABLE-EDIT-ACTIONS">enable-edit-actions
- section in the configuration file</ulink> to learn why and in which
- cases it's safe to enable again.
-</para>
-
-<para>
- If you decided to enable the action editor, select the appropriate
- <quote>actions</quote> file, and click
- <quote><guibutton>Edit</guibutton></quote>. It is best to put personal or
- local preferences in <filename>user.action</filename> since this is not
- meant to be overwritten during upgrades, and will over-ride the settings in
- other files. Here you can insert new <quote>actions</quote>, and URLs for ad
- blocking or other purposes, and make other adjustments to the configuration.
- <application>Privoxy</application> will detect these changes automatically.
-</para>
-
-<para>
- A quick and simple step by step example:
-</para>
-
-<para>
- <itemizedlist>
-
- <listitem>
- <para>
- Right click on the ad image to be blocked, then select
- <quote><guimenuitem>Copy Link Location</guimenuitem></quote> from the
- pop-up menu.
- </para>
- </listitem>
- <listitem>
- <para>
- Set your browser to
- <ulink
- url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
- </para>
- </listitem>
- <listitem>
- <para>
- Find <filename>user.action</filename> in the top section, and click
- on <quote><guibutton>Edit</guibutton></quote>:
- </para>
-
- <!-- image of editor and actions files selections -->
- <para>
- <figure pgwide="0" float="0"><title>Actions Files in Use</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="files-in-use.jpg" format="jpg">
- </imageobject>
- <textobject>
- <phrase>[ Screenshot of Actions Files in Use ]</phrase>
- </textobject>
- </mediaobject>
- </figure>
- </para>
- </listitem>
-
- <listitem>
- <para>
- You should have a section with only
- <literal><link linkend="block">block</link></literal> listed under
- <quote>Actions:</quote>.
- If not, click a <quote><guibutton>Insert new section below</guibutton></quote>
- button, and in the new section that just appeared, click the
- <guibutton>Edit</guibutton> button right under the word <quote>Actions:</quote>.
- This will bring up a list of all actions. Find
- <literal><link linkend="block">block</link></literal> near the top, and click
- in the <quote>Enabled</quote> column, then <quote><guibutton>Submit</guibutton></quote>
- just below the list.
- </para>
- </listitem>
- <listitem>
- <para>
- Now, in the <literal><link linkend="block">block</link></literal> actions section,
- click the <quote><guibutton>Add</guibutton></quote> button, and paste the URL the
- browser got from <quote><guimenuitem>Copy Link Location</guimenuitem></quote>.
- Remove the <literal>http://</literal> at the beginning of the URL. Then, click
- <quote><guibutton>Submit</guibutton></quote> (or
- <quote><guibutton>OK</guibutton></quote> if in a pop-up window).
- </para>
- </listitem>
- <listitem>
- <para>
- Now go back to the original page, and press <keycap>SHIFT-Reload</keycap>
- (or flush all browser caches). The image should be gone now.
- </para>
- </listitem>
-
- </itemizedlist>
-</para>
-
-<para>
- This is a very crude and simple example. There might be good reasons to use a
- wildcard pattern match to include potentially similar images from the same
- site. For a more extensive explanation of <quote>patterns</quote>, and
- the entire actions concept, see <link linkend="actions-file">the Actions
- section</link>.
-</para>
-
-<para>
- For advanced users who want to hand edit their config files, you might want
- to now go to the <link linkend="act-examples">Actions Files Tutorial</link>.
- The ideas explained therein also apply to the web-based editor.
-</para>
-<para>
- There are also various
- <link linkend="filter">filters</link> that can be used for ad blocking
- (filters are a special subset of actions). These
- fall into the <quote>advanced</quote> usage category, and are explained in
- depth in later sections.
-</para>
-
-</sect2>
-
-</sect1>
-
-<!-- ~ End section ~ -->
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="startup">
-<title>Starting Privoxy</title>
-<para>
- Before launching <application>Privoxy</application> for the first time, you
- will want to configure your browser(s) to use
- <application>Privoxy</application> as a HTTP and HTTPS (SSL)
- <ulink url="http://en.wikipedia.org/wiki/Proxy_server">proxy</ulink>. The default is
- 127.0.0.1 (or localhost) for the proxy address, and port 8118 (earlier versions
- used port 8000). This is the one configuration step <emphasis>that must be done
-</emphasis>!
-</para>
-<para>
- Please note that <application>Privoxy</application> can only proxy HTTP and
- HTTPS traffic. It will not work with FTP or other protocols.
-</para>
-
- <!-- image of Mozilla Proxy configuration -->
- <para>
- <figure pgwide="0" float="0"><title>Proxy Configuration Showing
- Mozilla/Netscape HTTP and HTTPS (SSL) Settings</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="proxy_setup.jpg" format="jpg">
- </imageobject>
- <textobject>
- <phrase>[ Screenshot of Mozilla Proxy Configuration ]</phrase>
- </textobject>
- </mediaobject>
- </figure>
- </para>
-
-
-<para>
- With <application>Firefox</application>, this is typically set under:
-</para>
-
-<literallayout>
- <guibutton>Tools</guibutton> -> <guibutton>Options</guibutton> -> <guibutton>Advanced</guibutton> -> <guibutton>Network</guibutton> -><guibutton>Connection</guibutton> -> <guibutton>Settings</guibutton>
-
-</literallayout>
-
-<para>
- Or optionally on some platforms:
-</para>
-
-<literallayout>
- <guibutton>Edit</guibutton> -> <guibutton>Preferences</guibutton> -> <guibutton>General</guibutton> -> <guibutton>Connection Settings</guibutton> -> <guibutton>Manual Proxy Configuration</guibutton>
-
-</literallayout>
-
-
-<para>
- With <application>Netscape</application> (and
- <application>Mozilla</application>), this can be set under:
-</para>
-
-
-<literallayout>
-<!-- Mix ascii and gui art, something for everybody -->
-<!-- spacing on this is tricky -->
- <guibutton>Edit</guibutton> -> <guibutton>Preferences</guibutton> -> <guibutton>Advanced</guibutton> -> <guibutton>Proxies</guibutton> -> <guibutton>HTTP Proxy</guibutton>
-
-</literallayout>
-
-<para>
- For <application>Internet Explorer v.5-7</application>:
-</para>
-
-<literallayout>
- <guibutton>Tools</guibutton> -> <guibutton>Internet Options</guibutton> -> <guibutton>Connections</guibutton> -> <guibutton>LAN Settings</guibutton>
-</literallayout>
-
-<para>
- Then, check <quote>Use Proxy</quote> and fill in the appropriate info
- (Address: 127.0.0.1, Port: 8118). Include HTTPS (SSL), if you want HTTPS
- proxy support too (sometimes labeled <quote>Secure</quote>). Make sure any
- checkboxes like <quote>Use the same proxy server for all protocols</quote> is
- <emphasis>UNCHECKED</emphasis>. You want only HTTP and HTTPS (SSL)!
-</para>
-
- <!-- image of IE Proxy configuration -->
- <para>
- <figure pgwide="0" float="0"><title>Proxy Configuration Showing
- Internet Explorer HTTP and HTTPS (Secure) Settings</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="proxy2.jpg" format="jpg">
- </imageobject>
- <textobject>
- <phrase>[ Screenshot of IE Proxy Configuration ]</phrase>
- </textobject>
- </mediaobject>
- </figure>
- </para>
-
-
-<para>
- 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. Remove
- any <ulink url="http://en.wikipedia.org/wiki/Browser_cookie">cookies</ulink>,
- if you want <application>Privoxy</application> to manage that. You are now
- ready to start enjoying the benefits of using
- <application>Privoxy</application>!
-</para>
-
-<para>
- <application>Privoxy</application> itself is typically started by specifying the
- main configuration file to be used on the command line. If no configuration
- file is specified on the command line, <application>Privoxy</application>
- will look for a file named <filename>config</filename> in the current
- directory. Except on Win32 where it will try <filename>config.txt</filename>.
-</para>
-
-<sect2 id="start-redhat">
-<title>Red Hat and Fedora</title>
-<para>
- A default Red Hat installation may not start &my-app; upon boot. It will use
- the file <filename>/etc/privoxy/config</filename> as its main configuration
- file.
-</para>
-<para>
- <screen>
- # /etc/rc.d/init.d/privoxy start
-</screen>
-</para>
-<para>
- Or ...
-</para>
-<para>
- <screen>
- # service privoxy start
-</screen>
-</para>
-</sect2>
-
-<sect2 id="start-debian">
-<title>Debian</title>
-<para>
- We use a script. Note that Debian typically starts &my-app; upon booting per
- default. It will use the file
- <filename>/etc/privoxy/config</filename> as its main configuration
- file.
-</para>
-<para>
- <screen>
- # /etc/init.d/privoxy start
-</screen>
-</para>
-</sect2>
-
-<sect2 id="start-windows">
-<title>Windows</title>
-<para>
-Click on the &my-app; Icon to start <application>Privoxy</application>. If no configuration file is
- specified on the command line, <application>Privoxy</application> will look
- for a file named <filename>config.txt</filename>. Note that Windows will
- automatically start &my-app; when the system starts if you chose that option
- when installing.
-</para>
-<para>
- <application>Privoxy</application> can run with full Windows service functionality.
- On Windows only, the &my-app; program has two new command line arguments
- to install and uninstall &my-app; as a service. See the
- <link linkend="installation-pack-win">Windows Installation
- instructions</link> for details.
-</para>
-</sect2>
-
-<sect2 id="start-unices">
-<title>Solaris, NetBSD, FreeBSD, HP-UX and others</title>
-<para>
-Example Unix startup command:
-</para>
-<para>
- <screen>
- # /usr/sbin/privoxy /etc/privoxy/config
-</screen>
-</para>
-</sect2>
-
-<sect2 id="start-os2">
-<title>OS/2</title>
-<para>
- During installation, <application>Privoxy</application> is configured to
- start automatically when the system restarts. You can start it manually by
- double-clicking on the <application>Privoxy</application> icon in the
- <application>Privoxy</application> folder.
-</para>
-</sect2>
-
-<sect2 id="start-macosx">
-<title>Mac OS X</title>
-<para>
- 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.
-</para>
-<para>
- The privoxy service will automatically start after a successful
- installation. In addition, the privoxy service will automatically
- start every time your computer starts up.
-</para>
-<para>
- To prevent the privoxy service from automatically starting when your
- computer starts up, remove or rename the folder named
- /Library/StartupItems/Privoxy.
-</para>
-<para>
- A simple application named Privoxy Utility has been created which
- enables administrators to easily start and stop the privoxy service.
-</para>
-<para>
- 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.
-</para>
-<para>
- An administrator username and password must be supplied in order for
- the Privoxy Utility to perform any of the tasks.
-</para>
-</sect2>
-
-
-<sect2 id="start-amigaos">
-<title>AmigaOS</title>
-<para>
- Start <application>Privoxy</application> (with RUN <>NIL:) in your
- <filename>startnet</filename> script (AmiTCP), in
- <filename>s:user-startup</filename> (RoadShow), as startup program in your
- startup script (Genesis), or as startup action (Miami and MiamiDx).
- <application>Privoxy</application> will automatically quit when you quit your
- TCP/IP stack (just ignore the harmless warning your TCP/IP stack may display that
- <application>Privoxy</application> is still running).
-</para>
-</sect2>
-
-<sect2 id="start-gentoo">
-<title>Gentoo</title>
-<para>
- A script is again used. It will use the file <filename>/etc/privoxy/config
- </filename> as its main configuration file.
-</para>
-<para>
- <screen>
- /etc/init.d/privoxy start
- </screen>
-</para>
-<para>
- Note that <application>Privoxy</application> is not automatically started at
- boot time by default. You can change this with the <literal>rc-update</literal>
- command.
-</para>
-<para>
- <screen>
- rc-update add privoxy default
- </screen>
-</para>
-</sect2>
-
-<!--
-
-<para>
- See the section <link linkend="cmdoptions">Command line options</link> for
- further info.
-</para>
-
-must find a better place for this paragraph
-
-<para>
- The included default configuration files should give a reasonable starting
- point. Most of the per site configuration is done in the
- <ulink url="actions-file.html"><quote>actions</quote></ulink> files. These are
- where various cookie actions are defined, ad and banner blocking, and other
- aspects of <application>Privoxy</application> configuration. There are several
- such files included, with varying levels of aggressiveness.
-</para>
-
-<para>
- You will probably want to keep an eye out for sites for which you may prefer
- persistent cookies, and add these to your actions configuration as needed. By
- default, most of these will be accepted only during the current browser
- session (aka <quote>session cookies</quote>), unless you add them to the
- configuration. If you want the browser to handle this instead, you will need
- to edit <filename>user.action</filename> (or through the web based interface)
- and disable this feature. If you use more than one browser, it would make
- more sense to let <application>Privoxy</application> handle this. In which
- case, the browser(s) should be set to accept all cookies.
-</para>
-
-<para>
- Another feature where you will probably want to define exceptions for trusted
- sites is the popup-killing (through <ulink
- url="actions-file.html#FILTER-POPUPS"><quote>+filter{popups}</quote></ulink>),
- because your favorite shopping, banking, or leisure site may need
- popups (explained below).
-</para>
-
-<para>
- <application>Privoxy</application> does not support all of the optional HTTP/1.1
- features yet. In the unlikely event that you experience inexplicable problems
- with browsers that use HTTP/1.1 per default
- (like <application>Mozilla</application> or recent versions of I.E.), you might
- try to force HTTP/1.0 compatibility. For Mozilla, look under <literal>Edit ->
- Preferences -> Debug -> Networking</literal>.
- Alternatively, set the <quote>+downgrade-http-version</quote> config option in
- <filename>default.action</filename> which will downgrade your browser's HTTP
- requests from HTTP/1.1 to HTTP/1.0 before processing them.
-</para>
-
-<para>
- After running <application>Privoxy</application> for a while, you can
- start to fine tune the configuration to suit your personal, or site,
- preferences and requirements. There are many, many aspects that can
- be customized. <quote>Actions</quote>
- can be adjusted by pointing your browser to
- <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
- (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>),
- and then follow the link to <quote>View & Change the Current Configuration</quote>.
- (This is an internal page and does not require Internet access.)
-</para>
-
-<para>
- In fact, various aspects of <application>Privoxy</application>
- configuration can be viewed from this page, including
- current configuration parameters, source code version numbers,
- the browser's request headers, and <quote>actions</quote> that apply
- to a given URL. In addition to the actions file
- editor mentioned above, <application>Privoxy</application> can also
- be turned <quote>on</quote> and <quote>off</quote> (toggled) from this page.
-</para>
-
-<para>
- If you encounter problems, try loading the page without
- <application>Privoxy</application>. If that helps, enter the URL where
- you have the problems into <ulink url="http://p.p/show-url-info">the browser
- based rule tracing utility</ulink>. See which rules apply and why, and
- then try turning them off for that site one after the other, until the problem
- is gone. When you have found the culprit, you might want to turn the rest on
- again.
-</para>
-
-<para>
- If the above paragraph sounds gibberish to you, you might want to <link
- linkend="actions-file">read more about the actions concept</link>
- or even dive deep into the <link linkend="actionsanat">Appendix
- on actions</link>.
-</para>
-
-<para>
- If you can't get rid of the problem at all, think you've found a bug in
- Privoxy, want to propose a new feature or smarter rules, please see the
- section <link linkend="contact"><quote>Contacting the
- Developers</quote></link> below.
-</para>
-
--->
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="cmdoptions">
-<title>Command Line Options</title>
-<para>
- <application>Privoxy</application> may be invoked with the following
- command-line options:
-</para>
-
-<para>
- <itemizedlist>
-
- <listitem>
- <para>
- <emphasis>--config-test</emphasis>
- </para>
- <para>
- Exit after loading the configuration files before binding to
- the listen address. The exit code signals whether or not the
- configuration files have been successfully loaded.
- </para>
- <para>
- If the exit code is 1, at least one of the configuration files
- is invalid, if it is 0, all the configuration files have been
- successfully loaded (but may still contain errors that can
- currently only be detected at run time).
- </para>
- <para>
- This option doesn't affect the log setting, combination with
- <emphasis>--no-daemon</emphasis> is recommended if a configured
- log file shouldn't be used.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>--version</emphasis>
- </para>
- <para>
- Print version info and exit. Unix only.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>--help</emphasis>
- </para>
- <para>
- Print short usage info and exit. Unix only.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>--no-daemon</emphasis>
- </para>
- <para>
- Don't become a daemon, i.e. don't fork and become process group
- leader, and don't detach from controlling tty. Unix only.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>--pidfile FILE</emphasis>
- </para>
- <para>
- On startup, write the process ID to <emphasis>FILE</emphasis>. Delete the
- <emphasis>FILE</emphasis> on exit. Failure to create or delete the
- <emphasis>FILE</emphasis> is non-fatal. If no <emphasis>FILE</emphasis>
- option is given, no PID file will be used. Unix only.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>--user USER[.GROUP]</emphasis>
- </para>
- <para>
- After (optionally) writing the PID file, assume the user ID of
- <emphasis>USER</emphasis>, and if included the GID of GROUP. Exit if the
- privileges are not sufficient to do so. Unix only.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>--chroot</emphasis>
- </para>
- <para>
- Before changing to the user ID given in the <emphasis>--user</emphasis> option,
- chroot to that user's home directory, i.e. make the kernel pretend to the &my-app;
- process that the directory tree starts there. If set up carefully, this can limit
- the impact of possible vulnerabilities in &my-app; to the files contained in that hierarchy.
- Unix only.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>--pre-chroot-nslookup hostname</emphasis>
- </para>
- <para>
- Specifies a hostname to look up before doing a chroot. On some systems, initializing the
- resolver library involves reading config files from /etc and/or loading additional shared
- libraries from /lib. On these systems, doing a hostname lookup before the chroot reduces
- the number of files that must be copied into the chroot tree.
- </para>
- <para>
- For fastest startup speed, a good value is a hostname that is not in /etc/hosts but that
- your local name server (listed in /etc/resolv.conf) can resolve without recursion
- (that is, without having to ask any other name servers). The hostname need not exist,
- but if it doesn't, an error message (which can be ignored) will be output.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <emphasis>configfile</emphasis>
- </para>
- <para>
- If no <emphasis>configfile</emphasis> is included on the command line,
- <application>Privoxy</application> will look for a file named
- <quote>config</quote> in the current directory (except on Win32
- where it will look for <quote>config.txt</quote> instead). Specify
- full path to avoid confusion. If no config file is found,
- <application>Privoxy</application> will fail to start.
- </para>
- </listitem>
-
- </itemizedlist>
-</para>
-
-<para>
- On <application>MS Windows</application> only there are two additional
- command-line options to allow <application>Privoxy</application> to install and
- run as a <emphasis>service</emphasis>. See the
-<link linkend="installation-pack-win">Window Installation section</link>
-for details.
-</para>
-
-</sect2>
-
-</sect1>
-
-<!-- ~ End section ~ -->
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="configuration"><title>Privoxy Configuration</title>
- <para>
- All <application>Privoxy</application> configuration is stored
- in text files. These files can be edited with a text editor.
- Many important aspects of <application>Privoxy</application> can
- also be controlled easily with a web browser.
- </para>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-
-<sect2>
-<title>Controlling Privoxy with Your Web Browser</title>
-<para>
- <application>Privoxy</application>'s user interface can be reached through the special
- URL <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
- (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>),
- which is a built-in page and works without Internet access.
- You will see the following section:
-
-</para>
-
-<!-- Needs to be put in a table and colorized -->
-<screen>
- <msgtext>
- <bridgehead renderas="sect2"> Privoxy Menu</bridgehead>
-
- <simplelist>
- <member>
- ▪ <ulink url="http://config.privoxy.org/show-status">View & change the current configuration</ulink>
- </member>
- <member>
- ▪ <ulink url="http://config.privoxy.org/show-version">View the source code version numbers</ulink>
- </member>
- <member>
- ▪ <ulink url="http://config.privoxy.org/show-request">View the request headers.</ulink>
- </member>
- <member>
- ▪ <ulink url="http://config.privoxy.org/show-url-info">Look up which actions apply to a URL and why</ulink>
- </member>
- <member>
- ▪ <ulink url="http://config.privoxy.org/toggle">Toggle Privoxy on or off</ulink>
- </member>
- <member>
- ▪ <ulink
- url="http://www.privoxy.org/&p-version;/user-manual/">Documentation</ulink>
- </member>
- </simplelist>
- </msgtext>
-</screen>
-
-
-<para>
- This should be self-explanatory. Note the first item leads to an editor for the
- <link linkend="actions-file">actions files</link>, which is where the ad, banner,
- cookie, and URL blocking magic is configured as well as other advanced features of
- <application>Privoxy</application>. This is an easy way to adjust various
- aspects of <application>Privoxy</application> configuration. The actions
- file, and other configuration files, are explained in detail below.
-</para>
-
-<para>
- <quote>Toggle Privoxy On or Off</quote> is handy for sites that might
- have problems with your current actions and filters. You can in fact use
- it as a test to see whether it is <application>Privoxy</application>
- causing the problem or not. <application>Privoxy</application> continues
- to run as a proxy in this case, but all manipulation is disabled, i.e.
- <application>Privoxy</application> acts like a normal forwarding proxy. There
- is even a toggle <link linkend="bookmarklets">Bookmarklet</link> offered, so
- that you can toggle <application>Privoxy</application> with one click from
- your browser.
-</para>
-
-<para>
- Note that several of the features described above are disabled by default
- in <application>Privoxy</application> 3.0.7 beta and later.
- Check the
- <ulink url="config.html">configuration file</ulink> to learn why
- and in which cases it's safe to enable them again.
-</para>
-
-</sect2>
-
-<!-- ~ End section ~ -->
-
-
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-
-<sect2 id="confoverview">
-<title>Configuration Files Overview</title>
-<para>
- For Unix, *BSD and Linux, all configuration files are located in
- <filename>/etc/privoxy/</filename> by default. For MS Windows, OS/2, and
- AmigaOS these are all in the same directory as the
- <application>Privoxy</application> executable. <![%p-not-stable;[ The name
- and number of configuration files has changed from previous versions, and is
- subject to change as development progresses.]]>
-</para>
-
-<para>
- The installed defaults provide a reasonable starting point, though
- some settings may be aggressive by some standards. For the time being, the
- principle configuration files are:
-</para>
-
-<para>
- <itemizedlist>
-
- <listitem>
- <para>
- The <link linkend="config">main configuration file</link> is named <filename>config</filename>
- on Linux, Unix, BSD, OS/2, and AmigaOS and <filename>config.txt</filename>
- on Windows. This is a required file.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <filename>match-all.action</filename> is used to define which <quote>actions</quote>
- relating to banner-blocking, images, pop-ups, content modification, cookie handling
- etc should be applied by default. It should be the first actions file loaded.
- </para>
- <para>
- <filename>default.action</filename> defines many exceptions (both positive and negative)
- from the default set of actions that's configured in <filename>match-all.action</filename>.
- It should be the second actions file loaded and shouldn't be edited by the user.
- </para>
- <para>
- Multiple actions files may be defined in <filename>config</filename>. These
- are processed in the order they are defined. Local customizations and locally
- preferred exceptions to the default policies as defined in
- <filename>match-all.action</filename> (which you will most probably want
- to define sooner or later) are best applied in <filename>user.action</filename>,
- where you can preserve them across upgrades. The file isn't installed by all
- installers, but you can easily create it yourself with a text editor.
- </para>
- <para>
- There is also a web based editor that can be accessed from
- <ulink
- url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
- (Shortcut: <ulink
- url="http://p.p/show-status">http://p.p/show-status</ulink>) for the
- various actions files.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <quote>Filter files</quote> (the <link linkend="filter-file">filter
- file</link>) can be used to re-write the raw page content, including
- viewable text as well as embedded HTML and JavaScript, and whatever else
- lurks on any given web page. The filtering jobs are only pre-defined here;
- whether to apply them or not is up to the actions files.
- <filename>default.filter</filename> includes various filters made
- available for use by the developers. Some are much more intrusive than
- others, and all should be used with caution. You may define additional
- filter files in <filename>config</filename> as you can with
- actions files. We suggest <filename>user.filter</filename> for any
- locally defined filters or customizations.
- </para>
- </listitem>
-
- </itemizedlist>
-</para>
-
-<para>
- The syntax of the configuration and filter files may change between different
- Privoxy versions, unfortunately some enhancements cost backwards compatibility.
- <!-- Add link to documentation-->
-</para>
-
-<para>
- All files use the <quote><literal>#</literal></quote> character to denote a
- comment (the rest of the line will be ignored) and understand line continuation
- through placing a backslash ("<literal>\</literal>") as the very last character
- in a line. If the <literal>#</literal> is preceded by a backslash, it looses
- its special function. Placing a <literal>#</literal> in front of an otherwise
- valid configuration line to prevent it from being interpreted is called "commenting
- out" that line. Blank lines are ignored.
-</para>
-
-<para>
- The actions files and filter files
- can use Perl style <link linkend="regex">regular expressions</link> for
- maximum flexibility.
-</para>
-
-<para>
- After making any changes, there is no need to restart
- <application>Privoxy</application> in order for the changes to take
- effect. <application>Privoxy</application> detects such changes
- automatically. Note, however, that it may take one or two additional
- requests for the change to take effect. When changing the listening address
- of <application>Privoxy</application>, these <quote>wake up</quote> requests
- must obviously be sent to the <emphasis>old</emphasis> listening address.
-</para>
-
-<![%p-not-stable;[
-<para>
- While under development, the configuration content is subject to change.
- The below documentation may not be accurate by the time you read this.
- Also, what constitutes a <quote>default</quote> setting, may change, so
- please check all your configuration files on important issues.
-</para>
-]]>
-
-</sect2>
-</sect1>
-<!-- ~ End section ~ -->
-
-
-<!-- ~~~~~~~~ New section Header ~~~~~~~~~ -->
-
-<!-- **************************************************** -->
-<!-- Include config.sgml here -->
-<!-- This is where the entire config file is detailed. -->
- &config;
-<!-- end include -->
-
-
-<!-- ~ End section ~ -->
-
-
-
-<!-- ~~~~~~~~ New section Header ~~~~~~~~~ -->
-
-<sect1 id="actions-file"><title>Actions Files</title>
-
-
-<!--
- XXX: similar descriptions are in the Configuration Files sections.
- We should only describe them at one place.
--->
-<para>
- The actions files are used to define what <emphasis>actions</emphasis>
- <application>Privoxy</application> takes for which URLs, and thus determines
- how ad images, cookies and various other aspects of HTTP content and
- transactions are handled, and on which sites (or even parts thereof).
- There are a number of such actions, with a wide range of functionality.
- Each action does something a little different.
- These actions give us a veritable arsenal of tools with which to exert
- our control, preferences and independence. Actions can be combined so that
- their effects are aggregated when applied against a given set of URLs.
-</para>
-<para>
- There
- are three action files included with <application>Privoxy</application> with
- differing purposes:
-</para>
-<para>
- <itemizedlist>
- <listitem>
- <para>
- <filename>match-all.action</filename> - is used to define which
- <quote>actions</quote> relating to banner-blocking, images, pop-ups,
- content modification, cookie handling etc should be applied by default.
- It should be the first actions file loaded
- </para>
- </listitem>
- <listitem>
- <para>
- <filename>default.action</filename> - defines many exceptions (both
- positive and negative) from the default set of actions that's configured
- in <filename>match-all.action</filename>. It is a set of rules that should
- work reasonably well as-is for most users. This file is only supposed to
- be edited by the developers. It should be the second actions file loaded.
- </para>
- </listitem>
- <listitem>
- <para>
- <filename>user.action</filename> - is intended to be for local site
- preferences and exceptions. As an example, if your ISP or your bank
- has specific requirements, and need special handling, this kind of
- thing should go here. This file will not be upgraded.
- </para>
- </listitem>
- <listitem>
- <para>
- <guibutton>Edit</guibutton> <guibutton>Set to Cautious</guibutton> <guibutton>Set to Medium</guibutton> <guibutton>Set to Advanced</guibutton>
- </para>
- <para>
- These have increasing levels of aggressiveness <emphasis>and have no
- influence on your browsing unless you select them explicitly in the
- editor</emphasis>. A default installation should be pre-set to
- <literal>Cautious</literal>. New users should try this for a while before
- adjusting the settings to more aggressive levels. The more aggressive
- the settings, then the more likelihood there is of problems such as sites
- not working as they should.
- </para>
- <para>
- The <guibutton>Edit</guibutton> button allows you to turn each
- action on/off individually for fine-tuning. The <guibutton>Cautious</guibutton>
- button changes the actions list to low/safe settings which will activate
- ad blocking and a minimal set of &my-app;'s features, and subsequently
- there will be less of a chance for accidental problems. The
- <guibutton>Medium</guibutton> button sets the list to a medium level of
- other features and a low level set of privacy features. The
- <guibutton>Advanced</guibutton> button sets the list to a high level of
- ad blocking and medium level of privacy. See the chart below. The latter
- three buttons over-ride any changes via with the
- <guibutton>Edit</guibutton> button. More fine-tuning can be done in the
- lower sections of this internal page.
- </para>
- <para>
- While the actions file editor allows to enable these settings in all
- actions files, they are only supposed to be enabled in the first one
- to make sure you don't unintentionally overrule earlier rules.
- </para>
- <para>
- The default profiles, and their associated actions, as pre-defined in
- <filename>default.action</filename> are:
- </para>
- <para>
- <table frame=all><title>Default Configurations</title>
- <tgroup cols=4 align=left colsep=1 rowsep=1>
- <colspec colname=c1>
- <colspec colname=c2>
- <colspec colname=c3>
- <colspec colname=c4>
- <thead>
- <row>
- <entry>Feature</entry>
- <entry>Cautious</entry>
- <entry>Medium</entry>
- <entry>Advanced</entry>
- </row>
- </thead>
- <!-- <tfoot> -->
- <!-- <row> -->
- <!-- <entry>f1</entry> -->
- <!-- <entry>f2</entry> -->
- <!-- <entry>f3</entry> -->
- <!-- <entry>f4</entry> -->
- <!-- </row> -->
- <!-- </tfoot> -->
- <tbody>
-
- <row>
- <entry>Ad-blocking Aggressiveness</entry>
- <entry>medium</entry>
- <entry>high</entry>
- <entry>high</entry>
- </row>
-
- <row>
- <entry>Ad-filtering by size</entry>
- <entry>no</entry>
- <entry>yes</entry>
- <entry>yes</entry>
- </row>
-
- <row>
- <entry>Ad-filtering by link</entry>
- <entry>no</entry>
- <entry>no</entry>
- <entry>yes</entry>
- </row>
- <row>
- <entry>Pop-up killing</entry>
- <entry>blocks only</entry>
- <entry>blocks only</entry>
- <entry>blocks only</entry>
- </row>
-
- <row>
- <entry>Privacy Features</entry>
- <entry>low</entry>
- <entry>medium</entry>
- <entry>medium/high</entry>
- </row>
-
- <row>
- <entry>Cookie handling</entry>
- <entry>none</entry>
- <entry>session-only</entry>
- <entry>kill</entry>
- </row>
-
- <row>
- <entry>Referer forging</entry>
- <entry>no</entry>
- <entry>yes</entry>
- <entry>yes</entry>
- </row>
-
- <row>
- <entry>GIF de-animation</entry>
- <entry>no</entry>
- <entry>yes</entry>
- <entry>yes</entry>
- </row>
-
- <row>
- <entry>Fast redirects</entry>
- <entry>no</entry>
- <entry>no</entry>
- <entry>yes</entry>
- </row>
-
- <row>
- <entry>HTML taming</entry>
- <entry>no</entry>
- <entry>no</entry>
- <entry>yes</entry>
- </row>
-
- <row>
- <entry>JavaScript taming</entry>
- <entry>no</entry>
- <entry>no</entry>
- <entry>yes</entry>
- </row>
-
- <row>
- <entry>Web-bug killing</entry>
- <entry>no</entry>
- <entry>yes</entry>
- <entry>yes</entry>
- </row>
-
- <row>
- <entry>Image tag reordering</entry>
- <entry>no</entry>
- <entry>yes</entry>
- <entry>yes</entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
- </para>
-
- </listitem>
- </itemizedlist>
-</para>
-
-<para>
- The list of actions files to be used are defined in the main configuration
- file, and are processed in the order they are defined (e.g.
- <filename>default.action</filename> is typically processed before
- <filename>user.action</filename>). The content of these can all be viewed and
- edited from <ulink
- url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.
- The over-riding principle when applying actions, is that the last action that
- matches a given URL wins. The broadest, most general rules go first
- (defined in <filename>default.action</filename>),
- followed by any exceptions (typically also in
- <filename>default.action</filename>), which are then followed lastly by any
- local preferences (typically in <emphasis>user</emphasis><filename>.action</filename>).
- Generally, <filename>user.action</filename> has the last word.
- </para>
-
-<para>
- An actions file typically has multiple sections. If you want to use
- <quote>aliases</quote> in an actions file, you have to place the (optional)
- <link linkend="aliases">alias section</link> at the top of that file.
- Then comes the default set of rules which will apply universally to all
- sites and pages (be <emphasis>very careful</emphasis> with using such a
- universal set in <filename>user.action</filename> or any other actions file after
- <filename>default.action</filename>, because it will override the result
- from consulting any previous file). And then below that,
- exceptions to the defined universal policies. You can regard
- <filename>user.action</filename> as an appendix to <filename>default.action</filename>,
- with the advantage that it is a separate file, which makes preserving your
- personal settings across <application>Privoxy</application> upgrades easier.
-</para>
-
-<para>
- Actions can be used to block anything you want, including ads, banners, or
- just some obnoxious URL whose content you would rather not see. Cookies can be accepted
- or rejected, or accepted only during the current browser session (i.e. not
- written to disk), content can be modified, some JavaScripts tamed, user-tracking
- fooled, and much more. See below for a <link linkend="actions">complete list
- of actions</link>.
-</para>
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect2>
-<title>Finding the Right Mix</title>
-<para>
- Note that some <link linkend="actions">actions</link>, like cookie suppression
- or script disabling, may render some sites unusable that rely on these
- techniques to work properly. Finding the right mix of actions is not always easy and
- certainly a matter of personal taste. And, things can always change, requiring
- refinements in the configuration. In general, it can be said that the more
- <quote>aggressive</quote> your default settings (in the top section of the
- actions file) are, the more exceptions for <quote>trusted</quote> sites you
- will have to make later. If, for example, you want to crunch all cookies per
- default, you'll have to make exceptions from that rule for sites that you
- regularly use and that require cookies for actually useful purposes, like maybe
- your bank, favorite shop, or newspaper.
-</para>
-
-<para>
- We have tried to provide you with reasonable rules to start from in the
- distribution actions files. But there is no general rule of thumb on these
- things. There just are too many variables, and sites are constantly changing.
- Sooner or later you will want to change the rules (and read this chapter again :).
-</para>
-</sect2>
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect2>
-<title>How to Edit</title>
-<para>
- The easiest way to edit the actions files is with a browser by
- using our browser-based editor, which can be reached from <ulink
- url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.
- Note: the config file option <link
- linkend="enable-edit-actions">enable-edit-actions</link> must be enabled for
- this to work. The editor allows both fine-grained control over every single
- feature on a per-URL basis, and easy choosing from wholesale sets of defaults
- like <quote>Cautious</quote>, <quote>Medium</quote> or
- <quote>Advanced</quote>. Warning: the <quote>Advanced</quote> setting is more
- aggressive, and will be more likely to cause problems for some sites.
- Experienced users only!
- </para>
-
-<para>
- If you prefer plain text editing to GUIs, you can of course also directly edit the
- the actions files with your favorite text editor. Look at
- <filename>default.action</filename> which is richly commented with many
- good examples.
-</para>
-</sect2>
-
-
-<sect2 id="actions-apply">
-<title>How Actions are Applied to Requests</title>
-<para>
- Actions files are divided into sections. There are special sections,
- like the <quote><link linkend="aliases">alias</link></quote> sections which will
- be discussed later. For now let's concentrate on regular sections: They have a
- heading line (often split up to multiple lines for readability) which consist
- of a list of actions, separated by whitespace and enclosed in curly braces.
- Below that, there is a list of URL and tag patterns, each on a separate line.
-</para>
-
-<para>
- To determine which actions apply to a request, the URL of the request is
- compared to all URL patterns in each <quote>action file</quote>.
- Every time it matches, the list of applicable actions for the request is
- incrementally updated, using the heading of the section in which the
- pattern is located. The same is done again for tags and tag patterns later on.
-</para>
-
-<para>
- If multiple applying sections set the same action differently,
- the last match wins. If not, the effects are aggregated.
- E.g. a URL might match a regular section with a heading line of <literal>{
- +<link linkend="handle-as-image">handle-as-image</link> }</literal>,
- then later another one with just <literal>{
- +<link linkend="block">block</link> }</literal>, resulting
- in <emphasis>both</emphasis> actions to apply. And there may well be
- cases where you will want to combine actions together. Such a section then
- might look like:
-</para>
-
- <para>
- <screen>
- { +<literal>handle-as-image</literal> +<literal>block{Banner ads.}</literal> }
- # Block these as if they were images. Send no block page.
- banners.example.com
- media.example.com/.*banners
- .example.com/images/ads/</screen>
- </para>
-
-<para>
- You can trace this process for URL patterns and any given URL by visiting <ulink
- url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>.
-</para>
-
-<para>
- Examples and more detail on this is provided in the Appendix, <link linkend="ACTIONSANAT">
- Troubleshooting: Anatomy of an Action</link> section.
-</para>
-</sect2>
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="af-patterns">
-<title>Patterns</title>
-<para>
- As mentioned, <application>Privoxy</application> uses <quote>patterns</quote>
- to determine what <emphasis>actions</emphasis> might apply to which sites and
- pages your browser attempts to access. These <quote>patterns</quote> use wild
- card type <emphasis>pattern</emphasis> matching to achieve a high degree of
- flexibility. This allows one expression to be expanded and potentially match
- against many similar patterns.
-</para>
-
-<para>
- Generally, an URL pattern has the form
- <literal><domain><port>/<path></literal>, where the
- <literal><domain></literal>, the <literal><port></literal>
- and the <literal><path></literal> are optional. (This is why the special
- <literal>/</literal> pattern matches all URLs). Note that the protocol
- portion of the URL pattern (e.g. <literal>http://</literal>) should
- <emphasis>not</emphasis> be included in the pattern. This is assumed already!
-</para>
-<para>
- 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 more flexible
- <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
- Expressions</quote></ulink> (POSIX 1003.2).
-</para>
-<para>
- The port part of a pattern is a decimal port number preceded by a colon
- (<literal>:</literal>). If the domain part contains a numerical IPv6 address,
- it has to be put into angle brackets
- (<literal><</literal>, <literal>></literal>).
-</para>
-
-<variablelist>
- <varlistentry>
- <term><literal>www.example.com/</literal></term>
- <listitem>
- <para>
- is a domain-only pattern and will match any request to <literal>www.example.com</literal>,
- regardless of which document on that server is requested. So ALL pages in
- this domain would be covered by the scope of this action. Note that a
- simple <literal>example.com</literal> is different and would NOT match.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>www.example.com</literal></term>
- <listitem>
- <para>
- means exactly the same. For domain-only patterns, the trailing <literal>/</literal> may
- be omitted.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>www.example.com/index.html</literal></term>
- <listitem>
- <para>
- matches all the documents on <literal>www.example.com</literal>
- whose name starts with <literal>/index.html</literal>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>www.example.com/index.html$</literal></term>
- <listitem>
- <para>
- matches only the single document <literal>/index.html</literal>
- on <literal>www.example.com</literal>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>/index.html$</literal></term>
- <listitem>
- <para>
- matches the document <literal>/index.html</literal>, regardless of the domain,
- i.e. on <emphasis>any</emphasis> web server anywhere.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>/</literal></term>
- <listitem>
- <para>
- Matches any URL because there's no requirement for either the
- domain or the path to match anything.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>:8000/</literal></term>
- <listitem>
- <para>
- Matches any URL pointing to TCP port 8000.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal><2001:db8::1>/</literal></term>
- <listitem>
- <para>
- Matches any URL with the host address <literal>2001:db8::1</literal>.
- (Note that the real URL uses plain brackets, not angle brackets.)
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>index.html</literal></term>
- <listitem>
- <para>
- matches nothing, since it would be interpreted as a domain name and
- there is no top-level domain called <literal>.html</literal>. So its
- a mistake.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3><title>The Domain Pattern</title>
-
-<para>
- The matching of the domain part offers some flexible options: if the
- domain starts or ends with a dot, it becomes unanchored at that end.
- For example:
-</para>
-
-<variablelist>
- <varlistentry>
- <term><literal>.example.com</literal></term>
- <listitem>
- <para>
- matches any domain with first-level domain <literal>com</literal>
- and second-level domain <literal>example</literal>.
- For example <literal>www.example.com</literal>,
- <literal>example.com</literal> and <literal>foo.bar.baz.example.com</literal>.
- Note that it wouldn't match if the second-level domain was <literal>another-example</literal>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>www.</literal></term>
- <listitem>
- <para>
- matches any domain that <emphasis>STARTS</emphasis> with
- <literal>www.</literal> (It also matches the domain
- <literal>www</literal> but most of the time that doesn't matter.)
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>.example.</literal></term>
- <listitem>
- <para>
- matches any domain that <emphasis>CONTAINS</emphasis> <literal>.example.</literal>.
- And, by the way, also included would be any files or documents that exist
- within that domain since no path limitations are specified. (Correctly
- speaking: It matches any FQDN that contains <literal>example</literal> as
- a domain.) This might be <literal>www.example.com</literal>,
- <literal>news.example.de</literal>, or
- <literal>www.example.net/cgi/testing.pl</literal> for instance. All these
- cases are matched.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-
-<para>
- Additionally, there are wild-cards that you can use in the domain names
- themselves. These work similarly to shell globbing type wild-cards:
- <quote>*</quote> represents zero or more arbitrary characters (this is
- equivalent to the
- <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
- Expression</quote></ulink> based syntax of <quote>.*</quote>),
- <quote>?</quote> represents any single character (this is equivalent to the
- regular expression syntax of a simple <quote>.</quote>), and you can define
- <quote>character classes</quote> in square brackets which is similar to
- the same regular expression technique. All of this can be freely mixed:
-</para>
-
-<variablelist>
- <varlistentry>
- <term><literal>ad*.example.com</literal></term>
- <listitem>
- <para>
- matches <quote>adserver.example.com</quote>,
- <quote>ads.example.com</quote>, etc but not <quote>sfads.example.com</quote>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>*ad*.example.com</literal></term>
- <listitem>
- <para>
- matches all of the above, and then some.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>.?pix.com</literal></term>
- <listitem>
- <para>
- matches <literal>www.ipix.com</literal>,
- <literal>pictures.epix.com</literal>, <literal>a.b.c.d.e.upix.com</literal> etc.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>www[1-9a-ez].example.c*</literal></term>
- <listitem>
- <para>
- matches <literal>www1.example.com</literal>,
- <literal>www4.example.cc</literal>, <literal>wwwd.example.cy</literal>,
- <literal>wwwz.example.com</literal> etc., but <emphasis>not</emphasis>
- <literal>wwww.example.com</literal>.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-
-<para>
- While flexible, this is not the sophistication of full regular expression based syntax.
-</para>
-
-</sect3>
-
-<!-- ~ End section ~ -->
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3><title>The Path Pattern</title>
-
-<para>
- <application>Privoxy</application> uses <quote>modern</quote> POSIX 1003.2
- <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
- Expressions</quote></ulink> for matching the path portion (after the slash),
- and is thus more flexible.
-</para>
-
-<para>
- There is an <link linkend="regex">Appendix</link> with a brief quick-start into regular
- expressions, you also might want to have a look at your operating system's documentation
- on regular expressions (try <literal>man re_format</literal>).
-</para>
-
-<para>
- Note that the path pattern is automatically left-anchored at the <quote>/</quote>,
- i.e. it matches as if it would start with a <quote>^</quote> (regular expression speak
- for the beginning of a line).
-</para>
-
-<para>
- Please also note that matching in the path is <emphasis>CASE INSENSITIVE</emphasis>
- by default, but you can switch to case sensitive at any point in the pattern by using the
- <quote>(?-i)</quote> switch: <literal>www.example.com/(?-i)PaTtErN.*</literal> will match
- only documents whose path starts with <literal>PaTtErN</literal> in
- <emphasis>exactly</emphasis> this capitalization.
-</para>
-
-<variablelist>
- <varlistentry>
- <term><literal>.example.com/.*</literal></term>
- <listitem>
- <para>
- Is equivalent to just <quote>.example.com</quote>, since any documents
- within that domain are matched with or without the <quote>.*</quote>
- regular expression. This is redundant
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>.example.com/.*/index.html$</literal></term>
- <listitem>
- <para>
- Will match any page in the domain of <quote>example.com</quote> that is
- named <quote>index.html</quote>, and that is part of some path. For
- example, it matches <quote>www.example.com/testing/index.html</quote> but
- NOT <quote>www.example.com/index.html</quote> because the regular
- expression called for at least two <quote>/'s</quote>, thus the path
- requirement. It also would match
- <quote>www.example.com/testing/index_html</quote>, because of the
- special meta-character <quote>.</quote>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>.example.com/(.*/)?index\.html$</literal></term>
- <listitem>
- <para>
- This regular expression is conditional so it will match any page
- named <quote>index.html</quote> regardless of path which in this case can
- have one or more <quote>/'s</quote>. And this one must contain exactly
- <quote>.html</quote> (but does not have to end with that!).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>.example.com/(.*/)(ads|banners?|junk)</literal></term>
- <listitem>
- <para>
- This regular expression will match any path of <quote>example.com</quote>
- that contains any of the words <quote>ads</quote>, <quote>banner</quote>,
- <quote>banners</quote> (because of the <quote>?</quote>) or <quote>junk</quote>.
- The path does not have to end in these words, just contain them.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>.example.com/(.*/)(ads|banners?|junk)/.*\.(jpe?g|gif|png)$</literal></term>
- <listitem>
- <para>
- This is very much the same as above, except now it must end in either
- <quote>.jpg</quote>, <quote>.jpeg</quote>, <quote>.gif</quote> or <quote>.png</quote>. So this
- one is limited to common image formats.
- </para>
- </listitem>
- </varlistentry>
-
-</variablelist>
-<para>
- There are many, many good examples to be found in <filename>default.action</filename>,
- and more tutorials below in <link linkend="regex">Appendix on regular expressions</link>.
-</para>
-
-</sect3>
-
-<!-- ~ End section ~ -->
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 id="tag-pattern"><title>The Tag Pattern</title>
-
-<para>
- Tag patterns are used to change the applying actions based on the
- request's tags. Tags can be created with either the
- <link linkend="CLIENT-HEADER-TAGGER">client-header-tagger</link>
- or the <link linkend="SERVER-HEADER-TAGGER">server-header-tagger</link> action.
-</para>
-
-<para>
- Tag patterns have to start with <quote>TAG:</quote>, so &my-app;
- can tell them apart from URL patterns. Everything after the colon
- including white space, is interpreted as a regular expression with
- path pattern syntax, except that tag patterns aren't left-anchored
- automatically (&my-app; doesn't silently add a <quote>^</quote>,
- you have to do it yourself if you need it).
-</para>
-
-<para>
- To match all requests that are tagged with <quote>foo</quote>
- your pattern line should be <quote>TAG:^foo$</quote>,
- <quote>TAG:foo</quote> would work as well, but it would also
- match requests whose tags contain <quote>foo</quote> somewhere.
- <quote>TAG: foo</quote> wouldn't work as it requires white space.
-</para>
-
-<para>
- Sections can contain URL and tag patterns at the same time,
- but tag patterns are checked after the URL patterns and thus
- always overrule them, even if they are located before the URL patterns.
-</para>
-
-<para>
- Once a new tag is added, Privoxy checks right away if it's matched by one
- of the tag patterns and updates the action settings accordingly. As a result
- tags can be used to activate other tagger actions, as long as these other
- taggers look for headers that haven't already be parsed.
-</para>
-
-<para>
- For example you could tag client requests which use the
- <literal>POST</literal> method,
- then use this tag to activate another tagger that adds a tag if cookies
- are sent, and then use a block action based on the cookie tag. This allows
- the outcome of one action, to be input into a subsequent action. However if
- you'd reverse the position of the described taggers, and activated the
- method tagger based on the cookie tagger, no method tags would be created.
- The method tagger would look for the request line, but at the time
- the cookie tag is created, the request line has already been parsed.
-</para>
-
-<para>
- While this is a limitation you should be aware of, this kind of
- indirection is seldom needed anyway and even the example doesn't
- make too much sense.
-</para>
-
-</sect3>
-
-</sect2>
-
-<!-- ~ End section ~ -->
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-
-<sect2 id="actions">
-<title>Actions</title>
-<para>
- All actions are disabled by default, until they are explicitly enabled
- somewhere in an actions file. Actions are turned on if preceded with a
- <quote>+</quote>, and turned off if preceded with a <quote>-</quote>. So a
- <literal>+action</literal> means <quote>do that action</quote>, e.g.
- <literal>+block</literal> means <quote>please block URLs that match the
- following patterns</quote>, and <literal>-block</literal> means <quote>don't
- block URLs that match the following patterns, even if <literal>+block</literal>
- previously applied.</quote>
-
-</para>
-
-<para>
- Again, actions are invoked by placing them on a line, enclosed in curly braces and
- separated by whitespace, like in
- <literal>{+some-action -some-other-action{some-parameter}}</literal>,
- followed by a list of URL patterns, one per line, to which they apply.
- Together, the actions line and the following pattern lines make up a section
- of the actions file.
-</para>
-
-<para>
- Actions fall into three categories:
-</para>
-
-<para>
- <itemizedlist>
- <listitem>
- <para>
- Boolean, i.e the action can only be <quote>enabled</quote> or
- <quote>disabled</quote>. Syntax:
- </para>
- <para>
- <screen>
- +<replaceable class="function">name</replaceable> # enable action <replaceable class="parameter">name</replaceable>
- -<replaceable class="function">name</replaceable> # disable action <replaceable class="parameter">name</replaceable></screen>
- </para>
- <para>
- Example: <literal>+handle-as-image</literal>
- </para>
- </listitem>
-
-
- <listitem>
- <para>
- Parameterized, where some value is required in order to enable this type of action.
- Syntax:
- </para>
- <para>
- <screen>
- +<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>} # enable action and set parameter to <replaceable class="parameter">param</replaceable>,
- # overwriting parameter from previous match if necessary
- -<replaceable class="function">name</replaceable> # disable action. The parameter can be omitted</screen>
- </para>
- <para>
- Note that if the URL matches multiple positive forms of a parameterized action,
- the last match wins, i.e. the params from earlier matches are simply ignored.
- </para>
- <para>
- Example: <literal>+hide-user-agent{Mozilla/5.0 (X11; U; FreeBSD i386; en-US; rv:1.8.1.4) Gecko/20070602 Firefox/2.0.0.4}</literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- Multi-value. These look exactly like parameterized actions,
- but they behave differently: If the action applies multiple times to the
- same URL, but with different parameters, <emphasis>all</emphasis> the parameters
- from <emphasis>all</emphasis> matches are remembered. This is used for actions
- that can be executed for the same request repeatedly, like adding multiple
- headers, or filtering through multiple filters. Syntax:
- </para>
- <para>
- <screen>
- +<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>} # enable action and add <replaceable class="parameter">param</replaceable> to the list of parameters
- -<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>} # remove the parameter <replaceable class="parameter">param</replaceable> from the list of parameters
- # If it was the last one left, disable the action.
- <replaceable class="parameter">-name</replaceable> # disable this action completely and remove all parameters from the list</screen>
- </para>
- <para>
- Examples: <literal>+add-header{X-Fun-Header: Some text}</literal> and
- <literal>+filter{html-annoyances}</literal>
- </para>
- </listitem>
-
- </itemizedlist>
-</para>
-
-<para>
- If nothing is specified in any actions file, no <quote>actions</quote> are
- taken. So in this case <application>Privoxy</application> would just be a
- normal, non-blocking, non-filtering proxy. You must specifically enable the
- privacy and blocking features you need (although the provided default actions
- files will give a good starting point).
-</para>
-
-<para>
- Later defined action sections always over-ride earlier ones of the same type.
- So exceptions to any rules you make, should come in the latter part of the file (or
- in a file that is processed later when using multiple actions files such
- as <filename>user.action</filename>). For multi-valued actions, the actions
- are applied in the order they are specified. Actions files are processed in
- the order they are defined in <filename>config</filename> (the default
- installation has three actions files). It also quite possible for any given
- URL to match more than one <quote>pattern</quote> (because of wildcards and
- regular expressions), and thus to trigger more than one set of actions! Last
- match wins.
-</para>
-
-<!-- start actions listing -->
-<para>
- The list of valid <application>Privoxy</application> actions are:
-</para>
-
-
-<!-- ********************************************************** -->
-<!-- Please note the below defined actions use id's that are -->
-<!-- probably linked from other places, so please don't change. -->
-<!-- -->
-<!-- ********************************************************** -->
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-
-<sect3 renderas="sect4" id="add-header">
-<title>add-header</title>
-
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>Confuse log analysis, custom applications</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- Sends a user defined HTTP header to the web server.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- boolean, parameterized, Multi-value -->
- <listitem>
- <para>Multi-value.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <para>
- Any string value is possible. Validity of the defined HTTP headers is not checked.
- It is recommended that you use the <quote><literal>X-</literal></quote> prefix
- for custom headers.
- </para>
- </listitem>
- </varlistentry>
-
-<varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- 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
- <quote>HTTP headers</quote> are, you definitely don't need to worry about this
- one.
- </para>
- <para>
- Headers added by this action are not modified by other actions.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage:</term>
- <listitem>
- <para>
- <screen>+add-header{X-User-Tracking: sucks}</screen>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect3>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="block">
-<title>block</title>
-
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>Block ads or other unwanted content</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- Requests for URLs to which this action applies are blocked, i.e. the
- requests are trapped by &my-app; and the requested URL is never retrieved,
- but is answered locally with a substitute page or image, as determined by
- the <literal><link
- linkend="handle-as-image">handle-as-image</link></literal>,
- <literal><link
- linkend="set-image-blocker">set-image-blocker</link></literal>, and
- <literal><link
- linkend="handle-as-empty-document">handle-as-empty-document</link></literal> actions.
-
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- boolean, parameterized, Multi-value -->
- <listitem>
- <para>Parameterized.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <para>A block reason that should be given to the user.</para>
- </listitem>
- </varlistentry>
-
-<varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- <application>Privoxy</application> sends a special <quote>BLOCKED</quote> 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).
- </para>
- <para>
- A very important exception occurs if <emphasis>both</emphasis>
- <literal>block</literal> and <literal><link linkend="handle-as-image">handle-as-image</link></literal>,
- apply to the same request: it will then be replaced by an image. If
- <literal><link linkend="set-image-blocker">set-image-blocker</link></literal>
- (see below) also applies, the type of image will be determined by its parameter,
- if not, the standard checkerboard pattern is sent.
- </para>
- <para>
- It is important to understand this process, in order
- to understand how <application>Privoxy</application> deals with
- ads and other unwanted content. Blocking is a core feature, and one
- upon which various other features depend.
- </para>
- <para>
- The <literal><link linkend="filter">filter</link></literal>
- action can perform a very similar task, by <quote>blocking</quote>
- banner images and other content through rewriting the relevant URLs in the
- document's HTML source, so they don't get requested in the first place.
- Note that this is a totally different technique, and it's easy to confuse the two.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage (section):</term>
- <listitem>
- <para>
- <screen>{+block{No nasty stuff for you.}}
-# Block and replace with "blocked" page
- .nasty-stuff.example.com
-
-{+block{Doubleclick banners.} +handle-as-image}
-# Block and replace with image
- .ad.doubleclick.net
- .ads.r.us/banners/
-
-{+block{Layered ads.} +handle-as-empty-document}
-# Block and then ignore
- adserver.example.net/.*\.js$</screen>
- </para>
- </listitem>
- </varlistentry>
-
-
-</variablelist>
-</sect3>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="change-x-forwarded-for">
-<title>change-x-forwarded-for</title>
-
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>Improve privacy by not forwarding the source of the request in the HTTP headers.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- Deletes the <quote>X-Forwarded-For:</quote> HTTP header from the client request,
- or adds a new one.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- Boolean, Parameterized, Multi-value -->
- <listitem>
- <para>Parameterized.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <itemizedlist>
- <listitem>
- <para><quote>block</quote> to delete the header.</para>
- </listitem>
- <listitem>
- <para>
- <quote>add</quote> to create the header (or append
- the client's IP address to an already existing one).
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- It is safe and recommended to use <literal>block</literal>.
- </para>
- <para>
- Forwarding the source address of the request may make
- sense in some multi-user setups but is also a privacy risk.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Example usage:</term>
- <listitem>
- <para>
- <screen>+change-x-forwarded-for{block}</screen>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect3>
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="client-header-filter">
-<title>client-header-filter</title>
-
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>
- Rewrite or remove single client headers.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- All client headers to which this action applies are filtered on-the-fly through
- the specified regular expression based substitutions.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- boolean, parameterized, Multi-value -->
- <listitem>
- <para>Parameterized.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <para>
- The name of a client-header filter, as defined in one of the
- <link linkend="filter-file">filter files</link>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- Client-header filters are applied to each header on its own, not to
- all at once. This makes it easier to diagnose problems, but on the downside
- you can't write filters that only change header x if header y's value is z.
- You can do that by using tags though.
- </para>
- <para>
- Client-header filters are executed after the other header actions have finished
- and use their output as input.
- </para>
- <para>
- If the request URI gets changed, &my-app; will detect that and use the new
- one. This can be used to rewrite the request destination behind the client's
- back, for example to specify a Tor exit relay for certain requests.
- </para>
- <para>
- Please refer to the <link linkend="filter-file">filter file chapter</link>
- to learn which client-header filters are available by default, and how to
- create your own.
- </para>
-
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage (section):</term>
- <listitem>
- <para>
- <screen>
-# Hide Tor exit notation in Host and Referer Headers
-{+client-header-filter{hide-tor-exit-notation}}
-/
- </screen>
- </para>
- </listitem>
- </varlistentry>
-
-</variablelist>
-</sect3>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="client-header-tagger">
-<title>client-header-tagger</title>
-
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>
- Block requests based on their headers.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- Client headers to which this action applies are filtered on-the-fly through
- the specified regular expression based substitutions, the result is used as
- tag.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- boolean, parameterized, Multi-value -->
- <listitem>
- <para>Parameterized.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <para>
- The name of a client-header tagger, as defined in one of the
- <link linkend="filter-file">filter files</link>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- Client-header taggers are applied to each header on its own,
- and as the header isn't modified, each tagger <quote>sees</quote>
- the original.
- </para>
- <para>
- Client-header taggers are the first actions that are executed
- and their tags can be used to control every other action.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage (section):</term>
- <listitem>
- <para>
- <screen>
-# 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/
- </screen>
- </para>
- <para>
- <screen>
-# Tag all requests with the Range header set
-{+client-header-tagger{range-requests}}
-/
-
-# Disable filtering for the tagged requests.
-#
-# With filtering enabled Privoxy would remove the Range headers
-# to be able to filter the whole response. The downside is that
-# it prevents clients from resuming downloads or skipping over
-# parts of multimedia files.
-{-filter -deanimate-gifs}
-TAG:^RANGE-REQUEST$
- </screen>
- </para>
- </listitem>
- </varlistentry>
-
-</variablelist>
-</sect3>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="content-type-overwrite">
-<title>content-type-overwrite</title>
-
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>Stop useless download menus from popping up, or change the browser's rendering mode</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- Replaces the <quote>Content-Type:</quote> HTTP server header.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- Boolean, Parameterized, Multi-value -->
- <listitem>
- <para>Parameterized.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <para>
- Any string.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- The <quote>Content-Type:</quote> HTTP server header is used by the
- browser to decide what to do with the document. The value of this
- header can cause the browser to open a download menu instead of
- displaying the document by itself, even if the document's format is
- supported by the browser.
- </para>
- <para>
- The declared content type can also affect which rendering mode
- the browser chooses. If XHTML is delivered as <quote>text/html</quote>,
- many browsers treat it as yet another broken HTML document.
- If it is send as <quote>application/xml</quote>, browsers with
- XHTML support will only display it, if the syntax is correct.
- </para>
- <para>
- If you see a web site that proudly uses XHTML buttons, but sets
- <quote>Content-Type: text/html</quote>, you can use &my-app;
- to overwrite it with <quote>application/xml</quote> and validate
- the web master's claim inside your XHTML-supporting browser.
- If the syntax is incorrect, the browser will complain loudly.
- </para>
- <para>
- You can also go the opposite direction: if your browser prints
- error messages instead of rendering a document falsely declared
- as XHTML, you can overwrite the content type with
- <quote>text/html</quote> and have it rendered as broken HTML document.
- </para>
- <para>
- By default <literal>content-type-overwrite</literal> only replaces
- <quote>Content-Type:</quote> headers that look like some kind of text.
- If you want to overwrite it unconditionally, you have to combine it with
- <literal><link linkend="force-text-mode">force-text-mode</link></literal>.
- This limitation exists for a reason, think twice before circumventing it.
- </para>
- <para>
- Most of the time it's easier to replace this action with a custom
- <literal><link linkend="server-header-filter">server-header filter</link></literal>.
- It allows you to activate it for every document of a certain site and it will still
- only replace the content types you aimed at.
- </para>
- <para>
- Of course you can apply <literal>content-type-overwrite</literal>
- to a whole site and then make URL based exceptions, but it's a lot
- more work to get the same precision.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage (sections):</term>
- <listitem>
- <para>
- <screen># Check if www.example.net/ really uses valid XHTML
-{ +content-type-overwrite{application/xml} }
-www.example.net/
-
-# but leave the content type unmodified if the URL looks like a style sheet
-{-content-type-overwrite}
-www.example.net/.*\.css$
-www.example.net/.*style
-</screen>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect3>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="crunch-client-header">
-<!--
-new action
--->
-<title>crunch-client-header</title>
-
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>Remove a client header <application>Privoxy</application> has no dedicated action for.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- Deletes every header sent by the client that contains the string the user supplied as parameter.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- Boolean, Parameterized, Multi-value -->
- <listitem>
- <para>Parameterized.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <para>
- Any string.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- This action allows you to block client headers for which no dedicated
- <application>Privoxy</application> action exists.
- <application>Privoxy</application> will remove every client header that
- contains the string you supplied as parameter.
- </para>
- <para>
- Regular expressions are <emphasis>not supported</emphasis> and you can't
- use this action to block different headers in the same request, unless
- they contain the same string.
- </para>
- <para>
- <literal>crunch-client-header</literal> is only meant for quick tests.
- If you have to block several different headers, or only want to modify
- parts of them, you should use a
- <literal><link linkend="client-header-filter">client-header filter</link></literal>.
- </para>
- <warning>
- <para>
- Don't block any header without understanding the consequences.
- </para>
- </warning>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage (section):</term>
- <listitem>
- <para>
- <screen># Block the non-existent "Privacy-Violation:" client header
-{ +crunch-client-header{Privacy-Violation:} }
-/
- </screen>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect3>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="crunch-if-none-match">
-<title>crunch-if-none-match</title>
-<!--
-new action
--->
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>Prevent yet another way to track the user's steps between sessions.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- Deletes the <quote>If-None-Match:</quote> HTTP client header.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- Boolean, Parameterized, Multi-value -->
- <listitem>
- <para>Boolean.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <para>
- N/A
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- Removing the <quote>If-None-Match:</quote> HTTP client header
- is useful for filter testing, where you want to force a real
- reload instead of getting status code <quote>304</quote> which
- would cause the browser to use a cached copy of the page.
- </para>
- <para>
- It is also useful to make sure the header isn't used as a cookie
- replacement (unlikely but possible).
- </para>
- <para>
- Blocking the <quote>If-None-Match:</quote> header shouldn't cause any
- caching problems, as long as the <quote>If-Modified-Since:</quote> header
- isn't blocked or missing as well.
- </para>
- <para>
- It is recommended to use this action together with
- <literal><link linkend="hide-if-modified-since">hide-if-modified-since</link></literal>
- and
- <literal><link linkend="overwrite-last-modified">overwrite-last-modified</link></literal>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage (section):</term>
- <listitem>
- <para>
- <screen># Let the browser revalidate cached documents but don't
-# allow the server to use the revalidation headers for user tracking.
-{+hide-if-modified-since{-60} \
- +overwrite-last-modified{randomize} \
- +crunch-if-none-match}
-/ </screen>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect3>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="crunch-incoming-cookies">
-<title>crunch-incoming-cookies</title>
-
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>
- Prevent the web server from setting HTTP cookies on your system
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- Deletes any <quote>Set-Cookie:</quote> HTTP headers from server replies.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- Boolean, Parameterized, Multi-value -->
- <listitem>
- <para>Boolean.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <para>
- N/A
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- This action is only concerned with <emphasis>incoming</emphasis> HTTP cookies. For
- <emphasis>outgoing</emphasis> HTTP cookies, use
- <literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal>.
- Use <emphasis>both</emphasis> to disable HTTP cookies completely.
- </para>
- <para>
- It makes <emphasis>no sense at all</emphasis> to use this action in conjunction
- with the <literal><link linkend="session-cookies-only">session-cookies-only</link></literal> action,
- since it would prevent the session cookies from being set. See also
- <literal><link linkend="filter-content-cookies">filter-content-cookies</link></literal>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage:</term>
- <listitem>
- <para>
- <screen>+crunch-incoming-cookies</screen>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect3>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="crunch-server-header">
-<title>crunch-server-header</title>
-<!--
-new action
--->
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>Remove a server header <application>Privoxy</application> has no dedicated action for.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- Deletes every header sent by the server that contains the string the user supplied as parameter.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- Boolean, Parameterized, Multi-value -->
- <listitem>
- <para>Parameterized.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <para>
- Any string.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- This action allows you to block server headers for which no dedicated
- <application>Privoxy</application> action exists. <application>Privoxy</application>
- will remove every server header that contains the string you supplied as parameter.
- </para>
- <para>
- Regular expressions are <emphasis>not supported</emphasis> and you can't
- use this action to block different headers in the same request, unless
- they contain the same string.
- </para>
- <para>
- <literal>crunch-server-header</literal> is only meant for quick tests.
- If you have to block several different headers, or only want to modify
- parts of them, you should use a custom
- <literal><link linkend="server-header-filter">server-header filter</link></literal>.
- </para>
- <warning>
- <para>
- Don't block any header without understanding the consequences.
- </para>
- </warning>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage (section):</term>
- <listitem>
- <para>
- <screen># Crunch server headers that try to prevent caching
-{ +crunch-server-header{no-cache} }
-/ </screen>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect3>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="crunch-outgoing-cookies">
-<title>crunch-outgoing-cookies</title>
-
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>
- Prevent the web server from reading any HTTP cookies from your system
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- Deletes any <quote>Cookie:</quote> HTTP headers from client requests.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- Boolean, Parameterized, Multi-value -->
- <listitem>
- <para>Boolean.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <para>
- N/A
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- This action is only concerned with <emphasis>outgoing</emphasis> HTTP cookies. For
- <emphasis>incoming</emphasis> HTTP cookies, use
- <literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal>.
- Use <emphasis>both</emphasis> to disable HTTP cookies completely.
- </para>
- <para>
- It makes <emphasis>no sense at all</emphasis> to use this action in conjunction
- with the <literal><link linkend="session-cookies-only">session-cookies-only</link></literal> action,
- since it would prevent the session cookies from being read.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage:</term>
- <listitem>
- <para>
- <screen>+crunch-outgoing-cookies</screen>
- </para>
- </listitem>
- </varlistentry>
-
-</variablelist>
-</sect3>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="deanimate-gifs">
-<title>deanimate-gifs</title>
-
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>Stop those annoying, distracting animated GIF images.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- De-animate GIF animations, i.e. reduce them to their first or last image.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- boolean, parameterized, Multi-value -->
- <listitem>
- <para>Parameterized.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <para>
- <quote>last</quote> or <quote>first</quote>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- This will also shrink the images considerably (in bytes, not pixels!). If
- the option <quote>first</quote> is given, the first frame of the animation
- is used as the replacement. If <quote>last</quote> 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).
- </para>
- <para>
- You can safely use this action with patterns that will also match non-GIF
- objects, because no attempt will be made at anything that doesn't look like
- a GIF.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage:</term>
- <listitem>
- <para>
- <screen>+deanimate-gifs{last}</screen>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect3>
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="downgrade-http-version">
-<title>downgrade-http-version</title>
-
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>Work around (very rare) problems with HTTP/1.1</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- Downgrades HTTP/1.1 client requests and server replies to HTTP/1.0.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- boolean, parameterized, Multi-value -->
- <listitem>
- <para>Boolean.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <para>
- N/A
- </para>
- </listitem>
- </varlistentry>
-
-<varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- This is a left-over from the time when <application>Privoxy</application>
- didn't support important HTTP/1.1 features well. It is left here for the
- unlikely case that you experience HTTP/1.1-related problems with some server
- out there.
- </para>
- <para>
- Note that enabling this action is only a workaround. It should not
- be enabled for sites that work without it. While it shouldn't break
- any pages, it has an (usually negative) performance impact.
- </para>