doc/pod/checklist.pod

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