=head1 NAME

nnrpd - NNTP server for on-campus hosts

=head1 SYNOPSIS

B<nnrpd> [B<-DfnoRSt>] [B<-b> I<address>] [B<-c> I<configfile>]
[B<-g> I<shadowgroup>>] [B<-i> I<initial>] [B<-I> I<instance>] [B<-p> I<port>]
[B<-P> I<prefork>] [B<-r> I<reason>] [B<-s> I<padding>]

=head1 DESCRIPTION

B<nnrpd> is an NNTP server for newsreaders. It accepts commands on its
standard input and responds on its standard output. It is normally
invoked by innd(8) with those descriptors attached to a remote client
connection. B<nnrpd> also supports running as a standalone daemon.

Unlike innd(8) B<nnrpd> supports all NNTP commands for user-oriented
reading and posting.

B<nnrpd> uses the F<readers.conf> file to control who is authorized to
access the Usenet database. When I<nnrpdloadlimit> in F<inn.conf> is
not 0, it will also reject connections if the load average is greater
than that value (typically 16).

On exit, B<nnrpd> will report usage statistics through syslog(3).

B<nnrpd> can also prevent high-volume posters from abusing your
resources. See the discussion of exponential backoff in inn.conf(5).

=head1 OPTIONS

=over 4

=item B<-b> I<address>

The B<-b> parameter instructs B<nnrpd> to bind to the specified IP
address when started as a standalone daemon using the B<-D> flag. This
has to be a valid IPv4 or IPv6 address belonging to an interface of
the local host.  It can also be ::0 (although the default is 0.0.0.0
if unspecified).

=item B<-c> I<configfile>

By default, B<nnrpd> reads the F<readers.conf> to determine how to
authenticate connections.  The B<-c> flag specifies an alternate file
for this purpose.  If the file name isn't fully qualified, it is taken
to be relative to I<pathetc> in F<inn.conf> (this is useful to have
several instances of B<nnrpd> running on different ports or IP
addresses with different settings.)

=item B<-D>

If specified, this parameter causes B<nnrpd> to operate as a
daemon. That is, it detaches itself and runs in the background,
forking a process for every connection. By default B<nnrpd> listens on
the NNTP port (119), so either innd(8) has to be started on another
port or B<nnrpd> B<-p> parameter.  Note that with this parameter,
B<nnrpd> continues running until killed.  This means that it reads
F<inn.conf> once on startup and never again until restarted. B<nnrpd>
should therefore be restarted if inn.conf is changed.

=item B<-f>

If specified, B<nnrpd> does not detach itself and runs in the
foreground when started as a standalone daemon using the B<-D> flag.

=item B<-g> I<shadowgroup>

On systems that have a shadow password file, B<nnrpd> tries to add the
group I<shadow> as a supplementary group if it is running in
standalone mode. On many systems, members of that group have read
permission for the shadow password file. The B<-g> parameter instructs
B<nnrpd> to try to add the named group as a supplementary group on
shadow systems instead of I<shadow>. This only works if
C<HAVE_GETSPNAM> in F<include/config.h> is defined and B<nnrpd> is
running in standalone mode since this call only works when B<nnrpd> is
started as root.

=item B<-i> I<initial>

Specify an initial command to B<nnrpd>. When used, I<initial> is taken
as if it were the first command received by B<nnrpd>.

=item B<-I> I<instance>

If specified I<instance> is used as an additional static portion
within MessageIDs generated by B<nnrpd>; typically this option would
be used where a cluster of machines exist with the same virtual
hostname and must be disambiguated during posts.

=item B<-n>

The B<-n> flag turns off resolution of IP addresses to names.  If you
only use IP-based restrictions in F<readers.conf> and can handle IP
addresses in your logs, using this flag may result in some additional
speed.

=item B<-o>

The B<-o> flag causes all articles to be spooled instead of sending
them to innd(8). B<rnews> with the B<-U> flag should be invoked from
cron on a regular basis to take care of these articles. This flag is
useful if innd(8) in accepting articles and B<nnrpd> is started
standalone or using inetd(8).

=item B<-p> I<port>

The B<-p> parameter instructs B<nnrpd> to listen on I<port> when
started as a standalone daemon using the B<-D> flag.

=item B<-P> I<prefork>

The B<-P> parameter instructs B<nnrpd> to prefork I<prefork> children
awaiting connections when started as a standalone daemon using the
B<-D> flag.

=item B<-r> I<reason>

If the B<-r> flag is used, then B<nnrpd> will reject the incoming
connection giving I<reason> as the text. This flag is used by innd(8)
when it is paused or throttled.

=item B<-R>

This option forces B<nnrpd> to be read-only. The startup banner will
indicate "no posting".

=item B<-s> I<padding>

As each command is received, B<nnrpd> tries to change its C<argv>
array so that ps(1) will print out the command being executed. To get
a full display, the B<-s> flag may be used with a long string as its
argument, which will be overwritten when the program changes its
title.

=item B<-S>

If specified, B<nnrpd> will start a negotiation for SSL session as
soon as connected. To use this flag, C<--with-openssl> must have been
specified at C<configure> time.

=item B<-t>

If the B<-t> flag is used then all client commands and initial
responses will be traced by reporting them in syslog. This flag is set
by innd(8) under the control of the ctlinnd(8) C<trace> command, and
is toggled upon receipt of a C<SIGHUP>; see signal(2).

=head1 PROTOCOL DIFFERENCES

B<nnrpd> implements the NNTP commands defined in RFC 977, with the following
differences:

=over 4

=item 1.

The C<slave> command is not implemented. This command has never been
fully defined.

=item 2.

The C<list> command may be followed by the optional word
C<active.times>, C<distributions>, C<distrib.pats>, C<moderators>,
C<newsgroups>, C<subscriptions>, or C<Ioverview.fmt> to get a list of
when newsgroups where created, a list of valid distributions, a file
specifying default distribution patterns, moderators list, a
one-per-line description of the current set of newsgroups, a list of
the automatic group subscriptions, or a listing of the
F<overview.fmt> file.

The command C<list active> is equivalent to the C<list> command. This
is a common extension.

=item 3.

The C<xhdr>, C<authinfo user> and C<authinfo pass> commands are
implemented.  These are based on the reference Unix
implementation. See
ftp://ftp.ietf.org/internet-drafts/draft-ietf-nntpext-imp-04.txt

=item 4.

A new command, C<xpat header range|MessageID pat [morepat...]>, is
provided.  The first argument is the case-insensitive name of the
header to be searched.  The second argument is either an article range
or a single Message-ID, as specified in RFC 977.  The third argument
is a C<uwildmat>(3)-style pattern; if there are additional arguments
they are joined together separated by a single space to form the
complete pattern.  This command is similar to the C<xhdr> command.  It
returns a C<221> response code, followed by the text response of all
article numbers that match the pattern.

=item 5.

The C<listgroup group> command is provided.  This is a comment
extension.  It is equivalent to the C<group> command, except that the
reply is a multi-line response containing the list of all article
numbers in the group.

=item 6.

The C<xgtitle [group]> command is provided. This extension is used by
ANU-News.  It returns a C<282> reply code, followed by a one-line
description of all newsgroups thatmatch the pattern. The default is
the current group.

=item 7.

The C<xover [range]> command is provided. It returns a C<224> reply
code, followed by the overview data for the specified range; the
default is to return the data for the current article.

=item 8.

The C<xpath MessageID> command is provided; see innd(8).

=item 9.

The C<date> command is provided; this is based on the draft NNTP
protocol revision (draft-ietf-nntpext-imp-04.txt).  It returns a
one-line response code of C<111>  followed by the GMT date and time on
the server in the form C<YYYYMMDDhhmmss>.

=head1 HISTORY

Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.
Overview support added by Rob Robertston <rob@violet.berkeley.edu> and
Rich in January, 1993. Exponential backoff (for posting) added by
Dave Hayes in Febuary 1998.

$Id: nnrpd.pod,v 1.2 2002/12/03 05:17:17 vinocur Exp $

=head1 SEE ALSO

ctlinnd(8), innd(8), inn.conf(5), signal(2), uwildmat(3).
