=head1 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 F<INSTALL>,
since getting started with installing INN can be complex.  Further
clarifications, updates, and expansion are welcome.

=head1 Setup

=over 4

=item *

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

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

where F</usr/local/news> is the home directory for the C<news> user.
This directory will be passed to B<configure> via the B<--prefix>
option.  It will also be set as I<pathnews> in F<inn.conf>.

=item *

Create a local mail alias for C<usenet> (editing your F<aliases> file
for instance).

=item *

Make sure the directory F</usr/local/news> and its subdirectories
are owned by C<news>, group C<news>.

You want to be careful that things in that directory stay owned by
C<news> S<-- but> you can't just C<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 C<make install> so as to
set the permissions correctly.  After that point, though, you may want to
C<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.)

=item *

If necessary, add F<~news/bin> (that is to say I<pathbin>) to the news
user's path and F<~news/share/man> (that is to say I<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 C<echo $MANPATH> does not give some reasonable path,
you'll need to look up what the default is for your system (such as
F</usr/man> or F</usr/share/man>).

=back

=head1 Compile

=over 4

=item *

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

=item *

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

You probably want B<--with-perl>.  If you're not using NetBSD with
cycbuffs or OpenBSD, perhaps B<--with-tagged-hash>.  You might want to
compile in TLS/SSL and S<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
C<make update> instead of C<make install> to keep your configuration files.

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

=back

=head1 Configure

=over 4

=item *

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

=item *

Now it's time to work on the files in F<~news/etc> (the default I<pathetc>
location set in F<inn.conf>).  Start with F<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 C<500>.

=item *

If using cycbuffs (the CNFS storage method), open F<cycbuff.conf> in one
window and a shell in another to create the cycbuff as described in
F<INSTALL>.  As you create them, record in F<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 F<storage.conf>.

=item *

In F<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 C<trash> storage method (you can also set a lower I<maxartsize>
in F<inn.conf>).

=item *

The default options in F<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).

=item *

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

=item *

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

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

=item *

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

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

In case you need to create empty initial database files, import an F<active>
file (owned by C<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.)

=item *

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

=item *

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

=back

=head1 Run

=over 4

=item *

Start B<innd> by running I<pathbin>/rc.news B<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 I<pathlog>/news.notice to see if everything went well; also use
C<ps> to see if B<innd> is running.

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

=item *

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

=back

=head1 Feeds

All of this can be done while INN is running.

=over 4

=item *

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

=item *

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

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

Then C<ctlinnd reload newsfeeds 'reason'>.

=back

=head1 Readers

=over 4

=item *

In F<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 I<pathbin>, name the file something like F<makepasswd.pl>
and change the internal paths to whatever you're using and wherever
you're putting the newsusers database.  The standard Apache B<htpasswd>
tool also works just fine to create INN password files.  For instance,
a line for the newsusers database corresponding to the user C<user>
with the password C<pass> would be C<user:LIfOpbjNaEQYE> as obtained
by the following command:

    % htpasswd -nbd user pass
    user:LIfOpbjNaEQYE

In case B<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 F<readers.conf>; every
time an B<nnrpd> launches, it reads its configuration from disk.

=item *

If you wish to use TLS/SSL for your readers, you can either use the same
F<readers.conf> file or use two different files (for instance F<readers.conf>
and F<readers-ssl.conf>).  The syntax is similar for both these files.
You then need to start a second B<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.

=back

=cut
