STEVEDORE

NAME
SYNOPSIS
DESCRIPTION
CONFIGURATION
OPTIONS
MIB
SEE ALSO
AUTHORS
BUG REPORTS
COPYRIGHT

NAME

stevedore - container state collector and SNMP agent daemon

SYNOPSIS

stevedore [-Fsd] [-f FILE] [--config-file=FILE] [--foreground] [--single] [--debug]

stevedore -? | --help | -V | --version

DESCRIPTION

Monitoring the health state of a collection of docker containers is based on the premise that each container is responsible for a certain service, which is assigned an identifier (SID). In the contrast to container IDs, service IDs are not necessarily unique for each container. It is quite OK (and even common) for several containers to have same SID. This can happen, for example, if one runs a distributed database server, with one container running master server and the rest running its slaves.

Each container is supposed to run the tallyman(1) command as part of its HEALTHCHECK configuration. This tool takes as its argument the command line that does the actual checking, collects its return and sends it over to the stevedore daemon that acts as a collector (see tallyman(1), for details).

The purpose of stevedore is two-fold. First, it provides a RESTful service that collects health check reports from multiple containers, and secondly it acts as SNMP subagent, delivering the collected information.

CONFIGURATION

The program reads its configuration from file /etc/stevedore.conf (exact location can differ depending on how the package was configured; if unsure, examine the output of stevedore --help). The file must exist and be readable.

The configuration consists of statements. Each statement begins with a keyword, followed by one or more arguments and is terminated with a semicolon. Arguments containing whitespace or special characters ( {, }, or ;) must be quoted.

Whitespace characters (horizontal space, tabulation and newline) are ignored except as they serve to separate tokens. Comments can be introduced by # and //, in which case they extend to the end of the physical line, or enclosed between /* and */, in which case they can occupy multiple lines. Comments may appear anywhere where white space may appear in the configuration file.

Statements
The following statements can appear in the configuration file:
listen
IP:PORT

Listen on this IP address and port. Default is 0.0.0.0:8990, i.e. all available IP addresses, port 8990.

pidfile FILE

Store PID of the daemon process in FILE. If this statement is not supplied, no pidfile will be used.

user UID

Run as this user. UID is either the user login name or numeric UID prefixed with a plus sign.

group GID

Run with this group privileges. GID is either the group name or numeric GID prefixed with a plus sign. In the absence of this statement, the primary group of the UID specified with the user statement will be used. Auxiliary groups of UID are always honored.

service SID

Define service to monitor. This is actually the only statement that must be present in the configuration file. It informs stevedore that it will be receiving updates about service ID SID and instructs it to create SNMP OIDs for reporting the state of this service.

There should be as many service statements as there are services to monitor.

instance-state-ttl SECONDS

Sets the time during which the state of the instance (container) is retained in cache. If no update arrives during the specified number of seconds, the container is marked as expired. Default is 30 seconds.

Syslog configuration
Unless the program is started in foreground mode (see the -F option), its logging output goes to syslog facility daemon. The syslog configuration can be changed using the following block statement:
syslog {
facility NAME;
tag STRING;
}

The substatements are:
facility
NAME

Set syslog facility. NAME is one of: user, daemon, auth, authpriv, mail, cron, local0 through local7 (case-insensitive), or a decimal facility number.

tag STRING

Tag syslog messages with this string, instead of the program name.

OPTIONS

-f, --config-file=FILE

Read configuration from FILE.

--config-help

Describe configuration file syntax and variables.

-F, --foreground

By default, stevedore disconnects itself from the controlling terminal and runs as a daemon. This option disables this behavior, instructing it to remain in foreground and print its diagnostic messages on standard error, instead of using the syslog interface. Use it for debugging.

-s, --single

By default, the program runs in two-process mode: there is a top-level sentinel process that starts a single working process and restarts it if it exits on error or signal. The purpose of this design is to catch and recover from possible bugs.

This option instructs stevedore to start the worker process directly.

-d, --debug

Increase debug verbosity.

-?, --help

Display short usage summary.

-V, --version

Display program version and licensing information and exit.

MIB

The MIB is kept in file TALLYMAN-MIB.txt which is normally installed to the location where net-snmp tools expect to find their MIBs.

The following OIDs are defined:
servicesUpTime.0

Total uptime of the Stevedore server.

servicesTotal.0

Total number of configured services.

servicesRunning.0

Number of running services, i.e. services that have at least one running container.

serviceTable

This branch provides a conceptual table of services with the corresponding statistics. It is indexed by serviceIndex. Each row has the following elements:
serviceName

Name of the service.

serviceInstances

Number of running instances (containers) in this service.

instanceTable

This branch provides a conceptual table of instances and is indexed by instanceIndex. Each row has the following OIDs:
instanceName

Hostname of the instance.

instanceService

Service name (ID) of the instance.

instanceState

State of the instance. Possible values are: stopped, running, expired, and error.

instanceTimeStamp

Time of the last successful probe.

instanceErrorMessage

Error message associated with this instance if instanceState is error.

SEE ALSO

tallyman(1).

AUTHORS

Sergey Poznyakoff

BUG REPORTS

Report bugs to <gray@gnu.org>.

COPYRIGHT

Copyright © 2018 Sergey Poznyakoff
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.


Manpage server at man.gnu.org.ua.

Powered by mansrv 1.1