Provided by: inn_1.7.2q-40build2_amd64 bug

NAME

       ctlinnd - control the InterNetNews daemon

SYNOPSIS

       ctlinnd [ -h ] [ -s ] [ -t timeout ] command [ argument...  ]

DESCRIPTION

       Ctlinnd sends a message to the control channel of innd(8), the InterNetNews server.

       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 the exit code for ctlinnd.
       If  the server successfully performed the command, ctlinnd will exit with a status of zero
       and print the reply on standard output.  If the server could not perform the command  (for
       example, it was told to remove a newsgroup that does not exist), it will direct ctlinnd to
       exit with a status of one.  The ``shutdown,'' ``xabort,'' and ``xexec''  commands  do  not
       generate a reply; ctlinnd will always exit silently with a status of zero.

OPTIONS

       -s     If  the  ``-s''  flag  is  used, then no message will be printed if the command was
              successful.

       -t     The ``-t'' flag can be used to specify how long to wait  for  the  reply  from  the
              server.   The  timeout  value  specifies the number of seconds to wait.  A value of
              zero waits forever, and a value less than zero indicates that no reply  is  needed.
              When  waiting  for a reply, ctlinnd will try every two minutes to see if the server
              is still running, so it is  unlikely  that  ``-t0''  will  hang.   The  default  is
              ``-t0.''

       -h     To  see  a  command  summary,  use  the ``-h'' flag.  If a command is included when
              ctlinnd is invoked with the ``-h'' flag, then only the usage for that command  will
              be given.

       If  a  large  number  of groups are going to be created or deleted at once, it may be more
       efficient to ``pause'' or ``throttle'' the server and edit the active file directly.

       The complete list of commands follows.  Note that all commands  have  a  fixed  number  of
       arguments.   If  a parameter can be an empty string, then it is necessary to specify it as
       two adjacent quotes, like "".

       addhist <Message-ID> arr exp post paths
              Add an entry to the history database.  This directs the server to create a  history
              line  for Message-ID.  The angle brackets are optional.  Arr, exp, and post specify
              when the article arrived, what its expiration date is, and when it was posted.  All
              three values are a number indicating the number of seconds since the epoch.  If the
              article does not have an Expires header, then exp should be  zero.   Paths  is  the
              pathname  within  the  news  spool  directory  where  the article is filed.  If the
              article is cross-posted, then the names should be separated by whitespace  and  the
              paths  argument  should  be  inside  double  quotes.   If  the  server is paused or
              throttled, this command causes it to briefly open the history database.

       allow reason
              Remote connections are allowed.  The reason must be the same  text  given  with  an
              earlier ``reject'' command, or an empty string.

       begin site
              Begin  feeding site.  This will cause the server to rescan the newsfeeds(5) file to
              find the specified site and set up a newsfeed for it.  If the site already  exists,
              a ``drop'' is done first.  This command is forwarded; see below.

       cancel <Message-ID>
              Remove  the article with the specified Message-ID from the local system.  This does
              not generate a cancel message.  The angle brackets are optional.  If the server  is
              paused or throttled, this command causes it to briefly open the history database.

       changegroup group rest
              The  newsgroup group is changed so that its fourth field in the active file becomes
              the value specified by the rest parameter.  This may be used to  make  an  existing
              group moderated or unmoderated, for example.

       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(3).

       drop site
              Flush and drop site from the server's  list  of  active  feeds.   This  command  is
              forwarded; see below.

       feedinfo site
              Print detailed information about the state of the feed to site or more brief status
              of all feeds if site is an empty string.

       perl flag
              Enable or disable perl news filtering.  If flag starts with the letter  ``y''  then
              filtering is enabled.  If it starts with ``n'', then filtering is disabled.

       feedinfo site
              Print detailed information about the state of the feed to site or more brief status
              of all feeds if site is an empty string.

       flush site
              Flush the buffer for the specified site.  The actions taken depend on the  type  of
              feed the site receives; see newsfeeds(5).  This is useful when the site is fed by a
              file and batching is going to start.  If site is an empty string,  then  all  sites
              are  flushed  and the active file and history databases are also written out.  This
              command is forwarded; see below.

       flushlogs
              Close the log and error log files and rename them to have a  .old  extension.   The
              history database and active file are also written out.

       go reason
              Re-open  the  history  database  and  start accepting articles after a ``pause'' or
              ``throttle'' command.  The reason must either be an empty string or match the  text
              that  was  given in the earlier ``pause'' or ``throttle'' command.  If a ``reject''
              command was done, this will also do an ``allow'' command if the reason matches  the
              text  that  was  given  in the ``reject.''  If a ``reserve'' command was done, this
              will also clear the reservation if the reason matches the text that  was  given  in
              the  ``reserve.''   Note  that  if  only the history database has changed while the
              server is paused or throttled, it is not necessary to send it a ``reload''  command
              before  sending  it  a  ``go''  command.  If the server throttled itself because it
              accumulated too many I/O errors, this command will reset the error count.   If  the
              server  was  not  started  with  the  ``-ny''  flag,  then this command also does a
              ``readers'' command with ``yes'' as the flag and reason as the text.

       hangup channel
              Close the socket on the  specified  incoming  channel.   This  is  useful  when  an
              incoming connection appears to be hung.

       help [command]
              Print a command summary for all commands, or just command if specified.

       logmode
              Cause the server to log its current operating mode to syslog.

       mode   Print  the  server's  operating  mode as a multi-line summary of the parameters and
              operating state.

       name nnn
              Print the name of channel number nnn or of all channels if it is an empty string.

       newgroup group rest creator
              Create the specified newsgroup.  The rest parameter should be the fourth  field  as
              described  in active(5); if it is not an equal sign, only the first letter is used.
              The creator should be the name of the person creating the group.  If the  newsgroup
              already  exists,  this  is  equivalent to the ``changegroup'' command.  This is the
              only command that has defaults.  The creator can be omitted and will default to the
              empty  string,  and  the  rest  parameter can be omitted and will default to ``y''.
              This command can be done while the server is paused or throttled;  it  will  update
              its  internal  state  when  a  ``go''  command  is  sent.  This command updates the
              active.times (see active(5)) file.

       param letter value
              Change the command-line parameters of the server.  The combination of defaults make
              it  possible  to  use  the text of the Control header directly.  Letter is the innd
              command-line option to set, and value is the  new  value.   For  example,  ``i  5''
              directs  the  server to allow only five incoming connections.  To enable or disable
              the action of the ``-n'' flag, use the letter ``y'' or ``n'', respectively, for the
              value.

       pause reason
              Pause  the  server  so  that  no  incoming  articles  are  accepted.   No  existing
              connections are closed, but the history database is closed.  This command should be
              used for short-term locks, such as when replacing the history files.  If the server
              was not started with the ``-ny'' flag, then this command also  does  a  ``readers''
              command with ``no'' as the flag and reason as the text.

       readers flag text
              Allow  or  disallow  newsreaders.   If  flag  starts  with  the  letter  ``n'' then
              newsreading is disallowed, by causing the server to pass the text as the  value  of
              the  nnrpd(8) ``-r'' flag.  If flag starts with the letter ``y'' and text is either
              an empty string, or the same string that was used when newsreading was  disallowed,
              then newsreading will be allowed.

       reject reason
              Remote connections (those that would not be handed off to nnrpd) are rejected, with
              reason given as the explanation.

       reload what reason
              The server updates its in-memory  copies  of  various  configuration  files.   What
              identifies  what  should be reloaded.  If it is an empty string or the word ``all''
              then everything is reloaded; if  it  is  the  word  ``history''  then  the  history
              database  is  closed  and  opened,  if  it  is  the  word  ``hosts.nntp''  then the
              hosts.nntp(5) file is reloaded; if it is the word ``active'' or ``newsfeeds''  then
              both   the   active   and   newsfeeds  files  are  reloaded;  if  it  is  the  word
              ``overview.fmt'' then the overview.fmt(5) file is reloaded.   If  it  is  the  word
              ``filter.perl''  then  the  filter_innd.pl  file  is reloaded.  If a Perl procedure
              named ``filter_before_reload''  exists,  it  will  be  called  prior  to  rereading
              filter.tcl.   If  a Perl procedure named ``filter_after_reload'' exists, it will be
              called after filter.pl has been reloaded.   Reloading  the  Perl  filter  does  not
              enable  filtering if it is disabled; use filter to do this.  The reason is reported
              to syslog.  There is no way  to  reload  the  data  inn.conf(5)  file;  the  server
              currently only uses the ``pathhost'' parameter, so this restriction should not be a
              problem.

       renumber group
              Scan the spool directory for the specified newsgroup and update the low-water  mark
              in the active file.  If group is an empty string then all newsgroups are scanned.

       reserve reason
              The  next  ``pause''  or  ``throttle''  command  must use reason as its text.  This
              ``reservation'' is cleared by giving an empty string for the reason.  This  command
              is  used by programs like expire(8) that want to avoid running into other instances
              of each other.

       rmgroup group
              Remove the specified newsgroup.  This is done by  editing  the  active  file.   The
              spool directory is not touched, and any articles in the group will be expired using
              the default expiration parameters.  Unlike the ``newgroup'' command,  this  command
              does not update the active.times file.

       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 ``throttle'' command first.

       signal sig site
              Signal sig is sent to the specified site, which must be a channel or exploder feed.
              Sig  can be a numeric signal number or the word ``hup,'' ``int,'' or ``term''; case
              is not significant.

       throttle reason
              Input is throttled so that all existing connections are closed and new  connections
              are  rejected.   The history database is closed.  This should be used for long-term
              locks, such as when expire is being run.  If the server was not  started  with  the
              ``-ny''  flag, then this command also does a ``readers'' command with ``no'' as the
              flag and reason as the text.

       trace item flag
              Tracing is turned on or off for the specified item.  Flag  should  start  with  the
              letter  ``y'' or ``n'' to turn tracing on or off.  If item starts is a number, then
              tracing is set for the specified innd channel, which must be for an  incoming  NNTP
              feed.  If it starts with the letter ``i'' then general innd tracing is turned on or
              off.  If it starts with the letter ``n'' then future nnrpd's will or will not  have
              the ``-t'' flag enabled, as appropriate.

       xabort reason
              The server logs the specified reason and then invokes the abort(3) routine.

       xexec path
              The  server  gets  ready  to  shut itself down, but instead of exiting it execs the
              specified path with all of its  original  arguments.   If  path  is  ``innd''  then
              /usr/sbin/innd  is  invoked;  if  it  is  ``inndstart'' then /usr/sbin/inndstart is
              invoked; if it is an empty string, it will invoke the appropriate program depending
              on whether or not it was started with the ``-p'' flag; any other value is an error.

       In  addition  to  being acted upon within the server, certain commands can be forwarded to
       the appropriate child process.  If the site receiving the command is an exploder (such  as
       buffchan(8))  or  it  is  a  funnel  that  feeds into an exploder, then 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 ``W'' flag (see newsfeed(5)), then the site name will be  appended
       to the command; otherwise no argument is appended.

BUGS

       Ctlinnd uses the inndcomm(3) library, and is therefore limited to server replies no larger
       than 4k.

HISTORY

       Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.  This is revision 1.39,  dated
       1996/10/29.

SEE ALSO

       active(5), expire(8), innd(8), inndcomm(3), inn.conf(5), newsfeeds(5), overview.fmt(5).

                                                                                       CTLINND(8)