doc/man/ctlinnd.8

   1 .\" $Revision: 7062 $
   2 .TH CTLINND 8
   3 .SH NAME
   4 ctlinnd \- control the InterNetNews daemon
   5 .SH SYNOPSIS
   6 .B ctlinnd
   7 [
   8 .B \-h
   9 ]
  10 [
  11 .B \-s
  12 ]
  13 [
  14 .BI \-t " timeout"
  15 ]
  16 .I command
  17 [
  18 .I argument...
  19 ]
  20 .SH DESCRIPTION
  21 .I Ctlinnd
  22 sends a message to the control channel of
  23 .IR innd (8),
  24 the InterNetNews server.
  25 .PP
  26 In the normal mode of behavior, the message is sent to the server, which
  27 then performs the requested action and sends back a reply with a text
  28 message and the exit code for
  29 .IR ctlinnd .
  30 If the server successfully performed the command,
  31 .I ctlinnd
  32 will exit with a status of zero and print the reply on standard output.
  33 If the server could not perform the command (for example, it was told to
  34 remove a newsgroup that does not exist), it will direct
  35 .I ctlinnd
  36 to exit with a status of one.  (Note that
  37 .I ctlinnd
  38 need not always exit immediately, see the ``\fB-t\fP'' flag.)
  39 The ``shutdown'', ``xabort'', and ``xexec'' commands do not generate a
  40 reply (because once
  41 .I innd
  42 has successfully exited, it is too late to send a reply to
  43 .IR ctlinnd );
  44 after these commands,
  45 .I ctlinnd
  46 will always exit silently with a status of zero.
  47 .SH OPTIONS
  48 .TP
  49 .B \-s
  50 If the ``\fB\-s\fP'' flag is
  51 used, then no message will be printed if the command was successful.
  52 .TP
  53 .B \-t timeout
  54 The ``\fB\-t\fP'' flag can be used to specify how long to wait for the reply
  55 from the server (for commands other than ``shutdown'', ``xabort'', and
  56 ``xexec'').
  57 The timeout value specifies the number of seconds to wait.
  58 A value of zero waits forever, and a value less
  59 than zero indicates that no reply is needed (that is, exit immediately
  60 with status zero).
  61 When waiting for a reply,
  62 .I ctlinnd
  63 will try every two minutes to see if the server is still running, so it
  64 is unlikely that ``\fB\-t0\fP'' will hang.
  65 The default is set as
  66 .I <CTLINND_TIMEOUT in include/config.h>
  67 (typically
  68 .IR 0 ).
  69 .TP
  70 .B \-h
  71 To see a command summary, use the ``\fB\-h\fP'' flag.
  72 If a command is included when
  73 .I ctlinnd
  74 is invoked with the ``\fB\-h\fP'' flag, then only the usage for that command
  75 will be given.
  76 .PP
  77 The complete list of commands follows.
  78 Note that all commands have a fixed number of arguments.
  79 If a parameter can be an empty string, then it is necessary to
  80 specify it as two adjacent quotes, like "".
  81 .TP
  82 .BI addhist " <Message-ID> arr exp post token"
  83 Add an entry to the history database.
  84 This directs the server to create a history line for
  85 .IR Message-ID .
  86 The angle brackets are optional.
  87 .IR Arr ,
  88 .IR exp ,
  89 and
  90 .I post
  91 specify when the article arrived, what its expiration date is, and
  92 when it was posted.
  93 All three values are numbers indicating the number of seconds since the
  94 epoch.
  95 .I Exp
  96 being zero indicates the article does not have an Expires header.
  97 .I Token
  98 is the storage API token indicating where the article is stored.
  99 If the server is throttled manually, this command causes it to briefly
 100 open the history database.
 101 If the server is paused or throttled for any other reason, this command
 102 is rejected.
 103 .TP
 104 .BI allow " reason"
 105 Remote connections are allowed.
 106 The
 107 .I reason
 108 must be the same text given with an earlier ``reject'' command, or an
 109 empty string.
 110 .TP
 111 .BI begin " site"
 112 Begin feeding
 113 .IR site .
 114 This will cause the server to rescan the
 115 .I newsfeeds
 116 file to find the specified site and set up a newsfeed for it.
 117 If the site already exists, a ``drop'' is done first.
 118 This command is forwarded; see NOTES below.
 119 .TP
 120 .BI cancel " <Message-ID>"
 121 Remove the article with the specified Message-ID from the local system.
 122 This does
 123 .I not
 124 generate a cancel message.
 125 The angle brackets are optional.
 126 If the server is throttled manually, this command causes it to briefly
 127 open the history database.
 128 If the server is paused or throttled for any other reason, this command
 129 is rejected.
 130 .TP
 131 .BI changegroup " group rest"
 132 The newsgroup
 133 .I group
 134 is changed so that its fourth field in the
 135 .I active
 136 file becomes the value specified by the
 137 .I rest
 138 parameter.
 139 This may be used to make an existing group moderated or unmoderated,
 140 for example.
 141 This command can only be used while the server is running (not throttled),
 142 unlike
 143 .B newgroup
 144 or
 145 .BR rmgroup .
 146 .TP
 147 .B checkfile
 148 Check the syntax of the
 149 .I newsfeeds
 150 file, and display a message if any errors are found.
 151 The details of the errors are reported to
 152 .IR syslog (3).
 153 .TP
 154 .BI drop " site"
 155 Flush and drop
 156 .I site
 157 from the server's list of active feeds.
 158 This command is forwarded; see NOTES below.
 159 .TP
 160 .BI feedinfo " site"
 161 Print detailed information about the state of the
 162 feed to
 163 .I site
 164 or more brief status of all feeds if
 165 .I site
 166 is an empty string.
 167 .TP
 168 .BI flush " site"
 169 Flush the buffer for the specified site.
 170 The actions taken depend on the type of feed the site receives; see
 171 .IR newsfeeds (5).
 172 This is useful when the site is fed by a file and batching is about to start.
 173 If
 174 .I site
 175 is an empty string, then all sites are flushed and the
 176 .I active
 177 file and history databases are also written out.
 178 This command is forwarded; see NOTES below.
 179 .TP
 180 .B flushlogs
 181 Close the log and error log files and rename them to have a
 182 .I \&.old
 183 extension.
 184 The history database and
 185 .I active
 186 file are also written out.
 187 .TP
 188 .BI go " reason"
 189 Re-open the history database and start accepting articles after a ``pause''
 190 or ``throttle'' command.
 191 The
 192 .I reason
 193 must either be an empty string or match the text that was given
 194 in the earlier ``pause'' or ``throttle'' command.
 195 If a ``reject'' command was done, this will also do an ``allow'' command
 196 if the
 197 .I reason
 198 matches the text that was given in the ``reject.''
 199 If a ``reserve'' command was done, this will also clear the reservation if
 200 the
 201 .I reason
 202 matches the text that was given in the ``reserve.''
 203 Note that if only the history database has changed while the server is
 204 paused or throttled, it is not necessary to send it a ``reload'' command
 205 before sending it a ``go'' command.
 206 If the server throttled itself because it accumulated too many I/O
 207 errors, this command will reset the error count.
 208 If the server was not started with the ``\fB\-ny\fP'' flag, then this command also
 209 does a ``readers'' command with ``yes'' as the flag and
 210 .I reason
 211 as the text.
 212 .TP
 213 .BI hangup " channel"
 214 Close the socket on the specified incoming channel.
 215 This is useful when an incoming connection appears to be hung.
 216 .TP
 217 .BI help " [command]"
 218 Print a command summary for all commands, or just
 219 .I command
 220 if specified.
 221 .TP
 222 .BI kill " signal site"
 223 Signal
 224 .I signal
 225 is sent to the specified
 226 .IR site ,
 227 which must be a channel or exploder feed.
 228 .I Signal
 229 can be a numeric signal number or the word ``hup'', ``int'', or ``term'';
 230 case is not significant.
 231 .TP
 232 .BI lowmark " file"
 233 Reset the lowmarks in the
 234 .I active
 235 file based on the contents of the given
 236 file. Each line in the file must be of the form:
 237 .IP
 238 .RS
 239 .nf
 240     group low-value
 241 .fi
 242 .RE
 243 .IP
 244 for example
 245 .IP
 246 .RS
 247 .nf
 248     comp.lang.c++    243
 249 .fi
 250 .RE
 251 .TP
 252 .BI logmode
 253 Cause the server to log its current operating mode to
 254 .IR syslog .
 255 .TP
 256 .BI mode
 257 Print the server's operating mode as a multi-line summary of the parameters
 258 and operating state.
 259 .TP
 260 .BI name " nnn"
 261 Print the name and relevant information of channel number
 262 .IR nnn ,
 263 or of all channels if it is an empty string.  The response is formatted as:
 264 .sp 1
 265 .in +0.5i
 266 .nf
 267 f1:f2:f3:f4:f5
 268 .fi
 269 .in -0.5i
 270 .sp 1
 271 Where the meanings of the fields are:
 272 .sp 1
 273 .in +0.5i
 274 .nf
 275 f1      name of this channel
 276 f2      channel number
 277 f3      channel type
 278 f4      idle time for this channel (nntp type)
 279         or process id (process type)
 280 f5      channel status (nntp type)
 281 .fi
 282 .in -0.5i
 283 .sp 1
 284 The channel type (f3) is one of following:
 285 .sp 1
 286 .in +0.5i
 287 .nf
 288 control         control channel which is used
 289                         for ctlinnd
 290 file                    file channel which is used for
 291                         file feed
 292 localconn               local channel which is used for
 293                         nnrpd or rnews
 294 nntp                    nntp channel which is used for
 295                         current remote connection
 296 proc                    process channel which is used
 297                         for process feed
 298 remconn         remote channel which will be
 299                         used for nntp
 300 .fi
 301 .in -0.5i
 302 .sp 1
 303 Channel status indicates whether the channel is paused or not.  Nothing is
 304 shown unless the channel is paused, in which case ``paused'' is shown.
 305 A channel is paused if the number of remote connection for that label in
 306 .I incoming.conf
 307 is beyond ``max-connections'' within ``hold-time'' seconds of connection.
 308 .TP
 309 .BI newgroup " group rest creator"
 310 Create the specified newsgroup.
 311 The
 312 .I rest
 313 parameter should be the fourth field as described in
 314 .IR active (5);
 315 if it is not an equal sign, only the first letter is used.
 316 The
 317 .I creator
 318 should be the identity of the person creating the group as described in
 319 .IR active (5).
 320 If the newsgroup already exists, this is equivalent to the ``changegroup''
 321 command.
 322 This is the only command that has defaults.
 323 The
 324 .I creator
 325 can be omitted and will default to the newsmaster (as specified at configure
 326 time, ``usenet'' by default), and the
 327 .I rest
 328 parameter can be omitted and will default to ``y''.
 329 This command can only be done while the server is throttled manually
 330 or running; it will
 331 update its internal state when a ``go'' command is sent.
 332 This command updates the
 333 .I active.times
 334 file (see
 335 .IR active.times (5)).
 336 This command is forwarded; see NOTES below.
 337 .TP
 338 .BI param " letter value"
 339 Change the command-line parameters of the server.
 340 The combination of defaults make it possible to use the text of the Control
 341 header directly.
 342 .I Letter
 343 is the
 344 .I innd
 345 command-line option to set, and
 346 .I value
 347 is the new value.
 348 For example, ``i 5'' directs the server to allow only five incoming
 349 connections.
 350 To enable or disable the action of the ``\fB\-n\fP'' flag, use the letter ``y''
 351 or ``n'', respectively, for the
 352 .IR value .
 353 .TP
 354 .BI pause " reason"
 355 Pause the server so that no incoming articles are accepted.
 356 No existing connections are closed, but the history database is closed.
 357 This command should be used for short-term locks, such as when replacing
 358 the history files.
 359 If the server was not started with the ``\fB\-ny\fP'' flag, then this command also
 360 does a ``readers'' command with ``no'' as the flag and
 361 .I reason
 362 as the text.
 363 .TP
 364 .BI perl " flag"
 365 Enable or disable perl news filtering, if
 366 .IR <\-\-with\-perl\ is\ specified\ at\ configure> .
 367 If
 368 .I flag
 369 starts with the letter ``y'' then filtering is enabled.  If it starts with
 370 ``n'', then filtering is disabled.
 371 .TP
 372 .BI python " flag"
 373 Enable or disable Python news filtering, if
 374 .IR <\-\-with\-python\ is\ specified\ at\ configure> .
 375 If
 376 .I flag
 377 starts with the letter ``y'' then filtering is enabled.  If it starts with
 378 ``n'', then filtering is disabled.
 379 .TP
 380 .BI readers " flag text"
 381 Allow or disallow newsreaders.
 382 If
 383 .I flag
 384 starts with the letter ``n'' then newsreading is disallowed, by
 385 causing the server to pass the
 386 .I text
 387 as the value of the
 388 .IR nnrpd (8)
 389 \&`\fB`\-r\fP'' flag.
 390 If
 391 .I flag
 392 starts with the letter ``y'' and
 393 .I text
 394 is either an empty string, or the same string that was used when newsreading
 395 was disallowed, then newsreading will be allowed.
 396 .\".TP
 397 .\".BI refile " path group"
 398 .\"The article specified by
 399 .\".I path
 400 .\"is refiled as if it were posted to the newsgroup
 401 .\".IR group .
 402 .TP
 403 .BI reject " reason"
 404 Remote connections (those that would not be handed off to
 405 .IR nnrpd )
 406 are rejected, with
 407 .I reason
 408 given as the explanation.
 409 .TP
 410 .BI reload " what reason"
 411 The server updates its in-memory copies of various configuration files.
 412 .I What
 413 identifies what should be reloaded.
 414 The
 415 .I reason
 416 is reported to
 417 .IR syslog .
 418 .sp 1
 419 There is no way to reload the
 420 .I inn.conf
 421 file; use
 422 .I "ctlinnd xexec innd"
 423 instead.
 424 .sp 1
 425 If
 426 .I what
 427 is an empty string or the word ``all'' then everything is reloaded;
 428 if it is the word ``history'' then the history database is closed and opened,
 429 if it is the word ``incoming.conf'' then the
 430 .I incoming.conf
 431 file is reloaded; if it is the word ``active'' or ``newsfeeds'' then both
 432 the
 433 .I active
 434 and
 435 .I newsfeeds
 436 files are reloaded; if it is the word ``overview.fmt'' then the
 437 .I overview.fmt
 438 file is reloaded.
 439 .sp 1
 440 If
 441 .I <\-\-with\-perl is specified at configure>
 442 and it is the word ``filter.perl'' then the
 443 .IR filter_innd.pl
 444 file is reloaded.  If a Perl procedure named ``filter_before_reload'' exists,
 445 it will be called prior to rereading
 446 .IR filter_innd.pl .
 447 If a Perl procedure named ``filter_after_reload'' exists, it will be called
 448 after
 449 .IR filter_innd.pl .
 450 has been reloaded.  Reloading the Perl filter does not enable filtering if
 451 it is disabled; use
 452 .I perl y
 453 to do this. The
 454 .I startup_innd.pl
 455 file cannot be reloaded.
 456 .sp 1
 457 If
 458 .I <\-\-with\-python is specified at configure>
 459 and it is the word ``filter.python'' then the
 460 .I filter_innd.py
 461 file is reloaded.  If a Python method named ``filter_before_reload'' exists,
 462 it will be called prior to rereading
 463 .IR filter_innd.py .
 464 If a Python method named ``__init__'' exists, it will be called
 465 after
 466 .IR filter_innd.py .
 467 has been reloaded.  Reloading the Python filter does not enable filtering if
 468 it is disabled; use
 469 .I python y
 470 to do this.
 471 If
 472 .I <\-\-with\-tcl is specified at configure>
 473 and it is the word ``filter.tcl'' then the
 474 .I filter.tcl
 475 file is reloaded.  If a TCL procedure named ``filter_before_reload'' exists,
 476 it will be called prior to rereading
 477 .IR filter.tcl.
 478 If a TCL procedure named ``filter_after_reload'' exists, it will be called
 479 after
 480 .I filter.tcl
 481 has been reloaded.  Reloading the Tcl filter does not enable filtering if
 482 it is disabled; use
 483 .IR filter
 484 to do this.
 485 The
 486 .I startup.tcl
 487 file cannot be reloaded.
 488 .TP
 489 .BI renumber " group"
 490 Scan overview database for the specified newsgroup and update the
 491 low-water mark and hi-water mark in the
 492 .I active
 493 file.  Regardless of the content of the overview database, the hi-water
 494 mark will not be decreased (decreasing it may cause duplicate article
 495 numbers to be assigned after a crash, which can cause serious problems
 496 with the tradspool storage method).
 497 If
 498 .I group
 499 is an empty string then all newsgroups are scanned.
 500 Renumber only works if overview data has been created.
 501 (See the description of ``enableoverview'' in
 502 .IR inn.conf (5)
 503 for details about overview creation.)
 504 .TP
 505 .BI renumberlow " file"
 506 This command does same as ``lowmark'' command.
 507 .TP
 508 .BI reserve " reason"
 509 The next ``pause'' or ``throttle'' command must use
 510 .I reason
 511 as its reason.
 512 This ``reservation'' is cleared by giving an empty string for the
 513 .IR reason .
 514 This command is used by programs like
 515 .IR expire (8)
 516 that want to avoid running into other instances of each other.
 517 .TP
 518 .BI rmgroup " group"
 519 Remove the specified newsgroup.
 520 This is done by editing the
 521 .I active
 522 file.
 523 The spool directory is not touched, and any articles in the group will
 524 still be expired using the default expiration parameters.
 525 Unlike the ``newgroup'' command, this command does not update the
 526 .I active.times
 527 file.
 528 This command can be done while the server is only throttled manually or running.
 529 This command is forwarded; see NOTES below.
 530 .TP
 531 .BI send " feed text..."
 532 The specified
 533 .I text
 534 is sent as a control line to the exploder
 535 .IR feed .
 536 .TP
 537 .BI shutdown " reason"
 538 The server is shut down, with the specified reason recorded in the log
 539 and sent to all open connections.
 540 .sp 1
 541 It is a good idea to send a ``throttle'' command first.
 542 .sp 1
 543 If Perl, Python, or TCL filtering is compiled in and enabled, certain
 544 functions are called at ``throttle'' or ``shutdown'' (for example, to
 545 save filter state to disk), consult the embedded filter documentation
 546 for details.
 547 .TP
 548 .BI stathist " off|filename"
 549 Enable or disable generation of history performance statistics.  If the
 550 parameter is ``off'', no statistics are gathered.  Otherwise statistics
 551 are written to the specified file.  The file can be parsed by
 552 .IR contrib/stathist.pl .
 553 .TP
 554 .BI status " off|interval"
 555 Adjust frequency in seconds at which
 556 .I innd
 557 reports status informatoin to syslog.  Status reporting is turned off if
 558 ``off'' or ``0'' is specified.  See ``status'' in
 559 .IR inn.conf (5)
 560 for information on how to set the startup default.
 561 .TP
 562 .BI tcl " flag"
 563 Enable or disable Tcl news filtering, if
 564 .IR <\-\-with\-tcl\ is\ specified\ at\ configure> .
 565 If
 566 .I flag
 567 starts with the letter ``y'' then filtering is enabled.  If it starts with
 568 ``n'', then filtering is disabled.
 569 .TP
 570 .BI throttle " reason"
 571 Input is throttled so that all existing connections are closed and new
 572 connections are rejected.
 573 The history database is closed.
 574 This should be used for long-term locks, such as when
 575 .I expire
 576 is being run.
 577 If the server was not started with the ``\-ny'' flag, then this command also
 578 does a ``readers'' command with ``no'' as the flag and
 579 .I reason
 580 as the text.
 581 .TP
 582 .BI timer " off|interval"
 583 Performance monitoring is turned off if ``off'' or ``0'' is specified,
 584 otherwise, statistics will be reported every
 585 .I interval
 586 seconds to syslog.  See ``timer'' in
 587 .IR inn.conf (5)
 588 for information on how to set the startup default.
 589 .TP
 590 .BI trace " item flag"
 591 Tracing is turned on or off for the specified
 592 .IR item .
 593 .I Flag
 594 should start with the letter ``y'' or ``n'' to turn tracing on or off.
 595 If
 596 .I item
 597 starts with a number, then tracing is set for the specified
 598 .I innd
 599 channel, which must be for an incoming NNTP feed.
 600 If it starts with the letter ``i'' then general
 601 .I innd
 602 tracing is turned on or off.
 603 If it starts with the letter ``n'' then future
 604 .IR nnrpd 's
 605 will or will not have the ``\-t'' flag enabled, as appropriate.
 606 The ``n'' flag does not affect
 607 .IR nnrpd 's
 608 already running or using ``-D'' (running as a daemon).
 609 .TP
 610 .BI xabort " reason"
 611 The server logs the specified
 612 .I reason
 613 and then invokes the
 614 .IR abort (3)
 615 routine.
 616 .TP
 617 .BI xexec " path"
 618 The server gets ready to shut itself down, but instead of exiting it
 619 .IR exec 's
 620 .I <pathbin in inn.conf>/inndstart
 621 with all of its original arguments except for ``\fB\-r\fP''.
 622 .I Path
 623 can be any of ``innd'', ``inndstart'', or an empty string, although all
 624 three valid parameters have exactly the same effect.
 625 Any other value is an error.
 626 .SH NOTES
 627 In addition to being acted upon within the server, certain commands can
 628 be forwarded to the appropriate child process.
 629 If the site receiving the command is an exploder (such as
 630 .IR buffchan (8)),
 631 or it is a funnel that feeds into an exploder, then the
 632 command can be forwarded.
 633 In this case, the server will send a command line to the exploder that
 634 consists of the
 635 .I ctlinnd
 636 command name.
 637 If the site funnels into an exploder that has an asterisk (``*'') in its ``W''
 638 flag (see
 639 .IR newsfeeds (5)),
 640 then the site name will be appended to the command; otherwise no argument
 641 is appended.
 642 .SH BUGS
 643 .I Ctlinnd
 644 uses the
 645 .IR inndcomm (3)
 646 library, and is therefore limited to server replies no larger than 4k.
 647 .SH HISTORY
 648 Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.
 649 .de R$
 650 This is revision \\$3, dated \\$4.
 651 ..
 652 .R$ $Id: ctlinnd.8 7062 2004-12-19 21:41:05Z rra $
 653 .SH "SEE ALSO"
 654 active(5),
 655 active.times(5),
 656 expire(8),
 657 innd(8),
 658 inndcomm(3),
 659 inn.conf(5),
 660 newsfeeds(5),
 661 overview.fmt(5).