SYNOPSIS
ctlinnd [ -h ] [ -s ] [ -t timeout ] command [ argument... ]
DESCRIPTION
Ctlinnd sends a message to the control channel of innd(8), the Inter-
NetNews 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,
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
command 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 unmoder-
ated, 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 writ-
ten 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 writ-
ten 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 reserva-
tion if the reason matches the text that was given in the
``reserve.'' Note that if only the history database has changed
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 signifi-
cant.
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
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 command updates the
active.times file (see active.times(5)). This command is for-
warded; see NOTES below.
param letter value
Change the command-line parameters of the server. The combina-
tion 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.
perl flag
Enable or disable perl news filtering, if <--with-perl is speci-
fied 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 disal-
lowed, 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.
feeds 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 fil-
ter.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 descrip-
tion 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
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 embed-
ded filter documentation for details.
stathist off|filename
Enable or disable generation of history performance statistics.
If the parameter is ``off'', no statistics are gathered. Other-
wise 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 infor-
matoin to syslog. Status reporting is turned off if ``off'' or
``0'' is specified. See ``status'' in inn.conf(5) for informa-
tion on how to set the startup default.
tcl flag
Enable or disable Tcl news filtering, if <--with-tcl is speci-
fied 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 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.
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 speci-
fied 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 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 news-
feeds(5)), then the site name will be appended to the command; other-
wise 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 7062, dated 2004-12-19.
SEE ALSO
active(5), active.times(5), expire(8), innd(8), inndcomm(3),
inn.conf(5), newsfeeds(5), overview.fmt(5).
CTLINND(8)
Man(1) output converted with
man2html