From Linux Man Pages
ctlinnd - control the InterNetNews daemon
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. (Note that ctlinnd need not always exit immediately, see the ``-t flag.) The
``shutdown, ``xabort, and ``xexec commands do not generate a reply (because once innd has successfully
exited, it is too late to send a reply to ctlinnd); after these commands, 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 timeout
The ``-t flag can be used to specify how long to wait for the reply from the server (for commands other
than ``shutdown, ``xabort, and ``xexec). 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 (that is, exit
immediately with status zero). 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 set as <CTLINND_TIMEOUT
in include/config.h> (typically 0).
-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.
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 token
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 numbers indicating the number of seconds since the
epoch. Exp being zero indicates the article does not have an Expires header. Token is the storage API
token indicating where the article is stored. If the server is throttled manually, this command causes it
to briefly open the history database. If the server is paused or throttled for any other reason, this
command is rejected.
allow reason
Remote connections are allowed. The reason must be the same text given with an earlier ``reject com-
mand, or an empty string.
begin site
Begin feeding site. This will cause the server to rescan the newsfeeds 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 NOTES 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 throttled manually, this command causes it to
briefly open the history database. If the server is paused or throttled for any other reason, this com-
mand is rejected.
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.
This command can only be used while the server is running (not throttled), unlike newgroup or rmgroup.
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 NOTES 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.
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 about 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 NOTES 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 rea-
son 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.
kill signal site
Signal signal is sent to the specified site, which must be a channel or exploder feed. Signal can be a
numeric signal number or the word ``hup, ``int, or ``term; case is not significant.
lowmark file
Reset the lowmarks in the active file based on the contents of the given file. Each line in the file must
be of the form:
group low-value
for example
comp.lang.c++ 243
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 and relevant information of channel number nnn, or of all channels if it is an empty
string. The response is formatted as:
f1:f2:f3:f4:f5
Where the meanings of the fields are:
f1 name of this channel
f2 channel number
f3 channel type
f4 idle time for this channel (nntp type)
or process id (process type)
f5 channel status (nntp type)
The channel type (f3) is one of following:
control control channel which is used
for ctlinnd
file file channel which is used for
file feed
localconn local channel which is used for
nnrpd or rnews
nntp nntp channel which is used for
current remote connection
proc process channel which is used
for process feed
remconn remote channel which will be
used for nntp
Channel status indicates whether the channel is paused or not. Nothing is shown unless the channel is
paused, in which case ``paused is shown. A channel is paused if the number of remote connection for
that label in incoming.conf is beyond ``max-connections within ``hold-time seconds of connection.
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 identity of the per-
son creating the group as described in active(5). 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 newsmaster (as specified at configure time, ``usenet by default), and the rest
parameter can be omitted and will default to ``y. This command can only be done while the server is
throttled manually or running; it will update its internal state when a ``go command is sent. This com-
mand updates the active.times file (see active.times(5)). This command is forwarded; see NOTES below.
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 ``read-
ers command with ``no as the flag and reason as the text.
perl flag
Enable or disable perl news filtering, if <--with-perl is specified at configure>. If flag starts with
the letter ``y then filtering is enabled. If it starts with ``n, then filtering is disabled.
python flag
Enable or disable Python news filtering, if <--with-python is specified at configure>. If flag starts
with the letter ``y then filtering is enabled. If it starts with ``n, then filtering is disabled.
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. The reason is reported to syslog.
There is no way to reload the inn.conf file; use ctlinnd xexec innd instead.
If what 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 ``incoming.conf then the incoming.conf
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 file is reloaded.
If <--with-perl is specified at configure> and 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_innd.pl. If a Perl procedure named ``filter_after_reload exists, it will be called
after filter_innd.pl. has been reloaded. Reloading the Perl filter does not enable filtering if it is
disabled; use perl y to do this. The startup_innd.pl file cannot be reloaded.
If <--with-python is specified at configure> and it is the word ``filter.python then the filter_innd.py
file is reloaded. If a Python method named ``filter_before_reload exists, it will be called prior to
rereading filter_innd.py. If a Python method named ``__init__ exists, it will be called after fil-
ter_innd.py. has been reloaded. Reloading the Python filter does not enable filtering if it is disabled;
use python y to do this. If <--with-tcl is specified at configure> and it is the word ``filter.tcl then
the filter.tcl file is reloaded. If a TCL procedure named ``filter_before_reload exists, it will be
called prior to rereading filter.tcl. If a TCL procedure named ``filter_after_reload exists, it will be
called after filter.tcl has been reloaded. Reloading the Tcl filter does not enable filtering if it is
disabled; use filter to do this. The startup.tcl file cannot be reloaded.
renumber group
Scan overview database for the specified newsgroup and update the low-water mark and hi-water mark in the
active file. Regardless of the content of the overview database, the hi-water mark will not be decreased
(decreasing it may cause duplicate article numbers to be assigned after a crash, which can cause serious
problems with the tradspool storage method). If group is an empty string then all newsgroups are scanned.
Renumber only works if overview data has been created. (See the description of ``enableoverview in
inn.conf(5) for details about overview creation.)
renumberlow file
This command does same as ``lowmark command.
reserve reason
The next ``pause or ``throttle command must use reason as its reason. 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 still be expired using the default expiration parameters.
Unlike the ``newgroup command, this command does not update the active.times file. This command can be
done while the server is only throttled manually or running. This command is forwarded; see NOTES below.
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.
If Perl, Python, or TCL filtering is compiled in and enabled, certain functions are called at ``throttle
or ``shutdown (for example, to save filter state to disk), consult the embedded filter documentation for
details.
stathist off|filename
Enable or disable generation of history performance statistics. If the parameter is ``off, no statis-
tics are gathered. Otherwise statistics are written to the specified file. The file can be parsed by
contrib/stathist.pl.
status off|interval
Adjust frequency in seconds at which innd reports status informatoin to syslog. Status reporting is
turned off if ``off or ``0 is specified. See ``status in inn.conf(5) for information on how to set
the startup default.
tcl flag
Enable or disable Tcl news filtering, if <--with-tcl is specified at configure>. If flag starts with the
letter ``y then filtering is enabled. If it starts with ``n, then filtering is disabled.
throttle reason
Input is throttled so that all existing connections are closed and new connections are rejected. The his-
tory 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.
timer off|interval
Performance monitoring is turned off if ``off or ``0 is specified, otherwise, statistics will be
reported every interval seconds to syslog. See ``timer in inn.conf(5) for information on how to set the
startup default.
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 with 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. The ``n flag does not affect nnrpd's already running or using ``-D
(running as a daemon).
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 exec's <pathbin in inn.conf>/innd-
start with all of its original arguments except for ``-r. Path can be any of ``innd, ``inndstart,
or an empty string, although all three valid parameters have exactly the same effect. Any other value is
an error.
NOTES
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 newsfeeds(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
Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. This is revision 1.24.2.2, dated 2004/12/19.
RELATED
active(5), active.times(5), expire(8), innd(8), inndcomm(3), inn.conf(5), newsfeeds(5), overview.fmt(5).
CATEGORY