chiark / gitweb /
debugging for thing that crashed
[innduct.git] / 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