Skip to main content

Managing development certificates

Topaz CLI offers a couple of commands to manage the local development certificates:

Commands:
  certs list        list dev certs
  certs generate    generate dev certs
  certs trust       trust/untrust dev certs
  certs remove      remove dev certs

Certs list​

The certs list command will list the certificate files, their validity, common name and set dns names from your topaz certs configuration directory.

Example:

topaz certs list

certs directory: /home/<user>/.config/topaz/certs

  FILE            NOT BEFORE            NOT AFTER             VALID  CN                DNS NAMES                  
  gateway-ca.crt  2024-03-11T11:30:19Z  2025-03-11T11:30:19Z  true   topaz-gateway-ca                             
  gateway.crt     2024-03-11T11:30:26Z  2025-03-11T11:30:26Z  true   topaz-gateway-ca  localhost,<hostname>
  grpc-ca.crt     2024-03-11T11:30:29Z  2025-03-11T11:30:29Z  true   topaz-grpc-ca                                
  grpc.crt        2024-03-11T11:30:29Z  2025-03-11T11:30:29Z  true   topaz-grpc-ca     localhost,<hostname>

Certs trust​

Allows adding/removing the generated development certs to the list of OS trusted certs. 

Usage: topaz certs trust --certs-dir="/home/<user>/.config/topaz/certs"

trust/untrust dev certs

Flags:
  -h, --help                                          Show context-sensitive help.
  -N, --no-check                                      disable local container status check ($TOPAZ_NO_CHECK)
  -L, --log=0                                         log level

      --certs-dir="/home/<user>/.config/topaz/certs"  path to dev certs folder
      --remove                                        remove dev cert from trust store

Note: On Linux the automatic dev-cert trusting mechanism is disabled as although most other applications in Linux use the system's trust store, the way that a system handles trusting certificates varies depending on the Linux distribution.

Example:

  • Debian-based distribution: we need to copy the certificate to /usr/local/share/ca-certificates/grpc-ca.crt. If we want to remove a certificate from the trusted list, we just have to take it out of this directory.
  • Arch and Fedora distributions: we can add the dev-certificates using the trust command - trust anchor --store grpc-ca.crt. To remove a certificate you can use trust anchor --remove grpc-ca.crt.
  • Alpine Linux: we need to copy the certificate file to /etc/ssl/certs/grpc-ca.crt. If we want to remove the certificate from the trusted list, we just remove the file from this directory.

To make these changes take effect we'll need to run the update-ca-certificates command.

Certs generate​

The generate command allows you to generate a new set of development certificates.

Usage: topaz certs generate
generate dev certs

Flags:
  -h, --help                                          Show context-sensitive help.
  -N, --no-check                                      disable local container status check ($TOPAZ_NO_CHECK)
  -L, --log=0                                         log level

      --certs-dir="/home/<user>/.config/topaz/certs"    path to dev certs folder
      --force                                         force generation of dev certs, overwriting existing cert files
      --trust                                         add generated certs to trust store
      --dns-names=localhost,...                       list of DNS names used to generate dev certs

You can easily specify a different certs directory and specific custom dns-names if desired. If you use the --trust flag it will execute the certs trust command after generation.

Certs remove​

Remove the development certs from the specified cert directory.

Usage: topaz certs remove --certs-dir="/home/<user>/.config/topaz/certs"

remove dev certs

Flags:
  -h, --help                                          Show context-sensitive help.
  -N, --no-check                                      disable local container status check ($TOPAZ_NO_CHECK)
  -L, --log=0                                         log level

      --certs-dir="/home/<user>/.config/topaz/certs"  path to dev certs folder