# Sample Configuration file for Privoxy # # $Id: config,v 1.30 2002/03/24 11:37:39 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 Privoxy configuration. If you modify this # file, you will need to send a couple of requests to the proxy # before any changes take effect. # # When starting Privoxy on Unix systems, give the name of this # file as an argument. On Windows systems, Privoxy will look for # this file with the name 'config.txt' in the same directory where # Privoxy 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, # # actionsfile default.action # # Indicates that the actionsfile is named 'default.action'. # # 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, Privoxy 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 # # Privoxy 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 Privoxy where to find all those other # files. # # Privoxy looks for these files in the directory specified with # "confdir" option. # # (Note that on Windows, Privoxy usually starts with the current # directory (".") being the same directory as the executable) # # 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 filterfile specified. # No sites are blocked. Nothing is an image. # actionsfile default.action # The 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: content modification. (see '+-filter' in actionsfile) # filterfile default.filter # # The logfile is where all logging and error messages are written. # The logfile can be useful for tracking down a problem with # Privoxy (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/privoxy.* +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 Privoxy 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, Privoxy 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 Privoxy 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: Do not display an e-mail address # admin-address fill@me.in.please # # Proxy-info-url can be set to a URL that contains more info about # this Privoxy 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 Privoxy will # listen for connections from your Web browser. The default is to # listen on the local host on port 8118, and this is suitable for # most users. (In your web browser, under proxy configuration, list # the proxy server as 'localhost' and the port as '8118'). # # If you already have another service running on port 8118, 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 []:" If you leave out the ip # adress, Privoxy 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 Privoxy 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:8118 # # If you want it to listen on all addresses (including the outside # connection): # # listen-address :8118 # # 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:8118 # listen-address 127.0.0.1:8118 # listen-address 127.0.0.1:8118 # # 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 # = debug fast redirects # debug 256 # = debug GIF deanimation # debug 512 # CLF = Common Log Format # debug 1024 # = debug kill popups # 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 # Privoxy) is always on and cannot be disabled. # # If you want to use CLF, you should set "debug 512" 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* # # Privoxy 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 Privoxy to handle requests sequentially. # # Default: Multithreaded mode # #single-threaded # # 'toggle' allows you to temporarily disable all Privoxy's # filtering. Just set "toggle 0". # # This can now be toggled remotely, through the web-based config # interface. There is no reason to edit this file any more. # # The Windows version of Privoxy 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 Privoxy on and off. This is useful if you want to # temporarily disable Privoxy, e.g., to access a site that # requires cookies which you normally have blocked. # # 'toggle 1' means Privoxy runs normally, 'toggle 0' means # that Privoxy becomes a non-anonymizing non-blocking # proxy. # # Default: 1 # toggle 1 # # For content filtering, i.e. the +filter and +deanimate-gif # actions, it is neccessary that Privoxy buffers up the # whole document body. This can be potentially dangerous, since # a server could just keep sending data indefinitely and wait # for your RAM to exhaust. # The buffer-limit option lets you set the size in Kbytes that # each buffer may use at maximum. When the documents buffer # exceeds that size, it is flushed to the client unfiltered and # no further attempt to filter the rest of it is taken. # Remember that there may multiple threads running, which might # require up to buffer-limit Kbytes *each*, unless you have set # single-threaded below. # # Default: 4069, i.e. 4 MB # buffer-limit 4069 # # Enable the web-based actionsfile editor. Set to 1 to enable, # 0 to disable. Note that you must have compiled Privoxy # with support for this feature, otherwise this option has no # effect. # # 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: Disabled # enable-edit-actions 1 # # Allow Privoxy to be toggled on and off remotely, using your # web browser. Set to 1 to enable, 0 to disable. Note that you # must have compiled Privoxy with support for this feature, # otherwise this option has no effect. # # Security note: If this is enabled, anyone who can use the proxy # can toggle it on or off, and their changes will affect all users. # For shared proxies, you probably want to disable this. # # Default: Disabled # enable-remote-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 Privoxy 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 # Privoxy 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 our web server to go # anywhere # # permit-access www.example.com/24 # # except deny one particular IP address from using it at all # # deny-access hacker.example.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 Privoxy 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:8118 # 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:8118 # (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:8118 # 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:8118 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 Privoxy with forwarding like this: # forward .* . # forward isp-b.com host-b:8118 # # host-b can run Privoxy with forwarding like this: # forward .* . # forward isp-a.com host-a:8118 # # 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 # # # Note: If you intend to chain Privoxy and squid locally, the chain # broswer -> squid -> Privoxy is the recommended way. # # Your squid configuration could then look like this: # # # Define Privoxy as parent cache # cache_peer 127.0.0.1 8118 parent 0 no-query # # # Define ACL for protocol FTP # acl FTP proto FTP # # # Do not forward ACL FTP to Privoxy # always_direct allow FTP # # # Do not forward ACL CONNECT (https) to Privoxy # always_direct allow CONNECT # # # Forward the rest to Privoxy # never_direct allow all # ############################################################################# # 5. WINDOWS GUI OPTIONS ############################################################################# # # Privoxy has a number of options specific to the Windows GUI # interface: # # activity-animation {1 or 0} # # If set to 1, the Privoxy icon will animate when Privoxy is # active. # #Win32-only: activity-animation 1 # log-messages {1 or 0} # # If set to 1, Privoxy 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, Privoxy 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 Privoxy 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 Privoxy 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 Privoxy: # # hide-console # # If this option is used, Privoxy will disconnect from and hide # the command console. # #Win32-only: #hide-console # Note: Privoxy is distributed under the GNU General Public License (GPL) # For details, see http://www.gnu.org/copyleft/gpl.html