ACME (Let's Encrypt) Certificates

AstLinux uses the acme-client command as a front-end to the core acme.sh script provided by the acme.sh project. The acme-client command limits issued certificates to only use DNS challenge validation, as such you need a supported DNS provider, of which there are well over 20 as of this writing.

The Command Line Interface (CLI) must be used to initially issue and deploy ACME certificates.

Note: AstLinux 1.3.0 or later is required

ACME Configuration

The generation of a Let's Encrypt Certificate does not require any special setup, but deployment options can be defined via the web interface:

Select the Network Tab in the web interface.

When the certificates are deployed the “ACME Deploy Service” services will receive the issued/renewed certificates and automatically restarted to make them active.

The “ACME Account Email Address” registration email address is used for expiry notifications, while optional it seems like a good idea to specify.

Tip → Clicking on the blue (i) icon will display topic information text similar to this documentation page.

Tip → The “HTTPS Server” ACME Deploy Service also creates a /mnt/kd/ssl/https_stunnel_server.pem PEM file containing the ACME private key and full certificate chain, automatically used with the HTTPS Stunnel server and can be configured to be used with the FOP2 server for
SSL/HTTPS with FOP2.

In order to apply web interface settings changes, use the CLI command:

gen-rc-conf

Issuing Certificates

This example on host pbx4 uses the acme-client wrapper around the core acme.sh script, the core version can be obtained by the command:

Only DNS challenge validation is supported within AstLinux, as such you need a supported DNS provider, in this example we are using Cloudflare. We need to export the CF_Key and CF_Email variables, adjust to match your credentials …

While not required, it is a good idea to unset the exported variables above that contain the DNS challenge validation credentials.

pbx4 ~ # unset CF_Key
pbx4 ~ # unset CF_Email

Note → The DNS challenge validation credentials remain stored in the /mnt/kd/acme/account.conf file so auto-renewals can be performed via cron.

Special Note → Depending on the acme.sh DNS provider script, some scripts store the exported credentials variable names exactly in /mnt/kd/acme/account.conf and others prepend SAVED_ to the variable names. When the credentials variable names are stored exactly any later changes to the credentials must be done by editing /mnt/kd/acme/account.conf. When the credentials variable names have SAVED_ prepended you may use export … later to change the saved credentials.

Auto-Renewing Certificates

Let's Encrypt certificates are only valid for 90 days, renewable after 60 days from the issue date. As such it is important to automate the process of renewing the certificate, this can be done by installing a cron entry using the command:

Multiple Domain Certificates

In the example above only one domain pbx4.example.org was specified. Let's Encrypt allows multiple domains to be specified with valid “Subject Alternative Name” entries in a single certificate. This assumes the DNSA and/or AAAA and/or SRV record of each domain points to the server with the issued certificate.

As an additional example let's say both example.org and subdomain pbx4.example.org are valid DNS entries you want to include in the “Subject Alternative Name” of the issued certificate.

Proceed as above, but simply include -d example.org when issuing the certificate, (specify the more general domain first) …

Likewise, when deploying the certificate, though you only need to specify the first -d example.org domain …

pbx4 ~ # acme-client --deploy --deploy-hook astlinux -d example.org

Additional CLI Commands

Some additional commands that may be useful to know …

List the issued certificate(s):

pbx4 ~ # acme-client --list

Revoke an issued certificate by domain:

pbx4 ~ # acme-client --revoke -d pbx4.example.org

Remove a certificate by domain:

pbx4 ~ # acme-client --remove -d pbx4.example.org

Advanced Options

For advanced users there may be situations where it would be useful to add special options for every occurrence of the acme-client command. Increasing the log-level and defining a log file would be one such example.

The /mnt/kd/acme/account.opts file does not exist by default, and needs to be manually created to enable this feature.

Example /mnt/kd/acme/account.opts file with persistent options added by acme-client to the acme.sh script:

## acme.sh options
log-level 3
log /var/log/acme-client.log

Tip → Most users will not need to create a /mnt/kd/acme/account.opts file.