WWWOFFLE - Configuration File - Version 2.9 =========================================== Introduction ------------ The configuration file (wwwoffle.conf) specifies all of the parameters that control the operation of the proxy server. The file is split into sections each containing a series of parameters as described below. The file CHANGES.CONF explains the changes in the configuration file between this version of the program and previous ones. The file is split into sections, each of which can be empty or contain one or more lines of configuration information. The sections are named and the order that they appear in the file is not important. The general format of each of the sections is the same. The name of the section is on a line by itself to mark the start. The contents of the section are enclosed between a pair of lines containing only the '{' and '}' characters or the '[' and ']' characters. When the '{' and '}' characters are used the lines between contain configuration information. When the '[' and ']' characters are used then there must only be a single non-empty line between them that contains the name of a file (in the same directory) containing the configuration information for the section. Comments are marked by a '#' character at the start of the line and they are ignored. Blank lines are also allowed and ignored. The phrases URL-SPECIFICATION (or URL-SPEC for short) and WILDCARD have specific meanings in the configuration file and are described at the end. Any item enclosed in '(' and ')' in the descriptions means that it is a parameter supplied by the user, anything enclosed in '[' and ']' is optional, the '|' symbol is used to denote alternate choices. Some options apply to specific URLs only, this is indicated by having a URL-SPECIFICATION enclosed between '<' & '>' in the option, the first URL-SPECIFICATION to match is used. If no URL-SPECIFICATION is given then it matches all URLs. -------------------------------------------------------------------------------- StartUp ------- This contains the parameters that are used when the program starts, changes to these are ignored if the configuration file is re-read while the program is running. bind-ipv4 = (hostname) | (ip-address) | none Specify the hostname or IP address to bind the HTTP proxy and WWWOFFLE control port sockets to using IPv4 (default='0.0.0.0'). If 'none' is specified then no IPv4 socket is bound. If this is changed from the default value then the first entry in the LocalHost section may need to be changed to match. bind-ipv6 = (hostname) | (ip-address) | none Specify the hostname or IP address to bind the HTTP proxy and WWWOFFLE control port sockets to using IPv6 (default='::'). If 'none' is specified then no IPv6 socket is bound. This requires the IPv6 compilation option. If this is changed from the default value then the first entry in the LocalHost section may need to be changed to match. http-port = (port) An integer specifying the port number for connections to access the internal WWWOFFLE pages and for HTTP/HTTPS/FTP proxying (default=8080). This is the port number that must be specified in the client to connect to the WWWOFFLE proxy for HTTP/HTTPS/FTP proxying. https-port = (port) An integer specifying the port number for encrypted connections to access the internal WWWOFFLE pages and for HTTP/FTP proxying (default=8443). Requires gnutls compilation option. wwwoffle-port = (port) An integer specifying the port number for the WWWOFFLE control connections to use (default=8081). spool-dir = (dir) The full pathname of the top level cache directory (spool directory) (default=/var/spool/wwwoffle or whatever was used when the program was compiled). run-uid = (user) | (uid) The username or numeric uid to change to when the WWWOFFLE server is started (default=none). This option only works if the server is started by the root user on UNIX-like systems. run-gid = (group) | (gid) The group name or numeric gid to change to when the WWWOFFLE server is started (default=none). This option only works if the server is started by the root user on UNIX-like systems. use-syslog = yes | no Whether to use the syslog facility for messages or not (default=yes). password = (word) The password used for authentication of the control pages, for deleting cached pages etc (default=none). For the password to be secure the configuration file must be set so that only authorised users can read it. max-servers = (integer) The maximum number of server processes that are started for online and automatic fetching (default=8). max-fetch-servers = (integer) The maximum number of server processes that are started to fetch pages that were marked in offline mode (default=4). This value must be less than max-servers or you will not be able to use WWWOFFLE interactively online while fetching. -------------------------------------------------------------------------------- Options ------- Options that control how the program works. log-level = debug | info | important | warning | fatal The minimum log level for messages in syslog or stderr (default=important). socket-timeout = (time) The time in seconds that WWWOFFLE will wait for data on a socket connection before giving up (default=120). dns-timeout = (time) The time in seconds that WWWOFFLE will wait for a DNS (Domain Name Service) lookup before giving up (default=60). connect-timeout = (time) The time in seconds that WWWOFFLE will wait for the socket connection to be made before giving up (default=30). disconnect-wait = (time) The extra time in seconds that WWWOFFLE will wait before disconnecting a socket connection (default=0). connect-retry = yes | no If a connection cannot be made to a remote server then WWWOFFLE should try again after a short delay (default=no). dir-perm = (octal int) The directory permissions to use when creating spool directories (default=0755). This option overrides the umask of the user and must be in octal starting with a '0'. file-perm = (octal int) The file permissions to use when creating spool files (default=0644). This option overrides the umask of the user and must be in octal starting with a '0'. run-online = (filename) The full pathname of a program to run when WWWOFFLE is switched to online mode (default=none). The program is started in the background with a single parameter set to the current mode name "online". run-offline = (filename) The full pathname of a program to run when WWWOFFLE is switched to offline mode (default=none). The program is started in the background with a single parameter set to the current mode name "offline". run-autodial = (filename) The full pathname of a program to run when WWWOFFLE is switched to autodial (default=none). The program is started in the background with a single parameter set to the current mode name "fetch". run-fetch = (filename) The full pathname of a program to run when a WWWOFFLE fetch starts or stops (default=none). The program is started in the background with two parameters, the first is the word "fetch" and the second is "start" or "stop". lock-files = yes | no Enable the use of lock files to stop more than one WWWOFFLE process from downloading the same URL at the same time (default=no). Disabling the lock-files may result in incomplete pages being displayed or many copies being downloaded if multiple requests are made for the same URL at the same time. reply-compressed-data = yes | no If the replies that are made to the client are to contain compressed data when requested (default=no). Requires zlib compilation option. reply-chunked-data = yes | no If the replies that are made to the client are to use chunked encoding when possible (default=yes). exec-cgi = (pathname) Enable the use of CGI scripts for the local pages on the WWWOFFLE server that match the wildcard pathname (default=none). -------------------------------------------------------------------------------- OnlineOptions ------------- Options that control how WWWOFFLE behaves when it is online. [] pragma-no-cache = yes | no Whether to request a new copy of a page if the request from the client has 'Pragma: no-cache' (default=yes). This option takes precedence over the request-changed and request-changed-once options. [] cache-control-no-cache = yes | no Whether to request a new copy of a page if the request from the client has 'Cache-Control: no-cache' (default=yes). This option takes precedence over the request-changed and request-changed-once options. [] cache-control-max-age-0 = yes | no Whether to request a new copy of a page if the request from the client has 'Cache-Control: max-age=0' (default=yes). This option takes precedence over the request-changed and request-changed-once options. [] cookies-force-refresh = yes | no Whether to force the refresh of a page if the request from the client contains a cookie (default=no). This option takes precedence over the request-changed and request-changed-once options. [] request-changed = (time) While online pages will only be fetched if the cached version is older than this specified time in seconds (default=600). Setting this value negative will indicate that cached pages are always used while online. Longer times can be specified with a 'm', 'h', 'd' or 'w' suffix for minutes, hours, days or weeks (e.g. 10m=600). [] request-changed-once = yes | no While online pages will only be fetched if the cached version has not already been fetched once this session online (default=yes). This option takes precedence over the request-changed option. [] request-expired = yes | no While online pages that have expired will always be requested again (default=no). This option takes precedence over the request-changed and request-changed-once options. [] request-no-cache = yes | no While online pages that ask not to be cached will always be requested again (default=no). This option takes precedence over the request-changed and request-changed-once options. [] request-redirection = yes | no While online pages that redirect the client to another URL temporarily will be requested again. (default=no). This option takes precedence over the request-changed and request-changed-once options. [] request-conditional = yes | no While online pages that are requested from the server will be conditional requests so that the server only sends data if the page has changed (default=yes). [] validate-with-etag = yes | no When making a conditional request to a server enable the use of the HTTP/1.1 cache validator 'Etag' as well as modification time 'If-Modified-Since' (default=yes). The request-conditional option must also be selected for this option to take effect. [] try-without-password = yes | no If a request is made for a URL that contains a username and password then a request is made for the same URL without a username and password specified (default=yes). This allows for requests for the URL without a password to re-direct the client to the passworded version. [] intr-download-keep = yes | no If the client closes the connection while online the currently downloaded incomplete page should be kept (default=no). [] intr-download-size = (integer) If the client closes the connection while online the page should continue to download if it is smaller than this size in kB (default=1). [] intr-download-percent = (integer) If the client closes the connection while online the page should continue to download if it is more than this percentage complete (default=80). [] timeout-download-keep = yes | no If the server connection times out while reading then the currently downloaded incomplete page should be kept (default=no). [] keep-cache-if-not-found = yes | no If the remote server replies with an error message or a redirection while there is a cached version with status 200 the previously cached version should be kept (default=no). [] request-compressed-data = yes | no If the requests that are made to the server are to request compressed data (default=yes). Requires zlib compilation option. [] request-chunked-data = yes | no If the requests that are made to the server are to request chunked encoding (default=yes). -------------------------------------------------------------------------------- OfflineOptions -------------- Options that control how WWWOFFLE behaves when it is offline. [] pragma-no-cache = yes | no Whether to request a new copy of a page if the request from the client has 'Pragma: no-cache' (default=yes). This option should be set to 'no' if when browsing offline all pages are re-requested by a 'broken' browser. [] cache-control-no-cache = yes | no Whether to request a new copy of a page if the request from the client has 'Cache-Control: no-cache' (default=yes). This option should be set to 'no' if when browsing offline all pages are re-requested by a 'broken' browser. [] cache-control-max-age-0 = yes | no Whether to request a new copy of a page if the request from the client has 'Cache-Control: max-age=0' (default=yes). This option should be set to 'no' if when browsing offline all pages are re-requested by a 'broken' browser. [] confirm-requests = yes | no Whether to return a page requiring user confirmation instead of automatically recording requests made while offline (default=no). [] dont-request = yes | no Do not request any URLs that match this when offline (default=no). -------------------------------------------------------------------------------- SSLOptions ---------- Options that control how WWWOFFLE behaves when a connection is made to it for an https or Secure Sockets Layer (SSL) server. Normally only tunnelling (with no decryption or caching of the data) is possible. When WWWOFFLE is compiled with the gnutls library it is possible configure WWWOFFLE to decrypt, cache and re-encrypt the connections. quick-key-gen = yes | no Normally generation of secret keys for the SSL/https functions uses the default GnuTLS option for random number source. This can be slow on some machines so this option selects a quicker but less secure random number source (default = no). Requires GnuTLS compilation option. expiration-time = (age) The length of time after creation that each certificate will expire (default = 1y). Requires GnuTLS compilation option. enable-caching = yes | no If caching (involving decryption and re-encryption) of SSL/https server connections is allowed (default = no). Requires GnuTLS compilation option. allow-tunnel = (host[:port]) A hostname and port number (a WILDCARD match) for an https/SSL server that can be connected to using WWWOFFLE as a tunnelling proxy (no caching or decryption of the data) (default is no hosts or ports allowed). This option should be set to *:443 to allow https to the default port number. There can be more than one option for other ports or hosts as required. This option takes precedence over the allow-cache option. The host value is matched against the URL as presented, no hostname to IP or IP to hostname lookups are performed to find alternative equivalent names. disallow-tunnel = (host[:port]) A hostname and port number (a WILDCARD match) for an https/SSL server that can not be connected to using WWWOFFLE as a tunnelling proxy. There can be more than one option for other ports or hosts as required. This option takes precedence over the allow-tunnel option. The host value is matched against the URL as presented, no hostname to IP or IP to hostname lookups are performed to find alternative equivalent names. allow-cache = (host[:port]) A hostname and port number (a WILDCARD match) for an https/SSL server that can be connected to using WWWOFFLE as a caching proxy (decryption of the data) (default is no hosts or ports allowed). This option should be set to *:443 to allow https to the default port number. There can be more than one option for other ports or hosts as required. The host value is matched against the URL as presented, no hostname to IP or IP to hostname lookups are performed to find alternative equivalent names. Requires GnuTLS compilation option. disallow-cache = (host[:port]) A hostname and port number (a WILDCARD match) for an https/SSL server that can not be connected to using WWWOFFLE as a caching proxy. This option takes precedence over the allow-cache option. The host value is matched against the URL as presented, no hostname to IP or IP to hostname lookups are performed to find alternative equivalent names. Requires GnuTLS compilation option. -------------------------------------------------------------------------------- FetchOptions ------------ Options that control what linked elements are downloaded when fetching pages that were requested while offline. [] stylesheets = yes | no If style sheets are to be fetched (default=no). [] images = yes | no If images are to be fetched (default=no). [] webbug-images = yes | no If images that are declared in the HTML to be 1 pixel square are also to be fetched (default=yes); requires the images option to be selected. If these images are not fetched then the replace-webbug-images option in the ModifyHTML section can be used to stop browsers requesting them. [] srcset-images = yes | no If images are included using the HTML5 'srcset' attribute are also to be fetched (default=yes); requires the images option to be selected. This HTML5 option allows multiple image URLs to be specified depending on the browser resolution, enabling this option fetches all of them. [] icon-images = yes | no If icons (also called favourite icons or shortcut icons) as used by browsers for bookmarks are to be fetched (default=no); requires the images option to be selected. [] only-same-host-images = yes | no If the only images that are fetched are the ones that are on the same host as the page that references them, requires the images option to also be selected (default=no). [] frames = yes | no If frames are to be fetched (default=no). [] iframes = yes | no If inline frames (iframes) are to be fetched (default=no). [] scripts = yes | no If scripts (e.g. Javascript) are to be fetched (default=no). [] objects = yes | no If objects (e.g. Java class files) are to be fetched (default=no). -------------------------------------------------------------------------------- IndexOptions ------------ Options that control what is displayed in the indexes. create-history-indexes = yes | no Enables creation of the lasttime/prevtime and lastout/prevout indexes (default=yes). The cycling of the indexes is always performed and they will flush even if this option is disabled. cycle-indexes-daily = yes | no Cycles the lasttime/prevtime and lastout/prevout indexes daily instead of each time online or fetching (default = no). list-outgoing = yes | no Choose if the URL is to be listed in the outgoing index (default=yes). list-latest = yes | no Choose if the URL is to be listed in the lasttime/prevtime and lastout/prevout indexes (default=yes). list-monitor = yes | no Choose if the URL is to be listed in the monitor index (default=yes). list-host = yes | no Choose if the URL is to be listed in the host indexes (default=yes). list-any = yes | no Choose if the URL is to be listed in any of the indexes (default=yes). -------------------------------------------------------------------------------- ModifyHTML ---------- Options that control how the HTML that is provided from the cache is modified. [] enable-modify-html = yes | no Enable the HTML modifications in this section (default=no). With this option disabled the following HTML options will not have any effect. With this option enabled there is a small speed penalty. [] add-cache-info = yes | no At the bottom of all of the spooled pages the date that the page was cached and some navigation buttons are to be added (default=no). [] anchor-cached-begin = (HTML code) | Anchors (links) in the spooled page that are in the cache are to have the specified HTML inserted at the beginning (default=""). [] anchor-cached-end = (HTML code) | Anchors (links) in the spooled page that are in the cache are to have the specified HTML inserted at the end (default=""). [] anchor-requested-begin = (HTML code) | Anchors (links) in the spooled page that are not in the cache but have been requested for download are to have the specified HTML inserted at the beginning (default=""). [] anchor-requested-end = (HTML code) | Anchors (links) in the spooled page that are not in the cache but have been requested for download are to have the specified HTML inserted at the end (default=""). [] anchor-not-cached-begin = (HTML code) | Anchors (links) in the spooled page that are not in the cache or requested are to have the specified HTML inserted at the beginning (default=""). [] anchor-not-cached-end = (HTML code) | Anchors (links) in the spooled page that are not in the cache or requested are to have the specified HTML inserted at the end (default=""). [] disable-script = yes | no Removes all scripts and scripted events (default=no). [] disable-applet = yes | no Removes all Java applets (default=no). [] disable-style = yes | no Removes all stylesheets and style references (default=no). [] disable-blink = yes | no Removes the tag from HTML but does not disable blink in stylesheets (default=no). [] disable-marquee = yes | no Removes the tag from HTML to stop scrolling text (default=no). [] disable-flash = yes | no Removes any Shockwave Flash animations (default=no). [] disable-iframe = yes | no Removes any inline frames (the