stork-server - The Main Stork Server

Synopsis

stork-server [-h] [-v] [-m] [-u] [–dbhost] [-p] [-d] [–db-sslmode] [–db-sslcert] [–db-sslkey] [–db-sslrootcert] [–db-trace-queries=] [–rest-cleanup-timeout] [–rest-graceful-timeout] [–rest-max-header-size] [–rest-max-body-size] [–rest-host] [–rest-port] [–rest-listen-limit] [–rest-keep-alive] [–rest-read-timeout] [–rest-write-timeout] [–rest-tls-certificate] [–rest-tls-key] [–rest-tls-ca] [–rest-static-files-dir] [–rest-base-url] [–rest-versions-url]

Description

stork-server provides the main Stork server capabilities. In every Stork deployment, there should be exactly one Stork server.

Arguments

The Stork server’s behavior is controlled with command-line switches and/or environment variables. The environment variables can be set before running the server, or they can be loaded from a file using the --use-env-file and --env-file flags. Note that some parts of the server configuration can only be controlled from the web UI, after the server has been started.

stork-server takes the following arguments (equivalent environment variables are listed in square brackets, where applicable):

-h|--help

Returns the list of available parameters.

-v|--version

Returns the stork-server version.

--hook-directory

The path to the hook directory. [$STORK_SERVER_HOOK_DIRECTORY]

--env-file

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

--use-env-file

Reads the environment variables from the environment file. The default is false.

-m|--metrics

Enables the periodic metrics collector and /metrics HTTP endpoint for Prometheus. This endpoint requires no authentication; it is recommended to restrict external access to it (e.g. using the HTTP proxy). It is disabled by default. [$STORK_SERVER_ENABLE_METRICS]

--initial-puller-interval

The default interval used by pullers fetching data from Kea; if not provided, the recommended values for each puller are used. [$STORK_SERVER_INITIAL_PULLER_INTERVAL]

-u|--db-user

Specifies the user name to be used for database connections. The default is stork. [$STORK_DATABASE_USER_NAME]

--db-password=

Specifies the database password for database connections. If not specified, the user is prompted for the password if necessary. [$STORK_DATABASE_PASSWORD]

--db-url

Specifies the URL to locate and connect to a database; mutually exclusive with the host, port, username, and password. [$STORK_DATABASE_URL]

--db-host

Specifies the name of the host, IP address, or socket path for the database connection. The default value depends on the system. [$STORK_DATABASE_HOST]

-p|--db-port

Specifies the port on which the database is available. The default is 5432. [$STORK_DATABASE_PORT]

-d|--db-name=

Specifies the name of the database to connect to. The default is stork. [$STORK_DATABASE_NAME]

--db-sslmode

Specifies the SSL mode for connecting to the database; possible values are disable, require, verify-ca, or verify-full. The default is disable. [$STORK_DATABASE_SSLMODE] Acceptable values are:

disable Disables encryption between the Stork server and the PostgreSQL database.

require Uses secure communication but does not verify the server’s identity, unless the root certificate location is specified and that certificate exists. If the root certificate exists, the behavior is the same as in the case of verify-ca.

verify-ca Uses secure communication and verifies the server’s identity by checking it against the root certificate stored on the Stork server machine.

verify-full Uses secure communication and verifies the server’s identity against the root certificate. In addition, checks that the server hostname matches the name stored in the certificate.

--db-sslcert

Specifies the location of the SSL certificate used by the server to connect to the database. [$STORK_DATABASE_SSLCERT]

--db-sslkey

Specifies the location of the SSL key used by the server to connect to the database. [$STORK_DATABASE_SSLKEY]

--db-sslrootcert

Specifies the location of the root certificate file used to verify the database server’s certificate. [$STORK_DATABASE_SSLROOTCERT]

--db-trace-queries=

Enables tracing of SQL queries. Possible values are run - only runtime, without migrations, all - both migrations and runtime, or none - disables the query logging. [$STORK_DATABASE_TRACE]

--db-read-timeout

The timeout for socket reads; if reached, commands fail instead of blocking. Zero disables the timeout. Requires a unit: either ms (milliseconds), s (seconds), or m (minutes), e.g.: 42s. The default is 0. [$STORK_DATABASE_READ_TIMEOUT]

--db-write-timeout

The timeout for socket writes; if reached, commands fail instead of blocking. Zero disables the timeout Requires a unit: either ms (milliseconds), s (seconds), or m (minutes), e.g.: 42s. The default is 0. [$STORK_DATABASE_WRITE_TIMEOUT]

--rest-cleanup-timeout

Specifies the period, in seconds, to wait before killing idle connections. The default is 10. [$STORK_REST_CLEANUP_TIMEOUT]

--rest-graceful-timeout

Specifies the period, in seconds, to wait before shutting down the server. The default is 15. [$STORK_REST_GRACEFUL_TIMEOUT]

--rest-max-header-size

Specifies the maximum number of bytes the server reads when parsing the request header’s keys and values, including the request line. It does not limit the size of the request body. The default is 1024 (1MB). [$STORK_REST_MAX_HEADER_SIZE]

--rest-max-body-size

Specifies the maximum number of bytes the server accepts when parsing the request body. HTTP 413 is returned if the body exceeds the limit. It does not limit the size of the request header. The default is 10MB. Set to zero to disable the limit. [$STORK_REST_MAX_BODY_SIZE]

--rest-host

Specifies the IP address to listen on for connections over the RESTful API. [$STORK_REST_HOST]

--rest-port

Specifies the port to listen on for connections over the RESTful API. The default is 8080. [$STORK_REST_PORT]

--rest-listen-limit

Specifies the maximum number of outstanding requests. [$STORK_REST_LISTEN_LIMIT]

--rest-keep-alive

Specifies the TCP keep-alive timeout, in minutes, on accepted connections. After this period, the server prunes dead TCP connections (e.g. if a laptop is closed mid-download). The default is 3.

--rest-read-timeout

Specifies the maximum duration, in seconds, before timing out the read of a request. The default is 30. [$STORK_REST_READ_TIMEOUT]

--rest-write-timeout

Specifies the maximum duration, in seconds, before timing out the write of a response. The default is 60. [$STORK_REST_WRITE_TIMEOUT]

--rest-tls-certificate

Specifies the certificate to use for secure connections. [$STORK_REST_TLS_CERTIFICATE]

--rest-tls-key

Specifies the private key to use for secure connections. [$STORK_REST_TLS_PRIVATE_KEY]

--rest-tls-ca

Specifies the Certificate Authority file to be used with a mutual TLS authority. [$STORK_REST_TLS_CA_CERTIFICATE]

--rest-static-files-dir

Specifies the directory with static files for the UI. [$STORK_REST_STATIC_FILES_DIR]

--rest-base-url

The base URL of the UI. This flag should be set if the UI is served from a subdirectory instead of the root URL. It must start and end with a slash. For example: https://www.example.com/admin/stork/ would need to have /admin/stork/ as the base url. The default is /. [$STORK_REST_BASE_URL]

--rest-versions-url

Specifies the URL of the file with current Kea, Stork and BIND 9 software versions metadata. By default, it is https://www.isc.org/versions.json. [$STORK_REST_VERSIONS_URL]

Note that there is no argument for the database password, as command-line arguments can sometimes be seen by other users. The password can be set using the STORK_DATABASE_PASSWORD variable.

Stork logs on 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 server with the local PostgreSQL database, run the following command:

$ stork-server

Custom database connection options can also be specified, e.g. host, port, and user:

$ stork-server --db-host=localhost --db-port=5432 --db-user=stork

The host may be a socket path. The default value works on most systems, but it may need to be explicitly specified if a non-standard PostgreSQL distribution is being used. For example, on a macOS system it may be necessary to run:

$ stork-server --db-host=/tmp

To listen on a non-default port and host, run the following command:

$ stork-server (...) --rest-host=hostname --rest-port=80

The REST API can be secured with TLS. To enable it, provide the certificate and key:

$ stork-server (...) --rest-tls-certificate=/path/to/cert.pem --rest-tls-ca=/path/to/ca.pem --rest-tls-key=/path/to/key.pem

To enable the server’s /metrics HTTP endpoint for Prometheus, run the following command:

$ stork-server (...) --metrics

The Stork server can be served from a subdirectory. For example, to run it from the http://example.com/stork/ URL, use the following command:

$ stork-server (...) --rest-base-url=/stork/

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

$ stork-server --use-env-file

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

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

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-server was first coded in November 2019 by Michal Nowikowski and Marcin Siodelski.

See Also

stork-agent(8)