chiark / gitweb /
option for no inotify; manpage fix
[innduct.git] / 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