CTLINND(8)						      System Manager's Manual							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 ``-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 val-
	      ues  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 brack-
	      ets 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 receiv-
       ing 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)