Preface: This documentation is about to be migrated to a different format. Do not file bug reports against section numbering or references within this document.
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 is developed on Linux, but has been reported to compile and run also under any BSD flavour, Solaris and Irix.
The Leafnode package consists of several programs, three essential ones and several add-ons.
These are the additional tools:
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.
Leafnode's distinguishing features are:
The current version of leafnode is available from http://www.dt.e-technik.tu-dortmund.de/~ma/leafnode/beta/
There is also a leafnode mailing list. Send mail to
leafnode-list-subscribe@dt.e-technik.tu-dortmund.de
to subscribe, or visit http://www.dt.e-technik.tu-dortmund.de/mailman/listinfo/leafnode-list/.
/bin/sh ./configure
to create an appropriate Makefile and config.h. If leafnode
cannot find your PCRE, it is probably an old version
without pcre-config, or pcre-config is not in your path.
Either add the directory containing pcre-config to your
$PATH, or call configure like this (we assume PCRE is in
/opt/pcre-3.9):
env CPPFLAGS="-I/opt/pcre-3.9" LDFLAGS="-L/opt/pcre-3.9" /bin/sh ./configure
NOTE: on some machines, when PCRE is linked against a
shared library, you will need to add /opt/pcre-3.9 to
LD_LIBRARY_PATH or to /etc/ld.so.conf.
The configure script can take some flags (replace DIR by a directory name, FILE by a file name):
--enable-spooldir=DIR To override the default /var/spool/news,
where leafnode puts its news spool unless
--localstatedir is given or --prefix is given and
different from /usr, in the latter case, the
default is $localstatedir/spool/news
--prefix=DIR Leafnode installs itself normally in the /usr/local/sbin
directory. If you want to use another directory, use this
flag. For example, if you want to install leafnode in
/usr/sbin, use --prefix=/usr
--sysconfdir=DIR Default path for configuration is /etc/leafnode when
--prefix is not used or set to /usr, and PREFIX/etc
otherwise. You can use this to change the config file
location from its default.
--with-dmalloc Lets leafnode include dmalloc header files and link
against libdmalloc. Only useful for debugging, not
needed for normal operation. This option requires
dmalloc, available from http://dmalloc.com/.
--with-runas-user=USER Lets leafnode run as user USER, defaults to "news".
--with-pam Enable PAM (pluggable authentication modules)
support.
BEWARE: Former versions always defaulted
their sysconfdir to /etc/leafnode. Current versions only
override sysconfdir to /etc/leafnode if configured without
--prefix or with --prefix=/usr. That way, if
--prefix=/opt/leafnode, the sysconfdir goes to
/opt/leafnode/etc, which is more appropriate.
make
There should be no errors.
make install
If you prefer an installation with the binaries stripped
free of symbols, use
make install-strip
instead.news.info /var/log/news
Note that if you want to send in a bug report and need debug logging, you'll have to replace news.info by news.debug (and send a SIGHUP, as shown below).
Your syslog.conf may already suggest a different file. If your syslog.conf suggests news.info logging, use that, but be sure to activate it in case it's commented out: remove leading hash marks and white space.
Also make sure you use TABs between news.info and the path.
If you want to use filtering of the incoming spool, see the section on the filter file below.
0 4 * * * /usr/local/sbin/texpireI did "crontab -u news -e" as root to edit the crontab file, and added this line. Substituting "1" for the third "*", thus:
0 4 * * 1 /usr/local/sbin/texpiretells cron to run texpire at 4am every Monday morning.
nntp stream tcp nowait news /usr/sbin/tcpd /usr/local/sbin/leafnodeNote: some systems install tcpd to a different path, but it's uncommon. Change the first path accordingly if your tcpd resides in /usr/etc or /usr/lbin. After these changes, force inetd to read the changed configuration file by sending it the HANGUP signal. To achieve this, issue the following command (as root):
kill -HUP `cat /var/run/inetd.pid`
service nntp
{
flags = NAMEINARGS NOLIBWRAP
socket_type = stream
protocol = tcp
wait = no
user = news
server = /usr/sbin/tcpd
server_args = /usr/local/sbin/leafnode
instances = 7
per_source = 3
}
Then send xinetd an USR2 signal to make it reread its
configuration. See the xinetd.conf(5) manual
page for details. Note: some systems install tcpd to
a different path, but it's uncommon. Change the first
path accordingly if your tcpd resides in /usr/etc or
/usr/lbin.
leafnode: ALLand into /etc/hosts.allow:
leafnode: 127.0.0.1to protect your news server from abuse. If you want to make leafnode accessible to additional IP numbers/domains, add them in /etc/hosts.allow in the format described above. See hosts_access(5) and hosts_options(5) (if applicable) for more information about tcp wrappers.
leafnode: 192.168.0.4: setenv NOPOSTING "You may only read."The contents of this variable are printed at the end of the banner, with control characters (as per iscntrl(3)) replaced by an underscore.
leafnode: 127.0.0.1 192.168.0.42: ALLOW leafnode: 192.168.0.0/255.255.255.0: setenv NOSUBSCRIBE 1 leafnode: ALL: DENY
After this, you should have empty files in /var/spool/news/interesting.groups/ for every group you want to read.
The local.groups and groupinfo files and the hash function for message.id have changed from any former version to 2.0b8_ma8.
IMPORTANT: To fix the "remote" groups, run fetchnews -f -- it will take some time, because it refetches the whole active file, but that's needed anyhow to figure the group status (posting allowed/not allowed/moderated group).
To fix local.groups, if you have perl installed:
perl -ple 's /\s+/\ty\t/' -i.bak /etc/leafnode/local.groupsThis will make a backup of your original /etc/leafnode/local.groups in /etc/leafnode/local.groups.bak.
If you don't have Perl, use a text editor that preserves HTAB characters, change all while space to TAB and insert an additional field reading just y:
Before: local.test some test group
After: local.testTAByTABsome test group
From 1.9.x to 2.0 there were some changes to options in the main configuration file. The options "maxage", "maxlines", "minlines", "maxbytes" and "maxcrosspost" have become obsolete in the main configuration file and have to be specified in the filter file instead. The advantage of this is that you can do much finer selection on these criteria now.
To replace, for example, a "maxage = 5" specification in the main configuration file, you should add the following to your filter file:
newsgroups = .* maxage = 5 action = kill
The leafnode programs will issue warnings if they encounter obsolete specifications in the main config file.
From version 1.9.3 on, the groupinfo file is sorted in a case-insensitive manner. To update correctly, do a "make update" as root after you have successfully completed "make install". This will re-sort the groupinfo file. The old groupinfo file will be stored as groupinfo.old just in case something goes wrong. You also have to change your main config file manually as described in the previous section.
Between leafnode-1.6alpha and leafnode-1.6, the format of the groupinfo file changed and some files moved to other places. To update correctly, do a "make update" as root after you have successfully completed "make install". This will reformat the groupinfo file and move the other files into the correct places. The old groupinfo file will be stored as groupinfo.old just in case something goes wrong. You also have to change your main config file manually as described in the section "Update from versions < 2.0".
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 main configuration file contains settings important for all programs of the leafnode suite. It defaults to /etc/leafnode/config, but several configuration files can be used at once by employing the -F switch of the programs.
The file contains two mandatory and a number of optional parameters.
NOTE: Global options must come first, server-specific options below the server = lines.
Mandatory parameters
server = news02.bigprovider.comYou have to specify at least one server (except if you want leafnode to serve as a local server only). Usually, this will be the news server of your provider. You can specify more than one server, and fetchnews will retrieve news from all of them, taking care not to transfer articles multiple times to your machine. Servers will be queried in the order specified in the config file.
expire = 5This parameter determines how many days threads are kept on your hard disk. texpire will delete whole threads, not just single articles.
Server-specific optional parameters
To configure interaction with the server somewhat, you can change the behaviour of fetchnews by setting several server-specific optional parameters. They have to be specified directly after the corresponding "server" statement. A new server statement in the config file will also allow new optional parameters.
username = mynameIf your upstream server requires a form of authentication, you can set your username and password here.
password = mypasswd
timeout = 30It may happen that, due to a bad connection or other reasons, the server stops talking to you while you fetch news. The "timeout" parameter determines the number of seconds fetchnews is supposed to wait for a response from the server before giving up.
nodesc = 1Some servers are unable to deliver descriptions of new newsgroups correctly. When fetchnews encounters such a server, it will print the warning
server.name does not process LIST NEWSGROUPS news.group.name correctly: use nodescTo allow for shorter download times, you should in this case set "nodesc = 1" for that particular server in the configuration file.
port = 8000Normally, fetchnews will try to retrieve news from port 119 (the standard nntp port) of your upstream server. If the upstream server runs on a different port, you can specify it with this option.
General optional parameters
authenticate = METHODRequire that NNTP clients connecting to your leafnode authenticate themselves. The only method currently supported is internal. In this mode, leafnode expects a file users in its sysconfdir, /etc/leafnode/users by default, which has a simple format, one line per user, with the user name (which cannot contain spaces), then a colon, then the crypt(3) encrypted password. To generate these lines, you can use the Perl program tools/make_pass.pl, for example, if you want to add a user "enigma" with a password of "break!me", type:
perl -wT tools/make_pass.pl 'enigma' 'break!me'and copy the resulting line to the users file.
hostname = host.domain.countryIf the postings that you write do not have message IDs (generated by the newsreader), leafnode will generate a message ID for you. (It will never overwrite an already existing message ID.) Message IDs generated by leafnode feature ".ln" before the @ sign. The message ID contains the fully qualified hostname of your machine which may not always be what you want. In that case, you can override the use of the hostname by using the "hostname" option.
create_all_links = 1Usually fetchnews will store articles only in the newsgroups which you consider interesting. Unfortunately, this makes it difficult to score for the number of newsgroups a message is posted to because the Newsgroups: header is not featured in the overview information; therefore you can determine the number of newsgroups an article is crossposted to only from the Xref: header. If "create_all_links" is set to 1, fetchnews will store articles in all newsgroups which they are posted to, making all these newsgroups turn up in the Xref: header.
groupexpire = a.news.group 7As outlined above, texpire will expire threads after "expire" days. If you want to adjust expiry times for certain groups, you may use the "groupexpire" parameter to do just that. You can specify groups or use wildcards; for example
groupexpire = *.announce 30will affect expiry times of all groups ending with ".announce".
filterfile = /etc/leafnode/filtersIf you want to employ filtering on incoming messages, you have to specify the path where the filterfile can be found. The format of the filterfile is described in the next chapter.
timeout_short = 2These two parameters determine how quickly a group is unsubscribed by leafnode after you have stopped reading it. If you have looked into the group only once, subscription is stopped after "timeout_short" days; if you have read it more regularly, subscription is stopped after "timeout_long" days. (You can stop subscription immediately by removing the corresponding file in /var/spool/news/interesting.groups/).
timeout_long = 5
timeout_active = 90By default, fetchnews will re-read active files from the upstream server every 90 days. This interval can be changed by setting "timeout_active" to a different value. Re-reading the active file frequently will keep it a little bit smaller but will increase the on-line time.
delaybody = 1This option switches fetchnews into a mode where only the headers of articles are fetched for visual inspection. Only the articles read in the newsreader will be retrieved the next time fetchnews is called. This can save a huge amount of disk space and download time but requires more manual intervention on the user side.
groupdelaybody = some.news.groupIf you want delaybody mode only for selected groups, you can enable this download mode for one specific group. The global delaybody switch above causes all groups to be treated that way. Use one line per group pattern.
debugmode = 260This option forces the leafnode programs into logging lots of information via the syslog daemon. It is only useful if you want to hunt down bugs. See config.example for an explanation of the number here.
The filter file format is currently described in fetchnews(5). Type man 5 filterfile or man -s 5 filterfile to see the description.
From version 2.0 on, Leafnode is able to handle local newsgroups. Local newsgroups are groups that exist only on your local server but not on upstream servers.
To create a local newsgroup, you have to think of a newsgroup name which should not exist on any of your upstream servers. It is therefore a good idea to start a new top-level hierarchy. You should also make up a description for your newsgroup.
If you choose a newsgroup name which exists already on an upstream server, the newsgroup is not treated as a local one.
Next, you write the name, status and description into the file /etc/leafnode/local.groups using your preferred text editor, which must not mangle TABs to SPACEs. The file should consist of lines in the format
# Comment lines are allowed, with a hash at the beginning of a line. # # However, no white space may precede the hash mark, and empty lines # are not valid. news.group.name<TAB>status<TAB>description(replace <TAB> with a TAB character!)
The first column of each line is taken as the newsgroup name; the second as the status (y for "may be posted to", m for "moderated" -- see below for moderator configuration), the third column of the line is interpreted as description. For example, to set up a newsgroup "local.leafnode" which deals with Leafnode's internals, you would put a line
local.leafnode<TAB>y<TAB>Local leafnode user groupinto /etc/leafnode/local.groups. (If your configuration does not reside in /etc/leafnode, replace this part of the pathname with the appropriate directory.)
From version 2.0 on, Leafnode also handles moderated newsgroups. These are newsgroups which only certain people may post into, and articles which a regular (non-moderator) user posts, are mailed to the moderator.
External moderated newsgroups are handled by the upstream servers.
To configure the moderators for local moderated groups, an INN-compatible "moderators" file is used. It is named /etc/leafnode/moderators and has the following format:
pattern:moderator
Empty lines and lines that start with a hash character (#) are considered comment lines and are ignored.
The pattern is a normal wildmat pattern, which means that it's a SHELL pattern, the most useful character is the asterisk (*) which matches any sequence of characters. The moderator given on that line applies to all groups that the pattern matches. Should multiple lines match a group, the first match in the file "wins", the second and subsequent patterns are not taken into account. So put the more specific patterns first.
The moderator is a regular internet mail address, with the exception that the first occurrence of "%s" is replaced with the newsgroup name, with dots (.) converted to dashes (-) for INN compatibility.
Example:
# This is a comment line # # special moderator, hans@example.com is mailed all articles for # local.special local.special:hans@example.com # moderator for all other local groups: local.*:egon+%s@example.net # that means: # mail postings for local.test to egon+local-test@example.net # mail postings for local.video to egon+local-video@example.net # # Note: if you put local.special below local.*, local.special will be # ignored.
If you want to uninstall leafnode (e.g. because you want to replace it with another newsserver) and have a Makefile available, you can achieve this by doing "make uninstall".
Do not uninstall an old version of leafnode before updating.
See the file FAQ.
Leafnode versions through 1.4 were written by Arnt Gulbrandsen <agulbra@troll.no> and are copyright 1995 Troll Tech AS, Postboks 6133 Etterstad, 0602 Oslo, Norway, fax +47 22646949.
Leafnode versions 1.5 up to 1.9.19 and 2.0b1 to 2.0b8 were written by Cornelius Krasel <krasel@wpxx02.toxi.uni-wuerzburg.de> and are copyright 1997-2001.
Leafnode versions 1.9.20 and up were written by Matthias Andree <matthias.andree@gmx.de> and Ralf Wildenhues <ralf.wildenhues@gmx.de> and are © copyright 2002 - 2003.
Leafnode versions 2.0b8_ma and 2.0.0.* were written by Matthias Andree <matthias.andree@gmx.de>, Ralf Wildenhues <ralf.wildenhues@gmx.de> and Jörg Dietrich <joerg@dietrich.net> and are © copyright 2001 - 2003.
Major modifications were made by
Randolf Skerka <Randolf.Skerka@gmx.de>
Kent Robotti <robotti@erols.com>
Markus Enzenberger <enz@cip.physik.uni-muenchen.de>
Matthias Andree <matthias.andree@gmx.de>
Jörg Dietrich <joerg@dietrich.net>
Stefan Wiens <s.wi@gmx.net>
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
The getaline() and getline() routines are Copyright (c) 2000-2002 Matthias Andree <matthias.andree@gmx.de>. They are licensed under the GNU Lesser General Public License (GNU LGPL) 2.1. A copy of the LGPL is provided in the file COPYING.
The wildmat() routine is Copyright (c) 1986-1991 Rich $alz <rsalz@osf.org>. The original copyright notice, taken from INN 2.2.2, follows:
Redistribution and use in any form are permitted provided that the following restrictions are met:THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
- Source distributions must retain this entire copyright notice and comment.
- Binary distributions must include the acknowledgement ``This product includes software developed by Rich Salz'' in the documentation or other materials provided with the distribution. This must not be represented as an endorsement or promotion without specific prior written permission.
- The origin of this software must not be misrepresented, either by explicit claim or by omission. Credits must appear in the source and documentation.
- Altered versions must be plainly marked as such in the source and documentation and must not be misrepresented as being the original software.
The replacement vsnprintf() function was written by Theo de Raadt and is Copyright (c) 1997 under the following restrictions:
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.