 |
Index for
Section 5 |
|
 |
Alphabetical
listing for R |
|
 |
Bottom of
page |
|
READERS.CONF(5)
NAME
readers.conf - Access control and configuration for nnrpd
DESCRIPTION
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 ispermitted 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.
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 SSL libraries, an auth group with the require_ssl:
parameter set to true only applies if the incoming connection is using SSL.
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.
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.
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 patterns matching
either hostnames or IP addresses, or IP netblocks specified in CIDR
notation. If a user connects 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
assigning the same user identity.
All hosts match if this parameter is not given.
localaddress:
A comma-separated list of local host or address patterns with the same
syntax as the same as with the hosts: parameter. If this parameter is
specified, its auth group will only match connections made to a
matching local interface. (Obviously, this is only useful for servers
with multiple interfaces.)
All local addresses match if this parameter is not given.
res:
A simple command line for a user resolver (shell metacharacters are not
supported). If a full path is not given, the program executed must be
in the pathbin/auth/resolv directory. 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, the
user has not provided a username and password). An examples of a
resolver would be a program that assigns an identity 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. The results of the first successful
one will be used.
auth:
A simple command line for a user authenticator (shell metacharacters
are not supported). If a full path is not given, the program executed
must be located in the pathbin/auth/passwd directory. An authenticator
is a program used to handle a user-supplied 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. See also perl_auth:
below.
perl_auth:
A path to a perl script for authentication. The perl_auth: parameter
works exactly like auth:, except that it calls the named script using
the perl hook rather then an external program. Multiple/mixed use of
the auth, perl_auth, and python_auth parameters is permitted within any
auth group; each line is tried in the order it appears. perl_auth: has
more power than auth: in that it provides the authentication program
with additional information about the client and the ability to return
an error string and a username. This parameter is only valid if INN is
compiled with Perl support (--with-perl passed to configure). More
information may be found in doc/hook-perl.
python_auth:
A python script for authentication. The python_auth: parameter works
exactly like auth:, except that it calls the named script using the
python hook rather then an external program. Multiple/mixed use of the
auth, perl_auth, and python_auth parameters is permitted within any
auth group; each line is tried in the order it appears. python_auth:
has more power than auth: in that it provides the authentication
program with additional information about the client and the ability to
return an error string and a username. This parameter is only valid if
INN is compiled with Python support (--with-python passed to
configure). More information may be found in doc/hook-python.
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: (if present) is appended
after an "@", 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 qualified 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 the subset of access groups
containing a matching key parameter.
require_ssl:
If set to true, an incoming connection only matches this auth group if
it is encrypted using SSL. This parameter is only valid if INN is
compiled with SSL support (--with-openssl passed to configure).
perl_access:
A path to a perl script for dynamically generating an access group. If
an auth group matches successfully and contains a perl_access
parameter, then the argument perl script will be used to create an
access group. This group will then determine the access rights of the
client, overriding any access groups in readers.conf. If and only if a
sucessful auth group contains the perl_access parameter, readers.conf
access groups are ignored and the client's rights are instead
determined dynamically. This parameter is only valid if INN is
compiled with Perl support (--with-perl passed to configure). More
information may be found in the file doc/hook-perl.
python_access:
A python script for dynamically generating an access group. If an auth
group matches successfully and contains a python_access parameter, then
the argument script will be used to create an access group. This group
will then determine the access rights of the client, overriding any
access groups in readers.conf. If and only if a successful auth group
contains the python_access parameter, readers.conf access groups are
ignored and the client's rights are instead determined dynamically.
This parameter is only valid if INN is compiled with Python support
(--with-python passed to configure). More information may be found in
the file doc/hook-python.
python_dynamic:
A python script for applying access control dynamically on a per
newsgroup basis. If an auth group matches successfully and contains a
python_dynamic parameter, then the argument script will be used to
determine the clients rights each time the user attempts to view a
newsgroup, or read or post an article. Access rights as determined by
python_dynamic override the values of access group parameters such as
newsgroups, read, and post. This parameter is only valid if INN is
compiled with Python support (--with-python passed to configure). More
information may be found in the file doc/hook-python.
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
essentially equivalent to "users: *").
newsgroups:
Users that match this access group are allowed to read and post to all
newsgroups matching this comma-separated list of wildmat patterns. The
empty string is equivalent to "newsgroups: *"; if this parameter is
missing, the connection will be rejected (unless read: and/or post: are
used instead, see below).
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) to specify some read-only groups; it cannot be used in
the same access group with a newsgroups: parameter. (If read: is used
and post: is missing, the client will have only read-only access.)
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 newsgroups: 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.
I The client may inject articles with IHAVE. Note that in order to
inject articles with the IHAVE the user must also have POST
permission (the "P" option).
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 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.)
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.
reject_with:
If this parameter is present, a client matching this block will be
disconnected with a "Permission denied" message containing the contents
(a "reason" string) of this parameter. Some newsreaders will then
display the reason to the user.
max_rate:
If this parameter is present (and nonzero) it is used for nnrpd's
rate-limiting code. The client will only be able to download at this
speed (in bytes/second). Note that if SSL is being used, limiting is
applied to the pre-encryption datastream.
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 formatted 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:
Set this parameter to make nnrpd behave as if it's running on a server
with a different name than it actually is. If you set this parameter,
you must also set either pathhost: or domain: to something different
than is set in inn.conf. All articles displayed to clients will then
have their Path: and Xref: headers altered to appear to be from the
server named in pathhost: or domain: (whichever is set), and posted
articles will use that server name in the Path:, Message-ID;, and
X-Trace: headers.
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: addnntppostingdate, addnntppostinghost,
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, and strippostcc.
SUMMARY
Here's a basic summary of what happens when a client connects:
· All auth groups are scanned and the ones that don't match the client (due
to hosts:, localaddress:, require_ssl:, etc) are eliminated.
· The remaining auth groups are 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 (starting from the bottom) 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
permissions), 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, the auth groups are rescanned, and only the
matching ones which contain at least one auth, perl_auth, or python_auth
line are considered. These auth groups are scanned from the last to the
first, running auth: programs and perl_auth: or python_auth: scripts.
The first auth group (starting from the bottom) to return a valid user is
kept as the active auth group.
· Regardless of how an auth group is established, as soon as one is, that
auth group is used to assign a user identity by taking the result of the
successful res, auth, perl_auth, or python_auth line (or the default: if
necessary), and appending the default-domain if necessary. (If the
perl_access: or python_access: parameter is present, see below.)
· Finally, an access group is selected by scanning the access groups from
bottom up and finding the first match. (If the established auth group
contained a perl_access: or python_access line, the dynamically generated
access group returned by the script is used instead.) User permissions
are granted based on the established access group.
EXAMPLES
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: <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.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 /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
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 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 /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: *
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 (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.
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.
SECURITY CONSIDERATIONS
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 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. Here are some ideas:
· To restrict connections on the standard nntp port (119) to use SSL for
some (or all) of the auth groups to match, use the require_ssl:
parameter.
· If you consider your local network (but not the internet) secure, have
some auth groups with a restrictive hosts: parameter; they would go
above, with ones having global applicability below.
· Consider running a "nnrpd -S" (with "-D", or out of "super-server" like
inetd) on the nntps port (563) for clients that support SSL. You can
use the require_ssl: parameter, or "-c" to specify an alternate
readers.conf if you want a substantially different configuration for
this case.
· If you want to restrict an auth group to only match loopback
connections (for users running newsreaders on localhost or connecting
via an ssh tunnel), use the localaddress: parameter.
HISTORY
Written by Aidan Cully <aidan@panix.com> for InterNetNews. Substantially
expanded by Russ Allbery <rra@stanford.edu>.
$Id: readers.conf.5,v 1.32.2.2 2003/09/08 04:31:57 rra Exp $
SEE ALSO
inn.conf(5), innd(8), newsfeeds(5), nnrpd(8), uwildmat(3).
|
Index for
Section 5 |
|
|
Alphabetical
listing for R |
|
 |
Top of
page |
|