stork-tool - A Tool for Managing Stork Server

Synopsis

stork-tool [global options] command [command options]

Description

stork-tool provides three features:

  • Certificate management - it allows the Stork server to export keys, certificates and tokens that are used to secure communication between Stork server and Stork agents.

  • Database Creation - it facilitates creating a new database for the Stork Server, and a user that can access this database with a generated password

  • Database migration - it allows database schema migrations to be performed, overwriting the database schema version and getting its current value. There is normally no need to use this, as the Stork server always runs the migration scripts on startup.

Certificate Management

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

  • cert-export Exports a certificate or other secret data. The options are:

    -f|--object=

    Specifies the object to dump, which can be one of cakey, cacert, srvkey, srvcert, or srvtkn. [$STORK_TOOL_CERT_OBJECT]

    -o|--file=

    Specifies the location of the file where the object should be saved. [$STORK_TOOL_CERT_FILE]

    To print the Certificate Authority key in the console:

    $ stork-tool cert-export --db-url postgresql://user:pass@localhost/dbname -f cakey
INFO[2021-05-25 12:36:07]       connection.go:59    checking connection to database
INFO[2021-05-25 12:36:07]            certs.go:225   CA key:
-----BEGIN PRIVATE KEY-----
MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQghrTv9SVZ/hv0xSM+
jvUk+VehIcf1tD/yMfAF4IiVXaahRANCAATgene6dVwo1xCmYjMKYxSrxgOWRm2G
R5X1x72axq2cAhCFm7EpD88oYZ3EBdoXmG9fihV5ZGtfFkSpIdzCNPQI
-----END PRIVATE KEY-----

    To export the server certificate to a file:

    $ stork-tool cert-export --db-url postgresql://user:pass@localhost/dbname -f srvcert -o srv-cert.pem
INFO[2021-05-25 12:36:46]       connection.go:59    checking connection to database
INFO[2021-05-25 12:36:46]            certs.go:221   server cert saved to file: srv-cert.pem

  • cert-import Imports a certificate or other secret data. The options are:

    -f|--object=

    Specifies the object to dump, which can be one of cakey, cacert, srvkey, srvcert, or srvtkn. [$STORK_TOOL_CERT_OBJECT]

    -i, --file= Specifies the location of the file from which the object is loaded. [$STORK_TOOL_CERT_FILE]

    To read the server token from stdin:

    $ echo abc | stork-tool cert-import --db-url postgresql://user:pass@localhost/dbname -f srvtkn
INFO[2021-08-11 13:31:55]       connection.go:59    checking connection to database
INFO[2021-08-11 13:31:55]            certs.go:259   reading server token from stdin
INFO[2021-08-11 13:31:55]            certs.go:261   server token read from stdin, length 4

    To import the server certificate from a file:

    $ stork-tool cert-import --db-url postgresql://user:pass@localhost/dbname -f srvcert -i srv.cert
INFO[2021-08-11 15:22:28]       connection.go:59    checking connection to database
INFO[2021-08-11 15:22:28]            certs.go:257   server cert loaded from srv.cert file, length 14

Database Creation

stork-tool offers the following commands for creating the database for the Stork Server:

  • db-create Create new database

  • db-password-gen Generate random database password

Options specific to db-create command:

-m, --db-maintenance-name

Existing maintenance database name. The default is “postgres”. [$STORK_DATABASE_MAINTENANCE_NAME]

-a, --db-maintenance-user

Database administrator user name. The default is “postgres”. [$STORK_DATABASE_MAINTENANCE_USER_NAME]

--db-maintenance-password

Database administrator password; if not specified, the user will be prompted for the password if necessary. [$STORK_DATABASE_MAINTENANCE_PASSWORD]

-f, --force

Recreate the database and the user if they exist. The default is false.

Examples

Create a new database stork with user stork and a generated password:

$ stork-tool db-create --db-maintenance-user postgres --db-name stork --db-user stork
INFO[2022-01-25 17:04:56]             main.go:145   created database and user for the server with the following credentials  database_name=stork password=L82B+kJEOyhDoMnZf9qPAGyKjH5Qo/Xb user=stork

When a database is created using psql tool, it is sometimes useful to generate a hard-to-guess password for this database:

$ stork-tool db-password-gen
INFO[2022-01-25 17:56:31]             main.go:157   generated new database password               password=znYDfWzvMhWRZyJJuu3EvUxH5KMi1SmJ

Database Migration

stork-tool offers the following commands:

  • db-init Creates a schema versioning table in the database.

  • db-up Runs all available migrations; use -t to migrate to a specific version.

  • db-down Reverts the last migration; use -t to migrate to a specific version.

  • db-reset Reverts all migrations.

  • db-version Prints the current migration version.

  • db-set-version Sets the database version without running migrations.

    The following option is specific to the db-up, db-down, and db-set-version commands:

    -t|--version=

    Specifies the target database schema version. The default is stork. [$STORK_TOOL_DB_VERSION]

To initialize a database schema:

$ STORK_DATABASE_PASSWORD=pass stork-tool db-init -u user -d dbname
INFO[2021-05-25 12:30:53]       connection.go:59    checking connection to database
INFO[2021-05-25 12:30:53]             main.go:100   Database version is 0 (new version 33 available)

To overwrite the current schema version to an arbitrary value:

$ STORK_DATABASE_PASSWORD=pass stork-tool db-set-version -u user -d dbname -t 42
INFO[2021-05-25 12:31:30]             main.go:77    Requested setting version to 42
INFO[2021-05-25 12:31:30]       connection.go:59    checking connection to database
INFO[2021-05-25 12:31:30]             main.go:94    Migrated database from version 0 to 42

Common Options

The following options pertain to both db- and cert- commands:

--db-url=

Specifies the URL for the Stork PostgreSQL database. It’s mutually exclusive with the host, port, username, and password. [$STORK_DATABASE_URL]

-u|--db-user=

Specifies the user name 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 will be prompted for the password if necessary. [$STORK_DATABASE_PASSWORD]

--db-host=

Specifies the name of the host, IP address or a 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 - disable the query logging. [$STORK_DATABASE_TRACE_QUERIES]

-h|--help

Shows a help message.

Note that there is no argument for the database password, as the command-line arguments can sometimes be seen by other users. It can be passed 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 the ANSI colors usage. Set CLICOLOR to 0 or false to disable colorization even if the TTY is attached.

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-tool was first coded in October 2019 by Marcin Siodelski; at that time it was called stork-db-migrate. In 2021, it was refactored as stork-tool and commands for Certificate Management were added by Michal Nowikowski.

See Also

stork-agent(8), stork-server(8)