This topic describes how you can set up and use CredHub Maestro, a command-line interface (CLI) that rotates certificates in CredHub.

Using CredHub Maestro, you can:

  • Determine if any of your CredHub certificates are expiring soon.

  • Rotate CredHub certificates.

  • Clean up inactive certificate versions so that CredHub does not run out of disk space.

Set up environment variables

This section describes setting up the environment variables you need to use CredHub Maestro.

Required environment variables

To set the CredHub environment variables you need for CredHub Maestro, follow the guidance in the following table:

To set BOSH environment variables, see Advanced troubleshooting with the BOSH CLI.

Environment Variable Description
BOSH_ENVIRONMENT BOSH Director URL or IP address
BOSH_CLIENT Name of BOSH client
BOSH_CLIENT_SECRET BOSH client secret
BOSH_CA_CERT Path or value of BOSH Director trusted certificate authority (CA)
CREDHUB_SERVER URL of BOSH Director CredHub server. This must be BOSH_ENVIRONMENT:8844.
CREDHUB_CLIENT Name of CredHub client. This is the same as BOSH_CLIENT.
CREDHUB_SECRET CredHub client secret. This is the same as BOSH_CLIENT_SECRET.
CREDHUB_CA_CERT Path or value of CredHub trusted CA certificate. This is the same as BOSH_CA_CERT.

Using CredHub Maestro from outside your foundation

To use CredHub Maestro from outside your foundation, you must also set the following variables in addition to the required environment variables:

Environment Variable Description
BOSH_ALL_PROXY SOCKS5 proxy address of BOSH Director jumpbox
CREDHUB_PROXY SOCKS5 proxy address of CredHub jumpbox

Optional environment variables

You can also set the following optional environment variables:

Environment Variable Description
MAESTRO_DEBUG Enable debug logging
MAESTRO_OUTPUT_JSON Print all CredHub Maestro command output as JSON

Commands

This section describes the commands you can use in CredHub Maestro.

To review a list of commands in CredHub Maestro, run maestro --help.

maestro list

maestro list displays expiry information for all actively-deployed certificates in CredHub.

You can use the following flags with maestro list:

  • expires-within: Filter certificates by expiry window. Valid units are d for days, w for weeks, m for months, and y for years.

  • deployment-name: Filter certificates by deployment name.

  • name: Show metadata for a single certificate.

  • include-all: Include inactive certificates in response.

  • ca-only: Filter certificates to include only CAs.

  • leaf-only: Filter to include only leaf certificates.

  • generated-only: Include only certificates that have been generated by CredHub.

The deployment-name and include-all flags are mutually exclusive.

maestro topology

maestro topology displays expiry information for all actively-deployed certificates in CredHub.

You can use the following flags with maestro topology:

  • name: Display topology for a single certificate.

  • include-all: Display topology for both active and inactive certificates.

maestro regenerate

maestro regenerate regenerates CredHub-generated certificates. By default, certificates that have been manually-set in CredHub are not regenerated.

maestro regenerate ca

maestro regenerate ca regenerates actively-deployed CAs and adds transitional flags to these new CA versions. The transitional status indicates that these new CA versions will not yet sign any leaf certificates, though they will be trusted by clients.

You can use the following flags with maestro regenerate ca:

  • all: Regenerate all actively-deployed CAs.

  • name: Regenerate a single CA by name.

  • dry-run: List CAs to be regenerated.

  • exclude: Comma-separated list of CAs to exclude from being regenerated. This includes all leaf certificates of excluded CAs.

  • force: Regenerate both CredHub-generated and manually-set CAs.

  • show-excluded: Show all certificates excluded from regeneration.

maestro regenerate leaf

maestro regenerate leaf regenerates actively-deployed leaf certificates.

You can use the following flags with maestro regenerate leaf:

  • all: Regenerate all actively-deployed leaf certificates.

  • name: Regenerate single leaf by name.

  • signed-by: Regenerate all actively-deployed leaf certificates signed by a specific CA.

  • dry-run: List leaf certificates to be regenerated.

  • exclude-signed-by: Exclude all leaf certificates signed by a list of CAs from being regenerated.

  • force: Regenerate both CredHub-generated and manually-set leaf certificates.

  • show-excluded: Show all certificates excluded from regeneration.

maestro update-transitional

maestro update-transitional updates the transitional flag for CAs.

maestro update-transitional signing

maestro update-transitional signing updates the transitional flag for the version of the actively-deployed CA that signed deployed leaf certificates.

You can use the following flags with maestro update-transitional signing:

  • all: Update the transitional flag for all actively-deployed CAs.

  • name: Update the transitional flag for a single CA.

  • dry-run: List CAs to be updated.

  • exclude: Exclude a list of CAs and their leaf certificates from being updated.

  • show-excluded: Show all certificates excluded from update.

maestro update-transitional remove

maestro update-transitional remove removes the transitional flag for all versions of the actively-deployed CA.

You can use the following flags with maestro update-transitional remove:

  • all: Remove the transitional flag for all actively-deployed CAs.

  • name: Remove the transitional flag for a single CA.

  • dry-run: List CAs to be updated.

  • exclude: Exclude a list of CAs and their children from being updated.

  • show-excluded: Show all certificates excluded from update.

maestro garbage-collect

maestro garbage-collect deletes inactive certificate versions.

maestro garbage-collect leaf

maestro garbage-collect leaf deletes inactive leaf certificate versions that are older than the active certificate version.

You can use the following flags with maestro garbage-collect leaf:

  • all: Remove all inactive versions of deployed leaf certificates.

  • name: Remove all inactive versions of a single leaf certificate.

  • dry-run: List leaf certificate versions to be removed.

  • force: Remove all inactive leaf certificates.

maestro garbage-collect ca

maestro garbage-collect ca deletes inactive CA versions that are older than the active CA version.

You can use the following flags with maestro garbage-collect ca:

  • all: Remove all inactive versions of deployed CAs.

  • name: Remove all inactive versions of a single CA.

  • dry-run: List CA versions to be removed.

  • force: Remove all inactive CAs.

Safety checks

CredHub Maestro performs basic safety checks when rotating certificates to prevent unsafe operations.

To skip CredHub Maestro safety checks, you can pass the --skip-safety-check flag to CredHub Maestro certificate rotation commands.

For more information, see Troubleshooting CredHub Maestro Safety Violations During Certificate Rotation.

check-circle-line exclamation-circle-line close-line
Scroll to top icon