CTLINND(8) | InterNetNews Documentation | CTLINND(8) |
ctlinnd - Control the main InterNetNews daemon
ctlinnd [-hs] [-t timeout] [command [argument ...]]
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.
The default is zero, indicating that ctlinnd should wait forever.
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 '').
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 field), and when it was posted (given in the Date header field), respectively. expires should be "0" if the article doesn't have an Expires header field. 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.
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.
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.
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.
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.
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.
<name>:<number>:<type>:<idle>:<status>
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> field 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.
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 field directly (although don't do this without checking the syntactic validity of the header field 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.
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".
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.
Note that enabling or disabling Perl filtering on every post received by nnrpd is parameterized with the perlfilter access parameter in readers.conf.
The advantage of this parameter over noreader in inn.conf is that it permits specifying a custom message.
This command has no effect if nnrpd is being run separately rather than spawned by innd.
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. (This file is however not available for reloading unless INN was compiled with Perl filtering support.) 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.
If what is the word "filter.python", the filter_innd.py file is reloaded. (This file is however not available for reloading unless INN was compiled with Python filtering support.) 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 command can only be done while the server is running or throttled manually. This command is forwarded; see "NOTES" below.
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.
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.
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.
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.
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.
Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. Rewritten in POD by Russ Allbery <eagle@eyrie.org>.
active(5), active.times(5), buffchan(8), incoming.conf(5), innd(8), inn.conf(5), libinn_inndcomm(3), newsfeeds(5), nnrpd(8).
2025-01-07 | INN 2.7.3 |