Skip to content

Manage SSL / TLS certificates with acme.sh (Let's Encrypt, ZeroSSL) for Ubiquiti UbiOS firmwares

License

Notifications You must be signed in to change notification settings

emilvissing/ubios-cert

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 

Repository files navigation

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

Last update: March 20, 2023

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 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 to fiddle 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.

Discontinued support for firmwares < v2.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).

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 V2.x or V3.x,
  • a registered domain where you have API access for running the DNS-01 API challenge

Installation

Download the package

  • ssh into 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.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 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.

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-server/raddb/certs/server.pem ./raddb-server.pem
cp /data/udapi-server/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 forcerenew.

Behaviour after firmware upgrade / reboot

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

De-installation and de-registration

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-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 setdefaultca. 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 bootrenew 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.

Known bugs and unknowns

  • For sure some, but no known.

UniFi OS and Network Controller Versions

Confirmed to work on UniFi OS Version 2.5.17, 3.0.19 and Network Version 7.3.83, 7.4.146

About

Manage SSL / TLS certificates with acme.sh (Let's Encrypt, ZeroSSL) for Ubiquiti UbiOS firmwares

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Shell 100.0%