INN Installation Checklist

Table of Contents

1. Introduction
2. Setup
3. Compile
4. Configure
5. Run
6. Feeds
7. Readers

Introduction

$Id: checklist.pod 8892 2010-01-17 12:37:25Z 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 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 <ftp://ftp.isc.org/isc/inn/> or a snapshot from <ftp://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 <ftp://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 <ftp://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 -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.

  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 -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 initiate a TLS connection. However, such clients are not widespread yet.