CTLINND (8)

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 set as <config$CTLINND_TIMEOUT> (typically 0.)

     -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, when <config$PERL_SUPPORT> ==
          DO.  If flag starts with the letter ``y'' then filtering is enabled.
          If it starts with ``n'', then filtering is disabled.


     tcl flag
          Enable or disable Tcl news filtering, when  <config$TCL_SUPPORT>  ==
          DO.  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
          <config$PERL_SUPPORT> == DO and 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.    If
          <config$TCL_SUPPORT>  ==  DO  and it is the word ``filter.tcl'' then
          the  filter.tcl  file  is  reloaded.   If  a  TCL  procedure   named
          ``filter_before_reload''   exists,   it  will  be  called  prior  to
          rereading    filter.tcl.     If    a     TCL     procedure     named
          ``filter_after_reload''  exists,  it will be called after filter.tcl
          has been  reloaded.   Reloading  the  Tcl  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.   The  startup.tcl  file
          cannot be reloaded.

     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    <config$_PATH_INND>     (typically
          /usr/news/bin/innd)

          is invoked; if it  is  ``inndstart''  then  <config$_PATH_INNDSTART>
          (typically  /usr/news/bin/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) .

You can find a summary and links related to this topic
as part of the Mib Software Usenet RKT.