⟦563e3745f⟧

TextFile

.TH newsxd 8
.SH NAME
newsxd \- daemon for managing the transmission of news
.SH SYNTAX
.B newsxd
[\-debug] [\-DEBUG] [\-newsxdebug] [\-c \fIfile\fR] [\-v]
[\-pid \fIfile\fR\|] [\-status \fIfile\fR] [\-log \fIfile\fR]
.br
.SH DESCRIPTION
The
.I newsxd
program
is a configurable daemon for controlling the transmission
of netnews.  It allows the definition of multiple categories of service,
by setting a number of parameters defining things such as how often news is to
be transmitted, the number of news transmitters that can be active at one
time, the maximum time a transmitter may spend sending netnews to a single
host, and the maximum system load at which netnews transmitters may be
started.
.I newsxd
can also be used to start up other programs which must be restarted
upon exit, or which must be run at regular intervals with greater granularity
than
.I cron(8)
allows.
.PP
When starting up, the
.I newsxd
program reads a configuration file
(usually \fI/usr/local/etc/newsxd.conf\fR) which specifies all of the
classes of service and their characteristics, where certain data files
are to be stored and what hosts netnews is to be transmitted to.
.PP
.I newsxd
is a daemon, and while it replaces such programs as
.I nntpsend,
it is not meant to be run from
.I cron(8),
but rather from /etc/rc.local.  If you have multiple copies of
.I newsxd
running the results will be unpredictable.
.SH OPTIONS
.IP -debug 15
Enables debugging.  If debugging is enabled,
.I newsxd
will not switch to daemon mode (i.e. will not detach itself from the
controlling terminal).
.IP -DEBUG
Enables painfully verbose debugging.
.IP -newsxdebug
Enables debugging when running
.I nntpxmit.
Also causes
.I nntpxmit
to be run synchronously
.I (newsxd
will wait for the
.I nntpxmit
to complete before continuing with other hosts).
.IP "-c \fIfile\fR"
Specifies an alternate configuration file for
.I newsxd
to load.
.IP "-pid \fIfile\fR"
Specifies an alternate file for
.I newsxd
to write its PID into when starting up.
.IP "-status \fIfile\fR"
Specifies an alternate file for
.I newsxd
to write its status into upon receipt of a QUIT signal.
.IP "-log \fIfile\fR"
Specifies an alternate file for
.I newsxd
to write its logging information into when FAKESYSLOG is being used.
.IP "-v"
Displays the version of newsxd that you are running.  \fINewsxd\fR
does NOT start running if the -v switch is specified.
.RE
.PP
The configuration file for
.I newsxd
consists of commands from the list below.  Comments are preceded by
pound (\#) signs and continue to the end of the line.  Case is significant.
.PP

class \fItype [options]\fR

defines a class of service.  \fItype\fR can be any printable string less than
eight characters long (0, 5, 9, high, low, boring, etc.)  There are a number
of options that can be specified (as a space-separated list) that will modify
the behavior of a service class:
.RS +.5i
.IP maxxmits=\fIn\fR 15
specifies the maximum number of netnews transmitters that
.I newsxd
will allow to be running simultaneously for this service class.  The
default value is 1.
.IP interval=\fIn[/m]\fR
specifies the start-to-start interval (in seconds) between successive
invocations of a netnews transmitter for a single host.  The default value
is 60 seconds.  The optional parameter \fIm\fR specifies the number of
seconds to wait between starting new transmitters for ANY host in this
service class; this is useful to prevent many transmitters from being
started simultaneously and spiking the system load.  The intra-class
startup interval, \fIm\fR, should not divide the \fIqueueinterval\fR
(below) evenly.
.IP maxload=\fIn\fR
defines the maximum load at which
.I newsxd
will start transmitters for this service class.  If the load passes beyond
this value, no new transmitters will be started until the load drops.  Any
currently running transmitters will not be affected.
.IP ttl=\fIn[/m]\fR
gives the maximum time-to-live in seconds for any invocation of a netnews
transmitter.  The default value is 999999 seconds (about 11 days).  The
optional parameter, \fIm\fR, gives the number of seconds to penalize a
transmitter that has exceeded its ttl; this is the number of seconds to
prevent a new transmitter from starting up for the penalized host.
.IP noworkfile
Normally the article batch file for the host is renamed before executing
the netnews transmitter as defined by the \fIworkfile\fR below.  This option
causes the renaming to be bypassed.
.IP nobatchfile
Normally an article batch file must exist for the host before
.I newsxd
will execute the transmitter for the host.  If this option is defined,
the check for a batch file will be bypassed.
.RE
.IN -5
.PP

xmit \fIclassname programpath programname [parameters]\fR

defines an alternate netnews transmission program, for which command-line
options can be specified.  You *MUST* define a transmission program for the
class
.I DEFAULT,
which will be used as the default news transmitter for all other classes.
See the example configuration shown below.  \fINewsxd\fR will use the
environment variable PATH that it was invoked with to search for the program
if an explicit path is not given.
.RS +.5i
.IP classname 15
is the name of an already-defined service class which is to
use this transmission program.
.IP programpath
is the path of the file to execute
.IP programname
is the name to be passed to the program as argv[0];
usually the last component of \fIprogrampath\fR.
.IP [parameters]
optional parameters and options (up to nine) to be
passed to the news transmitter.  In
.I parameters,
the following conversions will be made:
.RS 15
.IP %f 5
will be replaced with the per-host flags specified by the
.I host
command (see below).
.IP %h
will be replaced with the host name.
.IP %w
will be replaced with the name of the workfile for the host.
.IP %b
will be replaced with the name of the batchfile for the host.
.IP %s
will be replaced by an integer which is unique to all of the active
transmitters for that class.  Newsxd will select the lowest unused integer
each time a transmitter is started.  These 'slot numbers' start at 0.
.RE
.RE
.PP

queueinterval \fIseconds\fR

specifies the number of seconds between "queue runs".  During each queue
run
.I newsxd
will check each host to see if a netnews transmitter can be started for
that host.  The queueinterval should be at least as small as the smallest
interval specified in all of the \fIclass\fR definitions.  The default value
for \fIqueueinterval\fR is 60 seconds.
.PP

batchfile \fIfile\fR

specifies the file path where the batch files (files listing article paths
or IDs to be used by a netnews transmitter) are stored.  A %s in \fIfile\fR
will be replaced by the name of the current host.  Unless the
.I nobatchfile
option was specified for the host's service class, this
file must exist before a netnews transmitter will be executed for the host.
The default value for \fIbatchfile\fR is defined in newsxd.h and is normally
\fI/usr/spool/batch/%s\fR.
.PP

workfile \fIfile\fR

specifies the file path which the batch files are to be renamed to before
executing the netnews transmitter.  A %s in \fIfile\fR will be replaced by
the name of the current host.  If the \fInoworkfile\fR option was specified
for this host's service class, the batch file will NOT be renamed.  The
default value for \fIworkfile\fR is defined in newsxd.h and is normally
\fI/usr/spool/batch/%s.work\fR.
.PP

xmitlogs \fIfile\fR

where to log the output of each netnews transmitter.  If you need to keep
the information printed by a transmitter, use this option.  If you don't
need to use up the disk space, leave \fIxmitlogs\fR undefined and output
will be sent to /dev/null.
.PP

host \fIhostname classname xmittimes [options]\fR

defines a host which to which
.I newsxd
will transmit netnews.
.RS +.5i
.IP hostname 15
The name of the host to pass to the netnews transmitter.
.IP classname
The name of the service class that this host is in.
.IP xmittimes
The time(s) to allow new transmitters to start for this host.  See the
manpage for
.I L.sys(5)
for the format of
.I xmittimes.
.IP [options]
There are some options which can be used to modify the behavior of the
netnews transmitter for a host:
.RS +.5i
.IP nice=\fIn\fR 15
This optional value is added to the \fInice(3)\fR of the netnews
transmitter.  To be able to run at higher priorities (a lower \fInice\fR
value),
.I newsxd
must be
.I setuid(3)
root; otherwise
.I newsxd
should be
.I setuid(3)
news.  If no
\fIdeltanice\fR value is specified, the nice of the transmitter is not
modified by
.I newsxd.
.IP flags=\fIn\fR 15
Used to specify optional flags to be passed to the netnews transmitter for
the host.  The flags must be separated by vertical bars (|), not spaces,
in the 
.I newsxd.conf
file.  Note that "-l something" would be TWO flags and you would say
flags=-l|something.
.I Newsxd
will automatically separate the flags before calling the netnews
transmitter.
XXX
.IP ttl=\fIn[/m]\fR
The \fIttl\fR option may be used to override the default value established 
by the \fIclass\fR command (described above).
.IP interval=\fIn[/m]\fR
The \fIinterval\fR option may be used to override the default value established 
by the \fIclass\fR command (described above).
.IP maxload=\fIn\fR
The \fImaxload\fR option may be used to override the default value established 
by the \fIclass\fR command (described above).
.IP maxxmits=\fIn\fR
The \fImaxxmits\fR option may be used to override the default value established 
by the \fIclass\fR command (described above).
.RE
.IN -5
.PP
.SH "SIMPLE EXAMPLE"
The following is an example of a simple configuration file:

.nf
.ft CW
# Define a service class that just runs an nntpxmit to each host
# every hour.  Don't run nntpxmit if the load goes over 8.

class   normal  maxxmits=1  interval=3600  maxload=8

# Define the default news transmitter
xmit    DEFAULT /usr/local/lib/news/nntpxmit nntpxmit %h:%w

# Check the list of hosts every 10 minutes to see if we can send news to
# someone yet.
queueinterval    600

# In all of the following options, %s is replaced by the host name of the
# system being sent to.

# File news places articles paths/ids in
batchfile   /usr/spool/batch/%s

# File a news transmitter wants articles paths/ids in
workfile    /usr/spool/batch/%s.work

# Hosts to send news to.  Each line is of the format:
#                            CLASS   VALID START
# host HOSTNAME              NAME       TIMES

host dorothy                 normal  Any
host toto                    normal  Any
host wizard                  normal  Any
host witch                   normal  Any
host tinman                  normal  Any
host lion                    normal  Any
.ft P
.fi
.PP
.RE
.LP
.SH "COMPLEX EXAMPLE"
The following is an example of a more complex configuration file that
uses most of the options supported by
.I newsxd:

.nf
.ft CW
# Define a series of service classes for sending news to other sites:
#     nlink     NNTPlink Transmits (Continuous NNTPXMITs)
#     high      High Priority Transmits (Top-40)
#     med       Medium Prio Transmits (Non Top-40)
#     low       Low Priority Transmits (Endnodes)
#     batch     Batched (with sendbatch) newsfeeds

class   nlink   maxxmits=20 interval=60    maxload=10  noworkfile
xmit    nlink   /usr/local/lib/news/nntplink nntplink %h:%b

class   high    maxxmits=99 interval=60/20 maxload=8   ttl=1800

class   med     maxxmits=5  interval=300   maxload=6   ttl=1800/60

class   low     maxxmits=3  interval=1200  maxload=5   ttl=1100/60

class   batch   maxxmits=1  interval=3600  maxload=5   ttl=1800/1800
xmit    batch   /usr/local/lib/news/sendbatch sendbatch %f %h

# Define the default news transmitter
xmit    DEFAULT /usr/local/lib/news/nntpxmit nntpxmit %h:%w

# Check the transmit queue every <n> seconds (this should be at least as
# low as the smallest "interval" in all of the transmission classes).
queueinterval    20

# In all of the following options, %s is replaced by the host name of the
# system being sent to.

# File news places articles paths/ids in
batchfile   /usr/spool/batch/%s

# File a news transmitter wants articles paths/ids in
workfile    /usr/spool/batch/%s.work

# Where to log the output of a news transmitter (default is /dev/null)
# xmitlogs   /usr/spool/batch/%s.log

# Hosts to send news to.  Each line is of the format:
#                            CLASS   VALID START
# host HOSTNAME              NAME       TIMES          OPTIONS

host dorothy                 low     Any               nice=10
host toto                    low     Any               nice=10
host wizard                  low     Any               nice=10
host witch                   low     Any               nice=10
host tinman                  low     Any               nice=10
host lion                    low     Any               nice=10
host cactus.biz.com          low     Any               nice=10
host endnode.foobar.edu      low     Any2000-0500      nice=10
host biggernode.foobar.edu   med     SaSu|Wk1730-0730
host bignode.company.com     med     Any             
host midsize.company.com     med     Any             
host university.podunk.edu   med     Any             
host mrbackbone.bigu.edu     high    Any             
host gateway.bizness.com     high    Any             
host supernews.hellou.edu    high    Any             
host mrnntp.aloha.edu        high    Any             
host hello.world.edu         high    Any             
host supernews.foou.edu      nlink   Any
host backbone.newssite.edu   nlink   Any
host fred                    batch   Any nice=20 flags=-s500000 interval=86400
host barney                  batch   Any nice=20 flags=-s250000 interval=86400
host wilma                   batch   Any nice=20 flags=-s500000
host betty                   batch   Any nice=20 flags=-s500000|-m500000
host kitty                   batch   SaSu|Wk1730-730 flags=-c|-s250000
host dino                    batch   SaSu|Wk1730-730 flags=-c|-s250000
host bambam                  batch   Sa interval=86400

# Notes: Only send news to biggernode.foobar.edu during non-business hours
#        endnode.foobar.edu only wants news transmitted from 8PM to 5AM.
#        Only send news to fred and barney once per day (every 24 hours).
#        Do one batching run for bambam each Saturday.
.ft P
.fi
.PP
.RE
.LP
.SH "CONTROLLING NEWSXD"
The following signals have the specified effect when sent to the
server
.I named
process using the
.I kill
command:
.IP SIGHUP 13
Causes newsxd to reload newsxd.conf and remove (kill) any hosts or
transmitters which are no longer defined.
.IP SIGTERM
Causes newsxd to shut down, killing all active transmitters
.IP SIGQUIT
Dumps the current newsxd status to
.I /usr/tmp/newsxd.status
.IP IO
Causes newsxd to go into idle mode, where no new transmitters are started.
Send a HUP signal to newsxd to return to normal operating mode.
.IP SIGTRAP
Causes newsxd to write a DETAILED list of the contents of all important
internal data structures to
.I /usr/tmp/newsxd.status.dump
.IP SIGUSR1
Increases the current debugging level.  Caution: the debugging information
can get very voluminous, especially if DEBUG is enabled.
.IP SIGUSR2
Decreases the current debugging level.
.SH "THE STATUS FILE"
The
.I newsxd.status
file, which is created when a SIGQUIT signal is sent to 
.I newsxd,
shows the current state of all of the hosts managed by
.I newsxd.
There are several pieces of information listed for each host,
including the host name, the times during which a new netnews transmitter
can be started, the last time a netnews transmitter was started, and a
"Why Not Running" field which indicates why a netnews transmitter is not
currently running for that host.  The various types of "Why Not Running"
messages include:

.IP "TTL Penlty" 15
The netnews transmitter for the host ran longer than the time-to-live
defined for the service class, and the host is currently being penalized.
.IP "TTL Kill"
The netnews transmitter for the host was just killed because it ran
longer than the time-to-live defined for the service class.
.IP "Class Intv"
No new transmitters in this service class can start up yet because the
intra-class transmitter startup interval hasn't passed.  See the
.I interval
option under
.I class,
above.
.IP "Host Intvl"
No new transmitters for this host can start up yet because a transmitter
has already been run for this host recently (see the 
.I interval
option under
.I class,
above).
.IP "High Load"
The system load is too high to start new netnews transmitters for this
service class.  See the
.I maxload
option under
.I class,
above.
.IP "Wrong Time"
The current time doesn't fit any of the allowed startup times specified
for the host.
.IP "Max Xmits"
The maximum number of netnews transmitters for this class are already
running.  See the
.I maxxmits
option under
.I class,
above.
.IP "RUNNING"
A netnews transmitter for this host is currently running.
.IP "No Work"
There are currently no articles to send to this host.
.IP "Bad Rename"
.I newsxd
couldn't rename the host's
.I batchfile
to the
.I workfile.
.IP "NotMyTurn"
The host has already had a chance to transmit news and now it's time for
the other hosts to get a chance.  
.I Newsxd
uses a round-robin scheduling algorithm to insure the fair transmission
of netnews.

.SH RESTRICTIONS
Does not do exponential backoff when the transmitter for a host fails.
.SH BUGS
No known bugs exist in
.I newsxd,
but the wish list of features to add is quite long...
.SH FILES
.IP /usr/local/etc/newsxd.conf 28
.I newsxd
configuration file
.IP /usr/tmp/newsxd.pid 
Process ID number
.IP /usr/tmp/newsxd.status 
Dump of
.I newsxd
status
.IP /usr/spool/batch/*
batch and work files for
.I newsxd
and netnews transmitters.
.SH "SEE ALSO"
nntpxmit(1)
.SH AUTHOR
Chris Myers <chris@wugate.wustl.edu>
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦563e3745f⟧ TextFile

Derivation

TextFile
