Docker Operations

The keymanager script can assist you in performing a multitude of other operations. See keymanager help or .\keymanager.ps1 -Command help. The options include operations for updating the app, checking status and health, perform TLS certificate rotation, onboarding TSB instances and uninstalling the app.

tip

The keymanager sample commands bellow are always shown for a Linux installation. When running on Windows, substitute the commands with .\keymanager.ps1 -Command and the same operations.

Status

Below is a list of commands you can use to check on the status of your instance:

keymanager status
docker compose ps
curl -k https://localhost:8443

Running the status command will produce an output similar to this:

Securosys Key Manager - Service Status
========================================================
NAME              IMAGE                                         COMMAND                    SERVICE     CREATED          STATUS                    PORTS
kms-auth-1        securosys.jfrog.io/kms/kms/auth:latest        "/app/auth"                auth        37 minutes ago   Up 37 minutes (healthy)   8001/tcp
kms-dashboard-1   securosys.jfrog.io/kms/kms/dashboard:latest   "/usr/local/bin/dash"      dashboard   37 minutes ago   Up 37 minutes             0.0.0.0:5173->80/tcp, [::]:5173->80/tcp
kms-envoy-1       securosys.jfrog.io/kms/kms/envoy:latest       "/docker-entrypoint"       envoy       37 minutes ago   Up 37 minutes             0.0.0.0:8080->8080/tcp, [::]:8080->8080/tcp, 0.0.0.0:8443->8443/tcp, [::]:8443->8443/tcp
kms-keycore-1     securosys.jfrog.io/kms/kms/keycore:latest     "/app/keycore"             keycore     37 minutes ago   Up 37 minutes (healthy)   8010/tcp

Health Checks:
  Auth        healthy
  Keycore     healthy
  Dashboard   healthy

The curl command returns a response that the instance is up and running.

Logs

You may be interested in manually reviewing the health and behaviour of some of the containers. Sample commands for a few of the containers are listed here:

keymanager logs                     # all containers are streamed at once
docker compose logs -f              # all containers are streamed at once
docker compose logs -f auth         # check authentication requests and activity
docker compose logs -f tsb-rest-api # follow the TSB connections to your HSM Partition

Manage Containers

keymanager restart
docker compose restart          # or 'docker compose down' > 'docker compose up'
docker compose restart auth     # restarting `auth` seals the KMS again. Unseal via `/unseal`.
docker compose restart envoy

Update and Upgrade

Using the keymanager, you can fetch the latest version of the configuration scripts or update to the latest version of the KMS itself.

# check for update of the keymanager script
keymanager update

# check for upgrades of the Docker containers, pull latest version and restart the environment
keymanager upgrade

If the upgrade operations pulls newer versions and restarts your instance, you need to do the following:

1. Check container status
2. Unseal the KMS
3. Verify the gateway and key workflows

Remove

If you would like to remove the instance from the local environment or would like a fresh start, run:

keymanager uninstall

info

The KMS UI can always be uninstalled, as the app is stateless, however this will introduce additional work. We recommend uninstalling with caution. If the underlying keys are deleted (via a user or API), the instance will need to be reinstalled.