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 when it starts
80 up. This generally means that any changes take effect immediately on
81 all subsequent connections, but nnrpd may have to be restarted if you
82 use the -D option. (The location pathetc/readers.conf is only the
83 default; the same format applies to any file specified with "nnrpd
84 -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; in other words, it's in the form "<username>@<domain>" (or
133 sometimes just "<username>" if no domain is specified.
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 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 a 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:
177 parameters are used. If <res-program> only returns a username,
178 <defdomain> is 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. As several different persons can
264 be assigned the same "<SPECIAL>" identity, no user-specific Cancel-Lock
265 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
282 will just be ignored).
283 hosts:
285 A comma-separated list of remote hosts, wildmat patterns matching
286 either hostnames or IP addresses, or IP netblocks specified in CIDR
287 notation. If a user connects from a host that doesn't match this
288 parameter, this auth group will not match the connection and is
289 ignored.
290 Note that if you have a large number of patterns that can't be
292 merged into broader patterns (such as a large number of individual
293 systems scattered around the net that should have access), the
294 hosts: parameter may exceed the maximum line length of 8,192
295 characters. In that case, you'll need to break that auth group
296 into multiple auth groups, each with a portion of the hosts listed
297 in its hosts: parameter, and each assigning the same user identity.
298 All hosts match if this parameter is not given.
300 localaddress:
302 A comma-separated list of local host or address patterns with the
303 same syntax as the same as with the hosts: parameter. If this
304 parameter is specified, its auth group will only match connections
305 made to a matching local interface. (Obviously, this is only
306 useful for servers with multiple interfaces.)
307 All local addresses match if this parameter is not given.
309 res:
311 A simple command line for a user resolver (shell metacharacters are
312 not supported). If a full path is not given, the program executed
313 must be in the pathbin/auth/resolv directory. A resolver is an
314 authentication program which attempts to figure out the identity of
315 the connecting user using nothing but the connection information
316 (in other words, the user has not provided a username and
317 password). An examples of a resolver would be a program that
318 assigns an identity from an ident callback or from the user's
319 hostname.
320 One auth group can have multiple res: parameters, and they will be
322 tried in the order they're listed. The results of the first
323 successful one will be used.
324 Alternatively, a res block can be used instead of a res: parameter.
326 The recognized parameters in such res blocks are:
327 log:
329 A string to log in pathlog/news.notice (with "res also-log:"
330 prepended) before the resolver is tried. One res group can have
331 multiple log: parameters, and they will be logged in the order
332 they're listed.
333 program:
335 This parameter is mandatory in a res block. Its meaning is the
336 same as the res: parameter used directly in an auth block.
337 auth <auth-name> {
339 res: <res-program>
340 }
341 is therefore equivalent to:
343 auth <auth-name> {
345 res <res-name> {
346 program: <res-program>
347 }
348 }
349 auth:
351 A simple command line for a user authenticator (shell
352 metacharacters are not supported). If a full path is not given,
353 the program executed must be located in the pathbin/auth/passwd
354 directory. An authenticator is a program used to handle a user-
355 supplied username and password, via a mechanism such as AUTHINFO
356 USER/PASS. Like with res:, one auth group can have multiple auth:
357 parameters; they will be tried in order and the results of the
358 first successful one will be used. See also perl_auth: below.
359 The most common authenticator to use is ckpasswd(8); see its man
361 page for more information.
362 perl_auth:
364 A path to a perl script for authentication. The perl_auth:
365 parameter works exactly like auth:, except that it calls the named
366 script using the perl hook rather than an external program.
367 Multiple/mixed use of the auth, perl_auth, and python_auth
368 parameters is permitted within any auth group; each line is tried
369 in the order it appears. perl_auth: has more power than auth: in
370 that it provides the authentication program with additional
371 information about the client and the ability to return an error
372 string and a username. This parameter is only valid if INN is
373 compiled with Perl support (--with-perl passed to configure). More
374 information may be found in doc/hook-perl.
375 python_auth:
377 A Python script for authentication. The python_auth parameter
378 works exactly like auth, except that it calls the named script
379 (without its ".py" extension) using the Python hook rather than an
380 external program. Multiple/mixed use of the auth, perl_auth, and
381 python_auth parameters is permitted within any auth group; each
382 line is tried in the order it appears. python_auth has more power
383 than auth in that it provides the authentication program with
384 additional information about the client and the ability to return
385 an error string and a username. This parameter is only valid if
386 INN is compiled with Python support (--with-python passed to
387 configure). More information may be found in doc/hook-python.
388 default:
390 The default username for connections matching this auth group.
391 This is the username assigned to the user at connection time if all
392 resolvers fail or if there are no res: parameters. Note that it
393 can be either a bare username, in which case default-domain: (if
394 present) is appended after an "@", or a full identity string
395 containing an "@", in which case it will be used verbatim.
396 default-domain:
398 The default domain string for this auth group. If a user resolver
399 or authenticator doesn't provide a domain, or if the default
400 username is used and it doesn't contain a "@", this domain is used
401 to form the user identity. (Note that for a lot of setups, it's
402 not really necessary for user identities to be qualified with a
403 domain name, in which case there's no need to use this parameter.)
404 key:
406 If this parameter is present, any connection matching this auth
407 group will have its privileges determined only by the subset of
408 access groups containing a matching key parameter.
409 require_encryption:
411 If set to true, an incoming connection only matches this auth group
412 if it is encrypted, either from the beginning if the -S flag was
413 passed to nnrpd, or after a successful use of STARTTLS, or after a
414 successful authentication using a SASL mechanism which negotiates
415 an encrypted layer. This parameter is only valid if INN is
416 compiled with TLS/SSL or SASL support (by default if the OpenSSL
417 SSL and crypto libraries or the Cyrus SASL library are found at
418 configure time, otherwise see the --with-openssl and --with-sasl
419 flags passed to configure).
420 perl_access:
422 A path to a perl script for dynamically generating an access group.
423 If an auth group matches successfully and contains a perl_access
424 parameter, then the argument perl script will be used to create an
425 access group. This group will then determine the access rights of
426 the client, overriding any access groups in readers.conf. If and
427 only if a sucessful auth group contains the perl_access parameter,
428 readers.conf access groups are ignored and the client's rights are
429 instead determined dynamically. This parameter is only valid if
430 INN is compiled with Perl support (--with-perl passed to
431 configure). More information may be found in the file
432 doc/hook-perl.
433 python_access:
435 A Python script for dynamically generating an access group. If an
436 auth group matches successfully and contains a python_access
437 parameter, then the argument script (without its ".py" extension)
438 will be used to create an access group. This group will then
439 determine the access rights of the client, overriding any access
440 groups in readers.conf. If and only if a successful auth group
441 contains the python_access parameter, readers.conf access groups
442 are ignored and the client's rights are instead determined
443 dynamically. This parameter is only valid if INN is compiled with
444 Python support (--with-python passed to configure). More
445 information may be found in the file doc/hook-python.
446 python_dynamic:
448 A Python script for applying access control dynamically on a per
449 newsgroup basis. If an auth group matches successfully and
450 contains a python_dynamic parameter, then the argument script
451 (without its ".py" extension) will be used to determine the clients
452 rights each time the user attempts to view a newsgroup, or read or
453 post an article. Access rights as determined by python_dynamic
454 override the values of access group parameters such as newsgroups,
455 read and post. This parameter is only valid if INN is compiled
456 with Python support (--with-python passed to configure). More
457 information may be found in the file doc/hook-python.
458
460 users:
461 The privileges given by this access group apply to any user
462 identity which matches this comma-separated list of wildmat
463 patterns. If this parameter isn't given, the access group applies
464 to all users (and is essentially equivalent to "users: *").
465 newsgroups:
467 Users that match this access group are allowed to read and post to
468 all newsgroups matching this comma-separated list of wildmat
469 patterns. The empty string is equivalent to "newsgroups: *"; if
470 this parameter is missing, the connection will be rejected (unless
471 read: and/or post: are used instead, see below).
472 read:
474 Like the newsgroups: parameter, but the client is only given
475 permission to read the matching newsgroups. This parameter is
476 often used with post: (below) to specify some read-only groups; it
477 cannot be used in the same access group with a newsgroups:
478 parameter. (If read: is used and post: is missing, the client will
479 have only read-only access.)
480 post:
482 Like the newsgroups: parameter, but the client is only given
483 permission to post to the matching newsgroups. This parameter is
484 often used with read: (above) to define the patterns for reading
485 and posting separately (usually to give the user permission to read
486 more newsgroups than they're permitted to post to). It cannot be
487 used in the same access group with a newsgroups: parameter.
488 access:
490 A set of letters specifying the permissions granted to the client.
491 The letters are chosen from the following set:
492 R The client may read articles.
494 P The client may post articles.
496 I The client may inject articles with IHAVE. Note that in order
498 to inject articles with the IHAVE command, the user must also
499 have POST permission (the "P" option). Articles injected with
500 IHAVE are treated as though they were injected with POST, that
501 is to say such articles must not have been previously injected
502 (they must not contain header fields like Injection-Info).
503 A The client may post articles with Approved header fields (in
505 other words, may approve articles for moderated newsgroups). By
506 default, this is not allowed.
507 N The client may use the NEWNEWS command, overriding the global
509 setting.
510 L The client may post to newsgroups that are set to disallow local
512 posting (status fields "j", "n" and "x" in the active(5) file).
513 Note that if this parameter is given, allownewnews in inn.conf is
515 ignored for connections matching this access group and the ability
516 of the client to use NEWNEWS is entirely determined by the presence
517 of "N" in the access string. If you want to support NEWNEWS, make
518 sure to include "N" in the access string when you use this
519 parameter.
520 Note that if this parameter is given and "R" isn't present in the
522 access string, the client cannot read regardless of newsgroups: or
523 read: parameters. Similarly, if this parameter is given and "P"
524 isn't present, the client cannot post. This use of access: is
525 deprecated and confusing; it's strongly recommended that if the
526 access: parameter is used, "R" and "P" always be included in the
527 access string and newsgroups:, read:, and post: be used to control
528 access. (To grant read access but no posting access, one can have
529 just a read: parameter and no post: parameter.)
530 key:
532 If this parameter is present, this access group is only considered
533 when finding privileges for users matching auth groups with this
534 same key: parameter.
535 addcanlockuser:
537 If set to "none", posts made by these users will not have a user-
538 specific hash in the Cancel-Lock header field (only the admin hash
539 will be generated). No Cancel-Key header field will be present in
540 cancel or supersede requests. This is a string value and the
541 default is "username", that is to say a user-specific hash based on
542 the identity assigned to the connection is used.
543 Another possible value to this parameter is "ip", in which case a
545 user-specific hash based on the IP of the connection is used (which
546 should be a static IP so as to actually identify users).
547 See inn-secrets.conf(5) for more information about Cancel-Lock.
549 The main reason for this parameter is to deactivate this
550 authentication mechanism when the same identity or IP can be
551 assigned by an access group to different people. Otherwise, any of
552 these people would be able to send an authenticated withdrawal of
553 an article originally sent by another person with the same identity
554 or IP.
555 reject_with:
557 If this parameter is present, a client matching this block will be
558 disconnected with a "Permission denied" message containing the
559 contents (a "reason" string) of this parameter. Some newsreaders
560 will then display the reason to the user.
561 max_rate:
563 If this parameter is present (and nonzero), it is used for nnrpd's
564 rate-limiting code. The client will only be able to download at
565 this speed (in bytes/second). Note that if an encryption layer is
566 being used, limiting is applied to the pre-encryption datastream.
567 localtime:
569 If a Date or an Injection-Date header field is not included in a
570 posted article, nnrpd(8) normally adds these header fields in UTC.
571 If this is set to true, the Date header field will be formatted in
572 local time instead. (The Injection-Date header field is added
573 according to the behaviour of the addinjectiondate parameter in
574 inn.conf, and will remain in UTC, though.) This is a boolean value
575 and the default is false.
576 This parameter permits handling a relatively unusual corner case.
578 It is mostly a tool for people who want to disclose their local
579 time zone (it can be useful information in certain types of
580 discussions), but whose clients don't for some reason, and who can
581 arrange for the server to be in the same time zone as the client.
582 newsmaster:
584 Used as the contact address in the help message returned by
585 nnrpd(8), if the virtualhost: parameter is set to true.
586 strippath:
588 If set to true, any Path header field provided by a user in a post
589 is stripped rather than used as the beginning of the Path header
590 field body of the article. This is a boolean value and the default
591 is false.
592 perlfilter:
594 If set to false, posts made by these users do not pass through the
595 Perl filter even if it is otherwise enabled. This is a boolean
596 value and the default is true.
597 pythonfilter:
599 If set to false, posts made by these users do not pass through the
600 Python filter even if it is otherwise enabled. This is a boolean
601 value and the default is true.
602 virtualhost:
604 Set this parameter to true in order to make nnrpd behave as if it
605 is running on a server with a different name than it actually is.
606 The domain parameter must then be set, either in inn.conf or in the
607 same access group. All articles and overview data displayed to
608 clients will have their Xref header field bodies altered to appear
609 to be from the server named in domain, and posted articles will use
610 that server name in the Message-ID and Injection-Info header field
611 bodies. (Moreover, if the -I flag was given to nnrpd, posting
612 agents will be proposed to use Message-IDs containing the string
613 specified with -I.)
614 Similarly, the Path header field bodies displayed to clients or
616 generated in posted articles will use the value of domain (if
617 pathhost is not set in the access group, or has the same value as
618 in inn.conf) or pathhost (if pathhost is set in the access group to
619 something different than is set in inn.conf).
620 At least one of the domain or pathhost parameters must be set in
622 the access group to something different than in inn.conf, otherwise
623 nnrpd will fail to start.
624 Note that setting this parameter requires the server modify all
626 posts before presenting them to the client and therefore may
627 decrease performance slightly.
628 In addition, all of the following parameters are valid in access groups
630 and override the global setting in inn.conf. See inn.conf(5) for the
631 descriptions of these parameters:
632 addinjectiondate, addinjectionpostingaccount, addinjectionpostinghost,
634 backoff_auth, backoff_db, backoff_k, backoff_postfast, backoff_postslow,
635 backoff_trigger, checkincludedtext, clienttimeout, complaints, domain,
636 fromhost, localmaxartsize, moderatormailer, nnrpdauthsender, nnrpdcheckart,
637 nnrpdoverstats, nnrpdposthost, nnrpdpostport, organization, pathhost,
638 readertrack, spoolfirst, strippostcc.
639
641 Here's a basic summary of what happens when a client connects:
642 • All auth groups are scanned and the ones that don't match the client
644 (due to hosts, localaddress, require_encryption, etc.) are
645 eliminated.
646 • The remaining auth groups are scanned from the last to the first, and
648 an attempt is made to apply it to the current connection. This means
649 running res: programs, if any, and otherwise applying default:. The
650 first auth group (starting from the bottom) to return a valid user is
651 kept as the active auth group.
652 • If no auth groups yield a valid user (none have default: parameters
654 or successful res: programs) but some of the auth groups have auth:
655 lines (indicating a possibility that the user can authenticate and
656 then obtain permissions), the connection is considered to have no
657 valid auth group (which means that the access groups are ignored
658 completely) but the connection isn't closed. Instead, 480 is
659 returned for everything until the user authenticates.
660 • When the user authenticates, the auth groups are rescanned, and only
662 the matching ones which contain at least one auth, perl_auth, or
663 python_auth line are considered. These auth groups are scanned from
664 the last to the first, running auth: programs and perl_auth: or
665 python_auth: scripts. The first auth group (starting from the
666 bottom) to return a valid user is kept as the active auth group.
667 • Regardless of how an auth group is established, as soon as one is,
669 that auth group is used to assign a user identity by taking the
670 result of the successful res, auth, perl_auth, or python_auth line
671 (or the default: if necessary), and appending the default-domain if
672 necessary. (If the perl_access: or python_access: parameter is
673 present, see below.)
674 • Finally, an access group is selected by scanning the access groups
676 from bottom up and finding the first match. (If the established auth
677 group contained a perl_access: or python_access line, the dynamically
678 generated access group returned by the script is used instead.) User
679 permissions are granted based on the established access group.
680
682 Probably the simplest useful example of a complete readers.conf, this
683 gives permissions to read and post to all groups to any connections
684 from the "example.com" domain, except for Bob's machine, and no
685 privileges for anyone connecting elsewhere:
686 auth example.com {
688 hosts: "*.example.com, example.com, !bob.example.com"
689 default: "<EXAMPLE>"
690 }
691 access full {
693 users: "<EXAMPLE>"
694 newsgroups: *
695 addcanlockuser: none
696 }
697 Note that the above access realm could also be written without the
699 users: key, in which case it applies to any user identity (though in
700 this example, the user identity that will be assigned to all matching
701 connections is "<EXAMPLE>"). It is however recommended to keep an
702 explicit users: key so as to better view to whom the access block
703 applies.
704 As the only available auth realm only matches hosts in the
706 "example.com" domain, any connections from other hosts will be rejected
707 immediately.
708 If you have some systems that should only have read-only access to the
710 server, you can modify the example above slightly by adding an
711 additional auth and access group:
712 auth lab {
714 hosts: "*.lab.example.com"
715 default: <LAB>
716 }
717 access lab {
719 users: <LAB>
720 read: *
721 }
722 If those are put in the file after the above example, they'll take
724 precedence (because they're later in the file) for any user coming from
725 a machine in the lab.example.com domain, everyone will only have read
726 access, not posting access.
727 Here's a similar example for a news server that accepts connections
729 from anywhere but requires the user to specify a username and password.
730 The username and password are first checked against an external
731 database of usernames and passwords, and then make use of PAM:
732 auth all {
734 auth: "ckpasswd -f <pathdb in inn.conf>/newsusers"
735 auth: ckpasswd
736 }
737 access full {
739 users: *
740 newsgroups: *
741 }
742 When the user first connects, there are no res: keys and no default, so
744 they don't receive any valid identity and the connection won't match
745 any access groups (even ones with "users: *"). Such users receive
746 nothing but authentication-required responses from nnrpd until they
747 authenticate.
748 If they then later authenticate, the username and password are checked
750 first by running ckpasswd with the -f option for an external file of
751 encrypted passwords, and then uses PAM (if INN was built with PAM
752 support) to check the password (and if that fails, it tries to check
753 the password against the password field returned by getpwnam(3)). If
754 both of those fail, the user will continue to have no identity;
755 otherwise, an identity will be assigned (usually the supplied username,
756 perhaps with a domain appended, although an authenticator technically
757 can provide a completely different username for the identity), and the
758 access group will match, giving full access.
759 It may be educational to consider how to combine the above examples;
761 general groups always go first. The order of the auth groups actually
762 doesn't matter, since the "hosts: example.com" one only matches
763 connections before username/password is sent, and the "auth: ckpasswd"
764 one only matches after; order would matter if either group applied to
765 both cases. The order of the access groups in this case does matter,
766 provided the newsgroups: lines differ; the access group with no users:
767 line needs to be first, with the "users: <LOCAL>" group after.
768 Here's an example of another common case: a server that only allows
770 connections from a local domain and has an additional hierarchy that's
771 password-restricted.
772 auth "example.com" {
774 hosts: "*.example.com"
775 auth: "ckpasswd -f <pathdb in inn.conf>/newsusers"
776 default: "anonymous"
777 }
778 access regular {
780 newsgroups: "*,!example.restricted.*"
781 addcanlockuser: none
782 }
783 access full {
785 users: "*,!anonymous"
786 newsgroups: *
787 }
788 In this example, unauthenticated users get the identity "anonymous",
790 which matches only the first access group and hence doesn't get access
791 to the example.restricted.* hierarchy. No user-specific Cancel-Lock
792 elements should be generated for anonymous users. Anyone who
793 authenticates using a password in the newsusers file gets full access
794 to all groups. However, note that the only authentication block is
795 limited to hostnames in the example.com domain; connections outside of
796 that domain will never be allowed access or an opportunity to
797 authenticate.
798 Here's a very complicated example. This is for an organization that
800 has an internal hierarchy "example.*" only available to local shell
801 users, who are on machines where identd can be trusted. Dialup users
802 must provide a username and password, which is then checked against
803 RADIUS. Remote users have to use a username and password that's
804 checked against a database on the news server. Finally, the admin
805 staff (users "joe" and "jane") can post anywhere (including the
806 "example.admin.*" groups that are read-only for everyone else), and are
807 exempted from the Perl filter. For an additional twist, posts from
808 dialup users have their Sender header field replaced by their
809 authenticated identity.
810 Since this organization has some internal moderated newsgroups, the
812 admin staff can also post messages with Approved header fields, but
813 other users cannot.
814 auth default {
816 auth: "ckpasswd -f <pathdb in inn.conf>/newsusers"
817 default: <FAIL>
818 default-domain: example.com
819 }
820 auth shell {
822 hosts: *.shell.example.com
823 res: ident
824 auth: ckpasswd
825 default: <FAIL>
826 default-domain: shell.example.com
827 }
828 auth dialup {
830 hosts: *.dialup.example.com
831 auth: radius
832 default: <FAIL>
833 default-domain: dialup.example.com
834 }
835 access shell {
837 users: *@shell.example.com
838 read: *
839 post: "*, !example.admin.*"
840 }
841 access dialup {
843 users: *@dialup.example.com
844 newsgroups: *,!example.*
845 nnrpdauthsender: true
846 }
847 access other {
849 users: "*@example.com, !<FAIL>@example.com"
850 newsgroups: *,!example.*
851 }
852 access fail {
854 users: "<FAIL>@*"
855 newsgroups: !*
856 }
857 access admin {
859 users: "joe@*,jane@*"
860 newsgroups: *
861 access: "RPA"
862 perlfilter: false
863 }
864 Note the use of different domains to separate dialup from shell users
866 easily. Another way to do that would be with key: parameters, but this
867 way provides slightly more intuitive identity strings. Note also that
868 the fail access group catches not only failing connections from
869 external users but also failed authentication of shell and dialup users
870 and dialup users before they've authenticated. The identity string
871 given for, say, dialup users before RADIUS authentication has been
872 attempted matches both the dialup access group and the fail access
873 group, since it's "<FAIL>@dialup.example.com", but the fail group is
874 last so it takes precedence.
875 The shell auth group has an auth: parameter so that users joe and jane
877 can, if they choose, use username and password authentication to gain
878 their special privileges even if they're logged on as a different user
879 on the shell machines (or if ident isn't working). When they first
880 connect, they'd have the default access for that user, but they could
881 then send AUTHINFO USER and AUTHINFO PASS in order to get their
882 extended access.
883 Also note that if the users joe and jane are using their own accounts,
885 they get their special privileges regardless of how they connect,
886 whether the dialups, the shell machines, or even externally with a
887 username and password.
888 Finally, here's a very simple example of a configuration for a public
890 server for a particular hierarchy.
891 auth default {
893 hosts: *
894 default: <PUBLIC>
895 }
896 access default {
898 users: <PUBLIC>
899 newsgroups: example.*
900 addcanlockuser: none
901 }
902 Notice that clients aren't allowed to read any other groups; this keeps
904 them from getting access to administrative groups or reading control
905 messages, just as a precaution. When running a public server like
906 this, be aware that many public hierarchies will later be pulled down
907 and reinjected into the main Usenet, so it's highly recommended that
908 you also run a Perl or Python filter to reject any messages crossposted
909 out of your local hierarchy and any messages containing a Supersedes
910 header field. This will keep messages posted to your public hierarchy
911 from hurting any of the rest of Usenet if they leak out.
912
914 In general, separate passwords should be used for NNTP wherever
915 possible; the NNTP protocol itself does not protect passwords from
916 casual interception, and many implementations (including this one) do
917 not "lock out" accounts or otherwise discourage password-guessing
918 attacks. So it is best to ensure that a compromised password has
919 minimal effects.
920 Authentication using the AUTHINFO USER/PASS commands passes unencrypted
922 over the network. Extreme caution should therefore be used especially
923 with system passwords (e.g. "auth: ckpasswd -s"). Passwords can be
924 protected by using NNTP over TLS/SSL or through ssh tunnels, and this
925 usage can be enforced by a well-considered server configuration that
926 only permits certain auth groups to be applied in certain cases. One
927 can also authenticate using a strong SASL mechanism. Here are some
928 ideas:
929 • To restrict connections on the standard NNTP port (119) to use an
931 encryption layer for some (or all) of the auth groups to match, use
932 the require_encryption parameter. Note that a client can use
933 STARTTLS to negotiate an encrypted TLS connection. A secure layer
934 can also be negotiated during authentication via AUTHINFO SASL.
935 • If you consider your local network (but not the internet) secure,
937 have some auth groups with a restrictive hosts: parameter; they
938 would go above, with ones having global applicability below.
939 • Consider running nnrpd with the -S flag (either also with -D, or
941 out of "super-server" like inetd) on the NNTPS port (563) for
942 clients that support TLS/SSL. See nnrpd(8) for more details about
943 how to configure that. You can use the require_encryption
944 parameter or the -c flag to specify an alternate readers.conf file
945 if you want a substantially different configuration for this case.
946 • If you want to restrict an auth group to only match loopback
948 connections (for users running newsreaders on localhost or
949 connecting via an ssh tunnel), use the localaddress: parameter.
950
952 Written by Aidan Cully <aidan@panix.com> for InterNetNews.
953 Substantially expanded by Russ Allbery <eagle@eyrie.org>.
954
956 auth_krb5(8), ckpasswd(8), inn.conf(5), innd(8), inn-secrets.conf(5),
957 libinn_uwildmat(3), newsfeeds(5), nnrpd(8).
958INN 2.7.0 2022-07-10 READERS.CONF(5)