From b8f8ec5c8db0ee75c42487ba74b43c299fc7530a Mon Sep 17 00:00:00 2001 From: hal9 Date: Sat, 30 Mar 2002 04:16:45 +0000 Subject: [PATCH 1/1] Sync with source. --- doc/text/faq.txt | 15 +- doc/text/user-manual.txt | 366 ++++++++++++++++++++++----------------- 2 files changed, 213 insertions(+), 168 deletions(-) diff --git a/doc/text/faq.txt b/doc/text/faq.txt index 314e777a..2996a9a5 100644 --- a/doc/text/faq.txt +++ b/doc/text/faq.txt @@ -2,7 +2,7 @@ Privoxy Frequently Asked Questions By: Privoxy Developers -$Id: faq.sgml,v 1.33 2002/03/29 01:31:48 hal9 Exp $ +$Id: faq.sgml,v 1.34 2002/03/29 04:35:56 hal9 Exp $ This FAQ gives users and developers alike answers to frequently asked questions about Privoxy. @@ -127,7 +127,7 @@ development. Other developers subsequently joined with Stefan, and have since added many new features, refinements and enhancements. The result of this effort is Privoxy. -Privoxy started with the same Junkbuster 2.0.2 code base, but has advanced +Privoxy started with the Junkbuster 2.0.2 code base, but has advanced significantly at this point. ------------------------------------------------------------------------------- @@ -626,14 +626,15 @@ programmed to handle certain pages specially. With recent versions of Privoxy (version 2.9.x), you can get some information about Privoxy and change some settings by going to http://p.p/ or, -equivalently, http://www.privoxy.org/config/ (Note that p.p is far easier to -type but may not work in some configurations). +equivalently, http://config.privoxy.org/ (Note that p.p is far easier to type +but may not work in some configurations. With the name change to Privoxy, this +is changed from the previous http://i.j.b/ or earlier 2.9.x versions). -These pages are *not* forwarded to a server on the Internet - instead they are +These pages are not forwarded to a server on the Internet - instead they are handled by a special web server which is built in to Privoxy. If you are not running Privoxy, then http://p.p/ will fail, and http:// -www.privoxy.org/config/ will return a web page telling you you're not running +config.privoxy.org/ will return a web page telling you you're not running Privoxy. If you have version 2.0.2, then the equivalent is http://example.com/ @@ -828,7 +829,7 @@ for any request to the server, and Privoxy will not be in the picture. The best thing to do is try flushing the browser's caches. And then try again. If this doesn't help, you probably have an error in the rule you applied. Try -pasting the full URL of the offending ad into http://www.privoxy.org/config/ +pasting the full URL of the offending ad into http://config.privoxy.org/ show-url-info and see if any actions match your new rule. ------------------------------------------------------------------------------- diff --git a/doc/text/user-manual.txt b/doc/text/user-manual.txt index 8992b5e8..e7233189 100644 --- a/doc/text/user-manual.txt +++ b/doc/text/user-manual.txt @@ -2,7 +2,7 @@ Privoxy User Manual By: Privoxy Developers -$Id: user-manual.sgml,v 1.60 2002/03/27 01:57:34 hal9 Exp $ +$Id: user-manual.sgml,v 1.61 2002/03/29 01:31:08 hal9 Exp $ The user manual gives users information on how to install, configure and use Privoxy. Privoxy is a web proxy with advanced filtering capabilities for @@ -31,30 +31,30 @@ Table of Contents 2.5. Windows 2.6. Other -3. Privoxy Configuration +3. Quickstart to Using Privoxy - 3.1. Controlling Privoxy with Your Web Browser - 3.2. Configuration Files Overview - 3.3. The Main Configuration File + 3.1. Command Line Options + +4. Privoxy Configuration + + 4.1. Controlling Privoxy with Your Web Browser + 4.2. Configuration Files Overview + 4.3. The Main Configuration File - 3.3.1. Defining Other Configuration Files - 3.3.2. Other Configuration Options - 3.3.3. Access Control List (ACL) - 3.3.4. Forwarding - 3.3.5. Windows GUI Options + 4.3.1. Defining Other Configuration Files + 4.3.2. Other Configuration Options + 4.3.3. Access Control List (ACL) + 4.3.4. Forwarding + 4.3.5. Windows GUI Options - 3.4. The Actions File + 4.4. The Actions File - 3.4.1. URL Domain and Path Syntax - 3.4.2. Actions - 3.4.3. Aliases + 4.4.1. URL Domain and Path Syntax + 4.4.2. Actions + 4.4.3. Aliases - 3.5. The Filter File - 3.6. Templates - -4. Quickstart to Using Privoxy - - 4.1. Command Line Options + 4.5. The Filter File + 4.6. Templates 5. Contacting the Developers, Bug Reporting and Feature Requests 6. Copyright and History @@ -67,6 +67,9 @@ Table of Contents 8.1. Regular Expressions 8.2. Privoxy's Internal Pages + + 8.2.1. Bookmarklets + 8.3. Anatomy of an Action 1. Introduction @@ -131,6 +134,8 @@ currently under development: * Improved cookie management features (e.g. session based cookies). + * Improved signal handling, and a true daemon mode (Unix). + * Builds from source on most UNIX-like systems. Packages available for: Linux (RedHat, SuSE, or Debian), Windows, Sun Solaris, Mac OSX, OS/2, HP-UX 11 and AmigaOS. @@ -295,7 +300,125 @@ the same as above for Linux/Unix. ------------------------------------------------------------------------------- -3. Privoxy Configuration +3. Quickstart to Using Privoxy + +Before launching Privoxy for the first time, you will want to configure your +browser(s) to use Privoxy and the HTTP and HTTPS proxy. The default is +localhost for the proxy address, and port 8118 (earlier versions used port +800). This is the one required configuration that must be done! + +With Netscape (and Mozilla), this can be set under Edit -> Preferences -> +Advanced -> Proxies -> HTTP Proxy. For Internet Explorer: Tools > Internet +Properties -> Connections -> LAN Setting. Then, check "Use Proxy" and fill in +the appropriate info (Address: localhost, Port: 8118). Include if HTTPS proxy +support too. + +After doing this, flush your browser's disk and memory caches to force a +re-reading of all pages and get rid of any ads that may be cached. You are now +ready to start enjoying the benefits of using Privoxy. + +Privoxy is typically started by specifying the main configuration file to be +used on the command line. Example Unix startup command: + + + # /usr/sbin/privoxy /etc/privoxy/config + + + +An init script is provided for SuSE and Redhat. + +For for SuSE: /etc/rc.d/privoxy start + +For RedHat: /etc/rc.d/init.d/privoxy start + +If no configuration file is specified on the command line, Privoxy will look +for a file named config in the current directory. Except on Win32 where it will +try config.txt. If no file is specified on the command line and no default +configuration file can be found, Privoxy will fail to start. + +The included default configuration files should give a reasonable starting +point, though may be somewhat aggressive in blocking junk. Most of the per site +configuration is done in the "actions" files. These are where various cookie +actions are defined, ad and banner blocking, and other aspects of Privoxy +configuration. There are several such files included, with varying levels of +aggressiveness. + +You will probably want to keep an eye out for sites that require persistent +cookies, and add these to default.action as needed. By default, most of these +will be accepted only during the current browser session, until you add them to +the configuration. If you want the browser to handle this instead, you will +need to edit default.action and disable this feature. If you use more than one +browser, it would make more sense to let Privoxy handle this. In which case, +the browser(s) should be set to accept all cookies. + +Privoxy is HTTP/1.1 compliant, but not all 1.1 features are as yet implemented. +If browsers that support HTTP/1.1 (like Mozilla or recent versions of I.E.) +experience problems, you might try to force HTTP/1.0 compatibility. For +Mozilla, look under Edit -> Preferences -> Debug -> Networking. Or set the +"+downgrade" config option in default.action. + +After running Privoxy for a while, you can start to fine tune the configuration +to suit your personal, or site, preferences and requirements. There are many, +many aspects that can be customized. "Actions" (as specified in default.action) +can be adjusted by pointing your browser to http://p.p/, and then follow the +link to "edit the actions list". (This is an internal page and does not require +Internet access.) + +In fact, various aspects of Privoxy configuration can be viewed from this page, +including current configuration parameters, source code version numbers, the +browser's request headers, and "actions" that apply to a given URL. In addition +to the default.action file editor mentioned above, Privoxy can also be turned +"on" and "off" from this page. + +If you encounter problems, please verify it is a Privoxy bug, by disabling +Privoxy, and then trying the same page. Also, try another browser if possible +to eliminate browser or site problems. Before reporting it as a bug, see if +there is not a configuration option that is enabled that is causing the page +not to load. You can then add an exception for that page or site. For instance, +try adding it to the {fragile} section of default.action. This will turn off +most actions for this site. For more on troubleshooting problem sites, see the +Appendix. If a bug, please report it to the developers (see below). + +------------------------------------------------------------------------------- + +3.1. Command Line Options + +Privoxy may be invoked with the following command-line options: + + * --version + + Print version info and exit, Unix only. + + * --help + + Print a short usage info and exit, Unix only. + + * --no-daemon + + Don't become a daemon, i.e. don't fork and become process group leader, + don't detach from controlling tty. Unix only. + + * --pidfile FILE + + On startup, write the process ID to FILE. Delete the FILE on exit. Failiure + to create or delete the FILE is non-fatal. If no FILE option is given, no + PID file will be used. Unix only. + + * --user USER[.GROUP] + + After (optionally) writing the PID file, assume the user ID of USER, and if + included the GID of GROUP. Exit if the privileges are not sufficient to do + so. Unix only. + + * configfile + + If no configfile is included on the command line, Privoxy will look for a + file named "config" in the current directory (except on Win32 where it will + look for "config.txt" instead). Specify full path to avoid confusion. + +------------------------------------------------------------------------------- + +4. Privoxy Configuration All Privoxy configuration is kept in text files. These files can be edited with a text editor. Many important aspects of Privoxy can also be controlled easily @@ -303,10 +426,10 @@ with a web browser. ------------------------------------------------------------------------------- -3.1. Controlling Privoxy with Your Web Browser +4.1. Controlling Privoxy with Your Web Browser Privoxy can be reached by the special URL http://p.p/ (or alternately http:// -www.privoxy.org/config/), which is an internal page. You will see the following +config.privoxy.org/), which is an internal page. You will see the following section: Please choose from the following options: @@ -334,7 +457,7 @@ in this case, but all filtering is disabled. ------------------------------------------------------------------------------- -3.2. Configuration Files Overview +4.2. 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 @@ -372,7 +495,7 @@ configuration files on important issues. ------------------------------------------------------------------------------- -3.3. The Main Configuration File +4.3. The Main Configuration File Again, the main configuration file is named config on Linux/Unix/BSD and OS/2, and config.txt on Windows. Configuration lines consist of an initial keyword @@ -402,7 +525,7 @@ There are various aspects of Privoxy behavior that can be tuned. ------------------------------------------------------------------------------- -3.3.1. Defining Other Configuration Files +4.3.1. Defining Other Configuration Files Privoxy can use a number of other files to tell it what ads to block, what cookies to accept, etc. This section of the configuration file tells Privoxy @@ -506,7 +629,7 @@ links on the "untrusted" info page. ------------------------------------------------------------------------------- -3.3.2. Other Configuration Options +4.3.2. Other Configuration Options This part of the configuration file contains options that control how Privoxy operates. @@ -665,7 +788,7 @@ proxies, you probably want to disable this. Default: enabled. ------------------------------------------------------------------------------- -3.3.3. Access Control List (ACL) +4.3.3. Access Control List (ACL) Access controls are included at the request of some ISPs and systems administrators, and are not usually needed by individual users. Please note the @@ -768,7 +891,7 @@ the proxy. ------------------------------------------------------------------------------- -3.3.4. Forwarding +4.3.4. Forwarding This feature allows chaining of HTTP requests via multiple proxies. It can be used to better protect privacy and confidentiality when accessing specific @@ -912,7 +1035,7 @@ Your squid configuration could then look like this: ------------------------------------------------------------------------------- -3.3.5. Windows GUI Options +4.3.5. Windows GUI Options Privoxy has a number of options specific to the Windows GUI interface: @@ -980,7 +1103,7 @@ console. ------------------------------------------------------------------------------- -3.4. The Actions File +4.4. The Actions File The "default.action" file (formerly actionsfile or ijb.action) is used to define what actions Privoxy takes, and thus determines how images, cookies and @@ -1005,7 +1128,7 @@ well as the configuration file syntax that Privoxy understands. ------------------------------------------------------------------------------- -3.4.1. URL Domain and Path Syntax +4.4.1. URL Domain and Path Syntax Generally, a pattern has the form /, where both the and part are optional. If you only specify a domain part, the "/" can be @@ -1067,7 +1190,7 @@ with "PaTtErN" in exactly this capitalization. ------------------------------------------------------------------------------- -3.4.2. Actions +4.4.2. Actions Actions are enabled if preceded with a "+", and disabled if preceded with a "-". Actions are invoked by enclosing the action name in curly braces (e.g. @@ -1432,7 +1555,7 @@ Appendix for a brief example on troubleshooting actions. ------------------------------------------------------------------------------- -3.4.3. Aliases +4.4.3. Aliases Custom "actions", known to Privoxy as "aliases", can be defined by combining other "actions". These can in turn be invoked just like the built-in "actions". @@ -1484,7 +1607,7 @@ Some examples using our "shop" and "fragile" aliases from above: ------------------------------------------------------------------------------- -3.5. The Filter File +4.5. The Filter File Any web page can be dynamically modified with the filter file. This modification can be removal, or re-writing, of any web page content, including @@ -1547,7 +1670,7 @@ Kill those pesky little web-bugs: ------------------------------------------------------------------------------- -3.6. Templates +4.6. Templates When Privoxy displays one of its internal pages, such as a 404 Not Found error page, it uses the appropriate template. On Linux, BSD, and Unix, these are @@ -1556,114 +1679,6 @@ desired. ------------------------------------------------------------------------------- -4. Quickstart to Using Privoxy - -Install package, then run and enjoy! Privoxy is typically started by specifying -the main configuration file to be used on the command line. Example Unix -startup command: - - - # /usr/sbin/privoxy /etc/privoxy/config - - - -An init script is provided for SuSE and Redhat. - -For for SuSE: /etc/rc.d/privoxy start - -For RedHat: /etc/rc.d/init.d/privoxy start - -If no configuration file is specified on the command line, Privoxy will look -for a file named config in the current directory. Except on Win32 where it will -try config.txt. If no file is specified on the command line and no default -configuration file can be found, Privoxy will fail to start. - -Be sure your browser is set to use the proxy which is by default at localhost, -port 8118. With Netscape (and Mozilla), this can be set under Edit -> -Preferences -> Advanced -> Proxies -> HTTP Proxy. For Internet Explorer: Tools -> Internet Properties -> Connections -> LAN Setting. Then, check "Use Proxy" -and fill in the appropriate info (Address: localhost, Port: 8118). Include if -HTTPS proxy support too. - -The included default configuration files should give a reasonable starting -point, though may be somewhat aggressive in blocking junk. You will probably -want to keep an eye out for sites that require persistent cookies, and add -these to default.action as needed. By default, most of these will be accepted -only during the current browser session, until you add them to the -configuration. If you want the browser to handle this instead, you will need to -edit default.action and disable this feature. If you use more than one browser, -it would make more sense to let Privoxy handle this. In which case, the browser -(s) should be set to accept all cookies. - -If a particular site shows problems loading properly, try adding it to the -{fragile} section of default.action. This will turn off most actions for this -site. - -Privoxy is HTTP/1.1 compliant, but not all 1.1 features are as yet implemented. -If browsers that support HTTP/1.1 (like Mozilla or recent versions of I.E.) -experience problems, you might try to force HTTP/1.0 compatibility. For -Mozilla, look under Edit -> Preferences -> Debug -> Networking. Or set the -"+downgrade" config option in default.action. - -After running Privoxy for a while, you can start to fine tune the configuration -to suit your personal, or site, preferences and requirements. There are many, -many aspects that can be customized. "Actions" (as specified in default.action) -can be adjusted by pointing your browser to http://p.p/, and then follow the -link to "edit the actions list". (This is an internal page and does not require -Internet access.) - -In fact, various aspects of Privoxy configuration can be viewed from this page, -including current configuration parameters, source code version numbers, the -browser's request headers, and "actions" that apply to a given URL. In addition -to the default.action file editor mentioned above, Privoxy can also be turned -"on" and "off" from this page. - -If you encounter problems, please verify it is a Privoxy bug, by disabling -Privoxy, and then trying the same page. Also, try another browser if possible -to eliminate browser or site problems. Before reporting it as a bug, see if -there is not a configuration option that is enabled that is causing the page -not to load. You can then add an exception for that page or site. If a bug, -please report it to the developers (see below). - -------------------------------------------------------------------------------- - -4.1. Command Line Options - -Privoxy may be invoked with the following command-line options: - - * --version - - Print version info and exit, Unix only. - - * --help - - Print a short usage info and exit, Unix only. - - * --no-daemon - - Don't become a daemon, i.e. don't fork and become process group leader, - don't detach from controlling tty. Unix only. - - * --pidfile FILE - - On startup, write the process ID to FILE. Delete the FILE on exit. Failiure - to create or delete the FILE is non-fatal. If no FILE option is given, no - PID file will be used. Unix only. - - * --user USER[.GROUP] - - After (optionally) writing the PID file, assume the user ID of USER, and if - included the GID of GROUP. Exit if the privileges are not sufficient to do - so. Unix only. - - * configfile - - If no configfile is included on the command line, Privoxy will look for a - file named "config" in the current directory (except on Win32 where it will - look for "config.txt" instead). Specify full path to avoid confusion. - -------------------------------------------------------------------------------- - 5. Contacting the Developers, Bug Reporting and Feature Requests We value your feedback. However, to provide you with the best support, please @@ -1878,10 +1893,10 @@ perl5.6/pod/perlre.html 8.2. Privoxy's Internal Pages Since Privoxy proxies each requested web page, it is easy for Privoxy to trap -certain URLs. In this way, we can talk directly to Privoxy, and see how it is -configured, see how our rules are being applied, change these rules and other -configuration options, and even turn Privoxy's filtering off, all with a web -browser. +certain special URLs. In this way, we can talk directly to Privoxy, and see how +it is configured, see how our rules are being applied, change these rules and +other configuration options, and even turn Privoxy's filtering off, all with a +web browser. The URLs listed below are the special ones that allow direct access to Privoxy. Of course, Privoxy must be running to access these. If not, you will get a @@ -1889,45 +1904,74 @@ friendly error message. Internet access is not necessary either. * Privoxy main page: - http://www.privoxy.org/config/ + http://config.privoxy.org/ Alternately, this may be reached at http://p.p/, but this variation may not work as reliably as the above in some configurations. * Show information about the current configuration: - http://www.privoxy.org/config/show-status + http://config.privoxy.org/show-status * Show the source code version numbers: - http://www.privoxy.org/config/show-version + http://config.privoxy.org/show-version * Show the client's request headers: - http://www.privoxy.org/config/show-request + http://config.privoxy.org/show-request * Show which actions apply to a URL and why: - http://www.privoxy.org/config/show-url-info + http://config.privoxy.org/show-url-info - * Toggle Privoxy on or off: + * Toggle Privoxy on or off. In this case, "Privoxy" continues to run, but + only as a pass-through proxy, with no actions taking place: - http://www.privoxy.org/config/toggle + http://config.privoxy.org/toggle Short cuts. Turn off, then on: - http://www.privoxy.org/config/toggle?set=disable + http://config.privoxy.org/toggle?set=disable - http://www.privoxy.org/config/toggle?set=enable + http://config.privoxy.org/toggle?set=enable * Edit the actions list file: - http://www.privoxy.org/config/edit-actions + http://config.privoxy.org/edit-actions These may be bookmarked for quick reference. ------------------------------------------------------------------------------- +8.2.1. Bookmarklets + +Here are some bookmarklets to allow you to easily access a "mini" version of +this page. 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 will 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 +favourites/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. + + * Enable Privoxy + + * Disable Privoxy + + * Toggle Privoxy (Toggles between enabled and disabled) + + * View Privoxy Status + +Credit: The site which gave me the general idea for these bookmarklets is +www.bookmarklets.com. They have more information about bookmarklets. + +------------------------------------------------------------------------------- + 8.3. Anatomy of an Action The way Privoxy applies "actions" to any given URL can be complex, and not @@ -1936,9 +1980,9 @@ able to see just what Privoxy is doing. Especially, if something Privoxy is doing is causing us a problem inadvertantly. It can be a little daunting to look at the actions files themselves, since they tend to be filled with "regular expressions" whose consequences are not always so obvious. Privoxy -provides the http://www.privoxy.org/config/show-url-info page that can show us -very specifically how actions are being applied to any given URL. This is a big -help for troubleshooting. +provides the http://config.privoxy.org/show-url-info page that can show us very +specifically how actions are being applied to any given URL. This is a big help +for troubleshooting. First, enter one URL (or partial URL) at the prompt, and then Privoxy will tell us how the current configuration will handle it. This will not help with -- 2.39.2