Unix/Linux Go Back    

RedHat 9 (Linux i386) - man page for readers.conf (redhat section 5)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)

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.

       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 char-
       acter "#" 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 pro-
       vides mechanisms to establish 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 read-
       ers.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 privi-
       leges 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 nota-
       tion to match any IP address in a netblock; for example, "" will match any IP
       address between and inclusive.

       For any connection from a host that matches that wildmat expression or netblock, <res-pro-
       gram> (the program given with the res: parameter, if present) is run to determine the
       identity of the user just from the connection information.  If it fails, 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 is passed to <auth-program>, the value of the auth: parameter (if present).
       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 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 that group of

       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 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 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

       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 iden-
       tities 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.

	   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 does not exist.

	   A command line for a user resolver.	The program executed must be located in path-
	   bin/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 examples 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.

	   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-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.

	   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.

	   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.)

	   If this parameter is present, any connection matching this auth group will have its
	   privileges determined only by access groups containing a matching key parameter.

	   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: *").

	   Users that match this access group are allowed to read and post to all newsgroups
	   matching this comma-separated list of wildmat patterns.

	   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 newsgroups: parameter.

	   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.

	   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 con-
	   nections 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 sup-
	   port NEWNEWS, make sure to include "N" in the access string when you use this parame-

	   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.)

	   If this parameter is present, this access group is only considered when finding privi-
	   leges for users matching auth groups with this same key: parameter.

	   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.

	   Used as the contact address in the help message returned by nnrpd(8) if the virtual-
	   host: parameter is set to true.

	   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.

	   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.

	   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.

	   If set to true, nnrpd(8) will behave as if it's running 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 pathhost:, or
	   domain: if pathhost: isn't set or is set to the same value as in inn.conf(5).  One of
	   these parameters 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_post-
       fast, backoff_postslow, backoff_trigger, checkincludedtext, clienttimeout, complaints,
       domain, fromhost, localmaxartsize, moderatormailer, nnrpdauthsender, nnrpdcheckart, nnrp-
       doverstats, nnrpdposthost, nnrpdpostport, organization, pathhost, readertrack, spoolfirst,
       and strippostcc.

       Here's a basic summary of what happens when a client connects:

       o All auth groups are scanned and the ones that don't match the client IP address are

       o 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.

       o 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

       o 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.

       o 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.

       Here is probably the simplest useful example of a complete readers.conf.  This gives per-
       missions 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.example.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 sys-
       tem 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 ckpasswd may have to be
       setgid to a shadow group to use this option).  If both of those fail, the user will con-
       tinue to have no identity; otherwise, they will acquire some other identity string (what-
       ever 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 authenticated 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 iden-
       tity 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 spe-
       cial privileges regardless of how they connect, whether the dialups, the shell machines,
       or even externally with a username and password.

       Written by Aidan Cully <aidan@panix.com> for InterNetNews.  Substantially expanded by Russ
       Allbery <rra@stanford.edu>.

       $Id: readers.conf.5,v 2002/12/08 19:36:02 rra Exp $

       inn.conf(5), innd(8), newsfeeds(5), nnrpd(8), wildmat(3).

INN 2.3.4				    2002-12-08				  READERS.CONF(5)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums

All times are GMT -4. The time now is 01:21 PM.