Last update: December 13, 2023.
CAVEAT there have been reports that v3.7.2 (early access) keeps overwriting custom certificates, breaking some applications. Currently under investigation.
Spare you and your users from certificate errors when browsing to your UniFi Console's (Dream Machine Base / Pro / SE / R) administrative page, Guest Portal or 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). No need fiddling around with podman installations.
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.
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).
Over 150, check acme.sh DNS API Wiki for details.
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.
- A UniFi Console with firmware V2.x or V3.x,
- a registered domain where you have API access for running the DNS-01 API challenge
-
sshinto your UDM -
Download the archive to your home directory
-
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.envvi 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
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 Captive Portal (for Guest Hotspot and WiFiman) certificate as well as device certificate
ENABLE_CAPTIVE='no'
# you want to spare users from "intermediate certificate missing" errors?
# this will break WiFiman iOS app
# uncomment next line, set to 'yes' to provide the full chain to Captive Portal
CAPTIVE_FULLCHAIN='yes'
# Enable updating Radius support
ENABLE_RADIUS='no'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.
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.pemCalling 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
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 forcerenew.
Survived reboots and firmware updates, including release change from V2 to V3.
ssh into your UDM. Calling the script with parameter 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-certacme.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 setdefaultca. This CA will from now on be applied to newly issued certificates.
- Increase the log level in
ubios-cert.shby settingLOGLEVEL="--log-level 2" - Run
tail -f ${DATA_DIR}/ubios-cert/acme.sh/acme.sh.login separate terminal while runningsh ubios-cert.sh initial,sh ubios-cert.sh reneworsh ubios-cert.sh bootrenewmanually
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.
- For sure some, but no known.
Confirmed to work on UniFi OS Version 2.5.17, 3.0.19, 3.1.12, 3.2.6 and Network Version 7.3.83, 7.4.146, 8.0.24