- Fixed errors in general and forward explanations

[privoxy.git] / config

#  Sample Configuration file for the Internet Junkbuster 2.9.x

#
# $Id: config,v 1.14 2001/06/08 00:25:01 jongfoster Exp $
#

#  Table of Contents
#
#       1. INTRODUCTION
#       2. FORMAT OF THE CONFIGURATION FILE
#       3. OTHER CONFIGURATION FILES
#       4. GENERAL OPTIONS
#       5. WINDOWS GUI OPTIONS
#
#  1. INTRODUCTION
#
#  This file holds the Junkbuster configuration.  If you modify this
#  file, you will need to stop & restart Junkbuster, or use the
#  "Reload Config" option (Windows) before any changes take effect.
#
#  When starting Junkbuster on Unix systems, give the name of this
#  file as an argument.  On Windows systems, Junkbuster will look for
#  this file with the name 'junkbustr.txt' in the same directory where
#  Junkbuster is installed.
#
#  2. FORMAT OF THE CONFIGURATION FILE
#
#  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
#
#  Indicates that the blockfile is named 'blocklist.ini'.
#
#  The '#' indicates a comment.  Any part of a line following a '#' is
#  ignored, except if the '#' is preceded by a '\'.
#
#  Thus, by placing a # at the start of an existing configuration line,
#  you can make it a comment and it will be treated as if it weren't there. 
#  This is called "commenting out" an option and can be useful to turn
#  off features: If you comment out the "logfile" line, junkbuster will
#  not log to a file at all. Watch for the "default:" section in each 
#  explanation to see what happens if the option is left unset (or 
#  commented out). 
#
#  Long lines can be continued on the next line by using a `\' as
#  the last character.
#  

#
#  3. OTHER CONFIGURATION FILES
#
#  Junkbuster uses a number of other files to tell it what ads to
#  block, what cookies to accept, etc.  This section of the
#  configuration file tells Junkbuster where to find all those other
#  files.
#
#  On Windows, Junkbuster looks for these files in the same
#  directory as the executable.  On Unix, Junkbuster looks for these
#  files in the current working directory.  In either case, an
#  absolute path name can be used to avoid problems.

#  While we go modular and multiuser, the blocker, filter, and 
#  per-user config will be stored in subdirectories of confdir.
#  Now, only confdir/templates is used for storing HTML templates
#  for CGI results.
#
#  No trailing /, please.
confdir .

#
#  The directory where all logging (i.e. logfile and jarfile) takes place
#  No trailing /, please.
#
logdir .

#
#  Note that all file specifications below are relative to 
#  the above two directories!!!
#

#  The actions file 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.  Nothing is an image.
#
actionsfile actionsfile

#
#  The re_filterfile contains content modification rules.  These rules
#  permit powerful changes on the content of Web pages, e.g., you
#  could disable your favourite JavaScript annoyances, rewrite the
#  actual content, or just have some fun replacing "Microsoft"
#  with "Microsuck" wherever it appears on a Web page.
#
#  Default: No content modification.
#
re_filterfile   re_filterfile

#
#  The logfile is where all logging and error messages are written.
#  The logfile can be useful for tracking down a problem with
#  Junkbuster (e.g., it's not blocking an ad you think it should
#  block) but in most cases you probably will never look at it.
#
#  Your logfile will grow indefinitely, and you will probably want to
#  periodically remove it.  On Unix systems, you can do this with a
#  cron job (see 'man cron').
#
#  On SuSE Linux systems, you can place a line like
#  "/var/log/junkbuster.* +1024k 644 nobody.nogroup" in /etc/logfiles,
#  with the effect that cron.daily will automatically archive, gzip,
#  and empty the log, when it exceeds 1M size.
#
#  Default: Log to the standard error channel, not to a file
#
logfile      logfile

#
#  The jarfile defines where Junkbuster stores the cookies it
#  intercepts.  Note that if you use a jarfile, it may grow quite
#  large. 
#
#  Default: Don't store intercepted cookies
#
#jarfile     jarfile

#
#  If you specify a trustfile, Junkbuster will only allow access
#  to sites that are named in the trustfile. You can also mark
#  sites as trusted referrers, with the effect that access to
#  untrusted sites will be granted, if a link from a trusted
#  referrer was used. The link target will then be added to the
#  trustfile.
#  Note that this is a very restrictive feature that typical users
#  most propably want to leave disabled.
#
#  Default: Don't use the trust mechanism
#
#trustfile trust

#
#  If you use the trust mechanism, it is a good idea to write up
#  some online documentation about your blocking policy and to
#  specify the URL(s) here. They will appear on the page that
#  your users receive when they try to access untrusted content.
#  Use multiple times for multiple URLs.
#
#  Default: Don't display links on the "untrusted" info page.
#
trust-info-url http://www.your-site.com/why_we_block.html
trust-info-url http://www.your-site.com/what_we_allow.html


#
#  4. OPTIONS
#
#  This part of the configuration file contains options that control
#  how Junkbuster operates.
#

#
#  Admin-address should be set to the email address of the proxy
#  administrator. It is used in many of the proxy-generated pages.
#
#  Default: fill@me.in.please
#
#admin-address fill@me.in.please

#
#  Proxy-info-url can be set to a URL that contains more info about
#  this junkbuster installation, it's configuration and policies.
#  It is used in many of the proxy-generated pages and its use is
#  highly recommended, since your users will want to know why certain
#  content is blocked or modified.
#
#  Default: Don't show a link to online documentation
#
proxy-info-url http://www.your-site.com/proxy.html

#
#  Listen-address specifies the address and port where Junkbuster will
#  listen for connections from your Web browser.  The default is to
#  listen on the local host on port 8000, and this is suitable for
#  most users.  (In your web browser, under proxy configuration, list
#  the proxy server as 'localhost' and the port as '8000').
# 
#  If you already have another service running on port 8000, or if you
#  want to serve requests from other machines (e.g. on your local
#  network) as well, you will need to override the default. The syntax
#  is "listen-address [<ip-address>]:<port>" If you leave out the ip
#  adress, junkbuster 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 "aclfile" above).
#
#  For example, suppose you are running Junkbuster on a machine which
#  has the address 192.168.0.1 on your local private network
#  (192.168.0.0) and has another outside connection with a different
#  address. You want it to serve requests from inside only:
#
#     listen-address 192.168.0.1:8000
#
#  If you want it to listen on all addresses (including the outside
#  connection):
#
#     listen-address :8000
#
#  If you do this, consider using acls (see "aclfile" above).
#
#  Note: you will need to point your browser(s) to the address
#  and port that you have configured here.
#
#  Default:  listen-address    localhost:8000 
#            listen-address    127.0.0.1:8000
#


#
#  The debug option sets the level of debugging information to log in
#  the logfile (and to the console in the Windows version).  A debug
#  level of 1 is informative because it will show you each request as
#  it happens.  Higher levels of debug are probably only of interest
#  to developers.
#
#   debug         1 # GPC  = show each GET/POST/CONNECT request
#   debug         2 # CONN = show each connection status
#   debug         4 # IO   = show I/O status
#   debug         8 # HDR  = show header parsing
#   debug        16 # LOG  = log all data into the logfile
#   debug        32 # FRC  = debug force feature
#   debug        64 # REF  = debug regular expression filter 
#   debug       128 # RED  = debug fast redirects
#   debug       256 # CLF  = Common Log Format
#   debug      4096 # INFO = Startup banner and warnings.
#   debug      8192 # ERROR = Non-fatal errors
#
#  It is *highly recommended* that you enable ERROR
#  reporting.  (debug 8192).
#
#  The reporting of FATAL errors (i.e. ones which crash 
#  JunkBuster) is always on and cannot be disabled.
#
#  If you want to use CLF, you should set "debug 256" ONLY,
#  do not enable anything else.
#
#  Multiple "debug" directives, are OK - they're logical-OR'd
#  together. 
#
#   debug         15 # same as setting the first 4 listed above
#
#  Default: 0, i.e. log nothing but fatal errors
#
debug   1    # URLs
debug   4096 # Info
debug   8192 # Errors - *we highly recommended enabling this*

#
#  Junkbuster normally uses "multi-threading", a software technique
#  that permits it to handle many different requests simultaneously.
#  In some cases you may wish to disable this -- particularly if
#  you're trying to debug a problem.  The 'single-threaded' option
#  forces Junkbuster to handle requests sequentially.
#
#  Default: Multithreaded mode
#
#single-threaded

#
#    'toggle' allows you to temporarily disable all Junkbuster's 
#    filtering.  Just set "toggle 0".
#    
#    The Windows version of Junkbuster 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 '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.
#
#    'toggle 1' means Junkbuster runs normally, 'toggle 0' means
#    that Junkbuster becomes a non-anonymizing non-blocking
#    proxy.
#
#  Default: 1
#
toggle 1


#############################################################################
# Access Control List
#############################################################################
#
# Access controls are included at the request of some ISPs and systems
# administrators, and are not usually needed by individual users.
# Please note the warnings in the FAQ that this proxy is not
# intended to be a substitute for a firewall or to encourage anyone
# to defer addressing basic security weaknesses.
# For details see the documentation
#
# If no access settings are specified, the proxy talks to anyone that
# connects.  If any access settings file are specified, then the proxy
# talks only to IP addresses permitted somewhere in this file and not
# denied later in this file.
#
# Summary -- if using an ACL:
#
#  Client must have permission to receive service
#  LAST match in ACL wins
#  Default behavior is to deny service
#
# Syntax for an entry in the Access Control List is:
#
# ACTION    SRC_ADDR[/SRC_MASKLEN]    [ DST_ADDR[/DST_MASKLEN] ]
#
# where the fields are
#
# ACTION      = "permit-access" | "deny-access"
#
# SRC_ADDR    = client hostname or dotted IP address
# SRC_MASKLEN = number of bits in the subnet mask for the source
#
# DST_ADDR    = server or forwarder hostname or dotted IP address
# DST_MASKLEN = number of bits in the subnet mask for the target
#
# field separator (FS) is whitespace (space or tab)
#
# IMPORTANT NOTE
# ==============
# If the junkbuster is using a forwarder or a gateway for a particular 
# destination URL, the DST_ADDRR that is examined is the address of
# the forwarder or the gateway and NOT the address of the ultimate target.
# This is necessary because it may be impossible for the local
# junkbuster to determine the address of the ultimate target
# (that's often what gateways are used for).
#
# Here are a few examples to show how the ACL works:
#
# localhost is OK --  no DST_ADDR implies that ALL destination addresses are OK
# permit-access localhost
#
# a silly example to illustrate:
#
# permit any host on the class-C subnet with junkbusters to go anywhere
#
# permit-access www.junkbusters.com/24
#
# except deny one particular IP address from using it at all
#
# deny-access      ident.junkbusters.com
#
# another example
#
# You can specify an explicit network address and subnet mask.
# Explicit addresses do not have to be resolved to be used.
#
# permit-access 207.153.200.0/24
#
# a subnet mask of 0 matches anything, so the next line permits everyone.
#
# permit-access 0.0.0.0/0
#
# Note:  you cannot say
#
# permit-access .org
#
# to allow all .org domains; every IP-address listed must resolve fully.
#
# An ISP may want to provide a junkbuster that is accessible by "the world"
# and yet restrict use of some of their private content to hosts on its
# internal network (i.e. its own subscribers).  Say, for instance the
# ISP owns the Class-B IP address block 123.124.0.0 (a 16 bit netmask).
# This is how they could do it:
#
# permit-access 0.0.0.0/0   0.0.0.0/0   # other clients can go anywhere 
#                                       # with the following exceptions:
#
# deny-access   0.0.0.0/0   123.124.0.0/16 # block all external requests for
#                                          # sites on the ISP's network
#
# permit 0.0.0.0/0   www.my_isp.com # except for the ISP's main web site
#
# permit 123.124.0.0/16 0.0.0.0/0   # the ISP's clients can go anywhere
#
# Note that some hostnames may be listed with multiple IP addresses;
# the primary value returned by gethostbyname() is used.
#
# Default: Anyone can access the proxy.


#############################################################################
# Forwarding
#############################################################################
#
#
# This feature allows routing 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
#
# It can also be used in an environment with multiple networks to route
# requests via multiple gateways allowing transparent access to multiple
# networks without having to modify browser configurations.
#
# Also specified here are SOCKS proxies.  We support SOCKS 4 and SOCKS 4A.
# The difference is that SOCKS 4A will resolve the target hostname using
# DNS on the SOCKS server, not our local DNS client.
#
# The syntax of each line is
#
# forward target_domain[:port] http_proxy_host[:port]
# forward-socks4  target_domain[:port] socks_proxy_host[:port] http_proxy_host[:port]
# forward-socks4a target_domain[:port] socks_proxy_host[:port] http_proxy_host[:port]
#
# If http_proxy_host is ".", then requests are not forwarded to
# a HTTP proxy but are made directly to the web servers.
#
# Lines are checked in turn, and the last match wins.
#
# There is an implicit line equivalent to the following, which specifies that
# anything not finding a match on the list is to go out without forwarding
# or gateway protocol; like so:
#    forward .* .  # implicit
#
# In the following common configuration, everything goes to Lucent's LPWA,
# except SSL on port 443 (which it doesn't handle)
#    forward .*    lpwa.com:8000
#    forward :443 .
#
# See the FAQ for instructions on how to automate the login procedure for LPWA.
# Some users have reported difficulties related to LPWA's use of . as the
# last element of the domain, and have said that this can be fixed with this:
#    forward lpwa.  lpwa.com:8000
# (NOTE: the syntax for specifiying target_domain has changed since the
# previous paragraph weas written - it will not work now.  More information
# is welcome.)
#
# In this fictitious example, everything goes via an ISP's caching proxy,
# except requests to that ISP:
#
# forward .* caching.myisp.net:8000
# forward myisp.net .
#
# For the @home network, we're told the forwarding configuration is this:
# 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 security risk;
# see our page on cookies. 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 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
#
# An advanced example for network administrators:
#
# If you have links to multiple ISPs that provide various special content to
# their subscribers, you can configure forwarding to pass requests to the
# specific host that's connected to that ISP so that everybody can see all
# of the content on all of the ISPs.
#
# This is tricky, but here's a sample:
# 
# host-a has a PPP connection to isp-a.com
# host-b has a PPP connection to isp-b.com
#
# host-a can run an Internet Junkbuster proxy with forwarding like this:
#   forward .* .
#   forward isp-b.com host-b:8000
#
# host-b can run an Internet Junkbuster proxy with forwarding like this:
#   forward .* .
#   forward isp-a.com host-a:8000
#
# Now, *anyone* on the Internet (including users on host-a and host-b)
# can set their browser's proxy to *either* host-a or host-b and
# be able to browse the content on isp-a or isp-b.
#
#
# 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.
#
#   forward *. ssbcache.ukc.ac.uk:3128 # Use the proxy, except for:
#   forward .ukc.ac.uk            . # Anything on the same domain as us
#   forward *                     . # Host with no domain specified
#   forward 129.12.*.*            . # A dotted IP on our /16 network.
#   forward 127.*.*.*             . # Loopback address
#   forward localhost.localdomain . # Loopback address
#   forward www.ukc.mirror.ac.uk  . # Specific host
#


#############################################################################
#  5. WINDOWS GUI OPTIONS
#############################################################################
#
#  Junkbuster has a number of options specific to the Windows GUI
#  interface:
#
#    activity-animation      {1 or 0}
#
#    If set to 1, the Junkbuster icon will animate when Junkbuster is
#    active.
#
#Win32-only: activity-animation      1

#    log-messages            {1 or 0}
#
#    If set to 1, Junkbuster will log messages to the console window.
#
#Win32-only: log-messages            1

#    log-buffer-size         {1 or 0}?
#
#    If log-buffer-size is set to 1, the size of the log buffer, that
#    is the amount of memory used for the log messages displayed in
#    the console window, will be limited to 'log-max-lines' (see below).
#
#    Warning: Setting this to 0 will result in the buffer to grow
#             infinitely and eat up all your memory!
#
#Win32-only: log-buffer-size   1

#    log-max-lines   {number of lines, e.g., '200'}
#
#    Maximum number of lines held in the log buffer. See above.
#
#Win32-only: log-max-lines   200

#    log-highlight-messages  {1 or 0}
#
#    If set to 1, Junkbuster will highlight portions of the log
#    messages with a bold-faced font.
#
#Win32-only: log-highlight-messages  1

#    log-font-name           {font name, e.g., 'Comic Sans MS'}
#
#    The font used in the console window.
#
#Win32-only: log-font-name           Comic Sans MS

#    log-font-size           {font size in points, e.g., '8'}
#
#    Font size used in the console window.
#
#Win32-only: log-font-size           8

#    show-on-task-bar        {1 or 0}
#
#    Controls whether or not Junkbuster will appear as a button on the Task
#    bar when minimized.
#
#Win32-only: show-on-task-bar        0


#    close-button-minimizes  1
#
#    If set, the Windows close button will minimize Junkbuster instead
#    of closing the program (close with the exit option on the File
#    menu).
#
#Win32-only: close-button-minimizes  1


#
#  This option is specific to the Win32 console version of JunkBuster:
#
#    hide-console
#
#    If this option is used, Junkbuster will disconnect from and hide 
#    the command console.
#
#Win32-only: #hide-console


# Note: Junkbuster is distributed under the GNU General Public License (GPL)
#       For details, see http://www.gnu.org/copyleft/gpl.html