stork-agent - The Stork Agent to Monitor BIND 9 and Kea Services

Synopsis

stork-agent [–listen-stork-only] [–listen-prometheus-only] [-v] [–host=] [–port=] [–skip-tls-cert-verification=] [–prometheus-kea-exporter-address=] [–prometheus-kea-exporter-port=] [–prometheus-kea-exporter-interval=] [-h]

stork-agent register [–server-url=] [–server-token] [–agent-host=] [–agent-port=] [–non-interactive]

Description

The stork-agent is a tool that operates on systems that are running BIND 9 or Kea services. The Stork server typically connects to the Stork agent and uses it to monitor services remotely, but can also act as a stand-alone statistics exporter to Prometheus.

Arguments

The Stork agent’s behavior can be controlled with command-line switches and/or environment variables. The environment variables can be set before running the agent, or they can be loaded from a file using the --use-env-file and --env-file flags. stork-agent takes the following arguments (equivalent environment variables are listed in square brackets, where applicable)

--listen-stork-only

Instructs stork-agent to listen for commands from the Stork server, but not for Prometheus requests. [$STORK_AGENT_LISTEN_STORK_ONLY]

--listen-prometheus-only

Instructs stork-agent to listen for Prometheus requests, but not for commands from the Stork server. [$STORK_AGENT_LISTEN_PROMETHEUS_ONLY]

--hook-directory

The path to the hook directory. [$STORK_AGENT_HOOK_DIRECTORY]

--bind9-path

The path to the BIND 9 configuration file. Does not need to be specified, unless the location is uncommon. [$STORK_AGENT_BIND9_PATH]

--env-file

The environment file location; applicable only if the use-env-file is provided. The default is /etc/stork/agent.env.

--use-env-file

Instructs stork-agent to read the environment variables from the environment file. The default is false.

-v|--version

Returns the software version.

-h|--help

Returns the list of available parameters.

Stork server flags:

--server-url=

Specifies the URL of the Stork server receiving the registration request. Optional; can be skipped to suppress automatic registration. [$STORK_AGENT_SERVER_URL]

--host=

Specifies the IP address or hostname to listen on for incoming Stork server connections. [$STORK_AGENT_HOST]

--port=

Specifies the TCP port to listen on for incoming Stork server connections. The default is 8080. [$STORK_AGENT_PORT]

--skip-tls-cert-verification=

Indicates that TLS certificate verification should be skipped when the Stork agent makes HTTP calls over TLS. The default is false. [$STORK_AGENT_SKIP_TLS_CERT_VERIFICATION]

Prometheus Kea Exporter flags:

--prometheus-kea-exporter-address=

Specifies the IP address or hostname on which the Stork agent exports Kea statistics to Prometheus. The default is 0.0.0.0. [$STORK_AGENT_PROMETHEUS_KEA_EXPORTER_ADDRESS]

--prometheus-kea-exporter-port=

Specifies the port on which the Stork agent exports Kea statistics to Prometheus. The default is 9547. [$STORK_AGENT_PROMETHEUS_KEA_EXPORTER_PORT]

--prometheus-kea-exporter-interval=

Specifies how often the Stork agent collects statistics from Kea, in seconds. The default is 10. [$STORK_AGENT_PROMETHEUS_KEA_EXPORTER_INTERVAL]

--prometheus-kea-exporter-per-subnet-stats=

Enables or disables collecting per-subnet stats from Kea. The default is true. [$STORK_AGENT_PROMETHEUS_KEA_EXPORTER_PER_SUBNET_STATS]

Prometheus BIND 9 Exporter flags:

--prometheus-bind9-exporter-address=

Specifies the IP address or hostname on which the Stork agent exports BIND 9 statistics to Prometheus. The default is 0.0.0.0. [$STORK_AGENT_PROMETHEUS_BIND9_EXPORTER_ADDRESS]

--prometheus-bind9-exporter-port=

Specifies the port on which the Stork agent exports BIND 9 statistics to Prometheus. The default is 9119. [$STORK_AGENT_PROMETHEUS_BIND9_EXPORTER_PORT]

Stork logs at INFO level by default. Other levels can be configured using the STORK_LOG_LEVEL variable. Allowed values are: DEBUG, INFO, WARN, ERROR.

To control the logging colorization, Stork supports the CLICOLOR and CLICOLOR_FORCE standard UNIX environment variables. Use CLICOLOR_FORCE to enforce enabling or disabling ANSI colors usage. Set CLICOLOR to 0 or false to disable colorization even if the TTY is attached.

Stork evaluates and prioritizes the settings it receives based on where they are applied. Command-line flags have the highest priority; next are parameters from the environment file, if the --use-env-file flag is used. The lowest priority is given to environment variables.

Examples

To start the Stork agent and register it automatically with the Stork server, run the following command:

$ stork-agent --server-url=http://stork-server.example.com:8080 --host=stork-agent.example.com --port=8080

If the Stork agent is already registered with the Stork server, it can be started with this command:

$ stork-agent --host=stork-agent.example.com --port=8080

By default, the Stork agent receives server requests and exports metrics to Prometheus. To only listen to the Stork server, run the following command:

$ stork-agent (...) --listen-stork-only

To only listen to Prometheus requests, run the following command:

$ stork-agent (...) --listen-prometheus-only

If performance issues are observed with exporting Kea statistics to Prometheus, the interval between statistics collection can be increased, or collection of per-subnet stats can be disabled. For example:

$ stork-agent (...) --prometheus-kea-exporter-interval=30 --prometheus-kea-exporter-per-subnet-stats=false

By default, the Stork agent reads arguments only from the command line. To read arguments from the environment file, run the following command:

$ stork-agent --use-env-file

The default environment file location is /etc/stork/agent.env. To specify a different location, run the following command:

$ stork-agent --use-env-file --env-file=/path/to/agent.env

Registration

The register command runs the agent registration using a specified server token and exits. After successful registration, run the agent normally. The register command takes the following arguments:

-u|--server-url=

Specifies the URL of the Stork server receiving the registration request. [$STORK_AGENT_SERVER_URL]

-t|--server-token=

Specifies the access token used by the Stork server to allow registration of the Stork agents. [$STORK_AGENT_SERVER_TOKEN]

-a|--agent-host=

Specifies an IP address or DNS name of the host where the agent is running, e.g. localhost or 10.11.12.13. [$STORK_AGENT_HOST]

-p|--agent-port=

Specifies the port on which the agent listens for incoming connections. The default is 8080. [$STORK_AGENT_PORT]

-n|--non-interactive

Disables the interactive mode. The default is false. [$STORK_AGENT_NON_INTERACTIVE]

To register the Stork agent in interactive mode, run the following command:

$ stork-agent register
>>> Enter the URL of the Stork server:
>>> Enter the Stork server access token (optional):
>>> Enter IP address or FQDN of the host with Stork agent (for the Stork server connection) [hostname]:
>>> Enter port number that Stork Agent will listen on [8080]:

To register the Stork agent with the server token, providing all the necessary information through CLI arguments, run the following command:

$ stork-agent register --server-url=http://stork-server.example.com:8080 --server-token=1234567890 --agent-host=stork-agent.example.com --agent-port=8080

To register the Stork agent without the server token, using the environment variables, run the following commands:

$ export STORK_AGENT_SERVER_URL=http://stork-server.example.com:8080
$ export STORK_AGENT_HOST=stork-agent.example.com
$ export STORK_AGENT_PORT=8080
$ stork-agent register

Mailing Lists and Support

There are public mailing lists available for the Stork project. stork-users (stork-users at lists.isc.org) is intended for Stork users. stork-dev (stork-dev at lists.isc.org) is intended for Stork developers, prospective contributors, and other advanced users. The lists are available at https://www.isc.org/mailinglists. The community provides best-effort support on both of those lists.

History

stork-agent was first coded in November 2019 by Michal Nowikowski.

See Also

stork-server(8)