Ubuntu Manpage: ctlinnd - Control the main InterNetNews daemon

NAME

       ctlinnd - Control the main InterNetNews daemon

SYNOPSIS

       ctlinnd [-hs] [-t timeout] [command [argument ...]]

DESCRIPTION

       ctlinnd sends a message to the control channel of innd(8), the main InterNetNews daemon.

       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 an exit code for ctlinnd.  If the server
       successfully performed the command, ctlinnd will print the reply on standard output and exit with a
       status of zero.  If the server could not perform the command, it will direct ctlinnd to exit with a
       status of one.  By default, ctlinnd will wait forever for a response from innd; this can be changed with
       the -t flag.

       The "shutdown", "xabort", and "xexec" commands do not generate a reply, since they cause innd to exit.
       After these commands, ctlinnd will always exit silently with a status of zero.

OPTIONS

       -h  Prints  a  command  summary.   If  a command is given along with the -h flag, only the usage for that
           command will be given.

       -s  If the command was successful, don't print the output from innd.

       -t timeout
           Specifies how long to wait for the reply  from  the  server,  for  commands  other  than  "shutdown",
           "xabort",  and  "xexec".   timeout  is  the  number of seconds to wait.  A value of zero says to wait
           forever, and a value less than zero says not to wait at all but just  exit  immediately  with  status
           zero.   When waiting for a reply, ctlinnd will check every two minutes to be sure the server is still
           running, to make it less likely that ctlinnd will just hang.

           The default is zero, indicating that ctlinnd should wait forever.

COMMANDS

Here is the complete list of supported commands. Note that nearly all commands have a fixed number of
arguments. If a parameter may be an empty string, it is still necessary to pass the empty string to
ctlinnd as an argument (specified in the shell as two adjacent quotes, like '').

addhist message-id arrival expires posted token
Add an entry to the history database for message-id. The angle brackets around the message-ID are
optional. It should normally be protected from the shell with single quotes.

arrival, expires, and posted should be the number of seconds since epoch and indicate when the
article arrived, when it expires (via the Expires: header), and when it was posted (given in the
Date: header), respectively. expires should be 0 if the article doesn't have an Expires: header.
token is the storage API token for the article, and may be empty.

This command can only be used while the server is running, and will be rejected if the server is
paused or throttled.

allow reason
Allow remote connections, reversing a prior "reject" command. reason must be the same text given to
the "reject" command, or the empty string (which matches any reason).

begin site
Begin feeding site. The server will rescan the newsfeeds file to find the specified site and set up
a newsfeed for it. If the site already existed, a "drop" for that site is done first. This command
is forwarded; see NOTES below.

cancel message-id
Remove the article with the specified message-ID from the local system. This does not generate a
cancel control message; it only affects the local system. The angle brackets around the message-ID
are optional. It should normally be protected from the shell with single quotes (and not double
quotes). For instance:

ctlinnd cancel 'test@foo.bar'

Note that the history database is updated with the specified message-ID so if an article with the
same message-ID is afterwards received, it will be rejected; it is useful for rejecting spam before
it arrives.

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 status
The newsgroup group is changed so that its status (the fourth field in the active file) becomes
status. This may be used to make an existing group moderated or unmoderated, for example.

This command, unlike "newgroup" or "rmgroup", can only be used while the server is running, and will
be rejected if the server is paused or throttled.

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.

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 brief status about all feeds if
site is the empty string.

flush site
Flush the buffer for the specified site. The action taken depends on the type of feed the site
receives; see newsfeeds(5) for more information. This is useful when the site is being fed by a file
and batching is about to start, or to cleanly shut down and respawn a channel feed. If site is an
empty string, all sites are flushed and the active file and history database are also flushed to
disk. This command is forwarded; see NOTES below.

Flushing the innfeed channel feed is the recommended method of restarting innfeed to pick up new
configuration. innd will spawn a new innfeed process while the old process shuts down cleanly.

flushlogs
Close the news and error log files and rename them to add ".old" to the file name, then open fresh
news and error logs. The active file and history database are also flushed to disk.

go reason
Re-open the history database and start accepting articles again, reversing a previous "pause" or
"throttle" command. reason must be either the empty string or match the text that was given to the
earlier "pause" or "throttle" command.

If a "reject" command is in effect, this will also reverse it by doing the equivalent of an "allow"
command if the reason matches reason. Likewise, if a "reserve" command had been given, this will
clear the reservation if reason matches the text that was given to "reserve".

The history database is automatically closed on "throttle" or "pause" and reopened on "go", so the
history database can be replaced during the pause or throttle without requiring an explicit "reload"
command. If any other configuration files or the active file were modified, a "reload" command
should be given to force the server to re-read those files.

If the server throttled itself because it accumulated too many I/O errors, this command will reset
the error count.

If innd was not started with the -n y flag, this command also does the equivalent of a "readers"
command with "yes" as the flag and reason as the text.

hangup channel
Close the socket for the specified incoming channel. This may be useful when an incoming connection
appears to be hung (although innd will close idle connections automatically after a timeout).

help [command]
Print a command summary for all commands, or just command if one is specified. This is equivalent to
the -h option.

kill signal site
Signal signal is sent to the process underlying the specified site, which must be a channel or
exploder feed. signal may be a numeric signal number or one of "hup", "int", or "term"; case is not
significant.

logmode
Cause the server to log its current operating mode to syslog.

lowmark file
Reset the low water marks in the active file based on the contents of file. Each line in file must
be of the form:

group low-value

For example:

comp.lang.c++ 243

This command is mostly used by news.daily to update the active file after nightly expiration.

mode
Print the server's operating mode as a multi-line summary of the parameters and the operating state.
The parameters in the output correspond to command-line flags to innd and give the current settings
of those parameters that can be overridden by command-line flags.

name channel
Print the name and relevant information for the given incoming or outgoing channel, or for all
channels if channel is an empty string. The response is formatted as:

where <name> is the name of the channel, <number> is its number (generally the same as the file
descriptor assigned to it), <idle> is the idle time for an NNTP channel or the process ID for a
process channel, and <status> is the status for NNTP channels.

The type is one of the following values:

control Control channel for ctlinnd
file An outgoing file feed
localconn Local channel used by nnrpd and rnews for posting
nntp NNTP channel for remote connections
proc The process for a process feed
remconn The channel that accepts new remote connections

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 will be paused automatically if the number of
remote connections for that label in incoming.conf is greater than max-connections within hold-time
seconds.

newgroup group [status [creator]]
Create the specified newsgroup. The status parameter is the fourth field of the active file entry,
as described in active(5). If it is not an equal sign, only the first character is used. creator
should be the identity of the person creating the group. If the newsgroup already exists, this is
equivalent to the "changegroup" command.

creator, encoded in UTF-8 if given, may be omitted; if so, it will default to the newsmaster (as
specified at configure time, normally "usenet"). status may also be omitted; if so, it will default
to "y" (a normal, unmoderated group). The combination of defaults make it possible to use the text
of the Control: header directly (although don't do this without checking the syntactic validity of
the header first).

This command can only be done while the server is running or throttled manually. It will update its
internal state when a "go" command is sent. This command updates the active.times file as well.
This command is forwarded; see NOTES below.

param letter value
Change the specified server parameter. letter is the innd command-line option to set and value is
the new value. For example:

ctlinnd param i 5

would direct the server to allow only five incoming connections. To enable or disable the action of
the -n flag, use "n" for the letter and "y" or "n", respectively, for the value.

The supported values for letter are "a", "c", "H", "i", "l", "n", "o", "T", "t", and "X".

pause reason
Pause the server so that no incoming articles are accepted. No existing connections are closed, but
the history database is closed. This should be used for short-term locks, such as when replacing the
history database. If the server was not started with the -n y flag, this command also does the
equivalent of a "readers" command with "no" as the flag and reason as the text, encoded in UTF-8.

perl flag
Enable or disable Perl filtering. This command is only available if INN was built with Perl
filtering support. If flag starts with "y", filtering is enabled; if it starts with "n", filtering
is disabled.

When filtering is disabled, if the filter_innd.pl Perl filter defined a function "filter_end", it
will be called prior to the deactivation of the filter.

python flag
Enable or disable Python filtering. This command is only available if INN was built with Python
filtering support. If flag starts with "y", filtering is enabled; if it starts with "n", filtering
is disabled.

readers flag text
Allow or disallow readers. If flag starts with the letter "n", then reading is disallowed by causing
the server to pass text as the value of the -r flag to nnrpd. If flag starts with the letter "y" and
text is either an empty string or the same string, encoded in UTF-8, that was used when reading was
disabled, reading will be re-enabled.

This command has no effect if nnrpd is being run separately rather than spawned by innd.

reject reason
Remote connections (those that would not be handed off to nnrpd) are rejected with reason given as
the explanation, encoded in UTF-8. Existing connections are not closed.

reload what reason
Update the in-memory copy of server configuration files. what identifies what should be reloaded,
and reason is reported to syslog in the message noting the reload.

There is no way to reload inn.conf, storage.conf, or other configuration files for the storage or
overview backends. To pick up changes to those files, use "ctlinnd xexec innd" to restart innd.

If what is the empty string or the word "all", everything is reloaded. If it is the word "history",
the history database is closed and re-opened. If it is the word "incoming.conf", the corresponding
file is reloaded. If it is the word "active" or "newsfeeds", both the active and newsfeeds files are
reloaded, which will also cause all outgoing feeds to be flushed and restarted.

If what is the word "filter.perl", the filter_innd.pl file is reloaded. If the Perl filter defined a
function "filter_before_reload", it will be called prior to re-reading filter_innd.pl. If the Perl
function "filter_after_reload" is defined, it will be called after filter_innd.pl has been reloaded.
Reloading the Perl filter does not enable filtering if it has been disabled; use "perl y" to do this
instead. startup_innd.pl cannot be reloaded. This file is not available for reloading unless INN
was compiled with Perl filtering support.

If what is the word "filter.python", the filter_innd.py file is reloaded. If a Python method named
"filter_before_reload" exists, it will be called prior to re-reading 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 has been disabled; use "python y" to do this. This
file is not available for reloading unless INN was compiled with Python filtering support.

renumber group
Update the low water and high water marks for group in the active file based on the information in
the overview database. Regardless of the contents of the overview database, the high 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 the empty string,
all newsgroups are renumbered. Renumber only works if overview data has been created (if
enableoverview is set to true in inn.conf).

renumberlow file
Identical to the "lowmark" command.

reserve reason
Require the next "pause" or "throttle" command to use reason as its reason, encoded in UTF-8. This
reservation is cleared by giving an empty string for the reason. This is used by programs like
expire to coordinate pauses and throttles of the server and avoid trampling on other instances of
themselves.

rmgroup group
Remove the specified newsgroup. The group is removed from the active file and its overview
information is purged, making it immediately unavailable to readers. Unlike the "newgroup" command,
this command does not update the active.times file.

This command can only be done while the server is running or throttled manually. 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 so that feeds can be shut down
more gracefully.

If Perl or Python filtering is compiled in and enabled, certain functions are called at "throttle" or
"shutdown" (to save filter state to disk, for example). Consult the embedded filter documentation
for details.

stathist (off | filename)
Enable or disable generation of history performance statistics. If the parameter is "off", no
statistics are gathered. Otherwise, statistics are written to the specified file. A parser for this
file is provided in the contrib tree of the INN distribution.

status (off | interval)
Adjust the frequency with which innd reports status information to syslog. Status reporting is
turned off if "off" or 0 is given as the argument. Otherwise, status will be reported every interval
seconds. See status in inn.conf(5) for information on how to set the default.

throttle reason
Close all existing incoming connections and outgoing feeds and reject new connections. Close the
history database. This should be used for long-term locks or for running a large number of
"newgroup" and "rmgroup" commands without restarting all outgoing feeds between each one. (Note that
changing the status of existing newsgroups when the server is throttled cannot be done.)

If the server was not started with the -n y flag, then this command also does the equivalent of a
"readers" command with "no" as the flag and reason as the text, encoded in UTF-8.

timer (off | interval)
Adjust the frequency with which innd reports performance information to syslog. Performance
monitoring is turned off if "off" or 0 is given as the argument. Otherwise, statistics will be
reported every interval seconds to syslog. See timer in inn.conf(5) for information on how to set
the default.

trace item flag
Turn tracing on or off for the specified item. flag should start with the letter "y" or "n" to turn
tracing on or off, respectively. If item starts with a number, tracing is set up for the specified
innd channel, which must be an incoming NNTP feed. If it starts with the letter "i", general innd
tracing is turned on or off. If it starts with the letter "n", future nnrpd processes spawned by
"innd" will or will not be passed the -t flag, as appropriate. This will not affect any nnrpd
processes already running, or nnrpd processes started by some means other than innd.

xabort reason
Log the specified reason and then abort. On most systems, this will cause innd to dump a core file.
This is only useful for debugging.

xexec path
Shut down the server, but then rather than exiting, exec innd with all of its original arguments
except for -r. path may be either "innd" or an empty string, both of which are equivalent. Any
other value is an error.

This is the easiest way to start a new copy of innd after upgrading or reload configuration files
that can't be reloaded via the "reload" command.

NOTES

       In addition to being acted on by the server, certain commands can be forwarded to  an  appropriate  child
       process.  If the site receiving the command is an exploder (such as buffchan) or a funnel that feeds into
       an  exploder,  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) for more information on feed specifications), the site
       name will be appended to the command; otherwise, no argument is appended.

BUGS

       ctlinnd uses Unix domain sockets on most systems to communicate with innd and  is  therefore  limited  by
       whatever  maximum  packet size the operating system imposes on Unix domain datagrams.  This may mean that
       server replies are limited to 4 KB on some systems.

HISTORY

       Written  by  Rich  $alz  <rsalz@uunet.uu.net>  for  InterNetNews.   Rewritten  in  POD  by  Russ  Allbery
       <rra@stanford.edu>.

       $Id: ctlinnd.pod 9247 2011-07-17 18:03:49Z iulius $