GUIDE / PUBLIC BETA

How to automate Let's Encrypt certificate renewal on WatchGuard Firebox

Certbot and acme.sh can renew a certificate, but renewal alone does not place it on a Firebox. For cloud-managed devices, wgcert provides a small deployment step using WatchGuard's Firebox Management API.

1. Check the management mode

WatchGuard's certificate endpoints apply to cloud-managed Fireboxes whose configuration is stored in WatchGuard Cloud. Locally-managed Fireboxes, including devices that send only reports to the cloud, are outside this integration. Certificate API support requires a compatible Fireware version; WatchGuard documents v12.5.7 or later for cloud-managed devices.

In WatchGuard Cloud, enable API access under Administration → Managed Access. Use a read-write access ID for deployment. Keep the API key and password in the process environment; do not paste them into command arguments or issue reports.

2. Install wgcert

Download the archive for your operating system from the v0.1.0 prerelease. Check it against SHA256SUMS. Alternatively, build from source with Go 1.22 or later:

go test ./...
go build -o wgcert ./cmd/wgcert
./wgcert version

3. Configure the WatchGuard API

Use the regional base API and authentication URLs shown in Managed Access. The authentication URL can include /oauth/token; wgcert also accepts the base URL.

export WATCHGUARD_ACCOUNT_ID='ACC-...'
export WATCHGUARD_API_URL='https://api.REGION.cloud.watchguard.com'
export WATCHGUARD_AUTH_URL='https://api.REGION.cloud.watchguard.com'
export WATCHGUARD_API_KEY='...'
export WATCHGUARD_ACCESS_ID='...'
export WATCHGUARD_ACCESS_PASSWORD='...'

For unattended hooks, load these values from a file readable only by the service account. The values above are placeholders, not working credentials.

4. Discover and dry-run

wgcert devices
wgcert deploy --device FB-12345 \
  --cert /path/to/fullchain.pem \
  --key /path/to/privkey.pem \
  --dry-run

The dry-run parses the PEM files, checks that the key matches the leaf certificate, retrieves device certificate inventory, and describes the mutation plan without creating or installing anything.

For a WatchGuard Service Provider account, wgcert devices --include-hierarchy asks the Device Details API to include Subscriber-account devices. This is discovery only in the current beta; fleet deployment is intentionally out of scope.

5. Install a certificate on a test Firebox

wgcert deploy --device FB-12345 \
  --cert /path/to/fullchain.pem \
  --key /path/to/privkey.pem \
  --wait 2m

The WatchGuard install command is asynchronous. With --wait, wgcert polls the install transaction until it completes, fails or reaches the timeout. After the install request, wgcert also re-reads the remote certificate object and verifies its fingerprint against the local certificate.

If you explicitly need a full configuration deployment, add --deploy-config. Combined with --wait, wgcert also waits for that deployment transaction. A full deployment can include all pending configuration changes for the device, so review them first.

6. Verify the intended service

wgcert check --device FB-12345 \
  --verify-host firewall.example.com:443

This command reads WatchGuard Cloud's certificate inventory and performs a verified TLS handshake to the hostname you specify. Compare the served fingerprint with the certificate you intended to deploy. A certificate present in inventory is not enough to conclude that a proxy, management UI, VPN endpoint or other service is using it.

7. Connect your renewal client

The repository includes a Certbot deploy hook using RENEWED_LINEAGE. Set WGCERT_DEVICE and the WatchGuard environment variables in the hook's service environment. For acme.sh, use the reload script with installed fullchain and key paths supplied through WGCERT_CERT and WGCERT_KEY. Test a manual invocation against a lab device before enabling unattended renewal.

What is still unknown?

The key question is whether a renewed certificate becomes active in the intended Firebox configuration without a recurring manual step, including when the previous certificate is referenced by a service. A FireboxV or cloud-managed Firebox test must settle this. If you can test it, please share sanitized results.