This a convenient wrapper for the ACMEv2 client uacme that provides a ready-to-go solution for a cron-based periodic renewal of an arbitrary number of TLS certificates.
httpd-challenge-hook.sh:
-
busybox httpd
-
start-stop-daemon
from OpenRC
nsupdate-challenge-hook.sh:
-
knsupdate
andkdig
from Knot DNS tools ornsupdate
anddig
from BIND tools
acmedns-challenge-hook.sh:
-
kdig
from Knot DNS tools ordig
from BIND tools -
wget
(tested with Busybox or GNU)
Install package muacme from the Alpine’s community repository:
apk add muacme
# if you wanna use httpd-challenge-hook.sh:
apk add busybox-extras
# if you wanna use nsupdate-challenge-hook.sh or acmedns-challenge-hook.sh:
apk add knot-utils
See the help section in muacme (or run muacme -h
) and comments in muacme.conf.
Note that you have to create an ACME account first (see uacme(1) for more information):
uacme -v -c /etc/ssl/uacme new [EMAIL]
-
Issue a certificate for domain example.org with alternative name www.example.org (and using options specified in the configuration file /etc/muacme/muacme.conf):
muacme issue example.org www.example.org
-
Issue a certificate for each domain listed in the given file (one per line with optional alternative names separated by a space) for which we don’t have one already. Domains for which we already have a certificate will be ignored.
muacme issue -F domains.list
-
Renew all certificates that are close to their expiration:
muacme renew all
-
Renew certificate for domain example.org even if it’s too soon:
muacme renew -f example.org
-
A renew hook for reloading nginx on a system using OpenRC:
#!/bin/sh /etc/init.d/nginx --ifstarted --quiet reload
-
A cron script /etc/periodic/weekly/muacme-renew-all:
#!/bin/sh exec muacme renew -l all
httpd-challenge-hook.sh is a hook script for the HTTP-01 challenge that automatically starts busybox httpd server on port 80 to serve the key authorization for the challenge verification and stops it right after it’s done.
The complete process of renewal looks like this:
-
A cron job starts
muacme renew -l all
. -
muacme
invokesuacme
for each certificate found in /etc/ssl/uacme/. -
uacme
checks the certificate expiration date; if it’s near expiration (parameterdays
in /etc/muacme/muacme.conf), uacme generates a CSR and creates a new order at Let’s Encrypt. -
uacme
executes httpd-challenge-hook.sh script that writes the validation file for Let’s Encrypt into a temporary directory and starts a webserver (busybox httpd
) on port 80 to serve this file. -
Let’s Encrypt retrieves the validation file from
https://<domain>/.well-known/acme-challenge/<token>
. -
uacme
retrieves the issued certificate from Let’s Encrypt. -
uacme
executes httpd-challenge-hook.sh script again to remove the verification file and stop the webserver. -
uacme
executes your renew-hook.sh script to reload services etc.
nsupdate-challenge-hook.sh is a hook script for DNS-01 challenge that utilizes knsupdate
(or nsupdate
) to add/delete _acme-challenge.<domain>
TXT record for the requested domain name.
This script can be configured using /etc/muacme/muacme.conf or environment variables.
If you want to use nsupdate
and dig
instead of their Knot variants, you have to overwrite options dns01_nsupdate
and dns01_dig
.
acmedns-challenge-hook.sh is a hook script for DNS-01 challenge that calls REST API provided by the acme-dns server to add _acme-challenge.<domain>
TXT record for the requested domain name.
This script can be configured using /etc/muacme/muacme.conf or environment variables.
Before you can issue a certificate for a domain, you must do a registration on the acme-dns server and add the obtained subdomain, username and password to /etc/muacme/acme-dns.keys
.
This can be easily done using the provided muacme-acmedns
script, for example muacme-acmedns register https://auth.acme-dns.io
.
If you want to use dig
instead of its Knot variants, you have to overwrite option dns01_dig
.
This project is licensed under MIT License. For the full text of the license, see the LICENSE file.