.\" $Revision: 7062 $
.TH CTLINND 8
.SH NAME
ctlinnd \- control the InterNetNews daemon
.SH SYNOPSIS
.B ctlinnd
[
.B \-h
]
[
.B \-s
]
[
.BI \-t " timeout"
]
.I command
[
.I argument...
]
.SH DESCRIPTION
.I Ctlinnd
sends a message to the control channel of
.IR innd (8),
the InterNetNews server.
.PP
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
.IR ctlinnd .
If the server successfully performed the command,
.I 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
.I ctlinnd
to exit with a status of one.  (Note that
.I ctlinnd
need not always exit immediately, see the ``\fB-t\fP'' flag.)
The ``shutdown'', ``xabort'', and ``xexec'' commands do not generate a
reply (because once
.I innd
has successfully exited, it is too late to send a reply to
.IR ctlinnd );
after these commands,
.I ctlinnd
will always exit silently with a status of zero.
.SH OPTIONS
.TP
.B \-s
If the ``\fB\-s\fP'' flag is
used, then no message will be printed if the command was successful.
.TP
.B \-t timeout
The ``\fB\-t\fP'' 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,
.I ctlinnd
will try every two minutes to see if the server is still running, so it
is unlikely that ``\fB\-t0\fP'' will hang.
The default is set as 
.I <CTLINND_TIMEOUT in include/config.h> 
(typically 
.IR 0 ).
.TP
.B \-h
To see a command summary, use the ``\fB\-h\fP'' flag.
If a command is included when
.I ctlinnd
is invoked with the ``\fB\-h\fP'' flag, then only the usage for that command
will be given.
.PP
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 "".
.TP
.BI addhist " <Message-ID> arr exp post token"
Add an entry to the history database.
This directs the server to create a history line for
.IR Message-ID .
The angle brackets are optional.
.IR Arr ,
.IR exp ,
and
.I 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.
.I Exp
being zero indicates the article does not have an Expires header.
.I 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.
.TP
.BI allow " reason"
Remote connections are allowed.
The
.I reason
must be the same text given with an earlier ``reject'' command, or an
empty string.
.TP
.BI begin " site"
Begin feeding
.IR site .
This will cause the server to rescan the
.I 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.
.TP
.BI cancel " <Message-ID>"
Remove the article with the specified Message-ID from the local system.
This does
.I 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.
.TP
.BI changegroup " group rest"
The newsgroup
.I group
is changed so that its fourth field in the
.I active
file becomes the value specified by the
.I rest
parameter.
This may be used to make an existing group moderated or unmoderated,
for example.
This command can only be used while the server is running (not throttled),
unlike
.B newgroup
or
.BR rmgroup .
.TP
.B checkfile
Check the syntax of the
.I newsfeeds
file, and display a message if any errors are found.
The details of the errors are reported to
.IR syslog (3).
.TP
.BI drop " site"
Flush and drop
.I site
from the server's list of active feeds.
This command is forwarded; see NOTES below.
.TP
.BI feedinfo " site"
Print detailed information about the state of the
feed to
.I site
or more brief status of all feeds if
.I site
is an empty string.
.TP
.BI flush " site"
Flush the buffer for the specified site.
The actions taken depend on the type of feed the site receives; see
.IR newsfeeds (5).
This is useful when the site is fed by a file and batching is about to start.
If
.I site
is an empty string, then all sites are flushed and the
.I active
file and history databases are also written out.
This command is forwarded; see NOTES below.
.TP
.B flushlogs
Close the log and error log files and rename them to have a
.I \&.old
extension.
The history database and
.I active
file are also written out.
.TP
.BI go " reason"
Re-open the history database and start accepting articles after a ``pause''
or ``throttle'' command.
The
.I 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
.I reason
matches the text that was given in the ``reject.''
If a ``reserve'' command was done, this will also clear the reservation if
the
.I 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 ``\fB\-ny\fP'' flag, then this command also
does a ``readers'' command with ``yes'' as the flag and
.I reason
as the text.
.TP
.BI hangup " channel"
Close the socket on the specified incoming channel.
This is useful when an incoming connection appears to be hung.
.TP
.BI help " [command]"
Print a command summary for all commands, or just
.I command
if specified.
.TP
.BI kill " signal site"
Signal
.I signal
is sent to the specified
.IR site ,
which must be a channel or exploder feed.
.I Signal
can be a numeric signal number or the word ``hup'', ``int'', or ``term'';
case is not significant.
.TP
.BI lowmark " file"
Reset the lowmarks in the
.I active
file based on the contents of the given
file. Each line in the file must be of the form:
.IP
.RS
.nf
    group low-value
.fi
.RE
.IP
for example
.IP
.RS
.nf
    comp.lang.c++    243
.fi
.RE
.TP
.BI logmode
Cause the server to log its current operating mode to
.IR syslog .
.TP
.BI mode
Print the server's operating mode as a multi-line summary of the parameters
and operating state.
.TP
.BI name " nnn"
Print the name and relevant information of channel number
.IR nnn ,
or of all channels if it is an empty string.  The response is formatted as:
.sp 1
.in +0.5i
.nf
f1:f2:f3:f4:f5
.fi
.in -0.5i
.sp 1
Where the meanings of the fields are:
.sp 1
.in +0.5i
.nf
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)
.fi
.in -0.5i
.sp 1
The channel type (f3) is one of following:
.sp 1
.in +0.5i
.nf
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
.fi
.in -0.5i
.sp 1
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
.I incoming.conf
is beyond ``max-connections'' within ``hold-time'' seconds of connection.
.TP
.BI newgroup " group rest creator"
Create the specified newsgroup.
The
.I rest
parameter should be the fourth field as described in
.IR active (5);
if it is not an equal sign, only the first letter is used.
The
.I creator
should be the identity of the person creating the group as described in
.IR active (5).
If the newsgroup already exists, this is equivalent to the ``changegroup''
command.
This is the only command that has defaults.
The
.I creator
can be omitted and will default to the newsmaster (as specified at configure
time, ``usenet'' by default), and the
.I 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
.I active.times
file (see
.IR active.times (5)).
This command is forwarded; see NOTES below.
.TP
.BI 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.
.I Letter
is the
.I innd
command-line option to set, and
.I 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 ``\fB\-n\fP'' flag, use the letter ``y''
or ``n'', respectively, for the
.IR value .
.TP
.BI 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 ``\fB\-ny\fP'' flag, then this command also
does a ``readers'' command with ``no'' as the flag and
.I reason
as the text.
.TP
.BI perl " flag"
Enable or disable perl news filtering, if
.IR <\-\-with\-perl\ is\ specified\ at\ configure> .
If
.I flag
starts with the letter ``y'' then filtering is enabled.  If it starts with
``n'', then filtering is disabled.
.TP
.BI python " flag"
Enable or disable Python news filtering, if
.IR <\-\-with\-python\ is\ specified\ at\ configure> .
If
.I flag
starts with the letter ``y'' then filtering is enabled.  If it starts with
``n'', then filtering is disabled.
.TP
.BI readers " flag text"
Allow or disallow newsreaders.
If
.I flag
starts with the letter ``n'' then newsreading is disallowed, by
causing the server to pass the
.I text
as the value of the
.IR nnrpd (8)
\&`\fB`\-r\fP'' flag.
If
.I flag
starts with the letter ``y'' and
.I text
is either an empty string, or the same string that was used when newsreading
was disallowed, then newsreading will be allowed.
.\".TP
.\".BI refile " path group"
.\"The article specified by
.\".I path
.\"is refiled as if it were posted to the newsgroup
.\".IR group .
.TP
.BI reject " reason"
Remote connections (those that would not be handed off to
.IR nnrpd )
are rejected, with
.I reason
given as the explanation.
.TP
.BI reload " what reason"
The server updates its in-memory copies of various configuration files.
.I What
identifies what should be reloaded.
The
.I reason
is reported to
.IR syslog .
.sp 1
There is no way to reload the
.I inn.conf
file; use
.I "ctlinnd xexec innd"
instead.
.sp 1
If
.I 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 ``incoming.conf'' then the
.I incoming.conf
file is reloaded; if it is the word ``active'' or ``newsfeeds'' then both
the
.I active
and
.I newsfeeds
files are reloaded; if it is the word ``overview.fmt'' then the
.I overview.fmt
file is reloaded.
.sp 1
If
.I <\-\-with\-perl is specified at configure>
and it is the word ``filter.perl'' then the
.IR filter_innd.pl
file is reloaded.  If a Perl procedure named ``filter_before_reload'' exists,
it will be called prior to rereading
.IR filter_innd.pl .
If a Perl procedure named ``filter_after_reload'' exists, it will be called
after
.IR filter_innd.pl .
has been reloaded.  Reloading the Perl filter does not enable filtering if
it is disabled; use
.I perl y
to do this. The
.I startup_innd.pl
file cannot be reloaded.
.sp 1
If
.I <\-\-with\-python is specified at configure>
and it is the word ``filter.python'' then the
.I filter_innd.py
file is reloaded.  If a Python method named ``filter_before_reload'' exists,
it will be called prior to rereading
.IR filter_innd.py .
If a Python method named ``__init__'' exists, it will be called
after
.IR filter_innd.py .
has been reloaded.  Reloading the Python filter does not enable filtering if
it is disabled; use
.I python y
to do this.
If
.I <\-\-with\-tcl is specified at configure>
and it is the word ``filter.tcl'' then the
.I filter.tcl
file is reloaded.  If a TCL procedure named ``filter_before_reload'' exists,
it will be called prior to rereading
.IR filter.tcl.
If a TCL procedure named ``filter_after_reload'' exists, it will be called
after
.I filter.tcl
has been reloaded.  Reloading the Tcl filter does not enable filtering if
it is disabled; use
.IR filter
to do this.
The
.I startup.tcl
file cannot be reloaded.
.TP
.BI renumber " group"
Scan overview database for the specified newsgroup and update the
low-water mark and hi-water mark in the
.I 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
.I group
is an empty string then all newsgroups are scanned.
Renumber only works if overview data has been created.
(See the description of ``enableoverview'' in
.IR inn.conf (5)
for details about overview creation.)
.TP
.BI renumberlow " file"
This command does same as ``lowmark'' command.
.TP
.BI reserve " reason"
The next ``pause'' or ``throttle'' command must use
.I reason
as its reason.
This ``reservation'' is cleared by giving an empty string for the
.IR reason .
This command is used by programs like
.IR expire (8)
that want to avoid running into other instances of each other.
.TP
.BI rmgroup " group"
Remove the specified newsgroup.
This is done by editing the
.I active
file.
The spool directory is not touched, and any articles in the group will
still be expired using the default expiration parameters.
Unlike the ``newgroup'' command, this command does not update the
.I active.times
file.
This command can be done while the server is only throttled manually or running.
This command is forwarded; see NOTES below.
.TP
.BI send " feed text..."
The specified
.I text
is sent as a control line to the exploder
.IR feed .
.TP
.BI shutdown " reason"
The server is shut down, with the specified reason recorded in the log
and sent to all open connections.
.sp 1
It is a good idea to send a ``throttle'' command first.
.sp 1
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 embedded filter documentation
for details.
.TP
.BI stathist " off|filename"
Enable or disable generation of history performance statistics.  If the
parameter is ``off'', no statistics are gathered.  Otherwise statistics
are written to the specified file.  The file can be parsed by
.IR contrib/stathist.pl .
.TP
.BI status " off|interval"
Adjust frequency in seconds at which
.I innd
reports status informatoin to syslog.  Status reporting is turned off if
``off'' or ``0'' is specified.  See ``status'' in
.IR inn.conf (5)
for information on how to set the startup default.
.TP
.BI tcl " flag"
Enable or disable Tcl news filtering, if
.IR <\-\-with\-tcl\ is\ specified\ at\ configure> .
If
.I flag
starts with the letter ``y'' then filtering is enabled.  If it starts with
``n'', then filtering is disabled.
.TP
.BI 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
.I 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
.I reason
as the text.
.TP
.BI timer " off|interval"
Performance monitoring is turned off if ``off'' or ``0'' is specified,
otherwise, statistics will be reported every
.I interval
seconds to syslog.  See ``timer'' in
.IR inn.conf (5)
for information on how to set the startup default.
.TP
.BI trace " item flag"
Tracing is turned on or off for the specified
.IR item .
.I Flag
should start with the letter ``y'' or ``n'' to turn tracing on or off.
If
.I item
starts with a number, then tracing is set for the specified
.I innd
channel, which must be for an incoming NNTP feed.
If it starts with the letter ``i'' then general
.I innd
tracing is turned on or off.
If it starts with the letter ``n'' then future
.IR nnrpd 's
will or will not have the ``\-t'' flag enabled, as appropriate.
The ``n'' flag does not affect
.IR nnrpd 's
already running or using ``-D'' (running as a daemon).
.TP
.BI xabort " reason"
The server logs the specified
.I reason
and then invokes the
.IR abort (3)
routine.
.TP
.BI xexec " path"
The server gets ready to shut itself down, but instead of exiting it
.IR exec 's
.I <pathbin in inn.conf>/inndstart
with all of its original arguments except for ``\fB\-r\fP''.
.I 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.
.SH 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
.IR 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
.I ctlinnd
command name.
If the site funnels into an exploder that has an asterisk (``*'') in its ``W''
flag (see
.IR newsfeeds (5)),
then the site name will be appended to the command; otherwise no argument
is appended.
.SH BUGS
.I Ctlinnd
uses the
.IR inndcomm (3)
library, and is therefore limited to server replies no larger than 4k.
.SH HISTORY
Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.
.de R$
This is revision \\$3, dated \\$4.
..
.R$ $Id: ctlinnd.8 7062 2004-12-19 21:41:05Z rra $
.SH "SEE ALSO"
active(5),
active.times(5),
expire(8),
innd(8),
inndcomm(3),
inn.conf(5),
newsfeeds(5),
overview.fmt(5).