X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;f=doc%2Fsource%2Fuser-manual.sgml;h=b0073171df8a9093c3d4b693906419ca597c9850;hb=1fb33a20d4362b34061cfebec1d3db112f668235;hp=a7fe4aaf26a166a4da7aa6fd8aad40c8b144fe2d;hpb=2fdcad5d38e5a63296391ab509c72181b6a1d04a;p=privoxy.git diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml index a7fe4aaf..b0073171 100644 --- a/doc/source/user-manual.sgml +++ b/doc/source/user-manual.sgml @@ -6,7 +6,7 @@ This file belongs into ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/ - $Id: user-manual.sgml,v 1.35 2002/03/05 00:17:27 hal9 Exp $ + $Id: user-manual.sgml,v 1.47 2002/03/11 13:13:27 swa Exp $ Written by and Copyright (C) 2001 the SourceForge IJBSWA team. http://ijbswa.sourceforge.net @@ -28,7 +28,7 @@ Hal Burgiss Junkbuster User Manual -$Id: user-manual.sgml,v 1.35 2002/03/05 00:17:27 hal9 Exp $ +$Id: user-manual.sgml,v 1.47 2002/03/11 13:13:27 swa Exp $ @@ -40,18 +40,23 @@ Hal Burgiss - The user manual gives the users information on how to install and configure + The user manual gives users information on how to install, configure and use Internet Junkbuster. Internet - Junkbuster is an application that provides privacy and - security to users of the World Wide Web. + Junkbuster is a web proxy with advanced filtering capabilities + for protecting privacy, filtering web page content, managing cookies, + controlling access, and removing ads, banners, pop-ups and other obnoxious + Internet Junk. Junkbuster has a very flexible configuration and can be + customized to suit individual needs and tastes. Internet + Junkbuster has application for both stand-alone systems and + multi-user networks. You can find the latest version of the user manual at http://ijbswa.sourceforge.net/user-manual/. - - Feel free to send a note to the developers at ijbswa-developers@lists.sourceforge.net. - + + + @@ -73,7 +78,7 @@ You can find the latest version of the user manual at Since this is a BETA version, not all new features are well tested. This - documentation may be slightly out of sync as a result. And there - may be bugs, though hopefully not many! + documentation may be slightly out of sync as a result (especially with + CVS sources). And there may be bugs, though hopefully + not many! @@ -183,7 +189,7 @@ You can find the latest version of the user manual at Junkbuster is available as raw source code, or pre-compiled binaries. See the Junkbuster Home Page - for current release info. Junkbuster is also available - via Junkbuster + is also available via CVS. This is the recommended approach at this time. But please be aware that CVS is constantly changing, and it may break in mysterious ways. @@ -226,7 +232,7 @@ You can find the latest version of the user manual at Invoking and Configuring JunkBuster +JunkBuster Configuration + + All JunkBuster configuration is kept + in text files. These files can be edited with a text editor. + Many important aspects of JunkBuster can + also be controlled easily with a web browser. + + + + + + + +Controlling Junkbuster with Your Web Browser + + JunkBuster can be reached by the special + URL http://i.j.b/ (or alternately + http://ijbswa.sourceforge.net/config/, + which is an internal page. You will see the following section: + + + + + + +Please choose from the following options: + + * Show information about the current configuration + * Show the source code version numbers + * Show the client's request headers. + * Show which actions apply to a URL and why + * Toggle JunkBuster on or off + * Edit the actions list + + + + + + This should be self-explanatory. Note the last item is an editor for the + actions list, which is where much of the ad, banner, cookie, + and URL blocking magic is configured as well as other advanced features of + Junkbuster. This is an easy way to adjust various + aspects of Junkbuster configuration. The actions + file, and other configuration files, are explained in detail below. + Junkbuster will automatically detect any changes + to these files. + + + + Toggle JunkBuster On or Off is handy for sites that might + have problems with your current actions and filters, or just to test if + a site misbehaves, whether it is JunkBuster + causing the problem or not. Junkbuster continues + to run as a proxy in this case, but all filtering is disabled. + + + + + + + + + + + + + +Configuration Files Overview For Unix, *BSD and Linux, all configuration files are located in /etc/junkbuster/ by default. For MS Windows, OS/2, and @@ -479,8 +552,7 @@ configuration section below. HB.) actions relating to images, banners, pop-ups, access restrictions, banners and cookies. There is a CGI based editor for this file that can be accessed via http://i.j.b. This is the easiest method of - configuring actions. (Other actions + url="http://i.j.b">http://i.j.b. (Other actions files are included as well with differing levels of filtering and blocking, e.g. ijb-basic.action.) @@ -488,8 +560,9 @@ configuration section below. HB.) - The re_filterfile file can be used to rewrite the raw - page content, including text as well as embedded HTML and JavaScript. + The re_filterfile file can be used to re-write the raw + page content, including viewable text as well as embedded HTML and JavaScript, + and whatever else lurks on any given web page. @@ -513,90 +586,8 @@ configuration section below. HB.) Also, what constitutes a default setting, may change, so please check all your configuration files on important issues. - - - - - - -Command Line Options - - JunkBuster 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 - - - - After (optionally) writing the PID file, assume the user ID of - USER. Exit if the privileges are not sufficient to do - so. Unix only. - - - - - configfile - - - If no configfile is included on the command line, - JunkBuster 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. - - - - - - - - - @@ -721,10 +712,10 @@ configuration section below. HB.) apply to requests for each site. Default: Cookies to and from all destinations are kept only during the current browser session (i.e. they are not saved to disk). Pop-ups are disabled for all sites. All sites are - filtered if re_filterfile specified. No sites are blocked. An - empty image is displayed for filtered ads and other images (formerly - tinygif). The syntax of this file is explained in detail below. + filtered through selected sections of re_filterfile. No sites + are blocked. The JunkBuster logo is displayed for filtered ads and other + images . The syntax of this file is explained in detail below. @@ -738,12 +729,22 @@ configuration section below. HB.) - The re_filterfile file contains content modification rules. - These rules permit powerful changes on the content of Web pages, e.g., you - could disable your favorite JavaScript annoyances, rewrite the actual - content, or just have some fun replacing Microsoft with - MicroSuck wherever it appears on a Web page. Default: No - content modification, or whatever the developers are playing with :-/ + The re_filterfile file contains content modification rules + that use regular expressions. These rules permit powerful + changes on the content of Web pages, e.g., you could disable your favorite + JavaScript annoyances, re-write the actual displayed text, or just have some + fun replacing Microsoft with MicroSuck wherever + it appears on a Web page. Default: whatever the developers are playing with + :-/ + + + + Filtering requires buffering the page content, which may appear to slow down + page rendering since nothing is displayed until all content has passed + the filters. (It does not really take longer, but seems that way since + the page is not incrementally displayed.) This effect will be more noticeable + on slower connections. + @@ -2220,17 +2221,80 @@ Removed references to Win32. HB 09/23/01 - Filter the website through the re_filterfile: - + Apply the filters in the section_header + section of the re_filterfile file to the site(s). + Re_filterfile sections are grouped according to like + functionality. + + - +filter{filename} + +filter{section_header} + + + Filter sections that are pre-defined in the supplied + re_filterfile include: + + +
+ + + html-annoyances: Get rid of particularly annoying HTML abuse. + + + + + js-annoyances: Get rid of particularly annoying JavaScript abuse + + + + + no-poups: Kill all popups in JS and HTML + + + + + frameset-borders: Give frames a border + + + + + webbugs: Squish WebBugs (1x1 invisible GIFs used for user tracking) + + + + + no-refresh: Automatic refresh sucks on auto-dialup lines + + + + + fun: Text replacements for subversive browsing fun! + + + + + nimda: Remove (virus) Nimda code. + + + + + banners-by-size: Kill banners by size + + + + + crude-parental: Kill all web pages that contain the words "sex" or "warez" + + +
+ @@ -2368,14 +2432,18 @@ Removed references to Win32. HB 09/23/01 Decides what to do with URLs that end up tagged with {+block - +image}. There are 4 options. -image-blocker will - send a HTML blocked page, usually resulting in a - broken image icon. +image-blocker{logo} will - send a JunkBuster image. - +image-blocker{blank} will send a 1x1 transparent GIF image. - And finally, +image-blocker{http://xyz.com} will send a HTTP - temporary redirect to the specified image. This has the advantage of the - icon being being cached by the browser, which will speed up the display. + +image}, e.g an advertizement. There are five options. + -image-blocker will send a HTML blocked page, + usually resulting in a broken image icon. + +image-blocker{logo} will send a JunkBuster + logo image. +image-blocker{blank} will send a 1x1 + transparent GIF image. And finally, + +image-blocker{http://xyz.com} will send a HTTP temporary + redirect to the specified image. This has the advantage of the icon being + being cached by the browser, which will speed up the display. + +image-blocker{pattern} will send a checkboard type pattern, + which scales better than the logo (which can get blocky if the browser + enlarges it too much). @@ -2383,6 +2451,7 @@ Removed references to Win32. HB 09/23/01 +image-blocker{logo} +image-blocker{blank} + +image-blocker{pattern} +image-blocker{http://i.j.b/send-banner} @@ -2617,17 +2686,21 @@ Removed references to Win32. HB 09/23/01 - Turn on page filtering, with one exception for sourceforge: - + Turn on page filtering according to rules in the defined sections + of refilterfile, and make one exception for + sourceforge: + - # Run everything through the default filter file (re_filterfile): - {+filter} - - # But please don't re_filter code from sourceforge! + # Run everything through the filter file, using only the + # specified sections: + +filter{html-annoyances} +filter{js-annoyances} +filter{no-popups}\ + +filter{webbugs} +filter{nimda} +filter{banners-by-size} + + # Then disable filtering of code from sourceforge! {-filter} .cvs.sourceforge.net @@ -2785,16 +2858,24 @@ Removed references to Win32. HB 09/23/01 The Filter File - The filter file defines what filtering of web pages - Junkbuster does. The default filter file is - re_filterfile, located in the config directory. In this - file, any document content, whether viewable text or - embedded non-visible content, can be changed. + 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 tags and non-visible content. The default filter file is + re_filterfile, located in the config directory. + + + + The included example file is divided into sections. Each section begins + with the FILTER keyword, followed by the identifier + for that section, e.g. FILTER: webbugs. Each section performs + a similar type of filtering, such as html-annoyances. + This file uses regular expressions to alter or remove any string in the - target page. Some examples from the included default re_filterfile: + target page. The expressions can only operate on one line at a time. Some + examples from the included default re_filterfile: @@ -2806,9 +2887,24 @@ Removed references to Win32. HB 09/23/01 - # The status bar is for displaying link targets, not pointless buzzwords. - # Again, check it out on http://www.airport-cgn.de/. - s/status='.*?';*//ig + FILTER: html-annoyances + + # New browser windows should be resizeable and have a location and status + # bar. Make it so. + # + s/resizable="?(no|0)"?/resizable=1/ig s/noresize/yesresize/ig + s/location="?(no|0)"?/location=1/ig s/status="?(no|0)"?/status=1/ig + s/scrolling="?(no|0|Auto)"?/scrolling=1/ig + s/menubar="?(no|0)"?/menubar=1/ig + + # The <BLINK> tag was a crime! + # + s*<blink>|</blink>**ig + + # Is this evil? + # + #s/framespacing="?(no|0)"?//ig + #s/margin(height|width)=[0-9]*//gi @@ -2816,32 +2912,37 @@ Removed references to Win32. HB 09/23/01 Just for kicks, replace any occurrence of Microsoft with - MicroSuck: + MicroSuck, and have a little fun with topical buzzwords: + FILTER: fun + s/microsoft(?!.com)/MicroSuck/ig + + # Buzzword Bingo: + # + s/industry-leading|cutting-edge|award-winning/<font color=red><b>BINGO!</b></font>/ig - Kill those auto-refresh tags: + Kill those pesky little web-bugs: - # Kill refresh tags. I like to refresh myself. Manually. - # check it out on http://www.airport-cgn.de/ and go to the arrivals page. - # - s/<meta[^>]*http-equiv[^>]*refresh.*URL=([^>]*?)"?>/<link rev="x-refresh" href=$1>/i - s/<meta[^>]*http-equiv="?page-enter"?[^>]*content=[^>]*>/<!--no page enter for me-->/i + # webbugs: Squish WebBugs (1x1 invisible GIFs used for user tracking) + FILTER: webbugs + + s/<img\s+[^>]*?(width|height)\s*=\s*['"]?1\D[^>]*?(width|height)\s*=\s*['"]?1(\D[^>]*?)?>/<!-- Squished WebBug -->/sig @@ -2860,7 +2961,7 @@ Removed references to Win32. HB 09/23/01 When Junkbuster 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 locate in + On Linux, BSD, and Unix, these are located in /etc/junkbuster/templates by default. These may be customized, if desired. @@ -2877,8 +2978,8 @@ Removed references to Win32. HB 09/23/01 Quickstart to Using Junkbuster Install package, then run and enjoy! JunkBuster - accepts only one command line option -- the configuration file to be - used. Example Unix startup command: + is typically started by specifying the main configuration file to be + used on the command line. Example Unix startup command: @@ -2984,26 +3085,126 @@ For RedHat: /etc/rc.d/init.d/junkbuster start the developers (see below). + + + + + +Command Line Options + + JunkBuster 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, + JunkBuster 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. + + + + + + + + + + + + Contacting the Developers, Bug Reporting and Feature Requests - Please do not use the mailing lists for feature requests or - bug reports. They are not as easily tracked this way! +We value your feedback. However, to provide you with the best support, +please note: + + + + Use the Sourceforge support forum to get + help. + + Submit bugs only thru our Sourceforge bug + forum. +Make sure that the bug has not already been submitted. Please try to +verify that it is a Junkbuster bug, and not +a browser or site bug first. If you are using your own custom configuration, +please try the stock configs to see if the problem is a configuration +related bug. And if not using the latest development snapshot, please +try the latest one. Or even better, CVS sources. + + + + Submit feature requests only thru our Sourceforge feature request forum. + + + - - Feature requests and other questions should be posted to the Feature - request page at SourceForge. There is also an archive there. +For any other issues, feel free to use the mailing lists. @@ -3013,15 +3214,6 @@ communication (bugs, feature requests, etc.) Archives are available here too. - - Please report bugs, using the form at - Sourceforge. - Please try to verify that it is a Junkbuster bug, - and not a browser or site bug first. Also, check to make sure this is not - already a known bug. If you are using your own custom configuration, please - try the stock configs to see if the problem is a configuration related bug. - - @@ -3350,6 +3542,141 @@ communication (bugs, feature requests, etc.) + + + + + +JunkBuster's Internal Pages + + + Since JunkBuster proxies each requested + web page, it is easy for JunkBuster to + trap certain URLs. In this way, we can talk directly to + JunkBuster, and see how it is + configured, see how our rules are being applied, change these + rules and other configuration options, and even turn + JunkBuster's filtering off, all with + a web browser. + + + + + The URLs listed below are the special ones that allow direct access + to JunkBuster. Of course, + JunkBuster must be running to access these. If + not, you will get a friendly error message. + + + + + + + + + Junkbuster main page: + +
+ + http://ijbswa.sourceforge.net/config/ + +
+ + Alternately, this may be reached at http://i.j.b/, + but this variation may not work as reliably as the above in some + configurations. + + + + + + Show information about the current configuration: + +
+ + http://ijbswa.sourceforge.net/config/show-status + +
+ + + + + Show the source code version numbers: + +
+ + http://ijbswa.sourceforge.net/config/show-version + +
+ + + + + Show the client's request headers: + +
+ + http://ijbswa.sourceforge.net/config/show-request + +
+ + + + + Show which actions apply to a URL and why: + +
+ + http://ijbswa.sourceforge.net/config/show-url-info + +
+ + + + + Toggle JunkBuster on or off: + +
+ + http://ijbswa.sourceforge.net/config/toggle + +
+ + Short cuts. Turn off, then on: + +
+ + http://ijbswa.sourceforge.net/config/toggle?set=disable + +
+
+ + http://ijbswa.sourceforge.net/config/toggle?set=enable + +
+ + + + + Edit the actions list file: + +
+ + http://ijbswa.sourceforge.net/config/edit-actions + +
+ + + + + + + These may be bookmarked for quick reference. + + + + +