Certbot examples¶

The CertIntel Agent is the preferred method for certificate workflows, renewals and reporting. Its built-in scheduling and reporting make setup and maintenance easier; see the Linux Agent setup guide. These API reporting examples are an optional alternative when you want to keep Certbot as the renewal owner.

These PowerShell 7 examples wrap Certbot and send the same CertIntel requests as scripts/simple-acme/:

/api/v1/checkins/start before every Certbot run
/api/v1/checkins after every run, even when nothing was due
/api/v1/renewals/enrich from the successful deploy hook, including the current and previous certificate thumbprints, validity, SANs, and lineage path
/api/v1/renewals for each successful issuance, plus a failure event when Certbot exits non-zero

Files¶

Request-Certificate.ps1 wraps certbot certonly.
Renew-Certificates.ps1 wraps certbot renew and is the script to schedule.
Deploy-Hook.ps1 consumes Certbot's RENEWED_LINEAGE and RENEWED_DOMAINS hook variables after each successful issuance.
CertIntel-Common.ps1 contains the shared API, PEM-reading, previous-certificate snapshot, and native-process wrapper functions.

The scripts require PowerShell 7 (pwsh) on the Certbot host. They are designed for Linux paths and work with Certbot's standard /etc/letsencrypt configuration directory. Run them as an account that can run Certbot and read that directory, normally root.

Create a unique CertIntel write key for this host (scoped to the target organization, with both renewals and checkins enabled), then make these environment variables available to the scheduled account. Authentication is a single header, X-Api-Key: cik_<prefix>.<secret>:

export CERTINTEL_API_URL='https://api.certin.tel/api/v1/renewals'
export CERTINTEL_CHECKINS_URL='https://api.certin.tel/api/v1/checkins'
export CERTINTEL_API_KEY='cik_XXXXXXXX.YYYYYYYYYYYYYYYYYYYYYYYY'   # full write-scoped token

Use a protected environment file or your service manager's credential facility for the secret. Do not put it directly in a systemd ExecStart command or cron line.

Request a certificate¶

CertIntel DNS-01 plugin¶

First install the CertIntel wheel and create the private delegation mapping. The mapping file must be owned by the account running Certbot with mode 600. Use the same venv binary for both wrappers; a system or snap Certbot will not see the plugin installed in another environment. The DNS plugin has been tested; these additional reporting wrappers remain examples to verify in your environment.

Run from a Linux/WSL shell under the account with access to the credentials and Certbot directories (normally root):

pwsh -NoLogo -NoProfile -File ./Request-Certificate.ps1 \
  -Domain 'example.com,*.example.com' -Email [email protected] \
  -CertName example.com-staging \
  -Authenticator dns-certintel \
  -CredentialsPath /etc/certintel/delegations.json \
  -PropagationSeconds 60 \
  -CertbotPath /opt/certintel-certbot/bin/certbot \
  -ConfigDirectory /etc/letsencrypt-certintel-staging \
  -WorkDirectory /var/lib/letsencrypt-certintel-staging \
  -LogsDirectory /var/log/letsencrypt-certintel-staging \
  -Staging

The wrapper saves an absolute credentials path for renewal. Its CERTINTEL_API_KEY is the separate write-scoped reporting key, not the DNS credential in that file. Staging issuance is reported to CertIntel; use a test organization/reporting key. -DryRun on the renewal wrapper suppresses issuance reporting instead.

After staging succeeds, repeat issuance without -Staging, use -CertName example.com, and omit the three staging directory options to use production defaults. Test the saved production renewal and schedule the same command without -DryRun:

pwsh -NoLogo -NoProfile -File ./Renew-Certificates.ps1 \
  -CertName example.com -CertbotPath /opt/certintel-certbot/bin/certbot -DryRun

Replace the bare Certbot scheduler with the wrapper if you want check-in reporting. Renewal uses the authenticator, mapping and propagation delay saved at issuance. These scripts report certificate details; configure application deployment or reloads separately.

Other authenticators¶

Webroot example:

sudo -E pwsh -NoLogo -NoProfile -File ./Request-Certificate.ps1 \
  -Domain example.com,www.example.com \
  -Email [email protected] \
  -WebRoot /var/www/html

Standalone example (port 80 must be available):

sudo -E pwsh -NoLogo -NoProfile -File ./Request-Certificate.ps1 \
  -Domain example.com \
  -Email [email protected] \
  -Authenticator standalone

For DNS plugins, set -Authenticator to the installed plugin name and pass its remaining Certbot options as an array with -AdditionalArguments. Keep credential files readable only by the scheduled account. Use -Staging while proving challenge configuration.

The wrapper supplies Deploy-Hook.ps1 through --deploy-hook; do not separately install the same file in /etc/letsencrypt/renewal-hooks/deploy, or the issuance may be reported twice.

Renew certificates¶

Check every configured lineage:

sudo -E pwsh -NoLogo -NoProfile -File ./Renew-Certificates.ps1

Check one lineage or test renewal configuration against staging:

sudo -E pwsh -NoLogo -NoProfile -File ./Renew-Certificates.ps1 -CertName example.com
sudo -E pwsh -NoLogo -NoProfile -File ./Renew-Certificates.ps1 -DryRun

Schedule this wrapper instead of calling certbot renew directly, and replace or disable any preinstalled Certbot timer that still invokes the bare command. Certbot returns zero when nothing is due, so the wrapper always posts a completion check-in while the deploy hook is the authoritative signal that a certificate was actually issued. Dry runs post a check-in but intentionally suppress renewal/enrich payloads so staging certificates do not appear in production renewal history.

Before Certbot runs, the wrapper snapshots each current live/*/cert.pem thumbprint to a temporary file. The deploy hook uses that snapshot for OldCertThumbprint, preserving CertIntel's renewal-event replacement chain after Certbot updates the live links. The temporary file is deleted when the run ends and contains no private keys.

-ForceRenewal is for controlled testing only; routine use can exhaust CA rate limits.

Official references: