X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fuser-manual.sgml;h=349b430dbdea3aa9c609089b9582718186cb98ab;hp=302e6d0a79948cf48c578fc51b501dd3b32c847c;hb=a8156ded2b05b26bd90307f8a8bb4b0f0c87c9d3;hpb=6db41a0326d1eb6e391b8d143fc22ae6077792b3 diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml index 302e6d0a..349b430d 100644 --- a/doc/source/user-manual.sgml +++ b/doc/source/user-manual.sgml @@ -9,9 +9,11 @@ + - + + @@ -28,15 +30,11 @@ Privoxy"> ]> - Copyright &my-copy; 2001-2011 by - Privoxy Developers + Copyright &my-copy; 2001-2019 by + Privoxy Developers -$Id: user-manual.sgml,v 2.156 2013/01/05 22:56:31 ler762 Exp $ - @@ -99,14 +95,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 +108,7 @@ Hal. Introduction This documentation is included with the current &p-status; version of - Privoxy, v.&p-version;Privoxy, &p-version; Since this is a &p-status; version, not all new features are well tested. This documentation may be slightly out of sync as a result (especially with - CVS sources). And there may be bugs, though hopefully + git sources). + And there may be bugs, though hopefully not many! ]]> @@ -160,7 +154,7 @@ Hal. 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 +174,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 +226,6 @@ How to install the binary packages depends on your operating system: - -Solaris <!--, NetBSD, HP-UX--> - - - 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 @@ -282,7 +236,6 @@ How to install the binary packages depends on your operating system: system. Check that no Junkbuster or Privoxy objects are in your startup folder. - @@ -331,1195 +284,242 @@ How to install the binary packages depends on your operating system: and stopPrivoxy.sh supplied in /Applications/Privoxy. They must be run from an administrator account, using sudo. - - To uninstall, run /Applications/Privoxy/uninstall.command as sudo from an - administrator account. - - - -Installation from source - - To build and install the Privoxy source code on OS X you will need to obtain - the macsetup module from the Privoxy Sourceforge CVS repository (refer to - Sourceforge help for details of how to set up a CVS client to have read-only - access to the repository). This module contains scripts that leverage the usual - open-source tools (available as part of Apple's free of charge Xcode - distribution or via the usual open-source software package managers for OS X - (MacPorts, Homebrew, Fink etc.) to build and then install the privoxy binary - and associated files. The macsetup module's README file contains complete - instructions for its use. - - - 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 Privoxy Utility - for Mac OS X (also part of the macsetup module). This application can start - and stop the privoxy service and display its log and configuration files. - - - To uninstall, run the macsetup module's uninstall.sh as sudo from an - administrator account. - - - - -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 - - - 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. - - - - - - -Building from Source - - - The most convenient way to obtain the Privoxy sources - is to download the source tarball from our - 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 - CVS repository. - - - - -&buildsource; - - - - -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. - - - - In order not to lose your personal changes and adjustments when updating - to the latest default.action file we strongly - recommend that you use user.action and - user.filter for your local - customizations of Privoxy. See the Chapter on actions files for details. - - - - - - - - - - - -What's New in this Release - - Privoxy 3.0.19 is a stable release. - The changes since 3.0.18 stable are: - - - - - - - Bug fixes: - - - - Prevent a segmentation fault when de-chunking buffered content. - It could be triggered by malicious web servers if Privoxy was - configured to filter the content and running on a platform - where SIZE_T_MAX isn't larger than UINT_MAX, which probably - includes most 32-bit systems. On those platforms, all Privoxy - versions before 3.0.19 appear to be affected. - To be on the safe side, this bug should be presumed to allow - code execution as proving that it doesn't seems unrealistic. - - - - - Do not expect a response from the SOCKS4/4A server until it - got something to respond to. This regression was introduced - in 3.0.18 and prevented the SOCKS4/4A negotiation from working. - Reported by qqqqqw in #3459781. - - - - - - - - General improvements: - - - - Fix an off-by-one in an error message about connect failures. - - - - - Use a GNUMakefile variable for the webserver root directory and - update the path. Sourceforge changed it which broke various - web-related targets. - - - - - Update the CODE_STATUS description. - - - - - - - - - - The following changes were made between 3.0.17 and 3.0.18: - - - - - - - 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. - - - - - - - + + To uninstall, run /Applications/Privoxy/uninstall.command as sudo from an + administrator account. + + + +Installation from source + + To build and install the Privoxy source code on OS X you will need to obtain + the macsetup module from the Privoxy Sourceforge CVS repository (refer to + Sourceforge help for details of how to set up a CVS client to have read-only + access to the repository). This module contains scripts that leverage the usual + open-source tools (available as part of Apple's free of charge Xcode + distribution or via the usual open-source software package managers for OS X + (MacPorts, Homebrew, Fink etc.) to build and then install the privoxy binary + and associated files. The macsetup module's README file contains complete + instructions for its use. + + + 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 Privoxy Utility + for Mac OS X (also part of the macsetup module). This application can start + and stop the privoxy service and display its log and configuration files. + + + To uninstall, run the macsetup module's uninstall.sh as sudo from an + administrator account. + + + + +FreeBSD + + + Privoxy is part of FreeBSD's Ports Collection, you can build and install + it with cd /usr/ports/www/privoxy; make install clean. + + + + + + +Building from Source + + + The most convenient way to obtain the Privoxy source + code is to download the source tarball from our + + project download page, + or you can get the up-to-the-minute, possibly unstable, development version from + https://www.privoxy.org/. + + + +&buildsource; + + + + Windows + + Setup + + Install the Cygwin utilities needed to build Privoxy. + If you have a 64 bit CPU (which most people do by now), get the + Cygwin setup-x86_64.exe program here + (the .sig file is here). + + + Run the setup program and from View / Category select: + + + Devel + autoconf 2.5 + automake 1.15 + binutils + cmake + gcc-core + gcc-g++ + git + make + mingw64-i686-gcc-core + mingw64-i686-zlib + Editors + vim + Libs + libxslt: GNOME XSLT library (runtime) + Net + curl + openssh + Text + docbook-dssl + docbook-sgml31 + docbook-utils + openjade + Utils + gnupg + Web + w3m + + + + If you haven't already downloaded the Privoxy source code, get it now: + + + mkdir <root-dir> + cd <root-dir> + git clone https://www.privoxy.org/git/privoxy.git + + + + Get the source code (.zip or .tar.gz) for tidy from + + https://github.com/htacg/tidy-html5/releases, + unzip into <root-dir> and build the software: + + + cd <root-dir> + cd tidy-html5-x.y.z/build/cmake + cmake ../.. -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIB:BOOL=OFF -DCMAKE_INSTALL_PREFIX=/usr/local + make && make install + + + + If you want to be able to make a Windows release package, get the NSIS .zip file from + + + https://sourceforge.net/projects/nsis/files/NSIS%203/ + and extract the NSIS directory to privoxy/windows. + Then edit the windows/GNUmakefile to set the location of the NSIS executable - eg: + + +# Path to NSIS +MAKENSIS = ./nsis/makensis.exe + + + + + Build + + + To build just the Privoxy executable and not the whole installation package, do: + + + cd <root-dir>/privoxy + ./windows/MYconfigure && make + + + + Privoxy uses the GNU Autotools + for building software, so the process is: + + + $ autoheader # creates config.h.in + $ autoconf # uses config.h.in to create the configure shell script + $ ./configure [options] # creates GNUmakefile + $ make [options] # builds the program + + + + The usual configure options for building a native Windows application under cygwin are + + + + --host=i686-w64-mingw32 + --enable-mingw32 + --enable-zlib + --enable-static-linking + --disable-pthread + --disable-dynamic-pcre + + + + You can set the CFLAGS and LDFLAGS envars before + running configure to set compiler and linker flags. For example: + + + + $ export CFLAGS="-O2" # set gcc optimization level + $ export LDFLAGS="-Wl,--nxcompat" # Enable DEP + $ ./configure --host=i686-w64-mingw32 --enable-mingw32 --enable-zlib \ + > --enable-static-linking --disable-pthread --disable-dynamic-pcre + $ make # build Privoxy + + + + See the Developer's Manual + for building a Windows release package. + + + + + + + + +Keeping your Installation Up-to-Date + + + If you wish to receive an email notification whenever we release updates of + Privoxy or the actions file, subscribe + to our announce mailing list, privoxy-announce@lists.privoxy.org. + + + + In order not to lose your personal changes and adjustments when updating + to the latest default.action file we strongly + recommend that you use user.action and + user.filter for your local + customizations of Privoxy. See the Chapter on actions files for details. + + + + + + + + + + +What's New in this Release + +&changelog; @@ -1531,7 +531,6 @@ How to install the binary packages depends on your operating system: versions of Privoxy: - @@ -1562,12 +561,6 @@ How to install the binary packages depends on your operating system: 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. @@ -1622,11 +615,9 @@ How to install the binary packages depends on your operating system: that filtering does not work on compressed pages, so if you use, or want to use, filtering, you will need to force compression off. Example: - { +filter{google} +prevent-compression } .google. - Or if you use a number of filters, or filter many sites, you may just want to turn off compression for all sites in @@ -1654,14 +645,13 @@ How to install the binary packages depends on your operating system: --> - Quickstart to Using Privoxy - + @@ -1746,18 +736,6 @@ How to install the binary packages depends on your operating system: - - Please see the section Contacting the @@ -1773,7 +751,6 @@ How to install the binary packages depends on your operating system: - @@ -1850,7 +827,6 @@ How to install the binary packages depends on your operating system: set-image-blocker: - @@ -1925,7 +901,6 @@ How to install the binary packages depends on your operating system: - Advanced users will eventually want to explore &my-app; @@ -1971,7 +946,6 @@ How to install the binary packages depends on your operating system: A quick and simple step by step example: - @@ -1995,7 +969,6 @@ How to install the binary packages depends on your operating system: -
Actions Files in Use @@ -2006,7 +979,6 @@ How to install the binary packages depends on your operating system:
- @@ -2041,7 +1013,6 @@ How to install the binary packages depends on your operating system: - This is a very crude and simple example. There might be good reasons to use a @@ -2089,7 +1060,6 @@ How to install the binary packages depends on your operating system: -
Proxy Configuration Showing Mozilla/Netscape HTTP and HTTPS (SSL) Settings @@ -2101,7 +1071,6 @@ How to install the binary packages depends on your operating system:
- @@ -2110,7 +1079,6 @@ How to install the binary packages depends on your operating system: Tools -> Options -> Advanced -> Network ->Connection -> Settings - @@ -2119,7 +1087,6 @@ How to install the binary packages depends on your operating system: Edit -> Preferences -> General -> Connection Settings -> Manual Proxy Configuration - @@ -2133,7 +1100,6 @@ How to install the binary packages depends on your operating system: Edit -> Preferences -> Advanced -> Proxies -> HTTP Proxy - @@ -2153,7 +1119,6 @@ How to install the binary packages depends on your operating system: -
Proxy Configuration Showing Internet Explorer HTTP and HTTPS (Secure) Settings @@ -2165,7 +1130,6 @@ How to install the binary packages depends on your operating system:
- @@ -2185,41 +1149,38 @@ How to install the binary packages depends on your operating system: directory. Except on Win32 where it will try config.txt. - -Red Hat and Fedora + +Debian - A default Red Hat installation may not start &my-app; upon boot. It will use - the file /etc/privoxy/config as its main configuration + 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/rc.d/init.d/privoxy start + # /etc/init.d/privoxy start - + + + +FreeBSD and ElectroBSD - Or ... + 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. - - # service privoxy start - + If you installed Privoxy into a jail, the + paths above are relative to the jail root. - - - -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. + To start Privoxy manually, run: - - # /etc/init.d/privoxy start + # service privoxy onestart - @@ -2241,14 +1202,18 @@ Click on the &my-app; Icon to start Privoxy. If no co -Solaris, NetBSD, FreeBSD, HP-UX and others +Generic instructions for Unix derivates (Solaris, NetBSD, HP-UX etc.) Example Unix startup command: - - # /usr/sbin/privoxy /etc/privoxy/config + # /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. @@ -2265,71 +1230,24 @@ Example Unix startup command: 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. + 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. - An administrator username and password must be supplied in order for - the Privoxy Utility to perform any of the tasks. + 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'). - - - - -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). + 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. - -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 - - - - + Controlling Privoxy with Your Web Browser Privoxy's user interface can be reached through the special @@ -2589,20 +1506,18 @@ for details. (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 or toggle the tags that can be set based on the clients address         ▪  View the request headers. @@ -2615,7 +1530,7 @@ for details.         ▪  Documentation + url="https://www.privoxy.org/&p-version;/user-manual/">Documentation @@ -2637,10 +1552,7 @@ for details. 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. + Privoxy acts like a normal forwarding proxy. @@ -2663,9 +1575,9 @@ for details. 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 + For Unix, *BSD and GNU/Linux, all configuration files are located in + /etc/privoxy/ by default. For MS Windows and OS/2 + these are all in the same directory as the Privoxy executable. @@ -2677,13 +1589,12 @@ for details. principle configuration files are: - The main configuration file is named config - on Linux, Unix, BSD, OS/2, and AmigaOS and config.txt + on GNU/Linux, Unix, BSD, and OS/2, and config.txt on Windows. This is a required file. @@ -2735,7 +1646,6 @@ for details. - The syntax of the configuration and filter files may change between different @@ -2821,7 +1731,6 @@ for details. are three action files included with Privoxy with differing purposes: - @@ -2884,7 +1793,6 @@ for details. The default profiles, and their associated actions, as pre-defined in default.action are: - Default Configurations @@ -3002,11 +1910,9 @@ for details.
- - The list of actions files to be used are defined in the main configuration @@ -3049,7 +1955,7 @@ for details. - + Finding the Right Mix Note that some actions, like cookie suppression @@ -3074,7 +1980,7 @@ for details. - + How to Edit The easiest way to edit the actions files is with a browser by @@ -3130,14 +2036,12 @@ for details. 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 Generally, an URL pattern has the form - <domain><port>/<path>, where the - <domain>, the <port> + <host><port>/<path>, where the + <host>, 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, + The pattern matching syntax is different for the host and path parts of + the URL. The host 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, + (:). If the host part contains a numerical IPv6 address, it has to be put into angle brackets (<, >). @@ -3190,7 +2094,7 @@ for details. www.example.com/ - is a domain-only pattern and will match any request to www.example.com, + is a host-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. @@ -3201,7 +2105,7 @@ for details. www.example.com - means exactly the same. For domain-only patterns, the trailing / may + means exactly the same. For host-only patterns, the trailing / may be omitted. @@ -3250,6 +2154,15 @@ for details. + + 10.0.0.1/ + + + Matches any URL with the host address 10.0.0.1. + (Note that the real URL uses plain brackets, not angle brackets.) + + + <2001:db8::1>/ @@ -3273,11 +2186,13 @@ for details. -The Domain Pattern +The Host 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. + The matching of the host part offers some flexible options: if the + host pattern starts or ends with a dot, it becomes unanchored at that end. + The host pattern is often referred to as domain pattern as it is usually + used to match domain names and not IP addresses. For example: @@ -3384,7 +2299,7 @@ for details. -The Path Pattern +The Path Pattern Privoxy uses modern POSIX 1003.2 @@ -3446,7 +2361,7 @@ for details. 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!). + .html (and end with that!). @@ -3458,6 +2373,7 @@ for details. 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. + The path has to contain at least two slashes (including the one at the beginning). @@ -3484,18 +2400,18 @@ for details. -The Tag Pattern +The Request 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 + Request tag patterns are used to change the applying actions based on the + request's tags. Tags can be created based on HTTP headers 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 + Request tag patterns have to start with TAG:, so &my-app; + can tell them apart from other 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 ^, @@ -3511,36 +2427,110 @@ for details. - Sections can contain URL and tag patterns at the same time, - but tag patterns are checked after the URL patterns and thus + Sections can contain URL and request tag patterns at the same time, + but request 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 request tag is added, Privoxy checks right away if it's matched by one + of the request tag patterns and updates the action settings accordingly. As a result + request 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. + + + + + +The Negative Request Tag Patterns + + + To match requests that do not have a certain request tag, specify a negative tag pattern + by prefixing the tag pattern line with either NO-REQUEST-TAG: + or NO-RESPONSE-TAG: instead of TAG:. + + + + Negative request tag patterns created with NO-REQUEST-TAG: are checked + after all client headers are scanned, the ones created with NO-RESPONSE-TAG: + are checked after all server headers are scanned. In both cases all the created + tags are considered. + + + + +The Client Tag Pattern + + + + + + This is an experimental feature. The syntax is likely to change in future versions. + + + + + Client tag patterns are not set based on HTTP headers but based on + the client's IP address. Users can enable them themselves, but the + Privoxy admin controls which tags are available and what their effect + is. + + + + After a client-specific tag has been defined with the + client-specific-tag, + directive, action sections can be activated based on the tag by using a + CLIENT-TAG pattern. The CLIENT-TAG pattern is evaluated at the same priority + as URL patterns, as a result the last matching pattern wins. Tags that + are created based on client or server headers are evaluated later on + and can overrule CLIENT-TAG and 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. + The tag is set for all requests that come from clients that requested + it to be set. Note that "clients" are differentiated by IP address, + if the IP address changes the tag has to be requested again. - - 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. + Clients can request tags to be set by using the CGI interface http://config.privoxy.org/client-tags. - 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. + Example: + +# If the admin defined the client-specific-tag circumvent-blocks, +# and the request comes from a client that previously requested +# the tag to be set, overrule all previous +block actions that +# are enabled based on URL to CLIENT-TAG patterns. +{-block} +CLIENT-TAG:^circumvent-blocks$ + +# This section is not overruled because it's located after +# the previous one. +{+block{Nobody is supposed to request this.}} +example.org/blocked-example-page + @@ -3561,7 +2551,6 @@ for details. following patterns, and -block means don't block URLs that match the following patterns, even if +block previously applied. - @@ -3577,18 +2566,15 @@ for details. 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 @@ -3600,12 +2586,10 @@ for details. 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. @@ -3624,13 +2608,11 @@ for details. 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} @@ -3638,7 +2620,6 @@ for details. - If nothing is specified in any actions file, no actions are @@ -3733,9 +2714,16 @@ for details. Example usage: - - +add-header{X-User-Tracking: sucks} - + # Add a DNT ("Do not track") header to all requests, +# event to those that already have one. +# +# This is just an example, not a recommendation. +# +# There is no reason to believe that user-tracking websites care +# about the DNT header and depending on the User-Agent, adding the +# header may make user-tracking easier. +{+add-header{DNT: 1}} +/ @@ -3824,7 +2812,6 @@ for details. Example usage (section): - {+block{No nasty stuff for you.}} # Block and replace with "blocked" page .nasty-stuff.example.com @@ -3837,7 +2824,6 @@ for details. {+block{Layered ads.} +handle-as-empty-document} # Block and then ignore adserver.example.net/.*\.js$ - @@ -3908,9 +2894,7 @@ for details. Example usage: - +change-x-forwarded-for{block} - @@ -3944,7 +2928,7 @@ for details. Type: - Parameterized. + Multi-value. @@ -3988,13 +2972,11 @@ for details. Example usage (section): - # Hide Tor exit notation in Host and Referer Headers {+client-header-filter{hide-tor-exit-notation}} / - - + @@ -4031,7 +3013,7 @@ for details. Type: - Parameterized. + Multi-value. @@ -4063,7 +3045,6 @@ for details. Example usage (section): - # Tag every request with the User-Agent header {+client-header-tagger{user-agent}} @@ -4087,9 +3068,8 @@ 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}} @@ -4103,8 +3083,21 @@ TAG:^User-Agent: MPlayer/ # parts of multimedia files. {-filter -deanimate-gifs} TAG:^RANGE-REQUEST$ - - + + + +# Tag all requests with the client IP address +# +# (Technically the client IP address isn't included in the +# client headers but client-header taggers can set it anyway. +# For details see the tagger in default.filter) +{+client-header-tagger{client-ip-address}} +/ + +# Change forwarding settings for requests coming from address 10.0.0.1 +{+forward-override{forward-socks5 127.0.1.2:2222 .}} +TAG:^IP-ADDRESS: 10\.0\.0\.1$ + @@ -4204,7 +3197,6 @@ TAG:^RANGE-REQUEST$ Example usage (sections): - # Check if www.example.net/ really uses valid XHTML { +content-type-overwrite{application/xml} } www.example.net/ @@ -4214,7 +3206,6 @@ www.example.net/ www.example.net/.*\.css$ www.example.net/.*style - @@ -4293,12 +3284,10 @@ new action Example usage (section): - # Block the non-existent "Privacy-Violation:" client header { +crunch-client-header{Privacy-Violation:} } / - - + @@ -4375,14 +3364,13 @@ new action 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} -/ - +/ + @@ -4450,9 +3438,7 @@ new action Example usage: - +crunch-incoming-cookies - @@ -4529,28 +3515,229 @@ new action 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 + + + + + + Effect: + + + Deletes any Cookie: HTTP headers from client requests. + + + + + + Type: + + + Boolean. + + + + + Parameter: + + + N/A + + + + + + 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. + + + Example usage: + + +crunch-outgoing-cookies + + + + + + + + + +deanimate-gifs + + + + Typical use: + + Stop those annoying, distracting animated GIF images. + + + + + Effect: + + + De-animate GIF animations, i.e. reduce them to their first or last image. + + + + + + Type: + + + Parameterized. + + + + + Parameter: + + + last or first + + + + + + 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. + + + + + + Example usage: + + +deanimate-gifs{last} + + + + + + + + +delay-response + + + + Typical use: + + Delay responses to the client to reduce the load + + + + + Effect: + + + Delays responses to the client by sending the response in ca. 10 byte chunks. + + + + + + Type: + + + Parameterized. + + + + + Parameter: + + + Number of milliseconds + + + + + + Notes: + + + Sometimes when JavaScript code is used to fetch advertisements + it doesn't respect Privoxy's blocks and retries to fetch the + same resource again causing unnecessary load on the client. + + + This action delays responses to the client and can be combined + with blocks + to slow down the JavaScript code, thus reducing + the load on the client. + + + When used without blocks + the action can also be used to simulate a slow internet connection. + + + + + + Example usage: + + +delay-response{100} + + - -crunch-outgoing-cookies + +downgrade-http-version Typical use: - - Prevent the web server from reading any HTTP cookies from your system - + Work around (very rare) problems with HTTP/1.1 @@ -4558,14 +3745,14 @@ new action Effect: - Deletes any Cookie: HTTP headers from client requests. + Downgrades HTTP/1.1 client requests and server replies to HTTP/1.0. Type: - + Boolean. @@ -4580,29 +3767,34 @@ new action - + 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. + 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. - 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. + 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: + Example usage (section): - - +crunch-outgoing-cookies - + {+downgrade-http-version} +problem-host.example.com @@ -4611,14 +3803,14 @@ new action - -deanimate-gifs + +enable-https-filtering Typical use: - Stop those annoying, distracting animated GIF images. + Filter encrypted requests and responses @@ -4626,7 +3818,7 @@ new action Effect: - De-animate GIF animations, i.e. reduce them to their first or last image. + Encrypted requests are decrypted, filtered and forwarded encrypted. @@ -4635,7 +3827,7 @@ new action Type: - Parameterized. + Boolean. @@ -4643,50 +3835,47 @@ new action Parameter: - last or first + N/A - + 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). + This action allows &my-app; to filter encrypted requests and responses. + For this to work &my-app; has to generate a certificate and send it + to the client which has to accept it. - 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. + Before this works the directives in the + TLS section of the config + file have to be configured. - Example usage: + Example usage (section): - - +deanimate-gifs{last} - + {+enable-https-filtering} +www.example.com + - -downgrade-http-version + +external-filter Typical use: - Work around (very rare) problems with HTTP/1.1 + Modify content using a programming language of your choice. @@ -4694,7 +3883,12 @@ new action Effect: - Downgrades HTTP/1.1 client requests and server replies to HTTP/1.0. + 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 external + filter. + By default 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.) @@ -4703,7 +3897,7 @@ new action Type: - Boolean. + Multi-value. @@ -4711,44 +3905,51 @@ new action Parameter: - N/A + The name of an external content filter, as defined in the + filter file. + External filters can be defined in one or more files as defined by the + filterfile + option in the config file. + + When used in its negative form, + and without parameters, all filtering with external + filters is completely disabled. + - + 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. + External filters are scripts or programs that can modify the content in + case common filters + aren't powerful enough. With the exception that this action doesn't + use pcrs-based filters, the notes in the + filter section apply. + + + Currently external filters are executed with &my-app;'s privileges. + Only use external filters you understand and trust. + + - 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. + This feature is experimental, the syntax + may change in the future. + - Example usage (section): + Example usage: - - {+downgrade-http-version} -problem-host.example.com - + +external-filter{fancy-filter} - @@ -4861,14 +4062,12 @@ problem-host.example.com Example usage: - { +fast-redirects{simple-check} } one.example.com { +fast-redirects{check-decoded-url} } another.example.com/testing - @@ -4906,7 +4105,7 @@ problem-host.example.com Type: - Parameterized. + Multi-value. @@ -5010,108 +4209,112 @@ problem-host.example.com - +filter{js-annoyances} # Get rid of particularly annoying JavaScript abuse. + +filter{js-annoyances} # Get rid of particularly annoying JavaScript abuse. - +filter{js-events} # Kill all JS event bindings and timers (Radically destructive! Only for extra nasty sites). + +filter{js-events} # Kill JavaScript event bindings and timers (Radically destructive! Only for extra nasty sites). - +filter{html-annoyances} # Get rid of particularly annoying HTML abuse. + +filter{html-annoyances} # Get rid of particularly annoying HTML abuse. - +filter{content-cookies} # Kill cookies that come in the HTML or JS content. + +filter{content-cookies} # Kill cookies that come in the HTML or JS content. - +filter{refresh-tags} # Kill automatic refresh tags (for dial-on-demand setups). + +filter{refresh-tags} # Kill automatic refresh tags if refresh time is larger than 9 seconds. - +filter{unsolicited-popups} # Disable only unsolicited pop-up windows. Useful if your browser lacks this ability. + +filter{unsolicited-popups} # Disable only unsolicited pop-up windows. - +filter{all-popups} # Kill all popups in JavaScript and HTML. Useful if your browser lacks this ability. + +filter{all-popups} # Kill all popups in JavaScript and HTML. - +filter{img-reorder} # Reorder attributes in <img> tags to make the banners-by-* filters more effective. + +filter{img-reorder} # Reorder attributes in <img> tags to make the banners-by-* filters more effective. - +filter{banners-by-size} # Kill banners by size. + +filter{banners-by-size} # Kill banners by size. - +filter{banners-by-link} # Kill banners by their links to known clicktrackers. + +filter{banners-by-link} # Kill banners by their links to known clicktrackers. - +filter{webbugs} # Squish WebBugs (1x1 invisible GIFs used for user tracking). + +filter{webbugs} # Squish WebBugs (1x1 invisible GIFs used for user tracking). - +filter{tiny-textforms} # Extend those tiny textareas up to 40x80 and kill the hard wrap. + +filter{tiny-textforms} # Extend those tiny textareas up to 40x80 and kill the hard wrap. - +filter{jumping-windows} # Prevent windows from resizing and moving themselves. + +filter{jumping-windows} # Prevent windows from resizing and moving themselves. + +filter{frameset-borders} # Give frames a border and make them resizable. + + + +filter{iframes} # Removes all detected iframes. Should only be enabled for individual sites. - +filter{demoronizer} # Fix MS's non-standard use of standard charsets. + +filter{demoronizer} # Fix MS's non-standard use of standard charsets. - +filter{shockwave-flash} # Kill embedded Shockwave Flash objects. + +filter{shockwave-flash} # Kill embedded Shockwave Flash objects. - +filter{quicktime-kioskmode} # Make Quicktime movies saveable. + +filter{quicktime-kioskmode} # Make Quicktime movies saveable. - +filter{fun} # Text replacements for subversive browsing fun! + +filter{fun} # Text replacements for subversive browsing fun! - +filter{crude-parental} # Crude parental filtering. Note that this filter doesn't work reliably. + +filter{crude-parental} # Crude parental filtering. Note that this filter doesn't work reliably. - +filter{ie-exploits} # Disable some known Internet Explorer bug exploits. + +filter{ie-exploits} # Disable some known Internet Explorer bug exploits. - +filter{site-specifics} # Cure for site-specific problems. Don't apply generally! + +filter{site-specifics} # Cure for site-specific problems. Don't apply generally! - +filter{no-ping} # Removes non-standard ping attributes in <a> and <area> tags. + +filter{no-ping} # Removes non-standard ping attributes in <a> and <area> tags. - +filter{google} # CSS-based block for Google text ads. Also removes a width limitation and the toolbar advertisement. + +filter{google} # CSS-based block for Google text ads. Also removes a width limitation and the toolbar advertisement. - +filter{yahoo} # CSS-based block for Yahoo text ads. Also removes a width limitation. + +filter{yahoo} # CSS-based block for Yahoo text ads. Also removes a width limitation. - +filter{msn} # CSS-based block for MSN text ads. Also removes tracking URLs and a width limitation. + +filter{msn} # CSS-based block for MSN text ads. Also removes tracking URLs and a width limitation. - +filter{blogspot} # Cleans up some Blogspot blogs. Read the fine print before using this. + +filter{blogspot} # Cleans up some Blogspot blogs. Read the fine print before using this. @@ -5181,11 +4384,9 @@ new action Example usage: - +force-text-mode - - + @@ -5219,7 +4420,7 @@ new action Type: - Multi-value. + Parameterized. @@ -5252,6 +4453,32 @@ new action for socks5 connections (with remote DNS resolution). + + + forward-webserver 127.0.0.1:80 to use the HTTP + server listening at 127.0.0.1 port 80 without adjusting the + request headers. + + + This makes it more convenient to use Privoxy to make + existing websites available as onion services as well. + + + Many websites serve content with hardcoded URLs and + can't be easily adjusted to change the domain based + on the one used by the client. + + + Putting Privoxy between Tor and the webserver (or an stunnel + that forwards to the webserver) allows to rewrite headers and + content to make client and server happy at the same time. + + + Using Privoxy for webservers that are only reachable through + onion addresses and whose location is supposed to be secret + is not recommended and should not be necessary anyway. + + @@ -5274,7 +4501,8 @@ new action 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. + to exit. Due to design limitations, invalid parameter syntax isn't detected until the + action is used the first time. Use the show-url-info CGI page @@ -5287,23 +4515,23 @@ new action Example usage: - -# Always use direct connections for requests previously tagged as +# Use an ssh tunnel 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 .} \ +{+forward-override{forward-socks5 10.0.0.2:2222 .} \ -hide-if-modified-since \ -overwrite-last-modified \ } TAG:^User-Agent: fetch libfetch/2\.0$ - - + @@ -5375,13 +4603,11 @@ new action 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$ - - + @@ -5456,7 +4682,6 @@ example.org/.*\.js$ Example usage (sections): - # Generic image extensions: # {+handle-as-image} @@ -5468,7 +4693,6 @@ example.org/.*\.js$ {+block{Nasty banners.} +handle-as-image} nasty-banner-server.example.com/junk.cgi\?output=trash - @@ -5548,13 +4772,12 @@ new action 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} \ } -/ - +/ + @@ -5638,13 +4861,11 @@ new action Example usage: - # Disarm the download link in Sourceforge's patch tracker { -filter \ +content-type-overwrite{text/plain}\ +hide-content-disposition{block} } .sourceforge.net/tracker/download\.php - @@ -5727,13 +4948,11 @@ new action Example usage (section): - # Let the browser revalidate but make tracking based on the time less likely. {+hide-if-modified-since{-60} \ +overwrite-last-modified{randomize} \ +crunch-if-none-match} / - @@ -5802,10 +5021,9 @@ new action Example usage: - - +hide-from-header{block} or + +hide-from-header{block} + or +hide-from-header{spam-me-senseless@sittingduck.example.com} - @@ -5906,10 +5124,9 @@ new action Example usage: - - +hide-referrer{forge} or + +hide-referrer{forge} + or +hide-referrer{http://www.yahoo.com/} - @@ -5988,9 +5205,77 @@ new action Example usage: - +hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)} + + + + + + + + +ignore-certificate-errors + + + + Typical use: + + Filter encrypted requests and responses without verifying the certificate + + + + + Effect: + + + Encrypted requests are forwarded to sites without verifying the certificate. + + + + + + Type: + + + Boolean. + + + + + Parameter: + + + N/A + + + + + + Notes: + + + When the + +enable-https-filtering + action is used &my-app; by default verifies that the remote site uses a valid + certificate. + + + If the certificate is invalid the connection is aborted. + + + This action disabled the certificate check allowing requests to sites + with invalid certificates. + + + + + Example usage: + + + {+ignore-certificate-errors} + www.example.org + @@ -6066,13 +5351,11 @@ new action - +limit-connect{443} # Port 443 is OK. +limit-connect{80,443} # Ports 80 and 443 are OK. +limit-connect{-3, 7, 20-100, 500-} # Ports less than 3, 7, 20 to 100 and above 500 are OK. +limit-connect{-} # All ports are OK +limit-connect{,} # No HTTPS/SSL traffic is allowed - @@ -6157,10 +5440,7 @@ new action Example usages: - - +limit-cookie-lifetime{60} - - + +limit-cookie-lifetime{60} @@ -6246,7 +5526,6 @@ new action Example usage (sections): - # Selectively turn off compression, and enable a filter # @@ -6265,7 +5544,6 @@ new action # { -prevent-compression } .compusa.com/ - @@ -6357,13 +5635,11 @@ new action Example usage: - # Let the browser revalidate without being tracked across sessions { +hide-if-modified-since{-60} \ +overwrite-last-modified{randomize} \ +crunch-if-none-match} / - @@ -6427,9 +5703,15 @@ new action filter file section. - This action will be ignored if you use it together with - block. - It can be combined with + Requests can't be blocked and redirected at the same time, + applying this action together with + block + is a configuration error. Currently the request is blocked + and an error message logged, the behavior may change in the + future and result in Privoxy rejecting the action file. + + + This action can be combined with fast-redirects{check-decoded-url} to redirect to a decoded version of a rewritten URL. @@ -6448,14 +5730,13 @@ new action Example usages: - # Replace example.com's style sheet with another one { +redirect{http://localhost/css-replacements/example.com.css} } example.com/stylesheet\.css # Create a short, easy to remember nickname for a favorite site -# (relies on the browser accept and forward invalid URLs to &my-app;) -{ +redirect{http://www.privoxy.org/user-manual/actions-file.html} } +# (relies on the browser to accept and forward invalid URLs to &my-app;) +{ +redirect{https://www.privoxy.org/user-manual/actions-file.html} } a # Always use the expanded view for Undeadly.org articles @@ -6472,11 +5753,23 @@ undeadly.org/cgi\?action=article&sid=\d*$ {+redirect{s@^http://[^/]*/results\.aspx\?q=([^&]*).*@http://search.yahoo.com/search?p=$1@}} search.msn.com//results\.aspx\?q= +# Redirect http://example.com/&bla=fasel&toChange=foo (and any other value but "bar") +# to http://example.com/&bla=fasel&toChange=bar +# +# The URL pattern makes sure that the following request isn't redirected again. +{+redirect{s@toChange=[^&]+@toChange=bar@}} +example.com/.*toChange=(?!bar) + +# Add a shortcut to look up illumos bugs +{+redirect{s@^http://i([0-9]+)/.*@https://www.illumos.org/issues/$1@}} +# Redirected URL = http://i4974/ +# Redirect Destination = https://www.illumos.org/issues/4974 +i[0-9][0-9][0-9][0-9]*/ + # Redirect remote requests for this manual # to the local version delivered by Privoxy {+redirect{s@^http://www@http://config@}} www.privoxy.org/user-manual/ - @@ -6512,7 +5805,7 @@ www.privoxy.org/user-manual/ Type: - Parameterized. + Multi-value. @@ -6550,15 +5843,13 @@ www.privoxy.org/user-manual/ Example usage (section): - {+server-header-filter{html-to-xml}} example.org/xml-instance-that-is-delivered-as-html {+server-header-filter{xml-to-html}} example.org/instance-that-is-delivered-as-xml-but-is-not - - + @@ -6595,7 +5886,7 @@ example.org/instance-that-is-delivered-as-xml-but-is-not Type: - Parameterized. + Multi-value. @@ -6635,13 +5926,19 @@ example.org/instance-that-is-delivered-as-xml-but-is-not Example usage (section): - # Tag every request with the content type declared by the server {+server-header-tagger{content-type}} / - - + +# If the response has a tag starting with 'image/' enable an external +# filter that only applies to images. +# +# Note that the filter is not available by default, it's just a +# silly example. +{+external-filter{rotate-image} +force-text-mode} +TAG:^image/ + @@ -6734,9 +6031,7 @@ example.org/instance-that-is-delivered-as-xml-but-is-not Example usage: - +session-cookies-only - @@ -6836,21 +6131,15 @@ example.org/instance-that-is-delivered-as-xml-but-is-not Built-in pattern: - +set-image-blocker{pattern} - Redirect to the BSD daemon: - +set-image-blocker{http://www.freebsd.org/gifs/dae_up3.gif} - Redirect to the built-in pattern for better caching: - +set-image-blocker{http://config.privoxy.org/send-banner?type=pattern} - @@ -6858,7 +6147,7 @@ example.org/instance-that-is-delivered-as-xml-but-is-not - + Summary Note that many of these actions have the potential to cause a page to @@ -6917,7 +6206,6 @@ example.org/instance-that-is-delivered-as-xml-but-is-not Now let's define some aliases... - # Useful custom aliases we can use later. # @@ -6945,7 +6233,6 @@ example.org/instance-that-is-delivered-as-xml-but-is-not # c0 = +crunch-all-cookies c1 = -crunch-all-cookies - ...and put them to use. These sections would appear in the lower part of an @@ -6953,7 +6240,6 @@ example.org/instance-that-is-delivered-as-xml-but-is-not up for the / pattern): - # These sites are either very complex or very keen on # user data and require minimal interference to work: @@ -6977,7 +6263,6 @@ example.org/instance-that-is-delivered-as-xml-but-is-not {-filter{all-popups} -filter{unsolicited-popups}} .dabs.com .overclockers.co.uk - Aliases like shop and fragile are typically used for @@ -7001,7 +6286,7 @@ hal stop here and user.action file and see how all these pieces come together: - + match-all.action Remember all actions are disabled when matching starts, @@ -7028,7 +6313,6 @@ hal stop here multiple lines with line continuation. - { \ +change-x-forwarded-for{block} \ @@ -7036,15 +6320,14 @@ hal stop here +set-image-blocker{pattern} \ } / # Match all URLs - - + The default behavior is now set. - + default.action @@ -7064,14 +6347,12 @@ hal stop here that prevents older &my-app; versions from reading the file: - ########################################################################## # Settings -- Don't change! For internal Privoxy use ONLY. ########################################################################## {{settings}} for-privoxy-version=3.0.11 - After that comes the (optional) alias section. We'll use the example @@ -7079,7 +6360,6 @@ for-privoxy-version=3.0.11 that also explains why and how aliases are used: - ########################################################################## # Aliases @@ -7099,18 +6379,16 @@ for-privoxy-version=3.0.11 # fragile = -block -filter -crunch-all-cookies -fast-redirects -hide-referrer shop = -crunch-all-cookies -filter{all-popups} - The first of our specialized sections is concerned with fragile sites, i.e. sites that require minimum interference, because they are either very complex or very keen on tracking you (and have mechanisms in place that - make them unusable for people who avoid being tracked). We will simply use + make them unusable for people who avoid being tracked). We will use our pre-defined fragile alias instead of stating the list of actions explicitly: - ########################################################################## # Exceptions for sites that'll break under the default action set: @@ -7122,7 +6400,6 @@ for-privoxy-version=3.0.11 .office.microsoft.com # surprise, surprise! .windowsupdate.microsoft.com mail.google.com - Shopping sites are not as fragile, but they typically @@ -7130,7 +6407,6 @@ mail.google.com carts or item details. Again, we'll use a pre-defined alias: - # Shopping sites: # @@ -7139,7 +6415,6 @@ mail.google.com .worldpay.com # for quietpc.com .jungle.com .scan.co.uk - The fast-redirects @@ -7147,7 +6422,6 @@ mail.google.com breaks some sites. So disable it for popular sites where we know it misbehaves: - { -fast-redirects } login.yahoo.com @@ -7156,7 +6430,6 @@ edit.*.yahoo.com .altavista.com/.*(like|url|link):http .altavista.com/trans.*urltext=http .nytimes.com - It is important that Privoxy knows which @@ -7171,7 +6444,6 @@ edit.*.yahoo.com good start: - ########################################################################## # Images: @@ -7182,7 +6454,6 @@ edit.*.yahoo.com # { +handle-as-image } /.*\.(gif|jpe?g|png|bmp|ico)$ - And then there are known banner sources. They often use scripts to @@ -7199,7 +6470,6 @@ edit.*.yahoo.com action before, it still applies and needn't be repeated: - # Known ad generators: # @@ -7211,7 +6481,6 @@ ar.atwola.com .a[0-9].yimg.com/(?:(?!/i/).)*$ bs*.gsanet.com .qkimg.net - One of the most important jobs of Privoxy @@ -7231,7 +6500,6 @@ bs*.gsanet.com to keep the example short: - ########################################################################## # Block these fine banners: @@ -7250,12 +6518,11 @@ count*. # Site-specific patterns (abbreviated): # .hitbox.com - It's quite remarkable how many advertisers actually call their banner servers ads.company.com, or call the directory - in which the banners are stored simply banners. So the above + in which the banners are stored literally banners. So the above generic patterns are surprisingly effective. @@ -7280,7 +6547,6 @@ count*. with no block action applying. - ########################################################################## # Save some innocent victims of the above generic block patterns: @@ -7304,7 +6570,6 @@ ad[ud]*. # (adult.* and add.*) # www.globalintersec.com/adv # (adv = advanced) www.ugu.com/sui/ugu/adv - Filtering source code can have nasty side effects, @@ -7314,7 +6579,6 @@ www.ugu.com/sui/ugu/adv disables all filters in one fell swoop! - # Don't filter code! # @@ -7324,7 +6588,6 @@ bugzilla. developer. wiki. .sourceforge.net - The actual default.action is of course much more @@ -7333,7 +6596,7 @@ wiki. -user.action +user.action So far we are painting with a broad brush by setting general policies, @@ -7358,10 +6621,8 @@ wiki. - # My user.action file. <fred@example.com> - As aliases are local to the actions @@ -7369,7 +6630,6 @@ wiki. default.action, unless you repeat them here: - # Aliases are local to the file they are defined in. # (Re-)define aliases for this file: @@ -7400,8 +6660,6 @@ allow-ads = -block -filter{banners-by-size} -filter{banners-by-link} # MIME types. We want the browser to force these to be text documents. handle-as-text = -filter +-content-type-overwrite{text/plain} +-force-text-mode -hide-content-disposition - - Say you have accounts on some sites that you visit regularly, and you don't want to have to log in manually each time. So you'd like @@ -7411,30 +6669,25 @@ handle-as-text = -filter +-filter } .your-home-banking-site.com - Some file types you may not want to filter for various reasons: - # Technical documentation is likely to contain strings that might # erroneously get altered by the JavaScript-oriented filters: @@ -7446,7 +6699,6 @@ handle-as-text = -filter +-block action. Say you've @@ -7459,12 +6711,10 @@ stupid-server.example.com/ in default.action anyway: - { +block{Nasty ads.} } www.example.com/nasty-ads/sponsor\.gif another.example.net/more/junk/here/ - The URLs of dynamically generated banners, especially from large banner @@ -7478,14 +6728,12 @@ stupid-server.example.com/ browser. Use cautiously. - { +block-as-image } .doubleclick.net .fastclick.net /Realmedia/ads/ ar.atwola.com/ - Now you noticed that the default configuration breaks Forbes Magazine, @@ -7499,13 +6747,11 @@ stupid-server.example.com/ that misbehave, and add those to our personalized list of troublemakers: - { fragile } .forbes.com webmail.example.com .mybank.com - You like the fun text replacements in default.filter, @@ -7514,11 +6760,9 @@ stupid-server.example.com/ update-safe config, once and for all: - { +filter{fun} } / # For ALL sites! - Note that the above is not really a good idea: There are exceptions @@ -7535,13 +6779,11 @@ stupid-server.example.com/ sites that you feel provide value to you: - { allow-ads } .sourceforge.net .slashdot.org .osdn.net - Note that allow-ads has been aliased to @@ -7557,11 +6799,9 @@ stupid-server.example.com/ it should I choose to. - { handle-as-text } /.*\.sh$ - user.action is generally the best place to define @@ -7573,11 +6813,9 @@ stupid-server.example.com/ paths and patterns: - { +set-image-blocker{blank} } / # ALL sites - @@ -7600,7 +6838,7 @@ stupid-server.example.com/ - &my-app; supports three different filter actions: + &my-app; supports three different pcrs-based filter actions: filter to rewrite the content that is send to the client, client-header-filter @@ -7620,6 +6858,13 @@ stupid-server.example.com/ applying actions through sections with tag-patterns. + + Finally &my-app; supports the + external-filter action + to enable external filters + written in proper programming languages. + + Multiple filter files can be defined through the like this: - FILTER: foo Replace all "foo" with "bar" - Below that line, and up to the next header line, come the jobs that @@ -7692,9 +6935,37 @@ stupid-server.example.com/ in a syntax that imitates Perl's s/// operator. If you are familiar with Perl, you will find this to be quite intuitive, and may want to look at the - PCRS documentation for the subtle differences to Perl behaviour. Most - notably, the non-standard option letter U is supported, - which turns the default to ungreedy matching. + PCRS documentation for the subtle differences to Perl behaviour. + + + + Most notably, the non-standard option letter U is supported, + which turns the default to ungreedy matching (add ? to + quantifiers to turn them greedy again). + + + + The non-standard option letter D (dynamic) allows + to use the variables $host, $origin (the IP address the request came from), + $path, $url and $listen-address (the address on which Privoxy accepted the + client request. Example: 127.0.0.1:8118). + They will be replaced with the value they refer to before the filter + is executed. + + + + Note that '$' is a bad choice for a delimiter in a dynamic filter as you + might end up with unintended variables if you use a variable name + directly after the delimiter. Variables will be resolved without + escaping anything, therefore you also have to be careful not to chose + delimiters that appear in the replacement text. For example '<' should + be save, while '?' will sooner or later cause conflicts with $url. + + + + The non-standard option letter T (trivial) prevents + parsing for backreferences in the substitute. Use it if you want to include + text like '$&' in your substitute without quoting. @@ -7714,7 +6985,7 @@ stupid-server.example.com/ -Filter File Tutorial +Filter File Tutorial Now, let's complete our foo content filter. We have already defined the heading, but the jobs are still missing. Since all it does is to replace @@ -7722,9 +6993,7 @@ stupid-server.example.com/ needed: - s/foo/bar/ - But wait! Didn't the comment say that all occurrences @@ -7733,17 +7002,14 @@ stupid-server.example.com/ we'll need to add the g option: - s/foo/bar/g - Our complete filter now looks like this: - + FILTER: foo Replace all "foo" with "bar" s/foo/bar/g - Let's look at some real filters for more interesting examples. Here you see @@ -7752,14 +7018,12 @@ s/foo/bar/g - FILTER: js-annoyances Get rid of particularly annoying JavaScript abuse # Get rid of JavaScript referrer tracking. Test page: http://www.randomoddness.com/untitled.htm # s|(<script.*)document\.referrer(.*</script>)|$1"Not Your Business!"$2|Usg - Following the header line and a comment, you see the job. Note that it uses @@ -7841,12 +7105,10 @@ s|(<script.*)document\.referrer(.*</script>)|$1"Not Your Business!"$2|U this time only point out the constructs of special interest: - # The status bar is for displaying link targets, not pointless blahblah # s/window\.status\s*=\s*(['"]).*?\1/dUmMy=1/ig - \s stands for whitespace characters (space, tab, newline, @@ -7869,12 +7131,10 @@ s/window\.status\s*=\s*(['"]).*?\1/dUmMy=1/ig you move your mouse over links. - # Kill OnUnload popups. Yummy. Test: http://www.zdnet.com/zdsubs/yahoo/tree/yfs.html # s/(<body [^>]*)onunload(.*>)/$1never$2/iU - Including the @@ -7895,14 +7155,12 @@ s/(<body [^>]*)onunload(.*>)/$1never$2/iU The last example is from the fun department: - FILTER: fun Fun text replacements # Spice the daily news: # s/microsoft(?!\.com)/MicroSuck/ig - Note the (?!\.com) part (a so-called negative lookahead) @@ -7912,7 +7170,6 @@ s/microsoft(?!\.com)/MicroSuck/ig still replacing the word everywhere else. - # Buzzword Bingo (example for extended regex syntax) # @@ -7928,7 +7185,6 @@ s* industry[ -]leading \ | unrivalled \ *<font color="red"><b>BINGO!</b></font> \ *igx - The x option in this job turns on extended syntax, and allows for @@ -7963,6 +7219,7 @@ pre-defined filters for your convenience: The purpose of this filter is to get rid of particularly annoying JavaScript abuse. To that end, it + @@ -7986,7 +7243,6 @@ pre-defined filters for your convenience: - Use with caution. This is an aggressive filter, and can break sites that rely heavily on JavaScript. @@ -8411,6 +7667,78 @@ pre-defined filters for your convenience: + + +External filter syntax + + External filters are scripts or programs that can modify the content in + case common filters + aren't powerful enough. + + + External filters can be written in any language the platform &my-app; runs + on supports. + + + They are controlled with the + external-filter action + and have to be defined in the filterfile + first. + + + The header looks like any other filter, but instead of pcrs jobs, external + filters contain a single job which can be a program or a shell script (which + may call other scripts or programs). + + + External filters read the content from STDIN and write the rewritten + content to STDOUT. + The environment variables PRIVOXY_URL, PRIVOXY_PATH, PRIVOXY_HOST, + PRIVOXY_ORIGIN, PRIVOXY_LISTEN_ADDRESS can be used to get some details + about the client request. + + + &my-app; will temporary store the content to filter in the + temporary-directory. + + + +EXTERNAL-FILTER: cat Pointless example filter that doesn't actually modify the content +/bin/cat + +# Incorrect reimplementation of the filter above in POSIX shell. +# +# Note that it's a single job that spans multiple lines, the line +# breaks are not passed to the shell, thus the semicolons are required. +# +# If the script isn't trivial, it is recommended to put it into an external file. +# +# In general, writing external filters entirely in POSIX shell is not +# considered a good idea. +EXTERNAL-FILTER: cat2 Pointless example filter that despite its name may actually modify the content +while read line; \ +do \ + echo "$line"; \ +done + +EXTERNAL-FILTER: rotate-image Rotate an image by 180 degree. Test filter with limited value. +/usr/local/bin/convert - -rotate 180 - + +EXTERNAL-FILTER: citation-needed Adds a "[citation needed]" tag to an image. The coordinates may need adjustment. +/usr/local/bin/convert - -pointsize 16 -fill white -annotate +17+418 "[citation needed]" - + + + + + Currently external filters are executed with &my-app;'s privileges! + Only use external filters you understand and trust. + + + + External filters are experimental and the syntax may change in the future. + + + @@ -8471,14 +7799,12 @@ pre-defined filters for your convenience: is in an alpha or beta development stage: - <!-- @if-unstable-start --> ... beta warning HTML code goes here ... <!-- if-unstable-end@ --> - If the "unstable" symbol is set, everything in between and including @@ -8486,9 +7812,7 @@ pre-defined filters for your convenience: will disappear, leaving nothing but an empty comment: - <!-- --> - There's also an if-then-else construct and an #include @@ -8531,11 +7855,19 @@ Requests ©right; + + Privoxy is free software; you can + redistribute it and/or modify it under the terms of the + GNU General Public License, version 2, + as published by the Free Software Foundation and included in + the next section. + + -License - - &license; - +License + + + @@ -8623,35 +7955,35 @@ Requests and then some examples: - + . - Matches any single character, e.g. a, A, 4, :, or @. - + - + ? - The preceding character or expression is matched ZERO or ONE times. Either/or. - + - + + - The preceding character or expression is matched ONE or MORE times. - + - + * - The preceding character or expression is matched ZERO or MORE times. - + - + \ - The escape character denotes that the following character should be taken literally. This is used where one of the @@ -8660,25 +7992,25 @@ Requests sure the period is recognized only as a period (and not expanded to its meta-character meaning of any single character). - + - + [ ] - Characters enclosed in brackets will be matched if any of the enclosed characters are encountered. For instance, [0-9] matches any numeric digit (zero through nine). As an example, we can combine this with + to match any digit one of more times: [0-9]+. - + - + ( ) - parentheses are used to group a sub-expression, or multiple sub-expressions. - + - + | - The bar character works like an or conditional statement. A match is successful if the @@ -8687,7 +8019,7 @@ Requests and would match either this example or that example, and nothing else. - + These are just some of the ones you are likely to use when matching URLs with @@ -8803,7 +8135,7 @@ Requests - + Privoxy's Internal Pages @@ -8815,7 +8147,6 @@ Requests rules and other configuration options, and even turn Privoxy's filtering off, all with a web browser. - @@ -8826,7 +8157,6 @@ Requests necessary either. - @@ -8847,23 +8177,23 @@ Requests - Show information about the current configuration, including viewing and - editing of actions files: + View and toggle client tags:
- http://config.privoxy.org/show-status + http://config.privoxy.org/client-tags
- Show the source code version numbers: + Show information about the current configuration, including viewing and + editing of actions files: -
+
- http://config.privoxy.org/show-version + http://config.privoxy.org/show-status
@@ -8918,85 +8248,6 @@ Requests - - - - These may be bookmarked for quick reference. See next. - - - - -Bookmarklets - - Below are some bookmarklets to allow you to easily access a - mini version of some of Privoxy's - special pages. They are designed for MS Internet Explorer, but should work - equally well in Netscape, Mozilla, and other browsers which support - JavaScript. They are designed to run directly from your bookmarks - not by - clicking the links below (although that should work for testing). - - - To save them, right-click the link and choose Add to Favorites - (IE) or Add Bookmark (Netscape). You will get a warning that - the bookmark may not be safe - just click OK. Then you can run the - Bookmarklet directly from your favorites/bookmarks. For even faster access, - you can put them on the Links bar (IE) or the Personal - Toolbar (Netscape), and run them with a single click. - - - - - - - - Privoxy - Enable - - - - - - Privoxy - Disable - - - - - - Privoxy - Toggle Privoxy (Toggles between enabled and disabled) - - - - - - Privoxy- View Status - - - - - - Privoxy - Why? - - - - - - - Credit: The site which gave us the general idea for these bookmarklets is - www.bookmarklets.com. They - have more information about bookmarklets. - - - - @@ -9010,7 +8261,6 @@ Requests page is requested by your browser: - @@ -9119,7 +8369,7 @@ Requests - + 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 @@ -9149,8 +8399,7 @@ Requests 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. See the Bookmarklets section on a quick - and easy way to do this (be sure to flush caches afterward!). Looking at the + 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.) @@ -9193,7 +8442,6 @@ Requests configuration may vary): - Matches for http://www.google.com: @@ -9223,7 +8471,6 @@ Requests In file: user.action [ View ] [ Edit ] (no matches in this file) - This is telling us how we have defined our @@ -9279,12 +8526,9 @@ In file: user.action [ View ] [ Edit ]Privoxy is applying all its actions to google.com: - - - Final results: -add-header @@ -9342,8 +8586,8 @@ In file: user.action [ View ] [ Edit ] - + +set-image-blocker {pattern} + Notice the only difference here to the previous listing, is to @@ -9356,9 +8600,7 @@ In file: user.action [ View ] [ Edit ]ad.doubleclick.net: - - { +block{Domains starts with "ad"} } ad*. @@ -9368,7 +8610,6 @@ In file: user.action [ View ] [ Edit ] - We'll just show the interesting part here - the explicit matches. It is @@ -9400,9 +8641,7 @@ In file: user.action [ View ] [ Edit ] - - Matches for http://www.example.net/adsl/HOWTO/: In file: default.action [ View ] [ Edit ] @@ -9466,7 +8705,6 @@ In file: user.action [ View ] [ Edit ] - Ooops, the /adsl/ is matching /ads in our @@ -9482,13 +8720,10 @@ In file: user.action [ View ] [ Edit ] - - { -block } /adsl - Now the page displays ;-) @@ -9502,13 +8737,10 @@ In file: user.action [ View ] [ Edit ] - - { +block{Path starts with "ads".} +handle-as-image } /ads - That actually was very helpful and pointed us quickly to where the problem @@ -9522,9 +8754,7 @@ In file: user.action [ View ] [ Edit ]+filter: - - { shop } .quietpc.com .worldpay.com # for quietpc.com @@ -9532,25 +8762,20 @@ In file: user.action [ View ] [ Edit ] - { shop } is an alias that expands to { -filter -session-cookies-only }. Or you could do your own exception to negate filtering: - - - { -filter } # Disable ALL filter actions for sites in this section .forbes.com developer.ibm.com localhost - This would turn off all filtering for these sites. This is best @@ -9573,14 +8798,12 @@ In file: user.action [ View ] [ Edit ] - - + { fragile } # Handle with care: easy to break mail.google. mybank.example.com -