1CTLINND(8) System Manager's Manual CTLINND(8)
2
6 ctlinnd - control the InterNetNews daemon
7
9 ctlinnd [ -h ] [ -s ] [ -t timeout ] command [ argument... ]
10
12 Ctlinnd sends a message to the control channel of innd(8), the Inter‐
13 NetNews server.
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 the exit code for ctlinnd. If the server successfully
18 performed the command, ctlinnd will exit with a status of zero and
19 print the reply on standard output. If the server could not perform
20 the command (for example, it was told to remove a newsgroup that does
21 not exist), it will direct ctlinnd to exit with a status of one. (Note
22 that ctlinnd need not always exit immediately, see the ``-t'' flag.)
23 The ``shutdown'', ``xabort'', and ``xexec'' commands do not generate a
24 reply (because once innd has successfully exited, it is too late to
25 send a reply to ctlinnd); after these commands, ctlinnd will always
26 exit silently with a status of zero.
27
29 -s If the ``-s'' flag is used, then no message will be printed if
30 the command was successful.
31 -t timeout
33 The ``-t'' flag can be used to specify how long to wait for the
34 reply from the server (for commands other than ``shutdown'',
35 ``xabort'', and ``xexec''). The timeout value specifies the
36 number of seconds to wait. A value of zero waits forever, and a
37 value less than zero indicates that no reply is needed (that is,
38 exit immediately with status zero). When waiting for a reply,
39 ctlinnd will try every two minutes to see if the server is still
40 running, so it is unlikely that ``-t0'' will hang. The default
41 is set as <CTLINND_TIMEOUT in include/config.h> (typically 0).
42 -h To see a command summary, use the ``-h'' flag. If a command is
44 included when ctlinnd is invoked with the ``-h'' flag, then only
45 the usage for that command will be given.
46 The complete list of commands follows. Note that all commands have a
48 fixed number of arguments. If a parameter can be an empty string, then
49 it is necessary to specify it as two adjacent quotes, like "".
50 addhist <Message-ID> arr exp post token
52 Add an entry to the history database. This directs the server
53 to create a history line for Message-ID. The angle brackets are
54 optional. Arr, exp, and post specify when the article arrived,
55 what its expiration date is, and when it was posted. All three
56 values are numbers indicating the number of seconds since the
57 epoch. Exp being zero indicates the article does not have an
58 Expires header. Token is the storage API token indicating where
59 the article is stored. If the server is throttled manually,
60 this command causes it to briefly open the history database. If
61 the server is paused or throttled for any other reason, this
62 command is rejected.
63 allow reason
65 Remote connections are allowed. The reason must be the same
66 text given with an earlier ``reject'' command, or an empty
67 string.
68 begin site
70 Begin feeding site. This will cause the server to rescan the
71 newsfeeds file to find the specified site and set up a newsfeed
72 for it. If the site already exists, a ``drop'' is done first.
73 This command is forwarded; see NOTES below.
74 cancel <Message-ID>
76 Remove the article with the specified Message-ID from the local
77 system. This does not generate a cancel message. The angle
78 brackets are optional. If the server is throttled manually,
79 this command causes it to briefly open the history database. If
80 the server is paused or throttled for any other reason, this
81 command is rejected.
82 changegroup group rest
84 The newsgroup group is changed so that its fourth field in the
85 active file becomes the value specified by the rest parameter.
86 This may be used to make an existing group moderated or unmoder‐
87 ated, for example. This command can only be used while the
88 server is running (not throttled), unlike newgroup or rmgroup.
89 checkfile
91 Check the syntax of the newsfeeds file, and display a message if
92 any errors are found. The details of the errors are reported to
93 syslog(3).
94 drop site
96 Flush and drop site from the server's list of active feeds.
97 This command is forwarded; see NOTES below.
98 feedinfo site
100 Print detailed information about the state of the feed to site
101 or more brief status of all feeds if site is an empty string.
102 flush site
104 Flush the buffer for the specified site. The actions taken
105 depend on the type of feed the site receives; see newsfeeds(5).
106 This is useful when the site is fed by a file and batching is
107 about to start. If site is an empty string, then all sites are
108 flushed and the active file and history databases are also writ‐
109 ten out. This command is forwarded; see NOTES below.
110 flushlogs
112 Close the log and error log files and rename them to have a .old
113 extension. The history database and active file are also writ‐
114 ten out.
115 go reason
117 Re-open the history database and start accepting articles after
118 a ``pause'' or ``throttle'' command. The reason must either be
119 an empty string or match the text that was given in the earlier
120 ``pause'' or ``throttle'' command. If a ``reject'' command was
121 done, this will also do an ``allow'' command if the reason
122 matches the text that was given in the ``reject.'' If a
123 ``reserve'' command was done, this will also clear the reserva‐
124 tion if the reason matches the text that was given in the
125 ``reserve.'' Note that if only the history database has changed
126 while the server is paused or throttled, it is not necessary to
127 send it a ``reload'' command before sending it a ``go'' command.
128 If the server throttled itself because it accumulated too many
129 I/O errors, this command will reset the error count. If the
130 server was not started with the ``-ny'' flag, then this command
131 also does a ``readers'' command with ``yes'' as the flag and
132 reason as the text.
133 hangup channel
135 Close the socket on the specified incoming channel. This is
136 useful when an incoming connection appears to be hung.
137 help [command]
139 Print a command summary for all commands, or just command if
140 specified.
141 kill signal site
143 Signal signal is sent to the specified site, which must be a
144 channel or exploder feed. Signal can be a numeric signal number
145 or the word ``hup'', ``int'', or ``term''; case is not signifi‐
146 cant.
147 lowmark file
149 Reset the lowmarks in the active file based on the contents of
150 the given file. Each line in the file must be of the form:
151 group low-value
153 for example
155 comp.lang.c++ 243
157 logmode
159 Cause the server to log its current operating mode to syslog.
160 mode Print the server's operating mode as a multi-line summary of the
162 parameters and operating state.
163 name nnn
165 Print the name and relevant information of channel number nnn,
166 or of all channels if it is an empty string. The response is
167 formatted as:
168 f1:f2:f3:f4:f5
170 Where the meanings of the fields are:
172 f1 name of this channel
174 f2 channel number
175 f3 channel type
176 f4 idle time for this channel (nntp type)
177 or process id (process type)
178 f5 channel status (nntp type)
179 The channel type (f3) is one of following:
181 control control channel which is used
183 for ctlinnd
184 file file channel which is used for
185 file feed
186 localconn local channel which is used for
187 nnrpd or rnews
188 nntp nntp channel which is used for
189 current remote connection
190 proc process channel which is used
191 for process feed
192 remconn remote channel which will be
193 used for nntp
194 Channel status indicates whether the channel is paused or not.
196 Nothing is shown unless the channel is paused, in which case
197 ``paused'' is shown. A channel is paused if the number of
198 remote connection for that label in incoming.conf is beyond
199 ``max-connections'' within ``hold-time'' seconds of connection.
200 newgroup group rest creator
202 Create the specified newsgroup. The rest parameter should be
203 the fourth field as described in active(5); if it is not an
204 equal sign, only the first letter is used. The creator should
205 be the identity of the person creating the group as described in
206 active(5). If the newsgroup already exists, this is equivalent
207 to the ``changegroup'' command. This is the only command that
208 has defaults. The creator can be omitted and will default to
209 the newsmaster (as specified at configure time, ``usenet'' by
210 default), and the rest parameter can be omitted and will default
211 to ``y''. This command can only be done while the server is
212 throttled manually or running; it will update its internal state
213 when a ``go'' command is sent. This command updates the
214 active.times file (see active.times(5)). This command is for‐
215 warded; see NOTES below.
216 param letter value
218 Change the command-line parameters of the server. The combina‐
219 tion of defaults make it possible to use the text of the Control
220 header directly. Letter is the innd command-line option to set,
221 and value is the new value. For example, ``i 5'' directs the
222 server to allow only five incoming connections. To enable or
223 disable the action of the ``-n'' flag, use the letter ``y'' or
224 ``n'', respectively, for the value.
225 pause reason
227 Pause the server so that no incoming articles are accepted. No
228 existing connections are closed, but the history database is
229 closed. This command should be used for short-term locks, such
230 as when replacing the history files. If the server was not
231 started with the ``-ny'' flag, then this command also does a
232 ``readers'' command with ``no'' as the flag and reason as the
233 text.
234 perl flag
236 Enable or disable perl news filtering, if <--with-perl is speci‐
237 fied at configure>. If flag starts with the letter ``y'' then
238 filtering is enabled. If it starts with ``n'', then filtering
239 is disabled.
240 python flag
242 Enable or disable Python news filtering, if
243 <--with-python is specified at configure>. If flag starts with
244 the letter ``y'' then filtering is enabled. If it starts with
245 ``n'', then filtering is disabled.
246 readers flag text
248 Allow or disallow newsreaders. If flag starts with the letter
249 ``n'' then newsreading is disallowed, by causing the server to
250 pass the text as the value of the nnrpd(8) ``-r'' flag. If flag
251 starts with the letter ``y'' and text is either an empty string,
252 or the same string that was used when newsreading was disal‐
253 lowed, then newsreading will be allowed.
254 reject reason
256 Remote connections (those that would not be handed off to nnrpd)
257 are rejected, with reason given as the explanation.
258 reload what reason
260 The server updates its in-memory copies of various configuration
261 files. What identifies what should be reloaded. The reason is
262 reported to syslog.
263 There is no way to reload the inn.conf file; use ctlinnd xexec
265 innd instead.
266 If what is an empty string or the word ``all'' then everything
268 is reloaded; if it is the word ``history'' then the history
269 database is closed and opened, if it is the word ``incom‐
270 ing.conf'' then the incoming.conf file is reloaded; if it is the
271 word ``active'' or ``newsfeeds'' then both the active and news‐
272 feeds files are reloaded; if it is the word ``overview.fmt''
273 then the overview.fmt file is reloaded.
274 If <--with-perl is specified at configure> and it is the word
276 ``filter.perl'' then the filter_innd.pl file is reloaded. If a
277 Perl procedure named ``filter_before_reload'' exists, it will be
278 called prior to rereading filter_innd.pl. If a Perl procedure
279 named ``filter_after_reload'' exists, it will be called after
280 filter_innd.pl. has been reloaded. Reloading the Perl filter
281 does not enable filtering if it is disabled; use perl y to do
282 this. The startup_innd.pl file cannot be reloaded.
283 If <--with-python is specified at configure> and it is the word
285 ``filter.python'' then the filter_innd.py file is reloaded. If
286 a Python method named ``filter_before_reload'' exists, it will
287 be called prior to rereading filter_innd.py. If a Python method
288 named ``__init__'' exists, it will be called after fil‐
289 ter_innd.py. has been reloaded. Reloading the Python filter
290 does not enable filtering if it is disabled; use python y to do
291 this. If <--with-tcl is specified at configure> and it is the
292 word ``filter.tcl'' then the filter.tcl file is reloaded. If a
293 TCL procedure named ``filter_before_reload'' exists, it will be
294 called prior to rereading filter.tcl. If a TCL procedure named
295 ``filter_after_reload'' exists, it will be called after fil‐
296 ter.tcl has been reloaded. Reloading the Tcl filter does not
297 enable filtering if it is disabled; use filter to do this. The
298 startup.tcl file cannot be reloaded.
299 renumber group
301 Scan overview database for the specified newsgroup and update
302 the low-water mark and hi-water mark in the active file.
303 Regardless of the content of the overview database, the hi-water
304 mark will not be decreased (decreasing it may cause duplicate
305 article numbers to be assigned after a crash, which can cause
306 serious problems with the tradspool storage method). If group
307 is an empty string then all newsgroups are scanned. Renumber
308 only works if overview data has been created. (See the descrip‐
309 tion of ``enableoverview'' in inn.conf(5) for details about
310 overview creation.)
311 renumberlow file
313 This command does same as ``lowmark'' command.
314 reserve reason
316 The next ``pause'' or ``throttle'' command must use reason as
317 its reason. This ``reservation'' is cleared by giving an empty
318 string for the reason. This command is used by programs like
319 expire(8) that want to avoid running into other instances of
320 each other.
321 rmgroup group
323 Remove the specified newsgroup. This is done by editing the
324 active file. The spool directory is not touched, and any arti‐
325 cles in the group will still be expired using the default expi‐
326 ration parameters. Unlike the ``newgroup'' command, this com‐
327 mand does not update the active.times file. This command can be
328 done while the server is only throttled manually or running.
329 This command is forwarded; see NOTES below.
330 send feed text...
332 The specified text is sent as a control line to the exploder
333 feed.
334 shutdown reason
336 The server is shut down, with the specified reason recorded in
337 the log and sent to all open connections.
338 It is a good idea to send a ``throttle'' command first.
340 If Perl, Python, or TCL filtering is compiled in and enabled,
342 certain functions are called at ``throttle'' or ``shutdown''
343 (for example, to save filter state to disk), consult the embed‐
344 ded filter documentation for details.
345 stathist off|filename
347 Enable or disable generation of history performance statistics.
348 If the parameter is ``off'', no statistics are gathered. Other‐
349 wise statistics are written to the specified file. The file can
350 be parsed by contrib/stathist.pl.
351 status off|interval
353 Adjust frequency in seconds at which innd reports status infor‐
354 matoin to syslog. Status reporting is turned off if ``off'' or
355 ``0'' is specified. See ``status'' in inn.conf(5) for informa‐
356 tion on how to set the startup default.
357 tcl flag
359 Enable or disable Tcl news filtering, if <--with-tcl is speci‐
360 fied at configure>. If flag starts with the letter ``y'' then
361 filtering is enabled. If it starts with ``n'', then filtering
362 is disabled.
363 throttle reason
365 Input is throttled so that all existing connections are closed
366 and new connections are rejected. The history database is
367 closed. This should be used for long-term locks, such as when
368 expire is being run. If the server was not started with the
369 ``-ny'' flag, then this command also does a ``readers'' command
370 with ``no'' as the flag and reason as the text.
371 timer off|interval
373 Performance monitoring is turned off if ``off'' or ``0'' is
374 specified, otherwise, statistics will be reported every interval
375 seconds to syslog. See ``timer'' in inn.conf(5) for information
376 on how to set the startup default.
377 trace item flag
379 Tracing is turned on or off for the specified item. Flag should
380 start with the letter ``y'' or ``n'' to turn tracing on or off.
381 If item starts with a number, then tracing is set for the speci‐
382 fied innd channel, which must be for an incoming NNTP feed. If
383 it starts with the letter ``i'' then general innd tracing is
384 turned on or off. If it starts with the letter ``n'' then
385 future nnrpd's will or will not have the ``-t'' flag enabled, as
386 appropriate. The ``n'' flag does not affect nnrpd's already
387 running or using ``-D'' (running as a daemon).
388 xabort reason
390 The server logs the specified reason and then invokes the
391 abort(3) routine.
392 xexec path
394 The server gets ready to shut itself down, but instead of exit‐
395 ing it exec's <pathbin in inn.conf>/inndstart with all of its
396 original arguments except for ``-r''. Path can be any of
397 ``innd'', ``inndstart'', or an empty string, although all three
398 valid parameters have exactly the same effect. Any other value
399 is an error.
400
402 In addition to being acted upon within the server, certain commands can
403 be forwarded to the appropriate child process. If the site receiving
404 the command is an exploder (such as buffchan(8)), or it is a funnel
405 that feeds into an exploder, then the command can be forwarded. In
406 this case, the server will send a command line to the exploder that
407 consists of the ctlinnd command name. If the site funnels into an
408 exploder that has an asterisk (``*'') in its ``W'' flag (see news‐
409 feeds(5)), then the site name will be appended to the command; other‐
410 wise no argument is appended.
411
413 Ctlinnd uses the inndcomm(3) library, and is therefore limited to
414 server replies no larger than 4k.
415
417 Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. This is
418 revision 7062, dated 2004-12-19.
419
421 active(5), active.times(5), expire(8), innd(8), inndcomm(3),
422 inn.conf(5), newsfeeds(5), overview.fmt(5).
423 CTLINND(8)