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  com­
       mand,  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 wait­
              ing 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 <CTLINND_TIMEOUT in include/config.h> (typi­
              cally 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 com­
              mand 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(5)  file
       directly.

       The complete list of commands follows.  Note that all com­
       mands 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 "".

              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  direc­
              tory 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  throttled  manu­
              ally,  this  command  causes it to briefly open the
              history database.  And if the server is  paused  or
              throttled   except   that  case,  this  command  is
              rejected.

       allow reason
              Remote connections are allowed.  The reason must be
              the same text given with an earlier ``reject'' com­
              mand, 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 throttled manually, this command
              causes it to briefly  open  the  history  database.
              And  if  the  server  is paused or throttled except
              that case, this command is rejected.

       changegroup group rest
              The newsgroup group is changed so that  its  fourth
              field  in  the active file becomes the value speci­
              fied 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

              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.

       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  throt­
              tled  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.

              Reset  the lowmarks in the active file based on the
              contents of the given file. Each line in  the  file
              must be of the form:

                  group low-value

              for example

                  comp.lang.c++    243

       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 and relevant information of channel
              number nnn or of all channels if  it  is  an  empty
              string.  Format is:

                   f1:f2:f3:f4:f5

              And meaning of each field is:

                   f1   name of this channel
                   f2   channel number
                   f3   channel type
                   f4   idle time for this channel(nntp type)
                        or process id(process type)
                   f5   channel status(nntp type)

              F3 is one of followings:

                   control        control channel which is used
                                  for ctlinnd
                   file           file channel which is used for
                                  file feed
                   localconn      local channel which is used for
                                  nnrpd or rnews
                   nntp           nntp channel which is used for
                                  current remote connection
                   proc           process channel which is used
                                  for process feed
                   remconn        remote channel which will be
                                  used for nntp

              Channel  status  shows  if the channel is paused or
              not.   Nothing  is  shown  unless  the  channel  is
              paused.  Or ``paused'' is shown.  ``Paused'' status
              happens, if the number  of  remote  connection  for
              that  label  in  incoming.conf(5)  is beyond ``max-

              connected.

       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  newsmaster (as specified at
              configure time, ``usenet''  by  default),  and  the
              rest  parameter  can be omitted and will default to
              ``y''.  This command can be done while  the  server
              is  only  throttled  manually  or  running; it will
              update its internal state when a ``go'' command  is
              sent.   This  command updates the active.times (see
              active(5)) file.  This command  is  forwarded;  see
              below.

       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.

       perl flag
              Enable  or  disable   perl   news   filtering,   if
              <--with-perl is specified at configure>.   If  flag
              starts with the  letter  ``y''  then  filtering  is
              enabled.   If  it starts with ``n'', then filtering
              is disabled.

       python flag
              Enable  or  disable  Python  news   filtering,   if
              <--with-python is specified at configure>.  If flag
              starts with the  letter  ``y''  then  filtering  is

              is disabled.

       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 ``incom­
              ing.conf''  then  the  incoming.conf(5)   file   is
              reloaded;  if  it is the word ``active'' or ``news­
              feeds'' 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
              <--with-perl  is  specified at configure> and it is
              the word ``filter.perl''  then  the  filter_innd.pl
              file is reloaded.  If a Perl procedure named ``fil­
              ter_before_reload'' exists, it will be called prior
              to  rereading  filter_innd.pl.  If a Perl procedure
              named ``filter_after_reload'' exists,  it  will  be
              called  after  filter_innd.pl.   has been reloaded.
              Reloading the Perl filter does not enable filtering
              if  it  is  disabled;  use  perl  y to do this. The
              startup_innd.pl  file  cannot  be   reloaded.    If
              <--with-python is specified at configure> and it is
              the word ``filter.python'' then the  filter_innd.py
              file  is reloaded.  If a Python method named ``fil­
              ter_before_reload'' exists, it will be called prior
              to  rereading  filter_innd.py.   If a Python method
              named ``__init__'' exists, it will be called  after
              filter_innd.py.   has been reloaded.  Reloading the
              Python filter does not enable filtering  if  it  is
              disabled;  use python y to do this.  If <--with-tcl
              is specified at  configure>  and  it  is  the  word
              ``filter.tcl''   then   the   filter.tcl   file  is
              reloaded.   If  a  TCL   procedure   named   ``fil­
              ter_before_reload'' exists, it will be called prior
              to rereading filter.tcl.  If a TCL procedure  named

              after filter.tcl has been reloaded.  Reloading  the
              Tcl  filter does not enable filtering if it is dis­
              abled; use filter to do this.  The startup.tcl file
              cannot be reloaded.  The reason is reported to sys­
              log.   There  is  no  way  to   reload   the   data
              inn.conf(5) file.

       renumber group
              Scan  overview database for the specified newsgroup
              and update the low-water mark and hi-water mark  in
              the  active file.  If group is an empty string then
              all newsgroups are scanned.  Renumber never  works,
              unless  overview data is created.  See the descrip­
              tion  of  ``enableoverview''  in  inn.conf(5)   for
              overview creation.

       reserve reason
              The next ``pause'' or ``throttle'' command must use
              reason as  its  reason.   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.  This command can
              be done while the server is only throttled manually
              or  running.  This command is forwarded; see below.

       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  connec­
              tions.

              It  is  a  good idea to send a ``throttle'' command
              first.

              If <--with-python is specified at configure> and  a
              Python  method  named  ``filter_close''  exists, it
              will be called just before innd exits.

       signal sig site
              Signal sig is sent to  the  specified  site,  which
              must  be  a channel or exploder feed.  Sig can be a

              or ``term''; case is not significant.

       tcl flag
              Enable   or   disable   Tcl   news   filtering,  if
              <--with-tcl is specified at configure>.   If   flag
              starts  with  the  letter  ``y''  then filtering is
              enabled.  If it starts with ``n'',  then  filtering
              is disabled.

       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 ``read­
              ers'' command with ``no'' as the flag and reason as
              the text.

       timer off|interval
              Performance monitoring is turned off if ``off''  or
              ``0''  is  specified, otherwise, statistics will be
              reported every interval  seconds  to  syslog.   See
              inn.conf(5)  for  information  on  how  to  set the
              startup default.

       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  num­
              ber,  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 appropri­
              ate.   ``n''  does  not affect to nnrpd with ``-D''
              (running as a daemon).

       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 <PREFIX specified  with
              --prefix  at  configure>/inndstart  with all of its
              original arguments except for ``-r''.  Path can  be
              any  of ``innd'', ``inndstart'' or an empty string.
              any other value is an error.

       In addition to being acted upon within the server, certain

       cess.  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 InterNet­
       News.  This is revision 1.16.2.3, dated 2001/03/11.


SEE ALSO

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


Man(1) output converted with man2html