TrueNAS Scale Certificates
Overview
Add additional certificates to use for the web GUI on TrueNAS Scale.
Assumptions
TrueNAS Scale Setup completed.
Logged in as administrative user.
DNS Authenticator
Add a new DNS authenticator for LetsEncrypt to use when generating a certificate for the domain. TrueNAS Scale supports Cloudflare, Route53, and OVH with simple configuration. Alternatively, a shell script can be used with any providers.
Cloudflare API Token
Create an API token to interact with a Cloudflare Zone.
Navigate to the My Profile page and select the API Tokens tab.
Select Create Token. Configure the token with permission to edit Zone DNS. Only allow access to the zone resource required.
| Setting | Value | Description |
|---|---|---|
| Token Name | example-api-token | Choose a name to identify the token. |
| Permissions | Zone - DNS - Edit | Grant edit permissions for zone DNS. |
| Zone Resources | Include - Specific - example.com | Only include the zone that will utilize the token. |
Continue to summary and review the configuration, select Create Token.
When presented, copy the generated Cloudflare API token.
Add Authenticator
Navigate to the TrueNAS Certificates dashboard, found under Credentials in the menu.
From the Certificates dashboard, select Add in the ACME DNS-Authenticators section. Configure the authenticator with the generated API token from the DNS provider.
| Setting | Value | Description |
|---|---|---|
| Name | cloudflare-acme | Authenticator identifier. |
| Authenticator | cloudflare | DNS provider to use for ACME challenges. |
| Cloudflare Email | | Leave blank when using API token. |
| API Key | | Leave blank when using API token. |
| API Token | GeneratedCloudflareAPIToken | API token with DNS edit permissions for the domain. |
Certificate Signing Request
From the Certificates dashboard, select Add in the Certificate Signing Requests section. Configure the signing request for the domain of choice, truenas.example.com.
| Setting | Value | Description |
|---|---|---|
| Identifier and Type | — | — |
| Name | letsencrypt-csr | CSR identifier. |
| Type | Certificate Signing Request | Certificate request type. |
| Profiles | HTTPS RSA Certificate | Template for the request, use RSA for LetsEncrypt. |
| Certificate Options | — | — |
| Key Type | RSA | Algorithm, use RSA for LetsEncrypt. |
| Key Length | 4096 | Select a key length >= 2048. |
| Digest Algorithm | SHA384 | Select a digest algorithm >= SHA256. |
| Certificate Subject | — | — |
| Country | USA | Select local country. |
| State | . | Optional, use period to leave empty. |
| Locality | . | Optional, use period to leave empty. |
| Organization | . | Optional, use period to leave empty. |
| Organizational Unit | | Optional. |
[email protected] | Administrative email for the certificate, will be sent with the request. | |
| Common Name | | System FQDN, optional. |
| Subject Alternative Names | truenas.example.com | When generating a certificate just for TrueNAS to use, specify a hostname. Formerly a wildcard cert that could be used for applications, but that functionality was depreciated. |
| Extra Constraints | — | — |
| Basic Contraints | true | Leave as configured by the ‘Profiles’ definition. |
| Extended Key Usage | true | Leave as configured by the ‘Profiles’ definition. |
| Key Usage | true | Leave as configured by the ‘Profiles’ definition. |
Generate Certificate
With the DNS authenticator and Certificate Signing Request configured, the certificate can now be generated.
Admin Email
TrueNAS requires that an email address be configured for the admin user for an ACME challenege to be initiated.
From the TrueNAS menu, navigate to Credentials, Local Users, and select Edit for the admin user. Assign an email address for the user, [email protected]. Consider using the same email from the signing request.
Create ACME Certificate
Select the wrench icon next to the created certificate signing request, letsencrypt-csr.
Configure the certificate.
| Setting | Value | Description |
|---|---|---|
| Identifier | letsencrypt-cert | Identifier for the certificate. |
| Terms of Service | true | Agree to the LetsEncrypt Terms of Service. |
| Renew Certificate Days | 10 | Days before expiry to renew the certificate. |
| ACME Server Directory URI | Let's Encrypt Production Directory | Select the production or staging directory. Use staging when testing to avoid getting rate-limited. |
| Domains | — | — |
| DNS:truenas.example.com | cloudflare-acme | Select the configured DNS authenticator token. |
Save the certificate configuration and the generation process will begin. This will take a few minutes.
The newly created certificate will show up in the Certificates section of the dashboard.
Configure Web GUI
After generating the certificate, instruct TrueNAS to utilize it for the web GUI.
Navigate to System Settings, General, and select Settings in the GUI section.
Modify the GUI SSL Certificate configuration, switching from truenas_default to letsencrypt-cert.
References
Cloudflare. “Cloudflare API Documentation.” 2024. ↩︎
Let’s Encrypt. “Let’s Encrypt Documentation.” 2024. ↩︎