4.4BSD/usr/src/contrib/news/inn/doc/innd.8

.\" $Revision: 1.28 $
.TH INND 8
.SH NAME
innd, inndstart \- InterNetNews daemon
.SH SYNOPSIS
.B innd
[
.B \-a
]
[
.BI \-c " days"
]
[
.B \-d
]
[
.B \-f
]
[
.BI \-i " count"
]
[
.BI \-o " count"
]
[
.BI \-l " size"
]
[
.BI \-m " mode"
]
[
.BI \-n " flag"
]
[
.BI \-p " port"
]
[
.B \-r
]
[
.B \-s
]
[
.BI \-S " host"
]
[
.BI \-t " timeout"
]
[
.B \-u
]
[
.B \-x
]

.B inndstart
[
.B flags
]
.SH DESCRIPTION
.IR Innd ,
the InterNetNews daemon, handles all incoming NNTP feeds.
It reads the
.IR active (5),
.IR newsfeeds (5),
and
.IR hosts.nntp (5)
files into memory.
It then opens the NNTP port to receive articles from remote sites,
.\" =()<.ie '@<HAVE_UNIX_DOMAIN>@'DO' \{\>()=
.ie 'DO'DO' \{\
a Unix-domain stream socket to receive articles from local processes
such as
.IR nnrpd (8)
and
.IR rnews (1),
and a Unix-domain datagram socket for use by\}
.el and a named pipe for use by
.IR ctlinnd (8)
to direct the server to perform certain actions.
It also opens the
.IR history (5)
database and two log files to replace its standard output and standard error.
If the ``\-p'' flag is used, then the NNTP port is assumed to be
open on the specified descriptor.
(If this flag is used, then
.I innd
assumes it is running with the proper permissions and it will not call
.IR chown (2)
on any files or directories it creates.)
.PP
Once the files and sockets have been opened,
.I innd
waits for connections and data to be ready on its ports by using
.IR select (2)
and non-blocking I/O.
If no data is available, then it will flush its in-core data structures.
The default number of seconds to timeout before flushing is
.\" =()<@<DEFAULT_TIMEOUT>@ seconds.>()=
300 seconds.
This timeout may be changed by using the ``\-t'' flag.
.PP
To limit the number of incoming NNTP connections, use the ``\-i'' flag.
A value of zero will suppress this check.
.\" =()<.ie !@<DEFAULT_CONNECTIONS>@ The default is to not limit connections.>()=
.ie !50 The default is to not limit connections.
.\" =()<.el The default is @<DEFAULT_CONNECTIONS>@.>()=
.el The default is 50.
.PP
To limit the number of files that will be kept open for outgoing file
feeds, use the ``\-o'' flag.
The default is the number of available descriptors minus some reserved
for internal use.
.PP
To limit the size of an article, use the ``\-l'' flag.
If this flag is used, then any article bigger than
.I size
bytes will be rejected.
The default is no checking, which can also be obtained by using a value
of zero.
.PP
.I Innd
rejects articles that are too old.
While this behavior can be controlled by the history database,
occasionally a site dumps a batch of very old news back onto the network.
Use the ``\-c'' flag to specify a cutoff.
For example ``\-c21'' will reject any articles that were posted more than
21 days ago.
A value of zero will suppress this check.
.\" =()<.ie !@<DEFAULT_CUTOFF>@ The default is to not reject old articles.>()=
.ie !14 The default is to not reject old articles.
.\" =()<.el The default is @<DEFAULT_CUTOFF>@ days.>()=
.el The default is 14 days.
.PP
.I Innd
normally puts itself into the background, sets its standard output and
error to log files, and disassociates itself from the terminal.
Using the ``\-d'' flag instructs the server to not do this, while using
the ``\-f'' flag just leaves the server running the foreground.
The logs are normally buffered; use the ``\-u'' flag to have them
unbuffered.
.PP
To start the server in a paused or throttled state (see
.IR ctlinnd (8))
use the ``\-m'' flag to set the initial running mode.
The argument should start with a single letter
.IR g ,
.IR p ,
or
.IR t ,
to emulate the ``go,'' ``pause,'' or ``throttle'' commands, respectively.
.PP
If the ``\-r'' flag is used, the server will renumber the
.I active
file
as if a ``renumber'' command were sent.
.PP
If the ``\-s'' flag is used, then
.I innd
will not do any work but will instead just check the syntax of the
.I newsfeeds
file.
It will exit with an error status if there are any errors; the actual
errors will be reported in
.IR syslog (3).
.PP
If
.I innd
gets an NOSPC error (see
.IR intro (2))
while trying to write the
.I active
file, an article file, or the history database, it will send itself
a ``throttle'' command.
This will also happen if it gets too many I/O errors while writing
to any files.
.\" =()<.if '@<INND_NICE_KIDS>@'DO' \{\>()=
.if 'DONT'DO' \{\
.PP
Any sub-processes spawned by the server will get a
.IR nice (2)
.\" =()<value of @<INND_NICE_VALUE>@.\}>()=
value of 10.\}
\}
.PP
The ``\-n'' flag specifies whether or not pausing or throttling the server
should also disable future newsreading processes.
A value of ``y'' will make newreaders act as the server, a value of ``n'' will
allow newsreading even when the server is not running.
.\" =()<.ie '@<ALLOW_READERS>@'DONT' The default is to not allow reading.>()=
.ie 'DO'DONT' The default is to not allow reading.
.el The default is to allow reading.
.PP
If the ``\-S'' flag is used, then
.I innd
will run in ``slave'' mode.
When running as a slave, the server will only accept articles from the
specified
.IR host ,
which must use the
.I "``xreplic''"
protocol extension described below.
Note that the host must either appear in the
.I hosts.nntp
file, or the server must be started with the ``\-a'' flag.
.PP
By default, if a host if not mentioned in the
.I hosts.nntp
file, then the connection is handed off to
.IR nnrpd .
If the ``\-a'' flag is used, then any host can connect and transfer
articles.
.PP
If the ``\-x'' flag is used, then an Xref header will be added to all
articles even if they are not cross-posted.
.PP
.I Inndstart
is a small front-end program that opens the NNTP port, sets its
userid and groupid to the news maintainer, and then execs
.I innd
with the ``\-p'' flag and a minimal secure, environment.
This is a small, easily-understood front-end program that can be used if
a site does not want to run
.I innd
with root privileges.
.SH "CONTROL MESSAGES"
Arriving articles that have a Control header or have a Subject header that
starts with the five characters \&``cmsg\ '' are called
.IR "control messages" .
Except for the cancel message, these messages are implemented by
external programs in the
.\" =()<.I @<_PATH_CONTROLPROGS>@>()=
.I /var/spool/news/data/ctlbin
directory.
(Cancel messages update the history database, so they must be handled
internally; the cost of syncing, locking, then unlocking would be too
high given the number of cancel messages that are received.)
.PP
When a control message arrives, the first word of the text is converted
to lowercase and used as the name of the program to execute; if the named
program does not exist, then a program named
.\" =()<.I @<_PATH_BADCONTROLPROG>@>()=
.I default
is executed.
.PP
All control programs are invoked with four parameters.
The first is the address of the person who posted the message; this
is taken from the Sender header.
If that header is empty, then it is taken from the From header.
The second parameter is the address to send replies to; this is taken
from the Reply-To header.
If that header is empty then the poster's address is used.
The third parameter will be a name under which the article is filed, relative
to the news spool directory.
The fourth parameter is the host that sent the article, as specified
on the Path line.
.PP
The distribution of control message is also different from those of standard
articles.
.PP
Control messages are normally filed in the newsgroup named
.IR control .
They can be filed in subgroups, however, based on the control message
command.
For example, a newgroup message will be filed in
.I control.newgroup
if that group exists, otherwise it will be filed in
.IR control .
.PP
Sites may explicitly have the ``control'' newsgroup in their subscription
list, although it is usually best to exclude it.
If a control message is posted to a group whose name ends with the four
characters ``.ctl'' then the suffix is stripped off and what is left is
used as the group name.
For example, a cancel message posted to ``news.admin.ctl'' will be sent
to all sites that subscribe to ``control'' or ``news.admin.''
Newgroup and rmgroup messages receive additional special treatment.
If the message is approved and posted to the name of the group being created
or removed, then the message will be sent to all sites whose subscription
patterns would cause them to receive articles posted in that group.
.\" =()<.if '@<MERGE_TO_GROUPS>@'DO' \{\>()=
.if 'DONT'DO' \{\
.PP
If an article is posted to a newsgroup that starts with the three
letters ``to.'' it will get special treatment if the newsgroup does not
exist in the
.I active
file:
the article is filed into the newsgroup ``to'' and it is sent to
the first site named after the prefix.
For example, a posting to ``to.uunet'' will be filed in ``to'' and sent
to the site ``uunet.''\}
.SH "PROTOCOL DIFFERENCES"
.I Innd
implements the NNTP commands defined in RFC 977, with the following
differences:
.IP 1.
The
.I "``list''"
maybe followed by an optional
.IR "``active''" ,
.IR "``active.times''" ,
or
.I "``newsgroups''"
argument.
This common extension is not fully supported; see
.IR nnrpd (8).
.IP 2.
The
.I "``authinfo user''"
and
.I "``authinfo pass''"
commands are implemented.
These are based on the reference Unix implementation; no other documentation
is available.
.IP 3.
A new command,
.IR "``mode reader''" ,
is provided.
This command will cause the server to pass the connection on to
.IR nnrpd .
The command
.I "``mode query''"
is intended for future use, and is currently treated the same way.
.IP 4.
A new command,
.IR "``xreplic news.group:art[,news.group:art]''" ,
is provided.
This is similar to the
.I "``ihave''"
command (the same reply codes are used) except for the data that follows
the command word.
The data consists of entries separated by a single comma.
Each entry consists of a newsgroup name, a colon, and an article number.
Once processed, the article will be filed in the newsgroup and article
numbers specified in the command.
.IP 5.
A new command,
.IR "``xpath messageid''" ,
is provided.
The server responds with a
223 response and a space-separated list of filenames where the article
was filed.
.IP 6.
The only other commands implemented are
.IR "``head''" ,
.IR "``help''" ,
.IR "``ihave''" ,
.IR "``quit''" ,
and
.IR "``stat''" .
.SH "HEADER MODIFICATIONS"
.I Innd
modifiers as few article headers as possible, although it could be better
in this area.
.PP
The following headers, if present, are removed:
.RS
.nf
Date-Received
Posted
Posting-Version
Received
Relay-Version
.fi
.RE
Empty headers and headers that consist of nothing but whitespace are also
dropped.
.PP
The local site's name and an exclamation point are prepended to the Path header.
.PP
The Xref header is removed.
If the article is cross-posted a new header is generated.
.PP
The Lines header will be added if it is missing.
.PP
.I Innd
does not rewrite incorrect headers.
For example, it will not replace an incorrect Lines header, but will reject
the article.
.SH LOGGING
.I Innd
reports all incoming articles in its log file.
This is a text file with a variable number of space-separated fields in
one of the following formats:
.RS
.nf
mon dd hh:mm:ss.mmm + feed <Message-ID> site...
mon dd hh:mm:ss.mmm j feed <Message-ID> site...
mon dd hh:mm:ss.mmm c feed <Message-ID> site...
mon dd hh:mm:ss.mmm - feed <Message-ID> reason...
.fi
.RE
The first three fields are the date and time to millisecond resolution.
The fifth field is the site that sent the article (based on the Path
header) and the sixth field is the article's Message-ID; they will be a
question mark if the information is not available.
.PP
The fourth field indicates whether the article was accepted or not.
If it is a plus sign, then the article was accepted.
If it is the letter ``j'' then the article was accepted, but all of
newsgroups have an ``j'' in their
.I active
field, so the article was filed into the ``junk'' newsgroup.
If the fourth field is the letter ``c'', then a cancel message was
accepted before the original article arrived.
In all three cases, the article has been accepted and the ``site..'' field
contains the space-separated list of sites to which the article is
being sent.
.PP
If the fourth field is a minus sign, then the article was rejected.
The reasons for rejection include:
.RS
.nf
"%s" header too long
"%s" wants to cancel <%s> by "%s"
Article exceeds local limit of %s bytes
Article posted in the future -- "%s"
Bad "%s" header
Can't write history
Duplicate
Duplicate "%s" header
EOF in headers
Linecount %s != %s +- %s
Missing %s header
No body
No colon-space in "%s" header
No space
Space before colon in "%s" header
Too old -- "%s"
Unapproved for "%s"
Unwanted newsgroup "%s"
Unwanted distribution "%s"
Whitespace in "Newsgroups" header -- "%s"
.fi
.RE
Where ``%s'', above, is replaced by more specific information.
.\" =()<.if '@<WANT_TRASH>@'DO' \{\>()=
.if 'DONT'DO' \{\
.PP
Note that if an article is accepted and none of the newsgroups are valid,
it will be logged with both two lines, a ``j'' line and a minus sign line.\}
.PP
.I Innd
also makes extensive reports through
.IR syslog .
The first word of the log message will be the name of the site if
the entry is site-specific (such as a ``connected'' message).
The first word will be ``ME'' if the message relates to the server itself,
such as when a read error occurs.
.PP
If the second word is the four letters ``cant'' then an error is being
reported.
In this case, the next two words generally name the system call or library
routine that failed, and the object upon which the action was being performed.
The rest of the line may contain other information.
.PP
In other cases, the second word attempts to summarize what change
has been made, while the rest of the line gives more specific information.
The word ``internal'' generally indicates an internal logic error.
.SH HISTORY
Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.
.de R$
This is revision \\$3, dated \\$4.
..
.R$ $Id: innd.8,v 1.28 1993/03/18 21:03:39 rsalz Exp $
.SH "SEE ALSO"
active(5),
ctlinnd(8),
dbz(3z),
history(5),
hosts.nntp(5),
inn.conf(5),
newsfeeds(5),
nnrpd(8),
rnews(1),
syslog(8).