                        TABLE OF CONTENTS

- OVERVIEW
- FILES AND DIRECTORIES
- INSTALLATION
- UPDATE FROM VERSIONS < 1.6
- TROUBLESHOOTING


			    OVERVIEW

Leafnode is a USENET software package designed for small sites, with a
few tens of readers and only a slow link to the net.

It consists of several programs, three essential ones and several add-ons.

 - Leafnode is the NNTP server.  It talks to the normal news clients,
   and stores readership data.

 - Fetch is the NNTP news-gatherer.  It looks at the readership data
   Leafnode stores, and selects what groups to pull news from.

 - Texpire is responsible for deleting old and uninteresting news.  It
   deletes all discussion threads that are old and not recently read.

These are the add-ons:

 - Applyfilter lets you delete articles from your local news spool
   which fit a certain pattern.

 - Checkgroups inserts the titles of newsgroups into the newsgroup
   database.

 - Newsq shows which news are waiting to be transferred to your upstream
   server.

Only groups that someone has been reading in the past week are fetched
from the upstream NNTP server.  When someone stops reading a group,
fetch will stop reading that group a week later (this is the default
which can be configured), and when someone starts reading a group, fetch
will grab all the articles it can in that group the next time it runs.

Here are Leafnode's distinguishing features:

 - Uses very little disk space and bandwidth compared to other servers.
   Obviously truer for 3-user sites than for 30-user, and probably wholly
   untrue for 300-user sites.

 - Easy configuration and maintenance.  Leafnode tries very hard to
   recover automatically from error situations.

As most programs, Leafnode has also weaknesses:

 - Loses news.  In just about any error situation, leafnode tries to
   fix its problems by deleting the offending article.

 - Scales very badly.

The current version of leafnode is available from
	http://wpxx02.toxi.uni-wuerzburg.de/~krasel/leafnode.html

There is also a leafnode mailing list. Send mail to
	leafnode-list@wpxx02.toxi.uni-wuerzburg.de
with "Subscribe" in the Subject: to subscribe.

                      FILES AND DIRECTORIES

Leafnode puts its files in three separate directories: The spool
directory, the library directory, and the binaries directory.

In the spool directory you find the stored news, the active file and
some other short-lived configuration file. It defaults to /var/spool/news
and can be changed at compilation time. There are some special
directories here; see the leafnode(8) man page.

The library directory contains long-lived configuration files. It
defaults to /etc/leafnode and be changed at compilation time.

The binaries directory, /usr/local/sbin by default, contains the three
executable programs, texpire, fetch and leafnode. Again, this
directory can be changed at compilation time.



                           INSTALLATION

Read the file INSTALL.



                      UPDATE FROM VERSIONS < 1.6

There are some major changes from leafnode versions previous to 1.6.
These include leafnode-1.6alpha.

1) The format of the groupinfo file has changed.

2) Some files (including the groupinfo file) have moved from /usr/lib/leafnode/
   to /var/spool/news/leaf.node/

3) The article information for the main upstream server has been moved
   from groupinfo into a separate file.

To update correctly, do a "make update" as root after you have
successfully completed "make install". See the file INSTALL for more
details.



                          TROUBLESHOOTING

Here you find answers to some commonly encountered problems.

Problem: I want to change my upstream server.
Solution: I have never done this myself, but leafnode should have no
	  problems with it. Assuming that your new server is called
	  "new.upstream.server" and your old server "old.upstream.server",
	  I recommend following the procedure outlined below:
	  1) Add the following lines to your config file
		supplement = new.upstream.server
		maxfetch = 100
	     If you have already another maxfetch defined, reduce it
	     temporarily.
	  2) Run fetch.
	  3) Replace
		server = old.upstream.server
	     with
		server = new.upstream.server
	     and delete the two lines that were introduced in step 1).
	  That's it.

Problem: fetch hangs after writing something like "wrote
	 /var/spool/news/de/comp/os/linux/misc/.overview"
Solution: This is not a problem at all, but fetch's normal behaviour.
	  After getting all articles and storing them on your disk,
	  fetch finishes after starting a sub-process which does some
	  local cleanup in the background. This process is not controlled
	  by the shell anymore but still writes to the terminal. The shell
	  does not realize when this process ends and therefore cannot
	  produce a prompt.

Problem: I cannot connect to my newsserver.
Solution: Most likely your setup is incorrect. This can have several
	  reasons.
	  1) inetd is not running. Check with "ps axu | grep inetd"
	  2) inetd is running, but the entry in /etc/inetd.conf is
	     incorrect. Check the logfiles, usually something like
	     /var/log/messages or /var/log/syslog , for inetd error
	     messages.
	  3) inetd is running and the entry in /etc/inetd.conf is
	     correct, but the tcpd denies access to the server (in
	     /var/log/messages you will find something like
	     "leafnode: connection refused from ..."). Check the
	     entries in /etc/hosts.allow and /etc/hosts.deny. An
	     example for a correct entry is given in the INSTALL
	     file.
	  4) Another badly configured news server is already running
	     on your machine. Switch it off.
	  You can test your setup by opening a telnet connection to your
	  newsserver. This is done by doing "telnet localhost 119".
	  You should get back something like
		200 Leafnode NNTP Daemon, version xx running at yy
	  where xx is the version number and yy your hostname. Type "quit"
	  after seeing this message. If you don't get any connection at
	  all or something different, check through points 1-4 above.

Problem: tin complains about a missing file "/var/lib/news/active".
Solution: Either you have started the wrong version of tin (the one which
	  tries to read news directly from the spool) or your groupinfo file
	  is corrupt.
	  In the first case, simply invoke tin with the -r flag: "tin -r".
	  If this does not help, try to rebuild the groupinfo file by
	  starting fetch with the -f flag.

Problem: When searching news with Netscape, I only get back "unknown command".
Solution: To search news, older versions of Netscape needed a news server
	  which supports the XPAT command. Leafnode does not. If you want
	  to use Netscape, you have to upgrade to version 4.5 and press the
	  "options" button which appears in the "search messages" window.
	  In the box which appears you have to select "on your local system".

Problem: fetch does not fetch any articles.
Solution: a) Your groupinfo file is corrupt. Restart fetch with the -f
	     parameter.
	  b) /var/spool/news may have the wrong permissions. /var/spool/news
	     and all its subdirectories should be drwxrwsr-x and owned by
	     user and group news.

Problem: fetch crashes with a segmentation fault.
Solution: This should not happen. As a workaround, do the following:
	  If fetch crashes during posting, it helps to post the articles
	  separately (with "fetch -P"). If fetch crashes during reading news,
	  repeatedly calling it will finally fetch all the articles.

Problem: My news reader complains about repeated frequent timeouts of the
	 NNTP server.
Solution: Again, this is most likely the result of a corrupt groupinfo
	  file. Rebuild it by starting fetch with the -f parameter.

Problem: leafnode generates incorrect/incomplete message IDs.
Solution: Most likely your machine has no or an incomplete name. Leafnode
	  figures out the machine name by calling gethostname(2) and
	  using the return value for a gethostbyname(3) call. Therefore,
	  if you set the name of your computer correctly (using hostname(1)
	  and domainname(1)) you should also get correct message IDs.
	  If you don't want to change the name of your machine, you can
	  change the part of the Message-ID behind the @ sign by putting
	  "hostname = correct.hostname" in your config file. For more
	  information, see the leafnode(8) man page.

Problem: fetch has problems retrieving new newsgroups.
Solution: Maybe your upstream server supports neither the 
	  "XGTITLE news.group.name" nor the "LIST NEWSGROUPS news.group.name"
	  command. In this case, add "nodesc" to your server entry as
	  described in leafnode(8) and the config.example file.

Problem: texpire does not expire articles.
Solution: Run texpire with the -f parameter. This will expire articles
	  somewhat earlier because the time of last access on the files
	  will be ignored. If you have an urgent need to free some space
	  in your spool directory, reduce the expiry time in the config
	  file and re-run texpire -f.

Problem: When running leafnode in "delaybody" mode, I can only view the
	 headers with Netscape.
Solution: This is a problem of Netscape, not of Leafnode. Netscape is
	  storing read articles in its cache and (for some odd reason)
	  refuses to reload an article that has been already read. To force
	  Netscape to reload articles, clear the cache (Options/Network
	  Preferences in version 3.0x). Better, get a sensible newsreader.

Problem: If I post articles which have . at the beginning of a line (followed
 	 by other text), the dots get lost.
Solution: This problem has been described when your upstream server runs
	  INN 2.1. With regards to singular dots at the beginning of lines,
	  leafnode ignores RFC977 and just leaves them untouched. This works
	  very nicely together with DNEWS, but apparently not with INN.

If you run into problems, you can learn a lot about what leafnode sees
and does by putting "debugmode = 1" into the leafnode configuration file
and then turning on logging of the "debug" priority for the facility
"news". Leafnode (i.e. fetch, texpire and the nntp daemon) can write a
lot of informative output to this channel.
To turn on logging, do the following:
1) Put into /etc/syslogd.conf a line which looks like the one below:
     news.=debug	/var/log/news.debug
   It is mandatory that the two fields be separated by a tab, not spaces.
2) Become root and restart the syslog daemon:
     kill -HUP `cat /var/run/syslog.pid`
   or
     kill -HUP `cat /var/run/syslogd.pid`
   (depends on your distribution).
Be warned that the logfile can become very large fairly quickly.

You also may want to consult the Mini-Leafsite-HOWTO by Florian Kuehnert
<sutok@gmx.de> which was unfortunately written for leafnode-1.4 and is
therefore somewhat out of date. It is available from the usual places
(sunsite and mirrors).

Cornelius Krasel <krasel@wpxx02.toxi.uni-wuerzburg.de>
