By: Junkbuster Developers
- $Id: user-manual.sgml,v 1.20 2001/10/24 23:58:25 hal9 Exp $
+ $Id: user-manual.sgml,v 1.24 2001/12/02 01:13:42 hal9 Exp $
The user manual gives the users information on how to install and
configure Internet Junkbuster. Internet Junkbuster is an application
For gzipped tar archives, unpack the source:
- tar zxvf ijb_source_2.9*
- cd ijb_source_2.9*
+ tar xzvf ijb_source_* [.tgz or .tar.gz]
+ cd ijb_source_2.9.9_alpha
For retrieving the current CVS sources, you'll need the CVS package
installed first. To download CVS source:
This will create a directory named current/, which will contain the
source tree.
- Then, in either case, to build from source:
+ Then, in either case, to build from tarball/CVS source:
- autoconf #recommended for CVS source
- ./configure
- make
+ ./configure (--help to see options)
+ make (the make from gnu, gmake for *BSD)
su
- make install
+ make -n install (to see where all the files will go)
+ make install (to really install)
For Redhat and SuSE Linux RPM packages, see below.
_________________________________________________________________
To build Redhat RPM packages, install source as above. Then:
- autoconf #recommended for CVS source
+ autoheader [suggested for CVS source]
+ autoconf [suggested for CVS source]
./configure
make redhat-dist
To build SuSE RPM packages, install source as above. Then:
- autoconf #recommended for CVS source
+ autoheader [suggested for CVS source]
+ autoconf [suggested for CVS source]
./configure
make suse-dist
This will create both binary and src RPMs in the usual places.
Example:
- /usr/src/suse/RPMS/i686/junkbuster-2.9.9-1.i686.rpm
+ /usr/src/packages/RPMS/i686/junkbuster-2.9.9-1.i686.rpm
- /usr/src/suse/SRPMS/junkbuster-2.9.9-1.src.rpm
+ /usr/src/packages/SRPMS/junkbuster-2.9.9-1.src.rpm
To install, of course:
- rpm -Uvv /usr/src/suse/RPMS/i686/junkbuster-2.9.9-1.i686.rpm
+ rpm -Uvv /usr/src/packages/RPMS/i686/junkbuster-2.9.9-1.i686.rpm
This will place the Junkbuster configuration files in
/etc/junkbuster/, and log files in /var/log/junkbuster/.
will change in time):
* The main configuration file is named config on Linux, Unix, BSD,
- and OS/2, and junkbustr.txt on Windows. On Amiga, it is
+ and OS/2, and config.txt on Windows. On Amiga, it is
AmiTCP:db/junkbuster/config.
- * The actionsfile file is used to define various "actions" relating
+ * The ijb.action 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
+ 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.
- actionsfile and re_filterfile can use Perl style regular expressions
+ ijb.action and re_filterfile can use Perl style regular expressions
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.
3.1. The Main Configuration File
Again, the main configuration file is named config on Linux/Unix/BSD
- and OS/2, and junkbustr.txt on Windows. Configuration lines consist of
- an initial keyword followed by a list of values, all separated by
+ and OS/2, and config.txt on Windows. Configuration lines consist of an
+ initial keyword followed by a list of values, all separated by
whitespace (any number of spaces or tabs). For example:
blockfile blocklist.ini
Note that all file specifications below are relative to the above two
directories!
- The "actionsfile" contains patterns to specify the actions to apply to
- requests for each site. Default: Cookies to and from all destinations
- 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 [31]below.
+ The "ijb.action" file contains patterns to specify the actions to
+ 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). 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
+ [31]below.
- actionsfile actionsfile
+ actionsfile ijb.action
The "re_filterfile" file contains content modification rules. These
rules permit powerful changes on the content of Web pages, e.g., you
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.
+ that requires cookies which you would otherwise 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
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./.
+ To enable the web-based ijb.action file 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
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
+ 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.
forward .* proxy:8080
Also, we're told they insist on getting cookies and JavaScript, so you
- need to add home.com to the cookie file. We consider JavaScript a
+ should add home.com to the cookie file. We consider JavaScript a
security risk. Java need not be enabled.
In this example direct connections are made to all "internal" domains,
but everything else goes through Lucent's LPWA by way of the company's
SOCKS gateway to the Internet.
- forward_socks4 .* lpwa.com:8000 firewall.my_company.com:1080
+ forward-socks4 .* lpwa.com:8000 firewall.my_company.com:1080
forward my_company.com .
This is how you could set up a site that always uses SOCKS but no
forwarders:
- forward_socks4a .* . firewall.my_company.com:1080
+ forward-socks4a .* . firewall.my_company.com:1080
An advanced example for network administrators:
3.2. The Actions File
- The "actionsfile" is used to define what actions Junkbuster takes, and
- thus determines how images, cookies and various other aspects of HTTP
- content and transactions are handled. Images can be anything you want,
- including ads, banners, or just some obnoxious image that you would
- rather not see. Cookies can be accepted or rejected. The default file
- is in fact named actionsfile.
+ The "ijb.action" file (formerly actionsfile) is used to define what
+ actions Junkbuster takes, and thus determines how images, cookies and
+ various other aspects of HTTP content and transactions are handled.
+ Images can be anything you want, including ads, banners, or just some
+ obnoxious image that you would rather not see. Cookies can be accepted
+ or rejected, or accepted only during the current browser session (i.e.
+ not written to disk).
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
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".
+ [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
If nothing is specified in this file, no "actions" are taken. So in
this case JunkBuster would just be a normal, non-blocking,
non-anonymizing proxy. You must specifically enable the privacy and
- blocking features you need (although the provided default actionsfile
+ blocking features you need (although the provided default ijb.action
file will give a good starting point).
Later defined actions always over-ride earlier ones. For multi-valued
websites, though. Default is "nocompression" is turned on.
+nocompression
+ * If the website sets cookies, "no-cookies-keep" will make sure they
+ are erased when you exit and restart your web browser. This makes
+ profiling cookies useless, but won't break sites which require
+ cookies so that you can log in for transactions. Default: on.
+ +no-cookies-keep
+
* Prevent the website from reading cookies:
+no-cookies-read
Turn off cookies by default, then allow a few through for specified
sites:
- # Turn off all cookies
+ # Turn off all persistant cookies
{ +no-cookies-read }
{ +no-cookies-set }
- # Execeptions to the above, sites that need cookies
+ # Allow cookies for this browser session ONLY
+ { +no-cookies-keep }
+ # Execeptions to the above, sites that benefit from persistant cookie
+ s
{ -no-cookies-read }
{ -no-cookies-set }
+ { -no-cookies-keep }
.javasoft.com
.sun.com
.yahoo.com
.msdn.microsoft.com
.redhat.com
# Alternative way of saying the same thing
- {-no-cookies-set -no-cookies-read}
+ {-no-cookies-set -no-cookies-read -no-cookies-keep}
.sourceforge.net
.sf.net
built-in "actions". Currently, an alias can contain any character
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" defined.
+ defined before anything else in the ijb.actionfile ! And there can
+ only be one set of "aliases" defined.
Now let's define a few aliases:
startup command:
- # /usr/sbin/junkbuster /etc/junkbuster/config &
+ # /usr/sbin/junkbuster /etc/junkbuster/config
+ An init script is provided for SuSE and Redhat.
+
+ For for SuSE: /etc/rc.d/junkbuster start
+
+ For RedHat: /etc/rc.d/init.d/junkbuster start
+
If no configuration file is specified on the command line, Junkbuster
will look for a file named config in the current directory. Except on
Amiga where it will look for AmiTCP:db/junkbuster/config and Win32
- where it will try junkbstr.txt. If no file is specified on the command
+ where it will try config.txt. If no file is specified on the command
line and no default configuration file can be found, Junkbuster will
fail to start.
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
- cookies, and add these to actionsfile as needed. By default, most of
- these will be blocked until you add them to the configuration. If you
- want the browser to handle this instead, you will need to edit
- actionsfile and disable this feature. If you use more than one
- browser, it would make more sense to let Junkbuster handle this. In
- which case, the browser(s) should be set to accept all cookies.
+ persistant cookies, and add these to ijb.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 ijb.action and
+ disable this feature. If you use more than one browser, it would make
+ more sense to let Junkbuster 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 actionsfile. This will turn off most actions
+ the {fragile} section of ijb.action. This will turn off most actions
for this site.
HTTP/1.1 support is not fully 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 compatiblity. For Mozilla,
look under Edit -> Preferences -> Debug -> Networking. Or set the
- "+downgrade" config option in actionsfile.
+ "+downgrade" config option in ijb.action.
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.)
+ "Actions" (as specified in ijb.action) 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
+ that apply to a given URL. In addition to the ijb.action file editor
mentioned above, Junkbuster can also be turned "on" and "off" from
this page.
[48]http://ijbswa.sourceforge.net/
- [49]http://i.j.b./
+ [49]http://i.j.b/
[50]http://www.junkbusters.com/ht/en/cookies.html
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#AEN1161
- 20. file://localhost/home/swa/sf/current/doc/source/tmp.html#AEN1167
+ 19. file://localhost/home/swa/sf/current/doc/source/tmp.html#AEN1174
+ 20. file://localhost/home/swa/sf/current/doc/source/tmp.html#AEN1180
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