JUNKBUSTER(1)JUNKBUSTER(1)NAMEjunkbuster - The Internet Junkbuster Proxy (TM)
SYNOPSISjunkbuster configfile (Version 2.0 onwards)
junkbstr.exe configfile (Windows)
junkbuster [-a] [-y] [-s] [-c] [-v]
[-u user_agent] [-r referer] [-t from]
[-b blockfile] [-j jarfile] [-l logfile]
[-w NAME=VALUE] [-x Header_text]
[-h [bind_host_address][:bind_port]]
[-f forward_host[:port]] [-d N]
[-g gw_protocol[:[gw_host][:gw_port]]]
(Version 1.4 and earlier)
DESCRIPTIONjunkbuster is an instrumentable proxy that filters the
HTTP stream between web servers and browsers. Its main
purpose is to enhance privacy.
Versions before 2.0 used command-line options; Versions
from 2.0 onward use a configuration file. The following
descriptions of the options first give the older command-
line usage, then the new configfile line.
In Versions 2.0.1 upwards on Windows, a start-up message
is printed and the configuration is read from the file
junkbstr.ini if it exists and no argument was given.
All files except the configfile are checked for changes
before each page is fetched, so they may edited without
restarting the proxy.
OPTIONS
-b blockfile (Old) blockfile blockfile (New)
Block requests to URLs matching any pattern given
in the lines of the blockfile. The junkbuster
instead returns status 202, indicating that the
request has been accepted (though not completed),
and a message identifying itself (though the
browser may display only a broken image icon).
(Versions before 2.0 returned an error 403 (Forbid
den).) The syntax of a pattern is
[domain][:port][/path] (the http:// or https://
protocol part is omitted). To decide if a pattern
matches a target, the domains are compared first,
then the paths.
To compare the domains, the pattern domain and the target
domain specified in the URL are each broken into their
components. (Components are separated by the . (period)
character.) Next each of the target components is com
pared with the corresponding pattern component: last with
last, next-to-last with next-to-last, and so on. (This is
http://www.junkbusters.com/ht/en/ijb2.0man.html 1
JUNKBUSTER(1)JUNKBUSTER(1)
called right-anchored matching.) If all of the pattern
components find their match in the target, then the
domains are considered a match. Case is irrelevant when
comparing domain components.
A successfully matching pattern can be an anchored sub
string of a target, but not vice versa. Thus if a pattern
doesn't specify a domain, it matches all domains. Fur
thermore, when comparing two components, the components
must either match in their entirety or up to a wildcard *
(star character) in the pattern. The wildcard feature
implements only a "prefix" match capability ("abc*" vs.
"abcdefg"), not suffix matching ("*efg" vs. "abcdefg") or
infix matching ("abc*efg" vs. "abcdefg"). The feature is
restricted to the domain component; it is unrelated to the
optional regular expression feature in the path (described
below).
If a numeric port is specified in the pattern domain, then
the target port must match as well. The default port in a
target is port 80.
If the domain and port match, then the target URL path is
checked for a match against the path in the pattern.
Paths are compared with a simple case-sensitive left-
anchored substring comparison. Once again, the pattern
can be an anchored substring of the target, but not vice
versa. A path of / (slash) would match all paths. Wild
cards are not considered in path comparisons.
For example, the target URL
the.yellow-brick-road.com/TinMan/has_no_brain
would be matched (and blocked) by the following patterns
yellow-brick-road.com
and
Yellow*.COM
and
/TinM
but not
follow.the.yellow-brick-road.com
or
/tinman
Comments in a blockfile start with a # (hash) character
and end at a new line. Blank lines are also ignored.
Lines beginning with a ~ (tilde) character are taken to be
exceptions: a URL blocked by previous patterns that
matches the rest of the line is let through. (The last
match wins.)
Patterns may contain POSIX regular expressions provided
the junkbuster was compiled with this option (the default
in Version 2.0 on). The idiom /*.*/ad can then be used to
http://www.junkbusters.com/ht/en/ijb2.0man.html 2
JUNKBUSTER(1)JUNKBUSTER(1)
match any URL containing /ad (such as http://nomatter
where.com/images/advert/g3487.gif for example). These
expressions don't work in the domain part.
In version 1.3 and later the blockfile and cookiefile are
checked for changes before each request.
tinygif N
Set appearance of blocked GIFs. You can select one
of the following values:
0 = Show a ``broken icon'' in the browser
1 = Show a one pixel transparent GIF
2 = Show a GIF with the word ``JUNKBUSTER''
-w NAME=VALUE (Old) wafer NAME=VALUE (New)
Specifies a pair to be sent as a cookie with every
request to the server. (Such boring cookies are
called wafers.) This option may be called more
than once to generate multiple wafers. The origi
nal Netscape specification prohibited semi-colons,
commas and white space; these characters will be
URL-encoded if used in wafers. The Path and Domain
attributes are not currently supported.
-c cookiefile (Old) cookiefile cookiefile (New)
Enforce the cookie management policy specified in
the cookiefile. If this option is not used all
cookies are silently crunched, so that users who
never want cookies aren't bothered by browsers ask
ing whether each cookie should be accepted. How
ever, cookies can still get through via JavaScript
and SSL, so alerts should be left on.
In Version 1.2 and later this option must be followed by a
filename containing instructions on which sites are
allowed to receive and set cookies. By default cookies
are dropped in both the browser's request and the server's
response, unless the URL requested matches an entry in the
cookiefile. The matching algorithm is the same as for the
blockfile. A leading > character allows server-bound
cookies only; a < allows only browser-bound cookies; a ~
character stops cookies in both directions. Thus a cook_
iefile containing a single line with the two characters >*
will pass on all cookies to servers but not give any new
ones to the browser.
-j jarfile (Old) jarfile jarfile (New)
All Set-cookie attempts by the server are logged to
jarfile. If no wafer is specified, one containing
a canned notice (the vanilla wafer) is added as an
alert to the server unless the suppress-vanilla-
wafer option is invoked.
http://www.junkbusters.com/ht/en/ijb2.0man.html 3
JUNKBUSTER(1)JUNKBUSTER(1)-v (Old) suppress-vanilla-wafer (New)
Suppress the vanilla wafer.
-t from (Old) from from (New)
If the browser discloses an email address in the
FROM header (most don't), replace it with from. If
from is set to . (the period character) the FROM
is passed to the server unchanged. The default is
to delete the FROM header.
-r referer (Old) referer referer (New)
Whenever the browser discloses the URL that led to
the current request, replace it with referer. If
referer is set to . (period) the URL is passed to
the server unchanged. In Version 1.4 and later, if
referer is set to @ (at) the URL is sent in cases
where the cookiefile specifies that a cookie would
be sent. (No way to send bogus referers selec
tively is provided.) The default is to delete Ref
erer.
Version 2.0 also accepts the spelling referrer, which most
dictionaries consider correct.
-u user-agent (Old) user-agent user-agent (New)
Information disclosed by the browser about itself
is replaced with the value user-agent. If user-
agent is set to . (period) the User-Agent header
is passed to the server unchanged, along with any
UA headers produced by MS-IE (which would otherwise
be deleted). In Version 1.4 and later, if user-
agent is set to @ (at) these headers are sent
unchanged in cases where the cookiefile specifies
that a cookie would be sent, otherwise only default
User-Agent header is sent. That default is
Mozilla/3.0 (Netscape) with an unremarkable Macin
tosh configuration. If used with a browser less
advanced than Mozilla/3.0 or IE-3, the default may
encourage pages containing extensions that confuse
the browser.
-h [host][:port] (Old) listen-address [host][:port] (New)
If host is specified, bind the junkbuster to that
IP address. If a port is specified, use it. The
default port is 8000; the default host is local
host. Before Version 2.0.2, the default was to
bind to all IP addresses (INADDR_ANY); but this has
been restricted to localhost to avoid unintended
security breaches. (To open the proxy to all, use
the line
listen-address :8000
in the configuration file.)
http://www.junkbusters.com/ht/en/ijb2.0man.html 4
JUNKBUSTER(1)JUNKBUSTER(1)-f forward_host[:port] (Old) forwardfile forwardfile (New)
Version 1.X required all HTTP requests from the
client to be forwarded to the same destination.
Version 2.0 takes its routing specification from a
forwardfile, allowing selection of the proxy
(a.k.a. forwarding host) and gateway according to
the URL. Here is a typical line.
* lpwa.com:8000 . .
Each line contains four fields: target, forward_to,
via_gateway_type and gateway. As usual, the last target
domain that matches the requested URL wins, and the *
character alone matches any domain. The target domain
need not be a fully qualified hostname; it can be a gen
eral domain such as com or co.uk or even just a port num
ber. For example, because <a
href="http://lpwa.com">LPWA</a> does not handle SSL, the
line above will typically be followed by a line such as
:443 . . .
to allow SSL transactions to proceed directly. The cau
tious would also add an entry in their blockfile to stop
transactions to port 443 for all but specified trusted
sites.
If the winning forward_to field is . (the dot character)
the proxy connects directly to the server given in the
URL, otherwise it forwards to the host and port number
specified. The default port is 8000. The via_gate
way_type and gateway fields also use a dot to indicate no
gateway protocol. The gateway protocols are explained
below.
The example line above in a forwardfile alone would send
everything through port 8000 at lpwa.com with no gateway
protocol, and is equivalent to the old -f lpwa.com:8000
with no -g option. For more information see the example
file provided with the distribution.
Configure with care: no loop detection is performed. When
setting up chains of proxies that might loop back, try
adding Squid.
-g gw_protocol[:[gw_host][:gw_port]] (Old)
Use gw_protocol as the gateway protocol. This
option was introduced in Version 1.4, but was
folded into the forwardfile option in Version 2.0.
The default is to use no gateway protocol; this may
be explicitly specified as direct on the command
http://www.junkbusters.com/ht/en/ijb2.0man.html 5
JUNKBUSTER(1)JUNKBUSTER(1)
line or the dot character in the forwardfile. The
SOCKS4 protocol may be specified as socks or
socks4. The SOCKS4A protocol is specified as
socks4a. The SOCKS5 protocol is not currently sup
ported. The default SOCKS gw_port is 1080.
The user's browser should not be configured to use SOCKS;
the proxy conducts the negotiations, not the browser.
The user identification capabilities of SOCKS4 are delib_
erately not used; the user is always identified to the
SOCKS server as userid=anonymous. If the server's policy
is to reject requests from anonymous, the proxy will not
work. Use a debug value of 3 to see the status returned
by the server.
-d N (Old) debug N (New)
Set debug mode. The most common value is 1, to
pinpoint offensive URLs, so they can be added to
the blockfile. The value of N is a bitwise logi
cal-OR of the following values:
1 = URLs (show each URL requested by the browser);
2 = Connections (show each connection to or from the
proxy);
4 = I/O (log I/O errors);
8 = Headers (as each header is scanned, show the header
and what is done to it);
16 = Log everything (including debugging traces and the
contents of the pages). Multiple debug lines are
permitted; they are logical OR-ed together.
Because most browsers send several requests in parallel
the debugging output may appear intermingled, so the sin
gle-threaded option is recommended when using debug with N
greater than 1.
-y (Old) add-forwarded-header (New)
Add X-Forwarded-For headers to the server-bound
HTTP stream indicating the client IP address to the
server, in the new style of Squid 1.1.4. If you
want the traditional HTTP_FORWARDED response
header, add it manually with the -x option.
-x HeaderText (Old) add-header HeaderText (New)
Add the HeaderText verbatim to requests to the
server. Typical uses include adding old-style for
warding notices such as Forwarded: by http://pro-
privacy-isp.net and reinstating the Proxy-Connec
tion: Keep-Alive header (which the junkbuster
deletes so as not to reveal its existence). No
checking is done for correctness or plausibility,
so it can be used to throw any old trash into the
server-bound HTTP stream. Please don't litter.
http://www.junkbusters.com/ht/en/ijb2.0man.html 6
JUNKBUSTER(1)JUNKBUSTER(1)-s (Old) single-threaded (New)
Doesn't fork() a separate process (or create a sep
arate thread) to handle each connection. Useful
when debugging to keep the process single threaded.
-l logfile (Old) logfile logfile (New)
Write all debugging data into logfile. The default
logfile is the standard output.
aclfile aclfile (New)
Unless this option is used, the proxy talks to any
one who can connect to it, and everyone who can has
equal permissions on where they can go. An access
file allows restrictions to be placed on these two
policies, by distinguishing some source IP
addresses and/or some destination addresses. (If a
forwarder or a gateway is being used, its address
is considered the destination address, not the
ultimate IP address of the URL requested.)
Each line of the access file begins with either the word
permit or deny followed by source and (optionally) desti
nation addresses to be matched against those of the HTTP
request. The last matching line specifies the result: if
it was a deny line or if no line matched, the request will
be refused.
A source or destination can be specified as a single
numeric IP address, or with a hostname, provided that the
host's name can be resolved to a numeric address: this
cannot be used to block all .mil domains for example,
because there is no single address associated with that
domain name. Either form may be followed by a slash and
an integer N, specifying a subnet mask of N bits. For
example, permit 207.153.200.72/24 matches the entire
Class-C subnet from 207.153.200.0 through 207.153.200.255.
(A netmask of 255.255.255.0 corresponds to 24 bits of ones
in the netmask, as with *_MASKLEN=24.) A value of 16
would be used for a Class-B subnet. A value of zero for N
in the subnet mask length will cause any address to match;
this can be used to express a default rule. For more
information see the example file provided with the distri
bution.
If you like these access controls you should probably have
firewall; they are not intended to replace one.
trustfile trustfile (New)
This feature is experimental, has not been fully
documented and is very subject to change. The goal
is for parents to be able to choose a page or site
whose links they regard suitable for their young
children and for the proxy to allow access only to
sites mentioned there. To do this the proxy
http://www.junkbusters.com/ht/en/ijb2.0man.html 7
JUNKBUSTER(1)JUNKBUSTER(1)
examines the referer variable on each page request
to check they resulted from a click on the
``trusted referer'' site: if so the referred site
is added to a list of trusted sites, so that the
child can then move around that site. There are
several uncertainties in this scheme that experi
ence may be able to iron out; check back in the
months ahead.
trust_info_url trust_info_url (New)
When access is denied due to lack of a trusted ref
erer, this URL is displayed with a message pointing
the user to it for further information.
hide-console (New)
In the Windows version only, instructs the program
to disconnect from and hide the command console
after starting.
-a (Old)
(Obsolete) Accept the server's Set-cookie headers,
passing them through to the browser. This option
was removed in Version 1.2 and replaced by an
improvement to the -c option.
INSTALLATION AND USE
Browsers must be told where to find the junkbuster (e.g.
localhost port 8000). To set the HTTP proxy in Netscape
3.0, go through: Options; Network Preferences; Proxies;
Manual Proxy Configuration; View. See the FAQ for other
browsers. The Security Proxy should also be set to the
same values, otherwise shttp: URLs won't work.
Note the limitations explained in the FAQ.
CHECKING OPTIONS
To allow users to check that a junkbuster is running and
how it is configured, it intercepts requests for any URL
ending in /show-proxy-args and blocks it, returning
instead returns information on its version number and cur
rent configuration including the contents of its block
file. To get an explicit warning that no junkbuster
intervened if the proxy was not configured, it's best to
point it to a URL that does this, such as http://inter
net.junkbuster.com/cgi-bin/show-proxy-args on Junk
busters's website.
SEE ALSO
http://www.junkbusters.com/ht/en/ijbfaq.html
http://www.junkbusters.com/ht/en/cookies.html
http://internet.junkbuster.com/cgi-bin/show-proxy-args
http://www.cis.ohio-state.edu/htbin/rfc/rfc2109.html
http://squid.nlanr.net/Squid/
http://www-math.uni-paderborn.de/~axel/
http://www.junkbusters.com/ht/en/ijb2.0man.html 8
JUNKBUSTER(1)JUNKBUSTER(1)COPYRIGHT AND GPL
Written and copyright by the Anonymous Coders and Junk
busters Corporation and made available under the GNU Gen
eral Public License (GPL). This software comes with NO
WARRANTY. Internet Junkbuster Proxy is a trademark of
Junkbusters Corporation.
http://www.junkbusters.com/ht/en/ijb2.0man.html 9
