doc/checklist

   1 Introduction
   2
   3     $Id: checklist 5912 2002-12-03 05:31:11Z vinocur $
   4
   5     This is an installation checklist written by Rebecca Ore, intended to be
   6     the beginning of a different presentation of the information in INSTALL,
   7     since getting started with installing INN can be complex.  Further
   8     clarifications, updates, and expansion are welcome.
   9
  10 Setup
  11
  12     *   Make sure there is a "news" user (and a "news" group)
  13
  14     *   Create a home directory for news (perhaps /usr/local/news/) and make
  15         sure it (and subdirectories) are owned by "news", group "news".
  16
  17         You want to be careful that things in that directory stay owned by
  18         "news" -- but you can't just "chown -R news.news" after the install,
  19         because you may have binaries that are SUID root.  You can do the
  20         build as any user, because "make install" will set the permissions
  21         correctly.  After that point, though, you may want to "su news" to
  22         avoid creating any files as root.  (For routine maintenance once INN
  23         is working, you can generally be root.)
  24
  25     *   If necessary, add ~news/bin to the news user's path and ~news/man to
  26         the news user's manpath in your shell config files.  (You may want
  27         to do this, especially the second part, on your regular account; the
  28         manpages are very useful.)
  29
  30         You can do this now or later, but you will certainly want the
  31         manpages to help with configuring INN.
  32
  33         For bash, try:
  34
  35             PATH=~news/bin:$PATH
  36             export PATH
  37             MANPATH=~news/man:$MANPATH
  38             export MANPATH
  39
  40         or csh:
  41
  42             setenv PATH ~news/bin:$PATH
  43             setenv MANPATH ~news/man:$MANPATH
  44
  45         although if you don't already have MANPATH set, the above may give
  46         an error or override your defaults (making it so you can only read
  47         the news manpages); if "echo $MANPATH" does not give some reasonable
  48         path, you'll need to look up what the default is for your system
  49         (such as /usr/man or /usr/share/man).
  50
  51 Compile
  52
  53     *   Download the INN tarball and unpack.
  54
  55     *   Work out configure options ("./configure --help" for a list).  If
  56         you aren't working out of /usr/local/news, or want to put some files
  57         on a different partition, you can set the directories now (or later
  58         in inn.conf if you change your mind).
  59
  60         You probably want "--with-perl".  If you're not using NetBSD with
  61         cycbuffs or OpenBSD, perhaps "--with-tagged-hash".  You might want
  62         to compile in SSL and Berkeley DB, if your system supports them.
  63
  64             ./configure --with-perl ...
  65             make
  66
  67             su
  68             make install
  69
  70         (If you do the last step as root, all of the ownerships and
  71         permissions will be correct.)
  72
  73 Configure
  74
  75     *   Find INSTALL and open a separate window for it.  A printout is
  76         probably a good idea -- it's long but very helpful.  Any time the
  77         instructions below ask you to make a decision, you can probably find
  78         help in INSTALL.
  79
  80     *   Now it's time to work on the files in ~news/etc/.  Start with
  81         inn.conf; you must fill in the default moderators address, your
  82         fully qualified domain names and path.  Fill in all the blanks.
  83         Change the file descriptor limits to something like 500.
  84
  85     *   If using cycbuffs (the CNFS storage method), open cycbuff.conf in
  86         one window and a shell in another to create the cycbuff as described
  87         in INSTALL.  As you create them, record in cycbuff.conf the paths
  88         and sizes.  Save paths and sizes in a separate text file on another
  89         machine in case you ever blow away the wrong file.
  90
  91         Name the metacycbuff, then configure storage.conf.
  92
  93     *   In storage.conf, be sure that all sizes of articles can be
  94         accomodated.  If you want to throw away large articles, do it
  95         explicitly by using the "trash" storage method.
  96
  97     *   The default options in expire.ctl work fine if you have cycbuffs, if
  98         not, configure to suit.
  99
 100     *   Check over moderators and control.ctl.
 101
 102     *   Run ~news/bin/inncheck and fix anything noted.
 103
 104         Inncheck gives a rough check on the appropriateness of the
 105         configuration files as you go.  (It's the equivalent of "perl -cw
 106         yourfile.pl" for perl scripts.)
 107
 108         Note that inncheck is very conservative about permissions; there's
 109         no reason most of the config files can't be world-readable if you
 110         prefer that.
 111
 112     *   Import an active file (~news/db/active) and run inncheck again.
 113         Change where noted (there's a gotcha in the ISC's active list 000000
 114         000000 (whatever number of zeros) should be 0000000 00000001).
 115
 116     *   Create empty initial db files.  Be sure these end up owned by news.
 117
 118             cd ~news/db
 119
 120             touch newsgroups
 121             touch active.times
 122
 123             touch history
 124             ~news/bin/makedbz -i
 125             mv history.n.hash  history.hash
 126             mv history.n.index history.index
 127             mv history.n.dir   history.dir
 128
 129             chmod 644 *
 130
 131     *   Create the cron jobs and make the changes to your system's
 132         syslog.conf as noted in INSTALL.  Also create the cron job for
 133         nntpsend if you've chosen that over innfeed.
 134
 135         Create the log files.
 136
 137     *   For the time being, we can see if everything initially works without
 138         worrying about feeds or reader access.
 139
 140 Run
 141
 142     *   Start inn by running ~news/bin/rc.news *as the news user*.
 143
 144         Check ~news/log/news.notice to see if everything went well, also use
 145         "ps" to see if innd is running.
 146
 147         "telnet localhost 119" and you should see either a welcome banner or
 148         a "no permission to talk" message.  If not, investigate.
 149
 150     *   "man ctlinnd" now; you'll use "ctlinnd reload" as you complete your
 151         configuration.
 152
 153 Feeds
 154
 155     All of this can be done while INN is running.
 156
 157     *   To get your incoming feeds working, edit incoming.conf.  When done,
 158         "ctlinnd reload incoming.conf reason" (where "reason" is some text
 159         that will show up in the logs, anything will do).
 160
 161     *   To get your outgoing feeds working, decide whether to use innfeed or
 162         nntpsend.  Edit newsfeeds and either innfeed.conf or nntpsend.ctl.
 163
 164         In newsfeeds, if using innfeed, use the option which doens't require
 165         you to do a separate innfeed configuration unless you know more than
 166         I do.
 167
 168         Then "ctlinnd reload newsfeeds reason".
 169
 170     *   In readers.conf, remember that auth and access can be separated.
 171
 172         Begin with auth.  Your auth for password users could look like this:
 173
 174             auth "foreignokay" {
 175                 auth: "ckpasswd -d ~news/db/newsusers"
 176                 default: "<unauthenticated>"
 177             }
 178
 179         There is a perl script in the ckpasswd man page if you want to do
 180         authentications by password and have the appropriate libraries.
 181         Copy it to ~news/bin, name the file something like makepasswd.pl and
 182         change the internal paths to whatever you're using and wherever
 183         you're putting the newsusers database.  The standard Apache
 184         "htpasswd" tool also works just fine to create INN password files.
 185
 186         Follow with the access stanzas.  Something for people with
 187         passwords:
 188
 189             access "generalpeople" {
 190                 users: "*"
 191                 newsgroups: "*,!junk,!control,!control.*"
 192             }
 193
 194         And then something like one of the following two, depending on
 195         whether unauthenticated users get any access:
 196
 197             access "restrictive" {
 198                 users: "<unauthenticated>"
 199                 newsgroups: "!*"
 200             }
 201
 202             access "readonly" {
 203                 users: "<unauthenticated>"
 204                 read: "local.*"
 205                 post: "!*"
 206             }
 207
 208         You don't need to reload anything after modifying readers.conf;
 209         every time an nnrpd launches it reads its configuration from disk.
 210