stork-tool - A tool for managing Stork Server

Synopsis

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

Description

The stork-tool operates in two areas:

  • Certificates Management - it allows for exporting Stork Server keys, certificates and token that are used for securing communication between Stork Server and Stork Agents

  • Database Migration - it allows for performing database schema migrations, overwriting db schema version and getting its current value; usually, there is no need to use this area, as the Stork Server always runs the migration scripts on startup

Certificates Management

stork-tool offers the following commands:

  • cert-export Export certificate or other secret data

Options specific to cert-export command:

-f, --object=

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

-o, --file=

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

Examples

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

Export 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 Import certificate or other secret data

Options specific to cert-import command:

-f, --object=

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

-i, --file=

the file location from which the object will be loaded. [$STORK_TOOL_CERT_FILE]

Examples

Read 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

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

stork-tool offers the following commands:

  • db-init Create schema versioning table in the database

  • db-up Run all available migrations (or use -t to migrate to a specific version)

  • db-down Revert last migration (or use -t to migrate to a specific version)

  • db-reset Revert all migrations

  • db-version Print current migration version

  • db-set-version Set database version without running migrations

Options specific to db-up, db-down and db-set-version commands:

-t, --version=

target database schema version. (default: stork) [$STORK_TOOL_DB_VERSION]

Examples

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

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

Options common for db-* and cert-* commands:

--db-url=

the URL to locate Stork PostgreSQL database. [$STORK_DATABASE_URL]

-u, --db-user=

the user name to be used for database connections. (default: stork) [$STORK_DATABASE_USER_NAME]

--db-password=

the database password to be used for database connections. [$STORK_DATABASE_PASSWORD]

--db-host=

the name of the host where the database is available. (default: localhost) [$STORK_DATABASE_HOST]

-p, --db-port=

the port on which the database is available. (default: 5432) [$STORK_DATABASE_PORT]

-d, --db-name=

the name of the database to connect to. (default: stork) [$STORK_DATABASE_NAME]

--db-sslmode

the SSL mode for connecting to the database (i.e., disable, require, verify-ca or verify-full). (default: disable) [$STORK_DATABASE_SSLMODE]

--db-sslcert

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

--db-sslkey

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

--db-sslrootcert

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

--db-trace-queries=

enable tracing SQL queries: “run” - only runtime, without migrations, “all” - migrations and run-time. [$STORK_DATABASE_TRACE_QUERIES]

-h, --help

show help message

The --db-sslmode argument can have one of the following values:

disable

disable encryption between the Stork Server and the PostgreSQL database.

require

use secure communication but do 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 case of verify-ca mode.

verify-ca

use secure communication and verify the server’s identity by checking it against the root certificate stored on the Stork Server machine.

verify-full

use secure communication, verify the server’s identity against the root certificate. In addition, check that the server hostname matches the name stored in the certificate.

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.

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://lists.isc.org. The community provides best-effort support on both of those lists.

History

The stork-tool tool was first coded in October 2019 by Marcin Siodelski. That time it was called stork-db-migrate. In 2021 it was refactored to stork-tool and commands for Certificates Management were added by Michal Nowikowski.

See Also

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