catd - Agent control server
catd [-R configroot] [-D debugspec]
catd -c
catd [-D debugspec]
catd -I
catd -U
catd is a server that listens to ports for connections and starts Agents as
needed. catd can also start other programs, such as the
catlogger log dispatcher.
The configuration parameters determine the ports to which catd is to listen and the Agents or programs that it is to start.
On UNIX, catd is normally started as a daemon process at system startup or when Agents
are first configured.
On Windows NT, catd normally runs as a service, managed by the service control manager.
To control catd once it is running, use the start program.
- -D debugspecification
-
Set the debug level, debug output file, and other debug control options
supported by caterr_setdebug. The simplest form of this option is a single digit that specifies the
debug level. For more verbose output, increase the level. The debug level
is propagated to any Agents started by catd.
- -R configroot
-
UNIX only. Specify the directory where the configuration files are located.
This option overrides environment variable CATCONFDIR.
- -c
-
UNIX only. Read the configuration information, attempt to listen to all
ports configured, but do not start any programs or Agents.
catd exits with status 3 if no active Agents or programs are configured and
status 0 if there are active configurations. Other exit codes indicate
errors.
- -I
-
Windows NT only. Install catd as a service. A debug level set when installing the service will be
propagated to the service. Output is written to C:\catd.txt.
- -U
-
Windows NT only. Uninstall the catd service.
- .tcp.sportnumber.*
-
All port configuration files are read and Agents are associated with the
ports. Catd listens to these ports and starts Agents when connections arrive.
- .tcp.sportnumber.start
-
If set to ``auto,'' the Agent will be started when connections arrive. If
set to ``off,'' the Agent is disabled, which means that catd will not listen to this port and the Agent will not be started.
On Windows NT, this parameter can be set to ``auto,'' which indicates that
the port will be intercepted by the bindhook module, which in turn will instruct catd to start the Agent when connections arrive.
- .tcp.sportnumber.program
-
The full path to the Agent executable and any arguments that it is to be
given.
- .global.start.failcount
-
- .global.start.failinterval
-
- .global.start.faildisable
-
These three parameters control how processes that exit too rapidly will be
treated. Programs that repeatedly exit immediately after being started are
probably incorrectly configured or faulty, and continually restarting them
will only consume system resources unnecessarily.
If a program exits more than failcount times in failinterval
seconds, it will not be restarted again for faildiable seconds.
- .global.start.*
-
Nodes under
global.start
that have subnodes for start
and
program
are programs started by catd.
- .global.start.program.start
-
This parameter can be either ``on'' or ``off.'' If it is ``on,'' the
program will be started as soon as catd is started and restarted if it exits. If the parameter is set to ``off,''
the program will not be started.
- .global.start.program.program
-
The full path to the program executable and any arguments that it is to be
given.
When catd gets a connection on one of the ports on which it is listening, and the
associated Agent is not running, Catd will start the Agent and pass the listening socket to it.
The Agent is responsible for handling all connections to any ports that it
is configured to manage. Catd will stop listening to any ports managed by the Agent while the Agent is
running.
catd opens a pipe to a spawned Agent. On UNIX, the pipe is always installed as
the standard input (file descriptor zero). On Windows NT, the pipe handle
is passed as argument to the -C
flag, as a hexadecimal number. If the pipe is closed, the Agent is should
exit.
During startup, catd will send additional -P flags over the pipe, followed by a --. The Agent must support the following commands on the pipe:
- -P portspec [ @sockspec ]
-
Start listening to a the port specified by portspec, which is a string suitable for use as argument to catnet_listen. If a
@sockspec part is present, the socket is being passed from catd to the agent. The sockspec string can be used as an argument to
catsock_fromstring.
This command can also appear as a command line option.
- --
-
Only sent during startup, directly after any
-P
commands.
- remove portspec
-
Stop listening to the port specified by the portspec string, which will be a string previously passed by a
-p
command, with no @sockspec part.
- idle seconds
-
Change the idle timeout to a new number of seconds. The Agent should exit when there have been no active client connections
for the indicated number of seconds.
- lifespan seconds
-
Change the life span to a new number of seconds. When the Agent has been running for the indicated number of seconds, it
should exit as soon as there are no active clients.
- reconfig
-
The Agent is to re-read its configuration parameters and try to implement
as many as possible of the changes that may have been made.
- exit
-
The Agent is to exit.
UNIX only. These two variables are also exported by catd, for use by Agents and programs started by catd. Options defined on the command line override environment variables.
- CATCONFDIR
-
Setting this is equivalent to starting catd with the
-R
option.
- CATDEBUG
-
Setting this is equivalent to starting catd with the
-D
option.
cat, catlogger, start, config, caterr_setdebug,
catgen_getopt