=head1 Introduction

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

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.

=head1 Compile (when installing from scratch)

=over 4

=item *

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

=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 C<configure> via the B<--prefix> option.  It will
also be set as I<pathnews> in F<inn.conf>.

=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>.  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
C<make update> instead of C<make install> to keep your configuration files.

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

=item *

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

(If you ran C<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
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.)

=back

=head1 Parameter

=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.  You'll find in F<INSTALL> more
information and background about each step in this document.

=item *

Now it's time to work on the configuration files in your I<pathetc> directory.
Start with F<inn.conf>; you must fill in or check I<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 I<pathhost> (usually your
fully qualified domain name), the NNTP server to use for posts (I<server>
is commonly set to C<localhost>), the maximum size of articles you accept
(I<maxartsize>, set to S<1 MB> by default), and the abuse e-mail address
(I<complaints>).

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

=item *

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 F<INSTALL>.

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

=item *

Configure in F<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.

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

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

=item *

Review the F<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.

=item *

Create secrets in F<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.

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

=item *

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

=item *

If necessary, add the path to INN's binaries (as set in I<pathbin> in
F<inn.conf>) to the news user's path and the path to INN's man pages (usually
I<pathnews>/share/man) to the news user's C<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 F<~/.bashrc> file:

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

or csh in your F<~/.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 C<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>).

=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 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 F<contrib>
directory (and certainly already set up on your system if you installed INN
with a package for your distribution).

=item *

Check F<news.crit>, F<news.err> and F<news.notice> in your I<pathlog>
directory to see if everything went well; also use C<ps> to see if B<innd>
is running.

=item *

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

Send C<QUIT> to end the telnet connection.

=item *

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

=back

=head1 Additional Configuration

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

=over 4

=item *

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

=item *

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

=item *

You may want to install a spam and abuse filter.  Good choices
are either Cleanfeed (a widely used Perl filter you can find at
L<http://www.mixmin.net/cleanfeed/>) or PyClean (also a great Python filter
you can find at L<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.

=item *

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

=back

=head1 Feeds

All of this can be done while INN is running.

=over 4

=item *

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.

=item *

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

=item *

To get your outgoing feeds working, edit F<newsfeeds> and F<innfeed.conf>.
When done, C<ctlinnd reload newsfeeds 'reason'> and C<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.

=back

=head1 Readers

=over 4

=item *

In F<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 B<-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 F<readers.conf>; every time
a news client connects to the server, a new B<nnrpd> process is spawned and
reads its configuration from disk.

=item *

If you wish to use TLS 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-tls.conf>).  The syntax is similar for both 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-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.

=back

=cut
