X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;f=doc%2Fsource%2Fuser-manual.sgml;h=6d9c5d6c26ebb2e66447c3c9933b26af94eef35f;hb=0d8ef579629acfe8fbc049f4d661f11e49abebe8;hp=bf867bbea8d3c2beb06ee6417e1f55598c375b55;hpb=fe193e65c98014e4a07a052e6440c238844fc9d6;p=privoxy.git
diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml
index bf867bbe..6d9c5d6c 100644
--- a/doc/source/user-manual.sgml
+++ b/doc/source/user-manual.sgml
@@ -9,9 +9,11 @@
+
-
+
+
@@ -34,9 +36,9 @@
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: user-manual.sgml,v 2.152 2012/10/29 12:02:55 fabiankeil Exp $
+ $Id: user-manual.sgml,v 2.221 2017/05/20 09:27:54 fabiankeil Exp $
- Copyright (C) 2001-2011 Privoxy Developers http://www.privoxy.org/
+ Copyright (C) 2001-2017 Privoxy Developers https://www.privoxy.org/
See LICENSE.
========================================================================
@@ -55,12 +57,12 @@
- Copyright &my-copy; 2001-2011 by
- Privoxy Developers
+ Copyright &my-copy; 2001-2017 by
+ Privoxy Developers
-$Id: user-manual.sgml,v 2.152 2012/10/29 12:02:55 fabiankeil Exp $
+$Id: user-manual.sgml,v 2.221 2017/05/20 09:27:54 fabiankeil Exp $
@@ -99,14 +101,11 @@ Hal.
You can find the latest version of the Privoxy User Manual at http://www.privoxy.org/user-manual/.
+ url="https://www.privoxy.org/user-manual/">https://www.privoxy.org/user-manual/.
Please see the Contact section on how to
contact the developers.
-
-
-
@@ -115,7 +114,7 @@ Hal.
Introduction
This documentation is included with the current &p-status; version of
- Privoxy, v.&p-version;Privoxy, &p-version;Privoxy is available both in convenient pre-compiled
packages for a wide range of operating systems, and as raw source code.
For most users, we recommend using the packages, which can be downloaded from our
- Privoxy Project
+ Privoxy Project
Page.
@@ -180,36 +179,6 @@ How to install the binary packages depends on your operating system:
-
-Red Hat and Fedora RPMs
-
-
- RPMs can be installed with rpm -Uvh privoxy-&p-version;-1.rpm,
- and will use /etc/privoxy for the location
- of configuration files.
-
-
-
- Note that on Red Hat, Privoxy will
- not be automatically started on system boot. You will
- need to enable that using chkconfig,
- ntsysv, or similar methods.
-
-
-
- If you have problems with failed dependencies, try rebuilding the SRC RPM:
- rpm --rebuild privoxy-&p-version;-1.src.rpm. This
- will use your locally installed libraries and RPM version.
-
-
-
- Also note that if you have a Junkbuster RPM installed
- on your system, you need to remove it first, because the packages conflict.
- Otherwise, RPM will try to remove Junkbuster
- automatically if found, before installing Privoxy.
-
-
-
Debian and Ubuntu
@@ -262,16 +231,6 @@ How to install the binary packages depends on your operating system:
-
-Solaris
-
-
- Create a new directory, cd to it, then unzip and
- untar the archive. For the most part, you'll have to figure out where
- things go.
-
-
-
OS/2
@@ -305,6 +264,7 @@ How to install the binary packages depends on your operating system:
you downloaded a ready-built installation package (.pkg or .mpkg) or have
downloaded the source code.
+Installation from ready-built package
@@ -334,6 +294,7 @@ How to install the binary packages depends on your operating system:
To uninstall, run /Applications/Privoxy/uninstall.command as sudo from an
administrator account.
+Installation from source
@@ -371,53 +332,12 @@ How to install the binary packages depends on your operating system:
-AmigaOS
-
- Copy and then unpack the lha archive to a suitable location.
- All necessary files will be installed into Privoxy
- directory, including all configuration and log files. To uninstall, just
- remove this directory.
-
-
-
-
-FreeBSD
+FreeBSD
Privoxy is part of FreeBSD's Ports Collection, you can build and install
it with cd /usr/ports/www/privoxy; make install clean.
-
- If you don't use the ports, you can fetch and install
- the package with pkg_add -r privoxy.
-
-
- The port skeleton and the package can also be downloaded from the
- File Release
- Page, but there's no reason to use them unless you're interested in the
- beta releases which are only available there.
-
-
-
-
-Gentoo
-
- Gentoo source packages (Ebuilds) for Privoxy are
- contained in the Gentoo Portage Tree (they are not on the download page,
- but there is a Gentoo section, where you can see when a new
- Privoxy Version is added to the Portage Tree).
-
-
- Before installing Privoxy under Gentoo just do
- first emerge --sync to get the latest changes from the
- Portage tree. With emerge privoxy you install the latest
- version.
-
-
- Configuration files are in /etc/privoxy, the
- documentation is in /usr/share/doc/privoxy-&p-version;
- and the Log directory is in /var/log/privoxy.
-
@@ -428,14 +348,14 @@ How to install the binary packages depends on your operating system:
The most convenient way to obtain the Privoxy sources
is to download the source tarball from our
- project download
+ project download
page.
If you like to live on the bleeding edge and are not afraid of using
possibly unstable development versions, you can check out the up-to-the-minute
- version directly from the
+ version directly from the
CVS repository.
Keeping your Installation Up-to-Date
-
- As user feedback comes in and development continues, we will make updated versions
- of both the main actions file (as a separate
- package) and the software itself (including the actions file) available for
- download.
-
If you wish to receive an email notification whenever we release updates of
Privoxy or the actions file, subscribe
- to our announce mailing list, ijbswa-announce@lists.sourceforge.net.
+ url="https://lists.privoxy.org/mailman/listinfo/privoxy-announce">subscribe
+ to our announce mailing list, privoxy-announce@lists.privoxy.org.
@@ -486,5714 +399,2200 @@ How to install the binary packages depends on your operating system:
What's New in this Release
+
+&changelog;
+
+
+
+
+Note to Upgraders
+
- Privoxy 3.0.19 is a stable release.
- The changes since 3.0.18 stable are:
+ A quick list of things to be aware of before upgrading from earlier
+ versions of Privoxy:
-
+
+
+
+ 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
+ diff and maybe patch.
+
+
+ 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.
+
+
+
+
+ Note that some installers remove earlier versions completely,
+ including configuration files, therefore you should really save
+ any important configuration files!
+
+
+
+
+ On the other hand, other installers don't overwrite existing configuration
+ files, thinking you will want to do that yourself.
+
+
+
+
+ In the default configuration only fatal errors are logged now.
+ You can change that in the debug section
+ 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.
+
+
+
+
+
+ Three other config file settings are now off by default:
+ enable-remote-toggle,
+ enable-remote-http-toggle,
+ and enable-edit-actions.
+ If you use or want these, you will need to explicitly enable them, and
+ be aware of the security issues involved.
+
+
+
+
+
+
-
- The following changes were made between 3.0.17 and 3.0.18:
-
+
+
+
+Quickstart to Using Privoxy
-
-
- Bug fixes:
-
-
-
- If a generated redirect URL contains characters RFC 3986 doesn't
- permit, they are (re)encoded. Not doing this makes Privoxy versions
- from 3.0.5 to 3.0.17 susceptible to HTTP response splitting (CWE-113)
- attacks if the +fast-redirects{check-decoded-url} action is used.
-
-
-
-
- Fix a logic bug that could cause Privoxy to reuse a server
- socket after it got tainted by a server-header-tagger-induced
- block that was triggered before the whole server response had
- been read. If keep-alive was enabled and the request following
- the blocked one was to the same host and using the same forwarding
- settings, Privoxy would send it on the tainted server socket.
- While the server would simply treat it as a pipelined request,
- Privoxy would later on fail to properly parse the server's
- response as it would try to parse the unread data from the
- first response as server headers for the second one.
- Regression introduced in 3.0.17.
-
-
-
-
- When implying keep-alive in client_connection(), remember that
- the client didn't. Fixes a regression introduced in 3.0.13 that
- would cause Privoxy to wait for additional client requests after
- receiving a HTTP/1.1 request with "Connection: close" set
- and connection sharing enabled.
- With clients which terminates the client connection after detecting
- that the whole body has been received it doesn't really matter,
- but with clients that don't the connection would be kept open until
- it timed out.
-
-
-
-
- Fix a subtle race condition between prepare_csp_for_next_request()
- and sweep(). A thread preparing itself for the next client request
- could briefly appear to be inactive.
- If all other threads were already using more recent files,
- the thread could get its files swept away under its feet.
- So far this has only been reproduced while stress testing in
- valgrind while touching action files in a loop. It's unlikely
- to have caused any actual problems in the real world.
-
-
-
-
- Disable filters if SDCH compression is used unless filtering is forced.
- If SDCH was combined with a supported compression algorithm, Privoxy
- previously could try to decompress it and ditch the Content-Encoding
- header even though the SDCH compression wasn't dealt with.
- Reported by zebul666 in #3225863.
-
-
-
-
- Make a copy of the --user value and only mess with that when splitting
- user and group. On some operating systems modifying the value directly
- is reflected in the output of ps and friends and can be misleading.
- Reported by zepard in #3292710.
-
-
-
-
- If forwarded-connect-retries is set, only retry if Privoxy is actually
- forwarding the request. Previously direct connections would be retried
- as well.
-
-
-
-
- Fixed a small memory leak when retrying connections with IPv6
- support enabled.
-
-
-
-
- Remove an incorrect assertion in compile_dynamic_pcrs_job_list()
- It could be triggered by a pcrs job with an invalid pcre
- pattern (for example one that contains a lone quantifier).
-
-
-
-
- If the --user argument user[.group] contains a dot, always bail out
- if no group has been specified. Previously the intended, but undocumented
- (and apparently untested), behaviour was to try interpreting the whole
- argument as user name, but the detection was flawed and checked for '0'
- instead of '\0', thus merely preventing group names beginning with a zero.
-
-
-
-
- In html_code_map[], use a numeric character reference instead of '
- which wasn't standardized before XHTML 1.0.
-
-
-
-
- Fix an invalid free when compiled with FEATURE_GRACEFUL_TERMINATION
- and shut down through http://config.privoxy.org/die
-
-
-
-
- In get_actions(), fix the "temporary" backwards compatibility hack
- to accept block actions without reason.
- It also covered other actions that should be rejected as invalid.
- Reported by Billy Crook.
-
-
-
-
-
-
-
- General improvements:
-
-
-
- Privoxy can (re)compress buffered content before delivering
- it to the client. Disabled by default as most users wouldn't
- benefit from it.
-
-
-
-
- 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.
-
-
-
-
- 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.
-
-
-
-
- Allow to bind to multiple separate addresses.
- Patch set submitted by Petr Pisar in #3354485.
-
-
-
-
- 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.
-
-
-
-
- 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.
-
-
-
-
- When compiled without FEATURE_FAST_REDIRECTS, do not silently
- ignore +fast-redirect{} directives
-
-
-
-
- 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
-
-
-
-
- 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.
-
-
-
-
- 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.
-
-
-
-
- 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.
-
-
-
-
- In case of SOCKS5 failures, dump the socks response in the log message.
-
-
-
-
- Simplify the signal setup in main().
-
-
-
-
- Streamline socks5_connect() slightly.
-
-
-
-
- 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.
-
-
-
-
- In chat(), do not bother to generate a client request in case of
- direct CONNECT requests. It will not be used anyway.
-
-
-
-
- Reduce server_last_modified()'s stack size.
-
-
-
-
- Shorten get_http_time() by using strftime().
-
-
-
-
- Constify the known_http_methods pointers in unknown_method().
-
-
-
-
- Constify the time_formats pointers in parse_header_time().
-
-
-
-
- Constify the formerly_valid_actions pointers in action_used_to_be_valid().
-
-
-
-
- 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.
-
-
-
-
- Deduplicate the INADDR_NONE definition for Solaris by moving it to jbsockets.h
-
-
-
-
- In block_url(), ditch the obsolete workaround for ancient Netscape versions
- that supposedly couldn't properly deal with status code 403.
-
-
-
-
- Remove a useless NULL pointer check in load_trustfile().
-
-
-
-
- Remove two useless NULL pointer checks in load_one_re_filterfile().
-
-
-
-
- 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.
-
-
-
-
- Fix various typos. Fixes taken from Debian's 29_typos.dpatch by Roland Rosenfeld.
-
-
-
-
- Add a dok-tidy GNUMakefile target to clean up the messy HTML
- generated by the other dok targets.
-
-
-
-
- GNUisms in the GNUMakefile have been removed.
-
-
-
-
- Change the HTTP version in static responses to 1.1
-
-
-
-
- Synced config.sub and config.guess with upstream
- 2011-11-11/386c7218162c145f5f9e1ff7f558a3fbb66c37c5.
-
-
-
-
- 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.
-
-
-
-
- Terminate HTML lines in static error messages with \n instead of \r\n.
-
-
-
-
- Simplify cgi_error_unknown() a bit.
-
-
-
-
- In LogPutString(), don't bother looking at pszText when not
- actually logging anything.
-
-
-
-
- Change ssplit()'s fourth parameter from int to size_t.
- Fixes a clang complaint.
-
-
-
-
- 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.
-
-
-
-
- In rfc2553_connect_to(), start setting cgi->error_message on error.
-
-
-
-
- Change the expected status code returned for http://p.p/die depending
- on whether or not FEATURE_GRACEFUL_TERMINATION is available.
-
-
-
-
- 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.
-
-
-
-
- Add a proper CGI message for cgi_die().
-
-
-
-
- Don't enforce a logical line length limit in read_config_line().
-
-
-
-
- Slightly refactor server_last_modified() to remove useless gmtime*() calls.
-
-
-
-
- In get_content_type(), also recognize '.jpeg' as JPEG extension.
-
-
-
-
- Add '.png' to the list of recognized file extensions in get_content_type().
-
-
-
-
- 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.
-
-
-
-
- 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.
-
-
-
-
- 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.
-
-
-
-
- The socket timeout is used for SOCKS negotiations as well which
- previously couldn't timeout.
-
-
-
-
- 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.
-
-
-
-
- Treat all Content-Type header values containing the pattern
- 'script' as a sign of text. Reported by pribog in #3134970.
-
-
-
-
-
-
-
- Action file improvements:
-
-
-
- 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.
-
-
-
-
- Remove -prevent-compression from the fragile alias. It's no longer
- used anywhere by default and isn't known to break stuff anyway.
-
-
-
-
- Add a (disabled) section to block various Facebook tracking URLs.
- Reported by Dan Stahlke in #3421764.
-
-
-
-
- Add a (disabled) section to rewrite and redirect click-tracking
- URLs used on news.google.com.
- Reported by Dan Stahlke in #3421755.
-
-
-
-
- Unblock linuxcounter.net/.
- Reported by Dan Stahlke in #3422612.
-
-
-
-
- Block 'www91.intel.com/' which is used by Omniture.
- Reported by Adam Piggott in #3167370.
-
-
-
-
- Disable the handle-as-empty-doc-returns-ok option and mark it as deprecated.
- Reminded by tceverling in #2790091.
-
-
-
-
- Add ".ivwbox.de/" to the "Cross-site user tracking" section.
- Reported by Nettozahler in #3172525.
-
-
-
-
- Unblock and fast-redirect ".awin1.com/.*=http://".
- Reported by Adam Piggott in #3170921.
-
-
-
-
- Block "b.collective-media.net/".
-
-
-
-
- Widen the Debian popcon exception to "qa.debian.org/popcon".
- Seen in Debian's 05_default_action.dpatch by Roland Rosenfeld.
-
-
-
-
- Block ".gemius.pl/" which only seems to be used for user tracking.
- Reported by johnd16 in #3002731. Additional input from Lee and movax.
-
-
-
-
- Disable banners-by-size filters for '.thinkgeek.com/'.
- The filter only seems to catch pictures of the inventory.
-
-
-
-
- Block requests for 'go.idmnet.bbelements.com/please/showit/'.
- Reported by kacperdominik in #3372959.
-
-
-
-
- Unblock adainitiative.org/.
-
-
-
-
- Add a fast-redirects exception for '.googleusercontent.com/.*=cache'.
-
-
-
-
- Add a fast-redirects exception for webcache.googleusercontent.com/.
-
-
-
-
- Unblock http://adassier.wordpress.com/ and http://adassier.files.wordpress.com/.
-
-
-
-
-
-
-
- Filter file improvements:
-
-
-
- Let the yahoo filter hide '.ads'.
-
-
-
-
- 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'.
-
-
-
-
- Let the js-events filter additionally disarm setInterval().
- Suggested by dg1727 in #3423775.
-
-
-
-
-
-
-
- Documentation improvements:
-
-
-
- Clarify the effect of compiling Privoxy with zlib support.
- Suggested by dg1727 in #3423782.
-
-
-
-
- Point out that the SourceForge messaging system works like a black
- hole and should thus not be used to contact individual developers.
-
-
-
-
- Mention some of the problems one can experience when not explicitly
- configuring an IP addresses as listen address.
-
-
-
-
- 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.
-
-
-
-
-
-
-
- Log message improvements:
-
-
-
- If only the server connection is kept alive, do not pretend to
- wait for a new client request.
-
-
-
-
- Remove a superfluous log message in forget_connection().
-
-
-
-
- In chat(), properly report missing server responses as such
- instead of calling them empty.
-
-
-
-
- In forwarded_connect(), fix a log message nobody should ever see.
-
-
-
-
- Fix a log message in socks5_connect(), a failed write operation
- was logged as failed read operation.
-
-
-
-
- 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.
-
-
-
-
- Do not claim to listen on a socket until Privoxy actually does.
- Patch submitted by Petr Pisar #3354485
-
-
-
-
- Prevent a duplicated LOG_LEVEL_CLF message when sending out
- the "no-server-data" response.
-
-
-
-
- Also log the client socket when dropping a connection.
-
-
-
-
- Include the destination host in the 'Request ... marked for
- blocking. limit-connect{...} doesn't allow CONNECT ...' message
- Patch submitted by Saperski in #3296250.
-
-
-
-
- Prevent a duplicated log message if none of the resolved IP
- addresses were reachable.
-
-
-
-
- In connect_to(), do not pretend to retry if forwarded-connect-retries
- is zero or unset.
-
-
-
-
- When a specified user or group can't be found, put the name in
- single-quotes when logging it.
-
-
-
-
- In rfc2553_connect_to(), explain getnameinfo() errors better.
-
-
-
-
- Remove a useless log message in chat().
-
-
-
-
- When retrying to connect, also log the maximum number of connection
- attempts.
-
-
-
-
- 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.
-
-
-
-
- In a fatal error message in load_one_actions_file(), cover both
- URL and TAG patterns.
-
-
-
-
- In pcrs_strerror(), properly report unknown positive error code
- values as such. Previously they were handled like 0 (no error).
-
-
-
-
- In compile_dynamic_pcrs_job_list(), also log the actual error code as
- pcrs_strerror() doesn't handle all errors reported by pcre.
-
-
-
-
- Don't bother trying to continue chatting if the client didn't ask for it.
- Reduces log noise a bit.
-
-
-
-
- Make two fatal error message in load_one_actions_file() more descriptive.
-
-
-
-
- In cgi_send_user_manual(), log when rejecting a file name due to '/' or '..'.
-
-
-
-
- In load_file(), log a message if opening a file failed.
- The CGI error message alone isn't too helpful.
-
-
-
-
- In connection_destination_matches(), improve two log messages
- to help understand why the destinations don't match.
-
-
-
-
- Rephrase a log message in serve(). Client request arrival
- should be differentiated from closed client connections now.
-
-
-
-
- In serve(), log if a client connection isn't reused due to a
- configuration file change.
-
-
-
-
- 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.
-
-
-
-
-
-
-
- configure:
-
-
-
- Added a --disable-ipv6-support switch for platforms where support
- is detected but doesn't actually work.
-
-
-
-
- Do not check for the existence of strerror() and memmove() twice
-
-
-
-
- Remove a useless test for setpgrp(2). Privoxy doesn't need it and
- it can cause problems when cross-compiling.
-
-
-
-
- Rename the --disable-acl-files switch to --disable-acl-support.
- Since about 2001, ACL directives are specified in the standard
- config file.
-
-
-
-
- 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.
-
-
-
-
-
-
-
- Privoxy-Regression-Test:
-
-
-
- Added --shuffle-tests option to increase the chances of detection race conditions.
-
-
-
-
- Added a --local-test-file option that allows to use Privoxy-Regression-Test without Privoxy.
-
-
-
-
- Added tests for missing socks4 and socks4a forwarders.
-
-
-
-
- The --privoxy-address option now works with IPv6 addresses containing brackets, too.
-
-
-
-
- Perform limited sanity checks for parameters that are supposed to have numerical values.
-
-
-
-
- Added a --sleep-time option to specify a number of seconds to
- sleep between tests, defaults to 0.
-
-
-
-
- Disable the range-requests tagger for tests that break if it's enabled.
-
-
-
-
- Log messages use the ISO 8601 date format %Y-%m-%d.
-
-
-
-
- Fix spelling in two error messages.
-
-
-
-
- In the --help output, include a list of supported tests and their default levels.
-
-
-
-
- Adjust the tests to properly deal with FEATURE_TOGGLE being disabled.
-
-
-
-
-
-
-
- Privoxy-Log-Parser:
-
-
-
- Perform limited sanity checks for command line parameters that
- are supposed to have numerical values.
-
-
-
-
- Implement a --unbreak-lines-only option to try to revert MUA breakage.
-
-
-
-
- Accept and highlight: Added header: Content-Encoding: deflate
-
-
-
-
- Accept and highlight: Compressed content from 29258 to 8630 bytes.
-
-
-
-
- Accept and highlight: Client request arrived in time on socket 21.
-
-
-
-
- Highlight: Didn't receive data in time: a.fsdn.com:443
-
-
-
-
- Accept log messages with ISO 8601 time stamps, too.
-
-
-
-
-
-
-
- uagen:
-
-
-
- Bump generated Firefox version to 8.0.
-
-
-
-
- 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.
-
-
-
-
-
-
-
-
-
-
-
-
-Note to Upgraders
-
-
- A quick list of things to be aware of before upgrading from earlier
- versions of Privoxy:
-
-
-
-
-
-
-
- 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
- diff and maybe patch.
-
-
- 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.
-
-
-
-
- Note that some installers remove earlier versions completely,
- including configuration files, therefore you should really save
- any important configuration files!
-
-
-
-
- On the other hand, other installers don't overwrite existing configuration
- files, thinking you will want to do that yourself.
-
-
-
-
- standard.action has been merged into
- the default.action file.
-
-
-
-
- In the default configuration only fatal errors are logged now.
- You can change that in the debug section
- 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.
-
-
-
-
-
- Three other config file settings are now off by default:
- enable-remote-toggle,
- enable-remote-http-toggle,
- and enable-edit-actions.
- If you use or want these, you will need to explicitly enable them, and
- be aware of the security issues involved.
-
-
-
-
-
-
-
-
-
-
-
-
-
-Quickstart to Using Privoxy
-
-
-
-
-
- Install Privoxy. See the Installation Section below for platform specific
- information.
-
-
-
-
-
- Advanced users and those who want to offer Privoxy
- service to more than just their local machine should check the main config file, especially the security-relevant options. These are
- off by default.
-
-
-
-
-
- Start Privoxy, if the installation program has
- not done this already (may vary according to platform). See the section
- Starting Privoxy.
-
-
-
-
-
- Set your browser to use Privoxy as HTTP and
- HTTPS (SSL) proxy
- by setting the proxy configuration for address of
- 127.0.0.1 and port 8118.
- DO NOT activate proxying for FTP or
- any protocols besides HTTP and HTTPS (SSL) unless you intend to prevent your
- browser from using these protocols.
-
-
-
-
-
- Flush your browser's disk and memory caches, to remove any cached ad images.
- If using Privoxy to manage
- cookies,
- you should remove any currently stored cookies too.
-
-
-
-
-
- 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
- web-based action editor though.
- Be sure to read the warnings first.
-
-
- See the Configuration section for more
- configuration options, and how to customize your installation.
- You might also want to look at the next section for a quick
- introduction to how Privoxy blocks ads and
- banners.
-
-
-
-
-
- If you experience ads that slip through, innocent images that are
- blocked, or otherwise feel the need to fine-tune
- Privoxy's behavior, take a look at the actions files. As a quick start, you might
- find the richly commented examples
- helpful. You can also view and edit the actions files through the web-based user interface. The
- Appendix Troubleshooting: Anatomy of an
- Action has hints on how to understand and debug actions that
- misbehave.
-
-
-
-
-
-
-
- Please see the section Contacting the
- Developers on how to report bugs, problems with websites or to get
- help.
-
-
-
-
-
- Now enjoy surfing with enhanced control, comfort and privacy!
-
-
-
-
-
-
-
-
-
-
-Quickstart to Ad Blocking
-
-
- Ad blocking is but one of Privoxy's
- 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.
-
-
- 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.
-
-
- 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
- problem sites, and to spend more time adjusting the
- configuration to solve these unintended consequences. In short, there is
- not an easy way to eliminate all ads. Either take
- the easy way and settle for most ads blocked with the
- default configuration, or jump in and tweak it for your personal surfing
- habits and preferences.
-
-
- Secondly, a brief explanation of Privoxy's
- actions. Actions in this context, are
- the directives we use to tell Privoxy to perform
- some task relating to HTTP transactions (i.e. web browsing). We tell
- Privoxy to take some action. Each
- action has a unique name and function. While there are many potential
- actions in Privoxy's
- arsenal, only a few are used for ad blocking. Actions, and action
- configuration files, are explained in depth below.
-
-
- Actions are specified in Privoxy's configuration,
- followed by one or more URLs to which the action should apply. URLs
- can actually be URL type patterns 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.
-
-
- When you connect to a website, the full URL will either match one or more
- of the sections as defined in Privoxy's configuration,
- or not. If so, then Privoxy 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.
-
-
-
- The most important actions for basic ad blocking are: block, handle-as-image,
- handle-as-empty-document,and
- set-image-blocker:
-
-
-
-
-
-
-
- block - 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
- Privoxy's own built-in BLOCKED page instead to
- let you now what has happened (with some exceptions, see below).
-
-
-
-
-
- handle-as-image -
- tells Privoxy to treat this URL as an image.
- Privoxy'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
- Privoxy BLOCKED page (which would only result in
- a broken image 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.
-
-
-
-
-
- handle-as-empty-document -
- sends an empty document instead of Privoxy's
- normal BLOCKED HTML page. This is useful for file types that are neither
- HTML nor images, such as blocking JavaScript files.
-
-
-
-
-
- set-image-blocker - tells
- Privoxy 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
- block action somewhere in the
- configuration, and, it must also match an
- handle-as-image action.
-
-
- The configuration options on what to display instead of the ad are:
-
-
-
- pattern - a checkerboard pattern, so that an ad
- replacement is obvious. This is the default.
-
-
-
-
- blank - A very small empty GIF image is displayed.
- This is the so-called invisible configuration option.
-
-
-
-
- http://<URL> - A redirect to any image anywhere
- of the user's choosing (advanced usage).
-
-
-
-
-
-
-
-
- Advanced users will eventually want to explore &my-app;
- filters as well. Filters
- are very different from blocks.
- A block 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 no-no for
- nasty-word. 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.
-
-
-
- The quickest way to adjust any of these settings is with your browser through
- the special Privoxy editor at http://config.privoxy.org/show-status
- (shortcut: http://p.p/show-status). This
- is an internal page, and does not require Internet access.
-
-
-
- Note that as of Privoxy 3.0.7 beta the
- action editor is disabled by default. Check the
- enable-edit-actions
- section in the configuration file to learn why and in which
- cases it's safe to enable again.
-
-
-
- If you decided to enable the action editor, select the appropriate
- actions file, and click
- Edit. It is best to put personal or
- local preferences in user.action since this is not
- meant to be overwritten during upgrades, and will over-ride the settings in
- other files. Here you can insert new actions, and URLs for ad
- blocking or other purposes, and make other adjustments to the configuration.
- Privoxy will detect these changes automatically.
-
-
-
- A quick and simple step by step example:
-
-
-
-
-
-
-
- Right click on the ad image to be blocked, then select
- Copy Link Location from the
- pop-up menu.
-
-
-
-
- Set your browser to
- http://config.privoxy.org/show-status
-
-
-
-
- Find user.action in the top section, and click
- on Edit:
-
-
-
-
-
-
-
-
-
-
- You should have a section with only
- block listed under
- Actions:.
- If not, click a Insert new section below
- button, and in the new section that just appeared, click the
- Edit button right under the word Actions:.
- This will bring up a list of all actions. Find
- block near the top, and click
- in the Enabled column, then Submit
- just below the list.
-
-
-
-
- Now, in the block actions section,
- click the Add button, and paste the URL the
- browser got from Copy Link Location.
- Remove the http:// at the beginning of the URL. Then, click
- Submit (or
- OK if in a pop-up window).
-
-
-
-
- Now go back to the original page, and press SHIFT-Reload
- (or flush all browser caches). The image should be gone now.
-
-
-
-
-
-
-
- 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 patterns, and
- the entire actions concept, see the Actions
- section.
-
-
-
- For advanced users who want to hand edit their config files, you might want
- to now go to the Actions Files Tutorial.
- The ideas explained therein also apply to the web-based editor.
-
-
- There are also various
- filters that can be used for ad blocking
- (filters are a special subset of actions). These
- fall into the advanced usage category, and are explained in
- depth in later sections.
-
-
-
-
-
-
-
-
-
-
-
-Starting Privoxy
-
- Before launching Privoxy for the first time, you
- will want to configure your browser(s) to use
- Privoxy as a HTTP and HTTPS (SSL)
- proxy. 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 that must be done
-!
-
-
- Please note that Privoxy can only proxy HTTP and
- HTTPS traffic. It will not work with FTP or other protocols.
-
-
-
-
-
-
-
-
-
- With Firefox, this is typically set under:
-
-
-
- Tools -> Options -> Advanced -> Network ->Connection -> Settings
-
-
-
-
- Or optionally on some platforms:
-
-
-
- Edit -> Preferences -> General -> Connection Settings -> Manual Proxy Configuration
-
-
-
-
-
- With Netscape (and
- Mozilla), this can be set under:
-
-
-
-
-
-
- Edit -> Preferences -> Advanced -> Proxies -> HTTP Proxy
-
-
-
-
- For Internet Explorer v.5-7:
-
-
-
- Tools -> Internet Options -> Connections -> LAN Settings
-
-
-
- Then, check Use Proxy 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 Secure). Make sure any
- checkboxes like Use the same proxy server for all protocols is
- UNCHECKED. You want only HTTP and HTTPS (SSL)!
-
-
-
-
-
-
-
-
-
- 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 cookies,
- if you want Privoxy to manage that. You are now
- ready to start enjoying the benefits of using
- Privoxy!
-
-
-
- Privoxy 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, Privoxy
- will look for a file named config in the current
- directory. Except on Win32 where it will try config.txt.
-
-
-
-Red Hat and Fedora
-
- A default Red Hat installation may not start &my-app; upon boot. It will use
- the file /etc/privoxy/config as its main configuration
- file.
-
-
-
- # /etc/rc.d/init.d/privoxy start
-
-
-
- Or ...
-
-
-
- # service privoxy start
-
-
-
-
-
-Debian
-
- We use a script. Note that Debian typically starts &my-app; upon booting per
- default. It will use the file
- /etc/privoxy/config as its main configuration
- file.
-
-
-
- # /etc/init.d/privoxy start
-
-
-
-
-
-Windows
-
-Click on the &my-app; Icon to start Privoxy. If no configuration file is
- specified on the command line, Privoxy will look
- for a file named config.txt. Note that Windows will
- automatically start &my-app; when the system starts if you chose that option
- when installing.
-
-
- Privoxy 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
- Windows Installation
- instructions for details.
-
-
-
-
-Solaris, NetBSD, FreeBSD, HP-UX and others
-
-Example Unix startup command:
-
-
-
- # /usr/sbin/privoxy /etc/privoxy/config
-
-
-
-
-
-OS/2
-
- During installation, Privoxy is configured to
- start automatically when the system restarts. You can start it manually by
- double-clicking on the Privoxy icon in the
- Privoxy folder.
-
-
-
-
-Mac OS X
-
- After downloading the privoxy software, unzip the downloaded file by
- double-clicking on the zip file icon. Then, double-click on the
- installer package icon and follow the installation process.
-
-
- The privoxy service will automatically start after a successful
- installation. In addition, the privoxy service will automatically
- start every time your computer starts up.
-
-
- To prevent the privoxy service from automatically starting when your
- computer starts up, remove or rename the folder named
- /Library/StartupItems/Privoxy.
-
-
- A simple application named Privoxy Utility has been created which
- enables administrators to easily start and stop the privoxy service.
-
-
- In addition, the Privoxy Utility presents a simple way for
- administrators to edit the various privoxy config files. A method
- to uninstall the software is also available.
-
-
- An administrator username and password must be supplied in order for
- the Privoxy Utility to perform any of the tasks.
-
-
-
-
-
-AmigaOS
-
- Start Privoxy (with RUN <>NIL:) in your
- startnet script (AmiTCP), in
- s:user-startup (RoadShow), as startup program in your
- startup script (Genesis), or as startup action (Miami and MiamiDx).
- Privoxy will automatically quit when you quit your
- TCP/IP stack (just ignore the harmless warning your TCP/IP stack may display that
- Privoxy is still running).
-
-
-
-
-Gentoo
-
- A script is again used. It will use the file /etc/privoxy/config
- as its main configuration file.
-
-
-
- /etc/init.d/privoxy start
-
-
-
- Note that Privoxy is not automatically started at
- boot time by default. You can change this with the rc-update
- command.
-
-
-
- rc-update add privoxy default
-
-
-
-
-
-
-
-
-Command Line Options
-
- Privoxy may be invoked with the following
- command-line options:
-
-
-
-
-
-
-
- --config-test
-
-
- 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.
-
-
- 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).
-
-
- This option doesn't affect the log setting, combination with
- --no-daemon is recommended if a configured
- log file shouldn't be used.
-
-
-
-
- --version
-
-
- Print version info and exit. Unix only.
-
-
-
-
- --help
-
-
- Print short usage info and exit. Unix only.
-
-
-
-
- --no-daemon
-
-
- Don't become a daemon, i.e. don't fork and become process group
- leader, and don't detach from controlling tty. Unix only.
-
-
-
-
- --pidfile FILE
-
-
- On startup, write the process ID to FILE. Delete the
- FILE on exit. Failure to create or delete the
- FILE is non-fatal. If no FILE
- option is given, no PID file will be used. Unix only.
-
-
-
-
- --user USER[.GROUP]
-
-
- After (optionally) writing the PID file, assume the user ID of
- USER, and if included the GID of GROUP. Exit if the
- privileges are not sufficient to do so. Unix only.
-
-
-
-
- --chroot
-
-
- Before changing to the user ID given in the --user 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.
-
-
-
-
- --pre-chroot-nslookup hostname
-
-
- 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.
-
-
- 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.
-
-
-
-
-
- configfile
-
-
- If no configfile is included on the command line,
- Privoxy will look for a file named
- config in the current directory (except on Win32
- where it will look for config.txt instead). Specify
- full path to avoid confusion. If no config file is found,
- Privoxy will fail to start.
-
-
-
-
-
-
-
- On MS Windows only there are two additional
- command-line options to allow Privoxy to install and
- run as a service. See the
-Window Installation section
-for details.
-
-
-
-
-
-
-
-
-
-
-Privoxy Configuration
-
- All Privoxy configuration is stored
- in text files. These files can be edited with a text editor.
- Many important aspects of Privoxy can
- also be controlled easily with a web browser.
-
-
-
-
-
-
-Controlling Privoxy with Your Web Browser
-
- Privoxy's user interface can be reached through the special
- URL http://config.privoxy.org/
- (shortcut: http://p.p/),
- which is a built-in page and works without Internet access.
- You will see the following section:
-
-
-
-
-
-
- Privoxy Menu
-
-
-
- ▪ View & change the current configuration
-
-
- ▪ View the source code version numbers
-
-
- ▪ View the request headers.
-
-
- ▪ Look up which actions apply to a URL and why
-
-
- ▪ Toggle Privoxy on or off
-
-
- ▪ Documentation
-
-
-
-
-
-
-
- This should be self-explanatory. Note the first item leads to an editor for the
- actions files, which is where the ad, banner,
- cookie, and URL blocking magic is configured as well as other advanced features of
- Privoxy. This is an easy way to adjust various
- aspects of Privoxy configuration. The actions
- file, and other configuration files, are explained in detail below.
-
-
-
- Toggle Privoxy On or Off 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 Privoxy
- causing the problem or not. Privoxy continues
- to run as a proxy in this case, but all manipulation is disabled, i.e.
- Privoxy acts like a normal forwarding proxy. There
- is even a toggle Bookmarklet offered, so
- that you can toggle Privoxy with one click from
- your browser.
-
-
-
- Note that several of the features described above are disabled by default
- in Privoxy 3.0.7 beta and later.
- Check the
- configuration file to learn why
- and in which cases it's safe to enable them again.
-
-
-
-
-
-
-
-
-
-
-
-
-Configuration Files Overview
-
- For Unix, *BSD and Linux, all configuration files are located in
- /etc/privoxy/ by default. For MS Windows, OS/2, and
- AmigaOS these are all in the same directory as the
- Privoxy executable.
-
-
-
- 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:
-
-
-
-
-
-
-
- The main configuration file is named config
- on Linux, Unix, BSD, OS/2, and AmigaOS and config.txt
- on Windows. This is a required file.
-
-
-
-
-
- match-all.action is used to define which actions
- 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.
-
-
- default.action defines many exceptions (both positive and negative)
- from the default set of actions that's configured in match-all.action.
- It should be the second actions file loaded and shouldn't be edited by the user.
-
-
- Multiple actions files may be defined in config. These
- are processed in the order they are defined. Local customizations and locally
- preferred exceptions to the default policies as defined in
- match-all.action (which you will most probably want
- to define sooner or later) are best applied in user.action,
- 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.
-
-
- There is also a web based editor that can be accessed from
- http://config.privoxy.org/show-status
- (Shortcut: http://p.p/show-status) for the
- various actions files.
-
-
-
-
-
- Filter files (the filter
- file) 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.
- default.filter 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 config as you can with
- actions files. We suggest user.filter for any
- locally defined filters or customizations.
-
-
-
-
-
-
-
- The syntax of the configuration and filter files may change between different
- Privoxy versions, unfortunately some enhancements cost backwards compatibility.
-
-
-
-
- All files use the # character to denote a
- comment (the rest of the line will be ignored) and understand line continuation
- through placing a backslash ("\") as the very last character
- in a line. If the # is preceded by a backslash, it looses
- its special function. Placing a # in front of an otherwise
- valid configuration line to prevent it from being interpreted is called "commenting
- out" that line. Blank lines are ignored.
-
-
-
- The actions files and filter files
- can use Perl style regular expressions for
- maximum flexibility.
-
-
-
- After making any changes, there is no need to restart
- Privoxy in order for the changes to take
- effect. Privoxy 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 Privoxy, these wake up requests
- must obviously be sent to the old listening address.
-
-
-
- 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 default setting, may change, so
- please check all your configuration files on important issues.
-
-]]>
-
-
-
-
-
-
-
-
-
-
-
- &config;
-
-
-
-
-
-
-
-
-
-Actions Files
-
-
-
-
- The actions files are used to define what actions
- Privoxy 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.
-
-
- There
- are three action files included with Privoxy with
- differing purposes:
-
-
-
-
-
- match-all.action - is used to define which
- actions 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
-
-
-
-
- default.action - defines many exceptions (both
- positive and negative) from the default set of actions that's configured
- in match-all.action. 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.
-
-
-
-
- user.action - 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.
-
-
-
-
- EditSet to CautiousSet to MediumSet to Advanced
-
-
- These have increasing levels of aggressiveness and have no
- influence on your browsing unless you select them explicitly in the
- editor. A default installation should be pre-set to
- Cautious. 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.
-
-
- The Edit button allows you to turn each
- action on/off individually for fine-tuning. The Cautious
- 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
- Medium button sets the list to a medium level of
- other features and a low level set of privacy features. The
- Advanced 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
- Edit button. More fine-tuning can be done in the
- lower sections of this internal page.
-
-
- 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.
-
-
- The default profiles, and their associated actions, as pre-defined in
- default.action are:
-
-
-
Default Configurations
-
-
-
-
-
-
-
- Feature
- Cautious
- Medium
- Advanced
-
-
-
-
-
-
-
-
-
-
-
-
-
- Ad-blocking Aggressiveness
- medium
- high
- high
-
-
-
- Ad-filtering by size
- no
- yes
- yes
-
-
-
- Ad-filtering by link
- no
- no
- yes
-
-
- Pop-up killing
- blocks only
- blocks only
- blocks only
-
-
-
- Privacy Features
- low
- medium
- medium/high
-
-
-
- Cookie handling
- none
- session-only
- kill
-
-
-
- Referer forging
- no
- yes
- yes
-
-
-
- GIF de-animation
- no
- yes
- yes
-
-
-
- Fast redirects
- no
- no
- yes
-
-
-
- HTML taming
- no
- no
- yes
-
-
-
- JavaScript taming
- no
- no
- yes
-
-
-
- Web-bug killing
- no
- yes
- yes
-
-
-
- Image tag reordering
- no
- yes
- yes
-
-
-
-
-
-
-
-
-
-
-
-
- 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.
- default.action is typically processed before
- user.action). The content of these can all be viewed and
- edited from http://config.privoxy.org/show-status.
- 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 default.action),
- followed by any exceptions (typically also in
- default.action), which are then followed lastly by any
- local preferences (typically in user.action).
- Generally, user.action has the last word.
-
-
-
- An actions file typically has multiple sections. If you want to use
- aliases in an actions file, you have to place the (optional)
- alias section at the top of that file.
- Then comes the default set of rules which will apply universally to all
- sites and pages (be very careful with using such a
- universal set in user.action or any other actions file after
- default.action, because it will override the result
- from consulting any previous file). And then below that,
- exceptions to the defined universal policies. You can regard
- user.action as an appendix to default.action,
- with the advantage that it is a separate file, which makes preserving your
- personal settings across Privoxy upgrades easier.
-
-
-
- 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 complete list
- of actions.
-
-
-
-
-Finding the Right Mix
-
- Note that some actions, 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
- aggressive your default settings (in the top section of the
- actions file) are, the more exceptions for trusted 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.
-
-
-
- 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 :).
-
-
-
-
-
-How to Edit
-
- The easiest way to edit the actions files is with a browser by
- using our browser-based editor, which can be reached from http://config.privoxy.org/show-status.
- Note: the config file option enable-edit-actions 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 Cautious, Medium or
- Advanced. Warning: the Advanced setting is more
- aggressive, and will be more likely to cause problems for some sites.
- Experienced users only!
-
-
-
- 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
- default.action which is richly commented with many
- good examples.
-
-
-
-
-
-How Actions are Applied to Requests
-
- Actions files are divided into sections. There are special sections,
- like the alias 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.
-
-
-
- To determine which actions apply to a request, the URL of the request is
- compared to all URL patterns in each action file.
- 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.
-
-
-
- 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 {
- +handle-as-image },
- then later another one with just {
- +block }, resulting
- in both actions to apply. And there may well be
- cases where you will want to combine actions together. Such a section then
- might look like:
-
-
-
-
- { +handle-as-image +block{Banner ads.} }
- # Block these as if they were images. Send no block page.
- banners.example.com
- media.example.com/.*banners
- .example.com/images/ads/
-
-
-
- You can trace this process for URL patterns and any given URL by visiting http://config.privoxy.org/show-url-info.
-
-
-
- Examples and more detail on this is provided in the Appendix,
- Troubleshooting: Anatomy of an Action section.
-
-
-
-
-
-Patterns
-
- As mentioned, Privoxy uses patterns
- to determine what actions might apply to which sites and
- pages your browser attempts to access. These patterns use wild
- card type pattern matching to achieve a high degree of
- flexibility. This allows one expression to be expanded and potentially match
- against many similar patterns.
-
-
-
- Generally, an URL pattern has the form
- <domain><port>/<path>, where the
- <domain>, the <port>
- and the <path> are optional. (This is why the special
- / pattern matches all URLs). Note that the protocol
- portion of the URL pattern (e.g. http://) should
- not be included in the pattern. This is assumed already!
-
-
- 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
- Regular
- Expressions (POSIX 1003.2).
-
-
- The port part of a pattern is a decimal port number preceded by a colon
- (:). If the domain part contains a numerical IPv6 address,
- it has to be put into angle brackets
- (<, >).
-
-
-
-
- www.example.com/
-
-
- is a domain-only pattern and will match any request to www.example.com,
- 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 example.com is different and would NOT match.
-
-
-
-
- www.example.com
-
-
- means exactly the same. For domain-only patterns, the trailing / may
- be omitted.
-
-
-
-
- www.example.com/index.html
-
-
- matches all the documents on www.example.com
- whose name starts with /index.html.
-
-
-
-
- www.example.com/index.html$
-
-
- matches only the single document /index.html
- on www.example.com.
-
-
-
-
- /index.html$
-
-
- matches the document /index.html, regardless of the domain,
- i.e. on any web server anywhere.
-
-
-
-
- /
-
-
- Matches any URL because there's no requirement for either the
- domain or the path to match anything.
-
-
-
-
- :8000/
-
-
- Matches any URL pointing to TCP port 8000.
-
-
-
-
- <2001:db8::1>/
-
-
- Matches any URL with the host address 2001:db8::1.
- (Note that the real URL uses plain brackets, not angle brackets.)
-
-
-
-
- index.html
-
-
- matches nothing, since it would be interpreted as a domain name and
- there is no top-level domain called .html. So its
- a mistake.
-
-
-
-
-
-
-
-The Domain Pattern
-
-
- 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:
-
-
-
-
- .example.com
-
-
- matches any domain with first-level domain com
- and second-level domain example.
- For example www.example.com,
- example.com and foo.bar.baz.example.com.
- Note that it wouldn't match if the second-level domain was another-example.
-
-
-
-
- www.
-
-
- matches any domain that STARTS with
- www. (It also matches the domain
- www but most of the time that doesn't matter.)
-
-
-
-
- .example.
-
-
- matches any domain that CONTAINS.example..
- 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 example as
- a domain.) This might be www.example.com,
- news.example.de, or
- www.example.net/cgi/testing.pl for instance. All these
- cases are matched.
-
-
-
-
-
-
- Additionally, there are wild-cards that you can use in the domain names
- themselves. These work similarly to shell globbing type wild-cards:
- * represents zero or more arbitrary characters (this is
- equivalent to the
- Regular
- Expression based syntax of .*),
- ? represents any single character (this is equivalent to the
- regular expression syntax of a simple .), and you can define
- character classes in square brackets which is similar to
- the same regular expression technique. All of this can be freely mixed:
-
-
-
-
- ad*.example.com
-
-
- matches adserver.example.com,
- ads.example.com, etc but not sfads.example.com
-
-
-
-
- *ad*.example.com
-
-
- matches all of the above, and then some.
-
-
-
-
- .?pix.com
-
-
- matches www.ipix.com,
- pictures.epix.com, a.b.c.d.e.upix.com etc.
-
-
-
-
- www[1-9a-ez].example.c*
-
-
- matches www1.example.com,
- www4.example.cc, wwwd.example.cy,
- wwwz.example.com etc., but not
- wwww.example.com.
-
-
-
-
-
-
- While flexible, this is not the sophistication of full regular expression based syntax.
-
-
-
-
-
-
-
-
-The Path Pattern
-
-
- Privoxy uses modern POSIX 1003.2
- Regular
- Expressions for matching the path portion (after the slash),
- and is thus more flexible.
-
-
-
- There is an Appendix with a brief quick-start into regular
- expressions, you also might want to have a look at your operating system's documentation
- on regular expressions (try man re_format).
-
-
-
- Note that the path pattern is automatically left-anchored at the /,
- i.e. it matches as if it would start with a ^ (regular expression speak
- for the beginning of a line).
-
-
-
- Please also note that matching in the path is CASE INSENSITIVE
- by default, but you can switch to case sensitive at any point in the pattern by using the
- (?-i) switch: www.example.com/(?-i)PaTtErN.* will match
- only documents whose path starts with PaTtErN in
- exactly this capitalization.
-
-
-
-
- .example.com/.*
-
-
- Is equivalent to just .example.com, since any documents
- within that domain are matched with or without the .*
- regular expression. This is redundant
-
-
-
-
- .example.com/.*/index.html$
-
-
- Will match any page in the domain of example.com that is
- named index.html, and that is part of some path. For
- example, it matches www.example.com/testing/index.html but
- NOT www.example.com/index.html because the regular
- expression called for at least two /'s, thus the path
- requirement. It also would match
- www.example.com/testing/index_html, because of the
- special meta-character ..
-
-
-
-
- .example.com/(.*/)?index\.html$
-
-
- This regular expression is conditional so it will match any page
- named index.html regardless of path which in this case can
- have one or more /'s. And this one must contain exactly
- .html (but does not have to end with that!).
-
-
-
-
- .example.com/(.*/)(ads|banners?|junk)
-
-
- This regular expression will match any path of example.com
- that contains any of the words ads, banner,
- banners (because of the ?) or junk.
- The path does not have to end in these words, just contain them.
-
-
-
-
- .example.com/(.*/)(ads|banners?|junk)/.*\.(jpe?g|gif|png)$
-
-
- This is very much the same as above, except now it must end in either
- .jpg, .jpeg, .gif or .png. So this
- one is limited to common image formats.
-
-
-
-
-
-
- There are many, many good examples to be found in default.action,
- and more tutorials below in Appendix on regular expressions.
-
-
-
-
-
-
-
-
-The Tag Pattern
-
-
- Tag patterns are used to change the applying actions based on the
- request's tags. Tags can be created with either the
- client-header-tagger
- or the server-header-tagger action.
-
-
-
- Tag patterns have to start with TAG:, 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 ^,
- you have to do it yourself if you need it).
-
-
-
- To match all requests that are tagged with foo
- your pattern line should be TAG:^foo$,
- TAG:foo would work as well, but it would also
- match requests whose tags contain foo somewhere.
- TAG: foo wouldn't work as it requires white space.
-
-
-
- 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.
-
-
-
- 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.
-
-
-
- For example you could tag client requests which use the
- POST 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.
-
-
-
- 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.
-
-
-
-
-
-
-
-
-
-
-
-
-Actions
-
- All actions are disabled by default, until they are explicitly enabled
- somewhere in an actions file. Actions are turned on if preceded with a
- +, and turned off if preceded with a -. So a
- +action means do that action, e.g.
- +block means please block URLs that match the
- following patterns, and -block means don't
- block URLs that match the following patterns, even if +block
- previously applied.
-
-
-
-
- Again, actions are invoked by placing them on a line, enclosed in curly braces and
- separated by whitespace, like in
- {+some-action -some-other-action{some-parameter}},
- 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.
-
-
-
- Actions fall into three categories:
-
-
-
-
-
-
- Boolean, i.e the action can only be enabled or
- disabled. Syntax:
-
-
-
- +name # enable action name
- -name # disable action name
-
-
- Example: +handle-as-image
-
-
-
-
-
-
- Parameterized, where some value is required in order to enable this type of action.
- Syntax:
-
-
-
- +name{param} # enable action and set parameter to param,
- # overwriting parameter from previous match if necessary
- -name # disable action. The parameter can be omitted
-
-
- 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.
-
-
- Example: +hide-user-agent{Mozilla/5.0 (X11; U; FreeBSD i386; en-US; rv:1.8.1.4) Gecko/20070602 Firefox/2.0.0.4}
-
-
-
-
-
- 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, all the parameters
- from all 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:
-
-
-
- +name{param} # enable action and add param to the list of parameters
- -name{param} # remove the parameter param from the list of parameters
- # If it was the last one left, disable the action.
- -name # disable this action completely and remove all parameters from the list
-
-
- Examples: +add-header{X-Fun-Header: Some text} and
- +filter{html-annoyances}
-
-
-
-
-
-
-
- If nothing is specified in any actions file, no actions are
- taken. So in this case Privoxy 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).
-
-
-
- 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 user.action). 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 config (the default
- installation has three actions files). It also quite possible for any given
- URL to match more than one pattern (because of wildcards and
- regular expressions), and thus to trigger more than one set of actions! Last
- match wins.
-
-
-
-
- The list of valid Privoxy actions are:
-
-
-
-
-
-
-
-
-
-
-
-
-
-add-header
-
-
-
- Typical use:
-
- Confuse log analysis, custom applications
-
-
-
-
- Effect:
-
-
- Sends a user defined HTTP header to the web server.
-
-
-
-
-
- Type:
-
-
- Multi-value.
-
-
-
-
- Parameter:
-
-
- Any string value is possible. Validity of the defined HTTP headers is not checked.
- It is recommended that you use the X- prefix
- for custom headers.
-
-
-
-
-
- Notes:
-
-
- 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
- HTTP headers are, you definitely don't need to worry about this
- one.
-
-
- Headers added by this action are not modified by other actions.
-
-
-
-
-
- Example usage:
-
-
- +add-header{X-User-Tracking: sucks}
-
-
-
-
-
-
-
-
-
-block
-
-
-
- Typical use:
-
- Block ads or other unwanted content
-
-
-
-
- Effect:
-
-
- 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 handle-as-image,
- set-image-blocker, and
- handle-as-empty-document actions.
-
-
-
-
-
-
- Type:
-
-
- Parameterized.
-
-
-
-
- Parameter:
-
- A block reason that should be given to the user.
-
-
-
-
- Notes:
-
-
- Privoxy sends a special BLOCKED page
- for requests to blocked pages. This page contains the block reason given as
- parameter, a link to find out why the block action applies, and a click-through
- to the blocked content (the latter only if the force feature is available and
- enabled).
-
-
- A very important exception occurs if both
- block and handle-as-image,
- apply to the same request: it will then be replaced by an image. If
- set-image-blocker
- (see below) also applies, the type of image will be determined by its parameter,
- if not, the standard checkerboard pattern is sent.
-
-
- It is important to understand this process, in order
- to understand how Privoxy deals with
- ads and other unwanted content. Blocking is a core feature, and one
- upon which various other features depend.
-
-
- The filter
- action can perform a very similar task, by blocking
- 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.
-
-
-
-
-
- Example usage (section):
-
-
- {+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$
-
-
-
-
-
-
-
-
-
-
-
-change-x-forwarded-for
-
-
-
- Typical use:
-
- Improve privacy by not forwarding the source of the request in the HTTP headers.
-
-
-
-
- Effect:
-
-
- Deletes the X-Forwarded-For: HTTP header from the client request,
- or adds a new one.
-
-
-
-
-
- Type:
-
-
- Parameterized.
-
-
-
-
- Parameter:
-
-
-
- block to delete the header.
-
-
-
- add to create the header (or append
- the client's IP address to an already existing one).
-
-
-
-
-
-
-
- Notes:
-
-
- It is safe and recommended to use block.
-
-
- Forwarding the source address of the request may make
- sense in some multi-user setups but is also a privacy risk.
-
-
-
-
- Example usage:
-
-
- +change-x-forwarded-for{block}
-
-
-
-
-
-
-
-
-client-header-filter
-
-
-
- Typical use:
-
-
- Rewrite or remove single client headers.
-
-
-
-
-
- Effect:
-
-
- All client headers to which this action applies are filtered on-the-fly through
- the specified regular expression based substitutions.
-
-
-
-
-
- Type:
-
-
- Parameterized.
-
-
-
-
- Parameter:
-
-
- The name of a client-header filter, as defined in one of the
- filter files.
-
-
-
-
-
- Notes:
-
-
- 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.
-
-
- Client-header filters are executed after the other header actions have finished
- and use their output as input.
-
-
- 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.
-
-
- Please refer to the filter file chapter
- to learn which client-header filters are available by default, and how to
- create your own.
-
-
-
-
-
-
- Example usage (section):
-
-
-
-# Hide Tor exit notation in Host and Referer Headers
-{+client-header-filter{hide-tor-exit-notation}}
-/
-
-
-
-
-
-
-
-
-
-
-
-client-header-tagger
-
-
-
- Typical use:
-
-
- Block requests based on their headers.
-
-
-
-
-
- Effect:
-
-
- 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.
-
-
-
-
-
- Type:
-
-
- Parameterized.
-
-
-
-
- Parameter:
-
-
- The name of a client-header tagger, as defined in one of the
- filter files.
-
-
-
-
-
- Notes:
-
-
- Client-header taggers are applied to each header on its own,
- and as the header isn't modified, each tagger sees
- the original.
-
-
- Client-header taggers are the first actions that are executed
- and their tags can be used to control every other action.
-
-
-
-
-
- Example usage (section):
-
-
-
-# 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/
-
-
-
-
-# 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$
-
-
-
-
-
-
-
-
-
-
-
-content-type-overwrite
-
-
-
- Typical use:
-
- Stop useless download menus from popping up, or change the browser's rendering mode
-
-
-
-
- Effect:
-
-
- Replaces the Content-Type: HTTP server header.
-
-
-
-
-
- Type:
-
-
- Parameterized.
-
-
-
-
- Parameter:
-
-
- Any string.
-
-
-
-
-
- Notes:
-
-
- The Content-Type: 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.
-
-
- The declared content type can also affect which rendering mode
- the browser chooses. If XHTML is delivered as text/html,
- many browsers treat it as yet another broken HTML document.
- If it is send as application/xml, browsers with
- XHTML support will only display it, if the syntax is correct.
-
-
- If you see a web site that proudly uses XHTML buttons, but sets
- Content-Type: text/html, you can use &my-app;
- to overwrite it with application/xml and validate
- the web master's claim inside your XHTML-supporting browser.
- If the syntax is incorrect, the browser will complain loudly.
-
-
- 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
- text/html and have it rendered as broken HTML document.
-
-
- By default content-type-overwrite only replaces
- Content-Type: headers that look like some kind of text.
- If you want to overwrite it unconditionally, you have to combine it with
- force-text-mode.
- This limitation exists for a reason, think twice before circumventing it.
-
-
- Most of the time it's easier to replace this action with a custom
- server-header filter.
- 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.
-
-
- Of course you can apply content-type-overwrite
- to a whole site and then make URL based exceptions, but it's a lot
- more work to get the same precision.
-
-
-
-
-
- Example usage (sections):
-
-
- # 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
-
-
-
-
-
-
-
-
-
-
-
-crunch-client-header
-
-
-
- Typical use:
-
- Remove a client header Privoxy has no dedicated action for.
-
-
-
-
- Effect:
-
-
- Deletes every header sent by the client that contains the string the user supplied as parameter.
-
-
-
-
-
- Type:
-
-
- Parameterized.
-
-
-
-
- Parameter:
-
-
- Any string.
-
-
-
-
-
- Notes:
-
-
- This action allows you to block client headers for which no dedicated
- Privoxy action exists.
- Privoxy will remove every client header that
- contains the string you supplied as parameter.
-
-
- Regular expressions are not supported and you can't
- use this action to block different headers in the same request, unless
- they contain the same string.
-
-
- crunch-client-header 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
- client-header filter.
-
-
-
- Don't block any header without understanding the consequences.
-
-
-
-
-
-
- Example usage (section):
-
-
- # Block the non-existent "Privacy-Violation:" client header
-{ +crunch-client-header{Privacy-Violation:} }
-/
-
-
-
-
-
-
-
-
-
-
-crunch-if-none-match
-
-
-
- Typical use:
-
- Prevent yet another way to track the user's steps between sessions.
-
-
-
-
- Effect:
-
-
- Deletes the If-None-Match: HTTP client header.
-
-
-
-
-
- Type:
-
-
- Boolean.
-
-
-
-
- Parameter:
-
-
- N/A
-
-
-
-
- Notes:
-
-
- Removing the If-None-Match: HTTP client header
- is useful for filter testing, where you want to force a real
- reload instead of getting status code 304 which
- would cause the browser to use a cached copy of the page.
-
-
- It is also useful to make sure the header isn't used as a cookie
- replacement (unlikely but possible).
-
-
- Blocking the If-None-Match: header shouldn't cause any
- caching problems, as long as the If-Modified-Since: header
- isn't blocked or missing as well.
-
-
- It is recommended to use this action together with
- hide-if-modified-since
- and
- overwrite-last-modified.
-
-
-
-
-
- Example usage (section):
-
-
- # 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}
-/
-
-
-
-
-
-
-
-
-
-crunch-incoming-cookies
-
-
-
- Typical use:
-
-
- Prevent the web server from setting HTTP cookies on your system
-
-
-
-
-
- Effect:
-
-
- Deletes any Set-Cookie: HTTP headers from server replies.
-
-
-
-
-
- Type:
-
-
- Boolean.
-
-
-
-
- Parameter:
-
-
- N/A
-
-
-
+
+
+ Install Privoxy. See the Installation Section below for platform specific
+ information.
+
+
-
- Notes:
-
-
- This action is only concerned with incoming HTTP cookies. For
- outgoing HTTP cookies, use
- crunch-outgoing-cookies.
- Use both to disable HTTP cookies completely.
-
-
- It makes no sense at all to use this action in conjunction
- with the session-cookies-only action,
- since it would prevent the session cookies from being set. See also
- filter-content-cookies.
-
-
-
+
+
+ Advanced users and those who want to offer Privoxy
+ service to more than just their local machine should check the main config file, especially the security-relevant options. These are
+ off by default.
+
+
-
- Example usage:
-
-
- +crunch-incoming-cookies
-
-
-
-
-
+
+
+ Start Privoxy, if the installation program has
+ not done this already (may vary according to platform). See the section
+ Starting Privoxy.
+
+
+
+
+ Set your browser to use Privoxy as HTTP and
+ HTTPS (SSL) proxy
+ by setting the proxy configuration for address of
+ 127.0.0.1 and port 8118.
+ DO NOT activate proxying for FTP or
+ any protocols besides HTTP and HTTPS (SSL) unless you intend to prevent your
+ browser from using these protocols.
+
+
-
-
-crunch-server-header
-
-
-
- Typical use:
-
- Remove a server header Privoxy has no dedicated action for.
-
-
+
+
+ Flush your browser's disk and memory caches, to remove any cached ad images.
+ If using Privoxy to manage
+ cookies,
+ you should remove any currently stored cookies too.
+
+
-
- Effect:
-
-
- Deletes every header sent by the server that contains the string the user supplied as parameter.
-
-
-
+
+
+ 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
+ web-based action editor though.
+ Be sure to read the warnings first.
+
+
+ See the Configuration section for more
+ configuration options, and how to customize your installation.
+ You might also want to look at the next section for a quick
+ introduction to how Privoxy blocks ads and
+ banners.
+
+
-
- Type:
-
-
- Parameterized.
-
-
+
+
+ If you experience ads that slip through, innocent images that are
+ blocked, or otherwise feel the need to fine-tune
+ Privoxy's behavior, take a look at the actions files. As a quick start, you might
+ find the richly commented examples
+ helpful. You can also view and edit the actions files through the web-based user interface. The
+ Appendix Troubleshooting: Anatomy of an
+ Action has hints on how to understand and debug actions that
+ misbehave.
+
+
-
- Parameter:
-
-
- Any string.
-
-
-
+
+
+ Please see the section Contacting the
+ Developers on how to report bugs, problems with websites or to get
+ help.
+
+
-
- Notes:
-
-
- This action allows you to block server headers for which no dedicated
- Privoxy action exists. Privoxy
- will remove every server header that contains the string you supplied as parameter.
-
-
- Regular expressions are not supported and you can't
- use this action to block different headers in the same request, unless
- they contain the same string.
-
-
- crunch-server-header 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
- server-header filter.
-
-
-
- Don't block any header without understanding the consequences.
-
-
-
-
+
+
+ Now enjoy surfing with enhanced control, comfort and privacy!
+
+
-
- Example usage (section):
-
-
- # Crunch server headers that try to prevent caching
-{ +crunch-server-header{no-cache} }
-/
-
-
-
-
-
+
+
-
-crunch-outgoing-cookies
-
-
- Typical use:
-
-
- Prevent the web server from reading any HTTP cookies from your system
-
-
-
+
+Quickstart to Ad Blocking
+
+
+ Ad blocking is but one of Privoxy's
+ 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.
+
+
+ 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.
+
+
+ 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
+ problem sites, and to spend more time adjusting the
+ configuration to solve these unintended consequences. In short, there is
+ not an easy way to eliminate all ads. Either take
+ the easy way and settle for most ads blocked with the
+ default configuration, or jump in and tweak it for your personal surfing
+ habits and preferences.
+
+
+ Secondly, a brief explanation of Privoxy's
+ actions. Actions in this context, are
+ the directives we use to tell Privoxy to perform
+ some task relating to HTTP transactions (i.e. web browsing). We tell
+ Privoxy to take some action. Each
+ action has a unique name and function. While there are many potential
+ actions in Privoxy's
+ arsenal, only a few are used for ad blocking. Actions, and action
+ configuration files, are explained in depth below.
+
+
+ Actions are specified in Privoxy's configuration,
+ followed by one or more URLs to which the action should apply. URLs
+ can actually be URL type patterns 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.
+
+
+ When you connect to a website, the full URL will either match one or more
+ of the sections as defined in Privoxy's configuration,
+ or not. If so, then Privoxy 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.
+
-
- Effect:
-
-
- Deletes any Cookie: HTTP headers from client requests.
-
-
-
+
+ The most important actions for basic ad blocking are: block, handle-as-image,
+ handle-as-empty-document,and
+ set-image-blocker:
+
-
- Type:
-
-
- Boolean.
-
-
+
+
-
- Parameter:
-
-
- N/A
-
-
-
+
+
+ block - 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
+ Privoxy's own built-in BLOCKED page instead to
+ let you now what has happened (with some exceptions, see below).
+
+
-
- Notes:
-
-
- This action is only concerned with outgoing HTTP cookies. For
- incoming HTTP cookies, use
- crunch-incoming-cookies.
- Use both to disable HTTP cookies completely.
-
-
- It makes no sense at all to use this action in conjunction
- with the session-cookies-only action,
- since it would prevent the session cookies from being read.
-
-
-
+
+
+ handle-as-image -
+ tells Privoxy to treat this URL as an image.
+ Privoxy'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
+ Privoxy BLOCKED page (which would only result in
+ a broken image 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.
+
+
-
- Example usage:
-
-
- +crunch-outgoing-cookies
-
+
+
+ handle-as-empty-document -
+ sends an empty document instead of Privoxy's
+ normal BLOCKED HTML page. This is useful for file types that are neither
+ HTML nor images, such as blocking JavaScript files.
+
+
+
+
+
+ set-image-blocker - tells
+ Privoxy 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
+ block action somewhere in the
+ configuration, and, it must also match an
+ handle-as-image action.
+
+
+ The configuration options on what to display instead of the ad are:
+
+
+
+ pattern - a checkerboard pattern, so that an ad
+ replacement is obvious. This is the default.
+
+
+
+
+ blank - A very small empty GIF image is displayed.
+ This is the so-called invisible configuration option.
+
+
+
+
+ http://<URL> - A redirect to any image anywhere
+ of the user's choosing (advanced usage).
+
+
-
-
-
+
+
+
+
+ Advanced users will eventually want to explore &my-app;
+ filters as well. Filters
+ are very different from blocks.
+ A block 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 no-no for
+ nasty-word. 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.
+
+
+
+ The quickest way to adjust any of these settings is with your browser through
+ the special Privoxy editor at http://config.privoxy.org/show-status
+ (shortcut: http://p.p/show-status). This
+ is an internal page, and does not require Internet access.
+
+
+
+ Note that as of Privoxy 3.0.7 beta the
+ action editor is disabled by default. Check the
+ enable-edit-actions
+ section in the configuration file to learn why and in which
+ cases it's safe to enable again.
+
+
+ If you decided to enable the action editor, select the appropriate
+ actions file, and click
+ Edit. It is best to put personal or
+ local preferences in user.action since this is not
+ meant to be overwritten during upgrades, and will over-ride the settings in
+ other files. Here you can insert new actions, and URLs for ad
+ blocking or other purposes, and make other adjustments to the configuration.
+ Privoxy will detect these changes automatically.
+
-
-
-deanimate-gifs
+
+ A quick and simple step by step example:
+
-
-
- Typical use:
-
- Stop those annoying, distracting animated GIF images.
-
-
+
+
-
- Effect:
- De-animate GIF animations, i.e. reduce them to their first or last image.
+ Right click on the ad image to be blocked, then select
+ Copy Link Location from the
+ pop-up menu.
-
-
-
- Type:
-
-
- Parameterized.
-
-
-
-
- Parameter:
- last or first
+ Set your browser to
+ http://config.privoxy.org/show-status
-
-
-
- Notes:
- This will also shrink the images considerably (in bytes, not pixels!). If
- the option first is given, the first frame of the animation
- is used as the replacement. If last 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).
-
-
- 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.
+ Find user.action in the top section, and click
+ on Edit:
-
-
-
- Example usage:
-
-
- +deanimate-gifs{last}
-
-
-
-
-
+
+
+
+
+
+
+
+
+ You should have a section with only
+ block listed under
+ Actions:.
+ If not, click a Insert new section below
+ button, and in the new section that just appeared, click the
+ Edit button right under the word Actions:.
+ This will bring up a list of all actions. Find
+ block near the top, and click
+ in the Enabled column, then Submit
+ just below the list.
+
+
+
+
+ Now, in the block actions section,
+ click the Add button, and paste the URL the
+ browser got from Copy Link Location.
+ Remove the http:// at the beginning of the URL. Then, click
+ Submit (or
+ OK if in a pop-up window).
+
+
+
+
+ Now go back to the original page, and press SHIFT-Reload
+ (or flush all browser caches). The image should be gone now.
+
+
+
+
+
+
+
+ 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 patterns, and
+ the entire actions concept, see the Actions
+ section.
+
+
+
+ For advanced users who want to hand edit their config files, you might want
+ to now go to the Actions Files Tutorial.
+ The ideas explained therein also apply to the web-based editor.
+
+
+ There are also various
+ filters that can be used for ad blocking
+ (filters are a special subset of actions). These
+ fall into the advanced usage category, and are explained in
+ depth in later sections.
+
+
+
+
+
+
+
+
-
-downgrade-http-version
+
+Starting Privoxy
+
+ Before launching Privoxy for the first time, you
+ will want to configure your browser(s) to use
+ Privoxy as a HTTP and HTTPS (SSL)
+ proxy. 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 that must be done
+!
+
+
+ Please note that Privoxy can only proxy HTTP and
+ HTTPS traffic. It will not work with FTP or other protocols.
+
-
-
- Typical use:
-
- Work around (very rare) problems with HTTP/1.1
-
-
+
+
+
+
-
- Effect:
-
-
- Downgrades HTTP/1.1 client requests and server replies to HTTP/1.0.
-
-
-
-
- Type:
-
-
- Boolean.
-
-
+
+ With Firefox, this is typically set under:
+
-
- Parameter:
-
-
- N/A
-
-
-
+
+ Tools -> Options -> Advanced -> Network ->Connection -> Settings
-
- Notes:
-
-
- This is a left-over from the time when Privoxy
- 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.
-
-
- 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.
-
-
- If you come across a site where enabling this action helps, please report it,
- so the cause of the problem can be analyzed. If the problem turns out to be
- caused by a bug in Privoxy it should be
- fixed so the following release works without the work around.
-
-
-
+
-
- Example usage (section):
-
-
- {+downgrade-http-version}
-problem-host.example.com
-
-
-
+
+ Or optionally on some platforms:
+
+
+
+ Edit -> Preferences -> General -> Connection Settings -> Manual Proxy Configuration
+
+
+
+
+
+ With Netscape (and
+ Mozilla), this can be set under:
+
+
+
+
+
+
+ Edit -> Preferences -> Advanced -> Proxies -> HTTP Proxy
-
-
+
-
-
-fast-redirects
+
+ For Internet Explorer v.5-7:
+
-
-
- Typical use:
-
- Fool some click-tracking scripts and speed up indirect links.
-
-
+
+ Tools -> Internet Options -> Connections -> LAN Settings
+
-
- Effect:
-
-
- Detects redirection URLs and redirects the browser without contacting
- the redirection server first.
-
-
-
+
+ Then, check Use Proxy 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 Secure). Make sure any
+ checkboxes like Use the same proxy server for all protocols is
+ UNCHECKED. You want only HTTP and HTTPS (SSL)!
+
-
- Type:
-
-
- Parameterized.
-
-
+
+
+
+
-
- Parameter:
-
-
-
-
- simple-check to just search for the string http://
- to detect redirection URLs.
-
-
-
-
- check-decoded-url to decode URLs (if necessary) before searching
- for redirection URLs.
-
-
-
-
-
-
- Notes:
-
-
- Many sites, like yahoo.com, don't just link to other sites. Instead, they
- will link to some script on their own servers, giving the destination as a
- parameter, which will then redirect you to the final target. URLs
- resulting from this scheme typically look like:
- http://www.example.org/click-tracker.cgi?target=http%3a//www.example.net/.
-
-
- Sometimes, there are even multiple consecutive redirects encoded in the
- URL. These redirections via scripts make your web browsing more traceable,
- since the server from which you follow such a link can see where you go
- to. Apart from that, valuable bandwidth and time is wasted, while your
- browser asks the server for one redirect after the other. Plus, it feeds
- the advertisers.
-
-
- This feature is currently not very smart and is scheduled for improvement.
- If it is enabled by default, you will have to create some exceptions to
- this action. It can lead to failures in several ways:
-
-
- Not every URLs with other URLs as parameters is evil.
- Some sites offer a real service that requires this information to work.
- For example a validation service needs to know, which document to validate.
- fast-redirects assumes that every URL parameter that
- looks like another URL is a redirection target, and will always redirect to
- the last one. Most of the time the assumption is correct, but if it isn't,
- the user gets redirected anyway.
-
-
- Another failure occurs if the URL contains other parameters after the URL parameter.
- The URL:
- http://www.example.org/?redirect=http%3a//www.example.net/&foo=bar.
- contains the redirection URL http://www.example.net/,
- followed by another parameter. fast-redirects doesn't know that
- and will cause a redirect to http://www.example.net/&foo=bar.
- Depending on the target server configuration, the parameter will be silently ignored
- or lead to a page not found error. You can prevent this problem by
- first using the redirect action
- to remove the last part of the URL, but it requires a little effort.
-
-
- To detect a redirection URL, fast-redirects only
- looks for the string http://, either in plain text
- (invalid but often used) or encoded as http%3a//.
- Some sites use their own URL encoding scheme, encrypt the address
- of the target server or replace it with a database id. In theses cases
- fast-redirects is fooled and the request reaches the
- redirection server where it probably gets logged.
-
-
-
+
+ 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 cookies,
+ if you want Privoxy to manage that. You are now
+ ready to start enjoying the benefits of using
+ Privoxy!
+
-
- Example usage:
-
-
-
- { +fast-redirects{simple-check} }
- one.example.com
+
+ Privoxy 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, Privoxy
+ will look for a file named config in the current
+ directory. Except on Win32 where it will try config.txt.
+
- { +fast-redirects{check-decoded-url} }
- another.example.com/testing
-
-
-
+
+Debian
+
+ We use a script. Note that Debian typically starts &my-app; upon booting per
+ default. It will use the file
+ /etc/privoxy/config as its main configuration
+ file.
+
+
+
+ # /etc/init.d/privoxy start
+
+
+
-
-
+
+FreeBSD and ElectroBSD
+
+ To start Privoxy upon booting, add
+ "privoxy_enable='YES'" to /etc/rc.conf.
+ Privoxy will use
+ /usr/local/etc/privoxy/config as its main
+ configuration file.
+
+
+ If you installed Privoxy into a jail, the
+ paths above are relative to the jail root.
+
+
+ To start Privoxy manually, run:
+
+
+
+ # service privoxy onestart
+
+
+
+
+
+Windows
+
+Click on the &my-app; Icon to start Privoxy. If no configuration file is
+ specified on the command line, Privoxy will look
+ for a file named config.txt. Note that Windows will
+ automatically start &my-app; when the system starts if you chose that option
+ when installing.
+
+
+ Privoxy 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
+ Windows Installation
+ instructions for details.
+
+
+
+Generic instructions for Unix derivates (Solaris, NetBSD, HP-UX etc.)
+
+Example Unix startup command:
+
+
+
+ # /usr/sbin/privoxy --user privoxy /etc/privoxy/config
+
+
+
+ Note that if you installed Privoxy through
+ a package manager, the package will probably contain a platform-specific
+ script or configuration file to start Privoxy
+ upon boot.
+
+
-
-
-filter
+
+OS/2
+
+ During installation, Privoxy is configured to
+ start automatically when the system restarts. You can start it manually by
+ double-clicking on the Privoxy icon in the
+ Privoxy folder.
+
+
-
-
- Typical use:
-
- Get rid of HTML and JavaScript annoyances, banner advertisements (by size),
- do fun text replacements, add personalized effects, etc.
-
-
+
+Mac OS X
+
+ The privoxy service will automatically start after a successful installation
+ (and thereafter every time your computer starts up) however you will need to
+ configure your web browser(s) to use it. To do so, configure them to use a
+ proxy for HTTP and HTTPS at the address 127.0.0.1:8118.
+
+
+ To prevent the privoxy service from automatically starting when your computer
+ starts up, remove or rename the file /Library/LaunchDaemons/org.ijbswa.privoxy.plist
+ (on OS X 10.5 and higher) or the folder named
+ /Library/StartupItems/Privoxy (on OS X 10.4 'Tiger').
+
+
+ To manually start or stop the privoxy service, use the scripts startPrivoxy.sh
+ and stopPrivoxy.sh supplied in /Applications/Privoxy. They must be run from an
+ administrator account, using sudo.
+
+
-
- Effect:
-
-
- All instances of text-based type, most notably HTML and JavaScript, to which
- this action applies, can be filtered on-the-fly through the specified regular
- expression based substitutions. (Note: as of version 3.0.3 plain text documents
- are exempted from filtering, because web servers often use the
- text/plain MIME type for all files whose type they don't know.)
-
-
-
-
- Type:
-
-
- Parameterized.
-
-
+
-
-force-text-mode
-
-
-
- Typical use:
-
- Force Privoxy to treat a document as if it was in some kind of text format.
-
-
+
+ In fact, various aspects of Privoxy
+ configuration can be viewed from this page, including
+ current configuration parameters, source code version numbers,
+ the browser's request headers, and actions that apply
+ to a given URL. In addition to the actions file
+ editor mentioned above, Privoxy can also
+ be turned on and off (toggled) from this page.
+
-
- Effect:
-
-
- Declares a document as text, even if the Content-Type: isn't detected as such.
-
-
-
+
+ If you encounter problems, try loading the page without
+ Privoxy. If that helps, enter the URL where
+ you have the problems into the browser
+ based rule tracing utility. 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.
+
-
- Type:
-
-
- Boolean.
-
-
+
+ If the above paragraph sounds gibberish to you, you might want to read more about the actions concept
+ or even dive deep into the Appendix
+ on actions.
+
-
- Parameter:
-
-
- N/A
-
-
-
+
+ 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 Contacting the
+ Developers below.
+
-
- Notes:
-
-
- As explained above,
- Privoxy tries to only filter files that are
- in some kind of text format. The same restrictions apply to
- content-type-overwrite.
- force-text-mode declares a document as text,
- without looking at the Content-Type: first.
-
-
-
- Think twice before activating this action. Filtering binary data
- with regular expressions can cause file damage.
-
-
-
-
+-->
-
- Example usage:
-
-
-
-+force-text-mode
-
-
-
-
-
-
+
+
+Command Line Options
+
+ Privoxy may be invoked with the following
+ command-line options:
+
+
+
+
+
+
+ --config-test
+
+
+ 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.
+
+
+ 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).
+
+
+ This option doesn't affect the log setting, combination with
+ --no-daemon is recommended if a configured
+ log file shouldn't be used.
+
+
+
+
+ --version
+
+
+ Print version info and exit. Unix only.
+
+
+
+
+ --help
+
+
+ Print short usage info and exit. Unix only.
+
+
+
+
+ --no-daemon
+
+
+ Don't become a daemon, i.e. don't fork and become process group
+ leader, and don't detach from controlling tty. Unix only.
+
+
+
+
+ --pidfile FILE
+
+
+ On startup, write the process ID to FILE. Delete the
+ FILE on exit. Failure to create or delete the
+ FILE is non-fatal. If no FILE
+ option is given, no PID file will be used. Unix only.
+
+
+
+
+ --user USER[.GROUP]
+
+
+ After (optionally) writing the PID file, assume the user ID of
+ USER, and if included the GID of GROUP. Exit if the
+ privileges are not sufficient to do so. Unix only.
+
+
+
+
+ --chroot
+
+
+ Before changing to the user ID given in the --user 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.
+
+
+
+
+ --pre-chroot-nslookup hostname
+
+
+ Specifies a hostname (for example www.privoxy.org) 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.
+
+
+ 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.
+
+
-
-
-forward-override
-
-
-
- Typical use:
-
- Change the forwarding settings based on User-Agent or request origin
-
-
+
+
+ configfile
+
+
+ If no configfile is included on the command line,
+ Privoxy will look for a file named
+ config in the current directory (except on Win32
+ where it will look for config.txt instead). Specify
+ full path to avoid confusion. If no config file is found,
+ Privoxy will fail to start.
+
+
-
- Effect:
-
-
- Overrules the forward directives in the configuration file.
-
-
-
+
+
-
- Type:
-
-
- Multi-value.
-
-
+
+ On MS Windows only there are two additional
+ command-line options to allow Privoxy to install and
+ run as a service. See the
+Window Installation section
+for details.
+
-
- Parameter:
-
-
-
- forward . to use a direct connection without any additional proxies.
-
-
-
- forward 127.0.0.1:8123 to use the HTTP proxy listening at 127.0.0.1 port 8123.
-
-
-
-
- forward-socks4a 127.0.0.1:9050 . to use the socks4a proxy listening at
- 127.0.0.1 port 9050. Replace forward-socks4a with forward-socks4
- to use a socks4 connection (with local DNS resolution) instead, use forward-socks5
- for socks5 connections (with remote DNS resolution).
-
-
-
-
- forward-socks4a 127.0.0.1:9050 proxy.example.org:8000 to use the socks4a proxy
- listening at 127.0.0.1 port 9050 to reach the HTTP proxy listening at proxy.example.org port 8000.
- Replace forward-socks4a with forward-socks4 to use a socks4 connection
- (with local DNS resolution) instead, use forward-socks5
- for socks5 connections (with remote DNS resolution).
-
-
-
-
-
+
-
- Notes:
-
-
- This action takes parameters similar to the
- forward directives in the configuration
- file, but without the URL pattern. It can be used as replacement, but normally it's only
- used in cases where matching based on the request URL isn't sufficient.
-
-
-
- Please read the description for the forward directives before
- using this action. Forwarding to the wrong people will reduce your privacy and increase the
- chances of man-in-the-middle attacks.
-
-
- If the ports are missing or invalid, default values will be used. This might change
- in the future and you shouldn't rely on it. Otherwise incorrect syntax causes Privoxy
- to exit.
-
-
- Use the show-url-info CGI page
- to verify that your forward settings do what you thought the do.
-
-
-
-
+
-
- Example usage:
-
-
-
-# Always use direct connections for requests previously tagged as
-# User-Agent: fetch libfetch/2.0 and make sure
-# resuming downloads continues to work.
-# This way you can continue to use Tor for your normal browsing,
-# without overloading the Tor network with your FreeBSD ports updates
-# or downloads of bigger files like ISOs.
-# Note that HTTP headers are easy to fake and therefore their
-# values are as (un)trustworthy as your clients and users.
-{+forward-override{forward .} \
- -hide-if-modified-since \
- -overwrite-last-modified \
-}
-TAG:^User-Agent: fetch libfetch/2\.0$
-
-
-
-
-
-
+
-
-handle-as-empty-document
-
-
-
- Typical use:
-
- Mark URLs that should be replaced by empty documents if they get blocked
-
-
+Privoxy Configuration
+
+ All Privoxy configuration is stored
+ in text files. These files can be edited with a text editor.
+ Many important aspects of Privoxy can
+ also be controlled easily with a web browser.
+
-
- Effect:
-
-
- This action alone doesn't do anything noticeable. It just marks URLs.
- If the block action also applies,
- the presence or absence of this mark decides whether an HTML BLOCKED
- page, or an empty document will be sent to the client as a substitute for the blocked content.
- The empty document isn't literally empty, but actually contains a single space.
-
-
-
-
- Type:
-
-
- Boolean.
-
-
+
-
- Parameter:
-
-
- N/A
-
-
-
+
+Controlling Privoxy with Your Web Browser
+
+ Privoxy's user interface can be reached through the special
+ URL http://config.privoxy.org/
+ (shortcut: http://p.p/),
+ which is a built-in page and works without Internet access.
+ You will see the following section:
-
- Notes:
-
-
- Some browsers complain about syntax errors if JavaScript documents
- are blocked with Privoxy's
- default HTML page; this option can be used to silence them.
- And of course this action can also be used to eliminate the &my-app;
- BLOCKED message in frames.
-
-
- The content type for the empty document can be specified with
- content-type-overwrite{},
- but usually this isn't necessary.
-
-
-
+
-
- Example usage:
-
-
- # Block all documents on example.org that end with ".js",
-# but send an empty document instead of the usual HTML message.
-{+block{Blocked JavaScript} +handle-as-empty-document}
-example.org/.*\.js$
-
-
-
-
-
-
+
+
+
+ Privoxy Menu
+
+
+ ▪ View & change the current configuration
+
+
+ ▪ View the source code version numbers
+
+
+ ▪ View the request headers.
+
+
+ ▪ Look up which actions apply to a URL and why
+
+
+ ▪ Toggle Privoxy on or off
+
+
+ ▪ Documentation
+
+
+
+
-
-
-handle-as-image
-
-
- Typical use:
-
- Mark URLs as belonging to images (so they'll be replaced by images if they do get blocked, rather than HTML pages)
-
-
+
+ This should be self-explanatory. Note the first item leads to an editor for the
+ actions files, which is where the ad, banner,
+ cookie, and URL blocking magic is configured as well as other advanced features of
+ Privoxy. This is an easy way to adjust various
+ aspects of Privoxy configuration. The actions
+ file, and other configuration files, are explained in detail below.
+
-
- Effect:
-
-
- This action alone doesn't do anything noticeable. It just marks URLs as images.
- If the block action also applies,
- the presence or absence of this mark decides whether an HTML blocked
- page, or a replacement image (as determined by the set-image-blocker action) will be sent to the
- client as a substitute for the blocked content.
-
-
-
+
+ Toggle Privoxy On or Off 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 Privoxy
+ causing the problem or not. Privoxy continues
+ to run as a proxy in this case, but all manipulation is disabled, i.e.
+ Privoxy acts like a normal forwarding proxy.
+
-
- Type:
-
-
- Boolean.
-
-
+
+ Note that several of the features described above are disabled by default
+ in Privoxy 3.0.7 beta and later.
+ Check the
+ configuration file to learn why
+ and in which cases it's safe to enable them again.
+
-
- Parameter:
-
-
- N/A
-
-
-
+
-
- Notes:
-
-
- The below generic example section is actually part of default.action.
- It marks all URLs with well-known image file name extensions as images and should
- be left intact.
-
-
- Users will probably only want to use the handle-as-image action in conjunction with
- block, to block sources of banners, whose URLs don't
- reflect the file type, like in the second example section.
-
-
- Note that you cannot treat HTML pages as images in most cases. For instance, (in-line) ad
- frames require an HTML page to be sent, or they won't display properly.
- Forcing handle-as-image in this situation will not replace the
- ad frame with an image, but lead to error messages.
-
-
-
+
-
- Example usage (sections):
-
-
- # Generic image extensions:
-#
-{+handle-as-image}
-/.*\.(gif|jpg|jpeg|png|bmp|ico)$
-# These don't look like images, but they're banners and should be
-# blocked as images:
-#
-{+block{Nasty banners.} +handle-as-image}
-nasty-banner-server.example.com/junk.cgi\?output=trash
-
-
-
-
-
-
-
-hide-accept-language
-
-
-
- Typical use:
-
- Pretend to use different language settings.
-
-
-
- Effect:
-
-
- Deletes or replaces the Accept-Language: HTTP header in client requests.
-
-
-
+
+Configuration Files Overview
+
+ For Unix, *BSD and Linux, all configuration files are located in
+ /etc/privoxy/ by default. For MS Windows, OS/2, and
+ AmigaOS these are all in the same directory as the
+ Privoxy executable.
+
-
- Type:
-
-
- Parameterized.
-
-
+
+ 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:
+
+
+
+
-
- Parameter:
- Keyword: block, or any user defined value.
+ The main configuration file is named config
+ on Linux, Unix, BSD, OS/2, and AmigaOS and config.txt
+ on Windows. This is a required file.
-
-
- Notes:
- Faking the browser's language settings can be useful to make a
- foreign User-Agent set with
- hide-user-agent
- more believable.
+ match-all.action is used to define which actions
+ 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.
- However some sites with content in different languages check the
- Accept-Language: to decide which one to take by default.
- Sometimes it isn't possible to later switch to another language without
- changing the Accept-Language: header first.
+ default.action defines many exceptions (both positive and negative)
+ from the default set of actions that's configured in match-all.action.
+ It should be the second actions file loaded and shouldn't be edited by the user.
- Therefore it's a good idea to either only change the
- Accept-Language: header to languages you understand,
- or to languages that aren't wide spread.
+ Multiple actions files may be defined in config. These
+ are processed in the order they are defined. Local customizations and locally
+ preferred exceptions to the default policies as defined in
+ match-all.action (which you will most probably want
+ to define sooner or later) are best applied in user.action,
+ 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.
- Before setting the Accept-Language: header
- to a rare language, you should consider that it helps to
- make your requests unique and thus easier to trace.
- If you don't plan to change this header frequently,
- you should stick to a common language.
+ There is also a web based editor that can be accessed from
+ http://config.privoxy.org/show-status
+ (Shortcut: http://p.p/show-status) for the
+ various actions files.
-
-
- Example usage (section):
-
- # Pretend to use Canadian language settings.
-{+hide-accept-language{en-ca} \
-+hide-user-agent{Mozilla/5.0 (X11; U; OpenBSD i386; en-CA; rv:1.8.0.4) Gecko/20060628 Firefox/1.5.0.4} \
-}
-/
+
+ Filter files (the filter
+ file) 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.
+ default.filter 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 config as you can with
+ actions files. We suggest user.filter for any
+ locally defined filters or customizations.
-
-
-
+
+
+
+
+
+ The syntax of the configuration and filter files may change between different
+ Privoxy versions, unfortunately some enhancements cost backwards compatibility.
+
+
+
+
+ All files use the # character to denote a
+ comment (the rest of the line will be ignored) and understand line continuation
+ through placing a backslash ("\") as the very last character
+ in a line. If the # is preceded by a backslash, it looses
+ its special function. Placing a # in front of an otherwise
+ valid configuration line to prevent it from being interpreted is called "commenting
+ out" that line. Blank lines are ignored.
+
+
+
+ The actions files and filter files
+ can use Perl style regular expressions for
+ maximum flexibility.
+
+
+
+ After making any changes, there is no need to restart
+ Privoxy in order for the changes to take
+ effect. Privoxy 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 Privoxy, these wake up requests
+ must obviously be sent to the old listening address.
+
+
+
+ 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 default setting, may change, so
+ please check all your configuration files on important issues.
+
+]]>
+
+
+
+
+
+
+
+
+
+
+
+ &config;
+
+
+
+
+
+
+
+
+
+Actions Files
-
-
-hide-content-disposition
-
-
- Typical use:
-
- Prevent download menus for content you prefer to view inside the browser.
-
-
-
-
- Effect:
+
+ The actions files are used to define what actions
+ Privoxy 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.
+
+
+ There
+ are three action files included with Privoxy with
+ differing purposes:
+
+
+
- Deletes or replaces the Content-Disposition: HTTP header set by some servers.
+ match-all.action - is used to define which
+ actions 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
-
-
-
- Type:
-
- Parameterized.
+
+ default.action - defines many exceptions (both
+ positive and negative) from the default set of actions that's configured
+ in match-all.action. 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.
+
-
-
-
- Parameter:
- Keyword: block, or any user defined value.
+ user.action - 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.
-
-
-
- Notes:
- Some servers set the Content-Disposition: HTTP header for
- documents they assume you want to save locally before viewing them.
- The Content-Disposition: header contains the file name
- the browser is supposed to use by default.
+ EditSet to CautiousSet to MediumSet to Advanced
- In most browsers that understand this header, it makes it impossible to
- just view the document, without downloading it first,
- even if it's just a simple text file or an image.
+ These have increasing levels of aggressiveness and have no
+ influence on your browsing unless you select them explicitly in the
+ editor. A default installation should be pre-set to
+ Cautious. 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.
- Removing the Content-Disposition: header helps
- to prevent this annoyance, but some browsers additionally check the
- Content-Type: header, before they decide if they can
- display a document without saving it first. In these cases, you have
- to change this header as well, before the browser stops displaying
- download menus.
+ The Edit button allows you to turn each
+ action on/off individually for fine-tuning. The Cautious
+ 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
+ Medium button sets the list to a medium level of
+ other features and a low level set of privacy features. The
+ Advanced 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
+ Edit button. More fine-tuning can be done in the
+ lower sections of this internal page.
- It is also possible to change the server's file name suggestion
- to another one, but in most cases it isn't worth the time to set
- it up.
+ 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.
- This action will probably be removed in the future,
- use server-header filters instead.
+ The default profiles, and their associated actions, as pre-defined in
+ default.action are:
-
-
+
+
Default Configurations
+
+
+
+
+
+
+
+ Feature
+ Cautious
+ Medium
+ Advanced
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Ad-blocking Aggressiveness
+ medium
+ high
+ high
+
+
+
+ Ad-filtering by size
+ no
+ yes
+ yes
+
+
+
+ Ad-filtering by link
+ no
+ no
+ yes
+
+
+ Pop-up killing
+ blocks only
+ blocks only
+ blocks only
+
+
+
+ Privacy Features
+ low
+ medium
+ medium/high
+
+
+
+ Cookie handling
+ none
+ session-only
+ kill
+
+
+
+ Referer forging
+ no
+ yes
+ yes
+
+
+
+ GIF de-animation
+ no
+ yes
+ yes
+
+
+
+ Fast redirects
+ no
+ no
+ yes
+
+
+
+ HTML taming
+ no
+ no
+ yes
+
+
+
+ JavaScript taming
+ no
+ no
+ yes
+
+
+
+ Web-bug killing
+ no
+ yes
+ yes
+
+
+
+ Image tag reordering
+ no
+ yes
+ yes
+
+
+
+
+
+
+ Effect:
+
- http://config.privoxy.org/
+ This action alone doesn't do anything noticeable. If both
+ blockandhandle-as-imagealso
+ apply, i.e. if the request is to be blocked as an image,
+ then the parameter of this action decides what will be
+ sent as a replacement.
-
-
- There is a shortcut: http://p.p/ (But it
- doesn't provide a fall-back to a real page, in case the request is not
- sent through Privoxy)
-
-
+
+
-
-
- Show information about the current configuration, including viewing and
- editing of actions files:
-
-
+
+ Type:
+
+
+ Parameterized.
+
+
+
+
+ Parameter:
+
+
+
+
+ pattern to send a built-in checkerboard pattern image. The image is visually
+ decent, scales very well, and makes it obvious where banners were busted.
+
+
+
+
+ blank to send a built-in transparent image. This makes banners disappear
+ completely, but makes it hard to detect where Privoxy has blocked
+ images on a given page and complicates troubleshooting if Privoxy
+ has blocked innocent images, like navigation icons.
+
+
+
+
+ target-url to
+ send a redirect to target-url. You can redirect
+ to any image anywhere, even in your local filesystem via file:/// URL.
+ (But note that not all browsers support redirecting to a local file system).
+
+
+ A good application of redirects is to use special Privoxy-built-in
+ URLs, which send the built-in images, as target-url.
+ This has the same visual effect as specifying blank or pattern in
+ the first place, but enables your browser to cache the replacement image, instead of requesting
+ it over and over again.
+
+
+
+
+
+
+
+ Notes:
+
- http://config.privoxy.org/show-status
+ The URLs for the built-in images are http://config.privoxy.org/send-banner?type=type, where type is
+ either blank or pattern.
-
-
-
-
-
- Show the source code version numbers:
-
-
- http://config.privoxy.org/show-version
+ There is a third (advanced) type, called auto. It is NOT to be
+ used in set-image-blocker, but meant for use from filters.
+ Auto will select the type of image that would have applied to the referring page, had it been an image.
-
-
+
+
-
-
- Show the browser's request headers:
-
-
-
-
-
-
- Toggle Privoxy on or off. This feature can be turned off/on in the main
- config file. When toggled off, Privoxy
- continues to run, but only as a pass-through proxy, with no actions taking
- place:
-
-
- http://config.privoxy.org/toggle
+ Redirect to the BSD daemon:
-
+
+ There is a shortcut: http://p.p/ (But it
+ doesn't provide a fall-back to a real page, in case the request is not
+ sent through Privoxy)
+
+
- Revision 1.77 2002/04/17 13:51:23 oes
- Proofreading, part one
+
+
+ Show information about the current configuration, including viewing and
+ editing of actions files:
+
+
+
+ http://config.privoxy.org/show-status
+
+
+
- Revision 1.76 2002/04/16 04:25:51 hal9
- -Added 'Note to Upgraders' and re-ordered the 'Quickstart' section.
- -Note about proxy may need requests to re-read config files.
+
+
+ Show the source code version numbers:
+
+
+
+ http://config.privoxy.org/show-version
+
+
+
- Revision 1.75 2002/04/12 02:08:48 david__schmidt
- Remove OS/2 building info... it is already in the developer-manual
+
+
+ Show the browser's request headers:
+
+
+
+ http://config.privoxy.org/show-request
+
+
+
- Revision 1.74 2002/04/11 00:54:38 hal9
- Add small section on submitting actions.
+
+
+ Show which actions apply to a URL and why:
+
+
+
+ http://config.privoxy.org/show-url-info
+
+
+
- Revision 1.73 2002/04/10 18:45:15 swa
- generated
+
+
+ Toggle Privoxy on or off. This feature can be turned off/on in the main
+ config file. When toggled off, Privoxy
+ continues to run, but only as a pass-through proxy, with no actions taking
+ place:
+
+
+
- Revision 1.72 2002/04/10 04:06:19 hal9
- Added actions feedback to Bookmarklets section
+
+
- Revision 1.71 2002/04/08 22:59:26 hal9
- Version update. Spell chkconfig correctly :)
+
- Revision 1.70 2002/04/08 20:53:56 swa
- ?
- Revision 1.69 2002/04/06 05:07:29 hal9
- -Add privoxy-man-page.sgml, for man page.
- -Add authors.sgml for AUTHORS (and p-authors.sgml)
- -Reworked various aspects of various docs.
- -Added additional comments to sub-docs.
+
+
+Chain of Events
+
+ Let's take a quick look at how some of Privoxy's
+ core features are triggered, and the ensuing sequence of events when a web
+ page is requested by your browser:
+
- Revision 1.68 2002/04/04 18:46:47 swa
- consistent look. reuse of copyright, history et. al.
+
+
+
+
+ First, your web browser requests a web page. The browser knows to send
+ the request to Privoxy, which will in turn,
+ relay the request to the remote web server after passing the following
+ tests:
+
+
+
+
+ Privoxy traps any request for its own internal CGI
+ pages (e.g http://p.p/) and sends the CGI page back to the browser.
+
+
+
+
+ Next, Privoxy checks to see if the URL
+ matches any +block patterns. If
+ so, the URL is then blocked, and the remote web server will not be contacted.
+ +handle-as-image
+ and
+ +handle-as-empty-document
+ are then checked, and if there is no match, an
+ HTML BLOCKED page is sent back to the browser. Otherwise, if
+ it does match, an image is returned for the former, and an empty text
+ document for the latter. The type of image would depend on the setting of
+ +set-image-blocker
+ (blank, checkerboard pattern, or an HTTP redirect to an image elsewhere).
+
+
+
+
+ Untrusted URLs are blocked. If URLs are being added to the
+ trust file, then that is done.
+
+
+
+
+ If the URL pattern matches the +fast-redirects action,
+ it is then processed. Unwanted parts of the requested URL are stripped.
+
+
+
+
+ Now the rest of the client browser's request headers are processed. If any
+ of these match any of the relevant actions (e.g. +hide-user-agent,
+ etc.), headers are suppressed or forged as determined by these actions and
+ their parameters.
+
+
+
+
+ Now the web server starts sending its response back (i.e. typically a web
+ page).
+
+
+
+
+ First, the server headers are read and processed to determine, among other
+ things, the MIME type (document type) and encoding. The headers are then
+ filtered as determined by the
+ +crunch-incoming-cookies,
+ +session-cookies-only,
+ and +downgrade-http-version
+ actions.
+
+
+
+
+ If any +filter action
+ or +deanimate-gifs
+ action applies (and the document type fits the action), the rest of the page is
+ read into memory (up to a configurable limit). Then the filter rules (from
+ default.filter and any other filter files) are
+ processed against the buffered content. Filters are applied in the order
+ they are specified in one of the filter files. Animated GIFs, if present,
+ are reduced to either the first or last frame, depending on the action
+ setting.The entire page, which is now filtered, is then sent by
+ Privoxy back to your browser.
+
+
+ If neither a +filter action
+ or +deanimate-gifs
+ matches, then Privoxy passes the raw data through
+ to the client browser as it becomes available.
+
+
+
+
+ As the browser receives the now (possibly filtered) page content, it
+ reads and then requests any URLs that may be embedded within the page
+ source, e.g. ad images, stylesheets, JavaScript, other HTML documents (e.g.
+ frames), sounds, etc. For each of these objects, the browser issues a
+ separate request (this is easily viewable in Privoxy's
+ logs). And each such request is in turn processed just as above. Note that a
+ complex web page will have many, many such embedded URLs. If these
+ secondary requests are to a different server, then quite possibly a very
+ differing set of actions is triggered.
+
+
- Revision 1.67 2002/04/04 17:27:57 swa
- more single file to be included at multiple points. make maintaining easier
+
+
+
+ NOTE: This is somewhat of a simplistic overview of what happens with each URL
+ request. For the sake of brevity and simplicity, we have focused on
+ Privoxy's core features only.
+
- Revision 1.66 2002/04/04 06:48:37 hal9
- Structural changes to allow for conditional inclusion/exclusion of content
- based on entity toggles, e.g. 'entity % p-not-stable "INCLUDE"'. And
- definition of internal entities, e.g. 'entity p-version "2.9.13"' that will
- eventually be set by Makefile.
- More boilerplate text for use across multiple docs.
+
- Revision 1.65 2002/04/03 19:52:07 swa
- enhance squid section due to user suggestion
- Revision 1.64 2002/04/03 03:53:43 hal9
- A few minor bug fixes, and touch ups. Ready for review.
+
+
+Troubleshooting: Anatomy of an Action
- Revision 1.63 2002/04/01 16:24:49 hal9
- Define entities to include boilerplate text. See doc/source/*.
+
+ The way Privoxy applies
+ actions and filters
+ to any given URL can be complex, and not always so
+ easy to understand what is happening. And sometimes we need to be able to
+ see just what Privoxy is
+ doing. Especially, if something Privoxy is doing
+ is causing us a problem inadvertently. It can be a little daunting to look at
+ the actions and filters files themselves, since they tend to be filled with
+ regular expressions whose consequences are not
+ always so obvious.
+
- Revision 1.62 2002/03/30 04:15:53 hal9
- - Fix privoxy.org/config links.
- - Paste in Bookmarklets from Toggle page.
- - Move Quickstart nearer top, and minor rework.
+
+ One quick test to see if Privoxy is causing a problem
+ or not, is to disable it temporarily. This should be the first troubleshooting
+ step (be sure to flush caches afterward!). Looking at the
+ logs is a good idea too. (Note that both the toggle feature and logging are
+ enabled via config file settings, and may need to be
+ turned on.)
+
+
+ Another easy troubleshooting step to try is if you have done any
+ customization of your installation, revert back to the installed
+ defaults and see if that helps. There are times the developers get complaints
+ about one thing or another, and the problem is more related to a customized
+ configuration issue.
+
- Revision 1.61 2002/03/29 01:31:08 hal9
- Minor update.
+
+ Privoxy also provides the
+ http://config.privoxy.org/show-url-info
+ page that can show us very specifically how actions
+ are being applied to any given URL. This is a big help for troubleshooting.
+
- Revision 1.60 2002/03/27 01:57:34 hal9
- Added more to Anatomy section.
+
+ First, enter one URL (or partial URL) at the prompt, and then
+ Privoxy will tell us
+ how the current configuration will handle it. This will not
+ help with filtering effects (i.e. the +filter action) from
+ one of the filter files since this is handled very
+ differently and not so easy to trap! It also will not tell you about any other
+ URLs that may be embedded within the URL you are testing. For instance, images
+ such as ads are expressed as URLs within the raw page source of HTML pages. So
+ you will only get info for the actual URL that is pasted into the prompt area
+ -- not any sub-URLs. If you want to know about embedded URLs like ads, you
+ will have to dig those out of the HTML source. Use your browser's View
+ Page Source option for this. Or right click on the ad, and grab the
+ URL.
+
- Revision 1.59 2002/03/27 00:54:33 hal9
- Touch up intro for new name.
+
+ Let's try an example, google.com,
+ and look at it one section at a time in a sample configuration (your real
+ configuration may vary):
+
- Revision 1.58 2002/03/26 22:29:55 swa
- we have a new homepage!
+
+
+ Matches for http://www.google.com:
- Revision 1.57 2002/03/24 20:33:30 hal9
- A few minor catch ups with name change.
+ In file: default.action [ View ][ Edit ]
- Revision 1.56 2002/03/24 16:17:06 swa
- configure needs to be generated.
+ {+change-x-forwarded-for{block}
+ +deanimate-gifs {last}
+ +fast-redirects {check-decoded-url}
+ +filter {refresh-tags}
+ +filter {img-reorder}
+ +filter {banners-by-size}
+ +filter {webbugs}
+ +filter {jumping-windows}
+ +filter {ie-exploits}
+ +hide-from-header {block}
+ +hide-referrer {forge}
+ +session-cookies-only
+ +set-image-blocker {pattern}
+/
- Revision 1.55 2002/03/24 16:08:08 swa
- we are too lazy to make a block-built
- privoxy logo. hence removed the option.
+ { -session-cookies-only }
+ .google.com
- Revision 1.54 2002/03/24 15:46:20 swa
- name change related issue.
+ { -fast-redirects }
+ .google.com
- Revision 1.53 2002/03/24 11:51:00 swa
- name change. changed filenames.
+In file: user.action [ View ][ Edit ]
+(no matches in this file)
+
+
- Revision 1.52 2002/03/24 11:01:06 swa
- name change
+
+ This is telling us how we have defined our
+ actions, and
+ which ones match for our test case, google.com.
+ Displayed is all the actions that are available to us. Remember,
+ the + sign denotes on. -
+ denotes off. So some are on here, but many
+ are off. Each example we try may provide a slightly different
+ end result, depending on our configuration directives.
+
+
+ The first listing
+ is for our default.action file. The large, multi-line
+ listing, is how the actions are set to match for all URLs, i.e. our default
+ settings. If you look at your actions file, this would be the
+ section just below the aliases section near the top. This
+ will apply to all URLs as signified by the single forward slash at the end
+ of the listing -- / .
+
- Revision 1.51 2002/03/23 15:13:11 swa
- renamed every reference to the old name with foobar.
- fixed "application foobar application" tag, fixed
- "the foobar" with "foobar". left junkbustser in cvs
- comments and remarks to history untouched.
+
+ But we have defined additional actions that would be exceptions to these general
+ rules, and then we list specific URLs (or patterns) that these exceptions
+ would apply to. Last match wins. Just below this then are two explicit
+ matches for .google.com. The first is negating our previous
+ cookie setting, which was for +session-cookies-only
+ (i.e. not persistent). So we will allow persistent cookies for google, at
+ least that is how it is in this example. The second turns
+ off any +fast-redirects
+ action, allowing this to take place unmolested. Note that there is a leading
+ dot here -- .google.com. This will match any hosts and
+ sub-domains, in the google.com domain also, such as
+ www.google.com or mail.google.com. But it would not
+ match www.google.de! So, apparently, we have these two actions
+ defined as exceptions to the general rules at the top somewhere in the lower
+ part of our default.action file, and
+ google.com is referenced somewhere in these latter sections.
+
- Revision 1.50 2002/03/23 05:06:21 hal9
- Touch up.
+
+ Then, for our user.action file, we again have no hits.
+ So there is nothing google-specific that we might have added to our own, local
+ configuration. If there was, those actions would over-rule any actions from
+ previously processed files, such as default.action.
+ user.action typically has the last word. This is the
+ best place to put hard and fast exceptions,
+
- Revision 1.49 2002/03/21 17:01:05 hal9
- New section in Appendix.
+
+ And finally we pull it all together in the bottom section and summarize how
+ Privoxy is applying all its actions
+ to google.com:
- Revision 1.48 2002/03/12 06:33:01 hal9
- Catching up to Andreas and re_filterfile changes.
+
- Revision 1.47 2002/03/11 13:13:27 swa
- correct feedback channels
+
+
- Revision 1.46 2002/03/10 00:51:08 hal9
- Added section on JB internal pages in Appendix.
+ Final results:
- Revision 1.45 2002/03/09 17:43:53 swa
- more distros
+ -add-header
+ -block
+ +change-x-forwarded-for{block}
+ -client-header-filter{hide-tor-exit-notation}
+ -content-type-overwrite
+ -crunch-client-header
+ -crunch-if-none-match
+ -crunch-incoming-cookies
+ -crunch-outgoing-cookies
+ -crunch-server-header
+ +deanimate-gifs {last}
+ -downgrade-http-version
+ -fast-redirects
+ -filter {js-events}
+ -filter {content-cookies}
+ -filter {all-popups}
+ -filter {banners-by-link}
+ -filter {tiny-textforms}
+ -filter {frameset-borders}
+ -filter {demoronizer}
+ -filter {shockwave-flash}
+ -filter {quicktime-kioskmode}
+ -filter {fun}
+ -filter {crude-parental}
+ -filter {site-specifics}
+ -filter {js-annoyances}
+ -filter {html-annoyances}
+ +filter {refresh-tags}
+ -filter {unsolicited-popups}
+ +filter {img-reorder}
+ +filter {banners-by-size}
+ +filter {webbugs}
+ +filter {jumping-windows}
+ +filter {ie-exploits}
+ -filter {google}
+ -filter {yahoo}
+ -filter {msn}
+ -filter {blogspot}
+ -filter {no-ping}
+ -force-text-mode
+ -handle-as-empty-document
+ -handle-as-image
+ -hide-accept-language
+ -hide-content-disposition
+ +hide-from-header {block}
+ -hide-if-modified-since
+ +hide-referrer {forge}
+ -hide-user-agent
+ -limit-connect
+ -overwrite-last-modified
+ -prevent-compression
+ -redirect
+ -server-header-filter{xml-to-html}
+ -server-header-filter{html-to-xml}
+ -session-cookies-only
+ +set-image-blocker {pattern}
+
- Revision 1.44 2002/03/09 17:08:48 hal9
- New section on Jon's actions file editor, and move some stuff around.
+
+ Notice the only difference here to the previous listing, is to
+ fast-redirects and session-cookies-only,
+ which are activated specifically for this site in our configuration,
+ and thus show in the Final Results.
+
- Revision 1.43 2002/03/08 00:47:32 hal9
- Added imageblock{pattern}.
+
+ Now another example, ad.doubleclick.net:
+
- Revision 1.42 2002/03/07 18:16:55 swa
- looks better
+
+
- Revision 1.41 2002/03/07 16:46:43 hal9
- Fix a few markup problems for jade.
+ { +block{Domains starts with "ad"} }
+ ad*.
- Revision 1.40 2002/03/07 16:28:39 swa
- provide correct feedback channels
+ { +block{Domain contains "ad"} }
+ .ad.
- Revision 1.39 2002/03/06 16:19:28 hal9
- Note on perceived filtering slowdown per FR.
+ { +block{Doubleclick banner server} +handle-as-image }
+ .[a-vx-z]*.doubleclick.net
+
+
- Revision 1.38 2002/03/05 23:55:14 hal9
- Stupid I did it again. Double hyphen in comment breaks jade.
+
+ We'll just show the interesting part here - the explicit matches. It is
+ matched three different times. Two +block{} sections,
+ and a +block{} +handle-as-image,
+ which is the expanded form of one of our aliases that had been defined as:
+ +block-as-image. (Aliases are defined in
+ the first section of the actions file and typically used to combine more
+ than one action.)
+
- Revision 1.37 2002/03/05 23:53:49 hal9
- jade barfs on '- -' embedded in comments. - -user option broke it.
+
+ Any one of these would have done the trick and blocked this as an unwanted
+ image. This is unnecessarily redundant since the last case effectively
+ would also cover the first. No point in taking chances with these guys
+ though ;-) Note that if you want an ad or obnoxious
+ URL to be invisible, it should be defined as ad.doubleclick.net
+ is done here -- as both a +block{}
+ and an
+ +handle-as-image.
+ The custom alias +block-as-image just
+ simplifies the process and make it more readable.
+
- Revision 1.36 2002/03/05 22:53:28 hal9
- Add new - - user option.
+
+ One last example. Let's try http://www.example.net/adsl/HOWTO/.
+ This one is giving us problems. We are getting a blank page. Hmmm ...
+
- Revision 1.35 2002/03/05 00:17:27 hal9
- Added section on command line options.
+
+
- Revision 1.34 2002/03/04 19:32:07 oes
- Changed default port to 8118
+ Matches for http://www.example.net/adsl/HOWTO/:
- Revision 1.33 2002/03/03 19:46:13 hal9
- Emphasis on where/how to report bugs, etc
+ In file: default.action [ View ][ Edit ]
- Revision 1.32 2002/03/03 09:26:06 joergs
- AmigaOS changes, config is now loaded from PROGDIR: instead of
- AmiTCP:db/junkbuster/ if no configuration file is specified on the
- command line.
+ {-add-header
+ -block
+ +change-x-forwarded-for{block}
+ -client-header-filter{hide-tor-exit-notation}
+ -content-type-overwrite
+ -crunch-client-header
+ -crunch-if-none-match
+ -crunch-incoming-cookies
+ -crunch-outgoing-cookies
+ -crunch-server-header
+ +deanimate-gifs
+ -downgrade-http-version
+ +fast-redirects {check-decoded-url}
+ -filter {js-events}
+ -filter {content-cookies}
+ -filter {all-popups}
+ -filter {banners-by-link}
+ -filter {tiny-textforms}
+ -filter {frameset-borders}
+ -filter {demoronizer}
+ -filter {shockwave-flash}
+ -filter {quicktime-kioskmode}
+ -filter {fun}
+ -filter {crude-parental}
+ -filter {site-specifics}
+ -filter {js-annoyances}
+ -filter {html-annoyances}
+ +filter {refresh-tags}
+ -filter {unsolicited-popups}
+ +filter {img-reorder}
+ +filter {banners-by-size}
+ +filter {webbugs}
+ +filter {jumping-windows}
+ +filter {ie-exploits}
+ -filter {google}
+ -filter {yahoo}
+ -filter {msn}
+ -filter {blogspot}
+ -filter {no-ping}
+ -force-text-mode
+ -handle-as-empty-document
+ -handle-as-image
+ -hide-accept-language
+ -hide-content-disposition
+ +hide-from-header{block}
+ +hide-referer{forge}
+ -hide-user-agent
+ -overwrite-last-modified
+ +prevent-compression
+ -redirect
+ -server-header-filter{xml-to-html}
+ -server-header-filter{html-to-xml}
+ +session-cookies-only
+ +set-image-blocker{blank} }
+ /
- Revision 1.31 2002/03/02 22:45:52 david__schmidt
- Just tweaking
+ { +block{Path contains "ads".} +handle-as-image }
+ /ads
+
+
- Revision 1.30 2002/03/02 22:00:14 hal9
- Updated 'New Features' list. Ran through spell-checker.
+
+ Ooops, the /adsl/ is matching /ads in our
+ configuration! But we did not want this at all! Now we see why we get the
+ blank page. It is actually triggering two different actions here, and
+ the effects are aggregated so that the URL is blocked, and &my-app; is told
+ to treat the block as if it were an image. But this is, of course, all wrong.
+ We could now add a new action below this (or better in our own
+ user.action file) that explicitly
+ un blocks (
+ {-block}) paths with
+ adsl in them (remember, last match in the configuration
+ wins). There are various ways to handle such exceptions. Example:
+
- Revision 1.29 2002/03/02 20:34:07 david__schmidt
- Update OS/2 build section
+
+
- Revision 1.28 2002/02/24 14:34:24 jongfoster
- Formatting changes. Now changing the doctype to DocBook XML 4.1
- will work - no other changes are needed.
+ { -block }
+ /adsl
+
+
- Revision 1.27 2002/01/11 14:14:32 hal9
- Added a very short section on Templates
+
+ Now the page displays ;-)
+ Remember to flush your browser's caches when making these kinds of changes to
+ your configuration to insure that you get a freshly delivered page! Or, try
+ using Shift+Reload.
+
- Revision 1.26 2002/01/09 20:02:50 hal9
- Fix bug re: auto-detect config file changes.
+
+ But now what about a situation where we get no explicit matches like
+ we did with:
+
- Revision 1.25 2002/01/09 18:20:30 hal9
- Touch ups for *.action files.
+
+
- Revision 1.24 2001/12/02 01:13:42 hal9
- Fix typo.
+ { +block{Path starts with "ads".} +handle-as-image }
+ /ads
+
+
- Revision 1.23 2001/12/02 00:20:41 hal9
- Updates for recent changes.
+
+ That actually was very helpful and pointed us quickly to where the problem
+ was. If you don't get this kind of match, then it means one of the default
+ rules in the first section of default.action is causing
+ the problem. This would require some guesswork, and maybe a little trial and
+ error to isolate the offending rule. One likely cause would be one of the
+ +filter actions.
+ These tend to be harder to troubleshoot.
+ Try adding the URL for the site to one of aliases that turn off
+ +filter:
+
- Revision 1.22 2001/11/05 23:57:51 hal9
- Minor update for startup now daemon mode.
+
+
- Revision 1.21 2001/10/31 21:11:03 hal9
- Correct 2 minor errors
+ { shop }
+ .quietpc.com
+ .worldpay.com # for quietpc.com
+ .jungle.com
+ .scan.co.uk
+ .forbes.com
+
+
- Revision 1.18 2001/10/24 18:45:26 hal9
- *** empty log message ***
+
+ { shop } is an alias that expands to
+ { -filter -session-cookies-only }.
+ Or you could do your own exception to negate filtering:
- Revision 1.17 2001/10/24 17:10:55 hal9
- Catching up with Jon's recent work, and a few other things.
+
- Revision 1.16 2001/10/21 17:19:21 swa
- wrong url in documentation
+
+
- Revision 1.15 2001/10/14 23:46:24 hal9
- Various minor changes. Fleshed out SEE ALSO section.
+ { -filter }
+ # Disable ALL filter actions for sites in this section
+ .forbes.com
+ developer.ibm.com
+ localhost
+
+
- Revision 1.13 2001/10/10 17:28:33 hal9
- Very minor changes.
+
+ This would turn off all filtering for these sites. This is best
+ put in user.action, for local site
+ exceptions. Note that when a simple domain pattern is used by itself (without
+ the subsequent path portion), all sub-pages within that domain are included
+ automatically in the scope of the action.
+
- Revision 1.12 2001/09/28 02:57:04 hal9
- Ditto :/
+
+ Images that are inexplicably being blocked, may well be hitting the
++filter{banners-by-size}
+ rule, which assumes
+ that images of certain sizes are ad banners (works well
+ most of the time since these tend to be standardized).
+
- Revision 1.11 2001/09/28 02:25:20 hal9
- Ditto.
+
+ { fragile } is an alias that disables most
+ actions that are the most likely to cause trouble. This can be used as a
+ last resort for problem sites.
+
+
+
- Revision 1.9 2001/09/27 23:50:29 hal9
- A few changes. A short section on regular expression in appendix.
+ { fragile }
+ # Handle with care: easy to break
+ mail.google.
+ mybank.example.com
+
- Revision 1.8 2001/09/25 00:34:59 hal9
- Some additions, and re-arranging.
- Revision 1.7 2001/09/24 14:31:36 hal9
- Diddling.
+
+ Remember to flush caches! Note that the
+ mail.google reference lacks the TLD portion (e.g.
+ .com). This will effectively match any TLD with
+ google in it, such as mail.google.de.,
+ just as an example.
+
+
+ If this still does not work, you will have to go through the remaining
+ actions one by one to find which one(s) is causing the problem.
+
- Revision 1.6 2001/09/24 14:10:32 hal9
- Including David's OS/2 installation instructions.
+
- Revision 1.2 2001/09/13 15:27:40 swa
- cosmetics
+
- Revision 1.1 2001/09/12 15:36:41 swa
- source files for junkbuster documentation
+