0. Since version 1.9.17ma1, leafnode has been using GNU automake. All
   standard targets exist. If you want to hack on leafnode, do remember
   to use --enable-maintainer-mode in ./configure below in step #1.

1. (as user) Since version 1.9, leafnode uses GNU autoconf to determine what
   machine it will run on. Type

	sh ./configure

    to create an appropriate Makefile and config.h .  If you have and
    want to use IPV6, invoke "configure" with the --with-ipv6 flag.

    Remember that when you are updating a previously installed version of
    leafnode, you need to configure the new version of leafnode to
    overwrite the old one. You do this with the "configure --prefix"
    option. For example, if leafnode had been previously installed in
    /opt, you would configure leafnode with the command "./configure
    --prefix=/opt".  Further options are --with-spooldir, --sysconfdir,
    --with-lockfile to determine the location of the spooldir (defaults
    to /var/spool/news), configuration directory (defaults to
    /etc/leafnode if prefix is unset, PREFIX/etc otherwise) and of the
    lock file (defaults to /var/lock/fetchnews.lck)

2.  (as user) Type

	make

    There should be no errors. On Solaris, you may get some "function
    declaration isn't a prototype" warnings. These are harmless. Expect
    other warnings on Solaris as well, from experience: the older your
    OS, the more.

    Then type

	make check

    All tests must pass, otherwise, ask on the leafnode mailing list for
    help.

3a. (as root) Create a "news" user if you don't have one.

3b. (as root) Create an alias in your mail system to forward mail
    addressed to "news" to the real user who looks after leafnode.

    If you run qmail: get and install the fastforward package. It is
    available from qmail distribution sites.

    Find your aliases file (/etc/aliases or /etc/mail/aliases), add a
    line "news: joe" (assuming joe looks after your leafnode) and then
    type
	newaliases.

4.  (as root) Type
	make install

5.  (as root) If you are updating leafnode from a version before 1.9.3
    (including all 1.9.3 beta versions before 1.9.3b5), "make
     update". This will call the update.sh shell script provided with
    leafnode. Your groupinfo file will be reformatted and some other
    files will be moved around. In case something goes wrong, you will
    find your old groupinfo file in
    /var/spool/news/leaf.node/groupinfo.old. If everything works out
    correctly, you can delete this file (it is not needed any more).

6.  (as root) Edit $(sysconfdir)/config ($(sysconfdir) defaults to
    /etc/leafnode if it is unset and prefix is unset, to $prefix/etc if
    prefix is set.  For documentation, see config.example and
    leafnode(8). 

6a. It is absolutely necessary to change the "server" parameter to point
    it to your upstream news server (generally the one of your IP provider).

6b. Make sure $NNTPSERVER or /etc/nntpserver points to your own host so
    clients will talk to leafnode rather than try to go to the upstream
    server.  If you want to use filtering of the incoming spool, see "FILTER
    FILE" in the README.

6c. You definitely want to use "initialfetch = 100" or something in the
    config file, to prevent fetchnews from filling up your disk when
    hitting a high-volume newsgroup.

7.  (as root) If your system does not have a fully qualified domain name
    (Debian default installs belong to this group of systems), edit
    /etc/hosts to add one, for example, if your /etc/hosts has a line

    192.168.0.1 debian

    make that

    192.168.0.1 debian.example.com debian

    IMPORTANT: debian.example.com must be replaced by a real fully
    qualified domain name. Making up host names will cause trouble, like
    posts being discarded at the upstream server, posts being discarded
    when Message-IDs of different postings clash and other troubles.

8.  (as news) Set up a cron job to run texpire every night or maybe every
    week.  Here is my crontab line, which runs nightly:

0 4 * * * /usr/local/sbin/texpire

    I 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/texpire

    tells cron to run texpire at 4am Monday morning. See man crontab for
    details.

9.  Make sure fetchnews is run at the appropriate time.  If you have a
    full-time link, run it out of cron (as "news" again), if not, run it
    when your connection to the net is established.  If it is run as
    root, it will change user to "news". If you use PPP, you can probably
    run fetchnews from /etc/ppp/ip-up.local or /etc/ppp/ip-up.

10. (as root) Edit /etc/hosts.deny to add a line:
    leafnode: ALL

    Edit /etc/hosts.allow to add a line:
    leafnode: 127.0.0.1

    If you run leafnode in a LAN, you can of course add netmasks for the
    hosts in your LAN, like (still to /etc/hosts.allow):

    leafnode: 127.0.0.1 192.168.0.0/255.255.255.0

    See man hosts_access(5) and hosts_options(5) for more information.

11. How leafnode is actually started, depends on what facilities systems
    provide for. USE EXACTLY (ONLY) ONE OF THESE SUGGESTIONS IN THE
    SUBSECTIONS OF THIS SECTION. IF IN DOUBT, GO FOR 11c with
    tcpserver's native access control (the line with -x and with
    tcprules).

    A WORD OF WARNING: regardless of how you do access-control, do not
    use name-based access control unless you know what you're doing. Use
    IPs (like 1.2.3.4) instead. Do not use names that point to dynamic
    IP addresses or use dynamic IP addresses for access control!

    a) Traditionally, the software to start network daemons on demand
    was inetd, and it still is on e. g. HP-UX 10, Solaris 8, *BSD and
    others -- see section 11a below. However, most inetd implementations
    have design flaws, so this way is only recommended on FreeBSD for now.
    The configuration file for inetd is usually /etc/inetd.conf or
    /etc/inet/inetd.conf.

    b) Then, xinetd has joined in and is now the default on Red Hat
    Linux, it is described in section 11b.

    c) Another possibility is to use Dan J. Bernstein's daemontools and
    ucspi-tcp packages, but like all DJB-ware, their installation is
    easy, but different from that of most other packages. The
    installation is described in section 11c (automatic) and 11d
    (manual).

11a.ONLY WHEN USING INETD (Red Hat users: your system uses xinetd, look
    below at 11b. instead)

    (as root) Edit /etc/inetd.conf so that $(BINDIR)/leafnode is executed
    for incoming NNTP connections.  Here is my inetd.conf line (insert
    it at the leftmost column, without leading spaces!):

    nntp stream tcp nowait news /usr/sbin/tcpd /usr/local/sbin/leafnode

    This starts leafnode for all connections on the nntp port, subject to
    /etc/hosts.allow and /etc/hosts.deny screening.  If you don't have
    /usr/sbin/tcpd, fetch the tcp_wrappers package and install it.

    Using leafnode without tcpd is not supported and opens your computer
    to abuse (even happens on modem lines that are only connected during
    the fetch!)

    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`

    Proceed to step #12.

11b.ONLY WHEN USING XINETD
    (as root)

    xinetd versions before 2.3.3 are not supported. It may or may not
    work for you with older versions.

    More documentation is available in the xinetd and xinetd.conf
    manual pages. Try man xinetd.

     a. check if your /etc/xinetd.conf has a "includedir /etc/xinetd.d"
        line. If it has, store the configuration snippet below as
	/etc/xinetd.d/leafnode. If your xinetd.conf does NOT have that
	includedir line, append the configuration snippet to your
	/etc/xinetd.conf.

     b. After you have figured which of the two files to edit (or
        create), add this to the xinetd configuration file:

	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
	}

    This allows at most 7 leafnode connections. At most 3 connections
    are allowed from the same client host at the same time. Adjust these
    figures if necessary.

    Send xinetd a USR2 signal. Figure its PID with
    ps ax | egrep '[x]inetd' on Linux or *BSD or
    ps -ef | egrep '[x]inetd' on SysV machines (Solaris), then do:
    kill -s USR2 12345, replacing 12345 with the PID you just found
    out.

    Proceed to step #12.

11c. (as root) AUTOMATIC INSTALLATION WITH DAEMONTOOLS AND UCSPI-TCP

    Scope: this installation will configure to run tcpserver for
    leafnode, with native ("tcprules") access control that (by default)
    allows connections from 127.0.0.1 and listens on that address.

    If you want to use hosts.allow/hosts.deny, please go to section #11d.

    a. Before you can proceed, you need to install Dan J. Bernstein's
    daemontools and ucspi-tcp, available from
    http://cr.yp.to/daemontools.html and http://cr.yp.to/ucspi-tcp.html
    -- for IPv6 support, you'll also need Felix von Leitner's IPv6 patch
    from http://www.fefe.de/ucspi/. Make sure that svscan is running.

    b. Run setup-daemontools.sh. This will configure everything.
    leafnode is ready to accept connections from localhost (127.0.0.1).

    c. Configuration hints that relate to this setup (listening IP,
    access control, maximum number of clients) are in README-daemontools.

11d. (as root) MANUAL INSTALLATION WITH DAEMONTOOLS AND UCSPI-TCP
    a. Before you can proceed, you need to install Dan J. Bernstein's
    daemontools and ucspi-tcp, available from
    http://cr.yp.to/daemontools.html and http://cr.yp.to/ucspi-tcp.html
    -- for IPv6 support, you'll also need Felix von Leitner's IPv6 patch
    from http://www.fefe.de/ucspi/

    b. create a "log" directory in your leafnode config directory:
    mkdir /etc/leafnode/log

    c. create a "run" file in this directory with your favourite text
    editor:
    #! /bin/sh
    exec logger -p daemon.notice -t leafnode

    d. chmod 755 log/run

    e. create a "run" file in your leafnode configuration directory.
    Here are two possibilities: one will use the regular hosts.allow and
    hosts.deny mechanism, the other will use tcpserver's native access
    control.

    FOR hosts.allow, use something similar to this:
    #! /bin/sh
    exec 2>&1
    exec /usr/local/bin/tcpserver -c10 -l0 -H -v 127.0.0.1 119 \
    /usr/local/bin/setuidgid news /usr/local/bin/argv0 /usr/sbin/tcpd \
    /usr/local/sbin/leafnode

    You may need to adjust the paths if your software is in a
    non-standard location, and you must of course replace 127.0.0.1 with
    an IP of the leafnode computer that is visible in your entire LAN.

    The options are explained below.

    FOR tcpserver's native access control, use something similar to
    this:
    #! /bin/sh
    exec 2>&1
    exec /usr/local/bin/tcpserver -c10 -l0 -H -v -x nntp.cdb \
    127.0.0.1 119 \
    /usr/local/bin/setuidgid news /usr/local/sbin/leafnode

    As above, adjust the paths and the IP.

    -c10 means: allow at most 10 connections at the same time. -l0
    means: do not look up the local hostname, but use "0" instead
    (leafnode will do that by itself rather than looking at tcpserver's
    data). -H means: do not look up the remote computer's name (leafnode
    will do that as well). -v means: log connections. -x file means: use
    file as access control data base (compiled by tcprules) and refuse
    connections if it's missing. More information is in
    http://cr.yp.to/ucspi-tcp/tcpserver.html

    f. ONLY if using tcpserver's native access control:
    Create a nntp.rules file that defines the access, an example:
    joe@1.2.3.4:allow
    fool@192.168.0.4:deny
    192.168.0.:allow
    :deny

    g. ONLY if using tcpserver's native access control:
    compile the nntp.rules file into nntp.cdb:
    tcprules nntp.cdb nntp.tmp <nntp.rules
    YOU MUST REPEAT THIS EVERY TIME YOU CHANGE THE RULES FILE!
    (tcpserver will - just as tcpd - detect changes to the rules file
    by itself, no need to SIGHUP it).

    h. chmod 755 run

    i. create a symlink into /service:
    ln -s `pwd` /service/

    svscan should notice the new leafnode service within 5 seconds and
    start it.

12. (as root or news) Run fetchnews.  The first run will take some time
    since fetchnews reads a list of all newsgroups from your upstream
    server.  With an 28.8 modem, it can take as long as 60 minutes
    (depending on how many newsgroups your provider offers). To see
    fetchnews working, run it with -vvv. If you update leafnode from a
    version previous to 1.6, the format of the groupinfo file has
    changed. You should therefore run fetchnews with the parameter -f.

13. (as user) Read news using an NNTP client (with $NNTPSERVER or
    /etc/nntpserver pointing to your own host). Select the groups you
    want to read in the future. You will find them empty except a
    default article.  Reading this article is necessary with some
    newsreaders to select the groups for further fetching.

    After this, you should have empty files in
    /var/spool/news/interesting.groups/ for every group you want to
    read.

14. (as root or news) Run fetchnews again. This run should pick up all
    the groups you want to read.

15. Note: for access from remote sites, outside of your LAN, additional
    leafnode configuration is required since leafnode 1.9.23. See README
    and config.example for details.

Cornelius Krasel <krasel@wpxx02.toxi.uni-wuerzburg.de>
Matthias Andree <matthias.andree@gmx.de>
