Table of Contents
ctlinnd - control the InterNetNews daemon
ctlinnd [ -h ] [ -s
] [ -t timeout ] command [ argument... ]
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.
- -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 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 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
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'' 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 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 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.
- 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.
- 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++ 243logmode
- 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-connections'' within ``hold-time'' seconds since connected.
- 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 ``incoming.conf''
then the incoming.conf(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 <--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 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 ``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. The reason
is reported to syslog. 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 description 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 connections.
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 ``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 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. ``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 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.
Ctlinnd
uses the inndcomm(3)
library, and is therefore limited to server replies
no larger than 4k.
Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.
This is revision 1.16.2.6, dated 2002/03/25.
active(5)
, expire(8)
,
innd(8)
, inndcomm(3)
, inn.conf(5)
, newsfeeds(5)
, overview.fmt(5)
.
Table of Contents