μacme

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.

Table of Contents

• Requirements
• Installation
  • On Alpine Linux
  • From Tarball
• Usage
• Examples
• Challenge Hooks
  • httpd (HTTP-01)
  • nsupdate (DNS-01)
  • acmedns (DNS-01)
• License
• See Also

Requirements

• uacme

• POSIX-sh compatible shell with pipefail (e.g. Busybox ash, ZSH, bash, …)

• grep, sed, tr, xargs (BSD, Busybox or GNU)

• openssl command (should work with OpenSSL and LibreSSL)

httpd-challenge-hook.sh:

• busybox httpd

• start-stop-daemon from OpenRC

nsupdate-challenge-hook.sh:

• knsupdate and kdig from Knot DNS tools or nsupdate and dig from BIND tools

acmedns-challenge-hook.sh:

• kdig from Knot DNS tools or dig from BIND tools

• wget (tested with Busybox or GNU)

Installation

On Alpine Linux

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

From Tarball

wget https://github.com/jirutka/muacme/archive/v0.6.0/muacme-0.6.0.tar.gz
tar -xzf muacme-0.6.0.tar.gz
cd muacme-0.6.0
make install

Usage

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]

Examples

• 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

Challenge Hooks

httpd (HTTP-01)

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:

1. A cron job starts muacme renew -l all.

2. muacme invokes uacme for each certificate found in /etc/ssl/uacme/.

3. uacme checks the certificate expiration date; if it’s near expiration (parameter days in /etc/muacme/muacme.conf), uacme generates a CSR and creates a new order at Let’s Encrypt.

4. 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.

5. Let’s Encrypt retrieves the validation file from http://<domain>/.well-known/acme-challenge/<token>.

6. uacme retrieves the issued certificate from Let’s Encrypt.

7. uacme executes httpd-challenge-hook.sh script again to remove the verification file and stop the webserver.

8. uacme executes your renew-hook.sh script to reload services etc.

nsupdate (DNS-01)

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 (DNS-01)

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.

License

This project is licensed under MIT License. For the full text of the license, see the LICENSE file.

See Also

• uacme(1)

• kdig(1)

• knsupdate(1)