Get a free HTTPS certificate from LetsEncrypt for OpenWrt with ACME.sh
For experienced users
Step 1: Install packages
Use a command line and type opkg install acme luci-app-acme
then edit /etc/config/acme
and restart it with service acme restart
.
If you want to use DNS-based certificate verification, also install the DNS providers: opkg install acme-dnsapi
Step 2: Configure Web Server Here we'll tell uhttpd redirect to HTTPS.
These commands use the OpenWrt uci command, a brilliant way to parse, get, set, and edit values and sections from config files. It makes scripting OpenWrt a breeze.
uci set uhttpd.main.redirect_https=1 uci commit /etc/init.d/uhttpd restart
Step 3: Configure acme.sh and get your certificate
Edit /etc/config/acme
, and run /etc/init.d/acme restart
afterwards.
For example if you use the DuckDNS.org DDNS provider and wish to have a wildcard certificate *.example.duckdns.org
then install the acme-dnsapi
package and configure the acme like:
config acme option account_email 'youremail@example.com' config cert 'example_duckdns_wildcard' option enabled '1' option validation_method 'dns' option dns 'dns_duckdns' list credentials 'DuckDNS_Token="YOUR_TOKEN"' list domains '*.example.duckdns.org' list domains 'example.duckdns.org'
See Acme.sh DNS API: DuckDNS.org for details.
Step 4: Configure Firewall Open or forward LuCI port for external access. (use Webinterface)
More easier way by using GUI
Open LUCI dashboard then in main menu go to System -> Software. Then click on Update lists...
to load list of available packages.
The into the Filter
search type luci-app-acme
and press Enter. Click on install button. It should install acme.sh and its LUCI app to configure.
To configure in LUCI in the main menu open Services -> ACME certs.
Basic configuration:
Account email
: put your email to receive expiry notices when your certificate is coming up for renewal.- You'll see a two preconfigured but disabled EXAMPLE domains. But we'll make a new one for ourselves.
- At bottom find a field for a new domain config, type your domain but with underscores e.g.
example_com
and click onAdd
. - A new config section will be added. Now let's edit it.
- Check
Enabled
Domain names
: add your domainexample.com
. If you need a wildcard cert then also add*.example.com
(needs for DNS challenge).- Switch to
Challenge Validation
tab and selectValidation method
:- If you have a public web server then select
Webroot
. The default webroot path is/var/run/acme/challenge/
. See details below - If you need for a wildcard cert e.g.
*.example.com
or you don't have a public webserver then selectDNS
and configure DNS API - If you don't have any webserver then you can try the Standalone mode
- Click on
Save and Apply
In a minute the cert should be generated. You can check logs in Status -> System Log.
If any error occurred fix it and restart the acme service to trigger issuing.
Go to System -> Startup, find the acme service and click of Restart
.
Webroot
All OpenWrt webservers should serve the folder /var/run/acme/challenge/
under /.well-known/acme-challenge/
URL path by default. But if not then you can create a symlink:
mkdir /www/.well-known/ ln -s /var/run/acme/challenge/ /www/.well-known/acme-challenge
Now test if it's accessible from internet:
mkdir -p /var/run/acme/challenge/ echo Hi > /var/run/acme/challenge/README.txt wget -qO - http://example.com/.well-known/acme-challenge/README.txt
Use the generated certificates
After that you can find the certificates in a folder at /etc/ssl/acme/
e.g.:
/etc/ssl/acme/*.example.com.key
the TLS private key. Never share it!/etc/ssl/acme/*.example.com.fullchain.crt
the TLS certificate and chain of CA that signed it.
Detailed certificate configs are stored in /etc/acme/
.
You can use them in uhttpd, lighttpd, nginx, EmailRelay and any other server that you want to configure with TLS.
Standalone Mode Validation
ACME.sh
runs a temporary web-server in this mode to allow for validation. That server needs to be publicly accessible, so you may have to forward WAN port 80 to it. However, that server listens on port 80 by default, which might clash with uhttpd
. You can change the listening port to something like 8080, by editing the value of Le_HTTPPort
in /usr/lib/acme/acme.sh
, or by passing it the --httpport
argument. Then you must forward WAN port 80 (external port remains the same) to device port 8080.
See also
- Acme.sh Wiki: How to run on OpenWrt also describes how to configure uhttpd and firewall.