1READERS.CONF(5)           InterNetNews Documentation           READERS.CONF(5)
2
3
4

NAME

6       readers.conf - Access control and configuration for nnrpd
7

DESCRIPTION

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
18       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
23       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
29           hosts: *.example.com
30
31       Values that contain whitespace should be quoted with double quotes, as
32       in:
33
34           hosts: "*.example.com, *.example.net"
35
36       If the parameter does not contain whitespace, such as:
37
38           hosts: *.example.com,*.example.net
39
40       it's not necessary to quote it, although you may wish to anyway for
41       clarity.
42
43       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
47       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
52       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
63       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
67       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
71       An auth group definition looks like:
72
73           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
82       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
88       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
95       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
102       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
112       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
123       When matching auth groups, the last auth group in the file that matches
124       a given connection and username/password combination is used.
125
126       An access group definition usually looks like:
127
128           access <name> {
129               users: <identity-wildmat>
130               newsgroups: <group-wildmat>
131               # ...possibly other settings
132           }
133
134       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
140           access <name> {
141               users: <identity-wildmat>
142               read: <read-wildmat>
143               post: <post-wildmat>
144           }
145
146       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
152       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
160       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
168           auth example {
169               key: special
170               hosts: *.example.com
171               default: <SPECIAL>
172           }
173
174           access example {
175               key: special
176               users: <SPECIAL>
177               newsgroups: *
178           }
179
180       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
189       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
196       Configuration files can be included in other configuration files via
197       the syntax:
198
199           include <filename>
200
201       The file named <filename> is then included.  This syntax is allowed
202       only at top-level.
203
204       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

AUTH GROUP PARAMETERS

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
213       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
220           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
228           All hosts match if this parameter is not given.
229
230       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
237           All local addresses match if this parameter is not given.
238
239       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
250           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
254           Alternatively, a res block can be used instead of a res: parameter.
255           The recognized parameters in such res blocks are:
256
257           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
263           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
267                  auth <auth-name> {
268                      res: <res-program>
269                  }
270
271              is therefore equivalent to:
272
273                  auth <auth-name> {
274                      res <res-name> {
275                          program: <res-program>
276                      }
277                  }
278
279       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
289           The most common authenticator to use is ckpasswd(8); see its man
290           page for more information.
291
292       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
305       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
318       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
326       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
334       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
339       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
350       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
363       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
376       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

ACCESS GROUP PARAMETERS

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
395       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
402       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
410       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
418       access:
419           A set of letters specifying the permissions granted to the client.
420           The letters are chosen from the following set:
421
422           R  The client may read articles.
423
424           P  The client may post articles.
425
426           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
433           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
437           N  The client may use the NEWNEWS command, overriding the global
438              setting.
439
440           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
443           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
450           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
460       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
465       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
471       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
477       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
486           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
492       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
496       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
501       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
506       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
511       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
522           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
526       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
530           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

SUMMARY

538       Here's a basic summary of what happens when a client connects:
539
540       · 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
543       · 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
549       · 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
557       · 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
564       · 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
571       · 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

EXAMPLES

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
583           auth example.com {
584               hosts: "*.example.com, example.com"
585               default: "<EXAMPLE>"
586           }
587
588           access full {
589               users: "<EXAMPLE>"
590               newsgroups: *
591           }
592
593       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
600       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
604       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
608           auth lab {
609               hosts: "*.lab.example.com"
610               default: <LAB>
611           }
612
613           access lab {
614               users: <LAB>
615               read: *
616           }
617
618       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
623       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
629           auth all {
630               auth: "ckpasswd -d <pathdb in inn.conf>/newsusers"
631               auth: "ckpasswd -s"
632           }
633
634           access full {
635               users: *
636               newsgroups: *
637           }
638
639       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
645       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
657       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
666       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
670           auth "example.com" {
671               hosts: "*.example.com"
672               auth: "ckpasswd -d <pathdb in inn.conf>/newsusers"
673               default: "anonymous"
674           }
675
676           access regular {
677               newsgroups: "*,!example.restricted.*"
678           }
679
680           access full {
681               users: "*,!anonymous"
682               newsgroups: *
683           }
684
685       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
693       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
705       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
709           auth default {
710               auth: "ckpasswd -f <pathdb in inn.conf>/newsusers"
711               default: <FAIL>
712               default-domain: example.com
713           }
714
715           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
723           auth dialup {
724               hosts: *.dialup.example.com
725               auth: radius
726               default: <FAIL>
727               default-domain: dialup.example.com
728           }
729
730           access shell {
731               users: *@shell.example.com
732               read: *
733               post: "*, !example.admin.*"
734           }
735
736           access dialup {
737               users: *@dialup.example.com
738               newsgroups: *,!example.*
739               nnrpdauthsender: true
740           }
741
742           access other {
743               users: "*@example.com, !<FAIL>@example.com"
744               newsgroups: *,!example.*
745           }
746
747           access fail {
748               users: "<FAIL>@*"
749               newsgroups: !*
750           }
751
752           access admin {
753               users: "joe@*,jane@*"
754               newsgroups: *
755               access: "RPA"
756               perlfilter: false
757           }
758
759       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
770       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
778       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
783       Finally, here's a very simple example of a configuration for a public
784       server for a particular hierarchy.
785
786           auth default {
787               hosts: *
788               default: <PUBLIC>
789           }
790
791           access default {
792               users: <PUBLIC>
793               newsgroups: example.*
794           }
795
796       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

SECURITY CONSIDERATIONS

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
814       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
823       ·   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
829       ·   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
833       ·   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
840       ·   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

HISTORY

845       Written by Aidan Cully <aidan@panix.com> for InterNetNews.
846       Substantially expanded by Russ Allbery <eagle@eyrie.org>.
847
848       $Id: readers.conf.pod 10283 2018-05-14 12:43:05Z iulius $
849

SEE ALSO

851       auth_krb5(8), ckpasswd(8), inn.conf(5), innd(8), newsfeeds(5),
852       nnrpd(8), uwildmat(3).
853
854
855
856INN 2.6.3                         2018-05-14                   READERS.CONF(5)
Impressum