                        TABLE OF CONTENTS

- OVERVIEW
- FILES AND DIRECTORIES
- INSTALLATION
- UPDATE FROM A PREVIOUS VERSION
- 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:

 - 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.

 - 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, 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.

This list of Leafnode's weaknesses has been moved here from DONTREADME
due to popular demand:

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

 - Scales very badly.

Leafnode works nicely with tin and lynx and reasonably with Netscape.
I have not tested other newsreaders so far.



                      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 /usr/lib/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 A PREVIOUS VERSION

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: 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: tin complains about a missing file "/var/lib/news/active".
Solution: Probably your groupinfo file is corrupt. Start fetch with
	the -f parameter to rebuild it.

Problem: Netscape won't search news but returns "unknown command".
Solution: To search news, Netscape needs a news server which supports the
	XPAT command. Leafnode does not. Either get a real newsreader or
	another news server.

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: Your groupinfo file may be corrupt. Again, this can be repaired
	by starting fetch with the -f parameter. Make sure that you have
	sufficient disk space available on the partition in which
	/var/spool/news resides.

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.

Problem: texpire does not expire articles.
Solution: This apparently happens sometimes, and I have no real explanation
	  for it. If you run into this problem, do an "ls -lu > foobar" on
	  the directory which contains the articles (e.g.
	  /var/spool/news/comp/os/linux/misc). Look at the dates. Do you
	  have a program which does access news articles? Have you grepped
	  your news spool recently? All of this will confuse texpire.
	  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. This will usually help.

If you run into problems, you can learn a lot about what leafnode sees
and does by turning on logging of the "debug" priority for the facility
"news". Leafnode (i.e. fetch, texpire and the nntp daemon) is designed
to write a lot of 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`
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 is unfortunately out of date with regard to
leafnode-1.6. It is available from the usual places (sunsite and mirrors).

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