Valid and free TLS / SSL certificates for UniFi Consoles V4.x and V3.2.x

Last update: October 13, 2024.

Public Service Announcement: In its best tradition, UI has established some new, of course undocumented, black magic around valid SSL certificates. This project here tries to cope with this new twist. Web frontend and Hotspot are covered now, and WiFiMan will be toasted as soon as you use custom SSL certificates. This has been officially acknowledged by UI. Right now, RADIUS will still not work.

I suggest you give Glenn R.'s monster scripts a try - if you can. He's on the UI community forums and obviously knows extremely well what needs to be done, but is not willing to address the request for certificates issued with DNS-Challenge. Coincidently, he seems to work for UI and there is a UI team member called UI-Glenn.

If you're able to convince him or UI to provide proper, out of the box support for securing communication with UI devices beyond having a self-signed "unifi.local" certificate - I will archive this project the next minute. In the meantime...

What it does

Spare you and your users from certificate errors when browsing to your UniFi Console's (Dream Machine Base / Pro / SE / R) administrative web frontend, Hotspot Portal and RADIUS server.

TL;DR jump to Installation

It will install Neilpang's acme.sh, is extremely light as it runs on bare metal and survives (until further notice...) reboots and firmware upgrades (at least for minor revisions).

With that, it will

• issue TLS (aka SSL) certificates for a domain (with Subject Alternate Names or wildcards) you own, using (Let's Encrypt (LE), and other supported certification authorities,
• use the DNS-01 challenge, so you don't have be present on the Internet with open ports 80 and 443,
• renew your certificate automatically every 60 days.

Discontinued support for firmwares < v4.x

This branch serves the most current firmware(s).

If you're still running a V1.x (why would you...), please have a look at branch v1.x - which is no longer supported (at least not by me due to lack of hardware).

If you're on V2.x to anything before V3.2.7, check branch V2-to-V3.1.

Currently supported DNS API providers

Over 150, check acme.sh DNS API Wiki for details.

But why?

In most private installations, the UniFi console will live behind a router / firewall provided by an ISP, and we don't want to open HTTP(S) ports 80 and 443 to the interested public.

What you need

• A UniFi Console with firmware V4.x,
• a registered domain where you have API access for running the DNS-01 API challenge,
• the awareness you might break something.

Installation

Download the package

• ssh into your UDM

• Download the archive to your home directory and unzip it

  cd
  curl -L https://github.com/alxwolf/ubios-cert/archive/main.zip > ubios-cert.zip
  unzip ubios-cert.zip
  cd ubios-cert-main
  chmod +x deploy.sh

• Make your adjustments to ubios-cert.env

  vi ubios-cert/ubios-cert.env

• Deploy the files to their proper place

  ./deploy.sh

• Navigate to the deployment folder and issue your certificate for the first time

  cd /data/ubios-cert
  ./ubios-cert.sh initial

Make your adjustments

Adjust file ubios-cert.env to your needs.

First, define your certificate names and CA by adjusting

#######################################
# Configure certificates and provider #
#######################################

# The FQDN of your UniFi Console (comma separated fqdns and wildcards are supported)
CERT_HOSTS='domain.com,*.domain.com'

# Email address for registration
CA_REGISTRATION_EMAIL='[email protected]'

# Default CA: https://github.com/alxwolf/ubios-cert/wiki/acme.sh:-choosing-the-default-CA
DEFAULT_CA="letsencrypt"

Second,

#################################################
# Select services to provide the certificate to #
#################################################

# Enable updating Hotspot Portal certificate 
# this will break WiFiMan 100% as of v3.2.7
# provide options 'yes' or 'no' in lowercase
ENABLE_HOTSPOT='yes'

# Enable updating Radius support
# provide options 'yes' or 'no' in lowercase
ENABLE_RADIUS='yes'

Third, select your DNS API provider by adjusting the variable DNS_API_PROVIDER="dns_xxx".

dns_xxx must be replaced with the --dns parameter from your provider's acme.sh DNS API Wiki entry.

So for CloudFlare this would say

export DNS_API_PROVIDER="dns_cf"

Some APIs may require additional manual preparation, please check the Wiki.

Advanced: you can pass additional command line options to acme.sh by editing environment variable ACMESH_CMD_PARAMS.

First Run

Consider making a backup copy of your current certificate and key before moving on.

mkdir /data/ubios-cert/certbackup
cd /data/ubios-cert/certbackup
cp /data/unifi-core/config/unifi-core.key ./unifi-core.key_orig
cp /data/unifi-core/config/unifi-core.crt ./unifi-core.crt_orig
cp /data/udapi-config/raddb/certs/server.pem ./raddb-server.pem
cp /data/udapi-config/raddb/certs/server-key.pem ./raddb-server-key.pem

Calling the script with sh /data/ubios-cert/ubios-cert.sh initial will

• setup up the trigger for persistence over reboot / firmware upgrades
• establish a cron job to take care about your certificate renewals
• register an account with your email
• issue a certificate (with SANs, if you like)
• deploy the certificate to your network controller (and captive portal, if you selected that)
• restart the unifi-os

Certificate Renewal

Should be fully automated, done via a daily cron job. You can trigger a manual renewal by running sh /data/ubios-cert/ubios-cert.sh renew, which may be useful for debugging. If acme.sh fails, check if you hit the rate limits.

The certificate can be force-renewed by running sh /data/ubios-cert/ubios-cert.sh force-renew.

Behaviour after firmware upgrade / reboot

Survived reboots and firmware updates, including release change from V3 to V4.

De-installation and de-registration

ssh into your UDM. Calling the script with sh /data/ubios-cert/ubios-cert.sh cleanup will

• Remove the cron file from /etc/cron.d
• Remove the (most recently issued) domains from the Let's Encrypt account
• De-activate the Let's Encrypt account

Then, you can delete the script directory. As always, be careful with rm.

cd /data/
./ubios-cert/ubios-cert.sh cleanup
rm -irf ./ubios-cert

Selecting the default CA

acme.sh can access different CAs. You can select which CA you want it to use. The keywords are listed here. Adjust the value in ubios-cert.env first and then call the script with ubios-cert.sh set-default-ca. This CA will from now on be applied to newly issued certificates.

Debugging

• Increase the log level in ubios-cert.sh by setting LOGLEVEL="--log-level 2"
• Run tail -f ${DATA_DIR}/ubios-cert/acme.sh/acme.sh.login separate terminal while running sh ubios-cert.sh initial, sh ubios-cert.sh renew or sh ubios-cert.sh force-renew manually

Inspired by - Sources and Credits

A huge "Thank You" goes to

• Neilpang's acme.sh: the probably most convenient and most supported interface for Let's Encrypt, ZeoSSL, Buypass and SSL.com.
• llaforest: for implementing the native / bare metal version of acme.sh
• kchristensen's udm-le for UDM: his work provides the base for both structure of implementation and content.
• Glenn R.'s Easy Encrypt script

Known bugs and unknowns

• For sure some. And a lack of tests, checks and cleanup. RADIUS certificates are still broken.

UniFi OS and Network Controller Versions

Confirmed to work on UniFi OS Version 4.0.x and Network Version 8.5.6