1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
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<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
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
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.
57 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
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
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . \" simple accents for nroff and troff
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'
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 \
129 .\" ========================================================================
131 .IX Title "READERS.CONF 5"
132 .TH READERS.CONF 5 "2008-06-22" "INN 2.4.5" "InterNetNews Documentation"
134 readers.conf \- Access control and configuration for nnrpd
136 .IX Header "DESCRIPTION"
137 \&\fIreaders.conf\fR in \fIpathetc\fR specifies access control for \fInnrpd\fR\|(8). It
138 controls who is allowed to connect as a news reader and what they're
139 allowed to do after they connect. nnrpd reads this file when it starts
140 up. This generally means that any changes take effect immediately on all
141 subsequent connections, but \fBnnrpd\fR may have to be restarted if you use
142 the \fB\-D\fR option. (The location \fIpathetc\fR/readers.conf is only the
143 default; the same format applies to any file specified with \f(CW\*(C`nnrpd \-c\*(C'\fR.)
145 There are two types of entries in \fIreaders.conf\fR: parameter/value pairs
146 and configuration groups. Blank lines and anything after a number sign
147 (\f(CW\*(C`#\*(C'\fR) are ignored, unless the character \f(CW\*(C`#\*(C'\fR is escaped with \f(CW\*(C`\e\*(C'\fR. The
148 maximum number of characters on each line is 8,191.
150 Parameter/value pairs consist of a keyword immediately followed by a
151 colon, at least one whitespace character, and a value. The case of the
152 parameter is significant (parameter should generally be in all lowercase),
153 and a parameter may contain any characters except colon, \f(CW\*(C`#\*(C'\fR, and
154 whitespace. An example:
157 \& hosts: *.example.com
160 Values that contain whitespace should be quoted with double quotes, as in:
163 \& hosts: "*.example.com, *.example.net"
166 If the parameter does not contain whitespace, such as:
169 \& hosts: *.example.com,*.example.net
172 it's not necessary to quote it, although you may wish to anyway for
175 There is no way to continue a line on the next line, and therefore no way
176 to have a single parameter with a value longer than about 8,180
179 Many parameters take a boolean value. For all such parameters, the value
180 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
181 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
184 There are two basic types of configuration groups, auth and access. The
185 auth group provides mechanisms to establish the identity of the user, who
186 they are. The access group determines, given the user's identity, what
187 that user is permitted to do. Writing a \fIreaders.conf\fR file for your
188 setup is a two-step process: first assigning an identity to each incoming
189 connection using auth groups, and then giving each identity appropriate
190 privileges with access group. We recommend \fInot\fR intermingling auth
191 groups and access groups in the config file; it is often more sensible (in
192 the absence of the \fIkey\fR parameter) to put all of the auth groups first,
193 and all of the access groups below.
195 A user identity, as established by an auth group, looks like an e\-mail
196 address; in other words, it's in the form \*(L"<username>@<domain>\*(R" (or
197 sometimes just \*(L"<username>\*(R" if no domain is specified.
199 If \fInnrpdauthsender\fR is set in \fIinn.conf\fR, the user identity is also put
200 into the Sender: header of posts made by that user. See the documentation
201 of that option in \fIinn.conf\fR\|(5) for more details.
203 An auth group definition looks like:
207 \& hosts: <host\-wildmat>
208 \& auth: <auth\-program>
209 \& res: <res\-program>
210 \& default: <defuser>
211 \& default\-domain: <defdomain>
212 \& # ...possibly other settings
216 The <name> is used as a label for the group and is only for documentation
217 purposes. (If your syslog configuration records the \f(CW\*(C`news.debug\*(C'\fR
218 facility, the <name> will appear in the debugging output of nnrpd.
219 Examining that output can be very helpful in understanding why your
220 configuration doesn't do what you expect it to.)
222 A given auth group applies only to hosts whose name or \s-1IP\s0 address matches
223 the wildmat expression given with the hosts: parameter (comma\-separated
224 wildmat expressions allowed, but \f(CW\*(C`@\*(C'\fR is not supported). Rather than
225 wildmat expressions, you may also use \s-1CIDR\s0 notation to match any \s-1IP\s0
226 address in a netblock; for example, \*(L"10.10.10.0/24\*(R" will match any \s-1IP\s0
227 address between 10.10.10.0 and 10.10.10.255 inclusive.
229 If compiled against the \s-1SSL\s0 libraries, an auth group with the require_ssl:
230 parameter set to true only applies if the incoming connection is using
233 For any connection from a host that matches that wildmat expression or
234 netblock, each <res\-program> (multiple res: lines may be present in a
235 block; they are run in sequence until one succeeds), if any, is run to
236 determine the identity of the user just from the connection information.
237 If all the resolvers fail, or if the res: parameter isn't present, the
238 user is assigned an identity of \*(L"<defuser>@<defdomain>\*(R"; in other words,
239 the values of the default: and default\-domain: parameters are used. If
240 <res\-program> only returns a username, <defdomain> is used as the
243 If the user later authenticates via the \s-1AUTHINFO\s0 \s-1USER/PASS\s0 commands, the
244 provided username and password are passed to each <auth\-program> (multiple
245 auth, perl_auth, or python_auth lines may be present in a block; they are
246 run in sequence until one succeeds), if any. If one succeeds and returns
247 a different identity than the one assigned at the time of the connection,
248 it is matched against the available access groups again and the actions
249 the user is authorized to do may change. The most common <auth\-program>
250 to use is \fBckpasswd\fR, which supports several ways of checking passwords
251 including using \s-1PAM\s0. See the \fIckpasswd\fR\|(8) man page for more details.
253 When matching auth groups, the last auth group in the file that matches a
254 given connection and username/password combination is used.
256 An access group definition usually looks like:
260 \& users: <identity\-wildmat>
261 \& newsgroups: <group\-wildmat>
262 \& # ...possibly other settings
266 Again, <name> is just for documentation purposes. This says that all
267 users whose identity matches <identity\-wildmat> can read and post to all
268 newsgroups matching <group\-wildmat> (as before, comma-separated wildmat
269 expressions are allowed, but \f(CW\*(C`@\*(C'\fR is not supported). Alternately, you can
274 \& users: <identity\-wildmat>
275 \& read: <read\-wildmat>
276 \& post: <post\-wildmat>
280 and matching users will be able to read any group that matches
281 <read\-wildmat> and post to any group that matches <post\-wildmat>. You can
282 also set several other things in the access group as well as override
283 various \fIinn.conf\fR\|(5) parameters for just a particular group of users.
285 Just like with auth groups, when matching access groups the last matching
286 one in the file is used to determine the user's permissions. There is
287 an exception to this rule: if the auth group which matched the client
288 contains a perl_access: or python_access: parameter, then the script
289 given as argument is used to dynamically generate an access group.
290 This new access group is then used to determine the access rights of
291 the client; the access groups in the file are ignored.
293 There is one additional special case to be aware of. When forming
294 particularly complex authentication and authorization rules, it is
295 sometimes useful for the identities provided by a given auth group to only
296 apply to particular access groups; in other words, rather than checking
297 the identity against the users: parameter of every access group, it's
298 checked against the users: parameter of only some specific access groups.
299 This is done with the key: parameter. For example:
304 \& hosts: *.example.com
305 \& default: <SPECIAL>
317 In this case, the two key: parameters bind this auth group with this
318 access group. For any incoming connection matching \*(L"*.example.com\*(R"
319 (assuming there isn't any later auth group that also matches such hosts),
320 no access group that doesn't have \*(L"key: special\*(R" will even be considered.
321 Similarly, the above access group will only be checked if the user was
322 authenticated with an auth group containing \*(L"key: special\*(R". This
323 mechanism normally isn't useful; there is almost always a better way to
324 achieve the same result.
326 Also note in the example that there's no default\-domain: parameter, which
327 means that no domain is appended to the default username and the identity
328 for such connections is just \*(L"<\s-1SPECIAL\s0>\*(R". Note that some additional
329 add-ons to \s-1INN\s0 may prefer that authenticated identities always return a
330 full e\-mail address (including a domain), so you may want to set up your
333 Below is the full list of allowable parameters for auth groups and access
334 groups, and after that are some examples that may make this somewhat
336 .SH "AUTH GROUP PARAMETERS"
337 .IX Header "AUTH GROUP PARAMETERS"
338 An access group without at least one of the res:, auth:, perl_auth:,
339 python_auth:, or default: parameters makes no sense (and in practice will
343 A comma-separated list of remote hosts, wildmat patterns matching either
344 hostnames or \s-1IP\s0 addresses, or \s-1IP\s0 netblocks specified in \s-1CIDR\s0 notation. If
345 a user connects from a host that doesn't match this parameter, this auth
346 group will not match the connection and is ignored.
348 Note that if you have a large number of patterns that can't be merged into
349 broader patterns (such as a large number of individual systems scattered
350 around the net that should have access), the hosts: parameter may exceed
351 the maximum line length of 8,192 characters. In that case, you'll need to
352 break that auth group into multiple auth groups, each with a portion of
353 the hosts listed in its hosts: parameter, and each assigning the same user
356 All hosts match if this parameter is not given.
357 .IP "\fBlocaladdress:\fR" 4
358 .IX Item "localaddress:"
359 A comma-separated list of local host or address patterns with the same
360 syntax as the same as with the hosts: parameter. If this parameter is
361 specified, its auth group will only match connections made to a matching
362 local interface. (Obviously, this is only useful for servers with
363 multiple interfaces.)
365 All local addresses match if this parameter is not given.
368 A simple command line for a user resolver (shell metacharacters are not
369 supported). If a full path is not given, the program executed must be in
370 the \fIpathbin\fR/auth/resolv directory. A resolver is an authentication
371 program which attempts to figure out the identity of the connecting user
372 using nothing but the connection information (in other words, the user
373 has not provided a username and password). An examples of a resolver
374 would be a program that assigns an identity from an ident callback or
375 from the user's hostname.
377 One auth group can have multiple res: parameters, and they will be tried
378 in the order they're listed. The results of the first successful one
382 A simple command line for a user authenticator (shell metacharacters are
383 not supported). If a full path is not given, the program executed must be
384 located in the \fIpathbin\fR/auth/passwd directory. An authenticator is a
385 program used to handle a user-supplied username and password, via a
386 mechanism such as \s-1AUTHINFO\s0 \s-1USER/PASS\s0. Like with res:, one auth group can
387 have multiple auth: parameters; they will be tried in order and the
388 results of the first successful one will be used. See also perl_auth:
391 The most common authenticator to use is \fIckpasswd\fR\|(8); see its man page for
393 .IP "\fBperl_auth:\fR" 4
394 .IX Item "perl_auth:"
395 A path to a perl script for authentication. The perl_auth: parameter
396 works exactly like auth:, except that it calls the named script using
397 the perl hook rather then an external program. Multiple/mixed use of
398 the auth, perl_auth, and python_auth parameters is permitted within any
399 auth group; each line is tried in the order it appears. perl_auth:
400 has more power than auth: in that it provides the authentication
401 program with additional information about the client and the ability
402 to return an error string and a username. This parameter is only
403 valid if \s-1INN\s0 is compiled with Perl support (\fB\-\-with\-perl\fR passed to
404 configure). More information may be found in \fIdoc/hook\-perl\fR.
405 .IP "\fBpython_auth:\fR" 4
406 .IX Item "python_auth:"
407 A Python script for authentication. The \fIpython_auth\fR parameter works
408 exactly like \fIauth\fR, except that it calls the named script (without its
409 \&\f(CW\*(C`.py\*(C'\fR extension) using the Python hook rather then an external program.
410 Multiple/mixed use of the \fIauth\fR, \fIperl_auth\fR, and \fIpython_auth\fR
411 parameters is permitted within any auth group; each line is tried
412 in the order it appears. \fIpython_auth\fR has more power than \fIauth\fR
413 in that it provides the authentication program with additional information
414 about the client and the ability to return an error string and a username.
415 This parameter is only valid if \s-1INN\s0 is compiled with Python support
416 (\fB\-\-with\-python\fR passed to \fBconfigure\fR). More information may be
417 found in \fIdoc/hook\-python\fR.
418 .IP "\fBdefault:\fR" 4
420 The default username for connections matching this auth group. This is
421 the username assigned to the user at connection time if all resolvers fail
422 or if there are no res: parameters. Note that it can be either a bare
423 username, in which case default\-domain: (if present) is appended after
424 an \f(CW\*(C`@\*(C'\fR, or a full identity string containing an \f(CW\*(C`@\*(C'\fR, in which case it
425 will be used verbatim.
426 .IP "\fBdefault\-domain:\fR" 4
427 .IX Item "default-domain:"
428 The default domain string for this auth group. If a user resolver or
429 authenticator doesn't provide a domain, or if the default username is used
430 and it doesn't contain a \f(CW\*(C`@\*(C'\fR, this domain is used to form the user
431 identity. (Note that for a lot of setups, it's not really necessary for
432 user identities to be qualified with a domain name, in which case there's
433 no need to use this parameter.)
436 If this parameter is present, any connection matching this auth group will
437 have its privileges determined only by the subset of access groups
438 containing a matching key parameter.
439 .IP "\fBrequire_ssl:\fR" 4
440 .IX Item "require_ssl:"
441 If set to true, an incoming connection only matches this auth group if
442 it is encrypted using \s-1SSL\s0. This parameter is only valid if \s-1INN\s0 is
443 compiled with \s-1SSL\s0 support (\fB\-\-with\-openssl\fR passed to configure).
444 .IP "\fBperl_access:\fR" 4
445 .IX Item "perl_access:"
446 A path to a perl script for dynamically generating an access group. If
447 an auth group matches successfully and contains a perl_access parameter,
448 then the argument perl script will be used to create an access group.
449 This group will then determine the access rights of the client,
450 overriding any access groups in \fIreaders.conf\fR. If and only if a
451 sucessful auth group contains the perl_access parameter, \fIreaders.conf\fR
452 access groups are ignored and the client's rights are instead determined
453 dynamically. This parameter is only valid if \s-1INN\s0 is compiled with Perl
454 support (\fB\-\-with\-perl\fR passed to configure). More information may be
455 found in the file \fIdoc/hook\-perl\fR.
456 .IP "\fBpython_access:\fR" 4
457 .IX Item "python_access:"
458 A Python script for dynamically generating an access group. If
459 an auth group matches successfully and contains a \fIpython_access\fR parameter,
460 then the argument script (without its \f(CW\*(C`.py\*(C'\fR extension) will be used to
461 create an access group. This group will then determine the access rights
462 of the client, overriding any access groups in \fIreaders.conf\fR. If and only
463 if a successful auth group contains the \fIpython_access\fR parameter, \fIreaders.conf\fR
464 access groups are ignored and the client's rights are instead determined
465 dynamically. This parameter is only valid if \s-1INN\s0 is compiled with Python
466 support (\fB\-\-with\-python\fR passed to \fBconfigure\fR). More information may be
467 found in the file \fIdoc/hook\-python\fR.
468 .IP "\fBpython_dynamic:\fR" 4
469 .IX Item "python_dynamic:"
470 A Python script for applying access control dynamically on a per newsgroup
471 basis. If an auth group matches successfully and contains a
472 \&\fIpython_dynamic\fR parameter, then the argument script (without its
473 \&\f(CW\*(C`.py\*(C'\fR extension) will be used to determine the clients rights each time
474 the user attempts to view a newsgroup, or read or post an article. Access
475 rights as determined by \fIpython_dynamic\fR override the values of access
476 group parameters such as \fInewsgroups\fR, \fIread\fR and \fIpost\fR. This parameter
477 is only valid if \s-1INN\s0 is compiled with Python support (\fB\-\-with\-python\fR
478 passed to \fBconfigure\fR). More information may be found in the file
479 \&\fIdoc/hook\-python\fR.
480 .SH "ACCESS GROUP PARAMETERS"
481 .IX Header "ACCESS GROUP PARAMETERS"
484 The privileges given by this access group apply to any user identity which
485 matches this comma-separated list of wildmat patterns. If this parameter
486 isn't given, the access group applies to all users (and is essentially
487 equivalent to \f(CW\*(C`users: *\*(C'\fR).
488 .IP "\fBnewsgroups:\fR" 4
489 .IX Item "newsgroups:"
490 Users that match this access group are allowed to read and post to all
491 newsgroups matching this comma-separated list of wildmat patterns. The
492 empty string is equivalent to \f(CW\*(C`newsgroups: *\*(C'\fR; if this parameter is
493 missing, the connection will be rejected (unless read: and/or post: are
494 used instead, see below).
497 Like the newsgroups: parameter, but the client is only given permission to
498 read the matching newsgroups. This parameter is often used with post:
499 (below) to specify some read-only groups; it cannot be used in the same
500 access group with a newsgroups: parameter. (If read: is used and post:
501 is missing, the client will have only read-only access.)
504 Like the newsgroups: parameter, but the client is only given permission to
505 post to the matching newsgroups. This parameter is often used with read:
506 (above) to define the patterns for reading and posting separately (usually
507 to give the user permission to read more newsgroups than they're permitted
508 to post to). It cannot be used in the same access group with a
509 newsgroups: parameter.
510 .IP "\fBaccess:\fR" 4
512 A set of letters specifying the permissions granted to the client. The
513 letters are chosen from the following set:
517 The client may read articles.
520 The client may post articles.
523 The client may inject articles with \s-1IHAVE\s0. Note that in order to
524 inject articles with the \s-1IHAVE\s0 the user must also have \s-1POST\s0 permission
525 (the \f(CW\*(C`P\*(C'\fR option).
528 The client may post articles with Approved: headers (in other words, may
529 approve articles for moderated newsgroups). By default, this is not
533 The client may use the \s-1NEWNEWS\s0 command, overriding the global setting.
536 The client may post to newsgroups that are set to disallow local posting
537 (mode \f(CW\*(C`n\*(C'\fR in the \fIactive\fR\|(5) file).
541 Note that if this parameter is given, \fIallownewnews\fR in \fIinn.conf\fR is
542 ignored for connections matching this access group and the ability of the
543 client to use \s-1NEWNEWS\s0 is entirely determined by the presence of \f(CW\*(C`N\*(C'\fR in
544 the access string. If you want to support \s-1NEWNEWS\s0, make sure to include
545 \&\f(CW\*(C`N\*(C'\fR in the access string when you use this parameter.
547 Note that if this parameter is given and \f(CW\*(C`R\*(C'\fR isn't present in the access
548 string, the client cannot read regardless of newsgroups: or read:
549 parameters. Similarly, if this parameter is given and \f(CW\*(C`P\*(C'\fR isn't present,
550 the client cannot post. This use of access: is deprecated and confusing;
551 it's strongly recommended that if the access: parameter is used, \f(CW\*(C`R\*(C'\fR and
552 \&\f(CW\*(C`P\*(C'\fR always be included in the access string and newsgroups:, read:, and
553 post: be used to control access. (To grant read access but no posting
554 access, one can have just a read: parameter and no post: parameter.)
558 If this parameter is present, this access group is only considered when
559 finding privileges for users matching auth groups with this same key:
561 .IP "\fBreject_with:\fR" 4
562 .IX Item "reject_with:"
563 If this parameter is present, a client matching this block will be
564 disconnected with a \*(L"Permission denied\*(R" message containing the contents
565 (a \*(L"reason\*(R" string) of this parameter. Some newsreaders will then
566 display the reason to the user.
567 .IP "\fBmax_rate:\fR" 4
569 If this parameter is present (and nonzero), it is used for \fBnnrpd\fR's
570 rate-limiting code. The client will only be able to download at this
571 speed (in bytes/second). Note that if \s-1SSL\s0 is being used, limiting
572 is applied to the pre-encryption datastream.
573 .IP "\fBlocaltime:\fR" 4
574 .IX Item "localtime:"
575 If a Date: header is not included in a posted article, \fInnrpd\fR\|(8) normally
576 adds a new Date: header in \s-1UTC\s0. If this is set to true, the Date: header
577 will be formatted in local time instead. This is a boolean value and the
579 .IP "\fBnewsmaster:\fR" 4
580 .IX Item "newsmaster:"
581 Used as the contact address in the help message returned by \fInnrpd\fR\|(8), if
582 the virtualhost: parameter is set to true.
583 .IP "\fBstrippath:\fR" 4
584 .IX Item "strippath:"
585 If set to true, any Path: header provided by a user in a post is stripped
586 rather than used as the beginning of the Path: header of the article.
587 This is a boolean value and the default is false.
588 .IP "\fBperlfilter:\fR" 4
589 .IX Item "perlfilter:"
590 If set to false, posts made by these users do not pass through the Perl
591 filter even if it is otherwise enabled. This is a boolean value and the
593 .IP "\fBpythonfilter:\fR" 4
594 .IX Item "pythonfilter:"
595 If set to false, posts made by these users do not pass through the Python
596 filter even if it is otherwise enabled. This is a boolean value and the
598 .IP "\fBvirtualhost:\fR" 4
599 .IX Item "virtualhost:"
600 Set this parameter to true in order to make \fBnnrpd\fR behave as if it is
601 running on a server with a different name than it actually is. If you
602 set this parameter to true, you must also set either pathhost: or domain:
603 in the relevant access group in \fIreaders.conf\fR to something different
604 than is set in \fIinn.conf\fR. All articles displayed to clients will then have
605 their Path: and Xref: headers altered to appear to be from the server
606 named in pathhost: or domain: (whichever is set), and posted articles will
607 use that server name in the Path:, Message\-ID:, and X\-Trace: headers.
609 Note that setting this parameter requires the server modify all posts
610 before presenting them to the client and therefore may decrease
611 performance slightly.
613 In addition, all of the following parameters are valid in access groups
614 and override the global setting in \fIinn.conf\fR. See \fIinn.conf\fR\|(5) for the
615 descriptions of these parameters:
618 \& addnntppostingdate, addnntppostinghost, backoff_auth, backoff_db,
619 \& backoff_k, backoff_postfast, backoff_postslow, backoff_trigger,
620 \& checkincludedtext, clienttimeout, complaints, domain,
621 \& fromhost, localmaxartsize, moderatormailer, nnrpdauthsender,
622 \& nnrpdcheckart, nnrpdoverstats, nnrpdposthost, nnrpdpostport, organization,
623 \& pathhost, readertrack, spoolfirst, strippostcc.
627 Here's a basic summary of what happens when a client connects:
629 All auth groups are scanned and the ones that don't match the client
630 (due to hosts:, localaddress:, require_ssl:, etc) are eliminated.
632 The remaining auth groups are scanned from the last to the first, and an
633 attempt is made to apply it to the current connection. This means running
634 res: programs, if any, and otherwise applying default:. The first auth
635 group (starting from the bottom) to return a valid user is kept as the
638 If no auth groups yield a valid user (none have default: parameters or
639 successful res: programs) but some of the auth groups have auth: lines
640 (indicating a possibility that the user can authenticate and then obtain
641 permissions), the connection is considered to have no valid auth group
642 (which means that the access groups are ignored completely) but the
643 connection isn't closed. Instead, 480 is returned for everything until
644 the user authenticates.
646 When the user authenticates, the auth groups are rescanned, and only the
647 matching ones which contain at least one auth, perl_auth, or
648 python_auth line are considered. These auth groups are scanned from
649 the last to the first, running auth: programs and perl_auth: or
650 python_auth: scripts. The first auth group (starting from the bottom)
651 to return a valid user is kept as the active auth group.
653 Regardless of how an auth group is established, as soon as one is, that
654 auth group is used to assign a user identity by taking the result of the
655 successful res, auth, perl_auth, or python_auth line (or the
656 default: if necessary), and appending the default-domain if
657 necessary. (If the perl_access: or python_access: parameter is
660 Finally, an access group is selected by scanning the access groups from
661 bottom up and finding the first match. (If the established auth group
662 contained a perl_access: or python_access line, the dynamically
663 generated access group returned by the script is used instead.)
664 User permissions are granted based on the established access group.
666 .IX Header "EXAMPLES"
667 Probably the simplest useful example of a complete \fIreaders.conf\fR,
668 this gives permissions to read and post to all groups to any connections
669 from the \*(L"example.com\*(R" domain, and no privileges for anyone connecting
673 \& auth example.com {
674 \& hosts: "*.example.com, example.com"
685 Note that the access realm has no users: key and therefore applies to any
686 user identity. The only available auth realm only matches hosts in the
687 \&\*(L"example.com\*(R" domain, though, so any connections from other hosts will be
688 rejected immediately.
690 If you have some systems that should only have read-only access to the
691 server, you can modify the example above slightly by adding an additional
692 auth and access group:
696 \& hosts: "*.lab.example.com"
708 If those are put in the file after the above example, they'll take
709 precedence (because they're later in the file) for any user coming from a
710 machine in the lab.example.com domain, everyone will only have read
711 access, not posting access.
713 Here's a similar example for a news server that accepts connections from
714 anywhere but requires the user to specify a username and password. The
715 username and password are first checked against an external database of
716 usernames and passwords, and then against the system shadow password file:
720 \& auth: "ckpasswd \-d <pathdb in inn.conf>/newsusers"
721 \& auth: "ckpasswd \-s"
732 When the user first connects, there are no res: keys and no default, so
733 they don't receive any valid identity and the connection won't match any
734 access groups (even ones with \f(CW\*(C`users: *\*(C'\fR). Such users receive nothing
735 but authentication-required responses from nnrpd until they authenticate.
737 If they then later authenticate, the username and password are checked
738 first by running \fBckpasswd\fR with the \fB\-d\fR option for an external dbm
739 file of encrypted passwords, and then with the \fB\-s\fR option to check the
740 shadow password database (note that this option may require ckpasswd to
741 be setgid to a shadow group, and there are security considerations; see
742 \&\fIckpasswd\fR\|(8) for details). If both of those fail, the user will continue
743 to have no identity; otherwise, an identity will be assigned (usually
744 the supplied username, perhaps with a domain appended, although an
745 authenticator technically can provide a completely different username
746 for the identity), and the access group will match, giving full access.
748 It may be educational to consider how to combine the above examples;
749 general groups always go first. The order of the auth groups actually
750 doesn't matter, since the \*(L"hosts: example.com\*(R" one only matches
751 connections before username/password is sent, and the \*(L"auth: ckpasswd\*(R"
752 one only matches after; order would matter if either group applied to
753 both cases. The order of the access groups in this case does matter,
754 provided the newsgroups: lines differ; the access group with no users:
755 line needs to be first, with the \*(L"users: <\s-1LOCAL\s0>\*(R" group after.
757 Here's a very complicated example. This is for an organization that has
758 an internal hierarchy \*(L"example.*\*(R" only available to local shell users, who
759 are on machines where identd can be trusted. Dialup users must provide a
760 username and password, which is then checked against \s-1RADIUS\s0. Remote users
761 have to use a username and password that's checked against a database on
762 the news server. Finally, the admin staff (users \*(L"joe\*(R" and \*(L"jane\*(R") can
763 post anywhere (including the \*(L"example.admin.*\*(R" groups that are read-only
764 for everyone else), and are exempted from the Perl filter. For an
765 additional twist, posts from dialup users have their Sender: header
766 replaced by their authenticated identity.
768 Since this organization has some internal moderated newsgroups, the admin
769 staff can also post messages with Approved: headers, but other users
774 \& auth: "ckpasswd \-f <pathdb in inn.conf>/newsusers"
776 \& default\-domain: example.com
782 \& hosts: *.shell.example.com
784 \& auth: "ckpasswd \-s"
786 \& default\-domain: shell.example.com
792 \& hosts: *.dialup.example.com
795 \& default\-domain: dialup.example.com
801 \& users: *@shell.example.com
803 \& post: "*, !example.admin.*"
809 \& users: *@dialup.example.com
810 \& newsgroups: *,!example.*
811 \& nnrpdauthsender: true
817 \& users: "*@example.com, !<FAIL>@example.com"
818 \& newsgroups: *,!example.*
831 \& users: "joe@*,jane@*"
838 Note the use of different domains to separate dialup from shell users
839 easily. Another way to do that would be with key: parameters, but this
840 way provides slightly more intuitive identity strings. Note also that the
841 fail access group catches not only failing connections from external users
842 but also failed authentication of shell and dialup users and dialup users
843 before they've authenticated. The identity string given for, say, dialup
844 users before \s-1RADIUS\s0 authentication has been attempted matches both the
845 dialup access group and the fail access group, since it's
846 \&\*(L"<\s-1FAIL\s0>@dialup.example.com\*(R", but the fail group is last so it takes
849 The shell auth group has an auth: parameter so that users joe and jane
850 can, if they choose, use username and password authentication to gain
851 their special privileges even if they're logged on as a different user on
852 the shell machines (or if ident isn't working). When they first connect,
853 they'd have the default access for that user, but they could then send
854 \&\s-1AUTHINFO\s0 \s-1USER\s0 and \s-1AUTHINFO\s0 \s-1PASS\s0 (or \s-1AUTHINFO\s0 \s-1SIMPLE\s0) and get their
857 Also note that if the users joe and jane are using their own accounts,
858 they get their special privileges regardless of how they connect, whether
859 the dialups, the shell machines, or even externally with a username and
862 Finally, here's a very simple example of a configuration for a public
863 server for a particular hierarchy.
875 \& newsgroups: example.*
879 Notice that clients aren't allowed to read any other groups; this keeps
880 them from getting access to administrative groups or reading control
881 messages, just as a precaution. When running a public server like this,
882 be aware that many public hierarchies will later be pulled down and
883 reinjected into the main Usenet, so it's highly recommended that you also
884 run a Perl or Python filter to reject any messages crossposted out of your
885 local hierarchy and any messages containing a Supersedes: header. This
886 will keep messages posted to your public hierarchy from hurting any of the
887 rest of Usenet if they leak out.
888 .SH "SECURITY CONSIDERATIONS"
889 .IX Header "SECURITY CONSIDERATIONS"
890 In general, separate passwords should be used for \s-1NNTP\s0 wherever
891 possible; the \s-1NNTP\s0 protocol itself does not protect passwords from
892 casual interception, and many implementations (including this one) do
893 not \*(L"lock out\*(R" accounts or otherwise discourage password-guessing
894 attacks. So it is best to ensure that a compromised password has
897 Authentication using the \s-1AUTHINFO\s0 \s-1USER/PASS\s0 commands passes unencrypted
898 over the network. Extreme caution should therefore be used especially
899 with system passwords (e.g. \f(CW\*(C`auth: ckpasswd \-s\*(C'\fR). Passwords can be
900 protected by using \s-1NNTP\s0 over \s-1SSL\s0 or through ssh tunnels, and this usage
901 can be enforced by a well-considered server configuration that only
902 permits certain auth groups to be applied in certain cases. Here are
905 To restrict connections on the standard nntp port (119) to use \s-1SSL\s0 for
906 some (or all) of the auth groups to match, use the require_ssl:
909 If you consider your local network (but not the internet) secure, have
910 some auth groups with a restrictive hosts: parameter; they would go
911 above, with ones having global applicability below.
913 Consider running a \f(CW\*(C`nnrpd \-S\*(C'\fR (with \f(CW\*(C`\-D\*(C'\fR, or out of \*(L"super\-server\*(R"
914 like \fBinetd\fR) on the \s-1NNTPS\s0 port (563) for clients that support \s-1SSL\s0. See
915 \&\fInnrpd\fR\|(8) for more details about how to configure that. You
916 can use the require_ssl: parameter, or \f(CW\*(C`\-c\*(C'\fR to specify an alternate
917 \&\fIreaders.conf\fR if you want a substantially different configuration for
920 If you want to restrict an auth group to only match loopback connections
921 (for users running newsreaders on localhost or connecting via an ssh
922 tunnel), use the localaddress: parameter.
925 Written by Aidan Cully <aidan@panix.com> for InterNetNews. Substantially
926 expanded by Russ Allbery <rra@stanford.edu>.
928 $Id: readers.conf.5 7895 2008-06-22 17:54:10Z iulius $
930 .IX Header "SEE ALSO"
931 \&\fIauth_krb5\fR\|(8), \fIauth_smb\fR\|(8), \fIckpasswd\fR\|(8), \fIinn.conf\fR\|(5), \fIinnd\fR\|(8), \fInewsfeeds\fR\|(5),
932 \&\fInnrpd\fR\|(8), \fIuwildmat\fR\|(3).
~ian / inn-innduct.git / blob