Expanded readers.conf documentation

[Aidan Cully]

Thank you very, very, much for taking the time to go through the code and
write this man page...  There are a few comments I'd like to make:

On Sun, Apr 09, 2000 at 09:48:57PM, Russ Allbery said:
> =item B<res:>
> 
> A command line for a user resolver.  The program executed must be located
> in I<pathbin>/auth/resolv.  A resolver is an authentication program which
> attempts to figure out the identity of the connecting user using nothing
> but the connection information (in other words, a username and password
> aren't used).  Examples of resolvers would be a program that gets the
> username from an ident callback or a program that obtains the user's
> identity by querying a RADIUS server.

This might be a bit misleading, since the 'radius' program I wrote is
an 'auth:' program...  It takes the username/password you give it, and
uses the RADIUS protocol to ask the server to verify that the password
is valid for the username.  A better example might be a program that
obtains the user's identity by SNMP, or by fingering some kinds of
(e.g.) portmasters.

> =item B<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 (in other words, it
> defaults to a value of "*").

I think that's also a bit false...  IIRC, I wrote the code such that
when a 'users:' keyword isn't given, it'll match auth groups that
didn't succesfully return an auth identity, which 'users: *' doesn't
do.

> =head1 EXAMPLES
> 
> Here is probably the simplest useful example of a complete readers.conf.
> This gives permissions to read and post to all groups to any connections
> from the example.com domain, and no privileges for anyone connecting from
> anywhere else:
> 
>     auth example.com {
>         hosts: *example.com

I would prefer it if this one was written
	hosts: "*.example.com, example.com"
because, as written, the hosts: will match fooexample.com, and others,
instead of the probably intended example.com hosts/subdomains.

> Here's a similar example for a news server that accepts connections from
> anywhere but requires the user to specify a username and password.  The
> username and password is first checked against an external database of
> usernames and passwords, and then against the system shadow password file:
> 
>     auth all {
>         auth: "ckpasswd -d /usr/local/news/db/newsusers"
>         auth: "ckpasswd -s"
>         default: <FAIL>
>     }

You may want to get rid of the 'default: <FAIL>' line here, in case
(for some God-forsaken reason) someone wants to have a user named
<FAIL>.  These access groups will hopefully deal with this case
(though checking me on this would probably be a good idea):

access full {
	users: "*"
	newsgroups: *
}

access fail {
	newsgroups: !*
}

>         res: ident
>         auth: "ckpasswd -s"
>         default: <FAIL>
>         default-domain: shell.example.com
>     }
> 
>     auth dialup {
>         hosts: *.dialup.example.com
>         res: radius

Unless something's changed, radius is an 'auth:' hook.

> Note the use of different domains to separate dialup from shell users
> easily.  Another way to do that would be with key: parameters, but this
> provides slightly more intuitive identity strings.

I'd like to point out that, at least, the News Gizmo expects the
username to be an e-mail address, so that it can send mail notifying
users of some kinds of policy violations before they happen.  (e.g.,
sending more than 100 messages in a day.)  I think it can be fairly
likely that the perl filter want a valid e-mail address, and you
might want to point this out in your doc.

Again, thanks very much for the new doc.
--aidan
-- 
Aidan Cully       "Are all men from the future loud-mouthed braggarts?"
Not Panix Staff   "Nope.  Just me, baby.  Just me."
aidan at panix.com      -- King Arthur, Ash