Introduction

    This is an installation checklist initially 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.

    This checklist explains the steps to follow for a standard installation
    with reasonable defaults.

    The first part of this documentation can be skipped if INN is already
    installed on your system.  Some distributions provide a package, which
    should be used in preference of building from scratch.

Compile (when installing from scratch)

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

    *   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.

    *   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.  You might want to compile in TLS and
        SQLite, if your system supports them.  You will need to have the
        relevant external libraries to compile (depending on whether you use
        OpenSSL for TLS access to your news server, libcanlock to verify the
        authenticity of cancel articles, Perl and/or Python for spam and
        abuse filtering, etc.) and to correctly set the right paths to
        external programs (like for GnuPG to verify the authenticity of
        Usenet control messages).

            ./configure --with-perl --with-openssl --with-sqlite3 --with-canlock ...
            make

            su
            make install

        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, you can use "make cert" to generate a
        self-signed certificate and a private key.

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

        (If you ran "make install" as root, all of the ownerships and
        permissions should be correct.)

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

Parameter

    *   Find INSTALL and open a separate window for it.  A printout is
        probably a good idea -- it's long but very helpful.  You'll find in
        INSTALL more information and background about each step in this
        document.

    *   Now it's time to work on the configuration files in your *pathetc*
        directory.  Start with inn.conf; you must fill in or check
        *organization* (which can be commented if you do not want to add a
        default Organization header field to every post from your server),
        your path identity in *pathhost* (usually your fully qualified
        domain name), the NNTP server to use for posts (*server* is commonly
        set to "localhost"), the maximum size of articles you accept
        (*maxartsize*, set to 1 MB by default), and the abuse e-mail address
        (*complaints*).

        To store overview data, start with tradindexed overview method,
        already set by default in the *ovmethod* parameter, but know that
        there are various other options with their own pros and cons, as
        detailed in INSTALL.  (Especially, the ovsqlite overview method is
        also a good choice if your INN installation has SQLite support.)

    *   To store articles, start with traditional spool (named tradspool),
        but know that there are various other options with their own pros
        and cons, as detailed in INSTALL.

        The default storage.conf file is already parameterized to use that
        storage method.

    *   Configure in expire.ctl how long articles should be kept in your
        news spool.  The default of 90 days maybe does not fit your needs. 
        You can use different values for specific newsgroups or hierarchies
        depending on your interest in them.

    *   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.

        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://downloads.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://downloads.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 (have a look at the examples at
        the end of the actsync(8) man page for how to use it concretely).

    *   Review the subscriptions file, and update it according to the
        newsgroups you carry on your news server.  This file, which may be
        empty, is used by a few news clients to suggest newsgroups on the
        first time they connect to a news server.

    *   Create secrets in inn-secrets.conf to enable the generation of
        Cancel-Lock header fields in articles posted via your news server. 
        Other news servers will then be able to verify the authenticity of
        possible further cancels for these articles.  See the inn-secrets(5)
        man page for how to generate secrets.

    *   Create the cron jobs (especially news.daily), the log files, and
        make the changes to your system's syslog.conf as noted in INSTALL.

    *   Create a local mail alias for "usenet" (editing your /etc/aliases
        file for instance).  It will be useful for daily Usenet reports sent
        by news.daily and other parts of the system.

    *   If necessary, add the path to INN's binaries (as set in *pathbin* in
        inn.conf) to the news user's path and the path to INN's man pages
        (usually *pathnews*/share/man) to the news user's "MANPATH" in your
        shell config files.  (You may also 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 to add in your ~/.bashrc file:

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

        or csh in your ~/.cshrc file:

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

    *   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 so that INN starts
        when your server boots:

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

        Samples of init.d and systemd init scripts are present in the
        contrib directory (and certainly already set up on your system if
        you installed INN with a package for your distribution).

    *   Check news.crit, news.err and news.notice in your *pathlog*
        directory 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.

        Send "QUIT" to end the telnet connection.

    *   When you complete your configuration, do not forget to reload
        changed files (see the "ctlinnd reload" command in the ctlinnd(8)
        man page).  You can also see whether "ctlinnd checkfile" reports any
        problems.

Additional Configuration

    The following features are commonly used.  Though not mandatory, they
    are recommended and can of course be set up later.

    *   You may want to configure the process of newsgroup control messages
        to keep your list of newsgroups up to date (search for PGPKEYS in
        INSTALL to find the Section explaining that).  Also see
        controlchan(8) for how to set up the newsfeeds entry.

    *   You may want to configure the process of NoCeM notices used to
        cancel unwanted articles like spam (see the perl-nocem(8) man page).

    *   You may want to install a spam and abuse filter.  Good choices are
        either Cleanfeed (a widely used Perl filter you can find at
        <http://www.mixmin.net/cleanfeed/>) or PyClean (also a great Python
        filter you can find at <https://github.com/crooks/PyClean>).

        You need to have an INN installation built with Perl and/or Python
        support to be able to use these filters.

    *   You may want to submit your Path header field statistics to
        <http://top1000.anthologeek.net/>.  Have a look at the ninpaths(8)
        man page to see how to do that.

Feeds

    All of this can be done while INN is running.

    *   The first step is to get a news feed.  You can ask for an external
        feed in the news.admin.peering newsgroup.  Several news
        administrators will certainly respond and gracefully provide you
        with a news feed.

    *   To get your incoming feeds working, edit incoming.conf.  When done,
        "ctlinnd reload incoming.conf 'reason'" to reload that file (where
        "reason" is some text that will show up in the logs -- anything will
        do).  You'll find examples in the incoming.conf(5) man page for how
        to set up this file.

    *   To get your outgoing feeds working, edit newsfeeds and innfeed.conf.
        When done, "ctlinnd reload newsfeeds 'reason'" and "ctlinnd flush
        innfeed!" to reload these configuration files.  You'll find examples
        in the newsfeeds(5) and innfeed.conf(5) man pages for how to set up
        these files.

Readers

    *   In readers.conf, remember that authentication and authorization are
        configured in different blocks.  You'll find useful examples in the
        readers.conf(5) man page.  Also have a look at the description of
        the -f flag in the ckpasswd(8) man page, if you need to set up a
        password file.

        You don't need to reload anything after modifying readers.conf;
        every time a news client connects to the server, a new nnrpd process
        is spawned and reads its configuration from disk.

    *   If you wish to use TLS for your readers, you can either use the same
        readers.conf file or use two different files (for instance
        readers.conf and readers-tls.conf).  The syntax is similar for both
        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-tls.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.

