How can you have multiple step configurations on a single machine?

By default, the step toolchain assumes a single CA is in use, and it will store client configuration, CA configuration, and state directories (config, certs, secrets, db, etc.) inside a single folder, $HOME/.step.

If you regularly work with multiple CAs, we recommend enabling contexts.

Contexts let you configure and select multiple CAs and configuration profiles. If this optional feature is enabled, the $HOME/.step folder will have a different layout.

Every context consists of a client configuration profile (including [defaults.json](<>)), and a directory tree for CA configuration and state data (ca.json, CA roots, certificates, secrets, templates, db).

To enable contexts, pass the --context flag to any of the step setup commands, along with a label for your new context:

step ca bootstrap \\
       --ca-url <https://ca.internal:4443> \\
       --fingerprint c8d3...7aa \\
       --context vpn

The root certificate has been saved in /home/carl/.step/authorities/ca.internal/certs/root_ca.crt.
The authority configuration has been saved in /home/carl/.step/authorities/ca.internal/config/defaults.json.
The profile configuration has been saved in /home/carl/.step/profiles/ca.internal/config/defaults.json.

step context current



Contexts are enabled, and a new context is created, if --context [name] is passed to any of the following:

  • CA client bootstrap: step ca bootstrap
  • CA server init: step ca init
  • SSH client bootstrap: step ssh config

When contexts are enabled:

  • Client configuration is stored in the profiles directory, and CA server configuration and data is stored in authorities directory.
  • Context configuration files contexts.json and current-context.json are created in the top-level $STEPPATH.
  • There is always a currently active context (step context current), but you can pass a --context name to any step ca or step ssh command to temporarily select a context for a single operation.
  • Use the step context command group to switch contexts, remove a context and its associated configuration, and view the current context.
  • The step path command will show the current context's path. To display the top-level configuration directory name ($STEPPATH) when contexts are enabled, use step path --base.
  • Two defaults.json files are created: One in the profiles tree, and one in the authorities tree. They are merged, and the one in profiles takes precedence.
  • Context configuration files contexts.json and current-context.json are created in the top-level $STEPPATH.

Migrating to Contexts

There is no support for automatically migrating a single-profile $STEPPATH configuration into its own context. Enabling contexts will preserve any previously existing configuration or state data in $STEPPATH, but it will not migrate your existing configuration tree into its own new context.