home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / slurp108.zip / readme < prev    next >
Text File  |  1995-01-11  |  9KB  |  222 lines
  1.                 SLURP - An advanced passive NNTP client
  2.                 =======================================
  3.  
  4.                              Version 1.08
  5.                       Written by Stephen Hebditch
  6.                      (C) 1992/3 TQM Communications
  7.                                     
  8.                                  ------
  9.  
  10. Slurp is an advanced passive NNTP client for UNIX. It will connect to a
  11. remote NNTP server and retrieve articles in a specified set of Usenet
  12. newsgroups that have arrived after a particular date (typically the
  13. last time it was invoked) for processing by your local news system or
  14. forwarding on via UUCP to another news system. It replaces nntpxfer
  15. from the NNTP 1.5.11 reference implementation and nntpget from the INN
  16. distribution.
  17.  
  18.  
  19. The Feature List.
  20.  
  21. - No restriction on the number of newsgroups that can be retrieved in a
  22.   session. The client does a series of NEWNEWS requests if necessary to
  23.   build up a list of articles which need to be retrieved from the
  24.   server.
  25.  
  26. - Compatible with C News and INN.
  27.  
  28. - No lost articles due to unsynchronised clocks. By default, the time
  29.   for the next NEWNEWS is set by a call to the tcp time service on the
  30.   remote machine. This fixes a problem in nntpxfer and nntpget where
  31.   articles can be missed if the clock on the server is behind that on
  32.   the client.
  33.  
  34. - Faster article throughput. If configured to do so, slurp stacks up
  35.   the next article request before the current article is received,
  36.   decreasing the total article transfer time by around 30%. Unlike
  37.   nntpget, article batches can be written to the rnews spool directory
  38.   for processing with 'rnews -U' later, rather than being offered to
  39.   innd in turn. When used with C News, batches are written to the
  40.   in.coming directory. This provides a big speedup over nntpxfer which
  41.   created a new pipe to rnews for each article, lowering the transfer
  42.   speed and increasing the load on the client machine. These speed
  43.   improvements are of most use to the growing number of people
  44.   retrieving news over a dialup SLIP/PPP connection.
  45.  
  46. - Error recovery. In the event of an error occurring while articles are
  47.   being fetched, the message IDs of unretrieved articles are dumped to
  48.   a file. The next session can then retrieve the remaining articles
  49.   without having to restart from the previous start time.
  50.  
  51. - Easy configuration.
  52.  
  53.   slurp.sys defines which groups you wish to get from which server in a
  54.   similar way to the normal C News sys file, e.g.
  55.  
  56.     news.demon.co.uk:demon.*,!demon.msdos.announce,uk.*,\
  57.     !uk.net.maps/world,uk
  58.  
  59.   slurp.<hostname> contains the time to be used for the NEWNEWS request
  60.   at each server.
  61.  
  62.   The newsgroups list, start time and distributions can be overridden
  63.   on the command line. There are also settings to enable debugging
  64.   output, prevent writing the time for the next NEWNEWS to
  65.   slurp.<hostname>, issue a 'MODE READER' command to switch innd to
  66.   nnrpd, not dump unfetched message IDs in the event of an error, and
  67.   use the local time for the next NEWNEWS rather than the time at the
  68.   server.
  69.  
  70. - Support for the NNTP simple authorisation protocol.
  71.  
  72. - Logging to syslog of the number of new, missing and duplicate
  73.   articles at the end of a session plus, if required, the transfer
  74.   speed of the article fetching stage.
  75.  
  76. - Independent of the NNTP 1.5.11 code.
  77.  
  78. Slurp was written in ANSI C under Dell's SVR4/386, but ports easily to
  79. SunOs 4.x, Linux, BSDI BSD/386, HPUX, SCO, ISC, NeXT, Ultrix and most
  80. other recent versions of UNIX.
  81.  
  82.  
  83.  
  84. CONTENTS
  85. --------
  86.  
  87. In this archive you should have the following files:-
  88.  
  89. HISTORY        How we got from there to here.
  90. Makefile    The Makefile (yes, really!)
  91. README        What you're reading now
  92. articles.c    Routines for reading articles and batching them up
  93. conf.h        Compilation configuration file
  94. fakesyslog.c    Fake version of syslog for those without
  95. fakesyslog.h    Definitions needed for the above
  96. history.c    Routines to open and interrogate the news history file
  97. misc.c        Miscellaneous routines
  98. newnews.c    Routines to retrieve new message ids from the server
  99. nntp.h        Definitions of nntp response codes
  100. slurp.1        Slurp manual page
  101. slurp.c        Main program
  102. slurp.h        Definitions used by everything
  103. slurp.sys    Configuration file for groups to take from a server
  104. sockets.c    Server interface routines
  105. space.c        Determines space available on news disk
  106. time.c        Retrieves current time at remote server
  107.  
  108.  
  109.  
  110. COMPILATION AND INSTALLATION
  111. ----------------------------
  112.  
  113. 1. Edit conf.h to reflect your reflect your local configuration. This
  114. file contains full details about each item that you may need to change.
  115.  
  116. 2. Edit Makefile. If you have not installed dbz.h in /usr/include then
  117. you will need to add -Ipathname to CFLAGS so that the compiler does a
  118. search of the directory where it can be found. LIBS will need to
  119. contain entries to pick up the dbz library and possibly the sockets
  120. library depending on your system. If you don't have syslog then you
  121. will need to uncomment the FAKESRC and FAKEOBJ lines.
  122.  
  123. 3. Type 'make' and hopefully you will get the slurp executable.
  124.  
  125. 4. Copy slurp to wherever it is that you store your news binaries.
  126.  
  127. 5. Copy slurp.sys to whichever location you selected for it in conf.h.
  128.  
  129. 6. Copy the manual page to wherever you keep your manual pages.
  130.  
  131.  
  132.  
  133. QUICK START
  134. -----------
  135.  
  136. The slurp manual page contains full details on how to operate slurp. As
  137. a quick start all you need to do is:-
  138.  
  139. 1. Edit slurp.sys to set the hostname of the server you wish to connect
  140. to for retrieving articles and the groups you wish to receive.
  141.  
  142. 2. Edit slurp.<hostname> and enter a single line containing the time a
  143. couple of days previously, say, in 'YYMMDD HHMMSS' format.
  144.  
  145. 3. Run 'slurp <hostname>' and sit back while the articles flood into
  146. your local news system.
  147.  
  148. If you are running C News, then the next time that newsrun is invoked
  149. from cron, the articles in the in.coming directory will be added to the
  150. news system.
  151.  
  152. If you are running INN and do not have RNEWS defined, then it will be
  153. necessary to run 'rnews -U' to have the files from the rnews spool
  154. directory processed by the news system. If RNEWS is defined then they
  155. will be piped to innd as they arrive - doing this will lower the speed
  156. at which articles are transferred from the remote server.
  157.  
  158. Patches for the NNTP 1.5.11 server are available on request which
  159. implement caching of article locations during a NEWNEWS so that a
  160. further access of the history file is not required when an article is
  161. retrieved. I hope to have an equivalent patch available for INN soon.
  162.  
  163.  
  164.  
  165. CONDITIONS OF USE
  166. -----------------
  167.  
  168. The Slurp package and individual code as detailed is Copyright 1992/3
  169. TQM Communications, BCM Box 225, London, WC1N 3XX. All rights reserved.
  170.  
  171. This package may be freely distributed provided the following
  172. conditions are met. The files detailed in the contents section of this
  173. file must all be included. No charge, other than basic online charges
  174. or media costs, may be levied. You are permitted to make alterations to
  175. the code for your own personal use, but please feed back any bug fixes
  176. or enhancements to us so they may be included in any future releases.
  177.  
  178.  
  179.  
  180. DISCLAIMER
  181. ----------
  182.  
  183. TQM Communications makes no warranty of any kind in respect to this
  184. documentation and the software described. The user assumes any risk as
  185. to the quality and performance of this product. In no event will TQM
  186. Communications be liable for direct, indirect, incidental or
  187. consequential damages arising from any defect in the performance and
  188. use of this product.
  189.  
  190. All trademarks acknowledged.
  191.  
  192.  
  193.  
  194. ACKNOWLEDGEMENTS
  195. ----------------
  196.  
  197. The original inspiration for slurp came from nntpxfer, written by Brian
  198. Kantor. The article batching code is inspired by batch.c in the NNTP
  199. 1.5.11 package, written by Stan Barber and 'based on work by Henry
  200. Spencer and Geoff Collyer'. The fakesyslog code is taken from the NNTP
  201. 1.5.11 package where it is credited to John Robert LoVerso and Paul
  202. McKenny. The space code to determine whether there is enough space on
  203. the news disk was originally taken from the NNTP 1.5.11 package where
  204. it is credited to Stan Barber, Tad Guy, Chris Jepeway and Tom Lane.
  205. Regular expression expansion courtesy of Nick Lai. Network knowledge
  206. thanks to W. Richard Stevens, author of the most readable UNIX books
  207. around. For bug fixing, porting and enhancement ideas, thanks go to Tim
  208. Rylance, Pete Bentley, Stefan Schwarz, David Clunie, David Boyce,
  209. Barrie Spence and Philip Shearer.
  210.  
  211.  
  212.  
  213. CONTACT INFORMATION
  214. -------------------
  215.  
  216. All comments, bug reports, bug fixes, etc. should be sent to
  217. steveh@orbital.demon.co.uk. I'm also available for consultancy work if
  218. you want help in getting news and mail working.
  219.  
  220.  
  221. ---- END OF DOCUMENTATION
  222.