.. Copyright (C) 2019-2026 Internet Systems Consortium, Inc. ("ISC") This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. See the COPYRIGHT file distributed with this work for additional information regarding copyright ownership. .. _man-stork-agent: ``stork-agent`` - The Stork Agent to Monitor BIND 9 and Kea Services -------------------------------------------------------------------- Synopsis ~~~~~~~~ :program:`stork-agent` [**--listen-stork-only**] [**--listen-prometheus-only**] [**-v**] [**--host=**] [**--port=**] [**--skip-tls-cert-verification=**] [**--prometheus-kea-exporter-address=**] [**--prometheus-kea-exporter-port=**] [**-h**] :program:`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: .. code-block:: bash $ 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: .. code-block:: bash $ 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: .. code-block:: bash $ stork-agent (...) --listen-stork-only To only listen to Prometheus requests, run the following command: .. code-block:: bash $ 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: .. code-block:: bash $ 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: .. code-block:: bash $ stork-agent --use-env-file The default environment file location is ``/etc/stork/agent.env``. To specify a different location, run the following command: .. code-block:: bash $ 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: .. code-block:: bash $ 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: .. code-block:: bash $ 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: .. code-block:: bash $ 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 ~~~~~~~~ :manpage:`stork-server(8)`