Wrapper for `step ca renew` that behaves sanely with systemd

[Torstein-Eide]

Hi folks,

I ran into a small but persistent operational annoyance with step ca renew:

When a certificate does not need renewal, step exits with code 1.
That is technically correct – but in a systemd world, it looks like a failure.

So I wrote a tiny wrapper that makes renewal boring again:

• Pre-checks whether renewal is actually needed
• Only runs step ca renew when required
• Normalizes exit codes so “nothing to do” = success
• Supports post-renew hooks (reload nginx, haproxy, etc.)
• Plays nicely with systemd timers and services

Repo:
https://github.com/Torstein-Eide/Step-certificate-renewal-wrapper-script

The goal is not to replace step, but to make it operationally smoother in real systems where exit codes matter and automation should stay quiet unless something actually broke.

Bluntly:
step is correct.
systemd is strict.
This script keeps the peace between them.

Feedback welcome. If this solves a problem for others, even better.

[tashian]

Hi @Torstein-Eide, thanks for this!

We designed the needs-renewal subcommand to accommodate systemd. I ran into similar operational needs in my homelab and realized we needed this new subcommand, because I was having to write some bash to make step ca renew work with systemd.

We offer an example here of a service template that can be used to renew certs for systemd services:

[Unit]
Description=Certificate renewer for %I
After=network-online.target
Documentation=https://smallstep.com/docs/step-ca/renewal
StartLimitIntervalSec=0

[Service]
Type=oneshot
User=root

Environment=STEPPATH=/etc/step-ca \
            CERT_LOCATION=/etc/step/certs/%i.crt \
            KEY_LOCATION=/etc/step/certs/%i.key

; ExecCondition checks if the certificate is ready for renewal,
; based on the exit status of the command.
; (In systemd <242, you can use ExecStartPre= here.)
ExecCondition=/usr/bin/step certificate needs-renewal ${CERT_LOCATION}

; ExecStart renews the certificate, if ExecStartPre was successful.
ExecStart=/usr/bin/step ca renew --force ${CERT_LOCATION} ${KEY_LOCATION}

; Try to reload or restart the systemd service that relies on this cert-renewer
; If the relying service doesn't exist, forge ahead.
; (In systemd <229, use `reload-or-try-restart` instead of `try-reload-or-restart`)
ExecStartPost=/usr/bin/env sh -c "! systemctl --quiet is-active %i.service || systemctl try-reload-or-restart %i"

[Install]
WantedBy=multi-user.target

The idea here is to use systemd hooks to do any before/after renewal tasks. This can be customized with overrides for each specific service, since different services need different things in order to reload their certificates.

Could you help me understand the gap between what we've offered here, and what you've created?

If there are small changes we can make to step that would better address issues you encountered, we're definitely open to enhancement requests in this area.

[Torstein-Eide]

The line ExecCondition=/usr/bin/step certificate needs-renewal ${CERT_LOCATION} will have a return code of 1 to systemd this is an error, as I sad:

When a certificate does not need renewal, step exits with code 1. That is technically correct – but in a systemd world, it looks like a failure.

So I wrote a tiny wrapper that makes renewal boring again:

• Pre-checks whether renewal is actually needed
• Only runs step ca renew when required
• Normalizes exit codes so “nothing to do” = success
• Supports post-renew hooks (reload nginx, haproxy, etc.)
• Plays nicely with systemd timers and services

Since it now will have a return code of 0, the post ExecStartPost=/usr/bin/env sh -c "! systemctl --quiet is-active %i.service || systemctl try-reload-or-restart %i" will also run.

[tashian]

When an ExecCondition= returns a non-zero exit status, systemd does not treat it as an error. The unit is skipped — systemd considers this a successful condition check that evaluated to "don't run."

Specifically:

• Exit code 0: Condition met, proceed with the unit
• Exit codes 1-254: Condition not met, skip the unit (not treated as failure)
• Exit code 255: Treated as an actual error/failure

Ref: https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html#ExecCondition=

[Torstein-Eide]

When using ExecCondition=/usr/bin/step certificate needs-renewal ${CERT_LOCATION}

When wrapped

[tashian]

I see, thanks for sharing that.
So I can understand, you're seeing process failures (unit exit codes) and those end up getting treated as errors somewhere else in your workflow? And your wrapper ensures the unit's process exited successfully.

[Torstein-Eide]

Not exactly. Nothing downstream is actually affected by it, but I dislike seeing process failures (unit exit codes) for something that is a normal and expected state. Similar to certbot.

[tashian]

Yeah I agree. If you want to address this at the source, you could open a bug on systemd saying that it's confusing to display the standard exit code mappings when systemd used its own custom mapping to evaluate the exit code. For ExecCondition=, it would be accurate to display (1/SKIPPED) for example.