By: Junkbuster Developers
- $Id: user-manual.sgml,v 1.15 2001/10/14 23:46:24 hal9 Exp $
+ $Id: user-manual.sgml,v 1.20 2001/10/24 23:58:25 hal9 Exp $
The user manual gives the users information on how to install and
configure Internet Junkbuster. Internet Junkbuster is an application
blocking and cookie management, this is a list of new features
currently under development:
+ * A browser based configuration utility (WIP at [24]http://i.j.b).
* Modularized configuration that will allow for system wide
- settings, and individual user settings.
- * A browser based GUI configuration utility (not finished).
+ settings, and individual user settings. (not implemented yet)
* Blocking of annoying pop-up browser windows (previously available
as a patch).
- * Partial support for HTTP/1.1.
+ * Support for HTTP/1.1 (partially implemented at this point).
* Support for Perl Compatible Regular Expressions in the
configuration files, and generally a more sophisticated
configuration syntax over previous versions.
* Web page content filtering.
* Multi-threaded.
+
+ In addition, the configuration is more versatile overall.
_________________________________________________________________
2. Installation
Junkbuster is available as raw source code, or pre-compiled binaries.
- See the [24]Junkbuster Home Page for current release info. Junkbuster
- is also available via [25]CVS. This is the recommended approach at
+ See the [25]Junkbuster Home Page for current release info. Junkbuster
+ is also available via [26]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.
_________________________________________________________________
Then, in either case, to build from source:
+ autoconf #recommended for CVS source
./configure
make
su
To build Redhat RPM packages, install source as above. Then:
+ autoconf #recommended for CVS source
./configure
make redhat-dist
To build SuSE RPM packages, install source as above. Then:
+ autoconf #recommended for CVS source
./configure
make suse-dist
The OS/2 version of Junkbuster requires the EMX runtime library to be
installed. The EMX runtime library is available on the hobbes OS/2
archive, among many other locations:
- [26]http://hobbes.nmsu.edu/cgi-bin/h-search?sh=1&button=Search&key=emx
+ [27]http://hobbes.nmsu.edu/cgi-bin/h-search?sh=1&button=Search&key=emx
rt.zip&stype=all&sort=type&dir=%2Fpub%2Fos2%2Fdev%2Femx%2Fv0.9d
Junkbuster is packaged in a WarpIN self- installing archive. The
need a working EMX/GCC environment, plus several Unix-like tools. The
Hobbes OS/2 archive is a good place to start when building such an
environment. A set of Unix-like tools named gnupack is located here:
- [27]http://hobbes.nmsu.edu/cgi-bin/h-search?sh=1&key=gnupack&stype=all
+ [28]http://hobbes.nmsu.edu/cgi-bin/h-search?sh=1&key=gnupack&stype=all
&sort=type&dir=%2Fpub%2Fos2%2Fapps
Once you have the source code unpacked as above, you can build the
Some quick notes on other Operating Systems.
For FreeBSD (and other *BSDs?), the build will need gmake instead of
- the included make. gmake is available from [28]http://www.gnu.org. The
+ the included make. gmake is available from [29]http://www.gnu.org. The
rest should be the same as above for Linux/Unix.
_________________________________________________________________
* The main configuration file is named config on Linux, Unix, BSD,
and OS/2, and junkbustr.txt on Windows. On Amiga, it is
AmiTCP:db/junkbuster/config.
- * The actionsfile file is used to define various actions relating to
- images, banners, pop-ups, banners and cookies.
+ * The actionsfile file is used to define various "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 [30]http://i.j.b./. This is the easiest method of
+ configuring actions. (Still under active development.)
* The re_filterfile file can be used to rewrite the raw page
content, including text as well as embedded HTML and JavaScript.
for maximum flexibility. All files use the "#" character to denote a
comment. Such lines are not processed by Junkbuster. After making any
changes, restart Junkbuster in order for the changes to take effect.
+
+ While under development, the configuration content is subject to
+ change. The below documentation may not be accurate by the time you
+ read this. Also, what constitutes a "default" setting, may change, so
+ please check all your configuration files on important issues.
_________________________________________________________________
3.1. The Main Configuration File
Indicates that the blockfile is named "blocklist.ini".
- The "#" indicates a comment. Any part of a line following a "#" is
+ A "#" indicates a comment. Any part of a line following a "#" is
ignored, except if the "#" is preceded by a "\".
Thus, by placing a "#" at the start of an existing configuration line,
Long lines can be continued on the next line by using a "\" as the
very last character.
- There are various aspects of Junkbuster behavior that can be adjusted.
+ There are various aspects of Junkbuster behavior that can be tuned.
_________________________________________________________________
3.1.1. Defining Other Configuration Files
are filtered. Popups 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 [29]below.
+ "tinygif"). The syntax of this file is explained in detail [31]below.
actionsfile actionsfile
want to serve requests from other machines (e.g. on your local
network) as well, you will need to override the default. The syntax is
"listen-address [<ip-address>]:<port>". If you leave out the IP
- adress, junkbuster will bind to all interfaces (addresses) on your
- machine and may become reachable from the internet. In that case,
- consider using access control lists (acl's) (see "aclfile" above).
+ address, junkbuster will bind to all interfaces (addresses) on your
+ machine and may become reachable from the Internet. In that case,
+ consider using access control lists (acl's) (see "aclfile" above), or
+ a firewall.
For example, suppose you are running Junkbuster on a machine which has
the address 192.168.0.1 on your local private network (192.168.0.0)
Just set "toggle 0".
The Windows version of Junkbuster puts an icon in the system tray,
- which allows you to change this option without having to edit this
- file. If you right-click on that icon (or select the "Options" menu),
- one choice is "Enable". Clicking on enable toggles Junkbuster on and
- off. This is useful if you want to temporarily disable Junkbuster,
- e.g., to access a site that requires cookies which you normally have
- blocked.
+ which also allows you to change this option. If you right-click on
+ that icon (or select the "Options" menu), one choice is "Enable".
+ Clicking on enable toggles Junkbuster on and off. This is useful if
+ you want to temporarily disable Junkbuster, e.g., to access a site
+ that requires cookies which you normally have blocked. This can also
+ be toggled via a web browser at the Junkbuster internal address of
+ [32]http://i.j.b./ on any platform.
"toggle 1" means Junkbuster runs normally, "toggle 0" means that
- Junkbuster becomes a non-anonymizing non-blocking proxy. Default: 1.
+ Junkbuster becomes a non-anonymizing non-blocking proxy. Default: 1
+ (on).
toggle 1
+
+ For content filtering, i.e. the "+filter" and "+deanimate-gif"
+ actions, it is neccessary that Junkbuster buffers the entire document
+ body. This can be potentially dangerous, since a server could just
+ keep sending data indefinitely and wait for your RAM to exhaust. With
+ nasty consequences.
+
+ The buffer-limit option lets you set the maximum size in Kbytes that
+ each buffer may use. When the documents buffer exceeds this size, it
+ is flushed to the client unfiltered and no further attempt to filter
+ the rest of it is made. Remember that there may multiple threads
+ running, which might require increasing the "buffer-limit" Kbytes
+ each, unless you have enabled "single-threaded" above.
+
+ buffer-limit 4069
+
+ To enable the web-based actionsfile editor set enable-edit-actions to
+ 1, or 0 to disable. Note that you must have compiled JunkBuster with
+ support for this feature, otherwise this option has no effect. This
+ internal page can be reached at [33]http://i.j.b./.
+
+ Security note: If this is enabled, anyone who can use the proxy can
+ edit the actions file, and their changes will affect all users. For
+ shared proxies, you probably want to disable this. Default: enabled.
+
+ enable-edit-actions 1
+
+ Allow JunkBuster to be toggled on and off remotely, using your web
+ browser. Set "enable-remote-toggle"to 1 to enable, and 0 to disable.
+ Note that you must have compiled JunkBuster with support for this
+ feature, otherwise this option has no effect.
+
+ Security note: If this is enabled, anyone who can use the proxy can
+ toggle it on or off (see [34]http://i.j.b./), and their changes will
+ affect all users. For shared proxies, you probably want to disable
+ this. Default: enabled.
+
+ enable-remote-toggle 1
_________________________________________________________________
3.1.3. Access Control List (ACL)
This feature allows chaining of HTTP requests via multiple proxies. It
can be used to better protect privacy and confidentiality when
accessing specific domains by routing requests to those domains to a
- special purpose filtering proxy such as lpwa.com.
+ special purpose filtering proxy such as lpwa.com. Or to use a caching
+ proxy to speed up browsing.
It can also be used in an environment with multiple networks to route
requests via multiple gateways allowing transparent access to multiple
To determine which actions apply to a request, the URL of the request
is compared to all patterns in this file. Every time it matches, the
list of applicable actions for the URL is incrementally updated. You
- can trace this process by visiting [30]http://i.j.b/show-url-info.
+ can trace this process by visiting [35]http://i.j.b/show-url-info.
+
+ The actions file can be edited with a browser by loading
+ [36]http://i.j.b, and then select "Edit Actions".
There are four types of lines in this file: comments (begin with a "#"
character), actions, aliases and patterns, all of which are explained
- below.
+ below, as well as the configuration file syntax that Junkbuster
+ understands.
_________________________________________________________________
3.2.1. URL Domain and Path Syntax
If Junkbuster was compiled with "pcre" support (default), Perl
compatible regular expressions can be used. See the pcre/docs/
direcory or "man perlre" (also available on
- [31]http://www.perldoc.com/perl5.6/pod/perlre.html) for details. A
- brief discussion of regular expressions is in the [32]Appendix. For
+ [37]http://www.perldoc.com/perl5.6/pod/perlre.html) for details. A
+ brief discussion of regular expressions is in the [38]Appendix. For
instance:
/.*/advert[0-9]+\.jpe?g - would match a URL from any domain, with any
except space, tab, "=", "{" or "}". But please use only "a"- "z",
"0"-"9", "+", and "-". Alias names are not case sensitive, and must be
defined before anything else in actionsfile! And there can only be one
- set of "aliases" of defined.
+ set of "aliases" defined.
Now let's define a few aliases:
After running Junkbuster 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" (from actionsfile) can be adjusted by pointing your browser
+ to [39]http://i.j.b./, 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 Junkbuster 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 actionsfile editor
+ mentioned above, Junkbuster can also be turned "on" and "off" from
+ this page.
If you encounter problems, please verify it is a Junkbuster bug, by
disabling Junkbuster, and then trying the same page. Also, try another
5. Contact the Developers
Feature requests and other questions should be posted to the
- [33]Feature request page at SourceForge. There is also an archive
+ [40]Feature request page at SourceForge. There is also an archive
there.
Anyone interested in actively participating in development and related
- discussions can join the appropriate mailing list [34]here. Archives
+ discussions can join the appropriate mailing list [41]here. Archives
are available here too.
- Please report bugs, using the form at [35]Sourceforge. Please try to
+ Please report bugs, using the form at [42]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.
_________________________________________________________________
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details, which is available from
- [36]the Free Software Foundation, Inc, 59 Temple Place - Suite 330,
+ [43]the Free Software Foundation, Inc, 59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.
_________________________________________________________________
6.2. History
Junkbuster was originally written by Anonymous Coders and
- [37]JunkBusters Corporation, and was released as free open-source
- software under the GNU GPL. [38]Stefan Waldherr made many
- improvements, and started the [39]SourceForge project to rekindle
+ [44]JunkBusters Corporation, and was released as free open-source
+ software under the GNU GPL. [45]Stefan Waldherr made many
+ improvements, and started the [46]SourceForge project to rekindle
development. The last stable release was v2.0.2, which has now grown
whiskers ;-).
_________________________________________________________________
7. See also
- [40]http://sourceforge.net/projects/ijbswa
+ [47]http://sourceforge.net/projects/ijbswa
- [41]http://ijbswa.sourceforge.net/
+ [48]http://ijbswa.sourceforge.net/
- [42]http://ijbswa.sourceforge.net/config/
+ [49]http://i.j.b./
- [43]http://www.junkbusters.com/ht/en/cookies.html
+ [50]http://www.junkbusters.com/ht/en/cookies.html
- [44]http://www.waldherr.org/junkbuster/
+ [51]http://www.waldherr.org/junkbuster/
- [45]http://privacy.net/analyze/
+ [52]http://privacy.net/analyze/
- [46]http://www.squid-cache.org/
+ [53]http://www.squid-cache.org/
_________________________________________________________________
8. Appendix
you know enough to get started, you can learn more on your own :/
More reading on Perl Compatible Regular expressions:
- [47]http://www.perldoc.com/perl5.6/pod/perlre.html
+ [54]http://www.perldoc.com/perl5.6/pod/perlre.html
References
10. file://localhost/home/swa/sf/current/doc/source/tmp.html#INSTALLATION-WIN
11. file://localhost/home/swa/sf/current/doc/source/tmp.html#INSTALLATION-OTHER
12. file://localhost/home/swa/sf/current/doc/source/tmp.html#CONFIGURATION
- 13. file://localhost/home/swa/sf/current/doc/source/tmp.html#AEN152
+ 13. file://localhost/home/swa/sf/current/doc/source/tmp.html#AEN158
14. file://localhost/home/swa/sf/current/doc/source/tmp.html#ACTIONSFILE
15. file://localhost/home/swa/sf/current/doc/source/tmp.html#FILTERFILE
16. file://localhost/home/swa/sf/current/doc/source/tmp.html#QUICKSTART
17. file://localhost/home/swa/sf/current/doc/source/tmp.html#CONTACT
18. file://localhost/home/swa/sf/current/doc/source/tmp.html#COPYRIGHT
- 19. file://localhost/home/swa/sf/current/doc/source/tmp.html#AEN1103
- 20. file://localhost/home/swa/sf/current/doc/source/tmp.html#AEN1109
+ 19. file://localhost/home/swa/sf/current/doc/source/tmp.html#AEN1161
+ 20. file://localhost/home/swa/sf/current/doc/source/tmp.html#AEN1167
21. file://localhost/home/swa/sf/current/doc/source/tmp.html#SEEALSO
22. file://localhost/home/swa/sf/current/doc/source/tmp.html#APPENDIX
23. file://localhost/home/swa/sf/current/doc/source/tmp.html#REGEX
- 24. http://sourceforge.net/projects/ijbswa/
- 25. http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/ijbswa/current/
- 26. http://hobbes.nmsu.edu/cgi-bin/h-search?sh=1&button=Search&key=emxrt.zip&stype=all&sort=type&dir=%2Fpub%2Fos2%2Fdev%2Femx%2Fv0.9d
- 27. http://hobbes.nmsu.edu/cgi-bin/h-search?sh=1&key=gnupack&stype=all&sort=type&dir=%2Fpub%2Fos2%2Fapps
- 28. http://www.gnu.org/
- 29. file://localhost/home/swa/sf/current/doc/source/tmp.html#ACTIONSFILE
- 30. http://i.j.b/show-url-info
- 31. http://www.perldoc.com/perl5.6/pod/perlre.html
- 32. file://localhost/home/swa/sf/current/doc/source/tmp.html#REGEX
- 33. http://sourceforge.net/tracker/?atid=361118&group_id=11118&func=browse
- 34. http://sourceforge.net/mail/?group_id=11118
- 35. http://sourceforge.net/tracker/?group_id=11118&atid=111118
- 36. http://www.gnu.org/copyleft/gpl.html
- 37. http://www.junkbusters.com/ht/en/ijbfaq.html
- 38. http://www.waldherr.org/junkbuster/
- 39. http://sourceforge.net/projects/ijbswa/
- 40. http://sourceforge.net/projects/ijbswa
- 41. http://ijbswa.sourceforge.net/
- 42. http://ijbswa.sourceforge.net/config/
- 43. http://www.junkbusters.com/ht/en/cookies.html
- 44. http://www.waldherr.org/junkbuster/
- 45. http://privacy.net/analyze/
- 46. http://www.squid-cache.org/
- 47. http://www.perldoc.com/perl5.6/pod/perlre.html
+ 24. http://i.j.b/
+ 25. http://sourceforge.net/projects/ijbswa/
+ 26. http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/ijbswa/current/
+ 27. http://hobbes.nmsu.edu/cgi-bin/h-search?sh=1&button=Search&key=emxrt.zip&stype=all&sort=type&dir=%2Fpub%2Fos2%2Fdev%2Femx%2Fv0.9d
+ 28. http://hobbes.nmsu.edu/cgi-bin/h-search?sh=1&key=gnupack&stype=all&sort=type&dir=%2Fpub%2Fos2%2Fapps
+ 29. http://www.gnu.org/
+ 30. http://i.j.b/
+ 31. file://localhost/home/swa/sf/current/doc/source/tmp.html#ACTIONSFILE
+ 32. http://i.j.b/
+ 33. http://i.j.b/
+ 34. http://i.j.b/
+ 35. http://i.j.b/show-url-info
+ 36. http://i.j.b/
+ 37. http://www.perldoc.com/perl5.6/pod/perlre.html
+ 38. file://localhost/home/swa/sf/current/doc/source/tmp.html#REGEX
+ 39. http://i.j.b/
+ 40. http://sourceforge.net/tracker/?atid=361118&group_id=11118&func=browse
+ 41. http://sourceforge.net/mail/?group_id=11118
+ 42. http://sourceforge.net/tracker/?group_id=11118&atid=111118
+ 43. http://www.gnu.org/copyleft/gpl.html
+ 44. http://www.junkbusters.com/ht/en/ijbfaq.html
+ 45. http://www.waldherr.org/junkbuster/
+ 46. http://sourceforge.net/projects/ijbswa/
+ 47. http://sourceforge.net/projects/ijbswa
+ 48. http://ijbswa.sourceforge.net/
+ 49. http://i.j.b/
+ 50. http://www.junkbusters.com/ht/en/cookies.html
+ 51. http://www.waldherr.org/junkbuster/
+ 52. http://privacy.net/analyze/
+ 53. http://www.squid-cache.org/
+ 54. http://www.perldoc.com/perl5.6/pod/perlre.html
projects / privoxy.git / blobdiff