NAME

catd - Agent control server

SYNOPSIS

UNIX Synopsis

 catd [-R configroot] [-D debugspec]

 catd -c

Windows NT Synopsis

 catd [-D debugspec]

 catd -I

 catd -U

DESCRIPTION

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.

OPTIONS

-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.

CONFIGURATION PARAMETERS

.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.

INTERACTION WITH AGENTS

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.

ENVIRONMENT

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.

SEE ALSO

cat, catlogger, start, config, caterr_setdebug, catgen_getopt