+++ /dev/null
-.\" $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).
~ian / innduct.git / blobdiff