1CTLINND(8) InterNetNews Documentation CTLINND(8)
2
6 ctlinnd - Control the main InterNetNews daemon
7
9 ctlinnd [-hs] [-t timeout] [command [argument ...]]
10
12 ctlinnd sends a message to the control channel of innd(8), the main
13 InterNetNews daemon.
14 In the normal mode of behavior, the message is sent to the server,
16 which then performs the requested action and sends back a reply with a
17 text message and an exit code for ctlinnd. If the server successfully
18 performed the command, ctlinnd will print the reply on standard output
19 and exit with a status of zero. If the server could not perform the
20 command, it will direct ctlinnd to exit with a status of one. By
21 default, ctlinnd will wait forever for a response from innd; this can
22 be changed with the -t flag.
23 The "shutdown", "xabort", and "xexec" commands do not generate a reply,
25 since they cause innd to exit. After these commands, ctlinnd will
26 always exit silently with a status of zero.
27
29 -h Prints a command summary. If a command is given along with the -h
30 flag, only the usage for that command will be given.
31 -s If the command was successful, don't print the output from innd.
33 -t timeout
35 Specifies how long to wait for the reply from the server, for
36 commands other than "shutdown", "xabort", and "xexec". timeout is
37 the number of seconds to wait. A value of zero says to wait
38 forever, and a value less than zero says not to wait at all but
39 just exit immediately with status zero. When waiting for a reply,
40 ctlinnd will check every two minutes to be sure the server is still
41 running, to make it less likely that ctlinnd will just hang.
42 The default is zero, indicating that ctlinnd should wait forever.
44
46 Here is the complete list of supported commands. Note that nearly all
47 commands have a fixed number of arguments. If a parameter may be an
48 empty string, it is still necessary to pass the empty string to ctlinnd
49 as an argument (specified in the shell as two adjacent quotes, like
50 '').
51 addhist message-id arrival expires posted token
53 Add an entry to the history database for message-id. The angle
54 brackets around message-id are optional. It should normally be
55 protected from the shell with single quotes.
56 arrival, expires, and posted should be the number of seconds since
58 epoch and indicate when the article arrived, when it expires (via
59 the Expires header field), and when it was posted (given in the
60 Date header field), respectively. expires should be 0 if the
61 article doesn't have an Expires header field. token is the storage
62 API token for the article, and may be empty.
63 This command can only be used while the server is running, and will
65 be rejected if the server is paused or throttled.
66 allow reason
68 Allow remote connections, reversing a prior "reject" command.
69 reason must be the same text given to the "reject" command, or the
70 empty string (which matches any reason).
71 begin site
73 Begin feeding site. The server will rescan the newsfeeds file to
74 find the specified site and set up a newsfeed for it. If the site
75 already existed, a "drop" for that site is done first. This
76 command is forwarded; see "NOTES" below.
77 cancel message-id
79 Remove the article with the specified message-ID from the local
80 system. This does not generate a cancel control message; it only
81 affects the local system. The angle brackets around message-ID are
82 optional. It should normally be protected from the shell with
83 single quotes (and not double quotes). For instance:
84 ctlinnd cancel 'test@foo.bar'
86 Note that the history database is updated with the specified
88 Message-ID so if an article with the same Message-ID is afterwards
89 received, it will be rejected; it is useful for rejecting spam
90 before it arrives.
91 If the server is throttled manually, this command causes it to
93 briefly open the history database. If the server is paused or
94 throttled for any other reason, this command is rejected.
95 changegroup group status
97 The newsgroup group is changed so that its status (the fourth field
98 in the active file) becomes status. This may be used to make an
99 existing group moderated or unmoderated, for example.
100 This command, unlike "newgroup" or "rmgroup", can only be used
102 while the server is running, and will be rejected if the server is
103 paused or throttled.
104 checkfile
106 Check the syntax of the newsfeeds file and display a message if any
107 errors are found. The details of the errors are reported to
108 syslog.
109 drop site
111 Flush and drop site from the server's list of active feeds. This
112 command is forwarded; see "NOTES" below.
113 feedinfo site
115 Print detailed information about the state of the feed to site, or
116 brief status about all feeds if site is the empty string.
117 flush site
119 Flush the buffer for the specified site. The action taken depends
120 on the type of feed the site receives; see newsfeeds(5) for more
121 information. This is useful when the site is being fed by a file
122 and batching is about to start, or to cleanly shut down and respawn
123 a channel feed. If site is an empty string, all sites are flushed
124 and the active file and history database are also flushed to disk.
125 This command is forwarded; see "NOTES" below.
126 Flushing the innfeed channel feed is the recommended method of
128 restarting innfeed to pick up new configuration. innd will spawn a
129 new innfeed process while the old process shuts down cleanly.
130 flushlogs
132 Close the news and error log files and rename them to add ".old" to
133 the file name, then open fresh news and error logs. The active
134 file and history database are also flushed to disk. Exploder and
135 process channels are reopened so that they properly take into
136 account the new log files.
137 go reason
139 Re-open the history database and start accepting articles again,
140 reversing a previous "pause" or "throttle" command. reason must be
141 either the empty string or match the text that was given to the
142 earlier "pause" or "throttle" command.
143 If a "reject" command is in effect, this will also reverse it by
145 doing the equivalent of an "allow" command if the reason matches
146 reason. Likewise, if a "reserve" command had been given, this will
147 clear the reservation if reason matches the text that was given to
148 "reserve".
149 The history database is automatically closed on "throttle" or
151 "pause" and reopened on "go", so the history database can be
152 replaced during the pause or throttle without requiring an explicit
153 "reload" command. If any other configuration files or the active
154 file were modified, a "reload" command should be given to force the
155 server to re-read those files.
156 If the server throttled itself because it accumulated too many I/O
158 errors, this command will reset the error count.
159 If innd was not started with the -n y flag, this command also does
161 the equivalent of a "readers" command with "yes" as the flag and
162 reason as the text.
163 hangup channel
165 Close the socket for the specified incoming channel. This may be
166 useful when an incoming connection appears to be hung (although
167 innd will close idle connections automatically after a timeout, as
168 set with peertimeout in inn.conf).
169 help [command]
171 Print a command summary for all commands, or just command if one is
172 specified. This is equivalent to the -h option.
173 kill signal site
175 Signal signal is sent to the process underlying the specified site,
176 which must be a channel or exploder feed. signal may be a numeric
177 signal number or one of "hup", "int", or "term"; case is not
178 significant.
179 logmode
181 Cause the server to log its current operating mode to syslog.
182 lowmark file
184 Reset the low water marks in the active file based on the contents
185 of file. Each line in file must be of the form:
186 group low-value
188 For example:
190 comp.lang.c++ 243
192 This command is mostly used by news.daily to update the active file
194 after nightly expiration.
195 mode
197 Print the server's operating mode as a multi-line summary of the
198 parameters and the operating state. The parameters in the output
199 correspond to command-line flags to innd and give the current
200 settings of those parameters that can be overridden by command-line
201 flags.
202 name channel
204 Print the name and relevant information for the given incoming or
205 outgoing channel number, or for all channels if channel is an empty
206 string. The response is formatted as:
207 <name>:<number>:<type>:<idle>:<status>
209 where <name> is the name of the channel, <number> is its number
211 (generally the same as the file descriptor assigned to it), <idle>
212 is the idle time for an NNTP channel or the process ID for a
213 process channel, and <status> is the status for NNTP channels.
214 The <type> field is one of the following values:
216 control Control channel for ctlinnd
218 file An outgoing file feed
219 localconn Local channel used by nnrpd and rnews for posting
220 nntp NNTP channel for remote connections
221 proc The process for a process feed
222 remconn The channel that accepts new remote connections
223 Channel status indicates whether the channel is paused or not.
225 Nothing is shown unless the channel is paused, in which case
226 "paused" is shown. A channel will be paused automatically if the
227 number of remote connections for that label in incoming.conf is
228 greater than max-connections within hold-time seconds.
229 newgroup group [status [creator]]
231 Create the specified newsgroup. The status parameter is the fourth
232 field of the active file entry, as described in active(5). If it
233 is not an equal sign, only the first character is used. creator
234 should be the identity of the person creating the group. If the
235 newsgroup already exists, this is equivalent to the "changegroup"
236 command.
237 creator, encoded in UTF-8 if given, may be omitted; if so, it will
239 default to the newsmaster (as specified at configure time, normally
240 "usenet"). status may also be omitted; if so, it will default to
241 "y" (a normal, unmoderated group). The combination of defaults
242 make it possible to use the text of the Control header field
243 directly (although don't do this without checking the syntactic
244 validity of the header field first).
245 This command can only be done while the server is running or
247 throttled manually. It will update its internal state when a "go"
248 command is sent. This command updates the active.times file as
249 well. This command is forwarded; see "NOTES" below.
250 param letter value
252 Change the specified server parameter. letter is the innd command-
253 line option to set and value is the new value. For example:
254 ctlinnd param i 5
256 would direct the server to allow only five incoming connections.
258 To enable or disable the action of the -n flag, use "n" for the
259 letter and "y" or "n", respectively, for the value.
260 The supported values for letter are "a", "c", "H", "i", "l", "n",
262 "o", "T", "t", and "X".
263 pause reason
265 Pause the server so that no incoming articles are accepted. No
266 existing connections are closed, but the history database is
267 closed. This should be used for short-term locks, such as when
268 replacing the history database. If the server was not started with
269 the -n y flag, this command also does the equivalent of a "readers"
270 command with "no" as the flag and reason as the text, encoded in
271 UTF-8.
272 perl flag
274 Enable or disable Perl filtering on every article received by innd.
275 This command is only available if INN was built with Perl filtering
276 support. If flag starts with "y", filtering is enabled; if it
277 starts with "n", filtering is disabled.
278 When filtering is disabled, if the filter_innd.pl Perl filter
280 defined a function "filter_end", it will be called prior to the
281 deactivation of the filter.
282 Note that enabling or disabling Perl filtering on every post
284 received by nnrpd is parameterized with the perlfilter access
285 parameter in readers.conf.
286 python flag
288 Enable or disable Python filtering on every article received by
289 innd. This command is only available if INN was built with Python
290 filtering support. If flag starts with "y", filtering is enabled;
291 if it starts with "n", filtering is disabled.
292 readers flag text
294 Allow or disallow readers. If flag starts with the letter "n",
295 then reading is disallowed by causing the server to pass text as
296 the value of the -r flag to nnrpd. If flag starts with the letter
297 "y" and text is either an empty string or the same string, encoded
298 in UTF-8, that was used when reading was disabled, reading will be
299 re-enabled.
300 The advantage of this parameter over noreader in inn.conf is that
302 it permits specifying a custom message.
303 This command has no effect if nnrpd is being run separately rather
305 than spawned by innd.
306 reject reason
308 Remote connections (those that would not be handed off to nnrpd)
309 are rejected with reason given as the explanation, encoded in
310 UTF-8. Existing connections are not closed.
311 reload what reason
313 Update the in-memory copy of server configuration files. what
314 identifies what should be reloaded, and reason is reported to
315 syslog in the message noting the reload.
316 There is no way to reload inn.conf, storage.conf, or other
318 configuration files for the storage or overview backends. To pick
319 up changes to those files, use "ctlinnd xexec innd" to restart
320 innd.
321 If what is the empty string or the word "all", everything is
323 reloaded. If it is the word "history", the history database is
324 closed and re-opened. If it is the word "incoming.conf", the
325 corresponding file is reloaded. If it is the word "active" or
326 "newsfeeds", both the active and newsfeeds files are reloaded,
327 which will also cause all outgoing feeds to be flushed and
328 restarted.
329 If what is the word "filter.perl", the filter_innd.pl file is
331 reloaded. (This file is however not available for reloading unless
332 INN was compiled with Perl filtering support.) If the Perl filter
333 defined a function "filter_before_reload", it will be called prior
334 to re-reading filter_innd.pl. If the Perl function
335 "filter_after_reload" is defined, it will be called after
336 filter_innd.pl has been reloaded. Reloading the Perl filter does
337 not enable filtering if it has been disabled; use "perl y" to do
338 this instead. startup_innd.pl cannot be reloaded.
339 If what is the word "filter.python", the filter_innd.py file is
341 reloaded. (This file is however not available for reloading unless
342 INN was compiled with Python filtering support.) If a Python
343 method named "filter_before_reload" exists, it will be called prior
344 to re-reading filter_innd.py. If a Python method named "__init__"
345 exists, it will be called after filter_innd.py has been reloaded.
346 Reloading the Python filter does not enable filtering if it has
347 been disabled; use "python y" to do this.
348 renumber group
350 Update the low water and high water marks for group in the active
351 file based on the information in the overview database. Regardless
352 of the contents of the overview database, the high water mark will
353 not be decreased. (Decreasing it may cause duplicate article
354 numbers to be assigned after a crash, which can cause serious
355 problems with the tradspool storage method.) If group is the empty
356 string, all newsgroups are renumbered. Renumber only works if
357 overview data has been created (if enableoverview is set to true in
358 inn.conf).
359 renumberlow file
361 Identical to the "lowmark" command.
362 reserve reason
364 Require the next "pause" or "throttle" command to use reason as its
365 reason, encoded in UTF-8. This reservation is cleared by giving an
366 empty string for the reason. This is used by programs like expire
367 to coordinate pauses and throttles of the server and avoid
368 trampling on other instances of themselves.
369 rmgroup group
371 Remove the specified newsgroup. The group is removed from the
372 active file and its overview information is purged, making it
373 immediately unavailable to readers. Unlike the "newgroup" command,
374 this command does not update the active.times file.
375 This command can only be done while the server is running or
377 throttled manually. This command is forwarded; see "NOTES" below.
378 send feed text
380 The specified text is sent as a control line to the exploder feed.
381 shutdown reason
383 The server is shut down, with the specified reason recorded in the
384 log and sent to all open connections. It is a good idea to send a
385 "throttle" command first so that feeds can be shut down more
386 gracefully.
387 If Perl or Python filtering is compiled in and enabled, certain
389 functions are called at "throttle" or "shutdown" (to save filter
390 state to disk, for example). Consult the embedded filter
391 documentation for details.
392 stathist (off | filename)
394 Enable or disable generation of history performance statistics. If
395 the parameter is "off", no statistics are gathered. Otherwise,
396 statistics are written to the specified file. A parser for this
397 file is provided in the contrib tree of the INN distribution. See
398 stathist in inn.conf(5) for information on how to set the default.
399 status (off | interval)
401 Adjust the frequency with which innd reports status information to
402 syslog. Status reporting is turned off if "off" or 0 is given as
403 the argument. Otherwise, status will be reported every interval
404 seconds. See status in inn.conf(5) for information on how to set
405 the default.
406 throttle reason
408 Close all existing incoming connections and outgoing feeds, and
409 reject new connections. Close the history database. This should
410 be used for long-term locks or for running a large number of
411 "newgroup" and "rmgroup" commands without restarting all outgoing
412 feeds between each one. (Note that changing the status of existing
413 newsgroups when the server is throttled cannot be done.)
414 If the server was not started with the -n y flag, then this command
416 also does the equivalent of a "readers" command with "no" as the
417 flag and reason as the text, encoded in UTF-8.
418 timer (off | interval)
420 Adjust the frequency with which innd reports performance
421 information to syslog. Performance monitoring is turned off if
422 "off" or 0 is given as the argument. Otherwise, statistics will be
423 reported every interval seconds to syslog. See timer in
424 inn.conf(5) for information on how to set the default.
425 trace item flag
427 Turn tracing on or off for the specified item. flag should start
428 with the letter "y" or "n" to turn tracing on or off, respectively.
429 If item starts with a number, tracing is set up for the specified
430 innd channel, which must be an incoming NNTP feed. If it starts
431 with the letter "i", general innd tracing is turned on or off. If
432 it starts with the letter "n", future nnrpd processes spawned by
433 "innd" will or will not be passed the -t flag, as appropriate.
434 This will not affect any nnrpd processes already running, or nnrpd
435 processes started by some means other than innd.
436 xabort reason
438 Log the specified reason and then abort. On most systems, this
439 will cause innd to dump a core file. This is only useful for
440 debugging.
441 xexec path
443 Shut down the server, but then rather than exiting, exec innd with
444 all of its original arguments except for -r. path may be either
445 "innd" or an empty string, both of which are equivalent. Any other
446 value is an error.
447 This is the easiest way to start a new copy of innd after upgrading
449 or reload configuration files that can't be reloaded via the
450 "reload" command.
451
453 In addition to being acted on by the server, certain commands can be
454 forwarded to an appropriate child process. If the site receiving the
455 command is an exploder (such as buffchan) or a funnel that feeds into
456 an exploder, the command can be forwarded. In this case, the server
457 will send a command line to the exploder that consists of the ctlinnd
458 command name. If the site funnels into an exploder that has an
459 asterisk ("*") in its "W" flag (see newsfeeds(5) for more information
460 on feed specifications), the site name will be appended to the command;
461 otherwise, no argument is appended.
462
464 ctlinnd uses Unix domain sockets on most systems to communicate with
465 innd and is therefore limited by whatever maximum packet size the
466 operating system imposes on Unix domain datagrams. This may mean that
467 server replies are limited to 4 KB on some systems.
468
470 Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. Rewritten
471 in POD by Russ Allbery <eagle@eyrie.org>.
472
474 active(5), active.times(5), buffchan(8), incoming.conf(5), innd(8),
475 inn.conf(5), libinn_inndcomm(3), newsfeeds(5), nnrpd(8).
476INN 2.7.1 2023-03-07 CTLINND(8)