Let's Encrypt with FreeNAS 11.1 and later

How-to
1

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. 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. 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 https://github.com/Neilpang/acme.sh/tree/master/dnsapi. 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:

setenv CF_Key "(your cloudflare master API key)"
setenv CF_Email "you@example.com" # the email address you used to register for cloudflare
.acme.sh/acme.sh --issue -d fqdn_of_freenas_box --dns dns_cf --reloadcmd "/path/to/deploy_freenas.py"

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:

  1. fqdn_of_freenas_box must resolve to the external (i.e., public) IP address of your network.
  2. You must be able to open port 80 on your firewall, and send it to the jail where you installed acme.sh and socat (the FreeNAS box should never be exposed directly to the Internet).

The first step is a matter of your DNS records, and 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. The command will be /root/.acme.sh/acme.sh --cron . 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.

1 Like