home *** CD-ROM | disk | FTP | other *** search
/ Dream 52 / Amiga_Dream_52.iso / Linux / Magazine / wwwoffle-2.1.tar.gz / wwwoffle-2.1 / README < prev    next >
Text File  |  1998-03-02  |  24KB  |  525 lines
  1.           WWWOFFLE - World Wide Web Offline Explorer - Version 2.1
  2.           ========================================================
  3.  
  4.  
  5. The WWWOFFLE programs simplify World Wide Web browsing from computers that use
  6. intermittent (dial-up) connections to the internet.
  7.  
  8. Description
  9. -----------
  10.  
  11. The wwwoffled program is a simple proxy server with special features for use
  12. with dial-up internet links.  This means that it is possible to browse web pages
  13. and read them without having to remain connected.
  14.  
  15.  
  16. While Online
  17.     - Caching of pages that are viewed for review later.
  18.     - Conditional fetching to only get pages that have changed.
  19.  
  20. While Offline
  21.     - The ability to follow links and mark other pages for download.
  22.     - Browser or command line interface to select pages for downloading.
  23.     - Optional info on bottom of pages showing cached date and allowing refresh.
  24.     - Works with pages containing forms.
  25.     - Can be configured to use dial-on-demand for pages that are not cached.
  26.  
  27. Automated Download
  28.     - Downloading of specified pages non-interactively.
  29.     - Can automatically fetch inlined images in pages fetched this way.
  30.     - Can automatically fetch contents of all frames on pages fetched this way.
  31.     - Automatically follows links for pages that have been moved.
  32.     - Can monitor pages at regular intervals to fetch those that have changed.
  33.     - Makes backup copies of cached pages so server errors don't overwrite them.
  34.  
  35. Provides
  36.     - Caching of web pages (http), ftp sites and finger command.
  37.     - An introductory page with information and links to the built-in pages.
  38.     - Multiple indices of pages stored in cache for easy selection.
  39.     - Interactive or command line control of online/offline status.
  40.     - User selectable purging of pages from cache based on hostname.
  41.     - Interactive or command line option to fetch pages and links recursively.
  42.     - Interactive web page to allow editing of the configuration file.
  43.  
  44. General
  45.     - Can be used with one or more external proxies based on hostname.
  46.     - Automates proxy authentication for external proxies that require it.
  47.     - Configurable to still allow use on intranets while offline.
  48.     - Can be configured to block or not cache URLs based on file type or host.
  49.     - Can censor outgoing HTTP headers to maintain user privacy.
  50.     - All options controlled using a simple configuration file.
  51.     - Optional password control for management functions.
  52.  
  53.  
  54. Configuring A Web Browser
  55. -------------------------
  56.  
  57. To use the wwwoffle programs, requires that your web browser is set up to use it
  58. as a proxy.  The proxy hostname will be 'localhost' (or the name of the host
  59. that wwwoffled is running on), and the port number will be the one that is used
  60. by wwwoffled (default 8080).
  61.  
  62. Netscape V1:
  63.         In the Options->Preferences dialog window, enter localhost as the http
  64.         and ftp proxies and 8080 as the port numbers.
  65.  
  66. Netscape V3:
  67.         In the Options->Preferences dialog window under the Proxies tab select
  68.         the Manual Proxy Configuration option and enter localhost as the http
  69.         and ftp proxies and 8080 as the port numbers.
  70.  
  71. Mosaic V2.6, Lynx, Arena, Emacs-W3:
  72.         Set the environment variables http_proxy and ftp_proxy to
  73.         http://localhost:8080/
  74.  
  75. You will also need to disable the caching that the web browser performs itself
  76. between sessions to get the best out of the program.
  77.  
  78. Depending on which browser you use and which version, it is possible to request
  79. pages to be refreshed while offline.  This is done using the 'reload' or
  80. 'refresh' button or key on the browser.  On many browsers, there are two ways of
  81. doing this, one forces the proxy to reload the page, and this is the one that
  82. will cause the page to be refreshed.
  83.  
  84. The latest browser compatibilty information is available at:
  85. http://www.gedanken.demon.co.uk/wwwoffle/version-2.0/browser.html
  86.  
  87.  
  88. Welcome Page
  89. ------------
  90.  
  91. There is a welcome page at URL 'http://localhost:8080/' that gives a very brief
  92. description of the program and has links to the index pages, interactive control
  93. page and the wwwoffle internet home pages.
  94.  
  95. The most important places to get information about wwwoffle are the wwwoffle
  96. homepage 'http://www.gedanken.demon.co.uk/wwwoffle/index.html' which has
  97. information about wwwoffle in general.  Or even better the wwwoffle version-2.0
  98. user page 'http://www.gedanken.demon.co.uk/wwwoffle/Version-2.0/user.html' which
  99. has more information about this version of wwwoffle.
  100.  
  101.  
  102. Index Of Cached Files
  103. ---------------------
  104.  
  105. To get the index of cached files, use the URL 'http://localhost:8080/index/'.
  106. There are sufficient links on each of the index pages to allow easy navigation.
  107.  
  108. The indexes provides several levels of information:
  109.    A list of the requests in the outgoing directory.
  110.    A list of the files fetched the last time that the program was online.
  111.    A list of the files that are being monitored.
  112.    A list of the most recently fetched files.
  113.    A list of all hosts for each of the protocols (http,ftp etc.).
  114.       A list of all of the files on a particular host.
  115.  
  116. These indexes can be sorted in a number of ways:
  117.    No sorting
  118.    By time of last modification (update).
  119.    By time of last access.
  120.    By date of last update with markers for each day.
  121.    Alphabetically.
  122.    By file extension.
  123.  
  124. For each of the pages that are cached there are options to delete the page,
  125. refresh it, select the interactive refresh page with the URL already filled in
  126. or add the page to the list that is monitored regularly.
  127.  
  128.  
  129. Interactive Refresh Page
  130. ------------------------
  131.  
  132. Pages can be specified by using whatever method is provided by the browser that
  133. is used or as an alternative there is an interactive refresh page.  This allows
  134. the user to enter a URL and then fetch it if it is not currently cached or
  135. refresh it if it is in the cache.  There is also the option here to recursively
  136. fetch the pages that are linked to by the page that is specified.  This
  137. recursive fetching can be limited to pages from the same host, narrowed down to
  138. links in the same directory (or subdirectory) or widened to fetch pages from any
  139. web server.  This functionality is also provided in the 'wwwoffle' command line
  140. program.
  141.  
  142.  
  143. Monitoring Web-Pages
  144. --------------------
  145.  
  146. Pages can be specified that are to be checked at regular intervals.  This can
  147. either be every time that wwwoffle is online or every few days (user
  148. specifiable).  This parameter applies to all such requests and works as follows
  149. (with <n> as the interval); If the page has not been monitored in the last <n>
  150. days then fetch it next time that you go online, or if the date it was added to
  151. the list is a multiple of <n> then fetch it next time.  This means that if you
  152. don't go online for a week then the first time you will get all of the pages,
  153. but it won't fetch all pages on the same day from then on, they are spread out
  154. according to the date they were added to the list.
  155.  
  156.  
  157. Interactive Control Page
  158. ------------------------
  159.  
  160. The behaviour and mode of operation of the wwwoffle demon can be controlled from
  161. an interactive control page at 'http://localhost:8080/control/'.  This has a
  162. number of buttons that change the mode of the proxy server.  These provide the
  163. same functionality as the 'wwwoffle' command line program.  To provide security,
  164. this page can be password protected.  There is also the facility to delete pages
  165. from the cache or from the spooled outgoing requests directory.
  166.  
  167.  
  168. Interactive Configuration File Editing Page
  169. -------------------------------------------
  170.  
  171. The interactive configuration file editing page allows the configuration file
  172. wwwoffle.conf to be edited.  This facility can be reached via the control page
  173. 'http://localhost:8080/control/'.  Each section in the configuration file has a
  174. separate dialog box that allows the contents of the section to be changed.  The
  175. comments from the configuration file are displayed in the page so that the
  176. description of the possible values in the different sections can be consulted.
  177. When the contents of the sections have been updated, the configuration file can
  178. be re-read by selecting the link at the bottom of the page.
  179.  
  180.  
  181. Deleting Requests
  182. -----------------
  183.  
  184. If no password is used for the control pages then it is possible for anybody to
  185. delete requests that are recorded.  If a password is assigned then users that
  186. know this password can delete any request (or cached file or other thing).
  187. Individual users that do not know the password can delete pages that they have
  188. requested provided that they do it immediately that the "Will Get" page appears,
  189. the "Cancel" button on here has a once-only password that will delete that
  190. request.
  191.  
  192.  
  193. Backup Copies of Pages
  194. ----------------------
  195.  
  196. When a page is fetched while online a remote server error will overwrite any
  197. existing web page.  In this case a backup copy of the page is made so that when
  198. the error message has been read while offline the backup copy is placed back
  199. into the cache.  This is automatic for all cases of files that have remote
  200. server errors (and that do not use external proxies), no user intervention is
  201. required.
  202.  
  203.  
  204. Spool Directory Layout
  205. ----------------------
  206.  
  207. In the spool directory there is a directory for each of the network protocols
  208. that are handled.  In this directory there is a directory for each hostname that
  209. has been contacted and has pages cached.  These directories have the name of the
  210. host.  In each of these directories, there is an entry for each of the pages
  211. that are cached, generated using a hashing function to give a constant length.
  212. The entry consists of two files, one prefixed with 'D' that contains the data
  213. and one prefixed with 'U' that contains the URL.
  214.  
  215. The outgoing directory is a single directory that all of the pending requests
  216. are contained in, the format is the same with two files for each, but using 'O'
  217. for the file containing the request instead of 'D' and one prefixed with 'U'
  218. that contains the URL.
  219.  
  220. The lasttime directory is a single directory that contains an entry for each of
  221. the files that were fetched the last time that the program was online.  Each
  222. entry consists of two files, one prefixed with 'D' that is an empty placeholder
  223. and one prefixed with 'U' that contains the URL.
  224.  
  225. The monitor directory is a single directory that all of the regularly monitored
  226. requests are contained in, the format is the same as the outgoing directory with
  227. two files for each, using 'O' and 'U' prefixes.
  228.  
  229. If there is a symbolic link created pointing to one of the directories then all
  230. references to the link will be replaced by references to the directory.
  231. (e.g. If foo.com is a symbolic link to foo-mirror.co.uk then web page links to
  232. http://foo.com/path will be replaced by links to http://foo-mirror.co.uk/path).
  233. This means that local mirrors can be used where possible and sites with multiple
  234. names can share a single directory.
  235.  
  236.  
  237. The Programs and Configuration File
  238. -----------------------------------
  239.  
  240. There are two programs that make up this utility, with three distinct functions.
  241.  
  242. wwwoffle  - A program to interact with and control the HTTP proxy demon.
  243.  
  244. wwwoffled - A demon process that acts as an HTTP proxy.
  245. wwwoffles - A server that actually does the fetching of the web pages.
  246.  
  247. The wwwoffles function is combined with the wwwoffled function into the
  248. wwwoffled program from version 1.1 onwards.  This is to simplify the procedure
  249. of starting servers, and allow for future improvements.
  250.  
  251. The configuration file, called wwwoffle.conf by default contains all of the
  252. parameters that are used to control the way the wwwoffled and wwwoffles
  253. functions work.
  254.  
  255.  
  256. WWWOFFLE - User control program
  257. -------------------------------
  258.  
  259. The control program (wwwoffle) is used to control the action of the demon
  260. program (wwwoffled), or to request pages that are not in the cache.
  261.  
  262. The demon program needs to know if the system is online or offline, when to
  263. fetch the pages that have been previously requested and when to purge the cache
  264. of old pages.
  265.  
  266.  
  267. The first mode of operation is for controlling the demon process.  These are the
  268. functions that are also available on the interactive control page (except kill).
  269.  
  270. wwwoffle -online        Indicates to the demon that the system is online.
  271.  
  272. wwwoffle -autodial      Indicates to the demon that the system is in autodial
  273.                         mode, this will use cached pages if they exist and use
  274.                         the network as last resort, for dial-on-demand systems.
  275.  
  276. wwwoffle -offline       Indicates to the demon that the system is offline.
  277.  
  278. wwwoffle -fetch         Commands the demon to fetch the pages that were
  279.                         requested by browsers while the system was offline.
  280.                         wwwoffle exits when the fetching is complete.
  281.                         (This requires the demon to be told it is online).
  282.  
  283. wwwoffle -config        Cause the configuration file for the demon process to be
  284.                         re-read.  The config file can also be re-read by sending
  285.                         a HUP signal to the wwwoffled process.
  286.  
  287. wwwoffle -purge         Commands the demon to purge from the cache the pages
  288.                         that are older than the number of days specified in the
  289.                         configuration file, using modification or access
  290.                         time. Or if a maximum size is specified then delete the
  291.                         oldest pages until the maximum size is not exceeded.
  292.  
  293. wwwoffle -kill          Causes the demon to exit cleanly at a convenient point.
  294.  
  295.  
  296. The second mode of operation is to specify URLs to get.
  297.  
  298. wwwoffle <URL> .. <URL> Specifies to the demon URLs that must be fetched.
  299.                         If online then it is got immediately, else the request
  300.                         is stored for a later fetch.
  301.  
  302. wwwoffle <filename> ... The specified HTML file is be read and all of the links
  303.                         in it used as if they had been specified on the command
  304.                         line.
  305.  
  306. wwwoffle -F             Force the wwwoffle server to refresh the URL.
  307.                         (Or fetch it if not cached.)
  308.  
  309. wwwoffle -i             Specifies that the URLs when fetched are to be parsed
  310.                         for images and these are also to be fetched.
  311.  
  312. wwwoffle -f             Specifies that the URLs when fetched are to be parsed
  313.                         for frames and these are also to be fetched.
  314.  
  315. wwwoffle -r[<depth>]    Specifies that the URL when fetched is to have the links
  316.                         followed and these pages also fetched (to a depth
  317.                         specified by the optional depth parameter, default 1).
  318.                         Only links on the same server are to be fetched.
  319.  
  320. wwwoffle -R[<depth>]    This is the same as the '-r' option except that all of
  321.                         the links are to be followed, even those to other
  322.                         servers.
  323.  
  324. wwwoffle -d[<depth>]    This is the same as the '-r' option except that links
  325.                         are only followed if they are in the same directory or a
  326.                         sub-directory.
  327.  
  328.  
  329. The third mode of operation is to get a URL from the cache.
  330.  
  331. wwwoffle <URL>          Specifies the URL to get.
  332.  
  333. wwwoffle -o             Get the URL and output it on the standard output.
  334.                         (Or request it if not already cached.)
  335.  
  336.  
  337. The last mode of operation is to provide help in using the other modes.
  338.  
  339. wwwoffle -h             Gives help about the command line options.
  340.  
  341.  
  342. With any of the first three modes of operation the wwwoffle server can be
  343. specified in one of three different ways.
  344.  
  345. wwwoffle -c <config-file>
  346.                         Can be used to specify the configuration file that
  347.                         contains the port numbers, server hostname (the first
  348.                         entry in the LocalHost section) and the password (if
  349.                         required for the first mode of operation).  If there is
  350.                         a password then this is the only way to specify it.
  351.  
  352. wwwoffle -p <host>[:<port>]
  353.                         Can be used to specify the hostname and port number that
  354.                         the demon program listens to for control messages (first
  355.                         mode) or proxy connections (second and third modes).
  356.  
  357. WWWOFFLE_PROXY          An environment variable that can be used to specify
  358.                         either the argument to the -c option (must be the full
  359.                         pathname) or the argument to the -p option.  (In this
  360.                         case two ports can be specified, the first for the proxy
  361.                         connection, the second for the control connection
  362.                         e.g. 'localhost:8080:8081' or 'localhost:8080'.)
  363.  
  364.  
  365. WWWOFFLED - Demon program
  366. -------------------------
  367.  
  368. The demon program (wwwoffled) runs as an HTTP proxy and also accepts connections
  369. from the control program (wwwoffle).
  370.  
  371. The demon program needs to maintain the current state of the system, online or
  372. offline, as well as the other parameters in the configuration file.
  373.  
  374. As HTTP proxy requests come in, the program forks a copy of itself (the
  375. wwwoffles function) to handle the requests.  The server program can also be
  376. forked in response to the wwwoffle program requesting pages to be fetched.
  377.  
  378.  
  379. wwwoffled -c <config-file>      Starts the demon with the named configuration
  380.                                 file.
  381.  
  382. wwwoffled -d [level]            Starts the demon in debugging mode, i.e it does
  383.                                 not detach from the terminal and uses standard
  384.                                 error for the log messages.  The optional
  385.                                 numeric level (0 for none to 5 for all)
  386.                                 specifies the level of error messages for
  387.                                 standard error, if not specified then use
  388.                                 log-level from the config file.
  389.  
  390. wwwoffled -h                    Gives help about the command line options.
  391.  
  392.  
  393. There are a number of error and informational messages that are generated by the
  394. program as it runs.  By default (in the config file) these go to syslog, by
  395. using the -d flag the demon does not detach from the terminal and the errors are
  396. also on standard error.
  397.  
  398. By using the run-uid and run-gid options in the config file, it is possible to
  399. change the user id and group id that the program runs as.  This will require
  400. that the program is started by root and that the specified user has read/write
  401. access to the spool directory.
  402.  
  403.  
  404. WWWOFFLES - Server program
  405. --------------------------
  406.  
  407. The server (wwwoffles) starts by being forked from the demon (wwwoffled) in one
  408. of three different modes.
  409.  
  410. Real  - When the system is online and acting as a proxy for a browser.
  411.         All requests for web pages are handled by forking a new server which
  412.         will connect to the remote host and fetch the page.  This page is then
  413.         stored in the cache as well as being returned to the browser.  If the
  414.         page is already in the cache then the remote server is asked for a newer
  415.         page if one exists, else the cache one is used.
  416.  
  417. SpoolOrReal - When the system is in autodial mode and we have not decided if we
  418.         will go for Spool or Real mode.  Select Spool mode if already cached and
  419.         Real mode otherwise as a last resort.
  420.  
  421. Fetch - When the system is online and fetching pages that have been requested.
  422.         All web page requests in the outgoing directory are fetched by the
  423.         server connecting to the remote host to get the page.  This page is then
  424.         stored in the cache, there is no browser active.  If the page has been
  425.         moved then the link is followed and that one fetched.
  426.  
  427. Spool - When the system is offline and acting as a proxy for a browser.
  428.         All requests for web pages are handled by forking a server that will
  429.         either return a cached page or store the request.  If the page is
  430.         cached, it is returned to the browser, else a dummy page is returned
  431.         (and stored in the cache), and the outgoing request is stored.
  432.         If the cached page refers to a page that failed to be downloaded then it
  433.         will be deleted from the cache.
  434.  
  435. Depending on the existence of files in the spool and other conditions, the mode
  436. can be changed to one of several other modes.
  437.  
  438. RealNoCache - For requests for pages on the server machine or those specified
  439.         not to be cached in the configuration file.
  440.  
  441. RealRefresh - Used by the refresh button on the index or the wwwoffle program
  442.         to refetch a page while the system is online.
  443.  
  444. SpoolGet - Used when the page does not exist in the cache so a request needs to
  445.         be stored for it in the outgoing directory.
  446.  
  447. SpoolWillGet - Used when the page is not in the cache but a request for it is in
  448.         the outgoing directory already.
  449.  
  450. SpoolRefresh - Used when the refresh button on the index or the wwwoffle program
  451.         are used, the existing spooled page (if there is one) is not
  452.         overwritten, but a request is stored.
  453.  
  454. SpoolPragma - Used when the browser requests the cache to refresh the page
  455.         using the 'Pragma: no-cache' header, the existing spooled page (if there
  456.         is one) is not overwritten, but a request is stored.
  457.  
  458.  
  459. WWWOFFLE-TOOLS - Cache maintenance program
  460. ------------------------------------------
  461.  
  462. This is a quick hack program that I wrote to allow you to list the contents of
  463. the cache or move files around in it.
  464.  
  465. All of the programs should be invoked from the spool directory.
  466.  
  467. wwwoffle-rm     - Delete the URL that is specified on the command line.
  468.                   To delete all URLs from a host it is easier to use
  469.                   'rm -r http/foo' than use this.
  470.  
  471. wwwoffle-mv     - To rename a host directory in the spool to another name.
  472.                   Because the URL is encoded in the filename just renaming the
  473.                   directory will not work.  Instead of 'mv http/foo http/bar'
  474.                   use 'wwwoffle-mv http/foo http/bar'.
  475.  
  476. wwwoffle-ls     - To list the files in the directory in the style of 'ls -l'.
  477.                   For example use 'wwwoffle-ls http/foo' to list the URLs cached
  478.                   in the directory http/foo.
  479.  
  480. These are basically hacks that I needed and should not be considered as fully
  481. featured and fully debugged programs.
  482.  
  483.  
  484. Author and Copyright
  485. --------------------
  486.  
  487. The two programs wwwoffle and wwwoffled were written by Andrew M. Bishop in
  488. 1996,97,98 and are copyright Andrew M. Bishop 1996,97,98.
  489.  
  490. The program update-cache and the programs known as wwwoffle-tools were written
  491. by Andrew M. Bishop in 1997,98 and are copyright Andrew M. Bishop 1997,98.
  492.  
  493. They can be freely distributed according to the terms of the GNU General Public
  494. License (see the file `COPYING').
  495.  
  496. If you wish to submit bug reports or other comments about the programs then
  497. email the author amb@gedanken.demon.co.uk and put wwwoffle in the subject line.
  498.  
  499.  
  500. With Source Code Contributions From
  501. - - - - - - - - - - - - - - - - - -
  502.  
  503. Yannick Versley <sa6z225@public.uni-hamburg.de>
  504.         Initial syslog code (much rewritten before inclusion).
  505.  
  506. Axel Rasmus Wienberg <2wienbe@informatik.uni-hamburg.de>
  507.         Code to run wwwoffled as a specified uid/gid.
  508.  
  509. Andreas Dietrich <quasi@baccus.franken.de>
  510.         Code to detach the program from the terminal like a *real* demon.
  511.  
  512. Ullrich von Bassewitz <uz@wuschel.ibb.schwaben.com>
  513.         Better handling of signals.
  514.         Optimisation of the file handling in the outgoing directory.
  515.         The log-level, max-servers and max-fetch-servers config options.
  516.  
  517. Tilman Bohn <tb@bohn.isdn.uni-heidelberg.de>
  518.         Autodial mode.
  519.  
  520. And Other Useful Contributions From
  521. - - - - - - - - - - - - - - - - - -
  522.  
  523. Too many people to mention - (everybody that e-mailed me).
  524.         Suggestions and bug reports.
  525.