STEVEDORE
NAMESYNOPSIS
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