home *** CD-ROM | disk | FTP | other *** search
/ Dream 52 / Amiga_Dream_52.iso / Linux / Magazine / wwwoffle-2.1.tar.gz / wwwoffle-2.1 / README.CONF < prev    next >
Text File  |  1998-02-19  |  15KB  |  356 lines
  1.           WWWOFFLE - World Wide Web Offline Explorer - Version 2.1
  2.           ========================================================
  3.  
  4. If you are upgrading from version 1.x to version 2.x then you should read the
  5. file CHANGES.CONF which explains how to convert the sections in your existing
  6. wwwoffle.conf file to the new format.
  7.  
  8. If you are upgrading from version 2.0[abc] to version 2.1 then the file
  9. CHANGES.CONF shows the new options.
  10.  
  11.  
  12. The configuration file (wwwoffle.conf) specifies all of the parameters that
  13. control the operation of the proxy server.  The file is split into sections each
  14. containing a series of parameters as described below.
  15.  
  16. The sections are delimited in the file by having the section name alone on a
  17. line, a line containing a single '{', the parameters in the section and a line
  18. containing a single '}'.  Comments are marked by a '#' at the start of the line.
  19.  
  20.  
  21. StartUp
  22. -------
  23.  
  24. This contains the parameters that are used when the program starts, changes to
  25. these are ignored if the configuration file is re-read while the program is
  26. running.
  27.  
  28. http-port         = <port>          ; An integer specifying the port for the
  29.                                       HTTP proxy (default=8080).
  30. wwwoffle-port     = <port>          ; An integer specifying the port for
  31.                                       wwwoffle control connections
  32.                                       (default=8081).
  33. spool-dir         = <dir>           ; The name of the spool directory
  34.                                       (default=/var/spool/wwwoffle).
  35. run-uid           = <user> | <uid>  ; The username or numeric uid to run the
  36.                                       wwwoffled server as (default=none).
  37. run-gid           = <group> | <gid> ; The groupname or numeric gid to run the
  38.                                       wwwoffled server as (default=none).
  39. use-syslog        = yes | no        ; Whether to use the syslog facility for
  40.                                       messages (default=yes).
  41. password          = <word>          ; The password used for authentication of
  42.                                       the control message (default=none).
  43. max-servers       = <integer>       ; The maximum number of server processes
  44.                                       that are started (default=8).
  45. max-fetch-servers = <integer>       ; The maximum number of server processes
  46.                                       that are started to fetch pages that
  47.                                       were marked in offline mode (default=4).
  48.  
  49. Notes: For the password to work the configuration file must be set so that only
  50.        authorised users can read it.
  51.      : To use the run-uid/run-gid options, the server must be start as root.
  52.      : The max-fetch-servers value must be less than max-servers or you will
  53.        not be able to use wwwoffle interactively online while fetching.
  54.  
  55.  
  56. Options
  57. -------
  58.  
  59. Options that control how the program works.
  60.  
  61. log-level         = debug | info | important | warning | fatal
  62.                              ; Log messages with this or higher priority
  63.                                (default=important).
  64. fetch-images      = yes | no ; Whether to fetch the images that are contained in
  65.                                pages that are requested while offline and
  66.                                downloaded later (default=no).
  67. fetch-frames      = yes | no ; Whether to fetch the frames that are contained in
  68.                                pages that are requested while offline and
  69.                                downloaded later (default=no).
  70. index-latest-days = <age>    ; The number of days to display in the index of the
  71.                                latest pages (default=7 days).
  72. add-info-refresh  = yes | no ; At the bottom of all of the spooled pages the
  73.                                date that the page was cached and a refresh
  74.                                button is to be added (default=no).
  75. request-changed   = <time>   ; While online pages will only be fetched if the
  76.                                cached version is older than this specified time
  77.                                in seconds (default=600).
  78. pragma-no-cache   = yes | no ; Whether to request a new copy of a page if the
  79.                                request has 'Pragma: no-cache' (default=yes).
  80. offline-requests  = yes | no ; Whether to record requests that are made while
  81.                                offline or to return an error (default=yes).
  82. monitor-interval  = <age>    ; The interval in days between monitoring of the
  83.                                specified URLs (default=7 days).
  84.  
  85. Notes: The request-changed option can be set negative to indicate that cached
  86.        pages are always used while online.
  87.      : The pragma-no-cache option should be set to 'no' if when browsing
  88.        offline all pages are re-requested by a 'broken' browser.
  89.      : The monitor-interval option when set to '0' means to check each time
  90.        wwwoffle is online, '1' means once per day, etc.
  91.  
  92.  
  93. LocalHost
  94. ---------
  95.  
  96. A list of hosts that the host running the wwwoffled server may be known by.
  97. This is so that the proxy does not need to contact itself to get the server
  98. local pages.
  99.  
  100. <host> ; A hostname or IP address that in connection with the port number (in
  101.          the StartUp section) specifies the wwwoffle proxy HTTP server.
  102.  
  103. Notes: All of these hosts are also used the same way as those in the
  104.        LocalNet and AllowedConnect sections.
  105.      : The first named host is used as the server name for several features so
  106.        should be a name that will work from any client host if on a network.
  107.      : None of the entries here or in LocalNet are fetched via a proxy.
  108.  
  109.  
  110. LocalNet
  111. --------
  112.  
  113. A list of hosts that are not to be cached by wwwoffled because they are on a
  114. local network.
  115.  
  116. <host> ; A hostname or IP address that is not to be cached by the server.
  117.  
  118. Notes: The host name matches from the right so a domain name matches all hosts
  119.        in the domain, IP addresses match from the left.
  120.      : All entries here are assumed to be reachable even when offline.
  121.      : All of the hosts in LocalHost are also not cached.
  122.      : None of the entries here or in LocalHost are fetched via a proxy.
  123.  
  124.  
  125. AllowedConnect
  126. --------------
  127.  
  128. A list of client hosts that are allowed to connect to the server.
  129.  
  130. <host> ; A hostname or IP address that is allowed to connect to the server.
  131.  
  132. Notes: The host name matches from the right so a domain name matches all hosts
  133.        in the domain, IP addresses match from the left.
  134.      : All of the hosts in LocalHost are also allowed to connect.
  135.  
  136.  
  137. DontCache
  138. ---------
  139.  
  140. A list of servers and files on them that are not to be cached by wwwoffled.
  141.  
  142. default            = ...         ; When getting any URLs ...
  143. HOST-SPECIFICATION = ...         ; When getting URLs that match this ...
  144.        ...  = FILE-SPECIFICATION ; ... don't cache any files that match this.
  145.  
  146. Notes: See the bottom of this file for the description of HOST-SPECIFICATION
  147.      : See the bottom of this file for the description of FILE-SPECIFICATION
  148.      : The files will still be cached if fetched non-interactively.
  149.  
  150.  
  151. DontGet
  152. -------
  153.  
  154. A list of servers and files on them that are not to be got by wwwoffled (because
  155. they contain only junk adverts for example).
  156.  
  157. default            = ...         ; When getting any URLs ...
  158. HOST-SPECIFICATION = ...         ; When getting URLs that match this ...
  159.        ...  = FILE-SPECIFICATION ; ... don't get any files that match this.
  160.  
  161. Notes: See the bottom of this file for the description of HOST-SPECIFICATION
  162.      : See the bottom of this file for the description of FILE-SPECIFICATION
  163.  
  164.  
  165. DontGetRecursive
  166. ----------------
  167.  
  168. A list of servers and files on them that are not to be got by wwwoffled when
  169. fetching recursively.
  170.  
  171. default             = ...        ; When recursively getting any URLs ...
  172. HOST-SPECIFICATION  = ...        ; When recursively getting URLs that match
  173.                                     this ...
  174.        ...  = FILE-SPECIFICATION ; ... don't get any files that match this.
  175.  
  176. Notes: See the bottom of this file for the description of HOST-SPECIFICATION
  177.      : See the bottom of this file for the description of FILE-SPECIFICATION
  178.  
  179.  
  180. CensorHeader
  181. ------------
  182.  
  183. A list of HTTP header lines that are to be removed from the requests sent to web
  184. servers.
  185.  
  186. <header> ; A header field name, e.g. From, Cookie, User-Agent.
  187.  
  188. Notes: The header is case sensitive, and does not have a ':' at the end.
  189.  
  190.  
  191. FTPOptions
  192. ----------
  193.  
  194. Options to use when fetching files using ftp.
  195.  
  196. anon-username = <string>      ; The username to use for anonymous ftp
  197.                                 (default=anonymous).
  198. anon-password = <string>      ; The password to use for anonymous ftp
  199.                                 (default=<user>@<host>, determined at run time).
  200. auth-hostname = <host[:port]> ; A host to use a different username and password.
  201. auth-username = <string>      ; The username to use on the above host.
  202. auth-password = <string>      ; The password to use on the above host.
  203.  
  204. Notes: The anon-password should be set to a sensible value especially if you
  205.        are behind a firewall.
  206.      : The auth-hostname, auth-username and auth-password options must come
  207.        together as a triplet.
  208.      : The auth-hostname must be exact, it is not used as a wildcard match.
  209.  
  210.  
  211. MIMETypes
  212. ---------
  213.  
  214. MIME Types to use when fetching files not using HTTP.
  215.  
  216. default     = <mime-type>/<subtype> ; The default MIME type
  217.                                       (default=text/plain).
  218. .<file-ext> = <mime-type>/<subtype> ; The MIME type to associate with a file
  219.                                       extension.
  220.  
  221. Notes: You must include the '.' in the file extension.
  222.      : If more than one of the extensions match then the longest is used.
  223.  
  224.  
  225. Proxy
  226. -----
  227.  
  228. This contains the names of the HTTP (or other) proxies to use external to the
  229. local machine.
  230.  
  231. default             = <host[:port]> ; The hostname and port on it to use as the
  232.                                       default proxy.
  233. HOST-SPECIFICATION  = <host[:port]> ; The hostname and port on it to use as the
  234.                                       proxy when getting URLs that match the
  235.                                       HOST-SPECIFICATION.
  236. auth-hostname = <host[:port]>  ; A proxy server that uses proxy authentication.
  237. auth-username = <string>       ; The username to use on the above host.
  238. auth-password = <string>       ; The password to use on the above host.
  239.  
  240. Notes: See the bottom of this file for the description of HOST-SPECIFICATION
  241.      : A hostname that matches more than one entry here uses the proxy of the
  242.        longest matching one (protocol is included in assessing length).
  243.      : You can use none or no hostname to indicate that a default or particular
  244.        protocol or host is not to use a proxy.
  245.      : None of the hosts in LocalNet/LocalHost will be fetched via a proxy.
  246.      : The auth-hostname, auth-username and auth-password options must come
  247.        together as a triplet.
  248.      : The auth-hostname must be exact, it is not used as a wildcard match.
  249.  
  250.  
  251. Mirror
  252. ------
  253.  
  254. A list of servers that have mirrors to be used in preference or to resolve
  255. conflicts over multiple names for the same server.
  256.  
  257. <proto>/<host> = <proto>/<host> ; The first named protocol and host is to be
  258.                                   replaced by the second named protocol and
  259.                                   host.
  260. <host>         = <host>         ; The first named host is to be replaced by the
  261.                                   second named host for all protocols.
  262.  
  263. Notes: Symbolic links in the spool directory also work, but they are only
  264.        checked when wwwoffled is started or 'wwwoffle -config' is run.
  265.      : The host names must match exactly, no wildcards.
  266.  
  267.  
  268. Purge
  269. -----
  270.  
  271. The method to determine which pages to purge, the default age the host specific
  272. maximum age of the pages in days, and the maximum cache size.
  273.  
  274. use-mtime           = yes | no ; The method to use to decide which files to
  275.                                  purge, last access time (atime) or last
  276.                                  modification time (mtime) (default=no).
  277. max-size            = <size>   ; The maximum size for the cache in MB
  278.                                  (default=0).
  279. default             = <age>    ; The default maximum age of pages in days
  280.                                  (default=28).
  281. HOST-SPECIFICATION  = <age>    ; The maximum age of pages that match the
  282.                                  HOST-SPECIFICATION
  283.  
  284. Notes: See the bottom of this file for the description of HOST-SPECIFICATION
  285.      : A hostname that matches more than one entry here uses the age of the
  286.        longest matching one (protocol is included in assessing length).
  287.      : An age of zero means not to keep, negative not to delete.
  288.      : A maximum cache size of 0 means there is no limit to the size.
  289.      : When there is a non-zero maximum cache size it is measured excluding all
  290.        hosts with a negative maximum age (never purged hosts).
  291.  
  292.  
  293. --------------------------------------------------------------------------------
  294.  
  295. HOST-SPECIFICATION
  296. ------------------
  297.  
  298. When specifying a host and protocol in many of the sections a HOST-SPECIFICATION
  299. can be used, this is a way of recognising a URL.
  300.  
  301. For the purposes of this explanation a URL is considered to be made up of three
  302. parts.
  303.  
  304. proto           The protocol that is used (e.g. http, ftp)
  305. host            The server hostname (e.g. www.gedanken.demon.co.uk) or a domain
  306.                 name (e.g. demon.co.uk) or an IP address (e.g. 1.2.3.4) or a
  307.                 subnet (e.g. 1.2.3).
  308. port            The port number on the host (e.g. default of 80 for HTTP).
  309.  
  310.  
  311. For example the wwwoffle homepage: http://www.gedanken.demon.co.uk/wwwoffle/
  312. The protocol is 'http', the host is 'www.gedanken.demon.co.uk', the port is the
  313. default (in this case 80).
  314.  
  315.  
  316. A HOST-SPECIFICATION can be any one of the following:
  317.  
  318. /                       Any protocol, Any host, Any port
  319.  
  320. [/]<host>               Any protocol, Named host, Default port
  321.  
  322. [/]<host>:<port>        Any protocol, Named host, Specified port
  323.  
  324. [/]<host>:              Any protocol, Named host, Any port
  325.  
  326. <proto>/                Named protocol, Any host, Any port
  327.  
  328. <proto>/<host>          Named protocol, Named host, Default port
  329.  
  330. <proto>/<host>:<port>   Named protocol, Named host, Specified port
  331.  
  332. <proto>/<host>:         Named protocol, Named host, Any port
  333.  
  334.  
  335. Where [] indicates an optional feature, and <> indicate a user supplied name or
  336. number.
  337.  
  338.  
  339. FILE-SPECIFICATION
  340. ------------------
  341.  
  342. Several of the sections allow a FILE-SPECIFICATION to be entered, this is a way
  343. of recognising the path part of a URL.
  344.  
  345.  
  346. A FILE-SPECIFICATION can be either of the following:
  347.  
  348. /<path>                 Any file with a path that start with the specified one.
  349.  
  350. .<file-ext>             Any file that ends with the specified file extension.
  351.  
  352.  
  353. Where <> indicate a user supplied name or number.
  354.  
  355. Note: The '/' or '.' at the start is not optional.
  356.