readers.conf(5) InterNetNews Documentation readers.conf(5)NAMEreaders.conf - Access control and configuration for nnrpd
DESCRIPTIONreaders.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.
There are two types of entries in readers.conf: parame
ter/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 dou
ble 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 paramenter with a value
longer than about 8,180 characters.
Many parameters take a boolean value. For all such param
eters, 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 estab
lish the identity of the user, who they are. The access
group determines, given the user's identity, what they're
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.
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.
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.
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.
For any connection from a host that matches that wildmat
expression or netblock, <res-program> (the program given
with the res: parameter, if present) is run to determine
the identity of the user just from the connection informa
tion. If it fails, or if the res: parameter isn't pre
sent, the user is assigned an identity of "<defuser>@<def
domain>"; 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 is passed to
<auth-program>, the value of the auth: parameter (if pre
sent). If this 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.
When matching auth groups, the last auth group in the file
that matches a given connection or username/password com
bination 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-wild
mat> 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 that 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 one additional special case to be aware of. When
forming particularly complex authentication and authoriza
tion rules, it is sometimes useful for the identities pro
vided 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 checked.
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.
Also note in the above 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.
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.
AUTH GROUP PARAMETERS
hosts:
A comma-separated list of remote hosts, wildmat pat
terns matching either hostnames or IP addresses, or IP
netblocks specified in CIDR notation. If a user con
nects from a host that doesn't match this parameter,
this auth group will not match the connection and is
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 assign
ing the same user identity.
All hosts match if this parameter does not exist.
res:
A command line for a user resolver. The program exe
cuted must be located in pathbin/auth/resolv. A
resolver is an authentication program which attempts
to figure out the identity of the connecting user
using nothing but the connection information (in other
words, a username and password aren't used). An exam
ples of a resolver would be a program that gets the
username from an ident callback or from the user's
hostname.
One auth group can have multiple res: parameters, and
they will be tried in the order they're listed in and
the results of the first successful one will be used.
auth:
A command line for a user authenticator. The program
executed must be located in pathbin/auth/passwd. An
authenticator is a program used to handle a user-sup
plied username and password, via a mechanism such as
AUTHINFO USER/PASS. Like with res:, one auth group
can have multiple auth: parameters; they will be tried
in order and the results of the first successful one
will be used.
default:
The default username for connections matching this
auth group. This is the username assigned to the user
at connection time if all resolvers fail or if there
are no res: parameters. Note that it can be either a
bare username, in which case default-domain: is
appended after an "@" if set, or a full identity
string containing an "@", in which case it will be
used verbatim.
default-domain:
The default domain string for this auth group. If a
user resolver or authenticator doesn't provide a
domain, or if the default username is used and it
doesn't contain a "@", this domain is used to form the
user identity. (Note that for a lot of setups, it's
not really necessary for user identities to be quali
fied with a domain name, in which case there's no need
to use this parameter.)
key:
If this parameter is present, any connection matching
this auth group will have its privileges determined
only by access groups containing a matching key param
eter.
ACCESS GROUP PARAMETERS
users:
The privileges given by this access group apply to any
user identity which matches this comma-separated list
of wildmat patterns. If this parameter isn't given,
the access group applies to all users (and is essen
tially equivalent to "users: *").
newsgroups:
Users that match this access group are allowed to read
and post to all newsgroups matching this comma-sepa
rated list of wildmat patterns.
read:
Like the newsgroups: parameter, but the client is only
given permission to read the matching newsgroups.
This parameter is often used with post: (below) and
cannot be used in the same access group with a news
groups: parameter.
post:
Like the newsgroups: parameter, but the client is only
given permission to post to the matching newsgroups.
This parameter is often used with read: (above) to
define the patterns for reading and posting separately
(usually to give the user permission to read more
newsgroups than they're permitted to post to). It
cannot be used in the same access group with a news
groups: parameter.
access:
A set of letters specifying the permissions granted to
the client. The letters are chosen from the following
set:
R The client may read articles.
P The client may post articles.
A The client may post articles with Approved: headers
(in other words, may approve articles for moderated
newsgroups). By default, this is not allowed.
N The client may use the NEWNEWS command, overriding
the global setting.
L The client may post to newsgroups that are set to
disallow local posting (mode "n" in the active(5)
file).
Note that if this parameter is given, allownewnews in
inn.conf(5) 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. Simi
larly, if this parameter is given and "P" isn't pre
sent, 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 news
groups:, 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.)
key:
If this parameter is present, this access group is
only considered when finding privileges for users
matching auth groups with this same key: parameter.
localtime:
If a Date: header is not included in a posted article,
nnrpd(8) normally adds a new Date: header in UTC. If
this is set to true, the Date: header will be format
ted in local time instead. This is a boolean value
and the default is false.
newsmaster:
Used as the contact address in the help message
returned by nnrpd(8) if the virtualhost: parameter is
set to true.
strippath:
If set to true, any Path: header provided by a user in
a post is stripped rather than used as the beginning
of the Path: header of the article. This is a boolean
value and the default is false.
perlfilter:
If set to false, posts made by these users do not pass
through the Perl filter even if it is otherwise
enabled. This is a boolean value and the default is
true.
pythonfilter:
If set to false, posts made by these users do not pass
through the Python filter even if it is otherwise
enabled. This is a boolean value and the default is
true.
virtualhost:
If set to true, nnrpd(8) will behave as if it's run
ning on a server with a different name. This affects
the Path:, Message-ID:, and X-Trace: headers of posted
articles, as well as the apparent Path: and Xref:
headers of all articles read by the client. One of
pathhost: or domain: must be set in the same access
group if this parameter is set to true, and nnrpd(8)
will act as if the server name is the value of path
host:, or domain: if pathhost: isn't set or is set to
the same value as in inn.conf(5). One of these param
eters must be set to something different than that set
in inn.conf.
In addition, all of the following parameters are valid in
access groups and override the global setting in
inn.conf(5). See inn.conf(5) for the descriptions of
these parameters: addnntppostingdate, addnntppostinghost,
backoff_auth, backoff_db, backoff_k, backoff_postfast,
backoff_postslow, backoff_trigger, checkincludedtext,
clienttimeout, complaints, domain, fromhost, localmaxart
size, moderatormailer, nnrpdauthsender, nnrpdcheckart,
nnrpdoverstats, nnrpdposthost, nnrpdpostport, organiza
tion, pathhost, readertrack, spoolfirst, and strippostcc.
SUMMARY
Here's a basic summary of what happens when a client con
nects:
All auth groups are scanned and the ones that don't
match the client IP address are eliminated.
Each remaining auth group is scanned from the last to
the first, and an attempt is made to apply it to the
current connection. This means running res: programs,
if any, and otherwise applying default:. The first auth
group to return a valid user is kept as the active auth
group.
If no auth groups yield a valid user (none have default:
parameters or successful res: programs) but some of the
auth groups have auth: lines (indicating a possibility
that the user can authenticate and then obtain permis
sions), the connection is considered to have no valid
auth group (which means that the access groups are
ignored completely) but the connection isn't closed.
Instead, 480 is returned for everything until the user
authenticates.
When the user authenticates, all auth groups with auth:
lines are then checked from the bottom up and the first
one that returns a valid user is kept as the default
auth group.
Regardless of how an auth group is established, as soon
as one is, the user permissions are granted by scanning
the access groups from bottom up and finding the first
match.
EXAMPLES
Here is 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 from anywhere
else:
auth example.com {
hosts: "*.example.com, example.com"
default: <LOCAL>
}
access full {
newsgroups: *
}
Note that the access realm has no users: key and therefore
applies to any user identity. The only available auth
realm only matches hosts in the example.com domain,
though, so 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.exam
ple.com domain, and those users 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 is
first checked against an external database of usernames
and passwords, and then against the system shadow password
file:
auth all {
auth: "ckpasswd -d /usr/local/news/db/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 authen
tication required responses from nnrpd until they authen
ticate.
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 ckpasswd may have to be setgid to a shadow
group to use this option). If both of those fail, the
user will continue to have no identity; otherwise, they
will acquire some other identity string (whatever username
they specified, since the password was valid) and the
access group will match, giving them full access.
Finally, 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 have to use 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 authenti
cated identity.
auth default {
auth: "ckpasswd -f /usr/local/news/db/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: *
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 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 iden
tity 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 pass
word 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 (or
AUTHINFO SIMPLE) and 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.
HISTORY
Written by Aidan Cully <aidan@panix.com> for InterNetNews.
Substantially expanded by Russ Allbery <rra@stanford.edu>.
$Id: readers.conf.5,v 1.5.2.8 2001/03/03 07:57:56 rra Exp
$
SEE ALSOinn.conf(5), innd(8), newsfeeds(5), nnrpd(8), wildmat(3).
2001-03-02 INN 2.3.2 readers.conf(5)
