newsxd

NAME

SYNTAX

DESCRIPTION

When starting up, the newsxd program reads a configuration file (usually /usr/local/etc/newsxd.conf) 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.

newsxd is a daemon, and while it replaces such programs as nntpsend, it is not meant to be run from cron(8), but rather from /etc/rc.local. If you have multiple copies of newsxd running the results will be unpredictable.  

OPTIONS

-debug

Enables debugging. If debugging is enabled, newsxd will not switch to daemon mode (i.e. will not detach itself from the controlling terminal).

-DEBUG

Enables painfully verbose debugging.

-newsxdebug

Enables debugging when running nntpxmit. Also causes nntpxmit to be run synchronously (newsxd will wait for the nntpxmit to complete before continuing with other hosts).

-c file

Specifies an alternate configuration file for newsxd to load.

-pid file

Specifies an alternate file for newsxd to write its PID into when starting up.

-status file

Specifies an alternate file for newsxd to write its status into upon receipt of a QUIT signal.

-log file

Specifies an alternate file for newsxd to write its logging information into when FAKESYSLOG is being used.

-v

Displays the version of newsxd that you are running. Newsxd does NOT start running if the -v switch is specified.

The configuration file for 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.

class type [options]

defines a class of service. type 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:

maxxmits=n

specifies the maximum number of netnews transmitters that newsxd will allow to be running simultaneously for this service class. The default value is 1.

interval=n[/m]

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 m 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, m, should not divide the queueinterval (below) evenly.

maxload=n

defines the maximum load at which 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.

ttl=n[/m]

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, m, 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.

noworkfile

Normally the article batch file for the host is renamed before executing the netnews transmitter as defined by the workfile below. This option causes the renaming to be bypassed.

nobatchfile

Normally an article batch file must exist for the host before newsxd will execute the transmitter for the host. If this option is defined, the check for a batch file will be bypassed.

xmit classname programpath programname [parameters]

defines an alternate netnews transmission program, for which command-line options can be specified. You *MUST* define a transmission program for the class DEFAULT, which will be used as the default news transmitter for all other classes. See the example configuration shown below. Newsxd will use the environment variable PATH that it was invoked with to search for the program if an explicit path is not given.

classname

is the name of an already-defined service class which is to use this transmission program.

programpath

is the path of the file to execute

programname

is the name to be passed to the program as argv[0]; usually the last component of programpath.

[parameters]

optional parameters and options (up to nine) to be passed to the news transmitter. In parameters, the following conversions will be made:

%f

will be replaced with the per-host flags specified by the host command (see below).

%h

will be replaced with the host name.

%w

will be replaced with the name of the workfile for the host.

%b

will be replaced with the name of the batchfile for the host.

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

queueinterval seconds

specifies the number of seconds between "queue runs". During each queue run 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 class definitions. The default value for queueinterval is 60 seconds.

batchfile file

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 file will be replaced by the name of the current host. Unless the 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 batchfile is defined in newsxd.h and is normally /usr/spool/batch/%s.

workfile file

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

xmitlogs file

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 xmitlogs undefined and output will be sent to /dev/null.

host hostname classname xmittimes [options]

defines a host which to which newsxd will transmit netnews.

hostname

The name of the host to pass to the netnews transmitter.

classname

The name of the service class that this host is in.

xmittimes

The time(s) to allow new transmitters to start for this host. See the manpage for L.sys(5) for the format of xmittimes.

[options]

There are some options which can be used to modify the behavior of the netnews transmitter for a host:

nice=n

This optional value is added to the nice(3) of the netnews transmitter. To be able to run at higher priorities (a lower nice value), newsxd must be setuid(3) root; otherwise newsxd should be setuid(3) news. If no deltanice value is specified, the nice of the transmitter is not modified by newsxd.

flags=n

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 newsxd.conf file. Note that "-l something" would be TWO flags and you would say flags=-l|something. Newsxd will automatically separate the flags before calling the netnews transmitter. XXX

ttl=n[/m]

The ttl option may be used to override the default value established by the class command (described above).

interval=n[/m]

The interval option may be used to override the default value established by the class command (described above).

maxload=n

The maxload option may be used to override the default value established by the class command (described above).

maxxmits=n

The maxxmits option may be used to override the default value established by the class command (described above).

SIMPLE EXAMPLE

# 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

COMPLEX EXAMPLE

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

CONTROLLING NEWSXD

SIGHUP

Causes newsxd to reload newsxd.conf and remove (kill) any hosts or transmitters which are no longer defined.

SIGTERM

Causes newsxd to shut down, killing all active transmitters

SIGQUIT

Dumps the current newsxd status to /usr/tmp/newsxd.status

SIGIOT

Causes newsxd to kill all active transmitters and go into idle mode. Send a HUP signal to newsxd to return to normal operating mode.

SIGIO

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.

SIGTRAP

Causes newsxd to write a DETAILED list of the contents of all important internal data structures to /usr/tmp/newsxd.status.dump

SIGUSR1

Increases the current debugging level. Caution: the debugging information can get very voluminous, especially if DEBUG is enabled.

SIGUSR2

Decreases the current debugging level.

THE STATUS FILE

TTL Penlty

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.

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.

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 interval option under class, above.

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 interval option under class, above).

High Load

The system load is too high to start new netnews transmitters for this service class. See the maxload option under class, above.

Wrong Time

The current time doesn't fit any of the allowed startup times specified for the host.

Max Xmits

The maximum number of netnews transmitters for this class are already running. See the maxxmits option under class, above.

RUNNING

A netnews transmitter for this host is currently running.

No Work

There are currently no articles to send to this host.

Bad Rename

newsxd couldn't rename the host's batchfile to the workfile.

NotMyTurn

The host has already had a chance to transmit news and now it's time for the other hosts to get a chance. Newsxd uses a round-robin scheduling algorithm to insure the fair transmission of netnews.

RESTRICTIONS

BUGS

FILES

/usr/local/etc/newsxd.conf

newsxd configuration file

/usr/tmp/newsxd.pid

Process ID number

/usr/tmp/newsxd.status

Dump of newsxd status

/usr/spool/batch/*

batch and work files for newsxd and netnews transmitters.

SEE ALSO

AUTHOR

Index

NAME

SYNTAX

DESCRIPTION

OPTIONS

SIMPLE EXAMPLE

COMPLEX EXAMPLE

CONTROLLING NEWSXD

THE STATUS FILE

RESTRICTIONS

BUGS

FILES

SEE ALSO

AUTHOR