Introduction

    $Id: checklist.pod 10257 2018-03-08 16:17:55Z iulius $

    This is an installation checklist written by Rebecca Ore, intended to be
    the beginning of a different presentation of the information in INSTALL,
    since getting started with installing INN can be complex.  Further
    clarifications, updates, and expansion are welcome.

Setup

    *   Make sure there is a "news" user (and a "news" group to which the
        "news" user belongs).  If necessary, you can use:

            adduser --group --home /usr/local/news news

        where /usr/local/news is the home directory for the "news" user. 
        This directory will be passed to configure via the --prefix option. 
        It will also be set as *pathnews* in inn.conf.

    *   Create a local mail alias for "usenet" (editing your aliases file
        for instance).

    *   Make sure the directory /usr/local/news and its subdirectories are
        owned by "news", group "news".

        You want to be careful that things in that directory stay owned by
        "news" -- but you can't just "chown -R news:news" after the install,
        because you may have binaries that are SUID root.  You can do the
        build as any user, but you need to be root when doing "make install"
        so as to set the permissions correctly.  After that point, though,
        you may want to "su news -s /bin/sh" to avoid creating any files as
        root.  (For routine maintenance once INN is working, you can
        generally be root.  However, it is always better to be accustomed to
        doing that as the news user.)

    *   If necessary, add ~news/bin (that is to say *pathbin*) to the news
        user's path and ~news/share/man (that is to say
        *pathnews*/share/man) to the news user's MANPATH in your shell
        config files.  (You may want to do this, especially the second part,
        on your regular account; the man pages are very useful.)

        You can do this now or later, but you will certainly want the man
        pages to help with configuring INN.

        For bash, try:

            PATH=<pathbin in inn.conf>:$PATH
            export PATH
            MANPATH=<pathnews in inn.conf>/share/man:$MANPATH
            export MANPATH

        or csh:

            setenv PATH <pathbin in inn.conf>:$PATH
            setenv MANPATH <pathnews in inn.conf>/share/man:$MANPATH

        although if you don't already have MANPATH set, the above may give
        an error or override your defaults (making it so you can only read
        the news man pages); if "echo $MANPATH" does not give some
        reasonable path, you'll need to look up what the default is for your
        system (such as /usr/man or /usr/share/man).

Compile

    *   Download the INN tarball and unpack.  Make sure that you download
        the last release from <https://ftp.isc.org/isc/inn/> or a snapshot
        from <https://ftp.isc.org/isc/inn/snapshots/>.

    *   Work out configure options ("./configure --help" for a list).  If
        you aren't working out of /usr/local/news, or want to put some files
        on a different partition, you can set the directories now (or later
        in *pathnews* in inn.conf if you change your mind).  By default,
        --prefix=/usr/local/news is used.

        You probably want --with-perl.  If you're not using NetBSD with
        cycbuffs or OpenBSD, perhaps --with-tagged-hash.  You might want to
        compile in TLS/SSL and Berkeley DB, if your system supports them. 
        You will need to have the relevant external libraries to compile
        (depending on whether you use OpenSSL for TLS/SSL access to your
        news server, GnuPG to verify the authenticity of Usenet control
        messages, Perl, Python, etc.).

            ./configure --with-perl ...
            make

            su
            make install

        (If you do the last step as root, all of the ownerships and
        permissions will be correct.)

        Note that if you update a previous installation of INN, you should
        use "make update" instead of "make install" to keep your
        configuration files.

        If you wish to use TLS/SSL, you can use "make cert" to generate a
        certificate and a private key.

Configure

    *   Find INSTALL and open a separate window for it.  A printout is
        probably a good idea -- it's long but very helpful.  Any time the
        instructions below ask you to make a decision, you can probably find
        help in INSTALL.

    *   Now it's time to work on the files in ~news/etc (the default
        *pathetc* location set in inn.conf).  Start with inn.conf; you must
        fill in the default moderators address, your fully qualified domain
        names and path.  Fill in all the blanks.  Change the file descriptor
        limits to something like 500.

    *   If using cycbuffs (the CNFS storage method), open cycbuff.conf in
        one window and a shell in another to create the cycbuff as described
        in INSTALL.  As you create them, record in cycbuff.conf the paths
        and sizes.  Save paths and sizes in a separate text file on another
        machine in case you ever blow away the wrong file.

        Name the metacycbuff, then configure storage.conf.

    *   In storage.conf, be sure that all sizes of articles can be
        accomodated.  If you want to throw away large articles, do it
        explicitly by using the "trash" storage method (you can also set a
        lower *maxartsize* in inn.conf).

    *   The default options in expire.ctl work fine if you have cycbuffs; if
        not, configure to suit (depending on your disk space and your
        interest in some hierarchies, you can define how long you keep
        articles in your news spool).

    *   Check over moderators and control.ctl.  You may want to also
        configure the process of newsgroup control messages (see the
        corresponding section in INSTALL).

    *   Run "<pathbin in inn.conf>/inncheck -a -v -f --pedantic --perm" and
        fix anything noted: inncheck gives a rough check on the
        appropriateness of the configuration files as you go.  (It's the
        equivalent of "perl -cw yourfile.pl" for Perl scripts.)

        Note that inncheck is very conservative about permissions; there's
        no reason most of the config files can't be world-readable if you
        prefer that.

    *   You can now import an active file (*pathdb in inn.conf*/active) and
        run inncheck again.  You may want to look at
        <https://ftp.isc.org/pub/usenet/CONFIG/active> and only keep the
        lines corresponding to the newsgroups you are interested in.  Also
        import a newsgroups file which contains the descriptions of these
        newsgroups (see for instance
        <https://ftp.isc.org/pub/usenet/CONFIG/newsgroups>).

        Note that it is not necessary to do that now.  INN is shipped with
        minimal active and newsgroups files and you can add newsgroups later
        with "ctlinnd newgroup" or actsync.

        In case you need to create empty initial database files, import an
        active file (owned by "news") and execute as the news user:

            cd <pathdb in inn.conf>

            touch newsgroups
            touch active.times

            touch history
            <pathbin in inn.conf>/makedbz -i
            mv history.n.hash  history.hash
            mv history.n.index history.index
            mv history.n.dir   history.dir

            chmod 644 *

        (However, it is not necessary to do that since INN takes care of
        these files during the setup.)

    *   Create the cron jobs (especially news.daily), the log files, and
        make the changes to your system's syslog.conf as noted in INSTALL. 
        Also create the cron job for nntpsend if you've chosen that over
        innfeed.

    *   For the time being, we can see if everything initially works without
        worrying about feeds or reader access.

Run

    *   Start innd by running *pathbin*/rc.news as the news user.  It is
        also what you should launch in your init scripts:

            su news -s /bin/sh -c <pathbin in inn.conf>/rc.news

        Check *pathlog*/news.notice to see if everything went well; also use
        "ps" to see if innd is running.

        "telnet localhost 119" and you should see either a welcome banner or
        a "no permission to talk" message.  If not, investigate.

    *   "man ctlinnd" now; you'll use "ctlinnd reload" as you complete your
        configuration.  You can also see whether "ctlinnd checkfile" reports
        any problems.

Feeds

    All of this can be done while INN is running.

    *   To get your incoming feeds working, edit incoming.conf.  When done,
        "ctlinnd reload incoming.conf 'reason'" (where "reason" is some text
        that will show up in the logs -- anything will do).

    *   To get your outgoing feeds working, decide whether to use innfeed or
        nntpsend.  Edit newsfeeds and either innfeed.conf or nntpsend.ctl.

        In newsfeeds, if using innfeed, use the option which doesn't require
        you to do a separate innfeed configuration unless you know more than
        I do.

        Then "ctlinnd reload newsfeeds 'reason'".

Readers

    *   In readers.conf, remember that auth and access blocks can be
        separated.

        Begin with auth.  Your auth for password users could look like this:

            auth "foreignokay" {
                auth: "ckpasswd -d <pathdb in inn.conf>/newsusers"
                default: "<unauthenticated>"
            }

        There is a Perl script in the ckpasswd(8) man page if you want to do
        authentications by password and have the appropriate libraries. 
        Copy it to *pathbin*, name the file something like makepasswd.pl and
        change the internal paths to whatever you're using and wherever
        you're putting the newsusers database.  The standard Apache htpasswd
        tool also works just fine to create INN password files.  For
        instance, a line for the newsusers database corresponding to the
        user "user" with the password "pass" would be "user:LIfOpbjNaEQYE"
        as obtained by the following command:

            % htpasswd -nbd user pass
            user:LIfOpbjNaEQYE

        In case htpasswd is not installed or if you do not want to depend on
        it, another command involving Perl does a similar job:

            % perl -e 'print "user:".crypt("pass", "LI")."\n";'
            user:LIfOpbjNaEQYE

        Follow with the access stanzas.  Something for people with
        passwords:

            access "generalpeople" {
                users: "*"
                newsgroups: "*,!junk,!control,!control.*"
            }

        And then something like one of the following two, depending on
        whether unauthenticated users get any access:

            access "restrictive" {
                users: "<unauthenticated>"
                newsgroups: "!*"
            }

            access "readonly" {
                users: "<unauthenticated>"
                read: "local.*"
                post: "!*"
            }

        You don't need to reload anything after modifying readers.conf;
        every time an nnrpd launches, it reads its configuration from disk.

    *   If you wish to use TLS/SSL for your readers, you can either use the
        same readers.conf file or use two different files (for instance
        readers.conf and readers-ssl.conf).  The syntax is similar for both
        these files.  You then need to start a second nnrpd to listen to
        these connections to NNTPS port 563 and put something like that in
        your init scripts:

            su news -s /bin/sh -c '<pathbin>/nnrpd -D -c <pathetc>/readers-ssl.conf -p 563 -S'

        Note that a news client which supports the STARTTLS command can also
        use the conventional NNTP port 119 to dynamically upgrade from
        unencrypted to TLS-protected traffic during an NNTP session. 
        However, this practice is discouraged in favour of using the
        separate port 563.  See nnrpd(8) for more information about TLS
        support.

