This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: user-manual.sgml,v 1.15 2001/10/14 23:46:24 hal9 Exp $
+ $Id: user-manual.sgml,v 1.21 2001/10/31 21:11:03 hal9 Exp $
Written by and Copyright (C) 2001 the SourceForge
IJBSWA team. http://ijbswa.sourceforge.net
<artheader>
<title>Junkbuster User Manual</title>
-<pubdate>$Id: user-manual.sgml,v 1.15 2001/10/14 23:46:24 hal9 Exp $</pubdate>
+<pubdate>$Id: user-manual.sgml,v 1.21 2001/10/31 21:11:03 hal9 Exp $</pubdate>
<authorgroup>
<author>
<listitem>
<para>
- Modularized configuration that will allow for system wide settings, and
- individual user settings.
+ A browser based configuration utility (WIP at
+ <ulink url="http://i.j.b">http://i.j.b</ulink>).
</para>
</listitem>
<listitem>
<para>
- A browser based GUI configuration utility (not finished).
+ Modularized configuration that will allow for system wide settings, and
+ individual user settings. (not implemented yet)
</para>
</listitem>
<listitem>
<para>
- Partial support for HTTP/1.1.
+ Support for HTTP/1.1 (partially implemented at this point).
</para>
</listitem>
</itemizedlist>
</para>
+<para>
+ In addition, the configuration is more versatile overall.
+</para>
+
</sect2>
</sect1>
<para>
<screen>
- 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
</screen>
</para>
</para>
<para>
- Then, in either case, to build from source:
+ Then, in either case, to build from tarball/CVS source:
</para>
<para>
<screen>
- ./configure
- make
- su
- make install
+ ./configure (--help to see options)
+ make (the make from gnu, gmake for *BSD)
+ su
+ make -n install (to see where all the files will go)
+ make install (to really install)
</screen>
</para>
<para>
<screen>
+ autoheader [suggested for CVS source]
+ autoconf [suggested for CVS source]
./configure
make redhat-dist
</screen>
<para>
<screen>
+ autoheader [suggested for CVS source]
+ autoconf [suggested for CVS source]
./configure
make suse-dist
</screen>
</para>
<para>
- /usr/src/suse/RPMS/i686/junkbuster-2.9.9-1.i686.rpm
+ /usr/src/packages/RPMS/i686/junkbuster-2.9.9-1.i686.rpm
</para>
<para>
- /usr/src/suse/SRPMS/junkbuster-2.9.9-1.src.rpm
+ /usr/src/packages/SRPMS/junkbuster-2.9.9-1.src.rpm
</para>
<para>
<para>
<screen>
- 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
</screen>
</para>
<listitem>
<para>
The <filename>actionsfile</filename> file is used to define various
- actions relating to images, banners, pop-ups, banners and cookies.
+ <quote>actions</quote> 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 <ulink
+ url="http://i.j.b./">http://i.j.b./</ulink>. This is the easiest method of
+ configuring actions. (Still under active development.)
</para>
</listitem>
for the changes to take effect.
</para>
+<para>
+ 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 <quote>default</quote> setting, may change, so
+ please check all your configuration files on important issues.
+</para>
<!-- ~~~~~ New section ~~~~~ -->
</para>
<para>
- The <quote><literal>#</literal></quote> indicates a comment. Any part of a
+ A <quote><literal>#</literal></quote> indicates a comment. Any part of a
line following a <quote><literal>#</literal></quote> is ignored, except if
the <quote><literal>#</literal></quote> is preceded by a
<quote><literal>\</literal></quote>.
<para>
There are various aspects of <application>Junkbuster</application> behavior
- that can be adjusted.
+ that can be tuned.
</para>
serve requests from other machines (e.g. on your local network) as well, you
will need to override the default. The syntax is
<quote>listen-address [<ip-address>]:<port></quote>. If you leave
- out the IP adress, <application>junkbuster</application> will bind to all
+ out the IP ad
dress, <application>junkbuster</application> 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
- <quote>aclfile</quote> above).
+ Internet. In that case, consider using access control lists (acl's) (see
+ <quote>aclfile</quote> above), or a firewall.
</para>
<para>
<para>
The Windows version of <application>Junkbuster</application> 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
- <quote>Options</quote> menu), one choice is <quote>Enable</quote>. Clicking
- on enable toggles <application>Junkbuster</application> on and off. This is
- useful if you want to temporarily disable
- <application>Junkbuster</application>, e.g., to access a site that requires
- cookies which you normally have blocked.
+ the system tray, which also allows you to change this option. If you
+ right-click on that icon (or select the <quote>Options</quote> menu), one
+ choice is <quote>Enable</quote>. Clicking on enable toggles
+ <application>Junkbuster</application> on and off. This is useful if you want
+ to temporarily disable <application>Junkbuster</application>, 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 <application>Junkbuster</application>
+ internal address of <ulink url="http://i.j.b./">http://i.j.b./</ulink> on
+ any platform.
</para>
<para>
<quote>toggle 1</quote> means <application>Junkbuster</application> runs
normally, <quote>toggle 0</quote> means that
<application>Junkbuster</application> becomes a non-anonymizing non-blocking
- proxy. Default: 1.
+ proxy. Default: 1 (on).
</para>
<para>
</literal>
</para>
+<para>
+ For content filtering, i.e. the <quote>+filter</quote> and
+ <quote>+deanimate-gif</quote> actions, it is neccessary that
+ <application>Junkbuster</application> 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.
+</para>
+
+<para>
+ The <application>buffer-limit</application> 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 <quote>buffer-limit</quote>
+ Kbytes <emphasis>each</emphasis>, unless you have enabled
+ <quote>single-threaded</quote> above.
+</para>
+
+<para>
+ <literal>
+ <MSGText>
+ <literallayout>
+ <emphasis>buffer-limit 4069</emphasis>
+ </literallayout>
+ </MSGText>
+ </literal>
+</para>
+
+<para>
+ To enable the web-based actionsfile editor set
+ <application>enable-edit-actions</application> to 1, or 0 to disable. Note
+ that you must have compiled <application>JunkBuster</application> with
+ support for this feature, otherwise this option has no effect. This
+ internal page can be reached at <ulink
+ url="http://i.j.b./">http://i.j.b./</ulink>.
+ </para>
+
+<para>
+ 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.
+</para>
+
+<para>
+ <literal>
+ <MSGText>
+ <literallayout>
+ <emphasis>enable-edit-actions 1</emphasis>
+ </literallayout>
+ </MSGText>
+ </literal>
+</para>
+
+<para>
+ Allow <application>JunkBuster</application> to be toggled on and off
+ remotely, using your web browser. Set <quote>enable-remote-toggle</quote>to
+ 1 to enable, and 0 to disable. Note that you must have compiled
+ <application>JunkBuster</application> with support for this feature,
+ otherwise this option has no effect.
+</para>
+
+<para>
+ Security note: If this is enabled, anyone who can use the proxy can toggle
+ it on or off (see <ulink url="http://i.j.b./">http://i.j.b./</ulink>), and
+ their changes will affect all users. For shared proxies, you probably want to
+ disable this. Default: enabled.
+</para>
+
+<para>
+ <literal>
+ <MSGText>
+ <literallayout>
+ <emphasis>enable-remote-toggle 1</emphasis>
+ </literallayout>
+ </MSGText>
+ </literal>
+</para>
+
</sect3>
<!-- ~ End section ~ -->
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.
+ to a special purpose filtering proxy such as lpwa.com. Or to use
+ a caching proxy to speed up browsing.
</para>
<para>
<literal>
<MSGText>
<literallayout>
- <emphasis>forward_socks4 .* lpwa.com:8000 firewall.my_company.com:1080</emphasis>
+ <emphasis>forward-socks4 .* lpwa.com:8000 firewall.my_company.com:1080</emphasis>
<emphasis>forward my_company.com .</emphasis>
</literallayout>
</MSGText>
<literal>
<MSGText>
<literallayout>
- <emphasis>forward_socks4a .* . firewall.my_company.com:1080</emphasis>
+ <emphasis>forward-socks4a .* . firewall.my_company.com:1080</emphasis>
</literallayout>
</MSGText>
</literal>
url="http://i.j.b/show-url-info">http://i.j.b/show-url-info</ulink>.
</para>
+<para>
+ The actions file can be edited with a browser by loading
+ <ulink url="http://i.j.b">http://i.j.b</ulink>, and then select
+ <quote>Edit Actions</quote>.
+</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.
+ explained below, as well as the configuration file syntax that
+ <application>Junkbuster</application> understands.
+
</para>
<quote>-</quote>. Alias names are not case sensitive, and
<emphasis>must be defined before anything</emphasis> else in
<filename>actionsfile</filename>! And there can only be one set of
- <quote>aliases</quote> of defined.
+ <quote>aliases</quote> defined.
</para>
<para>
<para>
<screen>
- # /usr/sbin/junkbuster /etc/junkbuster/config &
+ # /usr/sbin/junkbuster /etc/junkbuster/config
</screen>
</para>
+<para>
+ An init script is provided for SuSE and Redhat.
+</para>
+
+<para>
+For for SuSE: /etc/rc.d/junkbuster start
+</para>
+
+<para>
+For RedHat: /etc/rc.d/init.d/junkbuster start
+</para>
+
+
<para>
If no configuration file is specified on the command line,
<application>Junkbuster</application> will look for a file named
</para>
<para>
- Be sure your browser is set to use
- the proxy which is by default at localhost, port 8000. With
- <application>Netscape</application> (and <application>Mozilla</application>),
- this can be set under <literal>Edit -> Preferences -> Advanced ->
- Proxies -> HTTP Proxy</literal>. For <application>Internet
- Explorer</application>: <literal>Tools > Internet Properties ->
- Connections -> LAN Setting</literal>. Then, check <quote>Use Proxy</quote>
- and fill in the appropriate info (Address: localhost, Port: 8000).
- Include if HTTPS proxy support too.
+ Be sure your browser is set to use the proxy which is by default at
+ localhost, port 8000. With <application>Netscape</application> (and
+ <application>Mozilla</application>), this can be set under <literal>Edit
+ -> Preferences -> Advanced -> Proxies -> HTTP Proxy</literal>.
+ For <application>Internet Explorer</application>: <literal>Tools >
+ Internet Properties -> Connections -> LAN Setting</literal>. Then,
+ check <quote>Use Proxy</quote> and fill in the appropriate info (Address:
+ localhost, Port: 8000). Include if HTTPS proxy support too.
</para>
<para>
After running <application>Junkbuster</application> 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.
+ be customized. <quote>Actions</quote> (from <filename>actionsfile</filename>)
+ can be adjusted by pointing your browser to
+ <ulink url="http://i.j.b./">http://i.j.b./</ulink>,
+ and then follow the link to <quote>edit the actions list</quote>.
+ (This is an internal page and does not require Internet access.)
+</para>
+
+<para>
+ In fact, various aspects of <application>Junkbuster</application>
+ configuration can be viewed from this page, including
+ current configuration parameters, source code version numbers,
+ the browser's request headers, and <quote>actions</quote> that apply
+ to a given URL. In addition to the <filename>actionsfile</filename>
+ editor mentioned above, <application>Junkbuster</application> can also
+ be turned <quote>on</quote> and <quote>off</quote> from this page.
</para>
<para>
</simplelist>
<simplelist>
<member>
- <ulink url="http://ijbswa.sourceforge.net/config/">http://ijbswa.sourceforge.net/config/</ulink>
+ <ulink url="http://i.j.b./">http://i.j.b./</ulink>
</member>
</simplelist>
<simplelist>
Temple Place - Suite 330, Boston, MA 02111-1307, USA.
$Log: user-manual.sgml,v $
+ Revision 1.21 2001/10/31 21:11:03 hal9
+ Correct 2 minor errors
+
+ Revision 1.18 2001/10/24 18:45:26 hal9
+ *** empty log message ***
+
+ Revision 1.17 2001/10/24 17:10:55 hal9
+ Catching up with Jon's recent work, and a few other things.
+
+ Revision 1.16 2001/10/21 17:19:21 swa
+ wrong url in documentation
+
Revision 1.15 2001/10/14 23:46:24 hal9
Various minor changes. Fleshed out SEE ALSO section.
projects / privoxy.git / blobdiff