TrueNAS SSL Certificate: Replacing the Self-Signed Certificate in TrueNAS CORE and SCALE

TrueNAS ships with a self-signed certificate and shows a browser warning every time you open the web UI. The warning is dismissible, but it also means you cannot verify you are connected to the real TrueNAS system and not an impostor — important for NAS devices that may hold backup data or sensitive files. This article covers replacing the TrueNAS self-signed certificate with a trusted one using Let’s Encrypt (via ACME DNS challenge), an internal CA, or a manually issued certificate.

TrueNAS certificate storage

TrueNAS stores certificates in its internal database (managed through the UI or API). Certificates are not files on disk that you edit directly — you import them through the UI or the TrueNAS CLI, and then assign them to services.

The web UI certificate is separate from:

• iSCSI TLS (configured per target)
• S3/MinIO TLS (TrueNAS SCALE)
• FTP TLS
• LDAP client certificates

This article covers the web UI certificate.

Option A: Let’s Encrypt via ACME DNS challenge (recommended)

This method works even when your TrueNAS is not publicly reachable on port 80, which is the common case for a home or office NAS. It uses DNS TXT records for domain validation.

Requirements

• A domain name you control (e.g., nas.example.com)
• A DNS provider supported by TrueNAS’s ACME client (TrueNAS supports Cloudflare, Route53, OVH, Namecheap, and others)
• Port 80 does NOT need to be open

TrueNAS SCALE (Dragonfish and later)

1. Go to System → Certificates → ACME DNS Authenticators.
2. Click Add, select your DNS provider (e.g., Cloudflare).
3. Enter the required credentials (e.g., Cloudflare API token with Zone:DNS:Edit permission).
4. Save.

Now create the certificate:

1. Go to System → Certificates.
2. Click Add.
3. Set Type to ACME Certificate.
4. Fill in:

• Name: truenas-lets-encrypt
• Domains: nas.example.com
• ACME Server Directory URI: https://acme-v02.api.letsencrypt.org/directory
• Terms of Service: accept
• Authenticator: select the DNS authenticator you created

1. Click Save. TrueNAS creates a DNS TXT record, waits for propagation, and then downloads the signed certificate.

Assign the certificate to the web UI:

1. Go to System → General Settings → GUI.
2. Set Certificate to the new certificate.
3. Click Save. The browser will reload with the new certificate.

TrueNAS CORE (12.x and 13.x)

1. Go to System → ACME DNS.
2. Add your DNS provider credentials.
3. Go to System → Certificates → Add.
4. Type: ACME Certificate.
5. Fill in domain, ACME server, DNS authenticator.
6. Save.
7. Go to System → General.
8. Set the GUI SSL Certificate to the new certificate.
9. Save.

---

Option B: Importing a certificate from an internal CA or external provider

If you have an internal CA or have received a certificate from a provider like Digicert or Sectigo, import it manually.

Step 1: Prepare the certificate files

You need:

• The certificate in PEM format (including the full chain — intermediate + leaf)
• The private key in PEM format (unencrypted)

If you have a PFX/PKCS12 file:

# Extract certificate and key from PFX
openssl pkcs12 -in certificate.pfx -clcerts -nokeys -out cert.pem
openssl pkcs12 -in certificate.pfx -nocerts -nodes -out key.pem

If you have separate leaf and intermediate files, concatenate them:

cat leaf.crt intermediate.crt > fullchain.pem

Step 2: Import via TrueNAS UI

TrueNAS SCALE:

1. Go to System → Certificates → Add.
2. Set Type to Import Certificate.
3. Paste the certificate (full chain) into Certificate.
4. Paste the private key into Private Key.
5. Give it a name (e.g., nas-internal-ca-2024).
6. Click Save.

TrueNAS CORE:

1. Go to System → Certificates → Add CA (if you have a CA to import) or Add for a certificate.
2. Select Import Certificate.
3. Paste the certificate and key.
4. Save.

Step 3: Assign the certificate

1. SCALE: Go to System → General Settings → GUI → Certificate → select the imported certificate → Save.
2. CORE: Go to System → General → GUI SSL Certificate → select the imported certificate → Save.

The web UI restarts and serves the new certificate.

---

Option C: TrueNAS API certificate import (automation)

For scripted or automated deployments, use the TrueNAS REST API:

# Get the current certificates
curl -s -k -u admin:password https://truenas.example.com/api/v2.0/certificate | python3 -m json.tool

# Import a new certificate
curl -s -k -u admin:password \
  -X POST https://truenas.example.com/api/v2.0/certificate \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "create_type": "CERTIFICATE_CREATE_IMPORTED",
  "name": "new-cert-2024",
  "certificate": "$(cat /etc/ssl/certs/nas-fullchain.pem | sed ':a;N;$!ba;s/\n/\\n/g')",
  "privatekey": "$(cat /etc/ssl/private/nas.key | sed ':a;N;$!ba;s/\n/\\n/g')"
}
EOF

# Get the certificate ID from the response
CERT_ID=<id from response>

# Set it as the GUI certificate
curl -s -k -u admin:password \
  -X PUT https://truenas.example.com/api/v2.0/system/general \
  -H "Content-Type: application/json" \
  -d "{\"ui_certificate\": ${CERT_ID}}"

# Reload the UI
curl -s -k -u admin:password \
  -X POST https://truenas.example.com/api/v2.0/system/general/ui_restart

---

Automating Let’s Encrypt renewal on TrueNAS SCALE

TrueNAS SCALE handles ACME certificate renewal automatically. The certificate is renewed when it has fewer than 10 days of validity remaining. You do not need to create a cron job for this.

To check renewal status, look at System → Certificates — the expiry date updates automatically after renewal.

---

Certificate renewal with external scripts (for manually imported certs)

If you manage certificates externally (from a different server), set up a renewal pipeline that pushes the new certificate to TrueNAS via the API:

#!/bin/bash
# Run this on your certificate management server after renewal

TRUENAS_HOST=https://nas.example.com
TRUENAS_USER=admin
TRUENAS_PASS="your-api-password"
CERT_NAME="external-cert-$(date +%Y%m)"
CERT_FILE=/etc/letsencrypt/live/nas.example.com/fullchain.pem
KEY_FILE=/etc/letsencrypt/live/nas.example.com/privkey.pem

CERT=$(cat ${CERT_FILE} | python3 -c "import sys; print(sys.stdin.read().replace('\n','\\n'))")
KEY=$(cat ${KEY_FILE} | python3 -c "import sys; print(sys.stdin.read().replace('\n','\\n'))")

# Import new certificate
CERT_ID=$(curl -s -k -u "${TRUENAS_USER}:${TRUENAS_PASS}" \
  -X POST "${TRUENAS_HOST}/api/v2.0/certificate" \
  -H "Content-Type: application/json" \
  -d "{\"create_type\":\"CERTIFICATE_CREATE_IMPORTED\",\"name\":\"${CERT_NAME}\",\"certificate\":\"${CERT}\",\"privatekey\":\"${KEY}\"}" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")

echo "Imported certificate ID: $CERT_ID"

# Set as GUI certificate
curl -s -k -u "${TRUENAS_USER}:${TRUENAS_PASS}" \
  -X PUT "${TRUENAS_HOST}/api/v2.0/system/general" \
  -H "Content-Type: application/json" \
  -d "{\"ui_certificate\": ${CERT_ID}}"

# Restart the UI to apply
curl -s -k -u "${TRUENAS_USER}:${TRUENAS_PASS}" \
  -X POST "${TRUENAS_HOST}/api/v2.0/system/general/ui_restart"

echo "Certificate rotation complete"

---

Using the TrueNAS hostname for the certificate

If your TrueNAS is only accessible by IP address and you want to avoid a certificate warning without a real domain name:

1. Use a wildcard certificate for your internal domain (e.g., *.example.internal) if you have one.
2. Add a local DNS record: nas.example.internal → TrueNAS IP.
3. Issue a certificate for nas.example.internal from your internal CA.
4. Deploy it to TrueNAS using the import method above.

The certificate CN/SAN must match exactly what you type in the browser address bar.

---

Troubleshooting

Problem	Cause	Fix
Browser still shows old cert after saving	Browser caching TLS state	Hard-refresh with Ctrl+Shift+R or open incognito
ACME order fails	DNS TXT record not propagating	Increase TTL on DNS zone; wait longer; check DNS provider API credentials
Certificate chain is not complete	Only leaf cert imported, no intermediate	Concatenate intermediate + leaf before importing
TrueNAS UI rejects the private key	Key is encrypted (has Proc-Type: 4,ENCRYPTED header)	Decrypt: openssl rsa -in encrypted.key -out decrypted.key
Cert mismatch warning	Certificate CN/SAN does not match URL	Issue cert for the exact hostname or IP (add IP SAN)

---

Summary

TrueNAS certificate replacement is done entirely through the web UI or API — there are no files to copy manually. For internet-connected or DNS-accessible deployments, use the built-in ACME client with a DNS challenge authenticator. For internal CA or externally-managed certificates, use the Import Certificate option. After importing, assign the certificate in System → General Settings → GUI. For automated rotation, the TrueNAS REST API accepts new certificates and can restart the web UI without SSH access.