1CTLINND(8)                InterNetNews Documentation                CTLINND(8)
2
3
4

NAME

6       ctlinnd - Control the main InterNetNews daemon
7

SYNOPSIS

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

DESCRIPTION

12       ctlinnd sends a message to the control channel of innd(8), the main
13       InterNetNews daemon.
14
15       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
24       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

OPTIONS

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
32       -s  If the command was successful, don't print the output from innd.
33
34       -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
43           The default is zero, indicating that ctlinnd should wait forever.
44

COMMANDS

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
52       addhist message-id arrival expires posted token
53           Add an entry to the history database for message-id.  The angle
54           brackets around the message-ID are optional.  It should normally be
55           protected from the shell with single quotes.
56
57           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), and when it was posted (given in the Date:
60           header), respectively.  expires should be 0 if the article doesn't
61           have an Expires: header.  token is the storage API token for the
62           article, and may be empty.
63
64           This command can only be used while the server is running, and will
65           be rejected if the server is paused or throttled.
66
67       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
72       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
78       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 the message-ID
82           are optional.  It should normally be protected from the shell with
83           single quotes (and not double quotes).  For instance:
84
85               ctlinnd cancel 'test@foo.bar'
86
87           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
92           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
96       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
101           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
105       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
110       drop site
111           Flush and drop site from the server's list of active feeds.  This
112           command is forwarded; see NOTES below.
113
114       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
118       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
127           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
131       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
138       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
144           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
150           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
157           If the server throttled itself because it accumulated too many I/O
158           errors, this command will reset the error count.
159
160           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
164       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).
168
169       help [command]
170           Print a command summary for all commands, or just command if one is
171           specified.  This is equivalent to the -h option.
172
173       kill signal site
174           Signal signal is sent to the process underlying the specified site,
175           which must be a channel or exploder feed.  signal may be a numeric
176           signal number or one of "hup", "int", or "term"; case is not
177           significant.
178
179       logmode
180           Cause the server to log its current operating mode to syslog.
181
182       lowmark file
183           Reset the low water marks in the active file based on the contents
184           of file.  Each line in file must be of the form:
185
186               group low-value
187
188           For example:
189
190               comp.lang.c++ 243
191
192           This command is mostly used by news.daily to update the active file
193           after nightly expiration.
194
195       mode
196           Print the server's operating mode as a multi-line summary of the
197           parameters and the operating state.  The parameters in the output
198           correspond to command-line flags to innd and give the current
199           settings of those parameters that can be overridden by command-line
200           flags.
201
202       name channel
203           Print the name and relevant information for the given incoming or
204           outgoing channel, or for all channels if channel is an empty
205           string.  The response is formatted as:
206
207               <name>:<number>:<type>:<idle>:<status>
208
209           where <name> is the name of the channel, <number> is its number
210           (generally the same as the file descriptor assigned to it), <idle>
211           is the idle time for an NNTP channel or the process ID for a
212           process channel, and <status> is the status for NNTP channels.
213
214           The type is one of the following values:
215
216               control     Control channel for ctlinnd
217               file        An outgoing file feed
218               localconn   Local channel used by nnrpd and rnews for posting
219               nntp        NNTP channel for remote connections
220               proc        The process for a process feed
221               remconn     The channel that accepts new remote connections
222
223           Channel status indicates whether the channel is paused or not.
224           Nothing is shown unless the channel is paused, in which case
225           "paused" is shown.  A channel will be paused automatically if the
226           number of remote connections for that label in incoming.conf is
227           greater than max-connections within hold-time seconds.
228
229       newgroup group [status [creator]]
230           Create the specified newsgroup.  The status parameter is the fourth
231           field of the active file entry, as described in active(5).  If it
232           is not an equal sign, only the first character is used.  creator
233           should be the identity of the person creating the group.  If the
234           newsgroup already exists, this is equivalent to the "changegroup"
235           command.
236
237           creator, encoded in UTF-8 if given, may be omitted; if so, it will
238           default to the newsmaster (as specified at configure time, normally
239           "usenet").  status may also be omitted; if so, it will default to
240           "y" (a normal, unmoderated group).  The combination of defaults
241           make it possible to use the text of the Control: header directly
242           (although don't do this without checking the syntactic validity of
243           the header first).
244
245           This command can only be done while the server is running or
246           throttled manually.  It will update its internal state when a "go"
247           command is sent.  This command updates the active.times file as
248           well.  This command is forwarded; see NOTES below.
249
250       param letter value
251           Change the specified server parameter.  letter is the innd command-
252           line option to set and value is the new value.  For example:
253
254               ctlinnd param i 5
255
256           would direct the server to allow only five incoming connections.
257           To enable or disable the action of the -n flag, use "n" for the
258           letter and "y" or "n", respectively, for the value.
259
260           The supported values for letter are "a", "c", "H", "i", "l", "n",
261           "o", "T", "t", and "X".
262
263       pause reason
264           Pause the server so that no incoming articles are accepted.  No
265           existing connections are closed, but the history database is
266           closed.  This should be used for short-term locks, such as when
267           replacing the history database.  If the server was not started with
268           the -n y flag, this command also does the equivalent of a "readers"
269           command with "no" as the flag and reason as the text, encoded in
270           UTF-8.
271
272       perl flag
273           Enable or disable Perl filtering.  This command is only available
274           if INN was built with Perl filtering support.  If flag starts with
275           "y", filtering is enabled; if it starts with "n", filtering is
276           disabled.
277
278           When filtering is disabled, if the filter_innd.pl Perl filter
279           defined a function "filter_end", it will be called prior to the
280           deactivation of the filter.
281
282       python flag
283           Enable or disable Python filtering.  This command is only available
284           if INN was built with Python filtering support.  If flag starts
285           with "y", filtering is enabled; if it starts with "n", filtering is
286           disabled.
287
288       readers flag text
289           Allow or disallow readers.  If flag starts with the letter "n",
290           then reading is disallowed by causing the server to pass text as
291           the value of the -r flag to nnrpd.  If flag starts with the letter
292           "y" and text is either an empty string or the same string, encoded
293           in UTF-8, that was used when reading was disabled, reading will be
294           re-enabled.
295
296           This command has no effect if nnrpd is being run separately rather
297           than spawned by innd.
298
299       reject reason
300           Remote connections (those that would not be handed off to nnrpd)
301           are rejected with reason given as the explanation, encoded in
302           UTF-8.  Existing connections are not closed.
303
304       reload what reason
305           Update the in-memory copy of server configuration files.  what
306           identifies what should be reloaded, and reason is reported to
307           syslog in the message noting the reload.
308
309           There is no way to reload inn.conf, storage.conf, or other
310           configuration files for the storage or overview backends.  To pick
311           up changes to those files, use "ctlinnd xexec innd" to restart
312           innd.
313
314           If what is the empty string or the word "all", everything is
315           reloaded.  If it is the word "history", the history database is
316           closed and re-opened.  If it is the word "incoming.conf", the
317           corresponding file is reloaded.  If it is the word "active" or
318           "newsfeeds", both the active and newsfeeds files are reloaded,
319           which will also cause all outgoing feeds to be flushed and
320           restarted.
321
322           If what is the word "filter.perl", the filter_innd.pl file is
323           reloaded.  If the Perl filter defined a function
324           "filter_before_reload", it will be called prior to re-reading
325           filter_innd.pl.  If the Perl function "filter_after_reload" is
326           defined, it will be called after filter_innd.pl has been reloaded.
327           Reloading the Perl filter does not enable filtering if it has been
328           disabled; use "perl y" to do this instead.  startup_innd.pl cannot
329           be reloaded.  This file is not available for reloading unless INN
330           was compiled with Perl filtering support.
331
332           If what is the word "filter.python", the filter_innd.py file is
333           reloaded.  If a Python method named "filter_before_reload" exists,
334           it will be called prior to re-reading filter_innd.py.  If a Python
335           method named "__init__" exists, it will be called after
336           filter_innd.py has been reloaded.  Reloading the Python filter does
337           not enable filtering if it has been disabled; use "python y" to do
338           this.  This file is not available for reloading unless INN was
339           compiled with Python filtering support.
340
341       renumber group
342           Update the low water and high water marks for group in the active
343           file based on the information in the overview database.  Regardless
344           of the contents of the overview database, the high water mark will
345           not be decreased.  (Decreasing it may cause duplicate article
346           numbers to be assigned after a crash, which can cause serious
347           problems with the tradspool storage method.)  If group is the empty
348           string, all newsgroups are renumbered.  Renumber only works if
349           overview data has been created (if enableoverview is set to true in
350           inn.conf).
351
352       renumberlow file
353           Identical to the "lowmark" command.
354
355       reserve reason
356           Require the next "pause" or "throttle" command to use reason as its
357           reason, encoded in UTF-8.  This reservation is cleared by giving an
358           empty string for the reason.  This is used by programs like expire
359           to coordinate pauses and throttles of the server and avoid
360           trampling on other instances of themselves.
361
362       rmgroup group
363           Remove the specified newsgroup.  The group is removed from the
364           active file and its overview information is purged, making it
365           immediately unavailable to readers.  Unlike the "newgroup" command,
366           this command does not update the active.times file.
367
368           This command can only be done while the server is running or
369           throttled manually.  This command is forwarded; see NOTES below.
370
371       send feed text
372           The specified text is sent as a control line to the exploder feed.
373
374       shutdown reason
375           The server is shut down, with the specified reason recorded in the
376           log and sent to all open connections.  It is a good idea to send a
377           "throttle" command first so that feeds can be shut down more
378           gracefully.
379
380           If Perl or Python filtering is compiled in and enabled, certain
381           functions are called at "throttle" or "shutdown" (to save filter
382           state to disk, for example).  Consult the embedded filter
383           documentation for details.
384
385       stathist (off | filename)
386           Enable or disable generation of history performance statistics.  If
387           the parameter is "off", no statistics are gathered.  Otherwise,
388           statistics are written to the specified file.  A parser for this
389           file is provided in the contrib tree of the INN distribution.
390
391       status (off | interval)
392           Adjust the frequency with which innd reports status information to
393           syslog.  Status reporting is turned off if "off" or 0 is given as
394           the argument.  Otherwise, status will be reported every interval
395           seconds.  See status in inn.conf(5) for information on how to set
396           the default.
397
398       throttle reason
399           Close all existing incoming connections and outgoing feeds and
400           reject new connections.  Close the history database.  This should
401           be used for long-term locks or for running a large number of
402           "newgroup" and "rmgroup" commands without restarting all outgoing
403           feeds between each one.  (Note that changing the status of existing
404           newsgroups when the server is throttled cannot be done.)
405
406           If the server was not started with the -n y flag, then this command
407           also does the equivalent of a "readers" command with "no" as the
408           flag and reason as the text, encoded in UTF-8.
409
410       timer (off | interval)
411           Adjust the frequency with which innd reports performance
412           information to syslog.  Performance monitoring is turned off if
413           "off" or 0 is given as the argument.  Otherwise, statistics will be
414           reported every interval seconds to syslog.  See timer in
415           inn.conf(5) for information on how to set the default.
416
417       trace item flag
418           Turn tracing on or off for the specified item.  flag should start
419           with the letter "y" or "n" to turn tracing on or off, respectively.
420           If item starts with a number, tracing is set up for the specified
421           innd channel, which must be an incoming NNTP feed.  If it starts
422           with the letter "i", general innd tracing is turned on or off.  If
423           it starts with the letter "n", future nnrpd processes spawned by
424           "innd" will or will not be passed the -t flag, as appropriate.
425           This will not affect any nnrpd processes already running, or nnrpd
426           processes started by some means other than innd.
427
428       xabort reason
429           Log the specified reason and then abort.  On most systems, this
430           will cause innd to dump a core file.  This is only useful for
431           debugging.
432
433       xexec path
434           Shut down the server, but then rather than exiting, exec innd with
435           all of its original arguments except for -r.  path may be either
436           "innd" or an empty string, both of which are equivalent.  Any other
437           value is an error.
438
439           This is the easiest way to start a new copy of innd after upgrading
440           or reload configuration files that can't be reloaded via the
441           "reload" command.
442

NOTES

444       In addition to being acted on by the server, certain commands can be
445       forwarded to an appropriate child process.  If the site receiving the
446       command is an exploder (such as buffchan) or a funnel that feeds into
447       an exploder, the command can be forwarded.  In this case, the server
448       will send a command line to the exploder that consists of the ctlinnd
449       command name.  If the site funnels into an exploder that has an
450       asterisk ("*") in its "W" flag (see newsfeeds(5) for more information
451       on feed specifications), the site name will be appended to the command;
452       otherwise, no argument is appended.
453

BUGS

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

HISTORY

461       Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.  Rewritten
462       in POD by Russ Allbery <eagle@eyrie.org>.
463
464       $Id: ctlinnd.pod 9767 2014-12-07 21:13:43Z iulius $
465

SEE ALSO

467       active(5), active.times(5), buffchan(8), incoming.conf(5), innd(8),
468       inndcomm(3), inn.conf(5), newsfeeds(5), nnrpd(8).
469
470
471
472INN 2.6.3                         2015-09-12                        CTLINND(8)
Impressum