Ubuntu Manpage: ctlinnd - control the InterNetNews daemon

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 indicates 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 commands 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 rescan 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 forwarded; see below.

cancel <Message-ID>
Remove the article with the specified Message-ID from the local system. This does
not generate a cancel message. 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.

perl flag
Enable or disable perl news filtering. If flag starts with the letter ``y'' then
filtering is enabled. If it starts with ``n'', then filtering is disabled.

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 articles 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 history 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 command 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 summary 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 creator 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 explanation.

reload what reason
The server updates its in-memory copies of various configuration 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 ``history'' 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. If it is the word
``filter.perl'' then the filter_innd.pl file is reloaded. If a Perl procedure
named ``filter_before_reload'' exists, it will be called prior to rereading
filter.tcl. If a Perl procedure named ``filter_after_reload'' exists, it will be
called after filter.pl has been reloaded. Reloading the Perl filter does not
enable filtering if it is disabled; use filter to do this. 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 running into other instances
of each other.

rmgroup group
Remove the specified newsgroup. This is done by editing 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 command 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/sbin/innd is invoked; if it is ``inndstart'' then /usr/sbin/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 limited to server replies no larger
       than 4k.

HISTORY