1READERS.CONF(5) InterNetNews Documentation READERS.CONF(5)
2
6 readers.conf - Access control and configuration for nnrpd
7
9 readers.conf in pathetc specifies access control for nnrpd(8). It
10 controls who is allowed to connect as a news reader and what they're
11 allowed to do after they connect. nnrpd reads this file when it starts
12 up. This generally means that any changes take effect immediately on
13 all subsequent connections, but nnrpd may have to be restarted if you
14 use the -D option. (The location pathetc/readers.conf is only the
15 default; the same format applies to any file specified with "nnrpd
16 -c".)
17 There are two types of entries in readers.conf: parameter/value pairs
19 and configuration groups. Blank lines and anything after a number sign
20 ("#") are ignored, unless the character "#" is escaped with "\". The
21 maximum number of characters on each line is 8,191.
22 Parameter/value pairs consist of a keyword immediately followed by a
24 colon, at least one whitespace character, and a value. The case of the
25 parameter is significant (parameter should generally be in all
26 lowercase), and a parameter may contain any characters except colon,
27 "#", and whitespace. An example:
28 hosts: *.example.com
30 Values that contain whitespace should be quoted with double quotes, as
32 in:
33 hosts: "*.example.com, *.example.net"
35 If the parameter does not contain whitespace, such as:
37 hosts: *.example.com,*.example.net
39 it's not necessary to quote it, although you may wish to anyway for
41 clarity.
42 There is no way to continue a line on the next line, and therefore no
44 way to have a single parameter with a value longer than about 8,180
45 characters.
46 Many parameters take a boolean value. For all such parameters, the
48 value may be specified as "true", "yes", or "on" to turn it on and may
49 be any of "false", "no", or "off" to turn it off. The case of these
50 values is not significant.
51 There are two basic types of configuration groups, auth and access.
53 The auth group provides mechanisms to establish the identity of the
54 user, who they are. The access group determines, given the user's
55 identity, what that user is permitted to do. Writing a readers.conf
56 file for your setup is a two-step process: first assigning an identity
57 to each incoming connection using auth groups, and then giving each
58 identity appropriate privileges with access group. We recommend not
59 intermingling auth groups and access groups in the config file; it is
60 often more sensible (in the absence of the key parameter) to put all of
61 the auth groups first, and all of the access groups below.
62 A user identity, as established by an auth group, looks like an e-mail
64 address; in other words, it's in the form "<username>@<domain>" (or
65 sometimes just "<username>" if no domain is specified.
66 If nnrpdauthsender is set in inn.conf, the user identity is also put
68 into the Sender: header of posts made by that user. See the
69 documentation of that option in inn.conf(5) for more details.
70 An auth group definition looks like:
72 auth <name> {
74 hosts: <host-wildmat>
75 auth: <auth-program>
76 res: <res-program>
77 default: <defuser>
78 default-domain: <defdomain>
79 # ...possibly other settings
80 }
81 The <name> is used as a label for the group and is only for
83 documentation purposes. (If your syslog configuration records the
84 "news.debug" facility, the <name> will appear in the debugging output
85 of nnrpd. Examining that output can be very helpful in understanding
86 why your configuration doesn't do what you expect it to.)
87 A given auth group applies only to hosts whose name or IP address
89 matches the wildmat expression given with the hosts: parameter (comma-
90 separated wildmat expressions allowed, but "@" is not supported).
91 Rather than wildmat expressions, you may also use CIDR notation to
92 match any IP address in a netblock; for example, "10.10.10.0/24" will
93 match any IP address between 10.10.10.0 and 10.10.10.255 inclusive.
94 If compiled against the TLS/SSL or SASL libraries, an auth group with
96 the require_ssl parameter set to true only applies if the incoming
97 connection is using an encryption layer, either from the beginning if
98 the -S flag was passed to nnrpd, or after a successful use of STARTTLS,
99 or after a successful authentication using a SASL mechanism which
100 negotiates an encryption layer.
101 For any connection from a host that matches that wildmat expression or
103 netblock, each <res-program> (multiple res: lines may be present in a
104 block; they are run in sequence until one succeeds), if any, is run to
105 determine the identity of the user just from the connection
106 information. If all the resolvers fail, or if the res: parameter isn't
107 present, the user is assigned an identity of "<defuser>@<defdomain>";
108 in other words, the values of the default: and default-domain:
109 parameters are used. If <res-program> only returns a username,
110 <defdomain> is used as the domain.
111 If the user later authenticates via the AUTHINFO USER/PASS commands,
113 the provided username and password are passed to each <auth-program>
114 (multiple auth, perl_auth, or python_auth lines may be present in a
115 block; they are run in sequence until one succeeds), if any. If one
116 succeeds and returns a different identity than the one assigned at the
117 time of the connection, it is matched against the available access
118 groups again and the actions the user is authorized to do may change.
119 The most common <auth-program> to use is ckpasswd, which supports
120 several ways of checking passwords including using PAM. See the
121 ckpasswd(8) man page for more details.
122 When matching auth groups, the last auth group in the file that matches
124 a given connection and username/password combination is used.
125 An access group definition usually looks like:
127 access <name> {
129 users: <identity-wildmat>
130 newsgroups: <group-wildmat>
131 # ...possibly other settings
132 }
133 Again, <name> is just for documentation purposes. This says that all
135 users whose identity matches <identity-wildmat> can read and post to
136 all newsgroups matching <group-wildmat> (as before, comma-separated
137 wildmat expressions are allowed, but "@" is not supported).
138 Alternately, you can use the form:
139 access <name> {
141 users: <identity-wildmat>
142 read: <read-wildmat>
143 post: <post-wildmat>
144 }
145 and matching users will be able to read any group that matches
147 <read-wildmat> and post to any group that matches <post-wildmat>. You
148 can also set several other things in the access group as well as
149 override various inn.conf(5) parameters for just a particular group of
150 users.
151 Just like with auth groups, when matching access groups the last
153 matching one in the file is used to determine the user's permissions.
154 There is an exception to this rule: if the auth group which matched the
155 client contains a perl_access: or python_access: parameter, then the
156 script given as argument is used to dynamically generate an access
157 group. This new access group is then used to determine the access
158 rights of the client; the access groups in the file are ignored.
159 There is one additional special case to be aware of. When forming
161 particularly complex authentication and authorization rules, it is
162 sometimes useful for the identities provided by a given auth group to
163 only apply to particular access groups; in other words, rather than
164 checking the identity against the users: parameter of every access
165 group, it's checked against the users: parameter of only some specific
166 access groups. This is done with the key: parameter. For example:
167 auth example {
169 key: special
170 hosts: *.example.com
171 default: <SPECIAL>
172 }
173 access example {
175 key: special
176 users: <SPECIAL>
177 newsgroups: *
178 }
179 In this case, the two key: parameters bind this auth group with this
181 access group. For any incoming connection matching "*.example.com"
182 (assuming there isn't any later auth group that also matches such
183 hosts), no access group that doesn't have "key: special" will even be
184 considered. Similarly, the above access group will only be checked if
185 the user was authenticated with an auth group containing "key:
186 special". This mechanism normally isn't useful; there is almost always
187 a better way to achieve the same result.
188 Also note in the example that there's no default-domain: parameter,
190 which means that no domain is appended to the default username and the
191 identity for such connections is just "<SPECIAL>". Note that some
192 additional add-ons to INN may prefer that authenticated identities
193 always return a full e-mail address (including a domain), so you may
194 want to set up your system that way.
195 Configuration files can be included in other configuration files via
197 the syntax:
198 include <filename>
200 The file named <filename> is then included. This syntax is allowed
202 only at top-level.
203 Below is the full list of allowable parameters for auth groups and
205 access groups, and after that are some examples that may make this
206 somewhat clearer.
207
209 An auth group without at least one of the res:, auth:, perl_auth:,
210 python_auth:, or default: parameters makes no sense (and in practice
211 will just be ignored).
212 hosts:
214 A comma-separated list of remote hosts, wildmat patterns matching
215 either hostnames or IP addresses, or IP netblocks specified in CIDR
216 notation. If a user connects from a host that doesn't match this
217 parameter, this auth group will not match the connection and is
218 ignored.
219 Note that if you have a large number of patterns that can't be
221 merged into broader patterns (such as a large number of individual
222 systems scattered around the net that should have access), the
223 hosts: parameter may exceed the maximum line length of 8,192
224 characters. In that case, you'll need to break that auth group
225 into multiple auth groups, each with a portion of the hosts listed
226 in its hosts: parameter, and each assigning the same user identity.
227 All hosts match if this parameter is not given.
229 localaddress:
231 A comma-separated list of local host or address patterns with the
232 same syntax as the same as with the hosts: parameter. If this
233 parameter is specified, its auth group will only match connections
234 made to a matching local interface. (Obviously, this is only
235 useful for servers with multiple interfaces.)
236 All local addresses match if this parameter is not given.
238 res:
240 A simple command line for a user resolver (shell metacharacters are
241 not supported). If a full path is not given, the program executed
242 must be in the pathbin/auth/resolv directory. A resolver is an
243 authentication program which attempts to figure out the identity of
244 the connecting user using nothing but the connection information
245 (in other words, the user has not provided a username and
246 password). An examples of a resolver would be a program that
247 assigns an identity from an ident callback or from the user's
248 hostname.
249 One auth group can have multiple res: parameters, and they will be
251 tried in the order they're listed. The results of the first
252 successful one will be used.
253 Alternatively, a res block can be used instead of a res: parameter.
255 The recognized parameters in such res blocks are:
256 log:
258 A string to log in pathlog/news.notice (with "res also-log:"
259 prepended) before the resolver is tried. One res group can have
260 multiple log: parameters, and they will be logged in the order
261 they're listed.
262 program:
264 This parameter is mandatory in a res block. Its meaning is the
265 same as the res: parameter used directly in an auth block.
266 auth <auth-name> {
268 res: <res-program>
269 }
270 is therefore equivalent to:
272 auth <auth-name> {
274 res <res-name> {
275 program: <res-program>
276 }
277 }
278 auth:
280 A simple command line for a user authenticator (shell
281 metacharacters are not supported). If a full path is not given,
282 the program executed must be located in the pathbin/auth/passwd
283 directory. An authenticator is a program used to handle a user-
284 supplied username and password, via a mechanism such as AUTHINFO
285 USER/PASS. Like with res:, one auth group can have multiple auth:
286 parameters; they will be tried in order and the results of the
287 first successful one will be used. See also perl_auth: below.
288 The most common authenticator to use is ckpasswd(8); see its man
290 page for more information.
291 perl_auth:
293 A path to a perl script for authentication. The perl_auth:
294 parameter works exactly like auth:, except that it calls the named
295 script using the perl hook rather than an external program.
296 Multiple/mixed use of the auth, perl_auth, and python_auth
297 parameters is permitted within any auth group; each line is tried
298 in the order it appears. perl_auth: has more power than auth: in
299 that it provides the authentication program with additional
300 information about the client and the ability to return an error
301 string and a username. This parameter is only valid if INN is
302 compiled with Perl support (--with-perl passed to configure). More
303 information may be found in doc/hook-perl.
304 python_auth:
306 A Python script for authentication. The python_auth parameter
307 works exactly like auth, except that it calls the named script
308 (without its ".py" extension) using the Python hook rather than an
309 external program. Multiple/mixed use of the auth, perl_auth, and
310 python_auth parameters is permitted within any auth group; each
311 line is tried in the order it appears. python_auth has more power
312 than auth in that it provides the authentication program with
313 additional information about the client and the ability to return
314 an error string and a username. This parameter is only valid if
315 INN is compiled with Python support (--with-python passed to
316 configure). More information may be found in doc/hook-python.
317 default:
319 The default username for connections matching this auth group.
320 This is the username assigned to the user at connection time if all
321 resolvers fail or if there are no res: parameters. Note that it
322 can be either a bare username, in which case default-domain: (if
323 present) is appended after an "@", or a full identity string
324 containing an "@", in which case it will be used verbatim.
325 default-domain:
327 The default domain string for this auth group. If a user resolver
328 or authenticator doesn't provide a domain, or if the default
329 username is used and it doesn't contain a "@", this domain is used
330 to form the user identity. (Note that for a lot of setups, it's
331 not really necessary for user identities to be qualified with a
332 domain name, in which case there's no need to use this parameter.)
333 key:
335 If this parameter is present, any connection matching this auth
336 group will have its privileges determined only by the subset of
337 access groups containing a matching key parameter.
338 require_ssl:
340 If set to true, an incoming connection only matches this auth group
341 if it is encrypted, either from the beginning if the -S flag was
342 passed to nnrpd, or after a successful use of STARTTLS, or after a
343 successful authentication using a SASL mechanism which negotiates
344 an encrypted layer. This parameter is only valid if INN is
345 compiled with TLS/SSL or SASL support (by default if the OpenSSL
346 SSL and crypto libraries or the Cyrus SASL library are found at
347 configure time, otherwise see the --with-openssl and --with-sasl
348 flags passed to configure).
349 perl_access:
351 A path to a perl script for dynamically generating an access group.
352 If an auth group matches successfully and contains a perl_access
353 parameter, then the argument perl script will be used to create an
354 access group. This group will then determine the access rights of
355 the client, overriding any access groups in readers.conf. If and
356 only if a sucessful auth group contains the perl_access parameter,
357 readers.conf access groups are ignored and the client's rights are
358 instead determined dynamically. This parameter is only valid if
359 INN is compiled with Perl support (--with-perl passed to
360 configure). More information may be found in the file
361 doc/hook-perl.
362 python_access:
364 A Python script for dynamically generating an access group. If an
365 auth group matches successfully and contains a python_access
366 parameter, then the argument script (without its ".py" extension)
367 will be used to create an access group. This group will then
368 determine the access rights of the client, overriding any access
369 groups in readers.conf. If and only if a successful auth group
370 contains the python_access parameter, readers.conf access groups
371 are ignored and the client's rights are instead determined
372 dynamically. This parameter is only valid if INN is compiled with
373 Python support (--with-python passed to configure). More
374 information may be found in the file doc/hook-python.
375 python_dynamic:
377 A Python script for applying access control dynamically on a per
378 newsgroup basis. If an auth group matches successfully and
379 contains a python_dynamic parameter, then the argument script
380 (without its ".py" extension) will be used to determine the clients
381 rights each time the user attempts to view a newsgroup, or read or
382 post an article. Access rights as determined by python_dynamic
383 override the values of access group parameters such as newsgroups,
384 read and post. This parameter is only valid if INN is compiled
385 with Python support (--with-python passed to configure). More
386 information may be found in the file doc/hook-python.
387
389 users:
390 The privileges given by this access group apply to any user
391 identity which matches this comma-separated list of wildmat
392 patterns. If this parameter isn't given, the access group applies
393 to all users (and is essentially equivalent to "users: *").
394 newsgroups:
396 Users that match this access group are allowed to read and post to
397 all newsgroups matching this comma-separated list of wildmat
398 patterns. The empty string is equivalent to "newsgroups: *"; if
399 this parameter is missing, the connection will be rejected (unless
400 read: and/or post: are used instead, see below).
401 read:
403 Like the newsgroups: parameter, but the client is only given
404 permission to read the matching newsgroups. This parameter is
405 often used with post: (below) to specify some read-only groups; it
406 cannot be used in the same access group with a newsgroups:
407 parameter. (If read: is used and post: is missing, the client will
408 have only read-only access.)
409 post:
411 Like the newsgroups: parameter, but the client is only given
412 permission to post to the matching newsgroups. This parameter is
413 often used with read: (above) to define the patterns for reading
414 and posting separately (usually to give the user permission to read
415 more newsgroups than they're permitted to post to). It cannot be
416 used in the same access group with a newsgroups: parameter.
417 access:
419 A set of letters specifying the permissions granted to the client.
420 The letters are chosen from the following set:
421 R The client may read articles.
423 P The client may post articles.
425 I The client may inject articles with IHAVE. Note that in order
427 to inject articles with the IHAVE command, the user must also
428 have POST permission (the "P" option). Articles injected with
429 IHAVE are treated as though they were injected with POST, that
430 is to say such articles must not have been previously injected
431 (they must not contain headers like Injection-Info:).
432 A The client may post articles with Approved: headers (in other
434 words, may approve articles for moderated newsgroups). By
435 default, this is not allowed.
436 N The client may use the NEWNEWS command, overriding the global
438 setting.
439 L The client may post to newsgroups that are set to disallow local
441 posting (status fields "j", "n" and "x" in the active(5) file).
442 Note that if this parameter is given, allownewnews in inn.conf is
444 ignored for connections matching this access group and the ability
445 of the client to use NEWNEWS is entirely determined by the presence
446 of "N" in the access string. If you want to support NEWNEWS, make
447 sure to include "N" in the access string when you use this
448 parameter.
449 Note that if this parameter is given and "R" isn't present in the
451 access string, the client cannot read regardless of newsgroups: or
452 read: parameters. Similarly, if this parameter is given and "P"
453 isn't present, the client cannot post. This use of access: is
454 deprecated and confusing; it's strongly recommended that if the
455 access: parameter is used, "R" and "P" always be included in the
456 access string and newsgroups:, read:, and post: be used to control
457 access. (To grant read access but no posting access, one can have
458 just a read: parameter and no post: parameter.)
459 key:
461 If this parameter is present, this access group is only considered
462 when finding privileges for users matching auth groups with this
463 same key: parameter.
464 reject_with:
466 If this parameter is present, a client matching this block will be
467 disconnected with a "Permission denied" message containing the
468 contents (a "reason" string) of this parameter. Some newsreaders
469 will then display the reason to the user.
470 max_rate:
472 If this parameter is present (and nonzero), it is used for nnrpd's
473 rate-limiting code. The client will only be able to download at
474 this speed (in bytes/second). Note that if an encryption layer is
475 being used, limiting is applied to the pre-encryption datastream.
476 localtime:
478 If a Date: or an Injection-Date: header field is not included in a
479 posted article, nnrpd(8) normally adds these header fields in UTC.
480 If this is set to true, the Date: header field will be formatted in
481 local time instead. (The Injection-Date: header field is added
482 according to the behaviour of the addinjectiondate parameter in
483 inn.conf, and will remain in UTC, though.) This is a boolean value
484 and the default is false.
485 This parameter permits handling a relatively unusual corner case.
487 It is mostly a tool for people who want to disclose their local
488 time zone (it can be useful information in certain types of
489 discussions), but whose clients don't for some reason, and who can
490 arrange for the server to be in the same time zone as the client.
491 newsmaster:
493 Used as the contact address in the help message returned by
494 nnrpd(8), if the virtualhost: parameter is set to true.
495 strippath:
497 If set to true, any Path: header provided by a user in a post is
498 stripped rather than used as the beginning of the Path: header of
499 the article. This is a boolean value and the default is false.
500 perlfilter:
502 If set to false, posts made by these users do not pass through the
503 Perl filter even if it is otherwise enabled. This is a boolean
504 value and the default is true.
505 pythonfilter:
507 If set to false, posts made by these users do not pass through the
508 Python filter even if it is otherwise enabled. This is a boolean
509 value and the default is true.
510 virtualhost:
512 Set this parameter to true in order to make nnrpd behave as if it
513 is running on a server with a different name than it actually is.
514 If you set this parameter to true, you must also set either
515 pathhost: or domain: in the relevant access group in readers.conf
516 to something different than is set in inn.conf. All articles
517 displayed to clients will then have their Path: and Xref: headers
518 altered to appear to be from the server named in pathhost: or
519 domain: (whichever is set), and posted articles will use that
520 server name in the Path:, Message-ID:, and Injection-Info: headers.
521 Note that setting this parameter requires the server modify all
523 posts before presenting them to the client and therefore may
524 decrease performance slightly.
525 In addition, all of the following parameters are valid in access groups
527 and override the global setting in inn.conf. See inn.conf(5) for the
528 descriptions of these parameters:
529 addinjectiondate, addinjectionpostingaccount, addinjectionpostinghost,
531 backoff_auth, backoff_db, backoff_k, backoff_postfast, backoff_postslow,
532 backoff_trigger, checkincludedtext, clienttimeout, complaints, domain,
533 fromhost, localmaxartsize, moderatormailer, nnrpdauthsender, nnrpdcheckart,
534 nnrpdoverstats, nnrpdposthost, nnrpdpostport, organization, pathhost,
535 readertrack, spoolfirst, strippostcc.
536
538 Here's a basic summary of what happens when a client connects:
539 · All auth groups are scanned and the ones that don't match the client
541 (due to hosts, localaddress, require_ssl, etc.) are eliminated.
542 · The remaining auth groups are scanned from the last to the first, and
544 an attempt is made to apply it to the current connection. This means
545 running res: programs, if any, and otherwise applying default:. The
546 first auth group (starting from the bottom) to return a valid user is
547 kept as the active auth group.
548 · If no auth groups yield a valid user (none have default: parameters
550 or successful res: programs) but some of the auth groups have auth:
551 lines (indicating a possibility that the user can authenticate and
552 then obtain permissions), the connection is considered to have no
553 valid auth group (which means that the access groups are ignored
554 completely) but the connection isn't closed. Instead, 480 is
555 returned for everything until the user authenticates.
556 · When the user authenticates, the auth groups are rescanned, and only
558 the matching ones which contain at least one auth, perl_auth, or
559 python_auth line are considered. These auth groups are scanned from
560 the last to the first, running auth: programs and perl_auth: or
561 python_auth: scripts. The first auth group (starting from the
562 bottom) to return a valid user is kept as the active auth group.
563 · Regardless of how an auth group is established, as soon as one is,
565 that auth group is used to assign a user identity by taking the
566 result of the successful res, auth, perl_auth, or python_auth line
567 (or the default: if necessary), and appending the default-domain if
568 necessary. (If the perl_access: or python_access: parameter is
569 present, see below.)
570 · Finally, an access group is selected by scanning the access groups
572 from bottom up and finding the first match. (If the established auth
573 group contained a perl_access: or python_access line, the dynamically
574 generated access group returned by the script is used instead.) User
575 permissions are granted based on the established access group.
576
578 Probably the simplest useful example of a complete readers.conf, this
579 gives permissions to read and post to all groups to any connections
580 from the "example.com" domain, and no privileges for anyone connecting
581 elsewhere:
582 auth example.com {
584 hosts: "*.example.com, example.com"
585 default: "<EXAMPLE>"
586 }
587 access full {
589 users: "<EXAMPLE>"
590 newsgroups: *
591 }
592 Note that the above access realm could also be written without the
594 users: key, in which case it applies to any user identity (though in
595 this example, the user identity that will be assigned to all matching
596 connections is "<EXAMPLE>"). It is however recommended to keep an
597 explicit users: key so as to better view to whom the access block
598 applies.
599 As the only available auth realm only matches hosts in the
601 "example.com" domain, any connections from other hosts will be rejected
602 immediately.
603 If you have some systems that should only have read-only access to the
605 server, you can modify the example above slightly by adding an
606 additional auth and access group:
607 auth lab {
609 hosts: "*.lab.example.com"
610 default: <LAB>
611 }
612 access lab {
614 users: <LAB>
615 read: *
616 }
617 If those are put in the file after the above example, they'll take
619 precedence (because they're later in the file) for any user coming from
620 a machine in the lab.example.com domain, everyone will only have read
621 access, not posting access.
622 Here's a similar example for a news server that accepts connections
624 from anywhere but requires the user to specify a username and password.
625 The username and password are first checked against an external
626 database of usernames and passwords, and then against the system shadow
627 password file:
628 auth all {
630 auth: "ckpasswd -d <pathdb in inn.conf>/newsusers"
631 auth: "ckpasswd -s"
632 }
633 access full {
635 users: *
636 newsgroups: *
637 }
638 When the user first connects, there are no res: keys and no default, so
640 they don't receive any valid identity and the connection won't match
641 any access groups (even ones with "users: *"). Such users receive
642 nothing but authentication-required responses from nnrpd until they
643 authenticate.
644 If they then later authenticate, the username and password are checked
646 first by running ckpasswd with the -d option for an external dbm file
647 of encrypted passwords, and then with the -s option to check the shadow
648 password database (note that this option may require ckpasswd to be
649 setgid to a shadow group, and there are security considerations; see
650 ckpasswd(8) for details). If both of those fail, the user will
651 continue to have no identity; otherwise, an identity will be assigned
652 (usually the supplied username, perhaps with a domain appended,
653 although an authenticator technically can provide a completely
654 different username for the identity), and the access group will match,
655 giving full access.
656 It may be educational to consider how to combine the above examples;
658 general groups always go first. The order of the auth groups actually
659 doesn't matter, since the "hosts: example.com" one only matches
660 connections before username/password is sent, and the "auth: ckpasswd"
661 one only matches after; order would matter if either group applied to
662 both cases. The order of the access groups in this case does matter,
663 provided the newsgroups: lines differ; the access group with no users:
664 line needs to be first, with the "users: <LOCAL>" group after.
665 Here's an example of another common case: a server that only allows
667 connections from a local domain and has an additional hierarchy that's
668 password-restricted.
669 auth "example.com" {
671 hosts: "*.example.com"
672 auth: "ckpasswd -d <pathdb in inn.conf>/newsusers"
673 default: "anonymous"
674 }
675 access regular {
677 newsgroups: "*,!example.restricted.*"
678 }
679 access full {
681 users: "*,!anonymous"
682 newsgroups: *
683 }
684 In this example, unauthenticated users get the identity "anonymous",
686 which matches only the first access group and hence doesn't get access
687 to the example.restricted.* hierarchy. Anyone who authenticates using
688 a password in the newsusers file gets full access to all groups.
689 However, note that the only authentication block is limited to
690 hostnames in the example.com domain; connections outside of that domain
691 will never be allowed access or an opportunity to authenticate.
692 Here's a very complicated example. This is for an organization that
694 has an internal hierarchy "example.*" only available to local shell
695 users, who are on machines where identd can be trusted. Dialup users
696 must provide a username and password, which is then checked against
697 RADIUS. Remote users have to use a username and password that's
698 checked against a database on the news server. Finally, the admin
699 staff (users "joe" and "jane") can post anywhere (including the
700 "example.admin.*" groups that are read-only for everyone else), and are
701 exempted from the Perl filter. For an additional twist, posts from
702 dialup users have their Sender: header replaced by their authenticated
703 identity.
704 Since this organization has some internal moderated newsgroups, the
706 admin staff can also post messages with Approved: headers, but other
707 users cannot.
708 auth default {
710 auth: "ckpasswd -f <pathdb in inn.conf>/newsusers"
711 default: <FAIL>
712 default-domain: example.com
713 }
714 auth shell {
716 hosts: *.shell.example.com
717 res: ident
718 auth: "ckpasswd -s"
719 default: <FAIL>
720 default-domain: shell.example.com
721 }
722 auth dialup {
724 hosts: *.dialup.example.com
725 auth: radius
726 default: <FAIL>
727 default-domain: dialup.example.com
728 }
729 access shell {
731 users: *@shell.example.com
732 read: *
733 post: "*, !example.admin.*"
734 }
735 access dialup {
737 users: *@dialup.example.com
738 newsgroups: *,!example.*
739 nnrpdauthsender: true
740 }
741 access other {
743 users: "*@example.com, !<FAIL>@example.com"
744 newsgroups: *,!example.*
745 }
746 access fail {
748 users: "<FAIL>@*"
749 newsgroups: !*
750 }
751 access admin {
753 users: "joe@*,jane@*"
754 newsgroups: *
755 access: "RPA"
756 perlfilter: false
757 }
758 Note the use of different domains to separate dialup from shell users
760 easily. Another way to do that would be with key: parameters, but this
761 way provides slightly more intuitive identity strings. Note also that
762 the fail access group catches not only failing connections from
763 external users but also failed authentication of shell and dialup users
764 and dialup users before they've authenticated. The identity string
765 given for, say, dialup users before RADIUS authentication has been
766 attempted matches both the dialup access group and the fail access
767 group, since it's "<FAIL>@dialup.example.com", but the fail group is
768 last so it takes precedence.
769 The shell auth group has an auth: parameter so that users joe and jane
771 can, if they choose, use username and password authentication to gain
772 their special privileges even if they're logged on as a different user
773 on the shell machines (or if ident isn't working). When they first
774 connect, they'd have the default access for that user, but they could
775 then send AUTHINFO USER and AUTHINFO PASS in order to get their
776 extended access.
777 Also note that if the users joe and jane are using their own accounts,
779 they get their special privileges regardless of how they connect,
780 whether the dialups, the shell machines, or even externally with a
781 username and password.
782 Finally, here's a very simple example of a configuration for a public
784 server for a particular hierarchy.
785 auth default {
787 hosts: *
788 default: <PUBLIC>
789 }
790 access default {
792 users: <PUBLIC>
793 newsgroups: example.*
794 }
795 Notice that clients aren't allowed to read any other groups; this keeps
797 them from getting access to administrative groups or reading control
798 messages, just as a precaution. When running a public server like
799 this, be aware that many public hierarchies will later be pulled down
800 and reinjected into the main Usenet, so it's highly recommended that
801 you also run a Perl or Python filter to reject any messages crossposted
802 out of your local hierarchy and any messages containing a Supersedes:
803 header. This will keep messages posted to your public hierarchy from
804 hurting any of the rest of Usenet if they leak out.
805
807 In general, separate passwords should be used for NNTP wherever
808 possible; the NNTP protocol itself does not protect passwords from
809 casual interception, and many implementations (including this one) do
810 not "lock out" accounts or otherwise discourage password-guessing
811 attacks. So it is best to ensure that a compromised password has
812 minimal effects.
813 Authentication using the AUTHINFO USER/PASS commands passes unencrypted
815 over the network. Extreme caution should therefore be used especially
816 with system passwords (e.g. "auth: ckpasswd -s"). Passwords can be
817 protected by using NNTP over TLS/SSL or through ssh tunnels, and this
818 usage can be enforced by a well-considered server configuration that
819 only permits certain auth groups to be applied in certain cases. One
820 can also authenticate using a strong SASL mechanism. Here are some
821 ideas:
822 · To restrict connections on the standard NNTP port (119) to use an
824 encryption layer for some (or all) of the auth groups to match, use
825 the require_ssl parameter. Note that a client can use STARTTLS to
826 negotiate an encrypted TLS connection. A secure layer can also be
827 negotiated during authentication via AUTHINFO SASL.
828 · If you consider your local network (but not the internet) secure,
830 have some auth groups with a restrictive hosts: parameter; they
831 would go above, with ones having global applicability below.
832 · Consider running nnrpd with the -S flag (either also with -D, or
834 out of "super-server" like inetd) on the NNTPS port (563) for
835 clients that support TLS/SSL. See nnrpd(8) for more details about
836 how to configure that. You can use the require_ssl parameter or
837 the -c flag to specify an alternate readers.conf file if you want a
838 substantially different configuration for this case.
839 · If you want to restrict an auth group to only match loopback
841 connections (for users running newsreaders on localhost or
842 connecting via an ssh tunnel), use the localaddress: parameter.
843
845 Written by Aidan Cully <aidan@panix.com> for InterNetNews.
846 Substantially expanded by Russ Allbery <eagle@eyrie.org>.
847 $Id: readers.conf.pod 10283 2018-05-14 12:43:05Z iulius $
849
851 auth_krb5(8), ckpasswd(8), inn.conf(5), innd(8), newsfeeds(5),
852 nnrpd(8), uwildmat(3).
853INN 2.6.3 2018-05-14 READERS.CONF(5)