cert-helper

What cert-helper is

A daemon that automates every step of getting a public TLS certificate on a CGP server, and keeps them fresh forever after.

CommuniGate Pro ships with only a manual TLS surface: an admin generates a private key in the web UI, pastes in a CSR or certificate, and files it under the domain’s SecureCertificate. No ACME. No Let’s Encrypt integration. No renewal scheduler. Every 90 days, someone remembers — or they don’t, and the browser certificate error page shows up on a Monday morning.

cert-helper replaces all of that with an unattended service. Every 24 hours (configurable) it walks the CGP CLI, finds every domain whose cert is inside the renewal window, orders a fresh one from Let’s Encrypt using DNS-01 via Cloudflare (or HTTP-01 via a static webroot), converts the key to the format CGP requires (PKCS#1 traditional RSA), pushes it back over the CGP CLI, and reads the installed cert back to confirm the fingerprint matches what was sent. If anything fails, an email lands in the postmaster mailbox with the domain name, timestamp, and error.

It also handles the “which domains SHOULD get a public cert” question. A CGP server usually has dozens of domains — a handful are yours, the rest are customer domains whose MX records point to your server but whose DNS you don’t control. Trying to issue certs for those would burn Let’s Encrypt rate limits and fail public CT log review. cert-helper’s eligibility filter (DNS lookup + local-IP check + allow/deny list) sorts them out, and (optionally) pushes CertificateType=Disabled to CGP for the ineligible ones — replacing any external “keep applying Disabled” script.

The renewal pipeline — end to end

Every renewal (manual or scheduled) runs the same 12-step pipeline. Understanding it makes troubleshooting simple — every step logs to cert-helper.log, so a failed run tells you exactly where it stopped.

Requirements before install

• CommuniGate Pro 6.4 or newer. The helper uses standard CLI verbs (LISTDOMAINS, GETDOMAINEFFECTIVESETTINGS, UPDATEDOMAINSETTINGS) which have been stable since 6.0.
• A CGP admin account. postmaster@<main-domain> works; needs domain-administrator rights on every domain the helper will touch.
• Network reachability to Let’s Encrypt. Outbound HTTPS to acme-v02.api.letsencrypt.org (production) or acme-staging-v02.api.letsencrypt.org (staging).
• A Cloudflare API token scoped to Zone.DNS:Edit on the zone containing your CGP domains. Global keys and tokens with excess scopes work but are strongly discouraged.
• The zone ID for that same zone.
• License file license.key covering cert-helper in its Helpers array. Without one, cert-helper runs in beta mode until 2026-12-31 (unstamped dev binary) or refuses to start (stamped release binary).
• Optional but recommended: A local SMTP relay on the CGP host, so postmaster notifications on failure can deliver.

Install — Windows & Linux

Windows

# 1. Create the install directory
New-Item -ItemType Directory C:\CommuniGate\Helpers\cert-helper -Force

# 2. Drop the binary + license
Copy-Item cert-helper.exe   C:\CommuniGate\Helpers\cert-helper\
Copy-Item license.key       C:\CommuniGate\Helpers\cert-helper\

# 3. Create the config from the template
Copy-Item cert-helper.toml.example C:\CommuniGate\Helpers\cert-helper\cert-helper.toml
notepad C:\CommuniGate\Helpers\cert-helper\cert-helper.toml
# see § Configuration reference

# 4. Register as a Windows Service (auto-start, restart-on-crash)
cd C:\CommuniGate\Helpers\cert-helper
.\cert-helper.exe --install-service
sc.exe start cert-helper
sc.exe query cert-helper

The service runs as LocalSystem. If you prefer a dedicated account, edit the service after install with sc.exe config cert-helper obj= "NT AUTHORITY\NetworkService".

Linux (Fedora / RHEL / Debian / Ubuntu)

The deploy tarball at /downloads/cert-helper/ contains a self-contained install-linux.sh that does everything below in one step. Or by hand:

sudo mkdir -p /opt/cert-helper /var/lib/cert-helper /var/log/cert-helper
sudo install -m 0755 cert-helper       /opt/cert-helper/cert-helper
sudo install -m 0600 license.key       /opt/cert-helper/license.key
sudo install -m 0600 cert-helper.toml  /opt/cert-helper/cert-helper.toml
sudo vim /opt/cert-helper/cert-helper.toml  # see § Configuration reference

sudo tee /etc/systemd/system/cert-helper.service <<'EOF'
[Unit]
Description=CGP Certificate Helper
After=network-online.target CGPro.service
Wants=network-online.target

[Service]
Type=simple
ExecStart=/opt/cert-helper/cert-helper --config /opt/cert-helper/cert-helper.toml
WorkingDirectory=/opt/cert-helper
Restart=always
RestartSec=30
User=root

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now cert-helper
sudo systemctl status cert-helper

Configuration reference (TOML)

Every section is optional at load time (defaults fill in what you omit) but you almost always want to review at least [cgp], [policy], [acme], and [cloudflare]. All master switches (SMTP send, auto-disable, ACME production URL) default to their safe value — nothing reaches out or mutates CGP until you opt in.

[cgp] — CommuniGate CLI connection

[db] — SQLite state store

[log] — File-based tracing

[policy] — Eligibility filter

[acme] — Let’s Encrypt account

[renewal] — Background scheduler

Retry backoff on per-domain failure: 1h → 6h → 24h → 24h → fail. After the 5th consecutive failure the row flips to failed; the scheduler skips it; an operator can reset by clicking Renew now on the dashboard.

[smtp] + [smtp.events] — Postmaster notifications

[web] — Operator dashboard

[cloudflare] — DNS-01 responder

Omit the whole [cloudflare] section to fall back to HTTP-01. See § HTTP-01 alternative.

First run & smoke test

• Start the service. On Windows: sc.exe start cert-helper. On Linux: systemctl start cert-helper.
• Open the dashboard at http://127.0.0.1:8765 (SSH port-forward if you’re remote: ssh -L 8765:127.0.0.1:8765 root@your-cgp-box).
• Verify the top strip: license status valid, config loaded, CGP host reachable.
• Click Run discover. Wait a few seconds. The domain list populates. Each row shows its outcome from the eligibility filter.
• Pick one eligible domain. Click Test renewal. This runs a dry-run of the challenge mechanism (creates a real TXT via CF, polls for propagation, deletes it) without burning an LE order. If this fails, so will a real renewal.
• When the probe passes, click Renew now. Watch the dashboard log tail. You should see the 12 pipeline steps run in order, ending in install verified with a new fingerprint.

Web dashboard tour

Read-write UI at http://127.0.0.1:8765. Auto-refreshes every 5 seconds.

Top strip

License status, server time, config file path, DB path, CGP host, policy mode, local IPs (both configured and auto-discovered).

Counts row

Total domains, and per-status counts (Active, Pending, Failed, Disabled, No-DNS, Ineligible).

Domain table

One row per CGP domain. Columns: name, status pill (colour-coded), CGP-side CertificateType, issuer, fingerprint (truncated), days-to-expiry (red if past, amber if under threshold), attempt count, last error.

Per-row action buttons:

• Renew now — force an immediate run through the pipeline. Resets attempt count first, so a failed row can be retried.
• Test renewal — dry-run of the challenge mechanism only. Safe to run any time.
• Enable / Disable — flip the operator-set status. Disabled is respected by the scheduler and by discovery’s auto-disable path.
• Re-discover — refresh just this row from CGP.

Recent log

Last 50 audit lines from the state DB: discover, renew-success, renew-failed, enable, disable, notification-sent.

Config panel

View + edit the TOML in-place. Save writes to the file on disk and reloads. Fields that would break the running scheduler (interval, threshold) apply immediately; changes to [cgp] host/port take effect on the next connection.

Eligibility filter

The customer’s core requirement: most CGP domains should NOT get a public cert. This is what the filter does, per domain.

• Allow / deny gate. allow_all_except passes everything except the listed names. deny_all_except only passes listed names. Denied = whole cert dropped with reason PolicyDeny.
• Collect SAN candidates. Base name + DomainAliases array + host part of Preferred URL for HTTP. Each candidate is evaluated separately from now on.
• DNS lookup. A / AAAA records via the OS resolver (tokio::net::lookup_host). NXDOMAIN = NoDns. Timeout / other errors = DnsError.
• Local-IP intersection. At least one resolved IP must be in local_ips. Miss = NotLocal.

Partial-cert fallback: a domain with 3 aliases where 1 fails still gets a cert, covering the 2 that passed. The dropped name goes into the dropped array and (if [smtp.events].sans_shrunk = true) triggers a notification email at renewal time.

Auto-disable: when auto_disable = true, a domain that just flipped from Active/Pending to Ineligible has its CertificateType set to Disabled via UPDATEDOMAINSETTINGS. This is idempotent — the setting is checked first, only written if it differs. Operator-set Disabled is never overridden.

Auto-renewal scheduler

When [renewal] enabled = true, a background tokio::time::interval task ticks every interval_seconds. First tick is skipped (avoids startup race). Each tick runs one renewal pass:

• Query SELECT domain FROM domains WHERE status='active' AND not_after < datetime('now', '+' || threshold_days || ' days').
• For each row, skip if Disabled / Ineligible / attempt_count ≥ MAX_ATTEMPTS (5).
• Check backoff window: skip if last_attempt + backoff(attempt_count) is in the future.
• Call renew_one(ctx, domain) — the same code path a manual Renew now uses.
• On success: reset attempt_count, update DB.
• On failure: record_attempt(domain, error), increment attempt_count, set backoff. After 5 attempts flip to failed.
• Send notification if the event class is enabled in [smtp.events].

Postmaster notifications

Four event classes, each independently toggleable. Every notification carries timestamp, domain, and error/context.

issuance_failed

The pipeline could not obtain a cert — ACME account creation failed, order was rejected, all SANs failed validation, LE returned a hard error, or install into CGP failed the read-back verify.

sans_shrunk

A renewal that yielded a cert covering fewer SAN names than the previous cert. Body lists which names were lost and which were kept. Operator investigates: did an alias’s DNS move? Was a domain removed? Did a CF token lose access to a zone?

no_dns

A configured domain or alias didn’t resolve at all (NXDOMAIN). Usually a stale DomainAliases entry.

not_local

Resolves but the IP isn’t in local_ips. Common cause: domain moved behind Cloudflare / another CDN, or your mailserver’s IP changed and local_ips is stale.

Cloudflare DNS-01 setup

DNS-01 is the recommended path for any domain fronted by a CDN (which most CGP-served domains are). It doesn’t require the helper to serve HTTP on port 80.

Create the API token

• Cloudflare dashboard → My Profile → API Tokens → Create Token.
• Use the template Edit zone DNS. Do NOT use the global API key.
• Zone Resources → Include → Specific zone → <your zone>. Cover only the zones cert-helper will touch.
• (Optional but recommended:) Client IP Address Filtering → restrict to the cert-helper host’s public egress IP.
• Save. The token string is shown once — copy it now.

Find the zone ID

Cloudflare dashboard → click your zone → the right sidebar shows Zone ID (32 hex chars).

Put both into [cloudflare]

[cloudflare]
api_token = "cfut_...your token..."
zone_id   = "6b57eb04d8a0ee5d819f69499186e300"

Restart cert-helper. That’s it. First Test renewal or Renew now will use it.

HTTP-01 alternative

When there’s no CDN in front of your domains, HTTP-01 is simpler: LE fetches http://<domain>/.well-known/acme-challenge/<token>, expects the key-authorization as the body.

Configure by omitting the [cloudflare] section and pointing [acme].http01_dir to a directory some HTTP server can serve at /.well-known/acme-challenge/. Two typical setups:

CGP’s own HTTP

CGP’s HTTPU already serves /webskins/<skin>/* paths. You can add a static mapping in the CGP Webskin config so /.well-known/acme-challenge/* serves from cert-helper’s http01_dir. Requires a small skin edit.

Nginx / Apache in front

Most reverse-proxy setups already do this:

location /.well-known/acme-challenge/ {
    root /var/lib/cert-helper;   # http01_dir’s parent
    default_type text/plain;
}

Staging vs production

Let’s Encrypt runs two directories:

Always develop against staging. Rate limits there are generous enough that an accidental infinite loop won’t lock you out. When staging works end-to-end for at least one domain:

• Switch [acme].directory_url to production.
• Drop the staged account: sqlite3 /var/lib/cert-helper/state.sqlite "DELETE FROM config WHERE key='acme_account_credentials'". Restart. A fresh production account is created on the next renewal.
• Trigger one manual Renew now. Verify the new cert’s issuer says Let’s Encrypt R12 (not the staging one).
• Once verified, the scheduler will use production for all future renewals.

Troubleshooting

Uninstall

Windows

sc.exe stop cert-helper
cd C:\CommuniGate\Helpers\cert-helper
.\cert-helper.exe --uninstall-service
Remove-Item -Recurse C:\CommuniGate\Helpers\cert-helper

Linux

sudo systemctl stop cert-helper
sudo systemctl disable cert-helper
sudo rm /etc/systemd/system/cert-helper.service
sudo systemctl daemon-reload
sudo rm -r /opt/cert-helper /var/lib/cert-helper /var/log/cert-helper

FAQ & glossary

Does cert-helper support wildcard certs?

Yes for issuance (LE supports *.example.com via DNS-01 only), but the current release doesn’t explicitly configure them. Add the wildcard as a DomainAliases entry on the CGP domain and it becomes a SAN candidate. Future release will add a first-class wildcard toggle.

Can I run one cert-helper for multiple CGP hosts?

Yes if they share a common CGP admin over a network-reachable port 106, but the recommended pattern is one cert-helper per CGP host — state stays local, dashboard is loopback-only, and there’s no cross-host coordination in the DB schema.

Does cert-helper store private keys?

Each issued cert’s private key is generated freshly per renewal, sent to CGP’s PrivateSecureKey field, and dropped from cert-helper memory. The state DB stores only the fingerprint and metadata, never the key material.

What happens if my Cloudflare API token is revoked?

Next renewal for any domain in that zone fails with an HTTP 401 from Cloudflare’s API. The issuance_failed notification fires. Rotate the token, edit [cloudflare].api_token, restart. Backoff timers reset on the next manual Renew.

Can I use another CA (ZeroSSL, Buypass) instead of Let’s Encrypt?

Any RFC 8555 ACME CA works — just point [acme].directory_url at their directory. Tested only against LE.

What’s the difference between failed and ineligible?

failed = we tried to renew and something went wrong (5 attempts exhausted). Row waits for operator action. ineligible = the eligibility filter said no (DNS, local-IP, or allow/deny gate). Row will be re-checked next discovery pass; if the underlying condition changes (new DNS, updated local_ips, adjusted allow-list), it’s promoted back to pending and picked up by the next scheduler tick.

What’s the license about?

An RSA-2048-signed JSON blob listing which helpers this box is licensed to run and until when. Sibling to notification-helper, dkim-signer, mailing-list-helper. cert-helper accepts any license whose Helpers array contains "cert-helper". Contact [email protected] to obtain one, or generate with the internal license-generator-v2.py.

Glossary