Skip to content

Trusted HTTPS for the OPNsense Web UI with Let's Encrypt

Updated

Overview

This guide shows you how to replace the OPNsense Web UI's self-signed certificate with a trusted Let's Encrypt certificate and configure automatic renewal—without exposing the administration interface to the internet.

A self-signed certificate already encrypts the connection. What changes here is identity verification: your browser can verify that the certificate belongs to the hostname you opened, without a certificate warning. This does not replace management firewall rules, strong authentication, or a VPN for remote administration.

Prerequisites

  • An OPNsense installation with working HTTPS administration and administrator access.
  • A domain you control, with public authoritative DNS hosted by a provider supported by the ACME Client plugin. The provider hosting the DNS zone matters—not necessarily the company where you registered the domain.
  • Credentials that let the plugin create and remove challenge TXT records in that zone. Use a dedicated credential with the narrowest permissions your provider supports. Some providers cannot restrict credentials to a single zone; understand that exposure before storing them on the firewall.
  • Internal DNS that resolves your chosen hostname to OPNsense's management IP.
  • Working outbound connectivity from OPNsense to the ACME service and DNS provider API, functional DNS resolution, and correct system time.
  • A current configuration backup and working console access in case a Web UI change locks you out. Protect backups because they can contain private keys and DNS credentials.

This guide is provider-independent: use any DNS provider with a supported DNS-01 integration in your installed ACME Client plugin. Only the provider selection and authentication fields differ; certificate issuance, Web UI configuration and renewal follow the same steps. Not every DNS provider offers a compatible API, so check support before starting.

All values below are examples; replace them with your own:

Setting Example
Publicly registered domain example.com
Web UI hostname opnsense.home.example.com
Internal management IP 192.168.10.1
ACME account name letsencrypt-prod
Challenge name dns-validation
Automation name restart-webui

How DNS-01 works

The ACME client proves control of your hostname by creating a temporary public TXT record at:

_acme-challenge.opnsense.home.example.com

Let's Encrypt queries that record through public DNS. Once validation succeeds, the client obtains a certificate and removes the challenge record.

Your browser uses a different DNS answer: the Web UI hostname resolves internally to the firewall's private IP. You do not need a public A or AAAA record pointing at the firewall, and Let's Encrypt does not need to connect to its Web UI. The challenge TXT record must be publicly resolvable; an internal-only record is not enough.

Public certificates also publish their names in Certificate Transparency logs. Choose a hostname you are comfortable disclosing. If you cannot use a publicly registered domain or do not want public certificate names, a private CA with its root installed on your devices is an alternative.

Steps

1. Prepare the internal hostname

In the DNS resolver used by your management clients, create a local record or host override:

opnsense.home.example.com → 192.168.10.1

If clients use OPNsense's Unbound resolver, configure the entry under Services → Unbound DNS → Overrides. If they use another DNS server, add it there instead. Do not change the firewall's system hostname just to add this management name.

From a management client, check the lookup:

nslookup opnsense.home.example.com

It should return the management IP. Open https://opnsense.home.example.com and confirm that it reaches your existing Web UI; the certificate warning is expected until the new certificate is applied.

If OPNsense rejects the new name with a rebinding/referrer warning, add that exact hostname under System → Settings → Administration → Alternate Hostnames. Keep the security checks enabled rather than disabling them globally. If your DNS resolver itself blocks the private-IP answer, use its narrowly scoped local override or exception.

Leave existing management rules, listener interfaces and HTTPS port unchanged. This guide assumes the default HTTPS port; if yours differs, include it in browser URLs and TLS checks.

2. Install and enable the ACME Client

  1. Open System → Firmware → Plugins.
  2. Find and install os-acme-client.
  3. Open Services → ACME Client → Settings.
  4. Enable Enable Plugin and Auto Renewal, then apply the settings.

Global auto renewal alone is not enough: the individual certificate must also have renewal enabled, and its renewed certificate must be loaded by the Web UI.

3. Register a Let's Encrypt account

Under Services → ACME Client → Accounts, add an account:

Field Value
Enabled Yes
Name letsencrypt-prod
E-Mail Address An email address you monitor
ACME CA Let's Encrypt production, not the Test CA

Save, then use Register account. Check the account status/log before proceeding.

For repeated experiments, use a separate account with Let's Encrypt Test CA to avoid production rate limits. Its certificates are intentionally not browser-trusted; do not deploy one as your final Web UI certificate. Use the production account for the final issuance.

4. Configure the DNS-01 challenge

Under Services → ACME Client → Challenge Types, add a challenge:

Field Value
Enabled Yes
Name dns-validation
Challenge Type DNS-01
DNS Service The supported integration for your authoritative DNS provider
Provider-specific fields The credentials and identifiers required by that integration
DNS Sleep Time Use the integration's recommended/default value; adjust if propagation requires it

Select the provider that hosts your public authoritative DNS zone, not your internal resolver or simply your domain registrar. Use a supported integration rather than a deprecated or unsupported entry.

After selecting DNS Service, fill in the fields shown for that integration. Depending on the provider, these may include an API token, an API key and secret, an account/customer ID, or a zone ID. There is no universal credential combination: follow the selected integration's help and the provider's API documentation. Match the credential type and API version to the integration bundled with your installed plugin.

Create a dedicated credential in your DNS provider's control panel. Grant the permissions required to find the zone and create/remove TXT records, limited to the intended zone where supported. A token with DNS write access but no required zone-read permission can still fail. Avoid a global account key if a scoped token is supported, and never put real credentials into screenshots, guide examples or shared logs.

DNS Sleep Time gives the public TXT record time to propagate before validation; it is not the certificate renewal interval. Start with the integration's documented recommendation. If validation runs before the TXT record is publicly visible, increase the wait based on the observed propagation delay rather than copying a value from another provider. Save the challenge.

If your provider is absent from the supported integrations or offers no suitable API, this direct automatic-renewal workflow does not apply as written. Use a supported authoritative DNS host, or a documented DNS-01 delegation setup with a supported validation service. Delegation requires additional configuration and is outside this walkthrough; do not substitute manual TXT updates and expect unattended renewal.

5. Create the Web UI restart automation

Under Services → ACME Client → Automations, add:

Field Value
Enabled Yes
Name restart-webui
Run Command Restart OPNsense Web UI

Save. This action lets the Web UI load the renewed certificate. Issuing a new certificate does not by itself prove that the running Web UI is serving it. Expect a brief administration interruption when the restart runs; plan around that if you manage the firewall remotely.

6. Request the certificate

Under Services → ACME Client → Certificates, add:

Field Value
Enabled Yes
Common Name opnsense.home.example.com
ACME Account letsencrypt-prod
Challenge Type dns-validation
Auto Renewal Enabled
Automations restart-webui

Show advanced settings if needed to select the automation. Leave key and renewal defaults unless you have a specific compatibility requirement. You do not need a wildcard certificate or extra alternative names for this single Web UI hostname.

Save, then select Issue/renew certificate. Allow time for the configured DNS wait; do not repeatedly click issuance while a request is running.

Check the certificate status and ACME Client → Log Files. Continue only after issuance succeeds. If it fails, diagnose the reported error before retrying. A restart at this stage may still load the old certificate because you have not selected the new one for the Web UI yet.

7. Apply the certificate to the Web UI

  1. Open System → Settings → Administration.
  2. Keep Protocol set to HTTPS.
  3. Under SSL Certificate, select the certificate issued for opnsense.home.example.com.
  4. Save/apply. Keep console access available while the Web UI restarts.
  5. Reopen https://opnsense.home.example.com in a fresh browser connection.

Verify that there is no certificate warning and inspect the browser's certificate details: the hostname must be covered, the chain trusted, and the validity dates current. Opening the IP address will normally still produce a name mismatch—the certificate is for the DNS name, not the private IP.

Optionally verify HTTPS from a management client with curl:

curl --head https://opnsense.home.example.com/

Expect an HTTP response without a TLS verification error; a redirect to the login page is normal. Do not use -k/--insecure: that would disable the check you are trying to perform. Browser and curl trust stores can differ, so use the browser check as well.

8. Verify renewal and certificate deployment

Recheck all three pieces of the renewal chain:

  • ACME Client → Settings: plugin and global auto renewal enabled.
  • Certificates: this certificate enabled, auto renewal enabled, and restart-webui selected.
  • Administration: the Web UI still uses this ACME-managed certificate.

Keep the DNS credential valid and leave the plugin enabled. Record the served certificate's expiry and serial number so you can compare after renewal. Do not hard-code a certificate lifetime or blindly change renewal intervals; use the supported defaults for your installed version and monitor the actual validity dates.

A manual renewal can check the issuance/deployment path when appropriate, but repeated forced production requests risk rate limits. A request that is skipped because renewal is not due is not evidence of a successful renewal. To claim unattended renewal verified, observe a scheduled renewal, confirm success in the ACME logs, and confirm that a new browser connection receives the renewed certificate with updated serial/validity dates. Check before the old certificate expires rather than discovering a failed renewal during an outage.

Troubleshooting

Symptom Check
Hostname does not reach the firewall Resolve it from the affected client. Check its DNS server, local override, management rule, and any unintended AAAA record. Certificate issuance does not create internal DNS records.
DNS API authentication fails Verify the selected authoritative DNS provider, supported integration, credential type/API version, zone identifiers and required read/write permissions. Check token expiry and any API source-IP restrictions.
TXT validation times out Check the public authoritative zone, TXT propagation and the ACME log. An internal-only TXT answer is insufficient. Increase the wait only if propagation is the cause.
A challenge exists publicly but local lookup fails Check the resolver OPNsense itself uses. Split DNS must not hide the public _acme-challenge record from the ACME client; fix that lookup/forwarding path rather than publishing the Web UI.
ACME reports a CAA restriction Check applicable public CAA records and whether they permit Let's Encrypt. Do not remove unrelated policy blindly.
Browser reports an untrusted issuer Confirm production issuance, not the Test CA, and inspect the served certificate chain and client trust store.
Browser reports the wrong hostname or old certificate Use the exact certificate hostname. Check the selected SSL certificate, Web UI restart and whether DNS reaches a different server. Reconnect before inspecting again.
Issuance succeeds but the Web UI certificate expires Check the attached automation and Web UI certificate selection. Compare the certificate served by the Web UI with the renewed one, not just the plugin's success message.
ACME fails before DNS validation Check firewall-originated DNS, outbound connectivity, system time and the precise log error. Client internet access alone does not prove the firewall can reach the APIs.
Web UI rejects the management hostname Add the exact Alternate Hostname; do not disable rebinding/referrer checks globally.

To inspect public DNS during a running challenge, use a terminal with dig installed:

dig NS example.com
# Replace ns1.provider.example with an authoritative server from the answer above.
dig @ns1.provider.example TXT _acme-challenge.opnsense.home.example.com

The TXT value should be visible on the authoritative servers during validation. Its absence after successful cleanup is normal. Query the actual delegated zone if your challenge name sits below a delegated subdomain. Treat full ACME logs as potentially sensitive; redact them before sharing.

Recovery

If the new certificate causes a problem while the Web UI remains reachable, select the previous known-good certificate under Administration, keep HTTPS enabled, and save/apply. Preserve the previous certificate until the new setup is verified.

If the Web UI is inaccessible, use the console recovery path prepared before starting. Recover the known-good configuration if necessary, understanding that a full restore can revert other changes as well. An alternate IP URL is not a guaranteed recovery path: hostname mismatches and HSTS can prevent access. Do not open WAN administration or switch to HTTP to work around a TLS problem.

If you abandon this setup, detach the restart automation and disable renewal for this certificate, then revoke the dedicated DNS API credential when nothing else needs it. Do not delete a certificate that the Web UI is still configured to use.

Completion checklist

  • Internal management DNS resolves to the intended firewall IP.
  • Production certificate issued successfully through DNS-01.
  • Web UI serves the certificate with a trusted chain and matching hostname.
  • Management access remains private; no WAN opening was added for validation.
  • Global and certificate-level renewal are enabled, with the Web UI restart automation attached.
  • Scheduled renewal and deployment of the renewed certificate observed and verified.

Sources

Keep exploring

Browse more on these topics, or compare notes with the community. Guides and videos stand on their own.

Discord community

Build, break, and learn together.

Talk homelabs, self-hosting, and automation with people building this stuff. This is a community, not personal support.

Join Discord(opens in a new tab)