- Here's another practical example, for University of Kent at
- Canterbury students with a network connection in their room, who
- need to use the University's Squid web cache.
-</para>
-
-<para>
- <literal>
- <MSGText>
- <literallayout>
- <emphasis>forward *. ssbcache.ukc.ac.uk:3128</emphasis> # Use the proxy, except for:
- <emphasis>forward .ukc.ac.uk . </emphasis> # Anything on the same domain as us
- <emphasis>forward * . </emphasis> # Host with no domain specified
- <emphasis>forward 129.12.*.* . </emphasis> # A dotted IP on our /16 network.
- <emphasis>forward 127.*.*.* . </emphasis> # Loopback address
- <emphasis>forward localhost.localdomain . </emphasis> # Loopback address
- <emphasis>forward www.ukc.mirror.ac.uk . </emphasis> # Specific host
- </literallayout>
- </MSGText>
- </literal>
-</para>
-
-<para>
- If you intend to chain <application>Junkbuster</application> and
- <application>squid</application> locally, then chain as
- <literal>browser -> squid -> junkbuster</literal> is the recommended way.
-</para>
-
-<para>
- Your squid configuration could then look like this:
-</para>
-
-<para>
- <literal>
- <MSGText>
- <literallayout>
- # Define junkbuster as parent cache
- cache_peer 127.0.0.1 8000 parent 0 no-query
-
- # Define ACL for protocol FTP
- acl FTP proto FTP
-
- # Do not forward ACL FTP to junkbuster
- always_direct allow FTP
-
- # Do not forward ACL CONNECT (https) to junkbuster
- always_direct allow CONNECT
-
- # Forward the rest to junkbuster
- never_direct allow all
- </literallayout>
- </MSGText>
- </literal>
-</para>
-
-</sect3>
-
-<!-- ~ End section ~ -->
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-
-<sect3>
-<title>Windows GUI Options</title>
-<!--
-Removed references to Win32. HB 09/23/01
--->
-<para>
- <application>Junkbuster</application> has a number of options specific to the
- Windows GUI interface:
-</para>
-
-<para>
- If <quote>activity-animation</quote> is set to 1, the
- <application>Junkbuster</application> icon will animate when
- <quote>Junkbuster</quote> is active. To turn off, set to 0.
-</para>
-
-<para>
- <literal>
- <MSGText>
- <literallayout>
- <emphasis>activity-animation 1</emphasis>
- </literallayout>
- </MSGText>
- </literal>
-</para>
-
-<para>
- If <quote>log-messages</quote> is set to 1,
- <application>Junkbuster</application> will log messages to the console
- window:
-</para>
-
-<para>
- <literal>
- <MSGText>
- <literallayout>
- <emphasis>log-messages 1</emphasis>
- </literallayout>
- </MSGText>
- </literal>
-</para>
-
-<para>
- If <quote>log-buffer-size</quote> is set to 1, the size of the log buffer,
- i.e. the amount of memory used for the log messages displayed in the
- console window, will be limited to <quote>log-max-lines</quote> (see below).
-</para>
-
-<para>
- Warning: Setting this to 0 will result in the buffer to grow infinitely and
- eat up all your memory!
-</para>
-
-<para>
- <literal>
- <MSGText>
- <literallayout>
- <emphasis>log-buffer-size 1</emphasis>
- </literallayout>
- </MSGText>
- </literal>
-</para>
-
-<para>
- <application>log-max-lines</application> is the maximum number of lines held
- in the log buffer. See above.
-</para>
-
-<para>
- <literal>
- <MSGText>
- <literallayout>
- <emphasis>log-max-lines 200</emphasis>
- </literallayout>
- </MSGText>
- </literal>
-</para>
-
-<para>
- If <quote>log-highlight-messages</quote> is set to 1,
- <application>Junkbuster</application> will highlight portions of the log
- messages with a bold-faced font:
-</para>
-
-<para>
- <literal>
- <MSGText>
- <literallayout>
- <emphasis>log-highlight-messages 1</emphasis>
- </literallayout>
- </MSGText>
- </literal>
-</para>
-
-<para>
- The font used in the console window:
-</para>
-
-<para>
- <literal>
- <MSGText>
- <literallayout>
- <emphasis>log-font-name Comic Sans MS</emphasis>
- </literallayout>
- </MSGText>
- </literal>
-</para>
-
-<para>
- Font size used in the console window:
-</para>
-
-<para>
- <literal>
- <MSGText>
- <literallayout>
- <emphasis>log-font-size 8</emphasis>
- </literallayout>
- </MSGText>
- </literal>
-</para>
-
-<para>
- <quote>show-on-task-bar</quote> controls whether or not
- <application>Junkbuster</application> will appear as a button on the Task bar
- when minimized:
-</para>
-
-<para>
- <literal>
- <MSGText>
- <literallayout>
- <emphasis>show-on-task-bar 0</emphasis>
- </literallayout>
- </MSGText>
- </literal>
-</para>
-
-<para>
- If <quote>close-button-minimizes</quote> is set to 1, the Windows close
- button will minimize <application>Junkbuster</application> instead of closing
- the program (close with the exit option on the File menu).
-</para>
-
-<para>
- <literal>
- <MSGText>
- <literallayout>
- <emphasis>close-button-minimizes 1</emphasis>
- </literallayout>
- </MSGText>
- </literal>
-</para>
-
-<para>
- The <quote>hide-console</quote> option is specific to the MS-Win console
- version of <application>JunkBuster</application>. If this option is used,
- <application>Junkbuster</application> will disconnect from and hide the
- command console.
-</para>
-
-<para>
- <literal>
- <MSGText>
- <literallayout>
- #hide-console
- </literallayout>
- </MSGText>
- </literal>
-</para>
-
-</sect3>
-</sect2>
-
-<!-- ~ End section ~ -->
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="actionsfile">
-<title>The Actions File</title>
-
-<para>
- The <quote>actionsfile</quote> is used to define what actions
- <application>Junkbuster</application> 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 <filename>actionsfile</filename>.
-</para>
-
-<para>
- 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 <ulink
- url="http://i.j.b/show-url-info">http://i.j.b/show-url-info</ulink>.
-</para>
-
-<para>
- There are four types of lines in this file: comments (begin with a
- <quote>#</quote> character), actions, aliases and patterns, all of which are
- explained below.
-</para>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3>
-<title>URL Domain and Path Syntax</title>
-<para>
- Generally, a pattern has the form <domain>/<path>, where both the
- <domain> and <path> part are optional. If you only specify a
- domain part, the <quote>/</quote> can be left out:
-</para>
-
-<para>
- <emphasis>www.example.com</emphasis> - is a domain only pattern and will match any request to
- <quote>www.example.com</quote>.
-</para>
-
-<para>
- <emphasis>www.example.com/</emphasis> - means exactly the same.
-</para>
-
-<para>
- <emphasis>www.example.com/index.html</emphasis> - matches only the single
- document <quote>/index.html</quote> on <quote>www.example.com</quote>.
-</para>
-
-<para>
- <emphasis>/index.html</emphasis> - matches the document <quote>/index.html</quote>, regardless of
- the domain.
-</para>
-
-<para>
- <emphasis>index.html</emphasis> - matches nothing, since it would be
- interpreted as a domain name and there is no top-level domain called
- <quote>.html</quote>.
-</para>
-
-<para>
- The matching of the domain part offers some flexible options: if the
- domain starts or ends with a dot, it becomes unanchored at that end.
- For example:
-</para>
-
-<para>
- <emphasis>.example.com</emphasis> - matches any domain that <emphasis>ENDS</emphasis> in
- <quote>.example.com</quote>.
-</para>
-
-<para>
- <emphasis>www.</emphasis> - matches any domain that <emphasis>STARTS</emphasis> with
- <quote>www</quote>.
-</para>
-
-<para>
- Additionally, there are wildcards that you can use in the domain names
- themselves. They work pretty similar to shell wildcards: <quote>*</quote>
- stands for zero or more arbitrary characters, <quote>?</quote> stands for
- any single character. And you can define charachter classes in square
- brackets and they can be freely mixed:
-</para>
-
-<para>
- <emphasis>ad*.example.com</emphasis> - matches <quote>adserver.example.com</quote>,
- <quote>ads.example.com</quote>, etc but not <quote>sfads.example.com</quote>.
-</para>
-
-<para>
- <emphasis>*ad*.example.com</emphasis> - matches all of the above, and then some.
-</para>
-
-<para>
- <emphasis>.?pix.com</emphasis> - matches <quote>www.ipix.com</quote>,
- <quote>pictures.epix.com</quote>, <quote>a.b.c.d.e.upix.com</quote>, etc.
-</para>
-
-<para>
- <emphasis>www[1-9a-ez].example.com</emphasis> - matches <quote>www1.example.com</quote>,
- <quote>www4.example.com</quote>, <quote>wwwd.example.com</quote>,
- <quote>wwwz.example.com</quote>, etc., but <emphasis>not</emphasis>
- <quote>wwww.example.com</quote>.
-</para>
-
-<para>
- If <application>Junkbuster</application> was compiled with
- <quote>pcre</quote> support (default), Perl compatible regular expressions
- can be used. See the <filename>pcre/docs/</filename> direcory or <quote>man
- perlre</quote> (also available on <ulink
- url="http://www.perldoc.com/perl5.6/pod/perlre.html">http://www.perldoc.com/perl5.6/pod/perlre.html</ulink>)
- for details. A brief discussion of regular expressions is in the
- <link linkend="regex">Appendix</link>. For instance:
-</para>
-
-<para>
- <emphasis>/.*/advert[0-9]+\.jpe?g</emphasis> - would match a URL from any
- domain, with any path that includes <quote>advert</quote> followed
- immediately by one or more digits, then a <quote>.</quote> and ending in
- either <quote>jpeg</quote> or <quote>jpg</quote>. So we match
- <quote>example.com/ads/advert2.jpg</quote>, and
- <quote>www.example.com/ads/banners/advert39.jpeg</quote>, but not
- <quote>www.example.com/ads/banners/advert39.gif</quote> (no gifs in the
- example pattern).
-</para>
-
-<para>
- Please note that matching in the path is case
- <emphasis>INSENSITIVE</emphasis> by default, but you can switch to case
- sensitive at any point in the pattern by using the
- <quote>(?-i)</quote> switch:
-</para>
-
-<para>
- <emphasis>www.example.com/(?-i)PaTtErN.*</emphasis> - will match only
- documents whose path starts with <quote>PaTtErN</quote> in
- <emphasis>exactly</emphasis> this capitalization.
-</para>
-
-</sect3>
-
-<!-- ~ End section ~ -->
-
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-
-<sect3>
-<title>Actions</title>
-<para>
- Actions are enabled if preceded with a <quote>+</quote>, and disabled if
- preceded with a <quote>-</quote>. Actions are invoked by enclosing the
- action name in curly braces (e.g. {+some_action}), followed by a list of
- URLs to which the action applies. There are three classes of actions:
-</para>
-
-<para>
- <itemizedlist>
-
- <listitem>
- <para>
- Boolean (e.g. <quote>+/-block</quote>):
- </para>
- <para>
- <literal>
- <MSGText>
- <literallayout>
- <emphasis>{+name}</emphasis> # enable this action
- <emphasis>{-name}</emphasis> # disable this action
- </literallayout>
- </MSGText>
- </literal>
- </para>
- </listitem>
-
-
- <listitem>
- <para>
- Parameterized (e.g. <quote>+/-hide-user-agent</quote>):
- </para>
- <para>
- <literal>
- <MSGText>
- <literallayout>
- <emphasis>{+name{param}}</emphasis> # enable action and set parameter to <quote>param</quote>
- <emphasis>{-name}</emphasis> # disable action
- </literallayout>
- </MSGText>
- </literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- Multi-value (e.g. <quote>{+/-add-header{Name: value}}</quote>, <quote>{+/-wafer{name=value}}</quote>):
- </para>
- <para>
- <literal>
- <MSGText>
- <literallayout>
- <emphasis>{+name{param}}</emphasis> # enable action and add parameter <quote>param</quote>
- <emphasis>{-name{param}}</emphasis> # remove the parameter <quote>param</quote>
- <emphasis>{-name}</emphasis> # disable this action totally
- </literallayout>
- </MSGText>
- </literal>
- </para>
- </listitem>
-
- </itemizedlist>
-</para>
-
-<para>
- If nothing is specified in this file, no <quote>actions</quote> are taken.
- So in this case <application>JunkBuster</application> 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 <filename>actionsfile</filename> file will
- give a good starting point).
-</para>
-
-<para>
- Later defined actions always over-ride earlier ones. For multi-valued
- actions, the actions are applied in the order they are specified.
-</para>
-
-<para>
- The list of valid <application>Junkbuster</application> <quote>actions</quote> are: