Remote Support Start download

TrueNAS with Let's Encrypt: Automating SSL Certificates for UI, WebShare, and Apps

TrueNASLetsEncryptSSL
TrueNAS with Let's Encrypt: Automating SSL Certificates for UI, WebShare, and Apps

A TrueNAS is rarely “just a file server” in practice. The web UI runs over TLS, WebShare delivers browser-based file drops to customers, and apps such as Nextcloud, MinIO, or Syncthing sit alongside — each of those surfaces eventually presents a certificate to a user. When the default self-signed certificate shows, the browser warning follows. When a certificate expires, replication jobs may stall silently. This article walks through how we pull a Let’s Encrypt wildcard certificate via ACME in TrueNAS 25.10 Goldeye, assign it to the right services, and keep renewals running for years — no downtime, no manual reminders, no browser warnings.

If you have never run through an ACME flow yourself, start with our foundational piece Automating Let’s Encrypt certificates with ACME. The article you are reading now goes one level deeper into TrueNAS specifics: the ACME dialog in the UI, the DNS authenticators, the role of the WebShare config, and how to swap a certificate for apps without a service restart.

Why TrueNAS needs Let’s Encrypt

TrueNAS ships with a pragmatic default: during install it generates a self-signed certificate so the web UI is reachable over HTTPS at all. That is enough to bring a system up — but not enough for day-to-day production. Three reasons speak against the default certificate:

Browser warnings train users badly. If “Advanced > Proceed anyway” becomes muscle memory, nobody will catch the day a certificate warning actually means something is wrong. It becomes especially awkward on TrueNAS WebShare, where external customers pick up files via browser — they do not want to see a certificate warning.

Replication and integrations break when certificates expire. TrueNAS-to-TrueNAS replication, S3 integrations for backup tools, and monitoring agents validate certificates more strictly than browsers do. An expired certificate on the target stops replication.

Certificate rotation is now a compliance topic. 90-day certificate lifetimes are standard in regulated industries, and since September 2026 the CA/B Forum decision has pushed the industry toward even shorter lifetimes. Teams that rotate manually will miss that cadence sooner rather than later.

The clean answer is Let’s Encrypt via ACME with a DNS-01 challenge, bound to every TLS-exposed service on the TrueNAS.

Prerequisites before the ACME setup in TrueNAS

Before opening the ACME dialog in TrueNAS, three topics deserve attention — they tend to cause the headaches later:

DNS under your own control. Wildcard certificates only work via the DNS-01 challenge. For that, TrueNAS needs API access to the DNS provider — specifically to a zone where a TXT record _acme-challenge.<domain> can be written. Cloudflare, Route53, Hetzner and a handful of others are supported directly as TrueNAS authenticators. If your DNS lives at a provider without an API, DNS-01 is a dead end — in that case consider migrating the zone to an API-capable provider or routing through HTTP-01 at an upstream reverse proxy.

Reverse proxy decision. TrueNAS does not include an HTTP-01 validator on an external port 80. Teams that prefer HTTP-01 over DNS-01 need an upstream reverse proxy that answers the challenge and forwards the certificate to TrueNAS. In many DATAZONE setups an OPNsense with os-acme-client sits in front — we described the flow in HAProxy and Let’s Encrypt for multi-domain setups on OPNsense. For internal-only NAS, DNS-01 is the better fit.

Naming scheme pinned up front. Which hostnames belong on the certificate? nas.company.com for the UI, share.company.com for WebShare, nextcloud.company.com for an app — or all of it covered by a wildcard *.company.com? Wildcards are convenient but do not fit every compliance posture. For most SMB setups we issue a wildcard plus the apex domain in a single request.

ACME in TrueNAS 25.10 Goldeye

TrueNAS 25.10 Goldeye is the current stable release — the ACME configuration is a bit cleaner than in older CORE versions, but the structure is the same. Four logical steps that come together under Credentials > Certificates:

  1. Create an ACME DNS authenticator. Under ACME DNS Authenticators > Add, choose the provider (for example Cloudflare) and paste in the API token. For Cloudflare, the token only needs Zone.DNS:Edit on the specific zone — nothing more. Route53 requires classic AccessKey/SecretKey from an IAM user with route53:ChangeResourceRecordSets on the matching hosted zone.

  2. Register an ACME account. TrueNAS offers a Create ACME Account button. Enter an email address (Let’s Encrypt uses it for expiry warnings on failing renewals) and register the account with Let’s Encrypt. For production, the Production directory URL is correct; for first tests, use Staging.

  3. Generate a CSR. Under Certificates > Add > Certificate Signing Request, create a CSR: common name is one hostname (for example nas.company.com); under Subject Alternate Names add every other hostname and the wildcard entry (*.company.com). Key length 4096 or EC secp384r1 — clients handle both reliably.

  4. Request the ACME certificate. From the CSR entry, click Create ACME Certificate, assign the authenticator from step 1 to every FQDN, and submit. TrueNAS now triggers the DNS-01 challenge: for each hostname a TXT record _acme-challenge.<host> is placed at the DNS provider, Let’s Encrypt validates, the record is cleaned up, the certificate lands in the TrueNAS certificate store.

Real-world timing: 30 to 120 seconds for the first run, depending on how fast the DNS provider propagates TXT records. If the process hangs, check System > Advanced > Save Debug — the ACME logs live there.

DNS challenge providers at a glance

ProviderMinimum API scopeNote
CloudflareZone.DNS:Edit on the specific zoneToken-based, fast propagation
AWS Route53route53:ChangeResourceRecordSets, hosted zone IDDedicated IAM user with its own access key
Hetzner DNSAPI token on the projectThinly documented but reliable
OVHcloudConsumer key plus app keySetup is more complex; permissions via the OVH console
INWXAPI user plus passwordFits smaller SMB zones well

If your DNS provider is not shipped as a TrueNAS authenticator, in practice the most stable fallback is to run an external ACME client (acme.sh or certbot) on an OPNsense or a small Debian host and import the resulting certificate into TrueNAS via API. More on that below.

Assigning the certificate to UI, WebShare, and apps

The certificate is in the store — and so far not in use anywhere. In TrueNAS there are three places where that assignment happens:

Web UI. Under System > General > GUI SSL Certificate, pick the new certificate and save. TrueNAS reloads the UI’s nginx — the current session is interrupted for two to four seconds, after which the UI is served with the Let’s Encrypt certificate. For clusters built on a TrueNAS 3-node pattern this is a per-node operation; we recommend doing the swap outside the production window.

WebShare. Under Shares > WebShare the certificate selector is per WebShare instance. Important: the FQDN that the certificate covers has to match the hostname users reach WebShare through — not the internal TrueNAS hostname. Teams that run WebShare and UI under different hostnames (share.company.com vs nas.company.com) pay for that comfort with the certificate having to cover both names — either as a wildcard or as a multi-SAN certificate. We walked through practical cases in WebShare vs Nextcloud for file sharing.

Apps. Since 25.10 Goldeye, TrueNAS Apps use a consistent model: every app that terminates TLS has a reference in its manifest to a certificate from the TrueNAS certificate store. For Nextcloud, Syncthing, MinIO, or a custom reverse proxy this means: open Edit on the app, pick the Let’s Encrypt certificate under Network Configuration > Certificate, save. Depending on the app the container restarts or just reloads its TLS config. Which apps live in which mode is covered in TrueNAS App catalog for SMB production.

Replication tasks and S3 target usage. Easy to miss: if TrueNAS itself acts as an S3 target for a backup tool or as a replication endpoint with WebSocket TLS, those pull from the same certificate store. After a swap, double-check the binding still points at the current certificate.

Renewal automation that stays current

Let’s Encrypt issues certificates with a 90-day lifetime and recommends renewing from day 60. TrueNAS handles this automatically once the ACME flow above has run once:

  • Scheduler. TrueNAS checks daily (overnight by default) whether a certificate has less than 30 days remaining. If so, it reruns the ACME flow and replaces the certificate.
  • Service reload. For the web UI an nginx reload is enough — that is wired into TrueNAS. For apps the behavior depends on how the TLS terminator is wired: either the terminator reloads or the container restarts. WebShare picks up the new certificate without a restart.
  • Alerting. If a renewal fails (for example because the DNS provider token expired), the error lands in the TrueNAS alert system. We strongly recommend hooking up mail alerting — a silent renewal failure is the single most common reason certificates still expire despite automation.

For genuinely critical systems we add an external monitor that checks remaining lifetime via openssl s_client on a weekly basis and opens a ticket if the number drops below 20 days. That is fallback logic, not a replacement for the TrueNAS automation — it only catches the case where four earlier layers all failed.

External ACME client as a fallback

Not every DNS provider is integrated into TrueNAS, and some compliance regimes require the ACME client to live outside the storage system. For those cases, the clean fallback looks like this:

  1. Run an ACME client on an OPNsense (os-acme-client plugin) or a small Linux host (acme.sh or certbot).
  2. Configure the DNS challenge there against the desired provider — the provider list for acme.sh is much broader than inside TrueNAS.
  3. After a successful issue, push the certificate into TrueNAS via a deploy hook that calls the REST API (/api/v2.0/certificate). Since 25.10 a WebSocket endpoint with TLS auth is also available.
  4. In the same deploy script, trigger the assignment to UI, WebShare, and apps via API. TrueNAS reloads the affected services on its own.

We rely on this pattern mainly when the NAS itself has no internet access (an isolated back-end VLAN) or when policy mandates certificates live on a central ACME host.

Common pitfalls and how we avoid them

After roughly two years of Let’s Encrypt practice on TrueNAS systems, a short list of recurring issues keeps coming up:

Forgotten token rotation. A Cloudflare or Route53 token expires after 12 months — Let’s Encrypt renewal fails silently. Fix: hook token rotation into the same cadence as other secret rotations, or use tokens without expiry where that is acceptable.

Wrong hostname on WebShare. Users hit share.company.com, but the certificate only covers nas.company.com. The browser refuses. Verification point: compare the SAN list of the certificate against every hostname actually in use.

App container with a stale certificate. After a renewal the UI reverse proxy picks up the fresh certificate, but an app container does not — it only reads the certificate at startup. Fix: configure the app for automatic reload on certificate change, or plan a manual app restart in the maintenance window around the renewal.

Replication task hangs. TrueNAS-to-TrueNAS replication validates certificate chains more strictly than browsers. When the target certificate is replaced by a Let’s Encrypt certificate, the replication config needs to revalidate — sometimes Edit > Save is enough, sometimes the trust store on the source needs a refresh.

Wrong network window for DNS-01. If the NAS has no outbound DNS (which happens in strongly segmented networks), its ACME client cannot write TXT records. Fix: either open outbound DNS for the NAS, or move to the external ACME client described above.

When DATAZONE handles this for you

For small setups with a handful of hostnames, the ACME setup in TrueNAS is a one-hour job. It gets more involved when several TrueNAS systems share a certificate, when a dedicated reverse proxy sits in front, or when compliance pushes certificate issuance to a central authority. Our TrueNAS configurator sizes systems including HA pairs, and through TrueNAS Support we accompany rollouts where Let’s Encrypt has to play nicely with AD integration, replication, and the app catalog. As an authorized iXsystems partner we have the vendor channels when the automation hits an edge case.

FAQ: TrueNAS and Let’s Encrypt

Is the default TrueNAS certificate good enough for internal use?

For first-time install, yes. For production, no. Browser warnings train users to ignore certificate alerts, and replication plus S3 usage grows unreliable with expired certificates. By the time WebShare or apps face outward, Let’s Encrypt should be in place.

Does Let’s Encrypt work on a NAS without internet access?

With HTTP-01, no. With DNS-01, yes — assuming the NAS can reach the Let’s Encrypt API and the DNS provider outbound. If that is not available, run the ACME client elsewhere and import the certificate into TrueNAS via API.

What happens if the automatic renewal fails?

TrueNAS logs the error in the alert system and retries the next day. Because Let’s Encrypt starts renewals at 60 days of remaining lifetime, roughly 30 days remain before the certificate truly expires. Enabling mail alerting is the single most important step to keep a failure from going unnoticed for weeks.

Wildcard certificate or one per service?

Wildcards are convenient and reduce rotation overhead. Regulated industries sometimes require a dedicated certificate per service — the admin burden grows, but isolation is tighter. For most SMB setups a wildcard plus the apex domain is a good trade-off.

Will the ACME flow in TrueNAS 25.10 Goldeye carry over to TrueNAS 27?

Current signs say yes — iXsystems has not rebuilt the ACME logic for 27, only polished the existing UI. TrueNAS 27 GA is scheduled for early December 2026; for production, we currently recommend sticking with 25.10 Goldeye and upgrading to 27 in the first quarter of 2027, once the initial patch releases are out.

What about CA pinning in clients?

If you still have clients that will not accept a swapped certificate — old backup agents with hard-coded fingerprints, say — tie the renewal to a planned client rollout. In those cases it is worth discussing whether the client can move to a modern CA-based trust model; CA pinning on 90-day certificates is not sustainable in practice.

More on these topics:

Plan your TrueNAS sizing live
Translate this article straight into a concrete configuration: pick model, drives, RAID level and networking — and get the resulting capacity in real time.
Configure now

Need IT consulting?

Contact us for a no-obligation consultation on Proxmox, OPNsense, TrueNAS and more.

Get in touch