NAME
ctlinnd - control the InterNetNews daemon
SYNOPSIS
ctlinnd [ -h ] [ -s ] [ -t timeout ] command [ argument... ]
DESCRIPTION
Ctlinnd sends a message to the control channel of innd(8),
the InterNetNews server.
In the normal mode of behavior, the message is sent to the
server, which then performs the requested action and sends
back a reply with a text message and the exit code for
ctlinnd. If the server successfully performed the command,
ctlinnd will exit with a status of zero and print the reply
on standard output. If the server could not perform the
command (for example, it was told to remove a newsgroup that
does not exist), it will direct ctlinnd to exit with a
status of one. The ``shutdown,'' ``xabort,'' and ``xexec''
commands do not generate a reply; ctlinnd will always exit
silently with a status of zero.
OPTIONS
-s If the ``-s'' flag is used, then no message will be
printed if the command was successful.
-t The ``-t'' flag can be used to specify how long to wait
for the reply from the server. The timeout value
specifies the number of seconds to wait. A value of
zero waits forever, and a value less than zero indi-
cates that no reply is needed. When waiting for a
reply, ctlinnd will try every two minutes to see if the
server is still running, so it is unlikely that ``-t0''
will hang. The default is ``-t0.''
-h To see a command summary, use the ``-h'' flag. If a
command is included when ctlinnd is invoked with the
``-h'' flag, then only the usage for that command will
be given.
If a large number of groups are going to be created or
deleted at once, it may be more efficient to ``pause'' or
``throttle'' the server and edit the active file directly.
The complete list of commands follows. Note that all com-
mands have a fixed number of arguments. If a parameter can
be an empty string, then it is necessary to specify it as
two adjacent quotes, like "".
addhist <Message-ID> arr exp post paths
Add an entry to the history database. This directs the
server to create a history line for Message-ID. The
angle brackets are optional. Arr, exp, and post
specify when the article arrived, what its expiration
date is, and when it was posted. All three values are
a number indicating the number of seconds since the
epoch. If the article does not have an Expires header,
then exp should be zero. Paths is the pathname within
the news spool directory where the article is filed.
If the article is cross-posted, then the names should
be separated by whitespace and the paths argument
should be inside double quotes. If the server is
paused or throttled, this command causes it to briefly
open the history database.
allow reason
Remote connections are allowed. The reason must be the
same text given with an earlier ``reject'' command, or
an empty string.
begin site
Begin feeding site. This will cause the server to res-
can the newsfeeds(5) file to find the specified site
and set up a newsfeed for it. If the site already
exists, a ``drop'' is done first. This command is for-
warded; see below.
cancel <Message-ID>
Remove the article with the specified Message-ID from
the local system. This does not generate a cancel mes-
sage. The angle brackets are optional. If the server
is paused or throttled, this command causes it to
briefly open the history database.
changegroup group rest
The newsgroup group is changed so that its fourth field
in the active file becomes the value specified by the
rest parameter. This may be used to make an existing
group moderated or unmoderated, for example.
checkfile
Check the syntax of the newsfeeds file, and display a
message if any errors are found. The details of the
errors are reported to syslog(3).
drop site
Flush and drop site from the server's list of active
feeds. This command is forwarded; see below.
feedinfo site
Print detailed information about the state of the feed
to site or more brief status of all feeds if site is an
empty string.
feedinfo site
Print detailed information about the state of the feed
to site or more brief status of all feeds if site is an
empty string.
flush site
Flush the buffer for the specified site. The actions
taken depend on the type of feed the site receives; see
newsfeeds(5). This is useful when the site is fed by a
file and batching is going to start. If site is an
empty string, then all sites are flushed and the active
file and history databases are also written out. This
command is forwarded; see below.
flushlogs
Close the log and error log files and rename them to
have a .old extension. The history database and active
file are also written out.
go reason
Re-open the history database and start accepting arti-
cles after a ``pause'' or ``throttle'' command. The
reason must either be an empty string or match the text
that was given in the earlier ``pause'' or ``throttle''
command. If a ``reject'' command was done, this will
also do an ``allow'' command if the reason matches the
text that was given in the ``reject.'' If a
``reserve'' command was done, this will also clear the
reservation if the reason matches the text that was
given in the ``reserve.'' Note that if only the his-
tory database has changed while the server is paused or
throttled, it is not necessary to send it a ``reload''
command before sending it a ``go'' command. If the
server throttled itself because it accumulated too many
I/O errors, this command will reset the error count.
If the server was not started with the ``-ny'' flag,
then this command also does a ``readers'' command with
``yes'' as the flag and reason as the text.
hangup channel
Close the socket on the specified incoming channel.
This is useful when an incoming connection appears to
be hung.
help [command]
Print a command summary for all commands, or just com-
mand if specified.
logmode
Cause the server to log its current operating mode to
syslog.
mode Print the server's operating mode as a multi-line sum-
mary of the parameters and operating state.
name nnn
Print the name of channel number nnn or of all channels
if it is an empty string.
newgroup group rest creator
Create the specified newsgroup. The rest parameter
should be the fourth field as described in active(5);
if it is not an equal sign, only the first letter is
used. The creator should be the name of the person
creating the group. If the newsgroup already exists,
this is equivalent to the ``changegroup'' command.
This is the only command that has defaults. The crea-
tor can be omitted and will default to the empty
string, and the rest parameter can be omitted and will
default to ``y''. This command can be done while the
server is paused or throttled; it will update its
internal state when a ``go'' command is sent. This
command updates the active.times (see active(5)) file.
param letter value
Change the command-line parameters of the server. The
combination of defaults make it possible to use the
text of the Control header directly. Letter is the
innd command-line option to set, and value is the new
value. For example, ``i 5'' directs the server to
allow only five incoming connections. To enable or
disable the action of the ``-n'' flag, use the letter
``y'' or ``n'', respectively, for the value.
pause reason
Pause the server so that no incoming articles are
accepted. No existing connections are closed, but the
history database is closed. This command should be
used for short-term locks, such as when replacing the
history files. If the server was not started with the
``-ny'' flag, then this command also does a ``readers''
command with ``no'' as the flag and reason as the text.
readers flag text
Allow or disallow newsreaders. If flag starts with the
letter ``n'' then newsreading is disallowed, by causing
the server to pass the text as the value of the
nnrpd(8) ``-r'' flag. If flag starts with the letter
``y'' and text is either an empty string, or the same
string that was used when newsreading was disallowed,
then newsreading will be allowed.
reject reason
Remote connections (those that would not be handed off
to nnrpd) are rejected, with reason given as the expla-
nation.
reload what reason
The server updates its in-memory copies of various con-
figuration files. What identifies what should be
reloaded. If it is an empty string or the word ``all''
then everything is reloaded; if it is the word ``his-
tory'' then the history database is closed and opened,
if it is the word ``hosts.nntp'' then the hosts.nntp(5)
file is reloaded; if it is the word ``active'' or
``newsfeeds'' then both the active and newsfeeds files
are reloaded; if it is the word ``overview.fmt'' then
the overview.fmt(5) file is reloaded. The reason is
reported to syslog. There is no way to reload the data
inn.conf(5) file; the server currently only uses the
``pathhost'' parameter, so this restriction should not
be a problem.
renumber group
Scan the spool directory for the specified newsgroup
and update the low-water mark in the active file. If
group is an empty string then all newsgroups are
scanned.
reserve reason
The next ``pause'' or ``throttle'' command must use
reason as its text. This ``reservation'' is cleared by
giving an empty string for the reason. This command is
used by programs like expire(8) that want to avoid run-
ning into other instances of each other.
rmgroup group
Remove the specified newsgroup. This is done by edit-
ing the active file. The spool directory is not
touched, and any articles in the group will be expired
using the default expiration parameters. Unlike the
``newgroup'' command, this command does not update the
active.times file.
send feed text...
The specified text is sent as a control line to the
exploder feed.
shutdown reason
The server is shut down, with the specified reason
recorded in the log and sent to all open connections.
It is a good idea to send a ``throttle'' command first.
signal sig site
Signal sig is sent to the specified site, which must be
a channel or exploder feed. Sig can be a numeric
signal number or the word ``hup,'' ``int,'' or
``term''; case is not significant.
throttle reason
Input is throttled so that all existing connections are
closed and new connections are rejected. The history
database is closed. This should be used for long-term
locks, such as when expire is being run. If the server
was not started with the ``-ny'' flag, then this com-
mand also does a ``readers'' command with ``no'' as the
flag and reason as the text.
trace item flag
Tracing is turned on or off for the specified item.
Flag should start with the letter ``y'' or ``n'' to
turn tracing on or off. If item starts is a number,
then tracing is set for the specified innd channel,
which must be for an incoming NNTP feed. If it starts
with the letter ``i'' then general innd tracing is
turned on or off. If it starts with the letter ``n''
then future nnrpd's will or will not have the ``-t''
flag enabled, as appropriate.
xabort reason
The server logs the specified reason and then invokes
the abort(3) routine.
xexec path
The server gets ready to shut itself down, but instead
of exiting it execs the specified path with all of its
original arguments. If path is ``innd'' then
/usr/local/news/bin/innd is invoked; if it is
``inndstart'' then /usr/local/news/bin/inndstart is
invoked; if it is an empty string, it will invoke the
appropriate program depending on whether or not it was
started with the ``-p'' flag; any other value is an
error.
In addition to being acted upon within the server, certain
commands can be forwarded to the appropriate child process.
If the site receiving the command is an exploder (such as
buffchan(8)) or it is a funnel that feeds into an exploder,
then the command can be forwarded. In this case, the server
will send a command line to the exploder that consists of
the ctlinnd command name. If the site funnels into an
exploder that has an asterisk (``*'') in its ``W'' flag (see
newsfeed(5)), then the site name will be appended to the
command; otherwise no argument is appended.
BUGS
Ctlinnd uses the inndcomm(3) library, and is therefore lim-
ited to server replies no larger than 4k.
HISTORY
Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.
This is revision 1.39, dated 1996/10/29.
SEE ALSO
active(5), expire(8), innd(8), inndcomm(3), inn.conf(5),
newsfeeds(5), overview.fmt(5).
Man(1) output converted with
man2html