| READERS.CONF(5) | InterNetNews Documentation | READERS.CONF(5) |
readers.conf - Access control and configuration for nnrpd
readers.conf in pathetc specifies access control for nnrpd(8). It controls who is allowed to connect as a news reader and what they're allowed to do after they connect. nnrpd reads this file when it starts up. This generally means that any changes take effect immediately on all subsequent connections, but nnrpd may have to be restarted if you use the -D option. (The location pathetc/readers.conf is only the default; the same format applies to any file specified with "nnrpd -c".)
There are two types of entries in readers.conf: parameter/value pairs and configuration groups. Blank lines and anything after a number sign ("#") are ignored, unless the character "#" is escaped with "\". The maximum number of characters on each line is 8,191.
Parameter/value pairs consist of a keyword immediately followed by a colon, at least one whitespace character, and a value. The case of the parameter is significant (parameter should generally be in all lowercase), and a parameter may contain any characters except colon, "#", and whitespace. An example:
hosts: *.example.com
Values that contain whitespace should be quoted with double quotes, as in:
hosts: "*.example.com, *.example.net"
If the parameter does not contain whitespace, such as:
hosts: *.example.com,*.example.net
it's not necessary to quote it, although you may wish to anyway for clarity.
There is no way to continue a line on the next line, and therefore no way to have a single parameter with a value longer than about 8,180 characters.
Many parameters take a boolean value. For all such parameters, the value may be specified as "true", "yes", or "on" to turn it on and may be any of "false", "no", or "off" to turn it off. The case of these values is not significant.
There are two basic types of configuration groups, auth and access. The auth group provides mechanisms to establish the identity of the user, who they are. The access group determines, given the user's identity, what that user is permitted to do. Writing a readers.conf file for your setup is a two-step process: first assigning an identity to each incoming connection using auth groups, and then giving each identity appropriate privileges with access group. We recommend not intermingling auth groups and access groups in the config file; it is often more sensible (in the absence of the key parameter) to put all of the auth groups first, and all of the access groups below.
A user identity, as established by an auth group, looks like an e-mail address; in other words, it's in the form "<username>@<domain>" (or sometimes just "<username>" if no domain is specified.
If nnrpdauthsender is set in inn.conf, the user identity is also put into the Sender: header of posts made by that user. See the documentation of that option in inn.conf(5) for more details.
An auth group definition looks like:
auth <name> {
hosts: <host-wildmat>
auth: <auth-program>
res: <res-program>
default: <defuser>
default-domain: <defdomain>
# ...possibly other settings
}
The <name> is used as a label for the group and is only for documentation purposes. (If your syslog configuration records the "news.debug" facility, the <name> will appear in the debugging output of nnrpd. Examining that output can be very helpful in understanding why your configuration doesn't do what you expect it to.)
A given auth group applies only to hosts whose name or IP address matches the wildmat expression given with the hosts: parameter (comma-separated wildmat expressions allowed, but "@" is not supported). Rather than wildmat expressions, you may also use CIDR notation to match any IP address in a netblock; for example, "10.10.10.0/24" will match any IP address between 10.10.10.0 and 10.10.10.255 inclusive.
If compiled against the TLS/SSL or SASL libraries, an auth group with the require_ssl parameter set to true only applies if the incoming connection is using an encryption layer, either from the beginning if the -S flag was passed to nnrpd, or after a successful use of STARTTLS, or after a successful authentication using a SASL mechanism which negotiates an encryption layer.
For any connection from a host that matches that wildmat expression or netblock, each <res-program> (multiple res: lines may be present in a block; they are run in sequence until one succeeds), if any, is run to determine the identity of the user just from the connection information. If all the resolvers fail, or if the res: parameter isn't present, the user is assigned an identity of "<defuser>@<defdomain>"; in other words, the values of the default: and default-domain: parameters are used. If <res-program> only returns a username, <defdomain> is used as the domain.
If the user later authenticates via the AUTHINFO USER/PASS commands, the provided username and password are passed to each <auth-program> (multiple auth, perl_auth, or python_auth lines may be present in a block; they are run in sequence until one succeeds), if any. If one succeeds and returns a different identity than the one assigned at the time of the connection, it is matched against the available access groups again and the actions the user is authorized to do may change. The most common <auth-program> to use is ckpasswd, which supports several ways of checking passwords including using PAM. See the ckpasswd(8) man page for more details.
When matching auth groups, the last auth group in the file that matches a given connection and username/password combination is used.
An access group definition usually looks like:
access <name> {
users: <identity-wildmat>
newsgroups: <group-wildmat>
# ...possibly other settings
}
Again, <name> is just for documentation purposes. This says that all users whose identity matches <identity-wildmat> can read and post to all newsgroups matching <group-wildmat> (as before, comma-separated wildmat expressions are allowed, but "@" is not supported). Alternately, you can use the form:
access <name> {
users: <identity-wildmat>
read: <read-wildmat>
post: <post-wildmat>
}
and matching users will be able to read any group that matches <read-wildmat> and post to any group that matches <post-wildmat>. You can also set several other things in the access group as well as override various inn.conf(5) parameters for just a particular group of users.
Just like with auth groups, when matching access groups the last matching one in the file is used to determine the user's permissions. There is an exception to this rule: if the auth group which matched the client contains a perl_access: or python_access: parameter, then the script given as argument is used to dynamically generate an access group. This new access group is then used to determine the access rights of the client; the access groups in the file are ignored.
There is one additional special case to be aware of. When forming particularly complex authentication and authorization rules, it is sometimes useful for the identities provided by a given auth group to only apply to particular access groups; in other words, rather than checking the identity against the users: parameter of every access group, it's checked against the users: parameter of only some specific access groups. This is done with the key: parameter. For example:
auth example {
key: special
hosts: *.example.com
default: <SPECIAL>
}
access example {
key: special
users: <SPECIAL>
newsgroups: *
}
In this case, the two key: parameters bind this auth group with this access group. For any incoming connection matching "*.example.com" (assuming there isn't any later auth group that also matches such hosts), no access group that doesn't have "key: special" will even be considered. Similarly, the above access group will only be checked if the user was authenticated with an auth group containing "key: special". This mechanism normally isn't useful; there is almost always a better way to achieve the same result.
Also note in the example that there's no default-domain: parameter, which means that no domain is appended to the default username and the identity for such connections is just "<SPECIAL>". Note that some additional add-ons to INN may prefer that authenticated identities always return a full e-mail address (including a domain), so you may want to set up your system that way.
Configuration files can be included in other configuration files via the syntax:
include <filename>
The file named <filename> is then included. This syntax is allowed only at top-level.
Below is the full list of allowable parameters for auth groups and access groups, and after that are some examples that may make this somewhat clearer.
An auth group without at least one of the res:, auth:, perl_auth:, python_auth:, or default: parameters makes no sense (and in practice will just be ignored).
Note that if you have a large number of patterns that can't be merged into broader patterns (such as a large number of individual systems scattered around the net that should have access), the hosts: parameter may exceed the maximum line length of 8,192 characters. In that case, you'll need to break that auth group into multiple auth groups, each with a portion of the hosts listed in its hosts: parameter, and each assigning the same user identity.
All hosts match if this parameter is not given.
All local addresses match if this parameter is not given.
One auth group can have multiple res: parameters, and they will be tried in the order they're listed. The results of the first successful one will be used.
Alternatively, a res block can be used instead of a res: parameter. The recognized parameters in such res blocks are:
auth <auth-name> {
res: <res-program>
}
is therefore equivalent to:
auth <auth-name> {
res <res-name> {
program: <res-program>
}
}
The most common authenticator to use is ckpasswd(8); see its man page for more information.
Note that if this parameter is given, allownewnews in inn.conf is ignored for connections matching this access group and the ability of the client to use NEWNEWS is entirely determined by the presence of "N" in the access string. If you want to support NEWNEWS, make sure to include "N" in the access string when you use this parameter.
Note that if this parameter is given and "R" isn't present in the access string, the client cannot read regardless of newsgroups: or read: parameters. Similarly, if this parameter is given and "P" isn't present, the client cannot post. This use of access: is deprecated and confusing; it's strongly recommended that if the access: parameter is used, "R" and "P" always be included in the access string and newsgroups:, read:, and post: be used to control access. (To grant read access but no posting access, one can have just a read: parameter and no post: parameter.)
This parameter permits handling a relatively unusual corner case. It is mostly a tool for people who want to disclose their local time zone (it can be useful information in certain types of discussions), but whose clients don't for some reason, and who can arrange for the server to be in the same time zone as the client.
Note that setting this parameter requires the server modify all posts before presenting them to the client and therefore may decrease performance slightly.
In addition, all of the following parameters are valid in access groups and override the global setting in inn.conf. See inn.conf(5) for the descriptions of these parameters:
addinjectiondate, addinjectionpostingaccount, addinjectionpostinghost,
backoff_auth, backoff_db, backoff_k, backoff_postfast, backoff_postslow,
backoff_trigger, checkincludedtext, clienttimeout, complaints, domain,
fromhost, localmaxartsize, moderatormailer, nnrpdauthsender, nnrpdcheckart,
nnrpdoverstats, nnrpdposthost, nnrpdpostport, organization, pathhost,
readertrack, spoolfirst, strippostcc.
Here's a basic summary of what happens when a client connects:
Probably the simplest useful example of a complete readers.conf, this gives permissions to read and post to all groups to any connections from the "example.com" domain, and no privileges for anyone connecting elsewhere:
auth example.com {
hosts: "*.example.com, example.com"
default: "<EXAMPLE>"
}
access full {
users: "<EXAMPLE>"
newsgroups: *
}
Note that the above access realm could also be written without the users: key, in which case it applies to any user identity (though in this example, the user identity that will be assigned to all matching connections is "<EXAMPLE>"). It is however recommended to keep an explicit users: key so as to better view to whom the access block applies.
As the only available auth realm only matches hosts in the "example.com" domain, any connections from other hosts will be rejected immediately.
If you have some systems that should only have read-only access to the server, you can modify the example above slightly by adding an additional auth and access group:
auth lab {
hosts: "*.lab.example.com"
default: <LAB>
}
access lab {
users: <LAB>
read: *
}
If those are put in the file after the above example, they'll take precedence (because they're later in the file) for any user coming from a machine in the lab.example.com domain, everyone will only have read access, not posting access.
Here's a similar example for a news server that accepts connections from anywhere but requires the user to specify a username and password. The username and password are first checked against an external database of usernames and passwords, and then against the system shadow password file:
auth all {
auth: "ckpasswd -d <pathdb in inn.conf>/newsusers"
auth: "ckpasswd -s"
}
access full {
users: *
newsgroups: *
}
When the user first connects, there are no res: keys and no default, so they don't receive any valid identity and the connection won't match any access groups (even ones with "users: *"). Such users receive nothing but authentication-required responses from nnrpd until they authenticate.
If they then later authenticate, the username and password are checked first by running ckpasswd with the -d option for an external dbm file of encrypted passwords, and then with the -s option to check the shadow password database (note that this option may require ckpasswd to be setgid to a shadow group, and there are security considerations; see ckpasswd(8) for details). If both of those fail, the user will continue to have no identity; otherwise, an identity will be assigned (usually the supplied username, perhaps with a domain appended, although an authenticator technically can provide a completely different username for the identity), and the access group will match, giving full access.
It may be educational to consider how to combine the above examples; general groups always go first. The order of the auth groups actually doesn't matter, since the "hosts: example.com" one only matches connections before username/password is sent, and the "auth: ckpasswd" one only matches after; order would matter if either group applied to both cases. The order of the access groups in this case does matter, provided the newsgroups: lines differ; the access group with no users: line needs to be first, with the "users: <LOCAL>" group after.
Here's an example of another common case: a server that only allows connections from a local domain and has an additional hierarchy that's password-restricted.
auth "example.com" {
hosts: "*.example.com"
auth: "ckpasswd -d <pathdb in inn.conf>/newsusers"
default: "anonymous"
}
access regular {
newsgroups: "*,!example.restricted.*"
}
access full {
users: "*,!anonymous"
newsgroups: *
}
In this example, unauthenticated users get the identity "anonymous", which matches only the first access group and hence doesn't get access to the example.restricted.* hierarchy. Anyone who authenticates using a password in the newsusers file gets full access to all groups. However, note that the only authentication block is limited to hostnames in the example.com domain; connections outside of that domain will never be allowed access or an opportunity to authenticate.
Here's a very complicated example. This is for an organization that has an internal hierarchy "example.*" only available to local shell users, who are on machines where identd can be trusted. Dialup users must provide a username and password, which is then checked against RADIUS. Remote users have to use a username and password that's checked against a database on the news server. Finally, the admin staff (users "joe" and "jane") can post anywhere (including the "example.admin.*" groups that are read-only for everyone else), and are exempted from the Perl filter. For an additional twist, posts from dialup users have their Sender: header replaced by their authenticated identity.
Since this organization has some internal moderated newsgroups, the admin staff can also post messages with Approved: headers, but other users cannot.
auth default {
auth: "ckpasswd -f <pathdb in inn.conf>/newsusers"
default: <FAIL>
default-domain: example.com
}
auth shell {
hosts: *.shell.example.com
res: ident
auth: "ckpasswd -s"
default: <FAIL>
default-domain: shell.example.com
}
auth dialup {
hosts: *.dialup.example.com
auth: radius
default: <FAIL>
default-domain: dialup.example.com
}
access shell {
users: *@shell.example.com
read: *
post: "*, !example.admin.*"
}
access dialup {
users: *@dialup.example.com
newsgroups: *,!example.*
nnrpdauthsender: true
}
access other {
users: "*@example.com, !<FAIL>@example.com"
newsgroups: *,!example.*
}
access fail {
users: "<FAIL>@*"
newsgroups: !*
}
access admin {
users: "joe@*,jane@*"
newsgroups: *
access: "RPA"
perlfilter: false
}
Note the use of different domains to separate dialup from shell users easily. Another way to do that would be with key: parameters, but this way provides slightly more intuitive identity strings. Note also that the fail access group catches not only failing connections from external users but also failed authentication of shell and dialup users and dialup users before they've authenticated. The identity string given for, say, dialup users before RADIUS authentication has been attempted matches both the dialup access group and the fail access group, since it's "<FAIL>@dialup.example.com", but the fail group is last so it takes precedence.
The shell auth group has an auth: parameter so that users joe and jane can, if they choose, use username and password authentication to gain their special privileges even if they're logged on as a different user on the shell machines (or if ident isn't working). When they first connect, they'd have the default access for that user, but they could then send AUTHINFO USER and AUTHINFO PASS in order to get their extended access.
Also note that if the users joe and jane are using their own accounts, they get their special privileges regardless of how they connect, whether the dialups, the shell machines, or even externally with a username and password.
Finally, here's a very simple example of a configuration for a public server for a particular hierarchy.
auth default {
hosts: *
default: <PUBLIC>
}
access default {
users: <PUBLIC>
newsgroups: example.*
}
Notice that clients aren't allowed to read any other groups; this keeps them from getting access to administrative groups or reading control messages, just as a precaution. When running a public server like this, be aware that many public hierarchies will later be pulled down and reinjected into the main Usenet, so it's highly recommended that you also run a Perl or Python filter to reject any messages crossposted out of your local hierarchy and any messages containing a Supersedes: header. This will keep messages posted to your public hierarchy from hurting any of the rest of Usenet if they leak out.
In general, separate passwords should be used for NNTP wherever possible; the NNTP protocol itself does not protect passwords from casual interception, and many implementations (including this one) do not "lock out" accounts or otherwise discourage password-guessing attacks. So it is best to ensure that a compromised password has minimal effects.
Authentication using the AUTHINFO USER/PASS commands passes unencrypted over the network. Extreme caution should therefore be used especially with system passwords (e.g. "auth: ckpasswd -s"). Passwords can be protected by using NNTP over TLS/SSL or through ssh tunnels, and this usage can be enforced by a well-considered server configuration that only permits certain auth groups to be applied in certain cases. One can also authenticate using a strong SASL mechanism. Here are some ideas:
Written by Aidan Cully <aidan@panix.com> for InterNetNews. Substantially expanded by Russ Allbery <eagle@eyrie.org>.
$Id: readers.conf.pod 10283 2018-05-14 12:43:05Z iulius $
auth_krb5(8), ckpasswd(8), inn.conf(5), innd(8), newsfeeds(5), nnrpd(8), uwildmat(3).
| 2018-05-14 | INN 2.6.4 |