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
, orsrvtkn
.[$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
, orsrvtkn
.[$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 databasedb-password-gen
Generate random database password
Options specific to db-create
command:
-m
,--db-maintenance-name
existing maintenance database name. (default: “postgres”) [$STORK_DATABASE_MAINTENANCE_NAME]
-a
,--db-maintenance-user
database administrator user name. (default: “postgres”) [$STORK_DATABASE_MAINTENANCE_USER_NAME]
--db-maintenance-password
database administrator password; if not specified, the user will be prompted for the password.
-f
,--force
recreate the database and the user if they exist. (default 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
, anddb-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.
[$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.
[$STORK_DATABASE_PASSWORD]
--db-host=
Specifies the name of the host where the database is available. The default is
localhost
.[$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
, orverify-full
. The default isdisable
.[$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 ofverify-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, orall
- both migrations and runtime.[$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.
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)