Let's Encrypt certificate for a tunnelled controller

When your controller login uses the controller tunnel, SZ-MCP can replace the controller’s self-signed certificate with one from Let’s Encrypt and renew it automatically. The certificate is issued for the tunnel hostname, for example sz-abcdefghijkl.neuralconfig.dev. The controller generates the private key itself, and the key never leaves the controller.

SZ-MCP does not need this certificate: the tunnel reaches a self-signed controller anyway. The certificate is for everything else that talks to the controller, such as the management web UI, the AP portal and the hotspot.

It comes with the controller tunnel, which is in limited rollout: contact support to have it enabled.

What do I need before I can get a certificate?

An admin with tunnels enabled, and a controller login that uses the tunnel. The Controller certificate (Let’s Encrypt) card on Configure › Controller appears only once the organisation has a tunnel. Until each condition is met, it says why:

Condition	What the card says otherwise
You are an organisation admin or the owner	”Only organisation admins can set this up.”
Controller tunnels are enabled for your account	”Controller certificates come with controller tunnels, which are in limited rollout.”
The controller login uses the tunnel hostname	”Use the tunnel for the controller login first: the certificate is installed through it.”

Every member can see the card’s status.

How do I get a certificate?

1. On Configure › Controller, find the Controller certificate (Let’s Encrypt) card.

2. Under Install it for:, tick the controller services that should use it. At least one is required, and Management web UI and API is ticked by default.

   Option	SmartZone service
   Management web UI and API	MANAGEMENT_WEB
   AP portal (guest and web auth)	AP_PORTAL
   Hotspot (WISPr)	HOTSPOT

3. Leave Renew automatically on (the default): “At two thirds of its life (about 60 days), under your approval.” Turn on Let’s Encrypt staging only to try the flow out: “A test certificate browsers don’t trust; for trying it out.” Staging is off by default.

4. Click Get a certificate. The card says “Saved. A certificate is issued within a minute or two.” and follows the run until it finishes.

What does SZ-MCP do to the controller?

It creates a key and certificate request on the controller, has Let’s Encrypt sign it, installs the result and points the chosen services at it. In order:

1. The controller generates the key and a certificate signing request (CSR) for the tunnel hostname. The key stays on the controller.
2. SZ-MCP reads the CSR and proves to Let’s Encrypt that it controls the name, with a DNS-01 challenge in SZ-MCP’s own DNS zone. Nothing on your network changes for this.
3. The signed certificate is imported on the controller, paired with its key. Its name on the controller is LE <tunnel label> <date-time>, for example LE sz-abcdefghijkl 20261004-0251.
4. The services you chose are switched to it, and SZ-MCP reads the setting back to confirm.
5. The certificate and CSR it replaced are removed, if nothing else uses them.

If a step fails, SZ-MCP undoes what that run created: the service mapping, the new certificate and the new CSR. The previous certificate stays in service. Each write to the controller is recorded in Write history, under the admin who approved the certificate.

The name is the tunnel hostname

The certificate is valid only for the tunnel hostname. Browsers on your network that reach the controller directly by its LAN address will still warn. For them, add an internal DNS record that points the tunnel hostname at the controller’s LAN address.

When is it renewed?

At two thirds of the certificate’s life (about 60 days for a Let’s Encrypt certificate), if Renew automatically is on. A job runs every minute and renews certificates that are due. A renewal runs under the approval of the admin who enabled it. That approval is checked again before every run.

Control	What it does
Renew now	Issues a new certificate at once, and makes you the approving admin. Limited to 3 a day per organisation; beyond that it returns rate_limited. Refused with “A certificate is being issued now.” while a run is in progress
Save	Appears when you change the services, staging or automatic renewal. Changing the services or staging issues a new certificate; turning renewal back on schedules the one that is due
Stop renewals	After “Stop certificate renewals?” it stops issuing and renewing: “Renewals stopped. The certificate stays on the controller until it expires or you replace it there.”

A failed run is retried after 1 hour, then 4 hours, then 12 hours, then every 24 hours.

What do the status chips mean?

Chip	Meaning
issuing now	A run is in progress
waiting to issue	Enabled, but no certificate has been issued yet
installed	A certificate is in service
installed (staging)	A staging certificate is in service; browsers do not trust it
expires soon	Less than 14 days of validity left
renewal failing	The last run failed and an earlier certificate is still in service
issuance failing	The last run failed and no certificate has been issued yet
expired	The certificate has expired

The card also shows the certificate’s Name, Valid until, Services, Next run (“not scheduled (automatic renewal is off)” when renewal is off) and Approved by. After a run, Show last run shows its step-by-step log.

What stops renewals?

Anything that removes the approval or the route to the controller. When a run finds one of these, it switches automatic renewal off and records why:

Cause	Recorded error
The approving admin left the organisation	the admin who enabled it is gone; an admin needs to enable it again
The approving admin is no longer an admin	the person who enabled it is no longer an admin of this organisation; an admin needs to enable it again
The tunnel was removed	the controller tunnel was removed
The tunnel hostname changed	the tunnel hostname changed to <hostname>; enable it again
The controller login no longer uses the tunnel	the controller login does not use the tunnel; use the tunnel for the login first

To resume once the cause is fixed, an admin turns Renew automatically back on and clicks Save, which makes them the approving admin.

What errors can I see?

A failed run shows “Last attempt … failed: …”, naming the step that failed and, for a controller step, what SmartZone answered.

Step in the error	What failed
csr	The controller refused to create the key and CSR
csr_download	The CSR could not be read back from the controller
acme	Let’s Encrypt did not issue the certificate
import	The controller refused the signed certificate
services	The controller did not switch the chosen services to the new certificate

Controller steps read like import: SmartZone answered 422: …. Errors from the card’s buttons appear as Error: …:

Code	Message
login_not_tunnel	Use the tunnel for the controller login first: the certificate is installed through it.
running	A certificate is being issued now. (on Stop renewals: …; try again in a few minutes.)
rate_limited	More than 3 Renew now clicks in a day

Next steps

Controller tunnel Set up the tunnel the certificate is issued for and installed through.

Controller requirements The certificate a controller needs when SZ-MCP reaches it directly.

Security model What SZ-MCP stores and what it sends to the controller.