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=] [-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.

Startup 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. It can be an absolute path or a path relative to the stork-agent executable directory. The default is ../lib/stork-agent/hooks, which typically resolves to /usr/lib/stork-agent/hooks. [$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_CONFIG]

Common locations where the agent is trying to find the BIND 9 configuration file are:

• /etc/bind/named.conf

• /etc/opt/isc/isc-bind/named.conf

• /etc/opt/isc/scls/isc-bind/named.conf

• /usr/local/etc/namedb/named.conf

--powerdns-path

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

Common locations where the agent is trying to find the PowerDNS configuration file are:

• /etc/powerdns/pdns.conf

• /etc/pdns/pdns.conf

• /usr/local/etc/pdns.conf

• /opt/homebrew/etc/powerdns/pdns.conf

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

Communication with the Stork Server

The following flags control the communication between the Stork agent and the Stork server.

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

The following flags control the Prometheus Kea exporter functionality.

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

The following flags control the Prometheus BIND 9 exporter functionality.

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

Zone Transfer Tracking (only for BIND 9)

The following flags control the zone transfer tracking functionality. It is disabled by default. When enabled (using the --enable-xfr-tracking flag), the agent will read and follow the log files or systemd logs deemed to contain the zone transfer events. Stork agent cannot track zone transfers if they are only logged to the syslog.

If the zone transfer tracking is enabled, and no other flags listed below are specified, the agent will try to determine the locations of the appropriate log files from the BIND 9 logging configuration. It will look for the log files containing the logs of the xfer-in and xfer-out categories.

In some cases, the administrator may wish to explicitly specify the log files locations. Specifically, when BIND 9 daemon runs in foreground and redirects output to an arbitrary file. In such cases, the administrator can use the --xfr-in-tracking-path and --xfr-out-tracking-path flags to specify the locations of the log files containing the incoming and outgoing zone transfer requests respectively. These flags override the locations detected from the BIND 9 logging configuration.

In order to track zone transfers in the systemd logs, the administrator must specify the --xfr-tracking-systemd-unit. This flag is mutually exclusive with the --xfr-in-tracking-path and --xfr-out-tracking-path options. If any of the latter is specified, the --xfr-tracking-systemd-unit is ignored.

The following flags control the zone transfer tracking functionality.

--enable-xfr-tracking

Enables the agent to track zone transfers initiated by BIND 9. The default is false. [$STORK_AGENT_ENABLE_XFR_TRACKING]

--xfr-in-tracking-path=

Specifies the path to the log file containing incoming zone transfer requests. This option is mutually exclusive with the xfr-tracking-systemd-unit option. If both are specified, the xfr-in-tracking-path option takes precedence. The default is empty in which case incoming zone transfer requests are not tracked in the log files. [$STORK_AGENT_XFR_IN_TRACKING_PATH]

--xfr-out-tracking-path=

Specifies the path to the log file containing outgoing zone transfer requests. This option is mutually exclusive with the xfr-tracking-systemd-unit option. If both are specified, the xfr-out-tracking-path option takes precedence. The default is empty in which case outgoing zone transfer requests are not tracked in the log files. [$STORK_AGENT_XFR_OUT_TRACKING_PATH]

--xfr-tracking-systemd-unit=

Specifies the systemd unit name for which zone transfers are logged. This option is mutually exclusive with the xfr-in-tracking-path and xfr-out-tracking-path options which take precedence over this option. The default is empty in which case zone transfer requests in systemd logs are not tracked. [$STORK_AGENT_XFR_TRACKING_SYSTEMD_UNIT]

Logging

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 collection of per-subnet stats can be disabled. For example:

$ stork-agent (...) --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)