| < Contributors | Russ Allbery > Software > INN > INN 2.5 Documentation |
$Id$
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.
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 -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.)
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).
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.
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.
Start innd by running pathbin/rc.news 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 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.
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'.
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, as well as pure Perl.
For instance, a line for the newsusers database corresponding to the
user user with the password pass would be user:LIfOpbjNaEQYE
as obtained by the following commands::
% htpasswd -nbd user pass
user:LIfOpbjNaEQYE
% 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 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 -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 initiate a TLS connection. However, such clients are not widespread yet.
| < Contributors | Russ Allbery > Software > INN > INN 2.5 Documentation |