certbro

certbro is an open-source command-line tool for the regfish TLS API and DNS API. It bundles ordering, domain validation, download, key rotation, deployment and renewal into a single command, instead of scripting every step separately.

Note

certbro is not an ACME client. It does not talk to Let’s Encrypt - it orders from DigiCert through the regfish API, from DV all the way to OV products. If you want Let’s Encrypt, use certbot or acme.sh; if you want to automate the regfish products, use certbro.

Source code and releases: github.com/regfish/certbro (Go, Apache 2.0, no external dependencies).

Requirements

• Linux (the installer supports macOS, the systemd automation does not)
• a regfish API key with access to TLS and DNS - see Create an API key
• a DNS zone managed by regfish (certbro creates the validation records itself)
• systemd for unattended renewal

Installation

curl -fsSL https://regfish.com/certbro/install.sh | sh

The installer detects the operating system and architecture, downloads the matching archive from the GitHub releases, verifies the SHA256 checksum against checksums.txt and aborts on a mismatch. It installs to /usr/local/bin/certbro.

For a reproducible rollout, pin the version - the current one is listed under Releases:

curl -fsSL https://regfish.com/certbro/install.sh | CERTBRO_VERSION=v0.1.10 sh

Setup

sudo certbro configure --api-key YOUR_REGFISH_API_KEY

certbro checks the key against the API before storing it and remembers when it did so. Without a verified key, every other command refuses to run.

Caution

The key is stored in plain text in /etc/certbro/state.json (mode 0600). This file does not belong in any backup that is more widely accessible than the server itself.

And: a REGFISH_API_KEY environment variable is not enough. certbro does not read it - not even when it is set in the env file that certbro install generates. Only the key stored through configure counts.

Ordering a certificate

sudo certbro issue \
  --name example-com \
  --common-name example.com \
  --dns-name www.example.com \
  --webserver nginx

Only --common-name is required. The most important of the other flags:

Flag	Default	Meaning
--name	--common-name in lower case	logical name that renew uses to find the certificate again
--dns-name	-	additional name (SAN), repeatable
--product	RapidSSL	checked against the live catalog; GET /tls/products returns the available products
--key-type	rsa	rsa or ecdsa
--webserver	-	nginx, apache or caddy
--install-hook	-	shell command to run after deployment
--validity-days	see below	validity of the order
--org-id	-	organization handle (hdl_…) for OV products

For RSA and ECDSA side by side there is certbro issue-pair - it creates two certificates with the suffixes -rsa and -ecdsa and only reloads the web server once both are finished.

Where the files live

This is the part you need to know: certbro creates three directories under /etc/certbro/<common-name>/.

Directory	Contents
live/	the stable paths - privkey.pem, cert.pem, chain.pem, fullchain.pem, metadata.json, plus request.csr.pem and bundle.zip where present. Overwritten on every deployment.
archive/<timestamp>/	an untouched snapshot of each deployment
pending/	only while an order is running: private key, CSR and order state. Disappears as soon as the certificate has been deployed.

The web server configuration must point at live/, never at archive/. The paths there never change, which is why the vhost does not need to be touched after a renewal.

Web server integration

Caution

--webserver nginx does not mean that certbro writes the nginx configuration. certbro checks the configuration and reloads it - you create the vhost yourself, and it must point at live/fullchain.pem and live/privkey.pem.

What gets run in each case:

Value	Check	Reload
nginx	nginx -t	systemctl reload nginx, otherwise nginx -s reload
apache	apachectl -t	apachectl -k graceful, otherwise systemctl reload apache2
caddy	caddy validate	caddy reload, otherwise systemctl reload caddy

Use --webserver-config to specify a different configuration path. The command from --install-hook runs after the reload and receives the paths as environment variables (CERTBRO_LIVE_DIR, CERTBRO_FULLCHAIN_PATH, CERTBRO_PRIVKEY_PATH and others).

Validity

Without --validity-days, certbro takes the longest validity the CA/Browser Forum currently allows, minus one day:

From	Default
today	199 days
2027-03-14	99 days
2029-03-14	46 days

The value has to be greater than the renewal lead time, otherwise certbro rejects it - the renewal would run into an endless loop.

Renewing

sudo certbro renew

Without --name, certbro checks every managed certificate. One is due when it expires in less than --renew-before-days (default: 7 days). To renew a single certificate, use --name example-com; --force renews it regardless.

Tip

If renew appears to do nothing, that is usually not an error: freshly issued certificates are skipped for 48 hours, and ones that are not yet due are skipped anyway. --force bypasses both.

certbro prevents parallel runs with a lock file - the second run ends with a note and exit code 0, so it does not disturb a cron job.

Renewing automatically

sudo certbro install

This creates a systemd service unit and a timer unit, enables the timer and reloads systemd. The timer runs hourly with a random delay of up to 30 minutes, so that not all servers make requests at the same time. Missed runs are caught up.

Without systemd, a cron entry does the job just as well:

17 3 * * * /usr/local/bin/certbro renew

Keeping track

sudo certbro list

shows the status, names, key type, expiry date and whether an action is pending, among other things, for each certificate. --json makes the output machine-readable.

What certbro does not do

• No revoking. Use POST /tls/certificate/{id}/revoke for that.
• No removing. There is no command to drop a managed certificate again - delete the corresponding directory instead.
• No web server configuration. See above.
• No touching other people’s DNS records. If a CNAME that certbro did not create is already sitting at the validation name, the run aborts and names it. That record then has to go by hand.
• DNS validation only. certbro uses dns-cname-token exclusively; it does not support email validation.

Further reading

• TLS automation with certbro - the complete workflow as a recipe
• Order an OV certificate with certbro - completed in the dash
• TLS endpoints - the API certbro uses underneath