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.
xexeccommands do not generate a reply, since they cause innd to exit. After these commands, ctlinnd will always exit silently with a status of zero.
|-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
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 ).
|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
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
|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
|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:
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
|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
|go reason||Re-open the history database and start accepting articles again, reversing a previous
The history database is automatically closed on
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
|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
|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:
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:
Channel status indicates whether the channel is paused or not. Nothing is shown unless the channel is paused, in which case
|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
creator, encoded in UTF-8 if given, may be omitted; if so, it will default to the newsmaster (as specified at configure time, normally
This command can only be done while the server is running or throttled manually. It will update its internal state when a
|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:
would direct the server to allow only five incoming connections. To enable or disable the action of the -n flag, use
The supported values for letter are
|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
|perl flag||Enable or disable Perl filtering. This command is only available if INN was built with Perl filtering support. If flag starts with
When filtering is disabled, if the filter_innd.pl Perl filter defined a function
|python flag||Enable or disable Python filtering. This command is only available if INN was built with Python filtering support. If flag starts with
|readers flag text||Allow or disallow readers. If flag starts with the letter
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
If what is the empty string or the word
If what is the word
If what is the word
|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
|reserve reason||Require the next
|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
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
If Perl or Python filtering is compiled in and enabled, certain functions are called at
|stathist (off | filename)||Enable or disable generation of history performance statistics. If the parameter is
|status (off | interval)||Adjust the frequency with which innd reports status information to syslog. Status reporting is turned off if
|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
If the server was not started with the -n y flag, then this command also does the equivalent of a
|timer (off | interval)||Adjust the frequency with which innd reports performance information to syslog. Performance monitoring is turned off if
|trace item flag||Turn tracing on or off for the specified item. flag should start with the letter
|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
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
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
Wflag (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.