Stork Tool

From: https://stork.readthedocs.io/en/v1.11.0/man/stork-tool.8.html#man -stork-tool

Intro	Synopsis	Description	Cert Mgmt
Examples	DB Migration	Common Options	Mailing Lists and Support
History	See Also


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 postgres
ql://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_DATA
BASE_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)