ctlinnd



CTLINND(8)                                                          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 Inter-
       NetNews 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.  (Note
       that  ctlinnd  need  not always exit immediately, see the ‘‘-t’’ flag.)
       The ‘‘shutdown’’, ‘‘xabort’’, and ‘‘xexec’’ commands do not generate  a
       reply  (because  once  innd  has successfully exited, it is too late to
       send a reply to ctlinnd); after these  commands,  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 timeout
              The ‘‘-t’’ flag can be used to specify how long to wait for  the
              reply  from  the  server  (for commands other than ‘‘shutdown’’,
              ‘‘xabort’’, and ‘‘xexec’’).  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 (that is,
              exit  immediately  with status zero).  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 <CTLINND_TIMEOUT in include/config.h> (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.

       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 token
              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 numbers indicating the number of  seconds  since  the
              epoch.   Exp  being  zero indicates the article does not have an
              Expires header.  Token is the storage API token indicating where
              the  article  is  stored.   If the server is throttled manually,
              this command causes it to briefly open the history database.  If
              the  server  is  paused  or throttled for any other reason, this
              command is rejected.

       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  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 NOTES 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.  If
              the  server  is  paused  or throttled for any other reason, this
              command is rejected.

       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 unmoder-
              ated,  for  example.   This  command  can only be used while the
              server is running (not throttled), unlike newgroup or rmgroup.

       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 NOTES 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
              about  to start.  If site is an empty string, then all sites are
              flushed and the active file and history databases are also writ-
              ten out.  This command is forwarded; see NOTES 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  writ-
              ten 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 reserva-
              tion 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.

       kill signal site
              Signal signal is sent to the specified site,  which  must  be  a
              channel or exploder feed.  Signal can be a numeric signal number
              or the word ‘‘hup’’, ‘‘int’’, or ‘‘term’’; case is not  signifi-
              cant.

       lowmark file
              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.   The  response  is
              formatted as:

                   f1:f2:f3:f4:f5

              Where the meanings of the fields are:

                   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)

              The channel type (f3) is one of following:

                   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  indicates whether the channel is paused or not.
              Nothing is shown unless the channel is  paused,  in  which  case
              ‘‘paused’’  is  shown.   A  channel  is  paused if the number of
              remote connection for that  label  in  incoming.conf  is  beyond
              ‘‘max-connections’’  within ‘‘hold-time’’ seconds of connection.

       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 identity of the person creating the group as described in
              active(5).  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 only be done while the server is
              throttled manually or running; it will update its internal state
              when  a  ‘‘go’’  command  is  sent.   This  command  updates the
              active.times file (see active.times(5)).  This command  is  for-
              warded; see NOTES below.

       param letter value
              Change  the command-line parameters of the server.  The combina-
              tion 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 speci-
              fied 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 enabled.  If it  starts  with
              ‘‘n’’, then filtering 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 disal-
              lowed, 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.  The reason  is
              reported to syslog.

              There  is  no way to reload the inn.conf file; use ctlinnd xexec
              innd instead.

              If what 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 file is reloaded; if it is the
              word ‘‘active’’ or ‘‘newsfeeds’’ then both the active and  news-
              feeds  files  are  reloaded;  if it is the word ‘‘overview.fmt’’
              then the overview.fmt 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 ‘‘filter_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 ‘‘filter_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  fil-
              ter_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 ‘‘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  fil-
              ter.tcl  has  been  reloaded.  Reloading the Tcl filter does not
              enable filtering if it is disabled; use filter to do this.   The
              startup.tcl file cannot be reloaded.

       renumber group
              Scan  overview  database  for the specified newsgroup and update
              the low-water  mark  and  hi-water  mark  in  the  active  file.
              Regardless of the content of the overview database, the hi-water
              mark will not be decreased (decreasing it  may  cause  duplicate
              article  numbers  to  be assigned after a crash, which can cause
              serious problems with the tradspool storage method).   If  group
              is  an  empty  string then all newsgroups are scanned.  Renumber
              only works if overview data has been created.  (See the descrip-
              tion  of  ‘‘enableoverview’’  in  inn.conf(5)  for details about
              overview creation.)

       renumberlow file
              This command does same as ‘‘lowmark’’ command.

       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 arti-
              cles in the group will still be expired using the default  expi-
              ration  parameters.   Unlike the ‘‘newgroup’’ command, this com-
              mand 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 NOTES 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 connections.

              It is a good idea to send a ‘‘throttle’’ command first.

              If Perl, Python, or TCL filtering is compiled  in  and  enabled,
              certain  functions  are  called  at ‘‘throttle’’ or ‘‘shutdown’’
              (for example, to save filter state to disk), consult the  embed-
              ded filter documentation for details.

       stathist off|filename
              Enable  or disable generation of history performance statistics.
              If the parameter is ‘‘off’’, no statistics are gathered.  Other-
              wise statistics are written to the specified file.  The file can
              be parsed by contrib/stathist.pl.

       status off|interval
              Adjust frequency in seconds at which innd reports status  infor-
              matoin  to syslog.  Status reporting is turned off if ‘‘off’’ or
              ‘‘0’’ is specified.  See ‘‘status’’ in inn.conf(5) for  informa-
              tion on how to set the startup default.

       tcl flag
              Enable  or  disable Tcl news filtering, if <--with-tcl is speci-
              fied 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 ‘‘readers’’  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 ‘‘timer’’ in 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 with a number, then tracing is set for the speci-
              fied  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.   The  ‘‘n’’  flag  does not affect nnrpd’s already
              running or using ‘‘-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 exit-
              ing it exec’s <pathbin in inn.conf>/inndstart with  all  of  its
              original  arguments  except  for  ‘‘-r’’.   Path  can  be any of
              ‘‘innd’’, ‘‘inndstart’’, or an empty string, although all  three
              valid  parameters have exactly the same effect.  Any other value
              is an error.


NOTES

       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  news-
       feeds(5)),  then  the site name will be appended to the command; other-
       wise 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.24.2.2, dated 2004/12/19.


SEE ALSO

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



                                                                    CTLINND(8)

Man(1) output converted with man2html