Provided by: inn_1.7.2debian-32_i386 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)