Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CTLINND(8)		  InterNetNews Documentation		    CTLINND(8)

NAME
       ctlinnd - Control the main InterNetNews daemon

SYNOPSIS
       ctlinnd [-hs] [-t timeout] [command [argument ...]]

DESCRIPTION
       ctlinnd sends a message to the control channel of innd(8), the main
       InterNetNews daemon.

       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	an exit	code for ctlinnd.  If the server successfully
       performed the command, ctlinnd will print the reply on standard output
       and exit	with a status of zero.	If the server could not	perform	the
       command,	it will	direct ctlinnd to exit with a status of	one.  By
       default,	ctlinnd	will wait forever for a	response from innd; this can
       be changed with the -t flag.

       The "shutdown", "xabort", and "xexec" commands do not generate a	reply,
       since they cause	innd to	exit.  After these commands, ctlinnd will
       always exit silently with a status of zero.

OPTIONS
       -h  Prints a command summary.  If a command is given along with the -h
	   flag, only the usage	for that command will be given.

       -s  If the command was successful, don't	print the output from innd.

       -t timeout
	   Specifies how long to wait for the reply from the server, for
	   commands other than "shutdown", "xabort", and "xexec".  timeout is
	   the number of seconds to wait.  A value of zero says	to wait
	   forever, and	a value	less than zero says not	to wait	at all but
	   just	exit immediately with status zero.  When waiting for a reply,
	   ctlinnd will	check every two	minutes	to be sure the server is still
	   running, to make it less likely that	ctlinnd	will just hang.

	   The default is zero,	indicating that	ctlinnd	should wait forever.

COMMANDS
       Here is the complete list of supported commands.	 Note that nearly all
       commands	have a fixed number of arguments.  If a	parameter may be an
       empty string, it	is still necessary to pass the empty string to ctlinnd
       as an argument (specified in the	shell as two adjacent quotes, like
       '').

       addhist message-id arrival expires posted token
	   Add an entry	to the history database	for message-id.	 The angle
	   brackets around the message-ID are optional.	 It should normally be
	   protected from the shell with single	quotes.

	   arrival, expires, and posted	should be the number of	seconds	since
	   epoch and indicate when the article arrived,	when it	expires	(via
	   the Expires:	header), and when it was posted	(given in the Date:
	   header), respectively.  expires should be 0 if the article doesn't
	   have	an Expires: header.  token is the storage API token for	the
	   article, and	may be empty.

	   This	command	can only be used while the server is running, and will
	   be rejected if the server is	paused or throttled.

       allow reason
	   Allow remote	connections, reversing a prior "reject"	command.
	   reason must be the same text	given to the "reject" command, or the
	   empty string	(which matches any reason).

       begin site
	   Begin feeding site.	The server will	rescan the newsfeeds file to
	   find	the specified site and set up a	newsfeed for it.  If the site
	   already existed, a "drop" for that site 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 control message; it	only
	   affects the local system.  The angle	brackets around	the message-ID
	   are optional.  It should normally be	protected from the shell with
	   single quotes (and not double quotes).  For instance:

	       ctlinnd cancel 'test@foo.bar'

	   Note	that the history database is updated with the specified
	   message-ID so if an article with the	same message-ID	is afterwards
	   received, it	will be	rejected; it is	useful for rejecting spam
	   before it arrives.

	   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 status
	   The newsgroup group is changed so that its status (the fourth field
	   in the active file) becomes status.	This may be used to make an
	   existing group moderated or unmoderated, for	example.

	   This	command, unlike	"newgroup" or "rmgroup", can only be used
	   while the server is running,	and will be rejected if	the server is
	   paused or throttled.

       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.

       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
	   brief status	about all feeds	if site	is the empty string.

       flush site
	   Flush the buffer for	the specified site.  The action	taken depends
	   on the type of feed the site	receives; see newsfeeds(5) for more
	   information.	 This is useful	when the site is being fed by a	file
	   and batching	is about to start, or to cleanly shut down and respawn
	   a channel feed.  If site is an empty	string,	all sites are flushed
	   and the active file and history database are	also flushed to	disk.
	   This	command	is forwarded; see NOTES	below.

	   Flushing the	innfeed	channel	feed is	the recommended	method of
	   restarting innfeed to pick up new configuration.  innd will spawn a
	   new innfeed process while the old process shuts down	cleanly.

       flushlogs
	   Close the news and error log	files and rename them to add ".old" to
	   the file name, then open fresh news and error logs.	The active
	   file	and history database are also flushed to disk.	Exploder and
	   process channels are	reopened so that they properly take into
	   account the new log files.

       go reason
	   Re-open the history database	and start accepting articles again,
	   reversing a previous	"pause"	or "throttle" command.	reason must be
	   either the empty string or match the	text that was given to the
	   earlier "pause" or "throttle" command.

	   If a	"reject" command is in effect, this will also reverse it by
	   doing the equivalent	of an "allow" command if the reason matches
	   reason.  Likewise, if a "reserve" command had been given, this will
	   clear the reservation if reason matches the text that was given to
	   "reserve".

	   The history database	is automatically closed	on "throttle" or
	   "pause" and reopened	on "go", so the	history	database can be
	   replaced during the pause or	throttle without requiring an explicit
	   "reload" command.  If any other configuration files or the active
	   file	were modified, a "reload" command should be given to force the
	   server to re-read those files.

	   If the server throttled itself because it accumulated too many I/O
	   errors, this	command	will reset the error count.

	   If innd was not started with	the -n y flag, this command also does
	   the equivalent of a "readers" command with "yes" as the flag	and
	   reason as the text.

       hangup channel
	   Close the socket for	the specified incoming channel.	 This may be
	   useful when an incoming connection appears to be hung (although
	   innd	will close idle	connections automatically after	a timeout).

       help [command]
	   Print a command summary for all commands, or	just command if	one is
	   specified.  This is equivalent to the -h option.

       kill signal site
	   Signal signal is sent to the	process	underlying the specified site,
	   which must be a channel or exploder feed.  signal may be a numeric
	   signal number or one	of "hup", "int", or "term"; case is not
	   significant.

       logmode
	   Cause the server to log its current operating mode to syslog.

       lowmark file
	   Reset the low water marks in	the active file	based on the contents
	   of file.  Each line in file must be of the form:

	       group low-value

	   For example:

	       comp.lang.c++ 243

	   This	command	is mostly used by news.daily to	update the active file
	   after nightly expiration.

       mode
	   Print the server's operating	mode as	a multi-line summary of	the
	   parameters and the operating	state.	The parameters in the output
	   correspond to command-line flags to innd and	give the current
	   settings of those parameters	that can be overridden by command-line
	   flags.

       name channel
	   Print the name and relevant information for the given incoming or
	   outgoing channel, or	for all	channels if channel is an empty
	   string.  The	response is formatted as:

	       <name>:<number>:<type>:<idle>:<status>

	   where <name>	is the name of the channel, <number> is	its number
	   (generally the same as the file descriptor assigned to it), <idle>
	   is the idle time for	an NNTP	channel	or the process ID for a
	   process channel, and	<status> is the	status for NNTP	channels.

	   The type is one of the following values:

	       control	   Control channel for ctlinnd
	       file	   An outgoing file feed
	       localconn   Local channel used by nnrpd and rnews for posting
	       nntp	   NNTP	channel	for remote connections
	       proc	   The process for a process feed
	       remconn	   The channel that accepts new	remote connections

	   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 will be paused	automatically if the
	   number of remote connections	for that label in incoming.conf	is
	   greater than	max-connections	within hold-time seconds.

       newgroup	group [status [creator]]
	   Create the specified	newsgroup.  The	status parameter is the	fourth
	   field of the	active file entry, as described	in active(5).  If it
	   is not an equal sign, only the first	character is used.  creator
	   should be the identity of the person	creating the group.  If	the
	   newsgroup already exists, this is equivalent	to the "changegroup"
	   command.

	   creator, encoded in UTF-8 if	given, may be omitted; if so, it will
	   default to the newsmaster (as specified at configure	time, normally
	   "usenet").  status may also be omitted; if so, it will default to
	   "y" (a normal, unmoderated group).  The combination of defaults
	   make	it possible to use the text of the Control: header directly
	   (although don't do this without checking the	syntactic validity of
	   the header first).

	   This	command	can only be done while the server is running or
	   throttled manually.	It will	update its internal state when a "go"
	   command is sent.  This command updates the active.times file	as
	   well.  This command is forwarded; see NOTES below.

       param letter value
	   Change the specified	server parameter.  letter is the innd command-
	   line	option to set and value	is the new value.  For example:

	       ctlinnd param i 5

	   would direct	the server to allow only five incoming connections.
	   To enable or	disable	the action of the -n flag, use "n" for the
	   letter and "y" or "n", respectively,	for the	value.

	   The supported values	for letter are "a", "c", "H", "i", "l",	"n",
	   "o",	"T", "t", and "X".

       pause reason
	   Pause the server so that no incoming	articles are accepted.	No
	   existing connections	are closed, but	the history database is
	   closed.  This should	be used	for short-term locks, such as when
	   replacing the history database.  If the server was not started with
	   the -n y flag, this command also does the equivalent	of a "readers"
	   command with	"no" as	the flag and reason as the text, encoded in
	   UTF-8.

       perl flag
	   Enable or disable Perl filtering.  This command is only available
	   if INN was built with Perl filtering	support.  If flag starts with
	   "y",	filtering is enabled; if it starts with	"n", filtering is
	   disabled.

	   When	filtering is disabled, if the filter_innd.pl Perl filter
	   defined a function "filter_end", it will be called prior to the
	   deactivation	of the filter.

       python flag
	   Enable or disable Python filtering.	This command is	only available
	   if INN was built with Python	filtering support.  If flag starts
	   with	"y", filtering is enabled; if it starts	with "n", filtering is
	   disabled.

       readers flag text
	   Allow or disallow readers.  If flag starts with the letter "n",
	   then	reading	is disallowed by causing the server to pass text as
	   the value of	the -r flag to nnrpd.  If flag starts with the letter
	   "y" and text	is either an empty string or the same string, encoded
	   in UTF-8, that was used when	reading	was disabled, reading will be
	   re-enabled.

	   This	command	has no effect if nnrpd is being	run separately rather
	   than	spawned	by innd.

       reject reason
	   Remote connections (those that would	not be handed off to nnrpd)
	   are rejected	with reason given as the explanation, encoded in
	   UTF-8.  Existing connections	are not	closed.

       reload what reason
	   Update the in-memory	copy of	server configuration files.  what
	   identifies what should be reloaded, and reason is reported to
	   syslog in the message noting	the reload.

	   There is no way to reload inn.conf, storage.conf, or	other
	   configuration files for the storage or overview backends.  To pick
	   up changes to those files, use "ctlinnd xexec innd" to restart
	   innd.

	   If what is the empty	string or the word "all", everything is
	   reloaded.  If it is the word	"history", the history database	is
	   closed and re-opened.  If it	is the word "incoming.conf", the
	   corresponding file is reloaded.  If it is the word "active" or
	   "newsfeeds",	both the active	and newsfeeds files are	reloaded,
	   which will also cause all outgoing feeds to be flushed and
	   restarted.

	   If what is the word "filter.perl", the filter_innd.pl file is
	   reloaded.  If the Perl filter defined a function
	   "filter_before_reload", it will be called prior to re-reading
	   filter_innd.pl.  If the Perl	function "filter_after_reload" is
	   defined, it will be called after filter_innd.pl has been reloaded.
	   Reloading the Perl filter does not enable filtering if it has been
	   disabled; use "perl y" to do	this instead.  startup_innd.pl cannot
	   be reloaded.	 This file is not available for	reloading unless INN
	   was compiled	with Perl filtering support.

	   If what is the word "filter.python",	the filter_innd.py file	is
	   reloaded.  If a Python method named "filter_before_reload" exists,
	   it will be called prior to re-reading 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 has been disabled; use "python y"	to do
	   this.  This file is not available for reloading unless INN was
	   compiled with Python	filtering support.

       renumber	group
	   Update the low water	and high water marks for group in the active
	   file	based on the information in the	overview database.  Regardless
	   of the contents of the overview database, the high 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 the empty
	   string, all newsgroups are renumbered.  Renumber only works if
	   overview data has been created (if enableoverview is	set to true in
	   inn.conf).

       renumberlow file
	   Identical to	the "lowmark" command.

       reserve reason
	   Require the next "pause" or "throttle" command to use reason	as its
	   reason, encoded in UTF-8.  This reservation is cleared by giving an
	   empty string	for the	reason.	 This is used by programs like expire
	   to coordinate pauses	and throttles of the server and	avoid
	   trampling on	other instances	of themselves.

       rmgroup group
	   Remove the specified	newsgroup.  The	group is removed from the
	   active file and its overview	information is purged, making it
	   immediately unavailable to readers.	Unlike the "newgroup" command,
	   this	command	does not update	the active.times file.

	   This	command	can only be done while the server is running or
	   throttled manually.	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 so that feeds can be shut down more
	   gracefully.

	   If Perl or Python filtering is compiled in and enabled, certain
	   functions are called	at "throttle" or "shutdown" (to	save filter
	   state to disk, for example).	 Consult the embedded filter
	   documentation for details.

       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.  A parser for this
	   file	is provided in the contrib tree	of the INN distribution.

       status (off | interval)
	   Adjust the frequency	with which innd	reports	status information to
	   syslog.  Status reporting is	turned off if "off" or 0 is given as
	   the argument.  Otherwise, status will be reported every interval
	   seconds.  See status	in inn.conf(5) for information on how to set
	   the default.

       throttle	reason
	   Close all existing incoming connections and outgoing	feeds and
	   reject new connections.  Close the history database.	 This should
	   be used for long-term locks or for running a	large number of
	   "newgroup" and "rmgroup" commands without restarting	all outgoing
	   feeds between each one.  (Note that changing	the status of existing
	   newsgroups when the server is throttled cannot be done.)

	   If the server was not started with the -n y flag, then this command
	   also	does the equivalent of a "readers" command with	"no" as	the
	   flag	and reason as the text,	encoded	in UTF-8.

       timer (off | interval)
	   Adjust the frequency	with which innd	reports	performance
	   information to syslog.  Performance monitoring is turned off	if
	   "off" or 0 is given as the argument.	 Otherwise, statistics will be
	   reported every interval seconds to syslog.  See timer in
	   inn.conf(5) for information on how to set the default.

       trace item flag
	   Turn	tracing	on or off for the specified item.  flag	should start
	   with	the letter "y" or "n" to turn tracing on or off, respectively.
	   If item starts with a number, tracing is set	up for the specified
	   innd	channel, which must be an incoming NNTP	feed.  If it starts
	   with	the letter "i",	general	innd tracing is	turned on or off.  If
	   it starts with the letter "n", future nnrpd processes spawned by
	   "innd" will or will not be passed the -t flag, as appropriate.
	   This	will not affect	any nnrpd processes already running, or	nnrpd
	   processes started by	some means other than innd.

       xabort reason
	   Log the specified reason and	then abort.  On	most systems, this
	   will	cause innd to dump a core file.	 This is only useful for
	   debugging.

       xexec path
	   Shut	down the server, but then rather than exiting, exec innd with
	   all of its original arguments except	for -r.	 path may be either
	   "innd" or an	empty string, both of which are	equivalent.  Any other
	   value is an error.

	   This	is the easiest way to start a new copy of innd after upgrading
	   or reload configuration files that can't be reloaded	via the
	   "reload" command.

NOTES
       In addition to being acted on by	the server, certain commands can be
       forwarded to an appropriate child process.  If the site receiving the
       command is an exploder (such as buffchan) or a funnel that feeds	into
       an exploder, 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 newsfeeds(5)	for more information
       on feed specifications),	the site name will be appended to the command;
       otherwise, no argument is appended.

BUGS
       ctlinnd uses Unix domain	sockets	on most	systems	to communicate with
       innd and	is therefore limited by	whatever maximum packet	size the
       operating system	imposes	on Unix	domain datagrams.  This	may mean that
       server replies are limited to 4 KB on some systems.

HISTORY
       Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.  Rewritten
       in POD by Russ Allbery <eagle@eyrie.org>.

       $Id: ctlinnd.pod	9767 2014-12-07	21:13:43Z iulius $

SEE ALSO
       active(5), active.times(5), buffchan(8),	incoming.conf(5), innd(8),
       inndcomm(3), inn.conf(5), newsfeeds(5), nnrpd(8).

INN 2.6.1			  2015-09-12			    CTLINND(8)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | COMMANDS | NOTES | BUGS | HISTORY | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ctlinnd&sektion=8&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help