CTLINND(8)CTLINND(8)NAMEctlinnd - control the InterNetNews daemon
SYNOPSISctlinnd [ -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 com
mand, 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 wait
ing 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> (typi
cally 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 com
mand will be given.
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 direc
tory 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 throttled
manually, this command causes it to briefly open
the history database. And if the server is paused
or throttled except that case, 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(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 throttled manually, this command
causes it to briefly open the history database.
And if the server is paused or throttled except
that case, this command is rejected.
changegroup group rest
The newsgroup group is changed so that its fourth
field in the active file becomes the value speci
fied 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.
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 throt
tled 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.
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. Format is:
f1:f2:f3:f4:f5
And meaning of each field is:
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)
F3 is one of followings:
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 shows if the channel is paused or
not. Nothing is shown unless the channel is
paused. Or ``paused'' is shown. ``Paused'' status
happens, if the number of remote connection for
that label in incoming.conf(5) is beyond ``max-con
nections'' within ``hold-time'' seconds since con
nected.
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 newsmaster (as specified at
configure time, ``usenet'' by default), and the
rest parameter can be omitted and will default to
``y''. This command can be done while the server
is only throttled manually or running; it will
update its internal state when a ``go'' command is
sent. This command updates the active.times (see
active(5)) file. This command is forwarded; see
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 ``readers'' 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. 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 ``incom
ing.conf'' then the incoming.conf(5) file is
reloaded; if it is the word ``active'' or ``news
feeds'' 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
<--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 ``fil
ter_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 ``fil
ter_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
filter_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 ``fil
ter_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 dis
abled; use filter to do this. The startup.tcl file
cannot be reloaded. The reason is reported to sys_
log. There is no way to reload the data
inn.conf(5) file.
renumber group
Scan overview database for the specified newsgroup
and update the low-water mark and hi-water mark in
the active file. If group is an empty string then
all newsgroups are scanned. Renumber never works,
unless overview data is created. See the descrip
tion of ``enableoverview'' in inn.conf(5) for
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 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 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 connec
tions.
It is a good idea to send a ``throttle'' command
first.
If <--with-python is specified at configure> and a
Python method named ``filter_close'' exists, it
will be called just before innd exits.
status off|interval
innd status reporting is turned off if ``off'' or
``0'' is specified, otherwise, status will be
reported every interval seconds to syslog. 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
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 ``read
ers'' 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 is a num
ber, 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 appropri
ate. ``n'' does not affect to nnrpd with ``-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 execs <PREFIX specified with
--prefix at configure>/inndstart with all of its
original arguments except for ``-r''. Path can be
any of ``innd'', ``inndstart'' or an empty string.
any other value is an error.
In addition to being acted upon within the server, certain
commands can be forwarded to the appropriate child pro
cess. 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
Written by Rich $alz <rsalz@uunet.uu.net> for InterNet
News. This is revision 1.16.2.6, dated 2002/03/25.
SEE ALSOactive(5), expire(8), innd(8), inndcomm(3), inn.conf(5),
newsfeeds(5), overview.fmt(5).
