Certificate Profiles
A certificate profile is the saved recipe for one certificate: the hostname, the DNS credential set, the Let's Encrypt account and the renewal settings. Issuing from a profile only STAGES a certificate — nothing is served until you activate it explicitly on Certificates or SSL Status. Start on the staging account: a staging certificate proves the credentials and the issuance path and is never served.
Inputs
| Name | Description | Allowed values | Default |
|---|---|---|---|
Name | How the profile is listed and named in issuance runs | Unique text | — |
Hostname | The name the certificate is issued for | One fully qualified domain name | — |
DNS credential set | Which stored provider credentials answer this profile's DNS-01 challenge | Any set on the DNS Credential Sets page | — |
ACME account | Staging (proof only) or production (trusted). Set when the profile is created and moved afterwards only by Promote | Let's Encrypt staging or Let's Encrypt production | Let's Encrypt staging |
Renew automatically | Renew before expiry and activate the renewed certificate once it is proven served. Unavailable on staging profiles, which are never scheduled | Checkbox | Off |
Renew before (days) | How many days before expiry a renewal starts | 7 to 60 | 30 |
Fields & columns
| Name | Description |
|---|---|
Account | "Staging — proof only" or "Production — trusted". A staging profile can never produce a served certificate |
DNS credential set | The credential set this profile uses for the DNS-01 challenge |
Auto-renew | On, Off, or "Never (staging)" — only production profiles are scheduled |
Next renewal | The absolute date the scheduler will next renew this profile's bound certificate |
Last run | The latest issuance run's status and, while it is working, the step it is on |
Failures | Consecutive failed issuances. The retry delay doubles with each one; a manual issue ignores it |
ACME accounts panel | The two fixed Let's Encrypt accounts. Each email can be edited until the account key exists, then it locks |
How to
Get a trusted certificate for the first time
- Add a DNS credential set and test it first — issuance cannot work without one.
- Set the email on the Let's Encrypt staging account in the panel at the top of this page.
- Click "Add Certificate Profile", name it, enter the hostname, choose the credential set and leave the account on staging.
- Save, then click "Test issuance (staging)". Click the row to watch the steps.
- When the staging run succeeds, set the email on the production account if it is not set yet.
- Click "Promote to production". The profile moves to the production account and a trusted issuance starts immediately.
- When that run succeeds the certificate is Ready, not active. Open Certificates (or rung 6 on SSL Status) and activate it.
Read a failed run
- Click the profile row to open its latest run.
- Each step shows a glyph: a tick for succeeded, a cross for failed, a dash for skipped, an ellipsis while running.
- The failure box names the step that failed and the redacted message.
- It also names the HTTP exchange journal folder — /data/config/acme-http-journal/<run>/ inside the manager container — which holds every request and response of that run with secrets scrubbed.
- Fix the cause, then issue again. A manual issue ignores the retry backoff.
Re-test a production profile
- The ACME account moves one way, staging to production, so a production profile cannot be moved back.
- Click "Duplicate as staging profile". The copy keeps the hostname, credential set and renewal window, and lands on the staging account with auto-renew off.
- Run "Test issuance (staging)" on the copy as often as you need — staging rate limits are lenient and nothing it produces is ever served.
Gotchas
- Setting up TLS for the first time? Start on SSL Status. It creates the profile with the hostname and credential set already filled in and offers the staging proof, the real issuance, activation and auto-renew in order. This page is for editing a profile directly or watching a run's steps.
- DNS propagation is confirmed against the zone's own authoritative nameservers, not a public resolver. That is deliberate: a public resolver caches the "no such record" answer it gave before the record existed, for as long as the zone's negative TTL says (an hour on some zones), so a retry inside that window could never see a freshly written record. Authoritative servers are not caches, and they are what Let's Encrypt validates against.
- Issuing never activates. A successful run leaves the certificate Ready in the inventory; serving it is a separate, explicitly confirmed step.
- A staging certificate is proof only. It is never activated, never a rollback target and never auto-renewed, whatever else is configured.
- The ACME account is chosen once. A trusted certificate comes from Promote, which also bumps the profile revision and starts the run in one action; it cannot be undone.
- Production has strict rate limits: 5 duplicate certificates per week, and failed attempts count. That is why an unproven production issue asks for confirmation.
- Auto-renew is unavailable on staging profiles, because only production profiles are scheduled at all.
- Renewal auto-activates only a certificate that renewal itself created, at the profile's current revision, once. A certificate you issued by hand always waits for an explicit activation.
- Editing a profile bumps its revision, which makes any Ready certificate from an earlier revision ineligible for auto-activation.
- Editing or deleting a profile is refused while one of its runs is still running.
- If the manager restarts mid-run, that run is marked failed at whichever step was going. The abandoned order is not resumed and any DNS challenge record it published is left at the provider — harmless, because the next Issue uses a fresh order and cleans up only its own records.
API calls (9)
| Method | Path | Description |
|---|---|---|
| GET | /api/admin/ssl/certificate-profiles | List profiles with their account, last run, next renewal and failure count |
| POST | /api/admin/ssl/certificate-profiles | Create a profile |
| PUT | /api/admin/ssl/certificate-profiles/:id | Update a profile and bump its revision |
| DELETE | /api/admin/ssl/certificate-profiles/:id | Delete a profile that has no running issuance |
| POST | /api/admin/ssl/certificate-profiles/:id/issue | Start an issuance run that only stages the certificate |
| POST | /api/admin/ssl/certificate-profiles/:id/promote | Move a staging profile to the production account and start a trusted issuance |
| GET | /api/admin/ssl/acme-accounts | Read the two fixed Let's Encrypt accounts |
| PUT | /api/admin/ssl/acme-accounts/:id | Set an account contact email, while the account key does not exist yet |
| GET | /api/admin/ssl/issuance-runs/:id | Poll one issuance run and its recorded steps |
Related
- DNS Credential Sets — A profile needs a tested credential set to answer its DNS-01 challenge
- Certificates — A successful run leaves a Ready certificate here, waiting for an explicit activation
- SSL Status — The guided path: creates the profile, runs the staging proof and the real issuance, activates and turns on auto-renew, one step at a time
- Issuance Runs — Every run these profiles started, including the older ones this page no longer shows