Provided by: leafnode_1.11.11-1_amd64 
NAME
leafnode - NNTP server for small (dialup) sites
SYNOPSIS
leafnode
DESCRIPTION
Leafnode is a USENET package intended for small sites, where there are few users and
little disk space, but where a large number of groups is desired.
The design of leafnode is intended to self-repair after problems, and to require no manual
maintenance.
The leafnode program itself is the NNTP server. It is run from inetd(8), xinetd(8) or
tcpserver when someone wants to read news. The other parts of the package, fetchnews and
texpire, are responsible for fetching new news from another server, and for deleting old
news.
ACCESS CONTROL
No authentication or access control is supported. This is a deliberate omission:
Implementing this is a job which should not be redone for each and every service.
It is mandatory that you use external access control mechanisms like tcpd, inetd/xinetd
compiled with libwrap support, tcpserver with -x option and the like and that these are in
effect. tcpd and libwrap are components of Wietse Venema's fine tcp_wrappers package.
As a very rough last line of defense against abuse, leafnode will drop connections from
outside your LANs by default. You can configure leafnode to let go of this restriction
(look for the allowstrangers option), but don't do that unless tight access control is in
place. Someone will abuse your computer sooner or later. Promised.
I recommend that either firewalling or tcpd be used for access control.
FILES
All these files and directories must be readable by the user "news". It is recommended
that, unless otherwise stated, that the user "news" be the only user in the group "news"
and these files belong to "root:news" (user:group) so leafnode cannot modify your
configuration or filter files.
/etc/news/leafnode should not be writable by the user "news", but it must be executable
for at least any of the group that the user "news" is in. /etc/news/leafnode/config
contains the configuration parameters for leafnode. It must not be writable by the user
"news". Set this to owner root:news and mode 640. For details, see CONFIGURATION below.
/var/spool/news must also be readable and writable by the user "news". It contains the
news articles; e.g. /var/spool/news/alt/fan/agulbra contains the articles in the
alt.fan.agulbra group. Each directory contains articles in numbered files (decimal
numbers, monotonically increasing), and a special file called .overview which contains the
"Subject", "From", "Date", "Message-ID", "References", "Bytes" and "Lines" headers for
each article in the group.
Several subdirectories are special:
/var/spool/news/leaf.node contains the files that leafnode creates during operation, for
example the groupinfo file which contains information about each USENET newsgroup. This
file is built by fetchnews (8). You can force a complete rebuild of the groupinfo file by
calling fetchnews with the parameter -f (see fetchnews (8)).
/var/spool/news/out.going contains local postings that fetchnews(8) is to pass to the
upstream NNTP server. After a posting has been successfully written to disk, its u+r
permission flag is set. This flag is interpreted by fetchnews(8) as "you may post this
article". This prevents fetchnews from posting articles that are still being received from
newsreaders. (Note: versions 1.9.23 to 1.9.32 inclusively used u+x instead, which caused
some "stuck post" problems with articles in the spool when a prior leafnode version was
updated to one of these 10 versions. Updating to leafnode 1.9.33 or later fixes the
problem.)
/var/spool/news/failed.postings contains local postings that the upstream server rejected.
fetchnews(8) will create files in this directory, but none of the leafnode programs will
delete anything in it.
/var/spool/news/message.id contains hard links to each message; this is used in place of
the dbz database typically used by bigger servers. (A directory such as this is probably
more efficient for the small servers leafnode is designed for but scales very badly.)
/var/spool/news/interesting.groups contains one file for each group an NNTP client has
asked to read. leafnode will update the ctime (ls -l usually shows the mtime, try ls -lc)
of the relevant file when a LISTGROUP, XOVER, XHDR, STAT, HEAD, BODY or ARTICLE command is
issued, when a GROUP or LIST ACTIVE command (the latter only with a single group, not with
patterns) is issued for an interesting group (to avoid unsubscribing low-traffic groups
that are still read) and fetchnews(8) will retrieve all new articles in all groups whose
files have been either
- touched during the past two days, or
- touched more than once, and at least once within the past week.
The timeout is configurable through the config file variables timeout_short and
timeout_long. See also fetchnews(8) for the -n option.
/etc/inetd.conf or /etc/xinetd.conf contains the configuration which starts leafnode. It
is strongly recommended to start leafnode as user news.
ENVIRONMENT
LN_REJECT_POST_PRE
If this variable exists, all POST commands are rejected with a 400 code. Use only
for debugging clients.
LN_REJECT_POST_POST
If this variable exists, the POST command is rejected with a 400 code after the
article and CRLF.CRLF has been received. Use only for debugging clients.
CONFIGURATION
All configuration is done using the file /etc/news/leafnode/config, which may include a
filter description file, filterfile for short, as described below.
For the purposes of this section, whitespace shall be defined as an arbitrary sequence
consisting of one or more SPACE or HTAB characters, ASCII positions 32 and 9,
respectively.
The configuration file is strictly line-oriented with LF or CRLF as line terminator.
Empty lines and lines consisting of only whitespace, possibly followed by a comment
(introduced by a hash mark (#) and extending through the end of the line), are skipped.
All other lines have exactly three mandatory fields, a plain text parameter, an assignment
character (=) optionally surrounded by whitespace and a value. The value is either plain
text or – new since leafnode v1.11 – a string in double quotes with trivial backslash
escape (see below).
Plain text starts at the first non-whitespace character and extends through the last non-
whitespace character on the line that is not a comment. A trailing comment on a line is
skipped.
Quoted strings are enclosed in double quote characters ("). The backslash character (\)
is skipped, but it copies the immediately following character verbatim, so that you can
specify the backslash itself by doubling it (\\) or a double quote character as part of
the string by preceding it with a backslash (\"); the hash mark has no special meaning as
command introducer inside quoted strings. Text after the end of the string is silently
ignored (this may change in future versions). Comments after quoted strings are ignored.
MANDATORY PARAMETERS
These parameters must be specified for leafnode to work.
server = news02.example.com
"server" is used by fetchnews (8) to select what NNTP server(s) to retrieve news
from and to post your articles to. You can specify more than one news server; in
that case, the servers will be queried from the top down. If you want to post
articles, at least one of your servers should allow you to post. In the example
above, news02.example.com is the news server.
This parameter can be given more than once. Each server starts with a fresh set of
default configuration options, no inheritance takes place from the previous server
definition. Only options explicitly marked "server-specific" can be set on a per
server basis, "general" options are set for all servers at the same time.
expire = 5
"expire" is the number of days an article should be kept around. In the example,
five days after the article has last been read, it is deleted by texpire (8). This
value MUST be at least 1. This parameter is global, see the introductory paragraph
of the following GENERAL OPTION PARAMETERS section to find out what this means.
GENERAL OPTIONAL PARAMETERS
These options can only be configured once in the configuration file, and take effect for
leafnode as a whole. It does not matter where these are specified relative to server=
options, but for clarity, you are encouraged to place these before the first server= line.
Specifying each of the global options more than once lets the last copy take effect, but
may cause errors in the future.
hostname = host.domain.country
By default, leafnode tries hard to figure the host name of your computer, skipping
inadequate (non-unique) names if possible. It will look up your computer's host
name with gethostname(3) and then try to qualify the name with gethostbyname(3) if
necessary. Common sources for the full name therefore are /etc/hosts, NIS and DNS,
but consult your system documentation for details.
If leafnode fails to determine the host name, this is usually a hint that your
system is not configured properly, or it has a hostname that is unsuitable for the
domain part of a Message-ID, for example, "localhost.localdomain", and you should
fix the name service configuration. Adding a unique fully-qualified host name to
/etc/hosts is usually sufficient. Please see README-FQDN for more details.
You can configure the unique fully-qualified host name here as well, but this is
not recommended and discouraged.
create_all_links = 1
Normally, fetchnews will store articles only in the newsgroups which it considers
interesting. With this option set, fetchnews will create hardlinks for all
newsgroups in the Newsgroups: header that it knows about. This may be of interest
if you want to apply a score- or killfile to the local Xref: line.
maxfetch = 1000
"maxfetch" specifies the maximum number of articles fetchnews (8) should fetch from
the upstream server in each group. Its use is not advised, because if you use it
you will not see all the traffic in a group. By default there is no limit.
initialfetch = 1
"initialfetch" defines how many articles from a newly subscribed group should be
fetched. The default is to fetch all old articles, which can get quite time-
consuming when subscribing to a very busy group. This is equivalent to setting
initialfetch to zero. If you want to get no old articles when subscribing to a new
group, you should set initialfetch to one, as in the example above.
groupexpire very.crowded.group = 1
groupexpire very.crowded.hierarchy.* = 1
"groupexpire" makes it possible to adjust expiry times for individual groups.
Expiry times are given in days. 0 means "use the default", negative values prevent
the expire process for this group altogether (you can consider this an archive
mode). This value is used by texpire (8). You can specify as many groupexpire lines
as you like. It is possible to specify glob (7)-like wildcard expressions.
maxage = 10
If an article turns up on your upstream news server which is older than "maxage"
days it will not been fetched even if you don't have it yet. This is useful if
your upstream server gets occasional "hiccups". The default is set to 10. If you
want to switch this feature off, set maxage to some very large value, such as 20000
(this is equivalent to roughly 54 years).
maxold = 10
Is synonymous to maxage, see above.
maxlines = 2000
If you want to avoid receiving very large articles, you may set the "maxlines"
parameter to the maximal number of lines an article should have. By default, this
feature is switched off.
minlines = 2
Sometimes newsgroups are spammed with empty postings. To reject these postings, you
can set the "minlines" parameter. Setting minlines to a value larger 4 is probably
not a good idea since you will also start to kill "real" postings then. By default,
this feature is switched off.
maxbytes = 100000
If you want to avoid receiving very large articles, instead of using the "maxlines"
parameter you can also use the "maxbytes" parameter. By default, this feature is
switched off.
maxcrosspost = 5
If you want to combat spam, you can filter out all postings that are posted to more
than a certain number of newsgroups. The number is defined by setting
"maxcrosspost". Setting this parameter to very low values is probably a bad idea.
This feature is switched off by default.
maxgroups = 5
Synonymous for maxcrosspost. See above.
filterfile = /etc/news/leafnode/filters
Leafnode can filter the input headers for arbitrary regular expressions. These are
stored in a file designated "filterfile". The format of "filterfile" is very
simple: one perl-compatible regular expression per line. If one of the regular
expressions fits to a header to be downloaded, the body of that article will be
rejected. This feature is switched off by default. The format of the regular
expressions is described in pcre(3).
timeout_short = 2
By default, a group that has been accidentally touched is being fetched for two
days. You can change this time by changing timeout_short.
timeout_long = 7
By default, a group that has not been read at all is being fetched for seven days
before being unsubscribed. This interval can be changed by setting timeout_long to
a different value.
timeout_active = 90
By default, active files from the upstream servers are re-read every 90 days. This
interval can be changed by setting timeout_active to a different value. Be aware
that reading an active file transfers about one MB of information if the server
that you are using carries a reasonable number of groups (i. e. around 20,000).
timeout_client = 900 (since v1.9.23)
By default, leafnode will drop the connection 900 seconds (15 minutes) after seeing
the last command from the client. You can change the timeout here. Setting it too
low (like below 5 minutes) will annoy your users and consume more system resources
for re-reading all the files.
timeout_fetchnews = 300 (since v1.9.52)
Fetchnews will, since v1.9.52, assume the upstream server has become wedged after
waiting for a reply for 300 seconds. You can change the timeout here.
timeout_lock = 5 (since v1.9.54)
Configure how many seconds the leafnode programs (applyfilter, checkgroups,
fetchnews, texpire) will wait for the lock file before aborting. Setting this to 0
means to wait indefinitely. NOTE: you can override this by setting the environment
variable LN_LOCK_TIMEOUT (note it is not LN_TIMEOUT_LOCK). The default is 5
seconds.
delaybody = 1
With this option set, fetchnews (8) fetches only the headers of an article for
visual inspection. Only when the headers have been read, the bodies of the articles
will be retrieved the next time fetchnews (8) is called. This can save a huge
amount of download time and disk space.
delaybody_in_situ = 1 (since v1.9.41)
This is only applicable with delaybody=1.
By default, leafnode will give the full downloaded article a new article number so
they appear as new in your newsreader. This does not work for all newsreaders. With
this option set, leafnode will retain the original article number. You'll have to
figure out how to tell your newsreader to show old articles. This option defaults
to 0. It is highly recommended to leave it unset.
debugmode = 1
With this option set, fetchnews (8), texpire (8) and leafnode (8) will start to log
lots of debugging output via syslog (8) at facility news and priority debug. Use it
for tracking down problems with your feed. debugmode should be left at 0 for
regular use because it can log enormous amounts of data. The higher the number, the
more will be logged. Choosing a figure greater than 3 will not make a difference at
the moment.
allow_8bit_headers = 1 (since v1.9.25)
By default, leafnode rejects local posts that have 8-bit characters in their
headers, because they violate relevant standards, particularly RFC-2822 (which
RFC-1036 is based on) that demands that Usenet news headers (as mail headers) must
be pure 7-bit US-ASCII, with only whitespace allowed from the control characters.
However, as UTF-8 is to come, and some national hierarchies, particularly the
Norwegian and Danish (no.*, dk.*) seem to have agreed on preferring just-send-eight
over RFC-2047, you can set this option to allow 8-bit data in headers. Leafnode
will however add a warning header if 8-bit data is present, stating that the site
administrator allowed this.
There is no way to make leafnode accept non-whitespace control characters in
headers.
allowSTRANGERS = MAGIC (since v1.9.23)
By default, leafnode refuses connections from outside your LANs. Check
config.example for how to use this parameter to let strangers connect to your
leafnode. Instead of MAGIC, you have to write a number as mentioned in
config.example. Note that capitalization matters.
linebuffer = 1
By default, stdout and sometimes stderr of applications are set to "fully buffered"
unless connected to terminals. Use this option to explicitly request line buffered
mode for stdout and stderr.
clamp_maxage = 0
By default, leafnode will derive a "maxage" argument from the expire time that is
applicable to the group (groupexpire if set, expire otherwise), to prevent fetching
articles again that were once there and then cleared by texpire(8). Set
clamp_maxage=0 to get rid of this behaviour.
article_despite_filter = 1 (since v1.9.33)
By default, fetchnews will request HEAD and BODY separately if a filter file is
defined and delaybody is off. For high latency, high throughput links (such as
interleaved DSL or satellite links), it may be faster to request head and body
together with an ARTICLE command and ignore the body if the filters apply (though
it may not be cheaper if you pay per MByte), enabling this option will force
leafnode to use the ARTICLE command in spite of filters being defined. (Note that
in delaybody mode, HEAD and BODY will ALWAYS be requested separately.)
newsadmin = news@leafnode.example.org (since v1.9.47)
This option sets the From: address for the placeholder article, it should be the
news administrator's mail address. It defaults to news@HOSTNAME, where HOSTNAME is
leafnode's hostname.
SERVER-SPECIFIC OPTIONAL PARAMETERS
These options can only be placed after the server= line of the server to which you would
like these to apply, and they always pertain to the preceding server= line. Specifying
them before the first server= line is an error.
username = myname
If any of your news servers requires authentication, you can enter your username on
that server here. This field may occur multiple times, once after each server
definition. See the introduction of this CONFIGURATION section for information on
how to quote myname.
password = mypassword
If any of your news servers requires authentication, you can enter your password on
that server here. This field may occur multiple times, once after each server
definition. Since the password is available in clear text, it is recommended that
you set the rights on the config file as restrictive as possible, otherwise other
users of your computer will be able to get your password(s) from that file. See the
introduction of this CONFIGURATION section for information on how to quote
mypassword.
port = 8000
By default, fetchnews tries to connect to its upstream news servers on the NNTP
port (119). If your servers run on a different port, you can specify those here.
This field may occur multiple times, once after each server definition.
Note: to modify the port your own leafnode servers listens on, change the
inetd.conf, xinetd.conf configuration file or the tcpsvd/tcpserver command line.
leafnode does not set up its listen port itself.
timeout = 30
By default, leafnode tries to connect for 10 seconds to a server and then gives up.
If you have a slow server, you can try for a longer time by setting the timeout
higher (in this example, 30 seconds). The timeout can be tuned individually for
each server.
noactive = ANYTHING (v1.9.25 ... v1.11.4)
noactive = 1 (since v1.11.5)
If this parameter is set, the active file is never downloaded from this server. Use
this for very slow servers unless they carry groups that other servers don't offer.
Leafnode versions 1.9.25 to 1.11.4 would always assume that "ANYTHING" had been 1.
"noactive = 0" is supported since v1.11.5.
nodesc = ANYTHING (until v1.11.4)
nodesc = 1 (since v1.11.5)
Some servers do not deliver news groups descriptions correctly because they cannot
parse the XGTITLE and LIST NEWSGROUPS commands. In that case, put this line after
the "server" line. Leafnode versions up to v1.11.4 would always assume that
"ANYTHING" had been 1. "nodesc = 0" is supported since v1.11.5.
nopost = 1 (since v1.9.23)
Prevent posting to this server. You can use this if the upstream won't let you post
but still greet leafnode with 200 or if the upstream doesn't forward your postings
reliably.
noread = 1 (since v1.9.33)
Prevent fetching news articles or active files from this server. You can use this
if the upstream is good to post, but too slow to fetch news from.
noxover = 1 (since v1.9.47)
Prevent the use of XOVER on the current server. Fetchnews will use XHDR instead.
only_groups_match_all = 1 (since v1.9.52)
Usually, when cross-posting an article, fetchnews will post the article if ANY
group listed in the Newsgroups: header is matched by the PCRE. With this option
on, ALL groups listed in the Newsgroups: header must match. This can be used to
avoid "poison" groups when you have multiple upstream servers.
only_groups_pcre = PCRE (since v1.9.28)
This parameter lists the Perl-compatible regular expression of groups that are
fetched or posted to this server. The PCRE is automatically anchored at the left
hand side, so you can omit the leading ^. Remember to escape dots, as in:
de\.comp\.|de\.comm\.
If this parameter is omitted, all groups are fetched from and posted to this
server.
Note: you must run fetchnews with the -f option after changing, adding or removing
any only_groups_pcre option.
Hint: you can use something like this to check your only_groups_pcre settings:
cut -f1 -d" " @spooldir@/leaf.node/groupinfo \
| pcregrep 'PATTERN'
post_anygroup = 1 (since v1.9.37)
This parameter makes leafnode post on this server without checking if it carries
the group an article is posted to. The default is post_anygroup = 0, which means
that leafnode will check with a "GROUP" command if the server carries the group the
articles is posted into. Use this on post-only servers that don't allow the "GROUP"
command. Note: inconsiderate use of this parameter may cause articles to end up in
the failed.postings directory.
OBSOLETE PARAMETERS
supplement
is synonymous to server. Don't use it on new installations.
fqdn is synonymous to hostname. Don't use it on new installations.
PROTOCOL
Here are the NNTP commands supported by this server:
ARTICLE, BODY, DATE, GROUP, HDR, HEAD, HELP, LAST, LIST, LIST ACTIVE, LIST ACTIVE.TIMES,
LIST EXTENSIONS, LIST NEWSGROUPS, LIST OVERVIEW.FMT, LISTGROUP, MODE, NEWGROUPS, NEXT,
POST, OVER, SLAVE, STAT, XHDR, XOVER. These commands follow RFC-977 and RFC-2980, except
HDR and OVER which are recognized in anticipation of current NNTP drafts.
Note that the syntax of HDR and OVER may change.
BUGS
Leafnode is totally unaware of UTF-8 and will reject a client that posts UTF-8 characters
in the header. Current Usefor drafts claim all article headers UTF-8 encoded Unicode.
Leafnode still expects RFC-2047 instead which may eventually be phased out in favour of
UTF-8.
Leafnode stops reading a line at the first NUL character.
Leafnode may not cope well with crosspostings that cross hierarchies if you have multiple
upstream feeds and use the only_groups_pcre configuration option.
Leafnode will only bother to determine the time zone offset for generated Date: headers
for posts that lack them on systems that offer the tm_gmtoff member in struct tm (commonly
BSD and GNU systems).
AUTHOR
Written by Arnt Gulbrandsen <agulbra@troll.no> and copyright 1995 Troll Tech AS, Postboks
6133 Etterstad, 0602 Oslo, Norway, fax +47 22646949.
Modified by Cornelius Krasel <krasel@wpxx02.toxi.uni-wuerzburg.de>, Randolf Skerka
<Randolf.Skerka@gmx.de> and Markus Enzenberger <enz@cip.physik.uni-muenchen.de>.
Copyright of the modifications 1997 – 1999.
Modified by Matthias Andree <matthias.andree@gmx.de>, Copyright 1999 – 2002. Modified by
Ralf Wildenhues <ralf.wildenhues@gmx.de>, Copyright 2002.
Jonathan Larmour <jifl@jifvik.org> contributed the timeout_client feature.
Andreas Meininger <a.meininger@gmx.net> contributed the code to let texpire ignore
groupexpire = -1 groups.
Mark Brown <broonie@debian.org> added the noactive option.
Numerous contributions by other people.
The initial development of leafnode has been paid for by Uninett AS
(http://www.uninett.no/).
SEE ALSO
applyfilter(8), checkgroups(8), fetchnews(8), newsq(1), texpire(8).
tcpd(8), hosts_access(5), glob(7), pcre(3), RFC 977, RFC 2980.