1READERS.CONF(5) InterNetNews Documentation READERS.CONF(5)
2
6 readers.conf - Access control and configuration for nnrpd
7
9 The readers.conf file parameters who is allowed to connect as a news
10 reader and what they're allowed to do after they connect. Bear in mind
11 that in readers.conf, authentication and authorization are configured
12 in different blocks. First, a user is authenticated, and assigned an
13 identity (in an "auth" block). Then this identity is authorized to
14 access certain newsgroups with certain rights (in an "access" block).
15 As for authentication, your "auth" block for password users could look
17 like this:
18 auth "foreignokay" {
20 auth: "ckpasswd -f <pathdb in inn.conf>/newsusers"
21 default: "<unauthenticated>"
22 }
23 See the documentation of the -f flag in the ckpasswd(8) man page for
25 how to generate passwords and make use of this newsusers file.
26 This way, with the "foreignokay" authentication block, a user
28 successfully authenticated as user "myusername" will be assigned the
29 identity "myusername". If authentication fails, it will be assigned
30 the default identity "<unauthenticated>" that will later be checked in
31 "access" blocks.
32 Authentication blocks are checked from the last one in the readers.conf
34 file to the first one (bottom up). As soon as one matches, the
35 corresponding identity is assigned to the user.
36 As for authorization, let's do something in an "access" block for
38 people successfully authenticated with passwords:
39 access "authenticatedpeople" {
41 users: "*"
42 newsgroups: "*,!junk,!control,!control.*"
43 }
44 And then something like one of the following two, depending on whether
46 unauthenticated users get any access:
47 access "restrictive" {
49 users: "<unauthenticated>"
50 newsgroups: "!*"
51 }
52 access "readonly" {
54 users: "<unauthenticated>"
55 read: "local.*"
56 post: "!*"
57 }
58 Please note that the "authenticatedpeople" block must appear in
60 readers.conf before "restrictive" or "readonly" blocks because access
61 blocks are checked from the last one in the readers.conf file to the
62 first one (bottom up). As soon as one matches the identity previously
63 assigned by an authentication block, it is chosen. The
64 "authenticatedpeople" access block matches every user that has not been
65 assigned "<unauthenticated>" as identity.
66 More examples and features are detailed below in this man page (notably
68 without any password file, with PAM, with Perl or Python hooks).
69 You don't need to reload anything after modifying readers.conf; every
71 time a news client connects to the server, a new nnrpd process is
72 spawned and reads its configuration from disk. Nonetheless, after any
73 changes, you can run "inncheck" to perform basic syntax checks against
74 the modified readers.conf file.
75
77 readers.conf in pathetc specifies access control for nnrpd(8). It
78 controls who is allowed to connect as a news reader and what they're
79 allowed to do after they connect. nnrpd reads this file every time a
80 news client connects to the server, even when running in daemon mode
81 with -D, which means that any changes on this file take effect
82 immediately on all subsequent connections. (The location of
83 readers.conf in pathetc is only the default; the same format applies to
84 any file specified with "nnrpd -c".)
85 There are two types of entries in readers.conf: parameter/value pairs
87 and configuration groups. Blank lines and anything after a number sign
88 ("#") are ignored, unless the character "#" is escaped with "\". The
89 maximum number of characters on each line is 8,191.
90 Parameter/value pairs consist of a keyword immediately followed by a
92 colon, at least one whitespace character, and a value. The case of the
93 parameter is significant (parameter should generally be in all
94 lowercase), and a parameter may contain any characters except colon,
95 "#", and whitespace. An example:
96 hosts: *.example.com
98 Values that contain whitespace should be quoted with double quotes, as
100 in:
101 hosts: "*.example.com, *.example.net"
103 If the parameter does not contain whitespace, such as:
105 hosts: *.example.com,*.example.net
107 it's not necessary to quote it, although you may wish to anyway for
109 clarity.
110 There is no way to continue a line on the next line, and therefore no
112 way to have a single parameter with a value longer than about 8,180
113 characters.
114 Many parameters take a boolean value. For all such parameters, the
116 value may be specified as "true", "yes", or "on" to turn it on and may
117 be any of "false", "no", or "off" to turn it off. The case of these
118 values is not significant.
119 There are two basic types of configuration groups: auth and access.
121 The auth group provides mechanisms to establish the identity of the
122 user, who they are. The access group determines, given the user's
123 identity, what that user is permitted to do. Writing a readers.conf
124 file for your setup is a two-step process: first assigning an identity
125 to each incoming connection using auth groups, and then giving each
126 identity appropriate privileges with access group. We recommend not
127 intermingling auth groups and access groups in the config file; it is
128 often more sensible (in the absence of the key parameter) to put all of
129 the auth groups first, and all of the access groups below.
130 A user identity, as established by an auth group, looks like an e-mail
132 address if a domain is specified (like "<username>@<domain>") or
133 otherwise just "<username>".
134 If nnrpdauthsender is set in inn.conf, the user identity is also put
136 into the Sender header field of posts made by that user. See the
137 documentation of that option in inn.conf(5) for more details.
138 An auth group definition looks like:
140 auth <name> {
142 hosts: <host-wildmat>
143 auth: <auth-program>
144 res: <res-program>
145 default: <defuser>
146 default-domain: <defdomain>
147 # ...possibly other settings
148 }
149 The <name> is used as a label for the group and is only for
151 documentation purposes. (If your syslog configuration records the
152 "news.debug" facility, the <name> will appear in the debugging output
153 of nnrpd. Examining that output can be very helpful in understanding
154 why your configuration doesn't do what you expect it to.)
155 A given auth group applies only to hosts whose name or IP address
157 matches the wildmat expression given with the hosts parameter (comma-
158 separated wildmat expressions are allowed, but "@" is not supported).
159 Rather than wildmat expressions, you may also use CIDR notation to
160 match any IP address in a netblock; for example, "10.10.10.0/24" will
161 match any IP address between 10.10.10.0 and 10.10.10.255 inclusive.
162 If compiled against the TLS/SSL or SASL libraries, an auth group with
164 the require_encryption parameter set to true only applies if the
165 incoming connection is using an encryption layer, either from the
166 beginning if the -S flag was passed to nnrpd, or after a successful use
167 of STARTTLS, or after a successful authentication using an SASL
168 mechanism which negotiates an encryption layer.
169 For any connection from a host that matches that wildmat expression or
171 netblock, each <res-program> (multiple res lines may be present in a
172 block; they are run in sequence until one succeeds), if any, is run to
173 determine the identity of the user just from the connection
174 information. If all the resolvers fail, or if the res parameter isn't
175 present, the user is assigned an identity of "<defuser>@<defdomain>";
176 in other words, the values of the default and default-domain parameters
177 are used. If <res-program> only returns a username, <defdomain> is
178 used as the domain.
179 If the user later authenticates via the AUTHINFO USER/PASS commands,
181 the provided username and password are passed to each <auth-program>
182 (multiple auth, perl_auth, or python_auth lines may be present in a
183 block; they are run in sequence until one succeeds), if any. If one
184 succeeds and returns a different identity than the one assigned at the
185 time of the connection, it is matched against the available access
186 groups again and the actions the user is authorized to do may change.
187 The most common <auth-program> to use is ckpasswd, which supports
188 several ways of checking passwords including using PAM. See the
189 ckpasswd(8) man page for more details.
190 When matching auth groups, the last auth group in the file that matches
192 a given connection and username/password combination is used.
193 An access group definition usually looks like:
195 access <name> {
197 users: <identity-wildmat>
198 newsgroups: <group-wildmat>
199 # ...possibly other settings
200 }
201 Again, <name> is just for documentation purposes. This says that all
203 users whose identity matches <identity-wildmat> can read and post to
204 all newsgroups matching <group-wildmat> (as before, comma-separated
205 wildmat expressions are allowed, but "@" is not supported).
206 Alternately, you can use the form:
207 access <name> {
209 users: <identity-wildmat>
210 read: <read-wildmat>
211 post: <post-wildmat>
212 }
213 and matching users will be able to read any group that matches
215 <read-wildmat> and post to any group that matches <post-wildmat>. You
216 can also set several other things in the access group as well as
217 override various inn.conf(5) parameters for just a particular group of
218 users.
219 Just like with auth groups, when matching access groups the last
221 matching one in the file is used to determine the user's permissions.
222 There is an exception to this rule: if the auth group which matched the
223 client contains a perl_access or python_access parameter, then the
224 script given as argument is used to dynamically generate an access
225 group. This new access group is then used to determine the access
226 rights of the client; the access groups in the file are ignored.
227 There is one additional special case to be aware of. When forming
229 particularly complex authentication and authorization rules, it is
230 sometimes useful for the identities provided by a given auth group to
231 only apply to particular access groups; in other words, rather than
232 checking the identity against the users parameter of every access
233 group, it's checked against the users parameter of only some specific
234 access groups. This is done with the key parameter. For example:
235 auth example {
237 key: special
238 hosts: *.example.com
239 default: <SPECIAL>
240 }
241 access example {
243 key: special
244 users: <SPECIAL>
245 newsgroups: *
246 addcanlockuser: none
247 }
248 In this case, the two key parameters bind this auth group with this
250 access group. For any incoming connection matching "*.example.com"
251 (assuming there isn't any later auth group that also matches such
252 hosts), no access group that doesn't have "key: special" will even be
253 considered. Similarly, the above access group will only be checked if
254 the user was authenticated with an auth group containing "key:
255 special". This mechanism normally isn't useful; there is almost always
256 a better way to achieve the same result.
257 Also note in the example that there's no default-domain parameter,
259 which means that no domain is appended to the default username and the
260 identity for such connections is just "<SPECIAL>". Note that some
261 additional add-ons to INN may prefer that authenticated identities
262 always return a full e-mail address (including a domain), so you may
263 want to set up your system that way if you are using add-ons. As
264 several different persons can be assigned the same "<SPECIAL>"
265 identity, no user-specific Cancel-Lock hashes should be generated.
266 Configuration files can be included in other configuration files via
268 the syntax:
269 include <filename>
271 The file named <filename> is then included. This syntax is allowed
273 only at top-level.
274 Below is the full list of allowable parameters for auth groups and
276 access groups, and after that are some examples that may make this
277 somewhat clearer.
278
280 An auth group without at least one of the res, auth, perl_auth,
281 python_auth, or default parameters makes no sense (and in practice will
282 just be ignored).
283 auth
285 A simple command line for a user authenticator (shell
286 metacharacters are not supported). If a full path is not given,
287 the program executed must be located in the pathbin/auth/passwd
288 directory. An authenticator is a program used to handle a user-
289 supplied username and password, via a mechanism such as AUTHINFO
290 USER/PASS. Like with res, one auth group can have multiple auth
291 parameters; they will be tried in order and the results of the
292 first successful one will be used. See also perl_auth.
293 The most common authenticator to use is ckpasswd(8); see its man
295 page for more information.
296 default
298 The default username for connections matching this auth group.
299 This is the username assigned to the user at connection time if all
300 resolvers fail or if there are no res parameters. Note that it can
301 be either a bare username, in which case default-domain (if
302 present) is appended after an "@", or a full identity string
303 containing an "@", in which case it will be used verbatim.
304 default-domain
306 The default domain string for this auth group. If a user resolver
307 or authenticator doesn't provide a domain, or if the default
308 username is used and it doesn't contain an "@", this domain is used
309 to form the user identity. (Note that for a lot of setups, it's
310 not really necessary for user identities to be qualified with a
311 domain name, in which case there's no need to use this parameter.)
312 hosts
314 A comma-separated list of remote hosts, wildmat patterns matching
315 either hostnames or IP addresses, or IP netblocks specified in CIDR
316 notation. If a user connects from a host that doesn't match this
317 parameter, this auth group will not match the connection and is
318 ignored.
319 Note that if you have a large number of patterns that can't be
321 merged into broader patterns (such as a large number of individual
322 systems scattered around the net that should have access), the
323 hosts parameter may exceed the maximum line length of 8,192
324 characters. In that case, you'll need to break that auth group
325 into multiple auth groups, each with a portion of the hosts listed
326 in its hosts parameter, and each assigning the same user identity.
327 All hosts match if this parameter is not given.
329 key If this parameter is present, any connection matching this auth
331 group will have its privileges determined only by the subset of
332 access groups containing a matching key parameter.
333 localaddress
335 A comma-separated list of local host or address patterns with the
336 same syntax as the hosts parameter. If this parameter is
337 specified, its auth group will only match connections made to a
338 matching local interface. (Obviously, this is only useful for
339 servers with multiple interfaces.)
340 All local addresses match if this parameter is not given.
342 perl_access
344 A path to a Perl script for dynamically generating an access group.
345 If an auth group matches successfully and contains a perl_access
346 parameter, then the argument Perl script will be used to create an
347 access group. This group will then determine the access rights of
348 the client, overriding any access groups in readers.conf. If and
349 only if a successful auth group contains the perl_access parameter,
350 readers.conf access groups are ignored and the client's rights are
351 instead determined dynamically. This parameter is only valid if
352 INN is compiled with Perl support (--with-perl passed to
353 "configure"). More information may be found in the file
354 doc/hook-perl.
355 perl_auth
357 A path to a Perl script for authentication. The perl_auth
358 parameter works exactly like auth, except that it calls the named
359 script using the Perl hook rather than an external program.
360 Multiple/mixed use of the auth, perl_auth, and python_auth
361 parameters is permitted within any auth group; each line is tried
362 in the order it appears. perl_auth has more power than auth in
363 that it provides the authentication program with additional
364 information about the client and the ability to return an error
365 string and a username. This parameter is only valid if INN is
366 compiled with Perl support (--with-perl passed to "configure").
367 More information may be found in doc/hook-perl.
368 python_access
370 A Python script for dynamically generating an access group. If an
371 auth group matches successfully and contains a python_access
372 parameter, then the argument script (without its ".py" extension)
373 will be used to create an access group. This group will then
374 determine the access rights of the client, overriding any access
375 groups in readers.conf. If and only if a successful auth group
376 contains the python_access parameter, readers.conf access groups
377 are ignored and the client's rights are instead determined
378 dynamically. This parameter is only valid if INN is compiled with
379 Python support (--with-python passed to "configure"). More
380 information may be found in the file doc/hook-python.
381 python_auth
383 A Python script for authentication. The python_auth parameter
384 works exactly like auth, except that it calls the named script
385 (without its ".py" extension) using the Python hook rather than an
386 external program. Multiple/mixed use of the auth, perl_auth, and
387 python_auth parameters is permitted within any auth group; each
388 line is tried in the order it appears. python_auth has more power
389 than auth in that it provides the authentication program with
390 additional information about the client and the ability to return
391 an error string and a username. This parameter is only valid if
392 INN is compiled with Python support (--with-python passed to
393 "configure"). More information may be found in doc/hook-python.
394 python_dynamic
396 A Python script for applying access control dynamically on a per
397 newsgroup basis. If an auth group matches successfully and
398 contains a python_dynamic parameter, then the argument script
399 (without its ".py" extension) will be used to determine the clients
400 rights each time the user attempts to view a newsgroup, or read or
401 post an article. Access rights as determined by python_dynamic
402 override the values of access group parameters such as newsgroups,
403 read and post. This parameter is only valid if INN is compiled
404 with Python support (--with-python passed to "configure"). More
405 information may be found in the file doc/hook-python.
406 require_encryption
408 If set to true, an incoming connection only matches this auth group
409 if it is encrypted, either from the beginning if the -S flag was
410 passed to nnrpd, or after a successful use of STARTTLS, or after a
411 successful authentication using an SASL mechanism which negotiates
412 an encrypted layer. This parameter is only valid if INN is
413 compiled with TLS/SSL or SASL support (by default if the OpenSSL
414 SSL and crypto libraries or the Cyrus SASL library are found at
415 configure time, otherwise see the --with-openssl and --with-sasl
416 flags passed to "configure").
417 res A simple command line for a user resolver (shell metacharacters are
419 not supported). If a full path is not given, the program executed
420 must be in the pathbin/auth/resolv directory. A resolver is an
421 authentication program which attempts to figure out the identity of
422 the connecting user using nothing but the connection information
423 (in other words, the user has not provided a username and
424 password). An example of a resolver would be a program that
425 assigns an identity from an ident callback or from the user's
426 hostname.
427 One auth group can have multiple res parameters, and they will be
429 tried in the order they're listed. The results of the first
430 successful one will be used.
431 Alternatively, a res block can be used instead of a res parameter.
433 The recognized parameters in such res blocks are:
434 log
436 A string to log in pathlog/news.notice (with "res also-log:"
437 prepended) before the resolver is tried. One res group can have
438 multiple log parameters, and they will be logged in the order
439 they're listed.
440 program
442 This parameter is mandatory in a res block. Its meaning is the
443 same as the res parameter used directly in an auth block.
444 auth <auth-name> {
446 res: <res-program>
447 }
448 is therefore equivalent to:
450 auth <auth-name> {
452 res <res-name> {
453 program: <res-program>
454 }
455 }
456
458 access
459 A set of letters specifying the permissions granted to the client.
460 The letters are chosen from the following set:
461 A The client may post articles with Approved header fields (in
463 other words, may approve articles for moderated newsgroups).
464 By default, this is not allowed.
465 I The client may inject articles with IHAVE. Note that in order
467 to inject articles with the IHAVE command, the user must also
468 have POST permission (the "P" option). Articles injected with
469 IHAVE are treated as though they were injected with POST, that
470 is to say such articles must not have been previously injected
471 (they must not contain header fields like Injection-Info).
472 L The client may post to newsgroups that are set to disallow
474 local posting (status fields "j", "n" and "x" in the active(5)
475 file).
476 N The client may use the NEWNEWS command, overriding the global
478 setting.
479 P The client may post articles.
481 R The client may read articles.
483 Note that if this parameter is given, allownewnews in inn.conf is
485 ignored for connections matching this access group and the ability
486 of the client to use NEWNEWS is entirely determined by the presence
487 of "N" in the access string. If you want to support NEWNEWS, make
488 sure to include "N" in the access string when you use this
489 parameter.
490 Note that if this parameter is given and "R" isn't present in the
492 access string, the client cannot read regardless of newsgroups or
493 read parameters. Similarly, if this parameter is given and "P"
494 isn't present, the client cannot post. This use of access is
495 deprecated and confusing; it's strongly recommended that if the
496 access parameter is used, "R" and "P" always be included in the
497 access string and newsgroups, read, and post be used to control
498 access. (To grant read access but no posting access, one can have
499 just a read parameter and no post parameter.)
500 addcanlockuser
502 If set to "none", posts made by these users will not have a user-
503 specific hash in the Cancel-Lock header field (only the admin hash
504 will be generated). No Cancel-Key header field will be present in
505 cancel or supersede requests. This is a string value and the
506 default is "username", that is to say a user-specific hash based on
507 the identity assigned to the connection is used.
508 Another possible value to this parameter is "ip", in which case a
510 user-specific hash based on the IP of the connection is used (which
511 should be a static IP so as to actually identify users).
512 See inn-secrets.conf(5) for more information about Cancel-Lock.
514 The main reason for this parameter is to deactivate this
515 authentication mechanism when the same identity or IP can be
516 assigned by an access group to different people. Otherwise, any of
517 these people would be able to send an authenticated withdrawal of
518 an article originally sent by another person with the same identity
519 or IP.
520 domain
522 When set, the value of this parameter is used for the domain part
523 (the right-hand side after "@") of autogenerated Message-IDs, as
524 well as for the server name indicated in Injection-Info header
525 fields.
526 By default, the value of this parameter is inherited from the
528 eponym parameter in inn.conf. However, if domain is not explicitly
529 set in readers.conf, the specific behaviour described above won't
530 be triggered unless virtualhost is set to true.
531 You may also want to set the fromhost parameter (inherited from
533 inn.conf) for the complaints address in the Injection-Info header
534 field, if its default value should be changed, and the complaints
535 parameter is not already set or newsmaster does not already contain
536 an "@".
537 groupexactcount
539 This parameter controls the threshold below with nnrpd should give
540 the exact number of still existing articles present in newsgroups
541 instead of an estimate. The exact number is usually updated once a
542 day during the expiry process by expirover (run by news.daily), and
543 is updated when new articles arrive but not necessarily when
544 articles are cancelled or overwritten in self-expiring storage
545 methods like CNFS.
546 When the estimated count of articles is strictly smaller than
548 groupexactcount, nnrpd will recount the number of still existing
549 articles, and report the exact value. If groupexactcount is set to
550 0, nnrpd will always recount. If set to 1, it will never recount.
551 Though exact article counts are not required, they may be useful to
553 distinguish empty newsgroups by reporting an exact count of 0
554 instead of an estimate of 1 (when it happens, the news client may
555 show that 1 article is present in the newsgroup, then it tries to
556 retrieve the article, and finally does not show anything to the
557 user).
558 It is not recommended to set a high value to this parameter because
560 it will slow the responses to news clients (recounting existing
561 articles takes time, especially on newsgroups with a lot of
562 articles).
563 This is an integer value, and the default is 5.
565 key If this parameter is present, this access group is only considered
567 when finding privileges for users matching auth groups with this
568 same key parameter.
569 localtime
571 If a Date or an Injection-Date header field is not included in a
572 posted article, nnrpd normally adds these header fields in UTC. If
573 this is set to true, the Date header field will be formatted in
574 local time instead. (The Injection-Date header field is added
575 according to the behaviour of the addinjectiondate parameter in
576 inn.conf, and will remain in UTC, though.) This is a boolean value
577 and the default is false.
578 This parameter permits handling a relatively unusual corner case.
580 It is mostly a tool for people who want to disclose their local
581 time zone (it can be useful information in certain types of
582 discussions), but whose clients don't for some reason, and who can
583 arrange for the server to be in the same time zone as the client.
584 max_rate
586 If this parameter is present (and non-zero), it is used for nnrpd's
587 rate-limiting code. The client will only be able to download at
588 this speed (in bytes/second). Note that if an encryption layer is
589 being used, limiting is applied to the pre-encryption datastream.
590 newsgroups
592 Users that match this access group are allowed to read and post to
593 all newsgroups matching this comma-separated list of wildmat
594 patterns. The empty string is equivalent to "newsgroups: *"; if
595 this parameter is missing, the connection will be rejected (unless
596 read and/or post are used instead).
597 newsmaster
599 Used as the contact address in the help message returned by
600 nnrpd(8), if the virtualhost: parameter is set to true.
601 perlfilter
603 If set to false, posts made by these users do not pass through the
604 Perl filter even if it is otherwise enabled. This is a boolean
605 value and the default is true.
606 post
608 Like the newsgroups parameter, but the client is only given
609 permission to post to the matching newsgroups. This parameter is
610 often used with read to define the patterns for reading and posting
611 separately (usually to give the user permission to read more
612 newsgroups than they're permitted to post to). It cannot be used
613 in the same access group with a newsgroups parameter.
614 pythonfilter
616 If set to false, posts made by these users do not pass through the
617 Python filter even if it is otherwise enabled. This is a boolean
618 value and the default is true.
619 This parameter currently has no effect as Python filtering is not
621 implemented yet in nnrpd. If you want to do Python filtering, you
622 have to use the one implemented in innd.
623 read
625 Like the newsgroups parameter, but the client is only given
626 permission to read the matching newsgroups. This parameter is
627 often used with post to specify some read-only groups; it cannot be
628 used in the same access group with a newsgroups parameter. (If
629 read is used and post is missing, the client will have only read-
630 only access.)
631 reject_with
633 If this parameter is present, a client matching this block will be
634 disconnected with a "Permission denied" message containing the
635 contents (a "reason" string) of this parameter. Some newsreaders
636 will then display the reason to the user.
637 strippath
639 If set to true, any Path header field provided by a user in a post
640 is stripped rather than used as the beginning of the Path header
641 field body of the article. This is a boolean value and the default
642 is false.
643 users
645 The privileges given by this access group apply to any user
646 identity which matches this comma-separated list of wildmat
647 patterns. If this parameter isn't given, the access group applies
648 to all users (and is essentially equivalent to "users: *").
649 virtualhost
651 Set this parameter to true in order to make nnrpd behave as if it
652 is running on a server with a different name than it actually has.
653 The domain parameter must then be set, either in inn.conf or in the
654 same access group. All articles and overview data displayed to
655 clients will have their Xref header field bodies altered to appear
656 to be from the server named in domain, and posted articles will use
657 that server name in the Message-ID and Injection-Info header field
658 bodies. (Moreover, if the -I flag was given to nnrpd, posting
659 agents will be proposed to use Message-IDs containing the string
660 specified with -I.)
661 Similarly, the Path header field bodies displayed to clients or
663 generated in posted articles will use the value of domain (if
664 pathhost is not set in the access group, or has the same value as
665 in inn.conf) or pathhost (if pathhost is set in the access group to
666 something different than is set in inn.conf).
667 Also, the domain part (the right-hand side after "@") of the
669 newsmaster e-mail mentioned in the help message returned by nnrpd
670 will use the value of domain if the newsmaster parameter does not
671 already have a domain part.
672 At least one of the domain or pathhost parameters must be set in
674 the access group to something different than in inn.conf, otherwise
675 nnrpd will fail to start.
676 Note that setting this parameter requires the server modify all
678 posts before presenting them to the client and therefore may
679 decrease performance slightly.
680 In addition, all of the following parameters are valid in access groups
682 and override the global setting in inn.conf. See inn.conf(5) for the
683 descriptions of these parameters:
684 addinjectiondate, addinjectionpostingaccount,
686 addinjectionpostinghost, backoff_auth, backoff_db, backoff_k,
687 backoff_postfast, backoff_postslow, backoff_trigger,
688 checkincludedtext, clienttimeout, complaints, fromhost,
689 localmaxartsize, moderatormailer, nnrpdauthsender, nnrpdcheckart,
690 nnrpdoverstats, nnrpdposthost, nnrpdpostport, organization,
691 pathhost, readertrack, spoolfirst, strippostcc.
692
694 Here's a basic summary of what happens when a client connects:
695 • All auth groups are scanned and the ones that don't match the
697 client (due to hosts, localaddress, require_encryption, etc.) are
698 eliminated.
699 • The remaining auth groups are scanned from the last to the first,
701 and an attempt is made to apply it to the current connection. This
702 means running res programs, if any, and otherwise applying default.
703 The first auth group (starting from the bottom) to return a valid
704 user is kept as the active auth group.
705 • If no auth groups yield a valid user (none have default parameters
707 or successful res programs) but some of the auth groups have auth
708 lines (indicating a possibility that the user can authenticate and
709 then obtain permissions), the connection is considered to have no
710 valid auth group (which means that the access groups are ignored
711 completely) but the connection isn't closed. Instead, a 480
712 response code (meaning that authentication is required) is returned
713 for everything until the user authenticates.
714 • When the user authenticates, the auth groups are rescanned, and
716 only the matching ones which contain at least one auth, perl_auth,
717 or python_auth line are considered. These auth groups are scanned
718 from the last to the first, running auth programs and perl_auth or
719 python_auth scripts. The first auth group (starting from the
720 bottom) to return a valid user is kept as the active auth group.
721 • Regardless of how an auth group is established, as soon as one is,
723 that auth group is used to assign a user identity by taking the
724 result of the successful res, auth, perl_auth, or python_auth line
725 (or the default if necessary), and appending default-domain if
726 necessary. (If the perl_access or python_access parameter is
727 present.)
728 • Finally, an access group is selected by scanning the access groups
730 from bottom up and finding the first match. (If the established
731 auth group contained a perl_access or python_access line, the
732 dynamically generated access group returned by the script is used
733 instead.) User permissions are granted based on the established
734 access group.
735
737 Probably the simplest useful example of a complete readers.conf, this
738 gives permissions to read and post to all groups to any connections
739 from the "example.com" domain, except for Bob's machine, and no
740 privileges for anyone connecting elsewhere:
741 auth example.com {
743 hosts: "*.example.com, example.com, !bob.example.com"
744 default: "<EXAMPLE>"
745 }
746 access full {
748 users: "<EXAMPLE>"
749 newsgroups: *
750 addcanlockuser: none
751 }
752 Note that the above access realm could also be written without the
754 users key, in which case it applies to any user identity (though in
755 this example, the user identity that will be assigned to all matching
756 connections is "<EXAMPLE>"). It is however recommended to keep an
757 explicit users key so as to better view to whom the access block
758 applies.
759 As the only available auth realm only matches hosts in the
761 "example.com" domain, any connections from other hosts will be rejected
762 immediately.
763 If you have some systems that should only have read-only access to the
765 server, you can modify the example above slightly by adding an
766 additional auth and access group:
767 auth lab {
769 hosts: "*.lab.example.com"
770 default: <LAB>
771 }
772 access lab {
774 users: <LAB>
775 read: *
776 }
777 If those are put in the file after the above example, they'll take
779 precedence (because they're later in the file) for any user coming from
780 a machine in the lab.example.com domain, everyone will only have read
781 access, not posting access.
782 Here's a similar example for a news server that accepts connections
784 from anywhere but requires the user to specify a username and password.
785 The username and password are first checked against an external
786 database of usernames and passwords, and then make use of PAM:
787 auth all {
789 auth: "ckpasswd -f <pathdb in inn.conf>/newsusers"
790 auth: ckpasswd
791 }
792 access full {
794 users: *
795 newsgroups: *
796 }
797 When the user first connects, there are no res keys and no default, so
799 they don't receive any valid identity and the connection won't match
800 any access groups (even ones with "users: *"). Such users receive
801 nothing but authentication-required responses from nnrpd until they
802 authenticate.
803 If they then later authenticate, the username and password are checked
805 first by running ckpasswd with the -f option for an external file of
806 encrypted passwords, and then uses PAM (if INN was built with PAM
807 support) to check the password (and if that fails, it tries to check
808 the password against the password field returned by getpwnam(3)). If
809 both of those fail, the user will continue to have no identity;
810 otherwise, an identity will be assigned (usually the supplied username,
811 perhaps with a domain appended, although an authenticator technically
812 can provide a completely different username for the identity), and the
813 access group will match, giving full access.
814 It may be educational to consider how to combine the above examples;
816 general groups always go first. The order of the auth groups actually
817 doesn't matter, since the "hosts: example.com" one only matches
818 connections before username/password is sent, and the "auth: ckpasswd"
819 one only matches after; order would matter if either group applied to
820 both cases. The order of the access groups in this case does matter,
821 provided the newsgroups lines differ; the access group with no users
822 line needs to be first, with the "users: <LOCAL>" group after.
823 Here's an example of another common case: a server that only allows
825 connections from a local domain and has an additional hierarchy that's
826 password-restricted.
827 auth "example.com" {
829 hosts: "*.example.com"
830 auth: "ckpasswd -f <pathdb in inn.conf>/newsusers"
831 default: "anonymous"
832 }
833 access regular {
835 newsgroups: "*,!example.restricted.*"
836 addcanlockuser: none
837 }
838 access full {
840 users: "*,!anonymous"
841 newsgroups: *
842 }
843 In this example, unauthenticated users get the identity "anonymous",
845 which matches only the first access group and hence doesn't get access
846 to the "example.restricted.*" hierarchy. No user-specific Cancel-Lock
847 elements should be generated for anonymous users. Anyone who
848 authenticates using a password in the newsusers file gets full access
849 to all groups. However, note that the only authentication block is
850 limited to hostnames in the example.com domain; connections outside of
851 that domain will never be allowed access nor have an opportunity to
852 authenticate.
853 Here's a very complicated example. This is for an organization that
855 has an internal hierarchy "example.*" only available to local shell
856 users, who are on machines where identd(8) can be trusted. Dialup
857 users must provide a username and password, which is then checked
858 against RADIUS. Remote users have to use a username and password
859 that's checked against a database on the news server. Finally, the
860 admin staff (users "joe" and "jane") can post anywhere (including the
861 "example.admin.*" groups that are read-only for everyone else), and are
862 exempted from the Perl filter. For an additional twist, posts from
863 dialup users have their Sender header field replaced by their
864 authenticated identity.
865 Since this organization has some internal moderated newsgroups, the
867 admin staff can also post messages with Approved header fields, but
868 other users cannot.
869 auth default {
871 auth: "ckpasswd -f <pathdb in inn.conf>/newsusers"
872 default: <FAIL>
873 default-domain: example.com
874 }
875 auth shell {
877 hosts: *.shell.example.com
878 res: ident
879 auth: ckpasswd
880 default: <FAIL>
881 default-domain: shell.example.com
882 }
883 auth dialup {
885 hosts: *.dialup.example.com
886 auth: radius
887 default: <FAIL>
888 default-domain: dialup.example.com
889 }
890 access shell {
892 users: *@shell.example.com
893 read: *
894 post: "*, !example.admin.*"
895 }
896 access dialup {
898 users: *@dialup.example.com
899 newsgroups: *,!example.*
900 nnrpdauthsender: true
901 }
902 access other {
904 users: "*@example.com, !<FAIL>@example.com"
905 newsgroups: *,!example.*
906 }
907 access fail {
909 users: "<FAIL>@*"
910 newsgroups: !*
911 }
912 access admin {
914 users: "joe@*,jane@*"
915 newsgroups: *
916 access: "RPA"
917 perlfilter: false
918 }
919 Note the use of different domains to separate dialup from shell users
921 easily. Another way to do that would be with key parameters, but this
922 way provides slightly more intuitive identity strings. Note also that
923 the fail access group catches not only failing connections from
924 external users but also failed authentication of shell and dialup users
925 before they've authenticated. The identity string given for, say,
926 dialup users before RADIUS authentication has been attempted matches
927 both the dialup access group and the fail access group, since it's
928 "<FAIL>@dialup.example.com", but the fail group is last, so it takes
929 precedence.
930 The shell auth group has an auth parameter so that users "joe" and
932 "jane" can, if they choose, use username and password authentication to
933 gain their special privileges even if they're logged on as a different
934 user on the shell machines (or if ident isn't working). When they
935 first connect, they'd have the default access for that user, but they
936 could then authenticate in order to get their extended access.
937 Also note that if the users "joe" and "jane" are using their own
939 accounts, they get their special privileges regardless of how they
940 connect, whether the dialups, the shell machines, or even externally
941 with a username and password.
942 Finally, here's a very simple example of a configuration for a public
944 server for a particular hierarchy.
945 auth default {
947 hosts: *
948 default: <PUBLIC>
949 }
950 access default {
952 users: <PUBLIC>
953 newsgroups: example.*
954 addcanlockuser: none
955 }
956 Notice that clients aren't allowed to read any other groups; this keeps
958 them from getting access to administrative groups or reading control
959 messages, just as a precaution. When running a public server like
960 this, be aware that many public hierarchies will later be pulled down
961 and reinjected into the main Usenet, so it's highly recommended that
962 you also run a Perl or Python filter to reject any messages crossposted
963 out of your local hierarchy, and any messages containing a Supersedes
964 header field. This will keep messages posted to your public hierarchy
965 from hurting any of the rest of Usenet if they leak out.
966
968 In general, separate passwords should be used for NNTP wherever
969 possible; the NNTP protocol itself does not protect passwords from
970 casual interception, and many implementations (including this one) do
971 not "lock out" accounts or otherwise discourage password-guessing
972 attacks. So it is best to ensure that a compromised password has
973 minimal effects.
974 Authentication using the AUTHINFO USER/PASS commands passes unencrypted
976 over the network. Extreme caution should therefore be used especially
977 with system passwords (e.g. "auth: ckpasswd -s"). Passwords can be
978 protected by using NNTP over TLS/SSL or through ssh tunnels, and this
979 usage can be enforced by a well-considered server configuration that
980 only permits certain auth groups to be applied in certain cases. One
981 can also authenticate using a strong SASL mechanism. Here are some
982 ideas:
983 • To restrict connections on the standard NNTP port (119) to use an
985 encryption layer for some (or all) of the auth groups to match, use
986 the require_encryption parameter. Note that a client can use
987 STARTTLS to negotiate an encrypted TLS connection. A secure layer
988 can also be negotiated during authentication via AUTHINFO SASL.
989 • If you consider your local network (but not the internet) secure,
991 have some auth groups with a restrictive hosts parameter; they
992 would go above, with ones having global applicability below.
993 • Consider running nnrpd with the -S flag (either also with -D, or
995 out of "super-server" like inetd) on the NNTPS port (563) for
996 clients that support TLS/SSL. See nnrpd(8) for more details about
997 how to configure that. You can use the require_encryption
998 parameter or the -c flag to specify an alternate readers.conf file
999 if you want a substantially different configuration for this case.
1000 • If you want to restrict an auth group to only match loopback
1002 connections (for users running newsreaders on localhost or
1003 connecting via an ssh tunnel), use the localaddress parameter.
1004
1006 Written by Aidan Cully <aidan@panix.com> for InterNetNews.
1007 Substantially expanded by Russ Allbery <eagle@eyrie.org>.
1008
1010 auth_krb5(8), ckpasswd(8), inn.conf(5), innd(8), inn-secrets.conf(5),
1011 libinn_uwildmat(3), newsfeeds(5), nnrpd(8).
1012INN 2.7.1 2023-03-07 READERS.CONF(5)