chiark / gitweb /
Commit 2.4.5-5 as unpacked
[inn-innduct.git] / doc / man / inn.conf.5
1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sh \" Subsection heading
6 .br
7 .if t .Sp
8 .ne 5
9 .PP
10 \fB\\$1\fR
11 .PP
12 ..
13 .de Sp \" Vertical space (when we can't use .PP)
14 .if t .sp .5v
15 .if n .sp
16 ..
17 .de Vb \" Begin verbatim text
18 .ft CW
19 .nf
20 .ne \\$1
21 ..
22 .de Ve \" End verbatim text
23 .ft R
24 .fi
25 ..
26 .\" Set up some character translations and predefined strings.  \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
29 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
30 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
31 .\" nothing in troff, for use with C<>.
32 .tr \(*W-
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
34 .ie n \{\
35 .    ds -- \(*W-
36 .    ds PI pi
37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
39 .    ds L" ""
40 .    ds R" ""
41 .    ds C` ""
42 .    ds C' ""
43 'br\}
44 .el\{\
45 .    ds -- \|\(em\|
46 .    ds PI \(*p
47 .    ds L" ``
48 .    ds R" ''
49 'br\}
50 .\"
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
55 .if \nF \{\
56 .    de IX
57 .    tm Index:\\$1\t\\n%\t"\\$2"
58 ..
59 .    nr % 0
60 .    rr F
61 .\}
62 .\"
63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
65 .hy 0
66 .if n .na
67 .\"
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
70 .    \" fudge factors for nroff and troff
71 .if n \{\
72 .    ds #H 0
73 .    ds #V .8m
74 .    ds #F .3m
75 .    ds #[ \f1
76 .    ds #] \fP
77 .\}
78 .if t \{\
79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80 .    ds #V .6m
81 .    ds #F 0
82 .    ds #[ \&
83 .    ds #] \&
84 .\}
85 .    \" simple accents for nroff and troff
86 .if n \{\
87 .    ds ' \&
88 .    ds ` \&
89 .    ds ^ \&
90 .    ds , \&
91 .    ds ~ ~
92 .    ds /
93 .\}
94 .if t \{\
95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
101 .\}
102 .    \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 .    \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 .    \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
117 \{\
118 .    ds : e
119 .    ds 8 ss
120 .    ds o a
121 .    ds d- d\h'-1'\(ga
122 .    ds D- D\h'-1'\(hy
123 .    ds th \o'bp'
124 .    ds Th \o'LP'
125 .    ds ae ae
126 .    ds Ae AE
127 .\}
128 .rm #[ #] #H #V #F C
129 .\" ========================================================================
130 .\"
131 .IX Title "INN.CONF 5"
132 .TH INN.CONF 5 "2008-04-06" "INN 2.4.5" "InterNetNews Documentation"
133 .SH "NAME"
134 inn.conf \- Configuration data for InterNetNews programs
136 .IX Header "DESCRIPTION"
137 \&\fIinn.conf\fR in \fIpathetc\fR is the primary general configuration file for
138 all InterNetNews programs.  Settings which control the general operation
139 of various programs, as well as the paths to all portions of the news
140 installation, are found here.  The \s-1INNCONF\s0 environment variable, if set,
141 specifies an alternate path to \fIinn.conf\fR.
142 .PP
143 This file is intended to be fairly static.  Any changes made to it will
144 generally not affect any running programs until they restart.  Unlike
145 nearly every other configuration file, \fIinn.conf\fR cannot be reloaded
146 dynamically using \fIctlinnd\fR\|(8); \fIinnd\fR\|(8) must be stopped and restarted for
147 relevant changes to \fIinn.conf\fR to take effect (\f(CW\*(C`ctlinnd xexec innd\*(C'\fR is
148 the fastest way to do this.)
149 .PP
150 Blank lines and lines starting with a number sign (\f(CW\*(C`#\*(C'\fR) are ignored.  All
151 other lines specify parameters, and should be of the following form:
152 .PP
153 .Vb 1
154 \&    <name>: <value>
155 .Ve
156 .PP
157 (Any amount of whitespace can be put after the colon and is optional.)  If
158 the value contains embedded whitespace or any of the characers \f(CW\*(C`[]<\*(C'\fR\*(L"\e:>,
159 it must be enclosed in double quotes (\*(R"").  A backslash (\f(CW\*(C`\e\*(C'\fR) can be used
160 to escape quotes and backslashes inside double quotes.  <name> is
161 case\-sensitive; \f(CW\*(C`server\*(C'\fR is not the same as \f(CW\*(C`Server\*(C'\fR or \f(CW\*(C`SERVER\*(C'\fR.
162 (\fIinn.conf\fR parameters are generally all in lowercase.)
163 .PP
164 If <name> occurs more than once in the file, the first value is used.
165 Some parameters specified in the file may be overridden by environment
166 variables.  Most parameters have default values if not specified in
167 \&\fIinn.conf\fR; those defaults are noted in the description of each
168 parameter.
169 .PP
170 Many parameters take a boolean value.  For all such parameters, the value
171 may be specified as \f(CW\*(C`true\*(C'\fR, \f(CW\*(C`yes\*(C'\fR, or \f(CW\*(C`on\*(C'\fR to turn it on and may be any
172 of \f(CW\*(C`false\*(C'\fR, \f(CW\*(C`no\*(C'\fR, or \f(CW\*(C`off\*(C'\fR to turn it off.  The case of these values is
173 significant.
174 .PP
175 This documentation is extremely long and organized as a reference manual
176 rather than as a tutorial.  If this is your first exposure to \s-1INN\s0 and
177 these parameters, it would be better to start by reading other man pages
178 and referring to this one only when an \fIinn.conf\fR parameter is explicitly
179 mentioned.  Those parameters which need to be changed when setting up a
180 new server are discussed in \fI\s-1INSTALL\s0\fR.
182 .IX Header "PARAMETERS"
183 .Sh "General Settings"
184 .IX Subsection "General Settings"
185 These parameters are used by a wide variety of different components of
186 \&\s-1INN\s0.
187 .IP "\fIdomain\fR" 4
188 .IX Item "domain"
189 This should be the domain name of the local host.  It should not have a
190 leading period, and it should not be a full host address.  It is used only
191 if the \fIGetFQDN()\fR routine in \fIlibinn\fR\|(3) cannot get the fully-qualified
192 domain name by using either the \fIgethostname\fR\|(3) or \fIgethostbyname\fR\|(3) calls.
193 The check is very simple; if either routine returns a name with a period
194 in it, then it is assumed to have the full domain name.  As this parameter
195 is rarely used, do not use it to affect the righthand side of
196 autogenerated Message\-IDs; see instead \fIvirtualhost\fR and \fIdomain\fR in
197 readers.conf.  The default value is unset.
198 .IP "\fIinnflags\fR" 4
199 .IX Item "innflags"
200 The flags to pass to innd on startup.  See \fIinnd\fR\|(8) for details on the
201 possible flags.  The default value is unset.
202 .IP "\fImailcmd\fR" 4
203 .IX Item "mailcmd"
204 The path to the program to be used for mailing reports and control
205 messages.  The default is \fIpathbin\fR/innmail.  This should not normally
206 need to be changed.
207 .IP "\fImta\fR" 4
208 .IX Item "mta"
209 The command to use when mailing postings to moderators and for the use of
210 \&\fIinnmail\fR\|(1).  The message, with headers and an added To: header, will be
211 piped into this program.  The string \f(CW%s\fR, if present, will be replaced
212 by the e\-mail address of the moderator.  It's strongly recommended for
213 this command to include \f(CW%s\fR on the command line rather than use the
214 addresses in the To: and Cc: headers of the message, since the latter
215 approach allows the news server to be abused as a mechanism to send mail
216 to arbitrary addresses and will result in unexpected behavior.  There is
217 no default value for this parameter; it must be set in \fIinn.conf\fR or a
218 fatal error message will be logged via syslog.
219 .Sp
220 For most systems, \f(CW\*(C`/usr/lib/sendmail \-oi \-oem %s\*(C'\fR (adjusted for the
221 correct path to sendmail) is a good choice.
222 .IP "\fIpathhost\fR" 4
223 .IX Item "pathhost"
224 What to put into the Path: header to represent the local site.  This is
225 added to the Path: header of all articles that pass through the system,
226 including locally posted articles, and is also used when processing some
227 control messages and when naming the server in status reports.  There is
228 no default value; this parameter must be set in \fIinn.conf\fR or \s-1INN\s0 will
229 not start.  A good value to use is the fully-qualified hostname of the
230 system.
231 .IP "\fIserver\fR" 4
232 .IX Item "server"
233 The name of the default \s-1NNTP\s0 server.  If \fInnrpdposthost\fR is not set and
234 \&\s-1UNIX\s0 domain sockets are not supported, \fInnrpd\fR\|(8) tries to hand off
235 locally-posted articles through an \s-1INET\s0 domain socket to this server.
236 \&\fIactsync\fR\|(8), \fInntpget\fR\|(8), and \fIgetlist\fR\|(8) also use this value as the default
237 server to connect to.  In the latter cases, the value of the \s-1NNTPSERVER\s0
238 environment variable, if it exists, overrides this.  The default value is
239 unset.
240 .Sh "Feed Configuration"
241 .IX Subsection "Feed Configuration"
242 These parameters govern incoming and outgoing feeds:  what size of
243 articles are accepted, what filtering and verification is performed on
244 them, whether articles in groups not carried by the server are still
245 stored and propagated, and other similar settings.
246 .IP "\fIartcutoff\fR" 4
247 .IX Item "artcutoff"
248 Articles older than this number of days are dropped.  This setting should
249 probably match the setting on the \f(CW\*(C`/remember/\*(C'\fR line in \fIexpire.ctl\fR.
250 The default value is \f(CW10\fR.
251 .IP "\fIbindaddress\fR" 4
252 .IX Item "bindaddress"
253 Which \s-1IP\s0 address \fIinnd\fR\|(8) should bind itself to.  This must be in
254 dotted-quad format (nnn.nnn.nnn.nnn).  If set to \f(CW\*(C`all\*(C'\fR or not set, innd
255 defaults to listening on all interfaces.  The value of the
256 \&\s-1INND_BIND_ADDRESS\s0 environment variable, if set, overrides this setting.
257 The default value is unset.
258 .IP "\fIbindaddress6\fR" 4
259 .IX Item "bindaddress6"
260 Like \fIbindaddress\fR but for IPv6 sockets. If only one of the \fIbindaddress\fR
261 and \fIbindaddress6\fR parameters is used, then only the socket for the
262 corresponding address family is created. If both parameters are used
263 then two sockets are created. If neither of them is used, the list of
264 sockets to listen on will be determined by the system library
265 \&\fI\fIgetaddrinfo\fI\|(3)\fR function.  The value of the \s-1INND_BIND_ADDRESS6\s0, if set,
266 overrides this setting.  The default value is unset.
267 .Sp
268 Note that you will generally need to put double quotes ("") around this
269 value if you set it, since IPv6 addresses contain colons.
270 .IP "\fIhiscachesize\fR" 4
271 .IX Item "hiscachesize"
272 If set to a value other than \f(CW0\fR, a hash of recently received message IDs
273 is kept in memory to speed history lookups.  The value is the amount of
274 memory to devote to the cache in kilobytes.  The cache is only used for
275 incoming feeds and a small cache can hold quite a few message IDs, so
276 large values aren't necessarily useful unless you have incoming feeds that
277 are badly delayed.  A good value for a system with more than one incoming
278 feed is \f(CW256\fR; systems with only one incoming feed should probably leave
279 this at \f(CW0\fR.  The default value is \f(CW0\fR.
280 .IP "\fIignorenewsgroups\fR" 4
281 .IX Item "ignorenewsgroups"
282 Whether newsgroup creation control messages (newgroup and rmgroup) should
283 be fed as if they were posted to the newsgroup they are creating or
284 deleting rather than to the newsgroups listed in the Newsgroups: header.
285 If this parameter is set, the newsgroup affected by the control message
286 will be extracted from the Control: header and the article will be fed as
287 if its Newsgroups: header contained solely that newsgroup.  This is useful
288 for routing control messages to peers when they are posted to irrelevant
289 newsgroups that shouldn't be matched against the peer's desired newsgroups
290 in \fInewsfeeds\fR.  This is a boolean value and the default is false.
291 .IP "\fIimmediatecancel\fR" 4
292 .IX Item "immediatecancel"
293 When using the timecaf storage method, article cancels are normally just
294 cached to be cancelled, not cancelled immediately.  If this is set to
295 true, they will instead by cancelled as soon as the cancel is processed.
296 This is a boolean value and the default is false.
297 .Sp
298 This setting is ignored unless the timecaf storage method is used.
299 .IP "\fIlinecountfuzz\fR" 4
300 .IX Item "linecountfuzz"
301 If set to something other than \f(CW0\fR, the line count of the article is
302 checked against the Lines: header of the article (if present) and the
303 artice is rejected if the values differ by more than this amount.  A
304 reasonable setting is \f(CW5\fR, which is the standard maximum signature length
305 plus one (some injection software calculates the Lines: header before
306 adding the signature).  The default value is \f(CW0\fR, which tells \s-1INN\s0 not to
307 check the Lines: header of incoming articles.
308 .IP "\fImaxartsize\fR" 4
309 .IX Item "maxartsize"
310 The maximum size of article (headers and body) that will be accepted by
311 the server, in bytes.  A value of \f(CW0\fR allows any size of article, but
312 note that \fBinnd\fR will crash if system memory is exceeded.  The default
313 value is \f(CW1000000\fR (approximately 1 \s-1MB\s0).  See also \fIlocalmaxartsize\fR.
314 .IP "\fImaxconnections\fR" 4
315 .IX Item "maxconnections"
316 The maximum number of incoming \s-1NNTP\s0 connections \fIinnd\fR\|(8) will accept.  The
317 default value is \f(CW50\fR.
318 .IP "\fIpathalias\fR" 4
319 .IX Item "pathalias"
320 If set, this value is prepended to the Path: header of accepted posts
321 (before \fIpathhost\fR) if it doesn't already appear in the Path: header.
322 The main purpose of this parameter is to configure all news servers within
323 a particular organization to add a common identity string to the
324 Path: header.  The default value is unset.
325 .IP "\fIpathcluster\fR" 4
326 .IX Item "pathcluster"
327 If set, this value is appended to the Path: header of accepted posts
328 (after \fIpathhost\fR) if it isn't already present as the last element
329 of the Path: header.  The main purpose of this parameter is to make
330 several news servers appear as one server.  The default value is unset.
331 .Sp
332 Note that the Path: header reads right to left, so appended means inserted
333 at the leftmost side of the Path: header.
334 .IP "\fIpgpverify\fR" 4
335 .IX Item "pgpverify"
336 Whether to enable \s-1PGP\s0 verification of control messages other than cancel.
337 This is a boolean value and the default is based on whether configure found
338 pgp, pgpv, or gpgv.
339 .IP "\fIport\fR" 4
340 .IX Item "port"
341 What \s-1TCP\s0 port \fIinnd\fR\|(8) should listen on.  The default value is \f(CW119\fR, the
342 standard \s-1NNTP\s0 port.
343 .IP "\fIrefusecybercancels\fR" 4
344 .IX Item "refusecybercancels"
345 Whether to refuse all articles whose message IDs start with
346 \&\f(CW\*(C`<cancel.\*(C'\fR.  This message \s-1ID\s0 convention is widely followed by spam
347 cancellers, so the vast majority of such articles will be cancels of spam.
348 This check, if enabled, is done before the history check and the message
349 \&\s-1ID\s0 is not written to the history file.  This is a boolean value and the
350 default is false.
351 .Sp
352 This is a somewhat messy, inefficient, and inexact way of refusing spam
353 cancels.  A much better way is to ask all of your upstream peers to not
354 send to you any articles with \f(CW\*(C`cyberspam\*(C'\fR in the Path: header (usually
355 accomplished by having them mark \f(CW\*(C`cyberspam\*(C'\fR as an alias for your machine
356 in their feed configuration).  The filtering enabled by this parameter is
357 hard\-coded; general filtering of message IDs can be done via the embedded
358 filtering support.
359 .IP "\fIremembertrash\fR" 4
360 .IX Item "remembertrash"
361 By default, \fIinnd\fR\|(8) records rejected articles in history so that, if
362 offered the same article again, it can be refused before it is sent.  If
363 you wish to disable this behavior, set this to false.  This can cause a
364 substantial increase in the amount of bandwidth consumed by incoming news
365 if you have several peers and reject a lot of articles, so be careful with
366 it.  Even if this is set to true, \s-1INN\s0 won't log some rejected articles to
367 history if there's reason to believe the article might be accepted if
368 offered by a different peer, so there is usually no reason to set this to
369 false (although doing so can decrease the size of the history file).  This
370 is a boolean value and the default is true.
371 .IP "\fIsourceaddress\fR" 4
372 .IX Item "sourceaddress"
373 Which local \s-1IP\s0 address to bind to for outgoing \s-1NNTP\s0 sockets (used by
374 \&\fIinnxmit\fR\|(8) among other programs, but \fInot\fR \fIinnfeed\fR\|(8) \*(-- see
375 \&\fIbindaddress\fR in \fIinnfeed.conf\fR\|(5) for that).  This must be in dotted-quad
376 format (nnn.nnn.nnn.nnn).  If set to \f(CW\*(C`all\*(C'\fR or not set, the operating
377 system will choose the source \s-1IP\s0 address for outgoing connections.  The
378 default value is unset.
379 .IP "\fIsourceaddress6\fR" 4
380 .IX Item "sourceaddress6"
381 Like \fIsourceaddress\fR but for IPv6 sockets.
382 .IP "\fIverifycancels\fR" 4
383 .IX Item "verifycancels"
384 Set this to true to enable a simplistic check on all cancel messages,
385 attempting to verify (by simple header comparison) that the cancel message
386 is from the same person as the original post.  This can't be done if the
387 cancel arrives before the article does, and is extremely easy to spoof.
388 While this check may once have served a purpose, it's now essentially
389 security via obscurity, commonly avoided by abusers, and probably not
390 useful.  This is a boolean value, and the default is false.
391 .IP "\fIwanttrash\fR" 4
392 .IX Item "wanttrash"
393 Set this to true if you want to file articles posted to unknown newsgroups
394 (newsgroups not in the \fIactive\fR file) into the \f(CW\*(C`junk\*(C'\fR newsgroup rather
395 than rejecting them.  This is sometimes useful for a transit news server
396 that needs to propagate articles in all newsgroups regardless if they're
397 carried locally.  This is a boolean value and the default is false.
398 .IP "\fIwipcheck\fR" 4
399 .IX Item "wipcheck"
400 If \s-1INN\s0 is offered an article by a peer on one channel, it will return
401 deferral responses (code 436) to all other offers of that article for this
402 many seconds.  (After this long, if the peer that offered the article
403 still hasn't sent it, it will be accepted from other channels.)  The
404 default value is \f(CW5\fR and probably doesn't need to be changed.
405 .IP "\fIwipexpire\fR" 4
406 .IX Item "wipexpire"
407 How long, in seconds, to keep track of message IDs offered on a channel
408 before expiring articles that still haven't been sent.  The default value
409 is \f(CW10\fR and probably doesn't need to be changed.
410 .IP "\fIdontrejectfiltered\fR" 4
411 .IX Item "dontrejectfiltered"
412 Normally \fIinnd\fR\|(8) rejects incoming articles when directed to do so by any
413 enabled article filters (Perl, Python, and \s-1TCL\s0).  However, this parameter
414 causes such articles \fInot\fR to be rejected; instead filtering can be
415 applied on outbound articles.  If this parameter is set, all articles will
416 be accepted on the local machine, but articles rejected by the filter will
417 \&\fInot\fR be fed to any peers specified in \fInewsfeeds\fR with the \f(CW\*(C`Af\*(C'\fR flag.
418 .Sh "Article Storage"
419 .IX Subsection "Article Storage"
420 These parameters affect how articles are stored on disk.
421 .IP "\fIcnfscheckfudgesize\fR" 4
422 .IX Item "cnfscheckfudgesize"
423 If set to a value other than \f(CW0\fR, the claimed size of articles in \s-1CNFS\s0
424 cycbuffs is checked against \fImaxartsize\fR plus this value, and if larger,
425 the \s-1CNFS\s0 cycbuff is considered corrupt.  This can be useful as a sanity
426 check after a system crash, but be careful using this parameter if you
427 have changed \fImaxartsize\fR recently.  The default value is \f(CW0\fR.
428 .IP "\fIenableoverview\fR" 4
429 .IX Item "enableoverview"
430 Whether to write out overview data for articles.  If set to false, \s-1INN\s0
431 will run much faster, but reading news from the system will be impossible
432 (the server will be for news transit only).  If this option is set to
433 true, \fIovmethod\fR must also be set.  This is a boolean value and the
434 default is true.
435 .IP "\fIgroupbaseexpiry\fR" 4
436 .IX Item "groupbaseexpiry"
437 Whether to enable newsgroup-based expiry.  If set to false, article expiry
438 is done based on storage class of storing method.  If set to true (and
439 overview information is available), expiry is done by newsgroup name.
440 This affects the format of \fIexpire.ctl\fR.  This is a boolean value and the
441 default is true.
442 .IP "\fImergetogroups\fR" 4
443 .IX Item "mergetogroups"
444 Whether to file all postings to \f(CW\*(C`to.*\*(C'\fR groups in the pseudonewsgroup
445 \&\f(CW\*(C`to\*(C'\fR.  If this is set to true, the newsgroup \f(CW\*(C`to\*(C'\fR must exist in the
446 \&\fIactive\fR file or \s-1INN\s0 will not start.  (See the discussion of \f(CW\*(C`to.\*(C'\fR
447 groups in \fIinnd\fR\|(8) under \s-1CONTROL\s0 \s-1MESSAGES\s0.)  This is a boolean value and
448 the default is false.
449 .IP "\fIovercachesize\fR" 4
450 .IX Item "overcachesize"
451 How many cache slots to reserve for open overview files.  If \s-1INN\s0 is
452 writing overview files (see \fIenableoverview\fR), \fIovmethod\fR is set to
453 \&\f(CW\*(C`tradindexed\*(C'\fR, and this is set to a value other than \f(CW0\fR, \s-1INN\s0 will keep
454 around and open that many recently written-to overview files in case more
455 articles come in for those newsgroups.  Every overview cache slot consumes
456 two file descriptors, so be careful not to set this value too high.  You
457 may be able to use the \f(CW\*(C`limit\*(C'\fR command to see how many open file
458 descriptors your operating system allows.  \fIinnd\fR\|(8) also uses an open file
459 descriptor for each incoming feed and outgoing channel or batch file, and
460 if it runs out of open file descriptors it may throttle and stop accepting
461 new news.  The default value is \f(CW15\fR (which is probably way too low if
462 you have a large number of file descriptors available).
463 .Sp
464 This setting is ignored unless \fIovmethod\fR is set to \f(CW\*(C`tradindexed\*(C'\fR.
465 .IP "\fIovgrouppat\fR" 4
466 .IX Item "ovgrouppat"
467 If set, restricts the overview data stored by \s-1INN\s0 to only the newsgroups
468 matching this comma-separated list of wildmat expressions.  Newsgroups not
469 matching this setting may not be readable, and if \fIgroupbaseexpiry\fR is
470 set to true and the storage method for these newsgroups does not have
471 self-expire functionality, storing overview data will fail.
472 The default is unset.
473 .IP "\fIovmethod\fR" 4
474 .IX Item "ovmethod"
475 Which overview storage method to use.  Currently supported values are
476 \&\f(CW\*(C`tradindexed\*(C'\fR, \f(CW\*(C`buffindexed\*(C'\fR, and \f(CW\*(C`ovdb\*(C'\fR.  There is no default value;
477 this parameter must be set if \fIenableoverview\fR is true (the default).
478 .RS 4
479 .ie n .IP """buffindexed""" 4
480 .el .IP "\f(CWbuffindexed\fR" 4
481 .IX Item "buffindexed"
482 Stores overview data and index information into buffers, which are
483 preconfigured files defined in \fIbuffinedexed.conf\fR.  \f(CW\*(C`buffindexed\*(C'\fR never
484 consumes additional disk space beyond that allocated to these buffers.
485 .ie n .IP """tradindexed""" 4
486 .el .IP "\f(CWtradindexed\fR" 4
487 .IX Item "tradindexed"
488 Uses two files per newsgroup, one containing the overview data and one
489 containing the index.  Fast for readers, but slow to write to.
490 .ie n .IP """ovdb""" 4
491 .el .IP "\f(CWovdb\fR" 4
492 .IX Item "ovdb"
493 Stores data into a Berkeley \s-1DB\s0 database.  See the \fIovdb\fR\|(5) man page.
494 .RE
495 .RS 4
496 .RE
497 .IP "\fIhismethod\fR" 4
498 .IX Item "hismethod"
499 Which history storage method to use.  The only currently supported
500 value is \f(CW\*(C`hisv6\*(C'\fR.  There is no default value; this parameter must
501 be set.
502 .RS 4
503 .ie n .IP """hisv6""" 4
504 .el .IP "\f(CWhisv6\fR" 4
505 .IX Item "hisv6"
506 Stores history data in the \s-1INN\s0 history v6 format:  \fIhistory\fR\|(5) text
507 file and a number of \fIdbz\fR\|(3) database files; this may be in true history
508 v6 format, or tagged hash format, depending on the build
509 options.  Separation of these two is a project which has not yet been
510 undertaken.
511 .RE
512 .RS 4
513 .RE
514 .IP "\fIstoreonxref\fR" 4
515 .IX Item "storeonxref"
516 If set to true, articles will be stored based on the newsgroup names in
517 the Xref: header rather than in the Newsgroups: header.  This affects what
518 the patterns in \fIstorage.conf\fR apply to.  The primary interesting effect
519 of setting this to true is to enable filing of all control messages
520 according to what storage class the control pseudogroups are filed in
521 rather than according to the newsgroups the control messages are posted
522 to.  This is a boolean value and the default is true.
523 .IP "\fIuseoverchan\fR" 4
524 .IX Item "useoverchan"
525 Whether to \fIinnd\fR\|(8) should create overview data internally through
526 \&\fIlibstorage\fR\|(3).  If set to false, innd creates overview data by itself.  If
527 set to true, innd does not create; instead overview data must be created
528 by \fIoverchan\fR\|(8) from an appropriate entry in \fInewsfeeds\fR.  Setting to true
529 may be useful, if innd cannot keep up with incoming feed and the
530 bottleneck is creation of overview data within innd.  This is a boolean
531 value and the default is false.
532 .IP "\fIwireformat\fR" 4
533 .IX Item "wireformat"
534 Only used with the tradspool storage method, this says whether to write
535 articles in wire format.  Wire format means storing articles with \f(CW\*(C`\er\en\*(C'\fR at
536 the end of each line and with periods at the beginning of lines doubled,
537 the article format required by the \s-1NNTP\s0 protocol.  Articles stored in this
538 format are suitable for sending directly to a network connection without
539 requiring conversion, and therefore setting this to true can make the
540 server more efficient.  The primary reason not to set this is if you have
541 old existing software that looks around in the spool and doesn't
542 understand how to read wire format.  Storage methods other than tradspool
543 always store articles in wire format.  This is a boolean value and the
544 default is false.
545 .IP "\fIxrefslave\fR" 4
546 .IX Item "xrefslave"
547 Whether to act as the slave of another server.  If set, \s-1INN\s0 attempts to
548 duplicate exactly the article numbering of the server feeding it by
549 looking at the Xref: header of incoming articles and assigning the same
550 article numbers to articles as was noted in the Xref: header from the
551 upstream server.  The result is that clients should be able to point at
552 either server interchangeably (using some load balancing scheme, for
553 example) and see the same internal article numbering.  Servers with this
554 parameter set should generally only have one upstream feed, and should
555 always have \fInnrpdposthost\fR set to hand locally posted articles off to
556 the master server.  The upstream should be careful to always feed articles
557 in order (\fIinnfeed\fR\|(8) can have problems with this in the event of a
558 backlog).  This is a boolean value and the default is false.
559 .IP "\fInfswriter\fR" 4
560 .IX Item "nfswriter"
561 For servers writing articles, determine whether the article spool is
562 on \s-1NFS\s0 storage.  If set, \s-1INN\s0 attempts to flush articles to the spool
563 in a more timely manner, rather than relying on the operating system
564 to flush things such as the \s-1CNFS\s0 article bitmaps.  You should only set
565 this parameter if you are attempting to use a shared \s-1NFS\s0 spool on a
566 machine acting as a single writer within a cluster.  This is a boolean
567 value and the default is false.
568 .IP "\fInfsreader\fR" 4
569 .IX Item "nfsreader"
570 For servers reading articles, determine whether the article spool is
571 on \s-1NFS\s0 storage.  If set, \s-1INN\s0 will attempt to force articles and
572 overviews to be read directly from the \s-1NFS\s0 spool rather than from
573 cached copies.  You should only set this parameter if you are
574 attempting to use a shared \s-1NFS\s0 spool on a machine acting a reader a
575 cluster.  This is a boolean value and the default is false.
576 .IP "\fInfsreaderdelay\fR" 4
577 .IX Item "nfsreaderdelay"
578 For servers reading articles, determine whether the article spool is
579 on \s-1NFS\s0 storage.  If \fInfsreader\fR is set, \s-1INN\s0 will use the value of
580 \&\fInfsreaderdelay\fR to delay the apparent arrival time of articles to
581 clients by this amount; this value should be tuned based on the \s-1NFS\s0
582 cache timeouts locally.  This default is 60 (1 minute).
583 .IP "\fImsgidcachesize\fR" 4
584 .IX Item "msgidcachesize"
585 How many cache slots to reserve for Message \s-1ID\s0 to storage token
586 translations.  When serving overview data to clients (\s-1NEWNEWS\s0, \s-1XOVER\s0
587 etc.), \fInnrpd\fR\|(8) can cache the storage token associated with a Message
588 \&\s-1ID\s0 and save the cost of looking it up in the history file; for some
589 configurations setting this parameter can save more than 90% of the
590 wall clock time for a session.  The default value is 10000.
591 .IP "\fItradindexedmmap\fR" 4
592 .IX Item "tradindexedmmap"
593 Whether to attempt to \fImmap()\fR tradindexed overviews articles.  Setting
594 this to true will give better performance on most systems, but some
595 systems have problems with \fImmap()\fR.  If this is set to false, overviews
596 will be read into memory before being sent to readers.  This is a
597 boolean value and the default is true.
598 .Sh "Reading"
599 .IX Subsection "Reading"
600 These parameters affect the behavior of \s-1INN\s0 for readers.  Most of them are
601 used by \fInnrpd\fR\|(8).  There are some special sets of settings that are broken
602 out separately after the initial alphabetized list.
603 .IP "\fIallownewnews\fR" 4
604 .IX Item "allownewnews"
605 Whether to allow use of the \s-1NEWNEWS\s0 command by clients.  This command used
606 to put a heavy load on the server in older versions of \s-1INN\s0, but is now
607 reasonably efficient, at least if only one newsgroup is specified by the
608 client.  This is a boolean value and the default is true.  If you use the
609 \&\fIaccess\fR parameter in \fIreaders.conf\fR, be sure to read about the way it
610 overrides \fIallownewnews\fR.
611 .IP "\fIarticlemmap\fR" 4
612 .IX Item "articlemmap"
613 Whether to attempt to \fImmap()\fR articles.  Setting this to true will give
614 better performance on most systems, but some systems have problems with
615 \&\fImmap()\fR.  If this is set to false, articles will be read into memory before
616 being sent to readers.  This is a boolean value and the default is false.
617 .IP "\fIclienttimeout\fR" 4
618 .IX Item "clienttimeout"
619 How long (in seconds) a client connection can be idle before it exits.
620 When setting this parameter, be aware that some newsreaders use the same
621 connection for reading and posting and don't deal well with the connection
622 timing out while a post is being composed.  If the system isn't having a
623 problem with too many long-lived connections, it may be a good idea to
624 increase this value to \f(CW3600\fR (an hour).  The default value is \f(CW600\fR
625 (ten minutes).
626 .IP "\fIinitialtimeout\fR" 4
627 .IX Item "initialtimeout"
628 How long (in seconds) \fBnnrpd\fR will wait for the first command from a
629 reader connection before dropping the connection.  This is a defensive
630 timeout intended to protect the news server from badly behaved reader
631 clients that open and abandon a multitude of connections without every
632 closing them.  The default value is \f(CW10\fR (ten seconds), which may need to
633 be increased if many clients connect via slow network links.
634 .IP "\fInnrpdcheckart\fR" 4
635 .IX Item "nnrpdcheckart"
636 Whether \fBnnrpd\fR should check the existence of an article before listing
637 it as present in response to an \s-1NNTP\s0 command.  The primary use of this
638 setting is to prevent nnrpd from returning information about articles
639 which are no longer present on the server but which still have overview
640 data available.  Checking the existence of articles before returning
641 overview information slows down the overview commands, but reduces the
642 number of \*(L"article is missing\*(R" errors seen by the client.  This is a
643 boolean value and the default is true.
644 .IP "\fInnrpperlauth\fR" 4
645 .IX Item "nnrpperlauth"
646 This parameter is now obsolete; see \*(L"Changes to Perl Authentication
647 Support for nnrpd\*(R" in \fIdoc/hook\-perl\fR.
648 .IP "\fInnrppythonauth\fR" 4
649 .IX Item "nnrppythonauth"
650 This parameter is now obsolete; see \*(L"Changes to Python Authentication and
651 Access Control Support for nnrpd\*(R" in \fIdoc/hook\-python\fR.
652 .IP "\fInoreader\fR" 4
653 .IX Item "noreader"
654 Normally, \fIinnd\fR\|(8) will fork a copy of \fInnrpd\fR\|(8) for all incoming
655 connections from hosts not listed in \fIincoming.conf\fR.  If this parameter
656 is set to true, those connections will instead be rejected with a 502
657 error code.  This should be set to true for a transit-only server that
658 doesn't support readers, or if nnrpd is running in daemon mode or being
659 started out of inetd.  This is a boolean value and the default is false.
660 .IP "\fIreaderswhenstopped\fR" 4
661 .IX Item "readerswhenstopped"
662 Whether to allow readers to connect even if the server is paused or
663 throttled.  This is only applicable if \fInnrpd\fR\|(8) is spawned from \fIinnd\fR\|(8)
664 rather than run out of inetd or in daemon mode.  This is a boolean value
665 and the default is false.
666 .IP "\fIreadertrack\fR" 4
667 .IX Item "readertrack"
668 Whether to enable the tracking system for client behavior.  Tracked
669 information is recorded to \fIpathlog\fR/tracklogs/log\-ID, where \s-1ID\s0 is
670 determined by nnrpd's \s-1PID\s0 and launch time.)  Currently the information
671 recorded includes initial connection and posting; only information about
672 clients listed in \fInnrpd.track\fR is recorded.  This is a boolean value and
673 the default is false.
674 .IP "\fInnrpdflags\fR" 4
675 .IX Item "nnrpdflags"
676 When \fInnrpd\fR\|(8) is spawned from \fIinnd\fR\|(8), these flags are passed as
677 arguments to the nnrpd process.  This setting does not affect instances
678 of nnrpd that are started in daemon mode, or instances that are started
679 via another listener process such as \fIinetd\fR\|(8) or \fIxinetd\fR\|(8).  Shell
680 quoting and metacharacters are not supported.  This is a string value
681 and the default is unset.
682 .IP "\fInnrpdloadlimit\fR" 4
683 .IX Item "nnrpdloadlimit"
684 If set to a value other than \f(CW0\fR, connections to nnrpd will be refused
685 if the system load average is higher than this value.  The default value
686 is \f(CW16\fR.
687 .PP
688 \&\s-1INN\s0 has optional support for generating keyword information automatically
689 from article body text and putting that information in overview for the
690 use of clients that know to look for it.  The following parameters control
691 that feature.
692 .PP
693 This may be too slow if you're taking a substantial feed, and probably
694 will not be useful for the average news reader; enabling this is not
695 recommended unless you have some specific intention to take advantage of
696 it.
697 .IP "\fIkeywords\fR" 4
698 .IX Item "keywords"
699 Whether the keyword generation support should be enabled.  This is a
700 boolean value and the default is false.
701 .Sp
702 \&\s-1FIXME:\s0 Currently, support for keyword generation is configured into \s-1INN\s0
703 semi-randomly (based on whether configure found the regex library); it
704 should be an option to configure and that option should be mentioned here.
705 .IP "\fIkeyartlimit\fR" 4
706 .IX Item "keyartlimit"
707 Articles larger than this value in bytes will not have keywords generated
708 for them (since it would take too long to do so).  The default value is
709 \&\f(CW100000\fR (approximately 100 \s-1KB\s0).
710 .IP "\fIkeylimit\fR" 4
711 .IX Item "keylimit"
712 Maximum number of bytes allocated for keyword data.  If there are more
713 keywords than will fit into this many bytes when separated by commas, the
714 rest are discarded.  The default value is \f(CW512\fR.
715 .IP "\fIkeymaxwords\fR" 4
716 .IX Item "keymaxwords"
717 Maximum number of keywords that will be generated for an article.  (The
718 keyword generation code will attempt to discard \*(L"noise\*(R" words, so the
719 number of keywords actually writen into the overview will usually be
720 smaller than this even if the maximum number of keywords is found.)  The
721 default value is \f(CW250\fR.
722 .Sh "Posting"
723 .IX Subsection "Posting"
724 These parameters are only used by \fInnrpd\fR\|(8), \fIinews\fR\|(1), and other programs
725 that accept or generate postings.  There are some special sets of settings
726 that are broken out separately after the initial alphabetized list.
727 .IP "\fIaddnntppostingdate\fR" 4
728 .IX Item "addnntppostingdate"
729 Whether to add an NNTP\-Posting\-Date: header to all local posts.  This is a
730 boolean value and the default is true.  Note that \s-1INN\s0 either does not add
731 this header or adds the name or \s-1IP\s0 address of the client.  There is no
732 intrinsic support for obfuscating the name of the client.  That has to be
733 done with a user-written Perl filter, if desired.
734 .IP "\fIaddnntppostinghost\fR" 4
735 .IX Item "addnntppostinghost"
736 Whether to add an NNTP\-Posting\-Host: header to all local posts giving the
737 \&\s-1FQDN\s0 or \s-1IP\s0 address of the system from which the post was received.  This
738 is a boolean value and the default is true.
739 .IP "\fIcheckincludedtext\fR" 4
740 .IX Item "checkincludedtext"
741 Whether to check local postings for the ratio of new to quoted text and
742 reject them if that ratio is under 50%.  Included text is recognized by
743 looking for lines beginning with \f(CW\*(C`>\*(C'\fR, \f(CW\*(C`|\*(C'\fR, or \f(CW\*(C`:\*(C'\fR.  This is a
744 boolean value and the default is false.
745 .IP "\fIcomplaints\fR" 4
746 .IX Item "complaints"
747 The value of the X\-Complaints\-To: header added to all local posts.  The
748 default is the newsmaster's e\-mail address.  (If the newsmaster, selected
749 at configure time and defaulting to \f(CW\*(C`usenet\*(C'\fR, doesn't contain \f(CW\*(C`@\*(C'\fR, the
750 address will consist of the newsmaster, a \f(CW\*(C`@\*(C'\fR, and the value of
751 \&\fIfromhost\fR.)
752 .IP "\fIfromhost\fR" 4
753 .IX Item "fromhost"
754 Contains a domain used to construct e\-mail addresses.  The address of the
755 local news administrator will be given as <user>@\fIfromhost\fR, where <user>
756 is the newsmaster user set at compile time (\f(CW\*(C`usenet\*(C'\fR by default).  This
757 setting will also be used by \fImailpost\fR\|(8) to fully qualify addresses and by
758 \&\fIinews\fR\|(1) to generate the Sender: header (and From: header if missing).
759 The value of the \s-1FROMHOST\s0 environment variable, if set, overrides this
760 setting.  The default is the fully-qualified domain name of the local
761 host.
762 .IP "\fIlocalmaxartsize\fR" 4
763 .IX Item "localmaxartsize"
764 The maximum article size (in bytes) for locally posted articles.  Articles
765 larger than this will be rejected.  A value of \f(CW0\fR allows any size of
766 article, but note that \fBnnrpd\fR and \fBinnd\fR will crash if system memory is
767 exceeded.  See also \fImaxartsize\fR, which applies to all articles including
768 those posted locally.  The default value is \f(CW1000000\fR (approximately 1
769 \&\s-1MB\s0).
770 .IP "\fImoderatormailer\fR" 4
771 .IX Item "moderatormailer"
772 The address to which to send submissions for moderated groups.  It is only
773 used if the \fImoderators\fR file doesn't exist, or if the moderated group to
774 which an article is posted is not matched by any entry in that file, and
775 takes the same form as an entry in the \fImoderators\fR file.  In most cases,
776 \&\f(CW\*(C`\*(C'\fR is a good value for this parameter (\f(CW%s\fR is
777 expanded into a form of the newsgroup name).  See \fImoderators\fR\|(5) for more
778 details about the syntax.  The default is unset.  If this parameter isn't
779 set and an article is posted to a moderated group that does not have a
780 matching entry in the \fImoderators\fR file, the posting will be rejected
781 with an error.
782 .IP "\fInnrpdauthsender\fR" 4
783 .IX Item "nnrpdauthsender"
784 Whether to generate a Sender: header based on reader authentication.  If
785 this parameter is set, a Sender: header will be added to local posts
786 containing the identity assigned by \fIreaders.conf\fR.  If the assigned
787 identity does not include an \f(CW\*(C`@\*(C'\fR, the reader's hostname is used.  If this
788 parameter is set but no identity is be assigned, the Sender: header will
789 be removed from all posts even if the poster includes one.  This is a
790 boolean value and the default is false.
791 .IP "\fInnrpdposthost\fR" 4
792 .IX Item "nnrpdposthost"
793 If set, \fInnrpd\fR\|(8) and \fIrnews\fR\|(1) will pass all locally posted articles to the
794 specified host rather than trying to inject them locally.  See also
795 \&\fInnrpdpostport\fR.  This should always be set if \fIxrefslave\fR is true.  The
796 default value is unset.
797 .IP "\fInnrpdpostport\fR" 4
798 .IX Item "nnrpdpostport"
799 The port on the remote server to connect to to post when \fInnrpdposthost\fR
800 is used.  The default value is \f(CW119\fR.
801 .IP "\fIorganization\fR" 4
802 .IX Item "organization"
803 What to put in the Organization: header if it is left blank by the poster.
804 The value of the \s-1ORGANIZATION\s0 environment variable, if set, overrides this
805 setting.  The default is unset, which tells \s-1INN\s0 not to insert an
806 Organization: header.
807 .IP "\fIspoolfirst\fR" 4
808 .IX Item "spoolfirst"
809 If true, \fInnrpd\fR\|(8) will spool new articles rather than attempting to send
810 them to \fIinnd\fR\|(8).  If false, nnrpd will spool articles only if it receives
811 an error trying to send them to innd.  Setting this to true can be useful
812 if nnrpd must respond as fast as possible to the client; however, when
813 set, articles will not appear to readers until they are given to innd.
814 nnrpd won't do this; \f(CW\*(C`rnews \-U\*(C'\fR must be run periodically to take the
815 spooled articles and post them.  This is a boolean value and the default
816 is false.
817 .IP "\fIstrippostcc\fR" 4
818 .IX Item "strippostcc"
819 Whether to strip To:, Cc:, and Bcc: headers out of all local posts via
820 \&\fInnrpd\fR\|(8).  The primary purpose of this setting is to prevent abuse of the
821 news server by posting to a moderated group and including To: or Cc:
822 headers in the post so that the news server will send the article to
823 arbitrary addresses.  \s-1INN\s0 now protects against this abuse in other ways
824 provided \fImta\fR is set to a command that includes \f(CW%s\fR and honors it, so
825 this is generally no longer needed.  This is a boolean value and the
826 default is false.
827 .PP
828 \&\fInnrpd\fR\|(8) has support for controlling high-volume posters via an
829 exponential backoff algorithm, as configured by the following parameters.
830 .PP
831 Exponential posting backoff works as follows:  News clients are indexed by
832 \&\s-1IP\s0 address (or username, see \fIbackoffauth\fR below).  Each time a post is
833 received from an \s-1IP\s0 address, the time of posting is stored (along with the
834 previous sleep time, see below).  After a configurable number of posts in
835 a configurable period of time, \fInnrpd\fR\|(8) will activate posting backoff and
836 begin to sleep for increasing periods of time before actually posting
837 anything.  Posts will still be accepted, but at an increasingly reduced
838 rate.
839 .PP
840 After backoff has been activated, the length of time to sleep is computed
841 based on the difference in time between the last posting and the current
842 posting.  If this difference is less than \fIbackoffpostfast\fR, the new
843 sleep time will be 1 + (previous sleep time * \fIbackoffk\fR).  If this
844 difference is less than \fIbackoffpostslow\fR but greater than
845 \&\fIbackoffpostfast\fR, then the new sleep time will equal the previous sleep
846 time.  If this difference is greater than \fIbackoffpostslow\fR, the new
847 sleep time is zero and posting backoff is deactivated for this poster.
848 .PP
849 Exponential posting backoff will not be enabled unless \fIbackoffdb\fR is set
850 and \fIbackoffpostfast\fR and \fIbackoffpostslow\fR are set to something other
851 than their default values.
852 .PP
853 Here are the parameters that control exponential posting backoff:
854 .IP "\fIbackoffauth\fR" 4
855 .IX Item "backoffauth"
856 Whether to index posting backoffs by user rather than by source \s-1IP\s0
857 address.  You must be using authentication in \fInnrpd\fR\|(8) for a value of true
858 to have any meaning.  This is a boolean value and the default is false.
859 .IP "\fIbackoffdb\fR" 4
860 .IX Item "backoffdb"
861 The path to a directory, writeable by the news user, that will contain the
862 backoff database.  There is no default for this parameter; you must
863 provide a path to a creatable or writeable directory to enable exponential
864 backoff.
865 .IP "\fIbackoffk\fR" 4
866 .IX Item "backoffk"
867 The amount to multiply the previous sleep time by if the user is still
868 posting too quickly.  A value of \f(CW2\fR will double the sleep time for each
869 excessive post.  The default value is \f(CW1\fR.
870 .IP "\fIbackoffpostfast\fR" 4
871 .IX Item "backoffpostfast"
872 Postings from the same identity that arrive in less than this amount of
873 time (in seconds) will trigger increasing sleep time in the backoff
874 algorithm.  The default value is \f(CW0\fR.
875 .IP "\fIbackoffpostslow\fR" 4
876 .IX Item "backoffpostslow"
877 Postings from the same identity that arrive in greater than this amount of
878 time (in seconds) will reset the backoff algorithm.  Another way to look
879 at this constant is to realize that posters will be allowed to generate at
880 most 86400/\fIbackoffpostslow\fR posts per day.  The default value is \f(CW1\fR.
881 .IP "\fIbackofftrigger\fR" 4
882 .IX Item "backofftrigger"
883 This many postings are allowed before the backoff algorithm is triggered.
884 The default value is \f(CW10000\fR.
885 .Sh "Monitoring"
886 .IX Subsection "Monitoring"
887 These parameters control the behavior of \fIinnwatch\fR\|(8), the program that
888 monitors \s-1INN\s0 and informs the news administrator if anything goes wrong
889 with it.
890 .IP "\fIdoinnwatch\fR" 4
891 .IX Item "doinnwatch"
892 Whether to start \fIinnwatch\fR\|(8) from  This is a boolean value, and
893 the default is true.
894 .IP "\fIinnwatchbatchspace\fR" 4
895 .IX Item "innwatchbatchspace"
896 Free space in \fIpathoutgoing\fR, in \fIinndf\fR\|(8) output units (normally
897 kilobytes), at which \fIinnd\fR\|(8) will be throttled by \fIinnwatch\fR\|(8), assuming a
898 default \fIinnwatch.ctl\fR.  The default value is \f(CW800\fR.
899 .IP "\fIinnwatchlibspace\fR" 4
900 .IX Item "innwatchlibspace"
901 Free space in \fIpathdb\fR, in \fIinndf\fR\|(8) output units (normally kilobytes), at
902 which \fIinnd\fR\|(8) will be throttled by \fIinnwatch\fR\|(8), assuming a default
903 \&\fIinnwatch.ctl\fR.  The default value is \f(CW25000\fR.
904 .IP "\fIinnwatchloload\fR" 4
905 .IX Item "innwatchloload"
906 Load average times 100 at which \fIinnd\fR\|(8) will be restarted by \fIinnwatch\fR\|(8)
907 (undoing a previous pause or throttle), assuming a default
908 \&\fIinnwatch.ctl\fR.  The default value is \f(CW1000\fR (that is, a load average of
909 10.00).
910 .IP "\fIinnwatchhiload\fR" 4
911 .IX Item "innwatchhiload"
912 Load average times 100 at which \fIinnd\fR\|(8) will be throttled by \fIinnwatch\fR\|(8),
913 assuming a default \fIinnwatch.ctl\fR.  The default value is \f(CW2000\fR (that
914 is, a load average of 20.00).
915 .IP "\fIinnwatchpauseload\fR" 4
916 .IX Item "innwatchpauseload"
917 Load average times 100 at which \fIinnd\fR\|(8) will be paused by \fIinnwatch\fR\|(8),
918 assuming a default \fIinnwatch.ctl\fR.  The default value is \f(CW1500\fR (that
919 is, a load average of 15.00).
920 .IP "\fIinnwatchsleeptime\fR" 4
921 .IX Item "innwatchsleeptime"
922 How long (in seconds) \fIinnwatch\fR\|(8) will sleep between each check of \s-1INN\s0.
923 The default value is \f(CW600\fR.
924 .IP "\fIinnwatchspoolnodes\fR" 4
925 .IX Item "innwatchspoolnodes"
926 Free inodes in \fIpatharticles\fR at which \fIinnd\fR\|(8) will be throttled by
927 \&\fIinnwatch\fR\|(8), assuming a default \fIinnwatch.ctl\fR.  The default value is
928 \&\f(CW200\fR.
929 .IP "\fIinnwatchspoolspace\fR" 4
930 .IX Item "innwatchspoolspace"
931 Free space in \fIpatharticles\fR and \fIpathoverview\fR, in \fIinndf\fR\|(8) output
932 units (normally kilobytes), at which \fIinnd\fR\|(8) will be throttled by
933 \&\fIinnwatch\fR\|(8), assuming a default \fIinnwatch.ctl\fR.  The default value is
934 \&\f(CW8000\fR.
935 .Sh "Logging"
936 .IX Subsection "Logging"
937 These parameters control what information \s-1INN\s0 logs.
938 .IP "\fIdocnfsstat\fR" 4
939 .IX Item "docnfsstat"
940 Whether to start \fIcnfsstat\fR\|(8) when \fIinnd\fR\|(8) is started.  cnfsstat will log
941 the status of all \s-1CNFS\s0 cycbuffs to syslog on a periodic basis (frequency
942 is the default for \f(CW\*(C`cnfsstat \-l\*(C'\fR, currently 600 seconds).  This is a
943 boolean value and the default is false.
944 .IP "\fIlogartsize\fR" 4
945 .IX Item "logartsize"
946 Whether the size of accepted articles (in bytes) should be written to the
947 article log file.  This is useful for flow rate statistics and is
948 recommended.  This is a boolean value and the default is true.
949 .IP "\fIlogcancelcomm\fR" 4
950 .IX Item "logcancelcomm"
951 Set this to true to log \f(CW\*(C`ctlinnd cancel\*(C'\fR commands to syslog.  This is a
952 boolean value and the default is false.
953 .IP "\fIlogcycles\fR" 4
954 .IX Item "logcycles"
955 How many old logs \fIscanlogs\fR\|(8) keeps.  \fIscanlogs\fR\|(8) is generally run by
956 \&\fInews.daily\fR\|(8) and will archive compressed copies of this many days worth
957 of old logs.  The default value is \f(CW3\fR.
958 .IP "\fIlogipaddr\fR" 4
959 .IX Item "logipaddr"
960 Whether the verified name of the remote feeding host should be logged to
961 the article log for incoming articles rather than the last entry in the
962 Path: header.  The only reason to ever set this to false is due to some
963 interactions with \fInewsfeeds\fR flags; see \fInewsfeeds\fR\|(5) for more
964 information.  This is a boolean value and the default is true.
965 .IP "\fIlogsitename\fR" 4
966 .IX Item "logsitename"
967 Whether the names of the sites to which accepted articles will be sent
968 should be put into the article log file.  This is useful for debugging and
969 statistics and can be used by \fInewsrequeue\fR\|(8).  This is a boolean value and
970 the default is true.
971 .IP "\fInnrpdoverstats\fR" 4
972 .IX Item "nnrpdoverstats"
973 Whether nnrpd overview statistics should be logged via syslog.  This can
974 be useful for measuring overview performance.  This is a boolean value and
975 the default is false.
976 .IP "\fInntpactsync\fR" 4
977 .IX Item "nntpactsync"
978 How many articles to process on an incoming channel before logging the
979 activity.  The default value is \f(CW200\fR.
980 .Sp
981 \&\s-1FIXME:\s0 This is a rather unintuitive name for this parameter.
982 .IP "\fInntplinklog\fR" 4
983 .IX Item "nntplinklog"
984 Whether to put the storage \s-1API\s0 token for accepted articles (used by
985 nntplink) in the article log.  This is a boolean value and the default is
986 false.
987 .IP "\fIstathist\fR" 4
988 .IX Item "stathist"
989 Where to write history statistics for analysis with
990 \&\fIcontrib/\fR; this can be modified with \fIctlinnd\fR\|(8) while innd is
991 running.  Logging does not occur unless a path is given, and there is no
992 default value.
993 .IP "\fIstatus\fR" 4
994 .IX Item "status"
995 How frequently (in seconds) \fIinnd\fR\|(8) should write out a status report.  The
996 report is written to \fIpathhttp\fR/inn_status.html.  If this is set to \f(CW0\fR or
997 \&\f(CW\*(C`false\*(C'\fR, status reporting is disabled.  The default value is \f(CW0\fR.
998 .IP "\fItimer\fR" 4
999 .IX Item "timer"
1000 How frequently (in seconds) \fIinnd\fR\|(8) should report performance timings to
1001 syslog.  If this is set to \f(CW0\fR, performance timing is disabled.  Enabling
1002 this is highly recommended, and \fIinnreport\fR\|(8) can produce a nice summary of
1003 the timings.  If set to \f(CW0\fR, performance timings in \fInnrpd\fR\|(8) are also
1004 disabled, although nnrpd always reports statistics on exit and therefore
1005 any non-zero value is equivalent for it.  The default value is \f(CW0\fR.
1006 .Sh "System Tuning"
1007 .IX Subsection "System Tuning"
1008 The following parameters can be modified to tune the low-level operation
1009 of \s-1INN\s0.  In general, you shouldn't need to modify any of them except
1010 possibly \fIrlimitnofile\fR unless the server is having difficulty.
1011 .IP "\fIbadiocount\fR" 4
1012 .IX Item "badiocount"
1013 How many read or write failures until a channel is put to sleep or
1014 closed.  The default value is \f(CW5\fR.
1015 .IP "\fIblockbackoff\fR" 4
1016 .IX Item "blockbackoff"
1017 Each time an attempted write returns \s-1EAGAIN\s0 or \s-1EWOULDBLOCK\s0, \fIinnd\fR\|(8) will
1018 wait for an increasing number of seconds before trying it again.  This is
1019 the multiplier for the sleep time.  If you're having trouble with channel
1020 feeds not keeping up, it may be good to change this value to \f(CW2\fR or \f(CW3\fR,
1021 since then when the channel fills \s-1INN\s0 will try again in a couple of
1022 seconds rather than waiting two minutes.  The default value is \f(CW120\fR.
1023 .IP "\fIchaninacttime\fR" 4
1024 .IX Item "chaninacttime"
1025 The time (in seconds) to wait between noticing inactive channels.  The
1026 default value is \f(CW600\fR.
1027 .IP "\fIchanretrytime\fR" 4
1028 .IX Item "chanretrytime"
1029 How many seconds to wait before a channel restarts.  The default value is
1030 \&\f(CW300\fR.
1031 .IP "\fIdatamovethreshold\fR" 4
1032 .IX Item "datamovethreshold"
1033 The threshold for deciding whether to move already-read data to the top of
1034 buffer or extend the buffer.  The buffer described here is used for reading
1035 \&\s-1NNTP\s0 data.  Increasing this value may improve performance, but it should
1036 not be increased on Systems with insufficient memory.  Permitted values
1037 are between \f(CW0\fR and \f(CW1048576\fR (out of range values are treated as
1038 \&\f(CW1048576\fR) and the default value is \f(CW8192\fR.  
1039 .IP "\fIicdsynccount\fR" 4
1040 .IX Item "icdsynccount"
1041 How many article writes between updating the active and history files.
1042 The default value is \f(CW10\fR.
1043 .IP "\fIkeepmmappedthreshold\fR" 4
1044 .IX Item "keepmmappedthreshold"
1045 When using buffindexed, retrieving overview data (that is, responding to
1046 \&\s-1XOVER\s0 or running expireover) causes mmapping of all overview data blocks
1047 which include requested overview data for newsgroup.  But for high volume
1048 newsgroups like control.cancel, this may cause too much mmapping at once
1049 leading to system resource problems.  To avoid this, if the amount to be
1050 mmapped exceeds \fIkeepmmappedthreshold\fR (in \s-1KB\s0), buffindexed mmap's just
1051 one overview block (8 \s-1KB\s0).  This parameter is specific to buffindexed
1052 overview storage method.  The default value is \f(CW1024\fR (1 \s-1MB\s0).
1053 .IP "\fImaxcmdreadsize\fR" 4
1054 .IX Item "maxcmdreadsize"
1055 If set to anything other than \f(CW0\fR, maximum buffer size (in bytes) for
1056 reading \s-1NNTP\s0 command will have this value.  It should not be large on
1057 systems which are slow to process and store articles, as that would lead
1058 to \fIinnd\fR\|(8) spending a long time on each channel and keeping other channels
1059 waiting.  The default value is \s-1BUFSIZ\s0 defined in stdio.h (\f(CW1024\fR in most
1060 environments, see \fIsetbuf\fR\|(3)).
1061 .IP "\fImaxforks\fR" 4
1062 .IX Item "maxforks"
1063 How many times to attempt a \fIfork\fR\|(2) before giving up.  The default value
1064 is \f(CW10\fR.
1065 .IP "\fInicekids\fR" 4
1066 .IX Item "nicekids"
1067 If set to anything other than \f(CW0\fR, all child processes of \fIinnd\fR\|(8) will
1068 have this \fInice\fR\|(2) value.  This is usually used to give all child processes
1069 of \fIinnd\fR\|(8) a lower priority (higher nice value) so that \fIinnd\fR\|(8) can get
1070 the lion's share of the \s-1CPU\s0 when it needs it.  The default value is \f(CW4\fR.
1071 .IP "\fInicenewnews\fR" 4
1072 .IX Item "nicenewnews"
1073 If set to anything greater than \f(CW0\fR, all \fInnrpd\fR\|(8) processes that receive
1074 and process a \s-1NEWNEWS\s0 command will \fInice\fR\|(2) themselves to this value
1075 (giving other nnrpd processes a higher priority).  The default value is
1076 \&\f(CW0\fR.  Note that this value will be ignored if set to a lower value than
1077 \&\fInicennrpd\fR (or \fInicekids\fR if \fInnrpd\fR\|(8) is spawned from \fIinnd\fR\|(8)).
1078 .IP "\fInicennrpd\fR" 4
1079 .IX Item "nicennrpd"
1080 If set to anything greater than \f(CW0\fR, all \fInnrpd\fR\|(8) processes will \fInice\fR\|(1)
1081 themselves to this value.  This gives other news processes a higher
1082 priority and can help \fIoverchan\fR\|(8) keep up with incoming news (if that's
1083 the object, be sure \fIoverchan\fR\|(8) isn't also set to a lower priority via
1084 \&\fInicekids\fR).  The default value is \f(CW0\fR, which will cause \fInnrpd\fR\|(8)
1085 processes spawned from \fIinnd\fR\|(8) to use the value of \fInicekids\fR, while
1086 \&\fInnrpd\fR\|(8) run as a daemon will use the system default priority.  Note that
1087 for \fInnrpd\fR\|(8) processes spawned from \fIinnd\fR\|(8), this value will be ignored if
1088 set to a value lower than \fInicekids\fR.
1089 .IP "\fIpauseretrytime\fR" 4
1090 .IX Item "pauseretrytime"
1091 Wait for this many seconds before noticing inactive channels.
1092 Wait for this many seconds before innd processes articles when it's paused
1093 or the number of channel write failures exceeds \fIbadiocount\fR.  The
1094 default value is \f(CW300\fR.
1095 .IP "\fIpeertimeout\fR" 4
1096 .IX Item "peertimeout"
1097 How long (in seconds) an \fIinnd\fR\|(8) incoming channel may be inactive before
1098 innd closes it.  The default value is \f(CW3600\fR (an hour).
1099 .IP "\fIrlimitnofile\fR" 4
1100 .IX Item "rlimitnofile"
1101 The maximum number of file descriptors that \fIinnd\fR\|(8) or \fIinnfeed\fR\|(8) can have
1102 open at once.  If \fIinnd\fR\|(8) or \fIinnfeed\fR\|(8) attempts to open more file
1103 descriptors than this value, it is possible the program may throttle or
1104 otherwise suffer reduced functionality.  The number of open file
1105 descriptors is roughly the maximum number of incoming feeds and outgoing
1106 batches for \fIinnd\fR\|(8) and the number of outgoing streams for \fIinnfeed\fR\|(8).  If
1107 this parameter is set to a negative value, the default limit of the
1108 operating system will be used; this will normally be adequate on systems
1109 other than Solaris.  Nearly all operating systems have some hard maximum
1110 limit beyond which this value cannot be raised, usually either 128, 256,
1111 or 1024.  The default value of this parameter is \f(CW\*(C`\-1\*(C'\fR.  Setting it to
1112 \&\f(CW256\fR on Solaris systems is highly recommended.
1113 .Sh "Paths and File Names"
1114 .IX Subsection "Paths and File Names"
1115 .IP "\fIpatharchive\fR" 4
1116 .IX Item "patharchive"
1117 Where to store archived news.  The default value is \fIpathspool\fR/archive.
1118 .IP "\fIpatharticles\fR" 4
1119 .IX Item "patharticles"
1120 The path to where the news articles are stored (for storage methods other
1121 than \s-1CNFS\s0).  The default value is \fIpathspool\fR/articles.
1122 .IP "\fIpathbin\fR" 4
1123 .IX Item "pathbin"
1124 The path to the news binaries.  The default value is \fIpathnews\fR/bin.
1125 .IP "\fIpathcontrol\fR" 4
1126 .IX Item "pathcontrol"
1127 The path to the files that handle control messages.  The code for handling
1128 each separate type of control message is located here.  Be very careful
1129 what you put in this directory with a name ending in \f(CW\*(C`.pl\*(C'\fR, as it can
1130 potentially be a severe security risk.  The default value is
1131 \&\fIpathbin\fR/control.
1132 .IP "\fIpathdb\fR" 4
1133 .IX Item "pathdb"
1134 The path to the database files used and updated by the server (currently,
1135 \&\fIactive\fR, \fIactive.times\fR, \fIhistory\fR and its indices, and
1136 \&\fInewsgroups\fR).  The default value is \fIpathnews\fR/db.
1137 .IP "\fIpathetc\fR" 4
1138 .IX Item "pathetc"
1139 The path to the news configuration files.  The default value is
1140 \&\fIpathnews\fR/etc.
1141 .IP "\fIpathfilter\fR" 4
1142 .IX Item "pathfilter"
1143 The path to the Perl, Tcl, and Python filters.  The default value is
1144 \&\fIpathbin\fR/filter.
1145 .IP "\fIpathhttp\fR" 4
1146 .IX Item "pathhttp"
1147 Where any \s-1HTML\s0 files (such as periodic status reports) are placed.  If the
1148 news reports should be available in real-time on the web, the files in
1149 this directory should be served by a web server.  The default value is
1150 the value of \fIpathlog\fR.
1151 .IP "\fIpathincoming\fR" 4
1152 .IX Item "pathincoming"
1153 Location where incoming batched news is stored.  The default value is
1154 \&\fIpathspool\fR/incoming.
1155 .IP "\fIpathlog\fR" 4
1156 .IX Item "pathlog"
1157 Where the news log files are written.  The default value is
1158 \&\fIpathnews\fR/log.
1159 .IP "\fIpathnews\fR" 4
1160 .IX Item "pathnews"
1161 The home directory of the news user and usually the root of the news
1162 hierarchy.  There is no default; this parameter must be set in \fIinn.conf\fR
1163 or \s-1INN\s0 will refuse to start.
1164 .IP "\fIpathoutgoing\fR" 4
1165 .IX Item "pathoutgoing"
1166 Default location for outgoing feed files.  The default value is
1167 \&\fIpathspool\fR/outgoing.
1168 .IP "\fIpathoverview\fR" 4
1169 .IX Item "pathoverview"
1170 The path to news overview files.  The default value is
1171 \&\fIpathspool\fR/overview.
1172 .IP "\fIpathrun\fR" 4
1173 .IX Item "pathrun"
1174 The path to files required while the server is running and run-time state
1175 information.  This includes lock files and the sockets for communicating
1176 with \fIinnd\fR\|(8).  This directory and the control sockets in it should be
1177 protected from unprivileged users other than the news user.  The default
1178 value is \fIpathnews\fR/run.
1179 .IP "\fIpathspool\fR" 4
1180 .IX Item "pathspool"
1181 The root of the news spool hierarchy.  This used mostly to set the
1182 defaults for other parameters, and to determine the path to the backlog
1183 directory for \fIinnfeed\fR\|(8).  The default value is \fIpathnews\fR/spool.
1184 .IP "\fIpathtmp\fR" 4
1185 .IX Item "pathtmp"
1186 Where \s-1INN\s0 puts temporary files.  For security reasons, this is not the
1187 same as the system temporary files directory (\s-1INN\s0 creates a lot of
1188 temporary files with predictable names and does not go to particularly
1189 great lengths to protect against symlink attacks and the like; this
1190 is safe provided that normal users can't write into its temporary
1191 directory).  The default value is set at configure time and defaults to
1192 \&\fIpathnews\fR/tmp.
1193 .SH "EXAMPLE"
1194 .IX Header "EXAMPLE"
1195 Here is a very minimalist example that only sets those parameters that are
1196 required.
1197 .PP
1198 .Vb 5
1199 \&    mta:                /usr/lib/sendmail \-oi \-oem %s
1200 \&    ovmethod:           tradindexed
1201 \&    pathhost: 
1202 \&    pathnews:           /usr/local/news
1203 \&    hismethod:          hisv6
1204 .Ve
1205 .PP
1206 For a more comprehensive example, see the sample \fIinn.conf\fR distributed
1207 with \s-1INN\s0 and installed as a starting point; it contains all of the default
1208 values for reference.
1209 .SH "HISTORY"
1210 .IX Header "HISTORY"
1211 Written by Rich \f(CW$alz\fR <> for InterNetNews and since
1212 modified, updated, and reorganized by innumerable other people.
1213 .PP
1214 $Id: inn.conf.5 7880 2008-06-16 20:37:13Z iulius $
1215 .SH "SEE ALSO"
1216 .IX Header "SEE ALSO"
1217 \&\fIinews\fR\|(1), \fIinnd\fR\|(8), \fIinnwatch\fR\|(8), \fInnrpd\fR\|(8), \fIrnews\fR\|(1).
1218 .PP
1219 Nearly every program in \s-1INN\s0 uses this file to one degree or another.  The
1220 above are just the major and most frequently mentioned ones.