1 .TH JUNKBUSTER 1 "http://www.junkbusters.com/ht/en/ijb2.0man.html"
\r
11 (Version 2.0 onwards)
\r
35 [-h [bind_host_address][:bind_port]]
\r
37 [-f forward_host[:port]]
\r
40 [-g gw_protocol[:[gw_host][:gw_port]]]
\r
42 (Version 1.4 and earlier)
\r
45 is an instrumentable proxy that filters the
\r
48 web servers and browsers.
\r
49 Its main purpose is to enhance privacy.
\r
51 Versions before 2.0 used command-line options;
\r
52 Versions from 2.0 onward use a configuration file.
\r
53 The following descriptions of the options first give the older
\r
54 command-line usage, then the new configfile line.
\r
56 In Versions 2.0.1 upwards on Windows,
\r
57 a start-up message is printed and the configuration is read from the file
\r
58 \fC\&junkbstr.ini\fP
\r
59 if it exists and no argument was given.
\r
61 All files except the configfile
\r
62 are checked for changes before each page is fetched,
\r
63 so they may edited without restarting the proxy.
\r
66 .\" anchor: o_b blockfile
\r
67 \fI-b blockfile\fP (Old) blockfile \fIblockfile\fP (New)
\r
68 Block\" ijbfaq.html#blocking
\r
71 matching any pattern given in the lines of the
\r
75 instead returns status 202, indicating that the request has been accepted
\r
76 (though not completed),
\r
78 message identifying itself\" ijbfaq.html#show
\r
79 (though the browser may
\r
80 display only a broken image icon).
\r
81 (Versions before 2.0 returned an error 403 (Forbidden).)
\r
82 The syntax of a pattern is
\r
83 \fB\&[domain][:port][/path]\fP
\r
88 protocol part is omitted).
\r
89 To decide if a pattern matches a target, the domains are compared first,
\r
92 To compare the domains,
\r
93 the pattern domain and the target
\r
94 domain specified in the
\r
96 are each broken into their components.
\r
97 (Components are separated by the
\r
99 (period) character.)
\r
100 Next each of the target components
\r
101 is compared with the corresponding pattern component: last with last,
\r
102 next-to-last with next-to-last, and so on.
\r
104 \fIright-anchored\fP
\r
106 If all of the pattern components find their match in the target,
\r
107 then the domains are considered a match.
\r
108 Case is irrelevant when comparing domain components.
\r
111 matching pattern can be an anchored substring of a target, but
\r
113 Thus if a pattern doesn't specify a domain,
\r
114 it matches all domains.
\r
115 .\" anchor: wildcard
\r
116 Furthermore, when comparing two components,
\r
117 the components must either match in their entirety or up to a wildcard
\r
119 (star character) in the pattern. The wildcard feature
\r
120 implements only a "prefix" match capability ("abc*" vs. "abcdefg"),
\r
121 not suffix matching ("*efg" vs. "abcdefg") or
\r
122 infix matching ("abc*efg" vs. "abcdefg").
\r
123 The feature is restricted to the domain component;
\r
124 it is unrelated to the optional
\r
126 feature in the path
\r
127 (described below).\" ijbman.html#regex
\r
130 is specified in the pattern domain, then the target port must
\r
131 match as well. The default port in a target is port 80.
\r
133 If the domain and port match,
\r
136 path is checked for
\r
137 a match against the path in the pattern.
\r
138 Paths are compared with a simple case-sensitive
\r
139 left-anchored substring comparison.
\r
140 Once again, the pattern can be an
\r
141 anchored substring of the target, but not vice versa.
\r
144 (slash) would match all paths. Wildcards are not considered in
\r
147 For example, the target
\r
151 \fB\&the.yellow-brick-road.com/TinMan/has_no_brain\fP
\r
153 would be matched (and blocked) by the following patterns
\r
156 \fB\&yellow-brick-road.com\fP
\r
161 \fB\&Yellow*.COM\fP
\r
171 \fB\&follow.the.yellow-brick-road.com\fP
\r
179 Comments in a blockfile start with a
\r
181 (hash) character and end at a new line.
\r
182 Blank lines are also ignored.
\r
184 Lines beginning with a
\r
186 (tilde) character are taken to be
\r
187 exceptions:\" ijbfaq.html#exceptions
\r
190 blocked by previous patterns that matches the rest of
\r
191 the line is let through. (The last match wins.)
\r
196 regular expressions\" ijbfaq.html#regex
\r
199 was compiled with this option
\r
200 (the default in Version 2.0 on).
\r
209 \fC\&http://nomatterwhere.com/images/advert/g3487.gif\fP
\r
212 don't work\" ijbman.html#substring
\r
213 in the domain part.
\r
215 In version 1.3 and later
\r
216 the blockfile and cookiefile are checked for changes before each request.
\r
219 Set appearance of blocked GIFs. You can select one of the following
\r
223 \h'-\w"0 = "u'0 = Show a ``broken icon'' in the browser
\r
225 \h'-\w"1 = "u'1 = Show a one pixel transparent GIF
\r
227 \h'-\w"2 = "u'2 = Show a GIF with the word ``JUNKBUSTER''
\r
229 popupfile \fI\&popup\fP
\r
230 Sets the name of the popupfile. If uncommented, the popupfile
\r
231 controls on which sites Javascript popup windows are disabled.
\r
233 .\" anchor: o_w wafer
\r
234 \fI-w NAME=VALUE\fP (Old) wafer \fINAME=VALUE\fP (New)
\r
235 Specifies a pair to be sent as a cookie with every request
\r
236 to the server.\" ijbfaq.html#wafers
\r
237 (Such boring cookies are called
\r
239 This option may be called more than once to generate multiple wafers.
\r
241 Netscape specification
\r
243 semi-colons, commas and white space;
\r
244 these characters will be
\r
247 The Path and Domain attributes are not currently supported.
\r
249 .\" anchor: o_c cookiefile
\r
250 \fI-c cookiefile\fP (Old) cookiefile \fIcookiefile\fP (New)
\r
251 Enforce the cookie management policy specified in the
\r
252 \fI\&cookiefile.\fP
\r
254 If this option is not used all cookies are silently crunched,
\r
255 so that users who never want cookies aren't bothered by browsers
\r
256 asking whether each cookie should be accepted.
\r
257 However, cookies can
\r
258 still get through\" ijbfaq.html#breakthrough
\r
260 JavaScript\" links.html#javascript
\r
263 so alerts should be left on.
\r
265 In Version 1.2 and later
\r
266 this option must be followed by a
\r
267 filename\" ijbfaq.html#crumble
\r
268 containing instructions on which sites are allowed to
\r
269 receive and set cookies.
\r
271 By default cookies are dropped in both the browser's request
\r
272 and the server's response, unless the
\r
274 requested matches an entry in the
\r
275 \fI\&cookiefile\fP.
\r
276 The matching algorithm is the same as for the blockfile.
\r
280 server-bound\" ijbfaq.html#directional
\r
284 allows only browser-bound cookies;
\r
287 character stops cookies in
\r
288 both directions.\" ijbfaq.html#crumble
\r
289 Thus a cookiefile containing a single line with the two characters
\r
291 will pass on all cookies to servers but not give any new ones to the browser.
\r
293 .\" anchor: o_j jarfile
\r
294 \fI-j jarfile\fP (Old) jarfile \fIjarfile\fP (New)
\r
295 All Set-cookie attempts by the server are
\r
296 logged\" ijbfaq.html#jar
\r
299 If no wafer is specified,
\r
301 canned notice\" ijbfaq.html#notice
\r
303 \fI\&vanilla wafer\fP)
\r
304 is added as an alert to the server
\r
306 suppress-vanilla-wafer\" ijbman.html#suppress-vanilla-wafer
\r
309 .\" anchor: o_v suppress-vanilla-wafer
\r
310 \fI-v\fP (Old) suppress-vanilla-wafer \fI\fP (New)
\r
311 Suppress the vanilla wafer.
\r
313 .\" anchor: o_t from
\r
314 \fI-t from\fP (Old) from \fIfrom\fP (New)
\r
316 discloses an email address\" ijbfaq.html#from
\r
319 header (most don't),
\r
326 (the period character)
\r
329 is passed to the server unchanged.
\r
330 The default is to delete the
\r
334 .\" anchor: o_r referer
\r
335 \fI-r referer\fP (Old) referer \fIreferer\fP (New)
\r
336 Whenever the browser discloses the
\r
339 led to\" ijbfaq.html#referer
\r
340 the current request,
\r
350 is passed to the server unchanged.
\r
353 and later, if referer is set to
\r
357 is sent in cases where the cookiefile
\r
358 specifies that a cookie would be sent.
\r
359 (No way to send bogus referers selectively is provided.)
\r
360 The default is to delete Referer.
\r
362 Version 2.0 also accepts the spelling
\r
364 which most dictionaries consider correct.
\r
366 .\" anchor: o_u user-agent
\r
367 \fI-u user-agent\fP (Old) user-agent \fIuser-agent\fP (New)
\r
368 Information disclosed by the browser
\r
369 about itself\" ijbfaq.html#agent
\r
370 is replaced with the value
\r
371 \fI\&user-agent.\fP
\r
379 header is passed to the server unchanged,
\r
382 headers produced by
\r
384 (which would otherwise be deleted).
\r
391 (at) these headers are sent unchanged in cases where the cookiefile
\r
392 specifies that a cookie would be sent,
\r
393 otherwise only default
\r
397 is Mozilla/3.0 (Netscape)
\r
398 with an unremarkable
\r
399 Macintosh\" ijbfaq.html#infer
\r
401 If used with a browser less advanced than Mozilla/3.0 or IE-3, the default
\r
402 may encourage pages containing extensions that confuse the browser.
\r
404 .\" anchor: o_h listen-address
\r
405 \fI-h [host][:port]\fP (Old) listen-address \fI[host][:port]\fP (New)
\r
416 is specified, use it.
\r
420 the default host is
\r
422 Before Version 2.0.2,
\r
423 the default was to bind to all
\r
426 (\fB\&INADDR_ANY\fP);
\r
427 but this has been restricted to
\r
429 to avoid unintended security breaches.
\r
430 (To open the proxy to all, use the line
\r
433 \fB\&listen-address :8000\fP
\r
435 in the configuration file.)
\r
437 .\" anchor: o_f forwardfile
\r
438 \fI-f forward_host[:port]\fP (Old) forwardfile \fIforwardfile\fP (New)
\r
439 Version 1.X required all
\r
441 requests from the client to be forwarded to the same destination.
\r
442 Version 2.0 takes its routing specification from a
\r
443 \fI\&forwardfile\fP,
\r
444 allowing selection of the proxy (a.k.a. forwarding host) and gateway
\r
447 Here is a typical line.
\r
453 * lpwa.com:8000 . .
\r
460 Each line contains four fields:
\r
462 \fB\&forward_to\fP,
\r
463 \fB\&via_gateway_type\fP
\r
467 last\" ijbman.html#compare
\r
469 domain that matches the requested
\r
474 character alone matches any domain.
\r
475 The target domain need not be a fully qualified
\r
476 hostname; it can be a general domain such as
\r
480 or even just a port number.
\r
482 For example, because
\r
483 <a href="http://lpwa.com">LPWA</a>
\r
485 SSL,\" ijbfaq.html#encrypt
\r
486 the line above will typically be followed by a line such as
\r
498 to allow SSL transactions to proceed directly.
\r
499 The cautious would also
\r
500 add an entry in their blockfile to stop transactions
\r
501 to port 443 for all but specified trusted sites.
\r
507 (the dot character) the proxy connects
\r
508 directly to the server given in the
\r
510 otherwise it forwards to the host and port number specified.
\r
511 The default port is 8000.
\r
513 \fC\&via_gateway_type\fP
\r
516 fields also use a dot to indicate no gateway protocol.
\r
517 The gateway protocols are explained
\r
518 below.\" ijbman.html#o_g
\r
520 The example line above in a forwardfile alone
\r
521 would send everything through port 8000 at
\r
523 with no gateway protocol,
\r
524 and is equivalent to the old
\r
525 \fC\&-f lpwa.com:8000\fP
\r
529 For more information see the example file provided with the distribution.
\r
531 Configure with care: no loop detection is performed.
\r
532 When setting up chains of proxies that might loop back, try adding
\r
533 Squid.\" ijbman.html#squid
\r
536 \fI-g gw_protocol[:[gw_host][:gw_port]]\fP (Old)
\r
538 \fI\&gw_protocol\fP
\r
539 as the gateway protocol.
\r
540 This option was introduced in Version 1.4,
\r
541 but was folded into the
\r
542 forwardfile\" ijbman.html#forwardfile
\r
543 option in Version 2.0.
\r
544 The default is to use no gateway protocol;
\r
545 this may be explicitly specified as
\r
547 on the command line
\r
548 or the dot character in the forwardfile.
\r
551 protocol may be specified as
\r
557 protocol is specified as
\r
561 protocol is not currently supported.
\r
567 The user's browser should
\r
570 configured\" ijbfaq.html#socks
\r
573 the proxy conducts the negotiations, not the browser.
\r
575 The user identification capabilities of
\r
577 are deliberately not used;
\r
578 the user is always identified to the
\r
581 \fC\&userid=anonymous\fP.
\r
582 If the server's policy is to reject requests from
\r
584 the proxy will not work.
\r
586 debug\" ijbman.html#o_d
\r
588 to see the status returned by the server.
\r
590 .\" anchor: o_d debug
\r
591 \fI-d N\fP (Old) debug \fIN\fP (New)
\r
593 The most common value is 1,
\r
595 pinpoint\" ijbfaq.html#pinpoint
\r
598 so they can be added to the blockfile.
\r
603 of the following values:
\r
606 \h'-\w"1 = "u'1 = URLs (show each URL requested by the browser);
\r
608 \h'-\w"2 = "u'2 = Connections (show each connection to or from the proxy);
\r
610 \h'-\w"4 = "u'4 = I/O (log I/O errors);
\r
612 \h'-\w"8 = "u'8 = Headers (as each header is scanned, show the header and what is done to it);
\r
614 \h'-\w"16 = "u'16 = Log everything (including debugging traces and the contents of the pages).
\r
618 lines are permitted; they are logical OR-ed together.
\r
620 Because most browsers send several requests in parallel
\r
621 the debugging output may appear intermingled, so the
\r
622 single-threaded\" ijbman.html#single-threaded
\r
623 option is recommended when using
\r
624 debug\" ijbman.html#debug
\r
629 .\" anchor: o_y add-forwarded-header
\r
630 \fI-y\fP (Old) add-forwarded-header \fI\fP (New)
\r
632 \fB\&X-Forwarded-For\fP
\r
633 headers to the server-bound
\r
636 indicating the client
\r
639 to the server,\" ijbfaq.html#detect
\r
640 in the new style of
\r
641 Squid 1.1.4.\" ijbman.html#squid
\r
642 If you want the traditional
\r
643 \fC\&HTTP_FORWARDED\fP
\r
644 response header, add it manually with the
\r
645 -x\" ijbman.html#o_x
\r
648 .\" anchor: o_x add-header
\r
649 \fI-x HeaderText\fP (Old) add-header \fIHeaderText\fP (New)
\r
652 verbatim to requests to the server.
\r
653 Typical uses include
\r
654 adding old-style forwarding notices such as
\r
655 \fB\&Forwarded: by http://pro-privacy-isp.net\fP
\r
656 and reinstating the
\r
657 \fB\&Proxy-Connection: Keep-Alive\fP
\r
662 not\" ijbfaq.html#detect
\r
663 to reveal its existence).
\r
664 No checking is done for correctness or plausibility,
\r
665 so it can be used to throw any old trash into the server-bound
\r
668 Please don't litter.
\r
670 .\" anchor: o_s single-threaded
\r
671 \fI-s\fP (Old) single-threaded \fI\fP (New)
\r
675 (or create a separate thread)
\r
676 to handle each connection.
\r
677 Useful when debugging to keep the process single threaded.
\r
679 .\" anchor: o_l logfile
\r
680 \fI-l logfile\fP (Old) logfile \fIlogfile\fP (New)
\r
681 Write all debugging data into
\r
685 is the standard output.
\r
687 .\" anchor: o_acl aclfile
\r
688 aclfile \fIaclfile\fP (New)
\r
689 Unless this option is used, the proxy talks to anyone who can connect to it,
\r
690 and everyone who can has equal permissions on where they can go.
\r
691 An access file allows restrictions to be placed on these two policies,
\r
692 by distinguishing some
\r
700 forwarder or a gateway\" ijbman.html#forwardfile
\r
701 is being used, its address is considered the destination address,
\r
708 Each line of the access file begins with
\r
713 followed by source and (optionally) destination addresses
\r
714 to be matched against those of the
\r
717 The last matching line specifies the result: if it was a
\r
719 line or if no line matched,
\r
720 the request will be refused.
\r
722 A source or destination
\r
723 can be specified as a single numeric
\r
726 or with a hostname, provided that the host's name
\r
727 can be resolved to a numeric address: this cannot be used to block all
\r
729 domains for example,
\r
730 because there is no single address associated with that domain name.
\r
731 Either form may be followed by a slash and an integer
\r
733 specifying a subnet mask of
\r
737 \fB\&permit 207.153.200.72/24\fP
\r
738 matches the entire Class-C subnet from
\r
740 through 207.153.200.255.
\r
741 (A netmask of 255.255.255.0 corresponds to 24 bits of
\r
742 ones in the netmask, as with
\r
743 \fC\&*_MASKLEN=24\fP.)
\r
744 A value of 16 would be used for a Class-B subnet.
\r
745 A value of zero for
\r
747 in the subnet mask length will cause any address to match;
\r
748 this can be used to express a default rule.
\r
749 For more information see the example file provided with the distribution.
\r
751 If you like these access controls
\r
752 you should probably have
\r
753 firewall;\" ijbfaq.html#firewall
\r
754 they are not intended to replace one.
\r
756 .\" anchor: o_tf trustfile
\r
757 trustfile \fItrustfile\fP (New)
\r
758 This feature is experimental, has not been fully documented and is
\r
759 very subject to change.
\r
760 The goal is for parents to be able to choose a page or site whose
\r
761 links they regard suitable for their
\r
762 young children\" ijbfaq.html#children
\r
763 and for the proxy to allow access only to sites mentioned there.
\r
764 To do this the proxy examines the
\r
765 referer\" ijbman.html#o_r
\r
766 variable on each page request to check they resulted from
\r
767 a click on the ``trusted referer'' site: if so the referred site
\r
768 is added to a list of trusted sites, so that the child can
\r
769 then move around that site.
\r
770 There are several uncertainties in this scheme that experience may be
\r
771 able to iron out; check back in the months ahead.
\r
773 .\" anchor: o_ti trust_info_url
\r
774 trust_info_url \fItrust_info_url\fP (New)
\r
775 When access is denied due to lack of a trusted referer, this
\r
777 is displayed with a message pointing the user to it for further information.
\r
779 .\" anchor: o_hc hide-console
\r
780 hide-console \fI\fP (New)
\r
781 In the Windows version only, instructs the program
\r
782 to disconnect from and hide the command console after starting.
\r
786 (Obsolete) Accept the server's
\r
788 headers, passing them through to the browser.
\r
789 .\" anchor: obsolete
\r
790 This option was removed in Version 1.2
\r
791 and replaced by an improvement to the
\r
792 -c\" ijbman.html#o_c
\r
795 .SH INSTALLATION AND USE
\r
796 Browsers must be told where to find the
\r
803 proxy in Netscape 3.0,
\r
806 \fB\&Network Preferences\fP;
\r
808 \fB\&Manual Proxy Configuration\fP;
\r
812 for other browsers.
\r
814 Security Proxy\" ijbfaq.html#security
\r
815 should also be set to the same values,
\r
821 Note the limitations
\r
824 .SH CHECKING OPTIONS
\r
826 check\" ijbfaq.html#show
\r
829 is running and how it is configured,
\r
830 it intercepts requests for any
\r
833 \fB\&/show-proxy-args\fP
\r
835 returning instead returns information on its
\r
837 current configuration
\r
838 including the contents of its blockfile.
\r
839 To get an explicit warning that no
\r
841 intervened if the proxy was not configured,
\r
842 it's best to point it to a
\r
844 that does this, such as
\r
845 http://internet.junkbuster.com/cgi-bin/show-proxy-args
\r
846 on Junkbusters's website.
\r
848 http://www.waldherr.org/junkbuster/\" waldherr.org#
\r
850 http://www.junkbusters.com/ht/en/ijbfaq.html\" ijbfaq.html#
\r
852 http://www.junkbusters.com/ht/en/cookies.html\" cookies.html#
\r
854 http://internet.junkbuster.com/cgi-bin/show-proxy-args
\r
856 http://www.cis.ohio-state.edu/htbin/rfc/rfc2109.html
\r
858 http://squid.nlanr.net/Squid/
\r
860 http://www-math.uni-paderborn.de/~axel/
\r
861 .SH COPYRIGHT AND GPL
\r
862 Written and copyright by the Anonymous Coders and Junkbusters Corporation
\r
863 and made available under the
\r
864 GNU General Public License (GPL).\" gpl.html#
\r
865 This software comes with
\r
866 NO WARRANTY.\" gpl.html#nowarr
\r
867 Internet Junkbuster
\r
870 trademark\" legal.html#marks
\r
871 of Junkbusters Corporation.
\r
projects / privoxy.git / blob