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 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_ssl parameter set to true only applies if the incoming
165 connection is using an encryption layer, either from the beginning if
166 the -S flag was passed to nnrpd, or after a successful use of STARTTLS,
167 or after a successful authentication using a SASL mechanism which
168 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 }
247 In this case, the two key: parameters bind this auth group with this
249 access group. For any incoming connection matching "*.example.com"
250 (assuming there isn't any later auth group that also matches such
251 hosts), no access group that doesn't have "key: special" will even be
252 considered. Similarly, the above access group will only be checked if
253 the user was authenticated with an auth group containing "key:
254 special". This mechanism normally isn't useful; there is almost always
255 a better way to achieve the same result.
256 Also note in the example that there's no default-domain: parameter,
258 which means that no domain is appended to the default username and the
259 identity for such connections is just "<SPECIAL>". Note that some
260 additional add-ons to INN may prefer that authenticated identities
261 always return a full e-mail address (including a domain), so you may
262 want to set up your system that way.
263 Configuration files can be included in other configuration files via
265 the syntax:
266 include <filename>
268 The file named <filename> is then included. This syntax is allowed
270 only at top-level.
271 Below is the full list of allowable parameters for auth groups and
273 access groups, and after that are some examples that may make this
274 somewhat clearer.
275
277 An auth group without at least one of the res:, auth:, perl_auth:,
278 python_auth:, or default: parameters makes no sense (and in practice
279 will just be ignored).
280 hosts:
282 A comma-separated list of remote hosts, wildmat patterns matching
283 either hostnames or IP addresses, or IP netblocks specified in CIDR
284 notation. If a user connects from a host that doesn't match this
285 parameter, this auth group will not match the connection and is
286 ignored.
287 Note that if you have a large number of patterns that can't be
289 merged into broader patterns (such as a large number of individual
290 systems scattered around the net that should have access), the
291 hosts: parameter may exceed the maximum line length of 8,192
292 characters. In that case, you'll need to break that auth group
293 into multiple auth groups, each with a portion of the hosts listed
294 in its hosts: parameter, and each assigning the same user identity.
295 All hosts match if this parameter is not given.
297 localaddress:
299 A comma-separated list of local host or address patterns with the
300 same syntax as the same as with the hosts: parameter. If this
301 parameter is specified, its auth group will only match connections
302 made to a matching local interface. (Obviously, this is only
303 useful for servers with multiple interfaces.)
304 All local addresses match if this parameter is not given.
306 res:
308 A simple command line for a user resolver (shell metacharacters are
309 not supported). If a full path is not given, the program executed
310 must be in the pathbin/auth/resolv directory. A resolver is an
311 authentication program which attempts to figure out the identity of
312 the connecting user using nothing but the connection information
313 (in other words, the user has not provided a username and
314 password). An examples of a resolver would be a program that
315 assigns an identity from an ident callback or from the user's
316 hostname.
317 One auth group can have multiple res: parameters, and they will be
319 tried in the order they're listed. The results of the first
320 successful one will be used.
321 Alternatively, a res block can be used instead of a res: parameter.
323 The recognized parameters in such res blocks are:
324 log:
326 A string to log in pathlog/news.notice (with "res also-log:"
327 prepended) before the resolver is tried. One res group can have
328 multiple log: parameters, and they will be logged in the order
329 they're listed.
330 program:
332 This parameter is mandatory in a res block. Its meaning is the
333 same as the res: parameter used directly in an auth block.
334 auth <auth-name> {
336 res: <res-program>
337 }
338 is therefore equivalent to:
340 auth <auth-name> {
342 res <res-name> {
343 program: <res-program>
344 }
345 }
346 auth:
348 A simple command line for a user authenticator (shell
349 metacharacters are not supported). If a full path is not given,
350 the program executed must be located in the pathbin/auth/passwd
351 directory. An authenticator is a program used to handle a user-
352 supplied username and password, via a mechanism such as AUTHINFO
353 USER/PASS. Like with res:, one auth group can have multiple auth:
354 parameters; they will be tried in order and the results of the
355 first successful one will be used. See also perl_auth: below.
356 The most common authenticator to use is ckpasswd(8); see its man
358 page for more information.
359 perl_auth:
361 A path to a perl script for authentication. The perl_auth:
362 parameter works exactly like auth:, except that it calls the named
363 script using the perl hook rather than an external program.
364 Multiple/mixed use of the auth, perl_auth, and python_auth
365 parameters is permitted within any auth group; each line is tried
366 in the order it appears. perl_auth: has more power than auth: in
367 that it provides the authentication program with additional
368 information about the client and the ability to return an error
369 string and a username. This parameter is only valid if INN is
370 compiled with Perl support (--with-perl passed to configure). More
371 information may be found in doc/hook-perl.
372 python_auth:
374 A Python script for authentication. The python_auth parameter
375 works exactly like auth, except that it calls the named script
376 (without its ".py" extension) using the Python hook rather than an
377 external program. Multiple/mixed use of the auth, perl_auth, and
378 python_auth parameters is permitted within any auth group; each
379 line is tried in the order it appears. python_auth has more power
380 than auth in that it provides the authentication program with
381 additional information about the client and the ability to return
382 an error string and a username. This parameter is only valid if
383 INN is compiled with Python support (--with-python passed to
384 configure). More information may be found in doc/hook-python.
385 default:
387 The default username for connections matching this auth group.
388 This is the username assigned to the user at connection time if all
389 resolvers fail or if there are no res: parameters. Note that it
390 can be either a bare username, in which case default-domain: (if
391 present) is appended after an "@", or a full identity string
392 containing an "@", in which case it will be used verbatim.
393 default-domain:
395 The default domain string for this auth group. If a user resolver
396 or authenticator doesn't provide a domain, or if the default
397 username is used and it doesn't contain a "@", this domain is used
398 to form the user identity. (Note that for a lot of setups, it's
399 not really necessary for user identities to be qualified with a
400 domain name, in which case there's no need to use this parameter.)
401 key:
403 If this parameter is present, any connection matching this auth
404 group will have its privileges determined only by the subset of
405 access groups containing a matching key parameter.
406 require_ssl:
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 a 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 perl_access:
419 A path to a perl script for dynamically generating an access group.
420 If an auth group matches successfully and contains a perl_access
421 parameter, then the argument perl script will be used to create an
422 access group. This group will then determine the access rights of
423 the client, overriding any access groups in readers.conf. If and
424 only if a sucessful auth group contains the perl_access parameter,
425 readers.conf access groups are ignored and the client's rights are
426 instead determined dynamically. This parameter is only valid if
427 INN is compiled with Perl support (--with-perl passed to
428 configure). More information may be found in the file
429 doc/hook-perl.
430 python_access:
432 A Python script for dynamically generating an access group. If an
433 auth group matches successfully and contains a python_access
434 parameter, then the argument script (without its ".py" extension)
435 will be used to create an access group. This group will then
436 determine the access rights of the client, overriding any access
437 groups in readers.conf. If and only if a successful auth group
438 contains the python_access parameter, readers.conf access groups
439 are ignored and the client's rights are instead determined
440 dynamically. This parameter is only valid if INN is compiled with
441 Python support (--with-python passed to configure). More
442 information may be found in the file doc/hook-python.
443 python_dynamic:
445 A Python script for applying access control dynamically on a per
446 newsgroup basis. If an auth group matches successfully and
447 contains a python_dynamic parameter, then the argument script
448 (without its ".py" extension) will be used to determine the clients
449 rights each time the user attempts to view a newsgroup, or read or
450 post an article. Access rights as determined by python_dynamic
451 override the values of access group parameters such as newsgroups,
452 read and post. This parameter is only valid if INN is compiled
453 with Python support (--with-python passed to configure). More
454 information may be found in the file doc/hook-python.
455
457 users:
458 The privileges given by this access group apply to any user
459 identity which matches this comma-separated list of wildmat
460 patterns. If this parameter isn't given, the access group applies
461 to all users (and is essentially equivalent to "users: *").
462 newsgroups:
464 Users that match this access group are allowed to read and post to
465 all newsgroups matching this comma-separated list of wildmat
466 patterns. The empty string is equivalent to "newsgroups: *"; if
467 this parameter is missing, the connection will be rejected (unless
468 read: and/or post: are used instead, see below).
469 read:
471 Like the newsgroups: parameter, but the client is only given
472 permission to read the matching newsgroups. This parameter is
473 often used with post: (below) to specify some read-only groups; it
474 cannot be used in the same access group with a newsgroups:
475 parameter. (If read: is used and post: is missing, the client will
476 have only read-only access.)
477 post:
479 Like the newsgroups: parameter, but the client is only given
480 permission to post to the matching newsgroups. This parameter is
481 often used with read: (above) to define the patterns for reading
482 and posting separately (usually to give the user permission to read
483 more newsgroups than they're permitted to post to). It cannot be
484 used in the same access group with a newsgroups: parameter.
485 access:
487 A set of letters specifying the permissions granted to the client.
488 The letters are chosen from the following set:
489 R The client may read articles.
491 P The client may post articles.
493 I The client may inject articles with IHAVE. Note that in order
495 to inject articles with the IHAVE command, the user must also
496 have POST permission (the "P" option). Articles injected with
497 IHAVE are treated as though they were injected with POST, that
498 is to say such articles must not have been previously injected
499 (they must not contain headers like Injection-Info:).
500 A The client may post articles with Approved: headers (in other
502 words, may approve articles for moderated newsgroups). By
503 default, this is not allowed.
504 N The client may use the NEWNEWS command, overriding the global
506 setting.
507 L The client may post to newsgroups that are set to disallow local
509 posting (status fields "j", "n" and "x" in the active(5) file).
510 Note that if this parameter is given, allownewnews in inn.conf is
512 ignored for connections matching this access group and the ability
513 of the client to use NEWNEWS is entirely determined by the presence
514 of "N" in the access string. If you want to support NEWNEWS, make
515 sure to include "N" in the access string when you use this
516 parameter.
517 Note that if this parameter is given and "R" isn't present in the
519 access string, the client cannot read regardless of newsgroups: or
520 read: parameters. Similarly, if this parameter is given and "P"
521 isn't present, the client cannot post. This use of access: is
522 deprecated and confusing; it's strongly recommended that if the
523 access: parameter is used, "R" and "P" always be included in the
524 access string and newsgroups:, read:, and post: be used to control
525 access. (To grant read access but no posting access, one can have
526 just a read: parameter and no post: parameter.)
527 key:
529 If this parameter is present, this access group is only considered
530 when finding privileges for users matching auth groups with this
531 same key: parameter.
532 reject_with:
534 If this parameter is present, a client matching this block will be
535 disconnected with a "Permission denied" message containing the
536 contents (a "reason" string) of this parameter. Some newsreaders
537 will then display the reason to the user.
538 max_rate:
540 If this parameter is present (and nonzero), it is used for nnrpd's
541 rate-limiting code. The client will only be able to download at
542 this speed (in bytes/second). Note that if an encryption layer is
543 being used, limiting is applied to the pre-encryption datastream.
544 localtime:
546 If a Date: or an Injection-Date: header field is not included in a
547 posted article, nnrpd(8) normally adds these header fields in UTC.
548 If this is set to true, the Date: header field will be formatted in
549 local time instead. (The Injection-Date: header field is added
550 according to the behaviour of the addinjectiondate parameter in
551 inn.conf, and will remain in UTC, though.) This is a boolean value
552 and the default is false.
553 This parameter permits handling a relatively unusual corner case.
555 It is mostly a tool for people who want to disclose their local
556 time zone (it can be useful information in certain types of
557 discussions), but whose clients don't for some reason, and who can
558 arrange for the server to be in the same time zone as the client.
559 newsmaster:
561 Used as the contact address in the help message returned by
562 nnrpd(8), if the virtualhost: parameter is set to true.
563 strippath:
565 If set to true, any Path: header provided by a user in a post is
566 stripped rather than used as the beginning of the Path: header of
567 the article. This is a boolean value and the default is false.
568 perlfilter:
570 If set to false, posts made by these users do not pass through the
571 Perl filter even if it is otherwise enabled. This is a boolean
572 value and the default is true.
573 pythonfilter:
575 If set to false, posts made by these users do not pass through the
576 Python filter even if it is otherwise enabled. This is a boolean
577 value and the default is true.
578 virtualhost:
580 Set this parameter to true in order to make nnrpd behave as if it
581 is running on a server with a different name than it actually is.
582 If you set this parameter to true, you must also set either
583 pathhost: or domain: in the relevant access group in readers.conf
584 to something different than is set in inn.conf. All articles
585 displayed to clients will then have their Path: and Xref: headers
586 altered to appear to be from the server named in pathhost: or
587 domain: (whichever is set), and posted articles will use that
588 server name in the Path:, Message-ID:, and Injection-Info: headers.
589 Note that setting this parameter requires the server modify all
591 posts before presenting them to the client and therefore may
592 decrease performance slightly.
593 In addition, all of the following parameters are valid in access groups
595 and override the global setting in inn.conf. See inn.conf(5) for the
596 descriptions of these parameters:
597 addinjectiondate, addinjectionpostingaccount, addinjectionpostinghost,
599 backoff_auth, backoff_db, backoff_k, backoff_postfast, backoff_postslow,
600 backoff_trigger, checkincludedtext, clienttimeout, complaints, domain,
601 fromhost, localmaxartsize, moderatormailer, nnrpdauthsender, nnrpdcheckart,
602 nnrpdoverstats, nnrpdposthost, nnrpdpostport, organization, pathhost,
603 readertrack, spoolfirst, strippostcc.
604
606 Here's a basic summary of what happens when a client connects:
607 • All auth groups are scanned and the ones that don't match the client
609 (due to hosts, localaddress, require_ssl, etc.) are eliminated.
610 • The remaining auth groups are scanned from the last to the first, and
612 an attempt is made to apply it to the current connection. This means
613 running res: programs, if any, and otherwise applying default:. The
614 first auth group (starting from the bottom) to return a valid user is
615 kept as the active auth group.
616 • If no auth groups yield a valid user (none have default: parameters
618 or successful res: programs) but some of the auth groups have auth:
619 lines (indicating a possibility that the user can authenticate and
620 then obtain permissions), the connection is considered to have no
621 valid auth group (which means that the access groups are ignored
622 completely) but the connection isn't closed. Instead, 480 is
623 returned for everything until the user authenticates.
624 • When the user authenticates, the auth groups are rescanned, and only
626 the matching ones which contain at least one auth, perl_auth, or
627 python_auth line are considered. These auth groups are scanned from
628 the last to the first, running auth: programs and perl_auth: or
629 python_auth: scripts. The first auth group (starting from the
630 bottom) to return a valid user is kept as the active auth group.
631 • Regardless of how an auth group is established, as soon as one is,
633 that auth group is used to assign a user identity by taking the
634 result of the successful res, auth, perl_auth, or python_auth line
635 (or the default: if necessary), and appending the default-domain if
636 necessary. (If the perl_access: or python_access: parameter is
637 present, see below.)
638 • Finally, an access group is selected by scanning the access groups
640 from bottom up and finding the first match. (If the established auth
641 group contained a perl_access: or python_access line, the dynamically
642 generated access group returned by the script is used instead.) User
643 permissions are granted based on the established access group.
644
646 Probably the simplest useful example of a complete readers.conf, this
647 gives permissions to read and post to all groups to any connections
648 from the "example.com" domain, and no privileges for anyone connecting
649 elsewhere:
650 auth example.com {
652 hosts: "*.example.com, example.com"
653 default: "<EXAMPLE>"
654 }
655 access full {
657 users: "<EXAMPLE>"
658 newsgroups: *
659 }
660 Note that the above access realm could also be written without the
662 users: key, in which case it applies to any user identity (though in
663 this example, the user identity that will be assigned to all matching
664 connections is "<EXAMPLE>"). It is however recommended to keep an
665 explicit users: key so as to better view to whom the access block
666 applies.
667 As the only available auth realm only matches hosts in the
669 "example.com" domain, any connections from other hosts will be rejected
670 immediately.
671 If you have some systems that should only have read-only access to the
673 server, you can modify the example above slightly by adding an
674 additional auth and access group:
675 auth lab {
677 hosts: "*.lab.example.com"
678 default: <LAB>
679 }
680 access lab {
682 users: <LAB>
683 read: *
684 }
685 If those are put in the file after the above example, they'll take
687 precedence (because they're later in the file) for any user coming from
688 a machine in the lab.example.com domain, everyone will only have read
689 access, not posting access.
690 Here's a similar example for a news server that accepts connections
692 from anywhere but requires the user to specify a username and password.
693 The username and password are first checked against an external
694 database of usernames and passwords, and then make use of PAM:
695 auth all {
697 auth: "ckpasswd -f <pathdb in inn.conf>/newsusers"
698 auth: ckpasswd
699 }
700 access full {
702 users: *
703 newsgroups: *
704 }
705 When the user first connects, there are no res: keys and no default, so
707 they don't receive any valid identity and the connection won't match
708 any access groups (even ones with "users: *"). Such users receive
709 nothing but authentication-required responses from nnrpd until they
710 authenticate.
711 If they then later authenticate, the username and password are checked
713 first by running ckpasswd with the -f option for an external file of
714 encrypted passwords, and then uses PAM (if INN was built with PAM
715 support) to check the password (and if that fails, it tries to check
716 the password against the password field returned by getpwnam(3)). If
717 both of those fail, the user will continue to have no identity;
718 otherwise, an identity will be assigned (usually the supplied username,
719 perhaps with a domain appended, although an authenticator technically
720 can provide a completely different username for the identity), and the
721 access group will match, giving full access.
722 It may be educational to consider how to combine the above examples;
724 general groups always go first. The order of the auth groups actually
725 doesn't matter, since the "hosts: example.com" one only matches
726 connections before username/password is sent, and the "auth: ckpasswd"
727 one only matches after; order would matter if either group applied to
728 both cases. The order of the access groups in this case does matter,
729 provided the newsgroups: lines differ; the access group with no users:
730 line needs to be first, with the "users: <LOCAL>" group after.
731 Here's an example of another common case: a server that only allows
733 connections from a local domain and has an additional hierarchy that's
734 password-restricted.
735 auth "example.com" {
737 hosts: "*.example.com"
738 auth: "ckpasswd -f <pathdb in inn.conf>/newsusers"
739 default: "anonymous"
740 }
741 access regular {
743 newsgroups: "*,!example.restricted.*"
744 }
745 access full {
747 users: "*,!anonymous"
748 newsgroups: *
749 }
750 In this example, unauthenticated users get the identity "anonymous",
752 which matches only the first access group and hence doesn't get access
753 to the example.restricted.* hierarchy. Anyone who authenticates using
754 a password in the newsusers file gets full access to all groups.
755 However, note that the only authentication block is limited to
756 hostnames in the example.com domain; connections outside of that domain
757 will never be allowed access or an opportunity to authenticate.
758 Here's a very complicated example. This is for an organization that
760 has an internal hierarchy "example.*" only available to local shell
761 users, who are on machines where identd can be trusted. Dialup users
762 must provide a username and password, which is then checked against
763 RADIUS. Remote users have to use a username and password that's
764 checked against a database on the news server. Finally, the admin
765 staff (users "joe" and "jane") can post anywhere (including the
766 "example.admin.*" groups that are read-only for everyone else), and are
767 exempted from the Perl filter. For an additional twist, posts from
768 dialup users have their Sender: header replaced by their authenticated
769 identity.
770 Since this organization has some internal moderated newsgroups, the
772 admin staff can also post messages with Approved: headers, but other
773 users cannot.
774 auth default {
776 auth: "ckpasswd -f <pathdb in inn.conf>/newsusers"
777 default: <FAIL>
778 default-domain: example.com
779 }
780 auth shell {
782 hosts: *.shell.example.com
783 res: ident
784 auth: ckpasswd
785 default: <FAIL>
786 default-domain: shell.example.com
787 }
788 auth dialup {
790 hosts: *.dialup.example.com
791 auth: radius
792 default: <FAIL>
793 default-domain: dialup.example.com
794 }
795 access shell {
797 users: *@shell.example.com
798 read: *
799 post: "*, !example.admin.*"
800 }
801 access dialup {
803 users: *@dialup.example.com
804 newsgroups: *,!example.*
805 nnrpdauthsender: true
806 }
807 access other {
809 users: "*@example.com, !<FAIL>@example.com"
810 newsgroups: *,!example.*
811 }
812 access fail {
814 users: "<FAIL>@*"
815 newsgroups: !*
816 }
817 access admin {
819 users: "joe@*,jane@*"
820 newsgroups: *
821 access: "RPA"
822 perlfilter: false
823 }
824 Note the use of different domains to separate dialup from shell users
826 easily. Another way to do that would be with key: parameters, but this
827 way provides slightly more intuitive identity strings. Note also that
828 the fail access group catches not only failing connections from
829 external users but also failed authentication of shell and dialup users
830 and dialup users before they've authenticated. The identity string
831 given for, say, dialup users before RADIUS authentication has been
832 attempted matches both the dialup access group and the fail access
833 group, since it's "<FAIL>@dialup.example.com", but the fail group is
834 last so it takes precedence.
835 The shell auth group has an auth: parameter so that users joe and jane
837 can, if they choose, use username and password authentication to gain
838 their special privileges even if they're logged on as a different user
839 on the shell machines (or if ident isn't working). When they first
840 connect, they'd have the default access for that user, but they could
841 then send AUTHINFO USER and AUTHINFO PASS in order to get their
842 extended access.
843 Also note that if the users joe and jane are using their own accounts,
845 they get their special privileges regardless of how they connect,
846 whether the dialups, the shell machines, or even externally with a
847 username and password.
848 Finally, here's a very simple example of a configuration for a public
850 server for a particular hierarchy.
851 auth default {
853 hosts: *
854 default: <PUBLIC>
855 }
856 access default {
858 users: <PUBLIC>
859 newsgroups: example.*
860 }
861 Notice that clients aren't allowed to read any other groups; this keeps
863 them from getting access to administrative groups or reading control
864 messages, just as a precaution. When running a public server like
865 this, be aware that many public hierarchies will later be pulled down
866 and reinjected into the main Usenet, so it's highly recommended that
867 you also run a Perl or Python filter to reject any messages crossposted
868 out of your local hierarchy and any messages containing a Supersedes:
869 header. This will keep messages posted to your public hierarchy from
870 hurting any of the rest of Usenet if they leak out.
871
873 In general, separate passwords should be used for NNTP wherever
874 possible; the NNTP protocol itself does not protect passwords from
875 casual interception, and many implementations (including this one) do
876 not "lock out" accounts or otherwise discourage password-guessing
877 attacks. So it is best to ensure that a compromised password has
878 minimal effects.
879 Authentication using the AUTHINFO USER/PASS commands passes unencrypted
881 over the network. Extreme caution should therefore be used especially
882 with system passwords (e.g. "auth: ckpasswd -s"). Passwords can be
883 protected by using NNTP over TLS/SSL or through ssh tunnels, and this
884 usage can be enforced by a well-considered server configuration that
885 only permits certain auth groups to be applied in certain cases. One
886 can also authenticate using a strong SASL mechanism. Here are some
887 ideas:
888 • To restrict connections on the standard NNTP port (119) to use an
890 encryption layer for some (or all) of the auth groups to match, use
891 the require_ssl parameter. Note that a client can use STARTTLS to
892 negotiate an encrypted TLS connection. A secure layer can also be
893 negotiated during authentication via AUTHINFO SASL.
894 • If you consider your local network (but not the internet) secure,
896 have some auth groups with a restrictive hosts: parameter; they
897 would go above, with ones having global applicability below.
898 • Consider running nnrpd with the -S flag (either also with -D, or
900 out of "super-server" like inetd) on the NNTPS port (563) for
901 clients that support TLS/SSL. See nnrpd(8) for more details about
902 how to configure that. You can use the require_ssl parameter or
903 the -c flag to specify an alternate readers.conf file if you want a
904 substantially different configuration for this case.
905 • If you want to restrict an auth group to only match loopback
907 connections (for users running newsreaders on localhost or
908 connecting via an ssh tunnel), use the localaddress: parameter.
909
911 Written by Aidan Cully <aidan@panix.com> for InterNetNews.
912 Substantially expanded by Russ Allbery <eagle@eyrie.org>.
913
915 auth_krb5(8), ckpasswd(8), inn.conf(5), innd(8), libinn_uwildmat(3),
916 newsfeeds(5), nnrpd(8).
917INN 2.6.5 2022-02-18 READERS.CONF(5)