.\"
.\" @(#)$Id: nntpd.dst,v 1.6 1994/11/01 05:48:22 sob Exp sob $
.\"
.TH NNTPD 8C "4 July 1990"
.UC 4
.SH NAME
nntpd \- Network News Transfer Protocol server
.SH SYNOPSIS
.B LNNTPD
.br
.I (with INETD, see below)
.SH DESCRIPTION
.I Nntpd
is a server that supports the proposed standard
for the stream based transmission of network
news articles.
It can be used both by ``reader/poster'' clients that
present news to users, and by
``transfer'' clients that transport news between machines.
When used with Internet TCP,
.I nntpd
operates at the port indicated in the ``nntp'' service
entry in
.IR SERVICES ;
the port number assigned by the Network Information Center
for this service is 119.
For use with DECNET (which is only known to work under ULTRIX),
define the NNTP object with NCP.
.sp
.nf
ncp define object NNTP number 0 file LNNTPD
ncp define object NNTP default user guest type stream
ncp set object NNTP all
.fi
.sp
This manual page describes
.I nntpd
from version 1.5.9 of the NNTP package.
.PP
.I Nntpd
can operate either as a stand-alone server, or as a
server under
.IR inetd (8C).
For stand-alone use,
.I nntpd
must be compiled with the -DALONE option, and is
usually invoked at system startup by the
.IR /etc/rc.local 
script.
Under
.IR inetd (8C),
the appropriate entry must be made in
.IR INETDCONFIG ,
and the server must be compiled without the
-DALONE flag. You may need to halt and restart 
.IR inetd (8C)
or send it SIGHUP to force it to reread
.IR INETDCONFIG .
.PP
The server handles clients on a one to one basis,
forking to take care of clients as they request
connections.
Each server changes its current
directory to the news spool directory
(
.IR NEWSSPOOL )
and then executes commands from its client.
These commands are described in ARPA Internet
RFC 977, ``Network News Transfer Protocol;
A Proposed Standard for the Stream Based Transmission
of News Articles.''
.SH "CLIENT ACCESS"
.PP
Sites may choose to limit
the hosts that can query the server for news.
Further, some sites may not wish to allow
certain hosts to post news.
Finally, some sites may wish to restrict the newsgroups
that can be accessed from remote hosts.
Such limiting can be accomplished through an
access file,
.IR NEWSLIB/nntp_access .
This file consists of three or four fields in the following form:
.sp
.nf
host/net/*domain.suffix/address   read/xfer/both/no  post/no  newsgroups
.fi
.sp
where
.f
.I host
is a valid host name as found in
.I HOSTFILE,
.I net
is a valid network name as found in
.I NETWORKFILE,
.I *.domain.suffix
is a valid domain part of a hostname preceeded by an asterisk,
.I address
is a valid internet address in the form of a dotted quad, and
.I ``read'',
.I ``xfer'',
.I ``both'',
.I ``post'',
and
.I ``no''
are the corresponding string constants.
.I Newsgroups
is an optional list of comma separated newsgroup names.
Anything to the right of a `#' character
is taken to be a comment and is ignored.
.PP
The presence of an entry in this file
implies that specific host, or
hosts on the named network, or hosts with a domain suffix that matches, are
allowed to read news, but not to post news.
The absence of a entry corresponding
to a client's host or network implies that the client
is not allowed to read or post news.
Default permissions can be set by having the
first entry in the file be a host/net name of
``default''.
If this is used, ``default'' must be the
first entry.
.PP
The first field to the right of the host/net entry
specifies the read access of the host/net in
question.
If the entry is ``read,'' matching
hosts can read news. This means that all commands but IHAVE and POST can
be executed.
If the entry is ``xfer,'' however,
matching hosts can only execute commands
used for transferring news, such as
NEWNEWS, NEWGROUPS, IHAVE, and ARTICLE with message-id parameters.
If the entry is ``both,'' ths host can
execute all commands but POST.
The string ``no'' denies read permission
of any kind to a matching host.
.PP
The next field to the right defines
whether a matching host has post
permission: if the field is ``post''
then the POST command is permitted; if
the field is ``no,'' then matching clients
are not allowed to post news.
.PP
The next field is optional, and, if present,
is a comma separated list of newsgroup names
that restrict the client's reading ability.
Clients are not allowed to read or transfer
articles in newsgroup names preceded by an exclamation
point.
By default, clients are allowed to read all newsgroups.
.PP
.I Nntpd
is selective and searches for a ``best match''
when searching this file to check its client's
permissions.  That is, a specific host name
match is used over a
client being a member of a specified net.
.SH EXAMPLE ACCESS FILE
.PP
.sp
.nf
#
# Example access file
#
default         xfer    no
ucb-ether       read    post
shadow          no      no
*.stanford.edu  no      no
ic              read    post     !ucb.postgres
128.249.1.1     read    no
.fi
.sp
.PP
The above file allows only transfer of news (i.e., no reading or posting)
by default.
Hosts on the network ``ucb-ether'' would be able to
read and post news, however news transfer would not be allowed.
The host ``shadow'' would not be allowed
to read or post news.
Hosts that have a domain suffix of ``.stanford.edu'' are denied access
to this server.
The host ``ic'' is allowed to read and post
news, but cannot access articles in the newsgroup
``ucb.postgres'' or any of its child newsgroups
(e.g., ``ucb.postgres.core'').
Finally, the host whose ip address is 128.249.1.1 is allowed to read but
not post. If you have mutl-homed host, all addresses for that host will need
to be listed with the same access information or things will not work as
expected.
.SH "INFORMING USERS OF NEW NEWSGROUPS"
.PP
The NEWGROUPS command does not work well when used with B news.
However, C news provides this information and use of the NEWGROUPS command
will be much more reliable.
For those sites using B news, client programs can determine if newgroups have
been created 
by testing for the difference in active file size from the previous session.
.PP
Older versions of
.I nntpd
relied on the program
.I mkgrdates
to prepare newsgroup creation information.
.I Mkgrdates
was fallible and could present a hefty load
on the serving system.
Consequently, it is no longer supported, and its use is discouraged.
.SH AUTHORS
Phil Lapsley (Internet: phil@berkeley.edu; UUCP: ...!ucbvax!phil)
.br
Stan Barber (Internet: sob@tmc.edu; UUCP: ...!bcm!sob)
.SH SEE ALSO
services(5),
inetd(8C),
rc.local(8)
.PP
RFC 977, ``Network News Transfer Protocol:
A Proposed Standard for the Stream Based Transmission
of News Articles.''