CTLINND
Section: Maintenance Commands (8)
Index
Return to Main Contents
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.
If the ``-s'' flag is
used, then no message will be printed if the command was successful.
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.''
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.
- 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.
- 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.
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
/news/news/etc/innd
is invoked; if it is ``inndstart'' then
/news/news/etc/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
newsfweed(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.30, dated 1993/03/18.
SEE ALSO
active(5),
expire(8),
innd(8),
inndcomm(3),
inn.conf(5),
newsfeeds(5),
overview.fmt(5).
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- BUGS
-
- HISTORY
-
- SEE ALSO
-
This document was created by
man2html,
using the manual pages.
Time: 04:38:16 GMT, December 02, 2024