Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
READERS.CONF(5)		  InterNetNews Documentation	       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	is permitted to	do.  Writing a readers.conf
       file for	your setup is a	two-step process: first	assigning an identity
       to each incoming	connection using auth groups, and then giving each
       identity	appropriate privileges with access group.  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.

       If nnrpdauthsender is set in inn.conf, the user identity	is also	put
       into the	Sender:	header of posts	made by	that user.  See	the
       documentation of	that option in inn.conf(5) for more details.

       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 TLS/SSL or SASL libraries, an auth group	with
       the require_ssl parameter set to	true only applies if the incoming
       connection is using an encryption layer,	either from the	beginning if
       the -S flag was passed to nnrpd,	or after a successful use of STARTTLS,
       or after	a successful authentication using a SASL mechanism which
       negotiates an encryption	layer.

       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.
       The most	common <auth-program> to use is	ckpasswd, which	supports
       several ways of checking	passwords including using PAM.	See the
       ckpasswd(8) man page for	more details.

       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.

       Configuration files can be included in other configuration files	via
       the syntax:

	   include <filename>

       The file	named <filename> is then included.  This syntax	is allowed
       only at top-level.

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

       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.

	   Alternatively, a res	block can be used instead of a res: paramater.
	   The recognized parameters in	such res blocks	are:

	   log:
	      A	string to log in pathlog/news.notice (with "res	also-log:"
	      prepended) before	the resolver is	tried.	One res	group can have
	      multiple log: parameters,	and they will be logged	in the order
	      they're listed.

	   program:
	      This parameter is	mandatory in a res block.  Its meaning is the
	      same as the res: parameter used directly in an auth block.

		  auth <auth-name> {
		      res: <res-program>
		  }

	      is therefore equivalent to:

		  auth <auth-name> {
		      res <res-name> {
			  program: <res-program>
		      }
		  }

       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.

	   The most common authenticator to use	is ckpasswd(8);	see its	man
	   page	for more information.

       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
	   (without its	".py" extension) 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, either from the beginning if the	-S flag	was
	   passed to nnrpd, or after a successful use of STARTTLS, or after a
	   successful authentication using a SASL mechanism which negotiates
	   an encrypted	layer.	This parameter is only valid if	INN is
	   compiled with TLS/SSL or SASL support (by default if	the OpenSSL
	   SSL and crypto libraries or the Cyrus SASL library are found	at
	   configure time, otherwise see the --with-openssl and	--with-sasl
	   flags 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 (without	its ".py" 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 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
	   (without its	".py" 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 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	command, the user must also
	      have POST	permission (the	"P" option).  Articles injected	with
	      IHAVE are	treated	as though they were injected with POST,	that
	      is to say	such articles must not have been previously injected
	      (they must not contain headers like Injection-Info:).

	   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 (status fields "j", "n" and "x" 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 an encryption layer is
	   being used, limiting	is applied to the pre-encryption datastream.

       localtime:
	   If a	Date: or an Injection-Date: header field is not	included in a
	   posted article, nnrpd(8) normally adds these	header fields in UTC.
	   If this is set to true, the Date: header field will be formatted in
	   local time instead.	(The Injection-Date: header field will remain
	   in UTC, though.)  This is a boolean value and the default is	false.

	   This	parameter permits to handle a relatively unusual corner	case.
	   It is mostly	a tool for people who want to disclose their local
	   time	zone (it can be	useful information in certain types of
	   discussions), but whose clients don't for some reason, and who can
	   arrange for the server to be	in the same time zone as the client.

       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 true in order to make nnrpd 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	readers.conf
	   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 Injection-Info: 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:

	   addinjectiondate, addinjectionpostingaccount, addinjectionpostinghost,
	   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.

SUMMARY
       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
	 (due to hosts,	localaddress, require_ssl, etc.) are eliminated.

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

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

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

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

       o 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:	"<EXAMPLE>"
	   }

	   access full {
	       users: "<EXAMPLE>"
	       newsgroups: *
	   }

       Note that the above access realm	could also be written without the
       users: key, in which case it applies to any user	identity (though in
       this example, the user identity that will be assigned to	all matching
       connections is "<EXAMPLE>").  It	is however recommended to keep an
       explicit	users: key so as to better view	to whom	the access block
       applies.

       As the only available auth realm	only matches hosts in the
       "example.com" domain, 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 <pathdb in inn.conf>/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 an example of another common case: a server that only allows
       connections from	a local	domain and has an additional hierarchy that's
       password-restricted.

	   auth	"example.com" {
	       hosts: "*.example.com"
	       auth: "ckpasswd -d <pathdb in inn.conf>/newsusers"
	       default:	"anonymous"
	   }

	   access regular {
	       newsgroups: "*,!example.restricted.*"
	   }

	   access full {
	       users: "*,!anonymous"
	       newsgroups: *
	   }

       In this example,	unauthenticated	users get the identity "anonymous",
       which matches only the first access group and hence doesn't get access
       to the example.restricted.* hierarchy.  Anyone who authenticates	using
       a password in the newsusers file	gets full access to all	groups.
       However,	note that the only authentication block	is limited to
       hostnames in the	example.com domain; connections	outside	of that	domain
       will never be allowed access or an opportunity to authenticate.

       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 <pathdb in inn.conf>/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 in order to 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 TLS/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.	 One
       can also	authenticate using a strong SASL mechanism.  Here are some
       ideas:

       o   To restrict connections on the standard NNTP	port (119) to use an
	   encryption layer for	some (or all) of the auth groups to match, use
	   the require_ssl parameter.  Note that a client can use STARTTLS to
	   negotiate an	encrypted TLS connection.  A secure layer can also be
	   negotiated during authentication via	AUTHINFO SASL.

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

       o   Consider running nnrpd with the -S flag (either also	with -D, or
	   out of "super-server" like inetd) on	the NNTPS port (563) for
	   clients that	support	TLS/SSL.  See nnrpd(8) for more	details	about
	   how to configure that.  You can use the require_ssl parameter or
	   the -c flag to specify an alternate readers.conf file if you	want a
	   substantially different configuration for this case.

       o   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 <eagle@eyrie.org>.

       $Id: readers.conf.pod 9977 2015-12-10 20:49:04Z iulius $

SEE ALSO
       auth_krb5(8), ckpasswd(8), inn.conf(5), innd(8),	newsfeeds(5),
       nnrpd(8), uwildmat(3).

INN 2.6.1			  2016-10-07		       READERS.CONF(5)

NAME | DESCRIPTION | AUTH GROUP PARAMETERS | ACCESS GROUP PARAMETERS | SUMMARY | EXAMPLES | SECURITY CONSIDERATIONS | HISTORY | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=readers.conf&sektion=5&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help