Integrating Let’s Encrypt TLS Certificates with FreeNAS
FreeNAS has long had the ability to use HTTPS for the web GUI, but that has usually meant dealing with self-signed certificates and the associated headaches, or paying for a commercial certificate. With the launch of Let’s Encrypt in December 2015, trusted TLS certificates became available at no cost. However, their short lifetime, as well as the requirement to use other software tools to issue them, has caused some challenges in integrating them into the FreeNAS web GUI.
With the release of FreeNAS 11.1, the FreeNAS API now has all the hooks needed for a script to automate deployment of a certificate. This resource will describe two methods for obtaining a certificate for your FreeNAS box. It will also describe how to automate deployment of the certificate. The goal is that the certificate will be issued (and renewed) and deployed automatically, and you won’t need to manually deal with it ever again.
Prerequisites
In order to obtain a certificate from Let’s Encrypt, you must own (or at least control) a public domain name–Let’s Encrypt will not issue a certificate for an IP address, nor for a .local domain. You must also be able to prove that you control that domain. Let’s Encrypt supports two methods of proof: either you must demonstrate the ability to change your domain’s DNS records, or you must be able to place a small text file where it can be reached at http://your_domain/.well-known/acme-challenge/pseudorandomstring.
If your DNS host has an API that allows for automated updates, this would be the preferred method, as it doesn’t require opening any outside access to your FreeNAS machine.
Installing acme.sh
Let’s Encrypt only issues certificates through client software that implements the ACME protocol. The “official” client from EFF is certbot, but many others have been developed. This guide will describe the use of acme.sh, a lightweight client that’s written as a shell script, is very flexible, and has very minimal dependencies. acme.sh will register an account with letsencrypt.org, obtain certificates, and call deploy_freenas.py to deploy them to your FreeNAS system.
To install acme.sh, log in to the shell of your FreeNAS box as root, and run curl https://get.acme.sh | sh -s email=you@yourdomain.com (inserting a valid email address). This will download the script, install it in /root/.acme.sh/, and adjust your PATH accordingly. Log out, and log back in.
Installing deploy_freenas.py
deploy_freenas.py is a Python script, based heavily on the work of @gary_1, that uses the FreeNAS API to upload the new certificate into the FreeNAS middleware and set it as the active certificate for the web GUI.
Download the script by changing to a convenient directory (either /root/, or perhaps a dataset where you store scripts), and running git clone https://github.com/danb35/deploy-freenas.
Once you’ve downloaded the script, you’ll need to create a configuration file called deploy_config. The git repo has an example (deploy_config.example) which you can copy and modify, or you can write your own from scratch. In its simplest form, the file would look like this:
[deploy]
password = YourSuperDuperSecureRootPassword
…and contain your FreeNAS root password. If you’re using TrueNAS 12.0, it’s recommended instead that you generate an API key and specify that (rather than your root password) with api_key = 1-DXcZ19sZoZFdGATIidJ8vMP6dxk3nHWz3XX876oxS7FospAGMQjkOft0h4itJDSP. The other parameters are documented in deploy_config.example.
Important: Since the config file contains your root password, make sure it’s only readable by root.
Issuing the certificate
Now it’s time to actually obtain your certificate. As noted above, to prove your ownership of your hostname, you’ll need to either make specified changes to your domain’s DNS records, or be able to respond to a HTTP challenge. The former is preferred if your DNS host supports it.
Using the DNS challenge
Many DNS hosts have APIs, which allow software to automate changes to your DNS records. acme.sh supports many of these DNS hosts, a list of the supported APIs (and how to use them) can be found at dnsapi · acmesh-official/acme.sh Wiki · GitHub. I use Cloudflare for my DNS. It’s free (at this service level), it has a responsive, easy-to-use dashboard, and its API is well-supported by acme.sh.
From the shell prompt, run the following commands:
export CF_Token="Y_jpG9AnfQmuX5Ss9M_qaNab6SQwme3HWXNDzRWs" - This is an API token for your account from Cloudflare; see the acme.sh docs for more information.
.acme.sh/acme.sh --issue -d fqdn_of_freenas_box --dns dns_cf
.acme.sh/acme.sh --install-cert -d fqdn_of_freenas_box --reloadcmd "/path/to/deploy_freenas.py"
If you use a different DNS host, you’ll need to substitute the appropriate credentials, which are documented at the link above. The examples at that link assume you’re using the bash shell, though they’ll also work with zsh, which has been the default root shell on FreeNAS since 11.2. If your root shell is something different like csh, you may need to replace the export with setenv. In that case, the first command above would look like setenv CF_Token "(your cloudflare master API key)". Note the use of “setenv” rather than “export”, and the lack of the = sign.
If all goes as expected, acme.sh will generate an account key, register the account with letsencrypt.org, request the certificate, create the appropriate DNS records, obtain the certificate, and clean up the DNS records. It will then call deploy_freenas.py to install the cert on FreeNAS.
Using the HTTP challenge
Note: The HTTP challenge uses acme.sh in standalone mode, which requires installation of socat. As a result, if you’re unable to use DNS validation, you’ll need to install acme.sh, socat, and deploy_freenas.py inside a jail.
To complete the HTTP challenge, the Let’s Encrypt servers must be able to connect to http://fqdn_of_freenas_box and obtain a small text file from /.well-known/acme-challenge/pseudorandomfilename. This means a few things:
- fqdn_of_freenas_box must resolve to the external (i.e., public) IP address of your network.
- You must be able to open port 80 on your firewall, and send it to the jail into which you installed acme.sh.
The first step is a matter of your DNS records; the second is a matter of the capabilities of, and your control over, your firewall.
Once the DNS records are published and the port forward is in place, run the following command:
acme.sh --issue -d fqdn_of_freenas_box --standalone --reloadcmd "/path/to/deploy_freenas.py"
As above, if all goes well, this will issue the certificate and deploy it to your system. You can remove the port forward after the cert is issued if you like, but you’ll need to put it back in place to renew the cert.
Automating renewal
Now that you’ve obtained and deployed your certificate, you’ll want to set up a cron job to renew it automatically. To do this, add a cron job through the web GUI, to run as root. It should run daily, at whatever time you like–it’s recommended that it run at an “odd” time like 3:17 am, rather than at the top of the hour, to avoid excessive stress on the Let’s Encrypt servers. The command will be /root/.acme.sh/acme.sh --cron if you used DNS validation, or iocage exec <jailname> /root/.acme.sh/acme.sh --cron if you installed acme.sh in a jail. With this command, acme.sh will run daily. If your certificate is at least 60 days old, it will attempt to renew it. If it fails, it will try again the next day, and so on until the certificate is successfully renewed.
Note
The above instructions describe the use of my deploy_freenas.py script to upload the newly-obtained cert into TrueNAS and configure services to use it. acme.sh now includes its own deployment script, which may suit your needs better. For more information on using it, see: deployhooks · acmesh-official/acme.sh Wiki · GitHub I believe my script gives more flexibility in choosing which services to apply the new cert to, though.
Also, TrueNAS itself now includes this capability, but only for a very short list of DNS providers–only Route53 for CORE, or Route53 or Cloudflare for SCALE. If you’re using an appropriate DNS provider, this may suit your needs.