=head1 Introduction

$Id: checklist.pod 5909 2002-12-03 05:17:18Z vinocur $

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.

=head1 Setup

=over 4

=item *

Make sure there is a "news" user (and a "news" group)

=item *

Create a home directory for news (perhaps F</usr/local/news/>) and make
sure it (and 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 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, because C<make install> will set the permissions
correctly.  After that point, though, you may want to C<su news> to
avoid creating any files as root.  (For routine maintenance once INN is
working, you can generally be root.)

=item *

If necessary, add F<~news/bin> to the news user's path and F<~news/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
manpages are very useful.)

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

For bash, try:

    PATH=~news/bin:$PATH
    export PATH
    MANPATH=~news/man:$MANPATH
    export MANPATH

or csh:

    setenv PATH ~news/bin:$PATH
    setenv MANPATH ~news/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
manpages); 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.

=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
F<inn.conf> if you change your mind).

You probably want C<--with-perl>.  If you're not using NetBSD with
cycbuffs or OpenBSD, perhaps C<--with-tagged-hash>.  You might want to
compile in SSL and Berkeley DB, if your system supports them.

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

    su
    make install

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

=back

=head1 Configure

=over 4

=item *

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

=item *

Now it's time to work on the files in F<~news/etc/>.  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 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
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 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 "trash" storage method.

=item *

The default options in F<expire.ctl> work fine if you have cycbuffs, if
not, configure to suit.

=item *

Check over F<moderators> and F<control.ctl>.

=item *

Run F<~news/bin/inncheck> and fix anything noted.

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

Import an active file (F<~news/db/active>) and run inncheck again.
Change where noted (there's a gotcha in the ISC's active list 000000
000000 (whatever number of zeros) should be 0000000 00000001).

=item *

Create empty initial db files.  Be sure these end up owned by news.

    cd ~news/db

    touch newsgroups
    touch active.times

    touch history
    ~news/bin/makedbz -i
    mv history.n.hash  history.hash
    mv history.n.index history.index
    mv history.n.dir   history.dir

    chmod 644 *

=item *

Create the cron jobs and make the changes to your system's
F<syslog.conf> as noted in INSTALL.  Also create the cron job for
nntpsend if you've chosen that over innfeed.

Create the log files.

=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 inn by running ~news/bin/rc.news I<as the news user>.

Check F<~news/log/news.notice> to see if everything went well, also use
C<ps> to see if innd is running.

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

=item *

C<man ctlinnd> now; you'll use C<ctlinnd reload> as you complete your
configuration.

=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 "reason" is some text that
will show up in the logs, anything will do).

=item *

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

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

Then C<ctlinnd reload newsfeeds reason>.

=item *

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

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

    auth "foreignokay" {
        auth: "ckpasswd -d ~news/db/newsusers"
        default: "<unauthenticated>"
    }

There is a perl script in the ckpasswd man page if you want to do
authentications by password and have the appropriate libraries.  Copy it
to ~news/bin, 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 C<htpasswd> tool also works
just fine to create INN password files.

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 nnrpd launches it reads its configuration from disk.

=back