home *** CD-ROM | disk | FTP | other *** search
/ Unix System Administration Handbook 1997 October / usah_oct97.iso / news / nn.tar / nn-6.5.1 / olddocs / doc / NNTP < prev    next >
Text File  |  1995-04-29  |  15KB  |  369 lines
  1.                  NNTP SUPPORT
  2.                  ------------
  3.  
  4. This file describes the NNTP support available in nn release 6.5.  The
  5. NNTP support was implemented by Rene' Seindal, seindal@diku.dk.
  6.  
  7.  
  8.                 PREREQUISITES
  9.                 -------------
  10.  
  11. First of all, you need read-access to an NNTP-server, and if you want
  12. to post, the server must allow that.
  13.  
  14. If you have news on one of your systems, and want to run an NNTP
  15. server on that system to feed other local systems, you need to get and
  16. install the nntp-1.5 distribution with at least patches 1-3 (I think
  17. patch 8 is the latest).  It is available from several ftp-sites in the
  18. USA.  It is also available on freja.diku.dk (ip 129.142.96.1).
  19.  
  20. However, just to run nn on you local system with or without NNTP, you
  21. don't need anything besides the nn 6.5 distribution!!
  22.  
  23. The necessary modules to access a remote NNTP server is an integrated
  24. part of nn, so if you specify to use NNTP, the necessary code is
  25. automatically included.
  26.  
  27. A recent version of the `mini-inews' program which is required to post
  28. articles via an NNTP server is also included for your convenience.
  29. See the INEWS section below.
  30.  
  31.                  HOW IT WORKS
  32.                  ------------
  33.  
  34. NNTP is supported both in nn and nnmaster.  When NNTP is used, the
  35. database with the header information used by nn is still maintained on
  36. the local system (because NNTP does not know about the nn database
  37. (yet?)).
  38.  
  39. When the master is set up to use NNTP, it will connect to the NNTP-
  40. server in each iteration of the collection (the interval set with -r),
  41. get a copy of the active file, and incorporate the new articles into the
  42. database.  To do this, the master will temporarily transfer one article
  43. at a time from the NNTP-server to the local system.
  44.  
  45. When the articles are read with nn, it will use the local database to
  46. present the menus, and fetch the articles from the NNTP-server as they
  47. are requested by the user.  It will connect to the NNTP server the first
  48. time it is necessary to fetch an article.
  49.  
  50. Neither nnmaster, nor nn will use NNTP if they run on the NNTP-server
  51. itself (they will directly access the news files).
  52.  
  53. Both nn and nnmaster access the server in reading mode.  The master and
  54. all client MUST use the same server at all times, since the local
  55. database contains article numbers, that are only unique for each
  56. NNTP-server.
  57.  
  58.  
  59.              SHARING THE DATABASE
  60.              --------------------
  61.  
  62. You must also decide whether you want to share the database between your
  63. local news clients, and how you are going to do it.
  64.  
  65. The database will take up some disk space, normally about 1Mb per 10.000
  66. articles.  There are several ways to manage this space.
  67.  
  68. This simplest solution, is to let each client run it own master, i.e.,
  69. have its own database.  This means, of course, no sharing.
  70.  
  71. Alternatively, one host can run the master, and distribute the database
  72. to the others via e.g., rdist.  This doesn't save disk space, but saves
  73. load on the NNTP-server.
  74.  
  75. Last, the database can be shared with NFS/RFS (see the description of
  76. NETWORK_DATABASE in the config.h file).
  77.  
  78. The possibility of making a `nndb-server' stands open.  It could be
  79. realized either as a separate server, running under inetd, or it could
  80. be incorporated into nntpd.  It has not been implemented, but might be
  81. part of a future release (any volunteers?).
  82.  
  83.  
  84.                 CONFIGURATION
  85.                 -------------
  86.  
  87. To use NNTP in nn, you must edit the relevant parts of config.h:
  88.  
  89. NNTP
  90.     You enable the use of NNTP by defining the macro NNTP.
  91.  
  92. NNTP_SERVER
  93.     Both the master and the clients will look up their NNTP-server
  94.     in the file given by the macro NNTP_SERVER.  If the name is not
  95.     an absolute path name, it is taken to be relative to
  96.     LIB_DIRECTORY.
  97.  
  98.     The format of the file is compatible with the one used in
  99.     clientlib.c in the nntp-1.5 distribution, i.e., the first
  100.     non-blank line, not starting with '#' is taken to be the name of
  101.     the NNTP-server.  This file MUST be present, and must contain a
  102.     valid host name.
  103.  
  104. NNTP_POST
  105.     If you use the NNTP based inews (part on the NNTP distribution)
  106.     and you have hosts that are not allowed to post to the NNTP
  107.     server, you should defined this.  It will make nn check at
  108.     connect time whether the NNTP server allows postings, and reject
  109.     all attempts to post, if the server disallows posting.  If you
  110.     do not define this, users will be allowed to post by nn, but the
  111.     posting will eventually fail.
  112.  
  113.     Again, this parameter is only relevant, if you use the NNTP
  114.     based inews, and have hosts that are not allowed to post.
  115.  
  116. NNTP_MINI_INEWS_HEADER
  117.     According to RFC 977, the mini-inews that comes with nntp
  118.     requires that the articles it receives contain a complete
  119.     header including Message-ID, Date, and Path fields (which the
  120.     normal inews generates itself).  I consider this to be a bug
  121.     in the RFC, and maybe some (future?) versions of mini-inews
  122.     will provide these fields.  However, if you use mini-inews for
  123.     postings and your version of mini-inews does not generate
  124.     these headers, you should define NNTP_MINI_INEWS_HEADER in
  125.     config.h.  Notice that the Message-ID and Path may be less
  126.     than perfect (but the Message-ID should be unique)!
  127.  
  128.  
  129. NEWS_LIB_DIRECTORY & INEWS
  130.     If either is defined, they specify the destination of the
  131.     mini-inews program when installed below with INEWS being used
  132.     if both are defined.  If neither is defined, it will be
  133.     installed in /usr/lib/news/inews.
  134.  
  135. EXCELAN
  136.     You can define this symbol if your tcp/ip is based on the
  137.     EXCELAN implementation (no netdb.h, no getservbyname(), no
  138.     gethostbyname()).  (This belongs in the s- file!)
  139.     You will (probably) also need to add -lsocket to NNTP_EXTRA_LIB.
  140.     Normally it will use port 119 for nntp, but this can be modified
  141.     through "#define IPPORT_NNTP 1150" (or similar) in the init file.
  142.  
  143. NO_BZERO
  144. NO_RENAME
  145.     You can define these symbols if your system doesn't provide
  146.     the bzero() and/or rename() functions (these #define:s belong
  147.     in the s- file).
  148.  
  149. NNTP_EXTRA_LIB
  150.     Here you can specify libraries and loader flags which are only
  151.     needed when compiled with NNTP.  The normal EXTRA_LIB is still
  152.     used.
  153.     
  154.         
  155.                 TUNING
  156.                 ------
  157.  
  158. Both the server and each client maintains a cache of recently accessed
  159. articles, to minimize communication with the server (mainly to avoid
  160. fetching large digests continuously).  The master needs the cache when
  161. it splits digests, and the clients need it, because nn has a tendency to
  162. reopen the articles several times.
  163.  
  164. The master's cache is kept in LIB_DIRECTORY, and each client's cache are
  165. kept in the users .nn directory.  The constant NNTPCACHE (defined in
  166. nntp.c but can be redefined in config.h) defines the size of the cache,
  167. whose optimal size depends on the amount of news kept on line on the
  168. NNTP-server.  Values of 5-10 gives reasonable results.  The effect is
  169. most striking when reading digested news.
  170.  
  171. The location and size of the cache can also be changed on a per-user
  172. basis via the related nntp- variables (see nn.1).
  173.  
  174.  
  175.                  INSTALLATION
  176.                  ------------
  177.  
  178. Making and installing nn using NNTP does not differ from a non-NNTP nn
  179. installation, except for the differences in the configuration and the
  180. need to specify the NNTP server in the NNTP_SERVER file.
  181.  
  182. Notice however, that the NNTP_SERVER file must be properly initialized
  183. before doing the 'make initdb'.
  184.  
  185. If something goes wrong in the initialization of the database, you will
  186. have to run 'nnmaster -I' again by hand.
  187.  
  188.  
  189.                 INEWS
  190.                 -----
  191.  
  192. If you want to post news via the NNTP server, you will need to run a
  193. program named `(mini-)inews' which is included in the normal NNTP
  194. distribution.  However, since this is the only part of the NNTP you
  195. need to run nn, a recent version (1.5.7) of the mini-inews program is
  196. included with nn in the inews/ directory.
  197.  
  198. If you already have installed and maintain mini-inews on your system,
  199. you should not use the version that comes with nn - it would just be
  200. extra unnecessary work.
  201.  
  202. However, if you don't run mini-inews already, using the version that
  203. comes with nn will be somewhat simpler to configure, because it takes
  204. advantage of the definitions you have already made for nn in config.h.
  205.  
  206. Thanks to Steve Simmons who contributed the simplified inews
  207. configuration (which I took the freedom to simplify even further).
  208.  
  209. To configure and install mini-inews, all you should need to do is
  210. (everything must be done with inews/ as current working directory):
  211.  
  212.     $ cd inews
  213.     $ edit conf.h    -- modify as described in the file
  214.     $ make
  215.  
  216. If things work, type:
  217.  
  218.     $ su
  219.     # make install
  220.  
  221. As far as I know, NNTP_MINI_INEWS_HEADER needs to be defined in
  222. nn's config.h for nn to work with this mini-inews version.
  223.  
  224. See the files inews/README.NN and inews/README for further information.
  225.  
  226.  
  227.                 ERROR HANDLING
  228.                 --------------
  229.  
  230. The handling of errors have been improved since the initial release.
  231.  
  232. The master will handle most errors by closing the connection, and
  233. returning to the main loop.  All errors in the master are logged, with
  234. a code of `N,' so they can be inspected with the `n' command in
  235. nnadmin's Log menu.
  236.  
  237. A few errors are considere fatal. If any of these occur operation will
  238. be discontinued.  These errors are such as failure to find the NNTP
  239. server, failure to find the NNTP service, and responses from the NNTP
  240. server in the 500 range (ill-formed requests, access denied, ...)
  241.  
  242. NNTP server timeouts are handled specially.  If the NNTP server times
  243. out, both nn and the master will attempt to restart it (by connecting
  244. again).  This shouldn't happen in the master (which won't leave sockets
  245. idle for that long), but it can easily happen in nn, if it is left
  246. suspended for too long.  If the server responds with code 400 (Service
  247. discontinued), a reconnect is also tried.
  248.  
  249.  
  250.                    PROBLEMS
  251.                    --------
  252.  
  253. I am not certain what should happen if the server sends back responses
  254. in the 1xx range.  I do not know whether a NNTP server is allowed to
  255. return one of these responses on its own initiative.  If it is, nn
  256. should probably ignore (or display) the messages.  Currently, nothing is
  257. done to treat these responses in any way.
  258.  
  259. I have seen a strange thing happen to the master, which I have not been
  260. able to reproduce.  The master ran on a Sun-4 running SunOS 4.0, and the
  261. NNTP server was a VAX 785 running MORE/bsd.  The NNTP software was
  262. version 1.5.3.  The master was stuck in a read from the NNTP server.  A
  263. netstat on the Sun show an established connection to nntpd on the Vax,
  264. but a netstat on the Vasx did not show any NNTP connections.  There was
  265. no nntpd running, and no messages on the console indicating any
  266. failures.
  267.  
  268. [ It is now known that this problem is related to the socket not
  269.   having the KEEP ALIVE flag set, but I have not got the necessary
  270.   patches to fix it,   ++Kim ]
  271.  
  272.  
  273.               SPONTANEOUS NNTP ERROR 502
  274.               --------------------------
  275.  
  276. Sometimes nn or nnmaster may stop with the following message:
  277.  
  278.     NNTP 502 You only have permission to transfer, sorry. 
  279.  
  280. This particular case is probably the result of the NNTP server trying to
  281. turn your IP address into a fully qualified domain name (FQDN) so it can
  282. look you up in its access file.
  283.  
  284. The NNTP server probably uses the domain name server (DNS) to map IP
  285. addresses into FQDNs.  If the local DNS doesn't already know the answer, it
  286. has to go out over the network to find it.  This can take a few seconds, and
  287. the library routine that does all this for the NNTP server might time out
  288. before the answer gets back to it.  If this happens, the NNTP server doesn't
  289. know your FQDN, so it gives you the default access specified in the server's
  290. nntp_access file, which is usually "xfer" (article transfer only).
  291.  
  292. In the time it takes for you to run nn again the DNS usuallu has its answer
  293. back, so things usually work the second time.  
  294.  
  295. One way to work around this problem is to specify the IP address of the
  296. client in the nntp server's access file; then it is not necessary to lookup
  297. the FQDN.
  298.  
  299. Thanks to Tim Ramsey and Nick Sayer for this information.
  300.  
  301.  
  302.               DEBUGGING NNTP CONNECTIONS
  303.               --------------------------
  304.  
  305. If you want to debug the nntp connection, you can run the nnmaster
  306. with the option -D2 (or -D3 which also turns on the normal -D verbose
  307. output).  In the nn client, you can turn on the nntp-debug variable in
  308. the init file.
  309.  
  310. The debug output from nnmaster will be placed in $TMP/nnmaster.log
  311. while the output in the client will appear on the message line.
  312.  
  313.  
  314.         POSSIBLE EXTENTIONS TO THE NNTP SERVER
  315.         --------------------------------------
  316.  
  317. The new expire method used in release 6.5 is very efficient on local
  318. systems, because it will just read the spool directories to get a list
  319. of available articles in each group.
  320.  
  321. However, with nntp, the only way I know of to get a list of available
  322. articles in a group with nntp is the XHDR request.  However, this will
  323. open every article in the group to extract the desired field, but the
  324. only thing I am interested in is the article number itself.
  325.  
  326. So I suggest to add a LISTGROUP request to the NNTP server to return
  327. the equivalent of
  328.     ls $GROUPDIR | sed -n '/^[0-9][0-9]*$/p'
  329. (in any order - nnmaster will sort the list itself).
  330.  
  331. Currently nnmaster will test whether this request works before using
  332. the XHDR request, so no changes to nnmaster will be required to take
  333. advantage of such a fix.
  334.  
  335.  
  336. Another possible performance increase would be if there was a request
  337. to get the current modification time of the ACTIVE file.  This is the
  338. check nnmaster will do to see if there might be work to do on a local
  339. system, but with NNTP it has to read the active file from the server
  340. and compare it to a local copy to determine whether there is work to
  341. do.  A simple ACTIVESTAT request returning the active file's age and
  342. size would fix this.
  343.  
  344. Currently nnmaster is not prepared to use such a request, but it would
  345. be easy to add.
  346.  
  347.  
  348.                  ALTERNATIVES
  349.                  ------------
  350.  
  351. Alternative implementations can be conceived, especially in the master.
  352. The master normally collects articles by rereading the active file,
  353. looking for changed article numbers.  For each group with new articles,
  354. it reads the new articles and adds them to the database.  This scheme
  355. has been kept in the NNTP-based master, to keep the changes at a
  356. minimum.
  357.  
  358. An alternative solution could be to use NEWNEWS to get a list of new
  359. articles since last collect, and fetch each article in sequence.  The
  360. newsgroups and article numbers within each group could then be found in
  361. the Xref: field.  This would probably improve efficiency, since the
  362. master would then generate fewer failing requests (for non-existent
  363. articles), and it would only read cross-posted articles once.  This
  364. solution would, however, require some surgery on the current structure
  365. of the masters main loop.
  366.  
  367. Suggestions and improvements are very much welcome.  Send your ideas or
  368. contributions to nn-bugs@dkuug.dk.
  369.