                        TABLE OF CONTENTS

- OVERVIEW
- FILES AND DIRECTORIES
- THE FILTER FILE
- INSTALLATION
- UPDATE FROM VERSIONS < 1.6
- UPDATE FROM VERSIONS < 1.9.3
- PROBLEMS

You can find German documentation in the directory doc_german/ . However,
this documentation may be slightly out of date. If in doubt, refer to
the English documentation.


			    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.

 - Fetchnews 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,
fetchnews will stop reading that group a week later (this is the default
which can be configured), and when someone starts reading a group, fetchnews
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.
 
 - The newsspool can be easily manipulated by small scripts. Some tiny
   examples are in the subdirectory tools/ .

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. All
directories can be changed at compile time.

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.

The binaries directory, /usr/local/sbin by default, contains the
executable programs applyfilter, texpire, fetchnews and leafnode.

The user directory, /usr/local/bin by default, contains the newsq
program.


                          THE FILTER FILE

From version 1.8, leafnode supports filtering of incoming headers for
arbitrary regular expressions. This feature is by default deactivated.
To activate it, you must first write a file which contains the regular
expressions to be filtered (the "filter file") and in addition point
leafnode to this file by entering a line of the format

filterfile = /path/to/your/filterfile

into your $(LIBDIR)/config.
The format of the filterfile is as follows:
1) One regular expression per line
2) Comments start with # at the beginning of a line
3) Empty lines are allowed

Here is a short example which will kill everything posted to alt.flame:

^Newsgroups:.*[, ]alt.flame$
^Newsgroups:.*[, ]alt.flame,

You cannot use

^Newsgroups:.*alt.flame

because this will also kill postings to alt.flame.nice or comp.alt.flame.

From version 1.9.3 leafnode uses Perl-compatible regular expressions which
are implemented in the PCRE library written by Philip Hazel, University
of Cambridge, UK. Perl regular expressions should be explained in any
reasonable book about Perl. There is also a whole book about regular
expressions published by O'Reilly. A rather technical explanation is given
in the pcre(7) man page which is included with leafnode.


                           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.


                      UPDATE FROM VERSIONS < 1.9.3

There is one more change from leafnode versions prior to 1.9.3. These
include leafnode-1.9.3beta versions up to leafnode-1.9.3b5.

The change is that the groupinfo file is now sorted in a case-insensitive
manner. To update correctly, do a "make update" as root after you have
successfully completed "make install". See the file INSTALL for more
details.

			PROBLEMS

Some commonly encountered problems with Leafnode are addressed in the
FAQ.

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

If you want to ask on Usenet about leafnode, look in the newsgroups
news.software.nntp (Germans can use de.comm.software.newsserver).

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