+++ /dev/null
-.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
-.\"
-.\" Standard preamble:
-.\" ========================================================================
-.de Sh \" Subsection heading
-.br
-.if t .Sp
-.ne 5
-.PP
-\fB\\$1\fR
-.PP
-..
-.de Sp \" Vertical space (when we can't use .PP)
-.if t .sp .5v
-.if n .sp
-..
-.de Vb \" Begin verbatim text
-.ft CW
-.nf
-.ne \\$1
-..
-.de Ve \" End verbatim text
-.ft R
-.fi
-..
-.\" Set up some character translations and predefined strings. \*(-- will
-.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
-.\" double quote, and \*(R" will give a right double quote. \*(C+ will
-.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
-.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
-.\" nothing in troff, for use with C<>.
-.tr \(*W-
-.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
-.ie n \{\
-. ds -- \(*W-
-. ds PI pi
-. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
-. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
-. ds L" ""
-. ds R" ""
-. ds C` ""
-. ds C' ""
-'br\}
-.el\{\
-. ds -- \|\(em\|
-. ds PI \(*p
-. ds L" ``
-. ds R" ''
-'br\}
-.\"
-.\" If the F register is turned on, we'll generate index entries on stderr for
-.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
-.\" entries marked with X<> in POD. Of course, you'll have to process the
-.\" output yourself in some meaningful fashion.
-.if \nF \{\
-. de IX
-. tm Index:\\$1\t\\n%\t"\\$2"
-..
-. nr % 0
-. rr F
-.\}
-.\"
-.\" For nroff, turn off justification. Always turn off hyphenation; it makes
-.\" way too many mistakes in technical documents.
-.hy 0
-.if n .na
-.\"
-.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
-.\" Fear. Run. Save yourself. No user-serviceable parts.
-. \" fudge factors for nroff and troff
-.if n \{\
-. ds #H 0
-. ds #V .8m
-. ds #F .3m
-. ds #[ \f1
-. ds #] \fP
-.\}
-.if t \{\
-. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
-. ds #V .6m
-. ds #F 0
-. ds #[ \&
-. ds #] \&
-.\}
-. \" simple accents for nroff and troff
-.if n \{\
-. ds ' \&
-. ds ` \&
-. ds ^ \&
-. ds , \&
-. ds ~ ~
-. ds /
-.\}
-.if t \{\
-. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
-. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
-. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
-. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
-. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
-. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
-.\}
-. \" troff and (daisy-wheel) nroff accents
-.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
-.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
-.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
-.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
-.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
-.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
-.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
-.ds ae a\h'-(\w'a'u*4/10)'e
-.ds Ae A\h'-(\w'A'u*4/10)'E
-. \" corrections for vroff
-.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
-.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
-. \" for low resolution devices (crt and lpr)
-.if \n(.H>23 .if \n(.V>19 \
-\{\
-. ds : e
-. ds 8 ss
-. ds o a
-. ds d- d\h'-1'\(ga
-. ds D- D\h'-1'\(hy
-. ds th \o'bp'
-. ds Th \o'LP'
-. ds ae ae
-. ds Ae AE
-.\}
-.rm #[ #] #H #V #F C
-.\" ========================================================================
-.\"
-.IX Title "READERS.CONF 5"
-.TH READERS.CONF 5 "2008-06-22" "INN 2.4.5" "InterNetNews Documentation"
-.SH "NAME"
-readers.conf \- Access control and configuration for nnrpd
-.SH "DESCRIPTION"
-.IX Header "DESCRIPTION"
-\&\fIreaders.conf\fR in \fIpathetc\fR specifies access control for \fInnrpd\fR\|(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 \fBnnrpd\fR may have to be restarted if you use
-the \fB\-D\fR option. (The location \fIpathetc\fR/readers.conf is only the
-default; the same format applies to any file specified with \f(CW\*(C`nnrpd \-c\*(C'\fR.)
-.PP
-There are two types of entries in \fIreaders.conf\fR: parameter/value pairs
-and configuration groups. Blank lines and anything after a number sign
-(\f(CW\*(C`#\*(C'\fR) are ignored, unless the character \f(CW\*(C`#\*(C'\fR is escaped with \f(CW\*(C`\e\*(C'\fR. The
-maximum number of characters on each line is 8,191.
-.PP
-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, \f(CW\*(C`#\*(C'\fR, and
-whitespace. An example:
-.PP
-.Vb 1
-\& hosts: *.example.com
-.Ve
-.PP
-Values that contain whitespace should be quoted with double quotes, as in:
-.PP
-.Vb 1
-\& hosts: "*.example.com, *.example.net"
-.Ve
-.PP
-If the parameter does not contain whitespace, such as:
-.PP
-.Vb 1
-\& hosts: *.example.com,*.example.net
-.Ve
-.PP
-it's not necessary to quote it, although you may wish to anyway for
-clarity.
-.PP
-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.
-.PP
-Many parameters take a boolean value. For all such parameters, the value
-may be specified as \f(CW\*(C`true\*(C'\fR, \f(CW\*(C`yes\*(C'\fR, or \f(CW\*(C`on\*(C'\fR to turn it on and may be any
-of \f(CW\*(C`false\*(C'\fR, \f(CW\*(C`no\*(C'\fR, or \f(CW\*(C`off\*(C'\fR to turn it off. The case of these values is
-not significant.
-.PP
-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 \fIreaders.conf\fR 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 \fInot\fR intermingling auth
-groups and access groups in the config file; it is often more sensible (in
-the absence of the \fIkey\fR parameter) to put all of the auth groups first,
-and all of the access groups below.
-.PP
-A user identity, as established by an auth group, looks like an e\-mail
-address; in other words, it's in the form \*(L"<username>@<domain>\*(R" (or
-sometimes just \*(L"<username>\*(R" if no domain is specified.
-.PP
-If \fInnrpdauthsender\fR is set in \fIinn.conf\fR, the user identity is also put
-into the Sender: header of posts made by that user. See the documentation
-of that option in \fIinn.conf\fR\|(5) for more details.
-.PP
-An auth group definition looks like:
-.PP
-.Vb 8
-\& auth <name> {
-\& hosts: <host\-wildmat>
-\& auth: <auth\-program>
-\& res: <res\-program>
-\& default: <defuser>
-\& default\-domain: <defdomain>
-\& # ...possibly other settings
-\& }
-.Ve
-.PP
-The <name> is used as a label for the group and is only for documentation
-purposes. (If your syslog configuration records the \f(CW\*(C`news.debug\*(C'\fR
-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.)
-.PP
-A given auth group applies only to hosts whose name or \s-1IP\s0 address matches
-the wildmat expression given with the hosts: parameter (comma\-separated
-wildmat expressions allowed, but \f(CW\*(C`@\*(C'\fR is not supported). Rather than
-wildmat expressions, you may also use \s-1CIDR\s0 notation to match any \s-1IP\s0
-address in a netblock; for example, \*(L"10.10.10.0/24\*(R" will match any \s-1IP\s0
-address between 10.10.10.0 and 10.10.10.255 inclusive.
-.PP
-If compiled against the \s-1SSL\s0 libraries, an auth group with the require_ssl:
-parameter set to true only applies if the incoming connection is using
-\&\s-1SSL\s0.
-.PP
-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 \*(L"<defuser>@<defdomain>\*(R"; 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.
-.PP
-If the user later authenticates via the \s-1AUTHINFO\s0 \s-1USER/PASS\s0 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 \fBckpasswd\fR, which supports several ways of checking passwords
-including using \s-1PAM\s0. See the \fIckpasswd\fR\|(8) man page for more details.
-.PP
-When matching auth groups, the last auth group in the file that matches a
-given connection and username/password combination is used.
-.PP
-An access group definition usually looks like:
-.PP
-.Vb 5
-\& access <name> {
-\& users: <identity\-wildmat>
-\& newsgroups: <group\-wildmat>
-\& # ...possibly other settings
-\& }
-.Ve
-.PP
-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 \f(CW\*(C`@\*(C'\fR is not supported). Alternately, you can
-use the form:
-.PP
-.Vb 5
-\& access <name> {
-\& users: <identity\-wildmat>
-\& read: <read\-wildmat>
-\& post: <post\-wildmat>
-\& }
-.Ve
-.PP
-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 \fIinn.conf\fR\|(5) parameters for just a particular group of users.
-.PP
-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.
-.PP
-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:
-.PP
-.Vb 5
-\& auth example {
-\& key: special
-\& hosts: *.example.com
-\& default: <SPECIAL>
-\& }
-.Ve
-.PP
-.Vb 5
-\& access example {
-\& key: special
-\& users: <SPECIAL>
-\& newsgroups: *
-\& }
-.Ve
-.PP
-In this case, the two key: parameters bind this auth group with this
-access group. For any incoming connection matching \*(L"*.example.com\*(R"
-(assuming there isn't any later auth group that also matches such hosts),
-no access group that doesn't have \*(L"key: special\*(R" will even be considered.
-Similarly, the above access group will only be checked if the user was
-authenticated with an auth group containing \*(L"key: special\*(R". This
-mechanism normally isn't useful; there is almost always a better way to
-achieve the same result.
-.PP
-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 \*(L"<\s-1SPECIAL\s0>\*(R". Note that some additional
-add-ons to \s-1INN\s0 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.
-.PP
-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.
-.SH "AUTH GROUP PARAMETERS"
-.IX Header "AUTH GROUP PARAMETERS"
-An access 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).
-.IP "\fBhosts:\fR" 4
-.IX Item "hosts:"
-A comma-separated list of remote hosts, wildmat patterns matching either
-hostnames or \s-1IP\s0 addresses, or \s-1IP\s0 netblocks specified in \s-1CIDR\s0 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.
-.Sp
-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.
-.Sp
-All hosts match if this parameter is not given.
-.IP "\fBlocaladdress:\fR" 4
-.IX Item "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.)
-.Sp
-All local addresses match if this parameter is not given.
-.IP "\fBres:\fR" 4
-.IX Item "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 \fIpathbin\fR/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.
-.Sp
-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.
-.IP "\fBauth:\fR" 4
-.IX Item "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 \fIpathbin\fR/auth/passwd directory. An authenticator is a
-program used to handle a user-supplied username and password, via a
-mechanism such as \s-1AUTHINFO\s0 \s-1USER/PASS\s0. 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.
-.Sp
-The most common authenticator to use is \fIckpasswd\fR\|(8); see its man page for
-more information.
-.IP "\fBperl_auth:\fR" 4
-.IX Item "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 \s-1INN\s0 is compiled with Perl support (\fB\-\-with\-perl\fR passed to
-configure). More information may be found in \fIdoc/hook\-perl\fR.
-.IP "\fBpython_auth:\fR" 4
-.IX Item "python_auth:"
-A Python script for authentication. The \fIpython_auth\fR parameter works
-exactly like \fIauth\fR, except that it calls the named script (without its
-\&\f(CW\*(C`.py\*(C'\fR extension) using the Python hook rather then an external program.
-Multiple/mixed use of the \fIauth\fR, \fIperl_auth\fR, and \fIpython_auth\fR
-parameters is permitted within any auth group; each line is tried
-in the order it appears. \fIpython_auth\fR has more power than \fIauth\fR
-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 \s-1INN\s0 is compiled with Python support
-(\fB\-\-with\-python\fR passed to \fBconfigure\fR). More information may be
-found in \fIdoc/hook\-python\fR.
-.IP "\fBdefault:\fR" 4
-.IX Item "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 \f(CW\*(C`@\*(C'\fR, or a full identity string containing an \f(CW\*(C`@\*(C'\fR, in which case it
-will be used verbatim.
-.IP "\fBdefault\-domain:\fR" 4
-.IX Item "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 \f(CW\*(C`@\*(C'\fR, 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.)
-.IP "\fBkey:\fR" 4
-.IX Item "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.
-.IP "\fBrequire_ssl:\fR" 4
-.IX Item "require_ssl:"
-If set to true, an incoming connection only matches this auth group if
-it is encrypted using \s-1SSL\s0. This parameter is only valid if \s-1INN\s0 is
-compiled with \s-1SSL\s0 support (\fB\-\-with\-openssl\fR passed to configure).
-.IP "\fBperl_access:\fR" 4
-.IX Item "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 \fIreaders.conf\fR. If and only if a
-sucessful auth group contains the perl_access parameter, \fIreaders.conf\fR
-access groups are ignored and the client's rights are instead determined
-dynamically. This parameter is only valid if \s-1INN\s0 is compiled with Perl
-support (\fB\-\-with\-perl\fR passed to configure). More information may be
-found in the file \fIdoc/hook\-perl\fR.
-.IP "\fBpython_access:\fR" 4
-.IX Item "python_access:"
-A Python script for dynamically generating an access group. If
-an auth group matches successfully and contains a \fIpython_access\fR parameter,
-then the argument script (without its \f(CW\*(C`.py\*(C'\fR extension) will be used to
-create an access group. This group will then determine the access rights
-of the client, overriding any access groups in \fIreaders.conf\fR. If and only
-if a successful auth group contains the \fIpython_access\fR parameter, \fIreaders.conf\fR
-access groups are ignored and the client's rights are instead determined
-dynamically. This parameter is only valid if \s-1INN\s0 is compiled with Python
-support (\fB\-\-with\-python\fR passed to \fBconfigure\fR). More information may be
-found in the file \fIdoc/hook\-python\fR.
-.IP "\fBpython_dynamic:\fR" 4
-.IX Item "python_dynamic:"
-A Python script for applying access control dynamically on a per newsgroup
-basis. If an auth group matches successfully and contains a
-\&\fIpython_dynamic\fR parameter, then the argument script (without its
-\&\f(CW\*(C`.py\*(C'\fR extension) 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 \fIpython_dynamic\fR override the values of access
-group parameters such as \fInewsgroups\fR, \fIread\fR and \fIpost\fR. This parameter
-is only valid if \s-1INN\s0 is compiled with Python support (\fB\-\-with\-python\fR
-passed to \fBconfigure\fR). More information may be found in the file
-\&\fIdoc/hook\-python\fR.
-.SH "ACCESS GROUP PARAMETERS"
-.IX Header "ACCESS GROUP PARAMETERS"
-.IP "\fBusers:\fR" 4
-.IX Item "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 \f(CW\*(C`users: *\*(C'\fR).
-.IP "\fBnewsgroups:\fR" 4
-.IX Item "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 \f(CW\*(C`newsgroups: *\*(C'\fR; if this parameter is
-missing, the connection will be rejected (unless read: and/or post: are
-used instead, see below).
-.IP "\fBread:\fR" 4
-.IX Item "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.)
-.IP "\fBpost:\fR" 4
-.IX Item "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.
-.IP "\fBaccess:\fR" 4
-.IX Item "access:"
-A set of letters specifying the permissions granted to the client. The
-letters are chosen from the following set:
-.RS 4
-.IP "R" 3
-.IX Item "R"
-The client may read articles.
-.IP "P" 3
-.IX Item "P"
-The client may post articles.
-.IP "I" 3
-.IX Item "I"
-The client may inject articles with \s-1IHAVE\s0. Note that in order to
-inject articles with the \s-1IHAVE\s0 the user must also have \s-1POST\s0 permission
-(the \f(CW\*(C`P\*(C'\fR option).
-.IP "A" 3
-.IX Item "A"
-The client may post articles with Approved: headers (in other words, may
-approve articles for moderated newsgroups). By default, this is not
-allowed.
-.IP "N" 3
-.IX Item "N"
-The client may use the \s-1NEWNEWS\s0 command, overriding the global setting.
-.IP "L" 3
-.IX Item "L"
-The client may post to newsgroups that are set to disallow local posting
-(mode \f(CW\*(C`n\*(C'\fR in the \fIactive\fR\|(5) file).
-.RE
-.RS 4
-.Sp
-Note that if this parameter is given, \fIallownewnews\fR in \fIinn.conf\fR is
-ignored for connections matching this access group and the ability of the
-client to use \s-1NEWNEWS\s0 is entirely determined by the presence of \f(CW\*(C`N\*(C'\fR in
-the access string. If you want to support \s-1NEWNEWS\s0, make sure to include
-\&\f(CW\*(C`N\*(C'\fR in the access string when you use this parameter.
-.Sp
-Note that if this parameter is given and \f(CW\*(C`R\*(C'\fR isn't present in the access
-string, the client cannot read regardless of newsgroups: or read:
-parameters. Similarly, if this parameter is given and \f(CW\*(C`P\*(C'\fR 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, \f(CW\*(C`R\*(C'\fR and
-\&\f(CW\*(C`P\*(C'\fR 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.)
-.RE
-.IP "\fBkey:\fR" 4
-.IX Item "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.
-.IP "\fBreject_with:\fR" 4
-.IX Item "reject_with:"
-If this parameter is present, a client matching this block will be
-disconnected with a \*(L"Permission denied\*(R" message containing the contents
-(a \*(L"reason\*(R" string) of this parameter. Some newsreaders will then
-display the reason to the user.
-.IP "\fBmax_rate:\fR" 4
-.IX Item "max_rate:"
-If this parameter is present (and nonzero), it is used for \fBnnrpd\fR's
-rate-limiting code. The client will only be able to download at this
-speed (in bytes/second). Note that if \s-1SSL\s0 is being used, limiting
-is applied to the pre-encryption datastream.
-.IP "\fBlocaltime:\fR" 4
-.IX Item "localtime:"
-If a Date: header is not included in a posted article, \fInnrpd\fR\|(8) normally
-adds a new Date: header in \s-1UTC\s0. 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.
-.IP "\fBnewsmaster:\fR" 4
-.IX Item "newsmaster:"
-Used as the contact address in the help message returned by \fInnrpd\fR\|(8), if
-the virtualhost: parameter is set to true.
-.IP "\fBstrippath:\fR" 4
-.IX Item "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.
-.IP "\fBperlfilter:\fR" 4
-.IX Item "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.
-.IP "\fBpythonfilter:\fR" 4
-.IX Item "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.
-.IP "\fBvirtualhost:\fR" 4
-.IX Item "virtualhost:"
-Set this parameter to true in order to make \fBnnrpd\fR behave as if it is
-running on a server with a different name than it actually is. If you
-set this parameter to true, you must also set either pathhost: or domain:
-in the relevant access group in \fIreaders.conf\fR to something different
-than is set in \fIinn.conf\fR. 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.
-.Sp
-Note that setting this parameter requires the server modify all posts
-before presenting them to the client and therefore may decrease
-performance slightly.
-.PP
-In addition, all of the following parameters are valid in access groups
-and override the global setting in \fIinn.conf\fR. See \fIinn.conf\fR\|(5) for the
-descriptions of these parameters:
-.PP
-.Vb 6
-\& 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, strippostcc.
-.Ve
-.SH "SUMMARY"
-.IX Header "SUMMARY"
-Here's a basic summary of what happens when a client connects:
-.IP "\(bu" 2
-All auth groups are scanned and the ones that don't match the client
-(due to hosts:, localaddress:, require_ssl:, etc) are eliminated.
-.IP "\(bu" 2
-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.
-.IP "\(bu" 2
-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.
-.IP "\(bu" 2
-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.
-.IP "\(bu" 2
-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.)
-.IP "\(bu" 2
-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.
-.SH "EXAMPLES"
-.IX Header "EXAMPLES"
-Probably the simplest useful example of a complete \fIreaders.conf\fR,
-this gives permissions to read and post to all groups to any connections
-from the \*(L"example.com\*(R" domain, and no privileges for anyone connecting
-elsewhere:
-.PP
-.Vb 4
-\& auth example.com {
-\& hosts: "*.example.com, example.com"
-\& default: <LOCAL>
-\& }
-.Ve
-.PP
-.Vb 3
-\& access full {
-\& newsgroups: *
-\& }
-.Ve
-.PP
-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
-\&\*(L"example.com\*(R" domain, though, so any connections from other hosts will be
-rejected immediately.
-.PP
-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:
-.PP
-.Vb 4
-\& auth lab {
-\& hosts: "*.lab.example.com"
-\& default: <LAB>
-\& }
-.Ve
-.PP
-.Vb 4
-\& access lab {
-\& users: <LAB>
-\& read: *
-\& }
-.Ve
-.PP
-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.
-.PP
-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:
-.PP
-.Vb 4
-\& auth all {
-\& auth: "ckpasswd \-d <pathdb in inn.conf>/newsusers"
-\& auth: "ckpasswd \-s"
-\& }
-.Ve
-.PP
-.Vb 4
-\& access full {
-\& users: *
-\& newsgroups: *
-\& }
-.Ve
-.PP
-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 \f(CW\*(C`users: *\*(C'\fR). Such users receive nothing
-but authentication-required responses from nnrpd until they authenticate.
-.PP
-If they then later authenticate, the username and password are checked
-first by running \fBckpasswd\fR with the \fB\-d\fR option for an external dbm
-file of encrypted passwords, and then with the \fB\-s\fR 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
-\&\fIckpasswd\fR\|(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.
-.PP
-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 \*(L"hosts: example.com\*(R" one only matches
-connections before username/password is sent, and the \*(L"auth: ckpasswd\*(R"
-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 \*(L"users: <\s-1LOCAL\s0>\*(R" group after.
-.PP
-Here's a very complicated example. This is for an organization that has
-an internal hierarchy \*(L"example.*\*(R" 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 \s-1RADIUS\s0. Remote users
-have to use a username and password that's checked against a database on
-the news server. Finally, the admin staff (users \*(L"joe\*(R" and \*(L"jane\*(R") can
-post anywhere (including the \*(L"example.admin.*\*(R" 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.
-.PP
-Since this organization has some internal moderated newsgroups, the admin
-staff can also post messages with Approved: headers, but other users
-cannot.
-.PP
-.Vb 5
-\& auth default {
-\& auth: "ckpasswd \-f <pathdb in inn.conf>/newsusers"
-\& default: <FAIL>
-\& default\-domain: example.com
-\& }
-.Ve
-.PP
-.Vb 7
-\& auth shell {
-\& hosts: *.shell.example.com
-\& res: ident
-\& auth: "ckpasswd \-s"
-\& default: <FAIL>
-\& default\-domain: shell.example.com
-\& }
-.Ve
-.PP
-.Vb 6
-\& auth dialup {
-\& hosts: *.dialup.example.com
-\& auth: radius
-\& default: <FAIL>
-\& default\-domain: dialup.example.com
-\& }
-.Ve
-.PP
-.Vb 5
-\& access shell {
-\& users: *@shell.example.com
-\& read: *
-\& post: "*, !example.admin.*"
-\& }
-.Ve
-.PP
-.Vb 5
-\& access dialup {
-\& users: *@dialup.example.com
-\& newsgroups: *,!example.*
-\& nnrpdauthsender: true
-\& }
-.Ve
-.PP
-.Vb 4
-\& access other {
-\& users: "*@example.com, !<FAIL>@example.com"
-\& newsgroups: *,!example.*
-\& }
-.Ve
-.PP
-.Vb 4
-\& access fail {
-\& users: "<FAIL>@*"
-\& newsgroups: !*
-\& }
-.Ve
-.PP
-.Vb 6
-\& access admin {
-\& users: "joe@*,jane@*"
-\& newsgroups: *
-\& access: "RPA"
-\& perlfilter: false
-\& }
-.Ve
-.PP
-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 \s-1RADIUS\s0 authentication has been attempted matches both the
-dialup access group and the fail access group, since it's
-\&\*(L"<\s-1FAIL\s0>@dialup.example.com\*(R", but the fail group is last so it takes
-precedence.
-.PP
-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
-\&\s-1AUTHINFO\s0 \s-1USER\s0 and \s-1AUTHINFO\s0 \s-1PASS\s0 (or \s-1AUTHINFO\s0 \s-1SIMPLE\s0) and get their
-extended access.
-.PP
-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.
-.PP
-Finally, here's a very simple example of a configuration for a public
-server for a particular hierarchy.
-.PP
-.Vb 4
-\& auth default {
-\& hosts: *
-\& default: <PUBLIC>
-\& }
-.Ve
-.PP
-.Vb 4
-\& access default {
-\& users: <PUBLIC>
-\& newsgroups: example.*
-\& }
-.Ve
-.PP
-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.
-.SH "SECURITY CONSIDERATIONS"
-.IX Header "SECURITY CONSIDERATIONS"
-In general, separate passwords should be used for \s-1NNTP\s0 wherever
-possible; the \s-1NNTP\s0 protocol itself does not protect passwords from
-casual interception, and many implementations (including this one) do
-not \*(L"lock out\*(R" accounts or otherwise discourage password-guessing
-attacks. So it is best to ensure that a compromised password has
-minimal effects.
-.PP
-Authentication using the \s-1AUTHINFO\s0 \s-1USER/PASS\s0 commands passes unencrypted
-over the network. Extreme caution should therefore be used especially
-with system passwords (e.g. \f(CW\*(C`auth: ckpasswd \-s\*(C'\fR). Passwords can be
-protected by using \s-1NNTP\s0 over \s-1SSL\s0 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:
-.IP "\(bu" 4
-To restrict connections on the standard nntp port (119) to use \s-1SSL\s0 for
-some (or all) of the auth groups to match, use the require_ssl:
-parameter.
-.IP "\(bu" 4
-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.
-.IP "\(bu" 4
-Consider running a \f(CW\*(C`nnrpd \-S\*(C'\fR (with \f(CW\*(C`\-D\*(C'\fR, or out of \*(L"super\-server\*(R"
-like \fBinetd\fR) on the \s-1NNTPS\s0 port (563) for clients that support \s-1SSL\s0. See
-\&\fInnrpd\fR\|(8) for more details about how to configure that. You
-can use the require_ssl: parameter, or \f(CW\*(C`\-c\*(C'\fR to specify an alternate
-\&\fIreaders.conf\fR if you want a substantially different configuration for
-this case.
-.IP "\(bu" 4
-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.
-.SH "HISTORY"
-.IX Header "HISTORY"
-Written by Aidan Cully <aidan@panix.com> for InterNetNews. Substantially
-expanded by Russ Allbery <rra@stanford.edu>.
-.PP
-$Id: readers.conf.5 7895 2008-06-22 17:54:10Z iulius $
-.SH "SEE ALSO"
-.IX Header "SEE ALSO"
-\&\fIauth_krb5\fR\|(8), \fIauth_smb\fR\|(8), \fIckpasswd\fR\|(8), \fIinn.conf\fR\|(5), \fIinnd\fR\|(8), \fInewsfeeds\fR\|(5),
-\&\fInnrpd\fR\|(8), \fIuwildmat\fR\|(3).
~ian / innduct.git / blobdiff