step ca renew

Name

step ca renew -- renew a certificate

Usage

step ca renew <crt-file> <key-file>
[--mtls] [--password-file=<file>] [--out=<file>] [--expires-in=<duration>]
[--force] [--pid=<int>] [--pid-file=<file>] [--signal=<int>]
[--exec=<string>] [--daemon] [--renew-period=<duration>]
[--ca-url=<uri>] [--root=<file>] [--context=<name>]

Description

step ca renew command renews the given certificate (with a request to the certificate authority) and writes the new certificate to disk - either overwriting crt-file or using a new file when the --out=file flag is used.

With the --daemon flag the command will periodically update the given certificate. By default, it will renew the certificate before 2/3 of the validity period of the certificate has elapsed. A random jitter is used to avoid multiple instances running at the same time. The amount of time between renewal and certificate expiration can be configured using the --expires-in flag, or a fixed period can be set with the --renew-period flag.

The --daemon flag can be combined with --pid, --signal, or --exec to provide certificate reloads on your services.

By default, the renew command authenticates to step-ca using mTLS, except when the certificate is expired and renewal after expiry is allowed by the CA.

There are scenarios where mTLS is not possible: When step-ca is behind a layer 7 proxy, when the server's leaf certificate EKU is not configured for client authentication, or when the server is a StepCAS RA for an upstream step-ca server. For these scenarios, use --mtls=false to force a flow that uses X5C token-based authentication.

Positional arguments

crt-file The certificate in PEM format that we want to renew.

key-file They key file of the certificate.

Options

--mtls Use mTLS to renew a certificate. Use --mtls=false to force the token authorization flow instead.

--ca-config=file The certificate authority configuration file. Defaults to $(step path)/config/ca.json

-f, --force Force the overwrite of files without asking.

--offline Creates a certificate without contacting the certificate authority. Offline mode uses the configuration, certificates, and keys created with step ca init, but can accept a different configuration file using --ca-config flag.

--password-file=file The path to the file containing the password to encrypt or decrypt the private key.

--out=file, --output-file=file The new certificate file path. Defaults to overwriting the crt-file positional argument

--expires-in=duration The amount of time remaining before certificate expiration, at which point a renewal should be attempted. The certificate renewal will not be performed if the time to expiration is greater than the --expires-in value. A random jitter (duration/20) will be added to avoid multiple services hitting the renew endpoint at the same time. The duration is a sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".

--pid=value The process id to signal after the certificate has been renewed. By default the the SIGHUP (1) signal will be used, but this can be configured with the --signal flag.

--pid-file=file The file from which to read the process id that will be signaled after the certificate has been renewed. By default the SIGHUP (1) signal will be used, but this can be configured with the --signal flag.

--signal=number The signal number to send to the selected PID, so it can reload the configuration and load the new certificate. Default value is SIGHUP (1)

--exec=command The command to run after the certificate has been renewed.

--daemon Run the renew command as a daemon, renewing and overwriting the certificate periodically. By default the daemon will renew a certificate before 2/3 of the time to expiration has elapsed. The period can be configured using the --renew-period or --expires-in flags.

--renew-period=duration The period with which to schedule renewals of the certificate in daemon mode. Requires the --daemon flag. The duration is a sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "1.5h", or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".

--ca-url=URI URI of the targeted Step Certificate Authority.

--root=file The path to the PEM file used as the root certificate authority.

--context=name The context name to apply for the given command.

Examples

Renew a certificate with the configured CA:

Renew a certificate without overwriting the previous certificate:

Renew a certificate forcing the overwrite of the previous certificate:

Renew a certificate using the token flow instead of mTLS:

Renew a certificate providing the --ca-url and --root flags:

Renew skipped because it was too early:

Renew the certificate before 2/3 of the validity has passed:

Renew the certificate before 8 hours and 30m of the expiration time:

Renew the certificate every 16h:

Renew the certificate and reload nginx:

Renew the certificate and convert it to DER:

Renew a certificate using the offline mode, requires the configuration files, certificates, and keys created with step ca init: