ACMEd

The Automatic Certificate Management Environment (ACME), is an internet standard (RFC 8555) which allows to automate X.509 certificates signing by a Certification Authority (CA). ACMEd is one of the many clients for this protocol.

Key features

http-01, dns-01 and tls-alpn-01 challenges
IP identifier validation extension RFC 8738
RSA 2048, RSA 4096, ECDSA P-256, ECDSA P-384, ECDSA P-521, Ed25519 and Ed448 certificates and account keys
Internationalized domain names support
Fully customizable challenge validation action
Fully customizable archiving method (yes, you can use git or anything else)
Nice and simple configuration file
A pre-built set of hooks that can be used in most circumstances
Run as a deamon: no need to set-up timers, crontab or other time-triggered process
Retry of HTTPS request rejected with a badNonce or other recoverable errors
Customizable HTTPS requests rate limits
External account binding
Optional key pair reuse (useful for HPKP)
For a given certificate, each domain name may be validated using a different challenge
A standalone server dedicated to the tls-alpn-01 challenge validation (tacd)

Planned features

STAR certificates RFC 8739
Daemon and certificates management via the acmectl tool
HTTP/2 support

Project status

This project is usable, but is still a work in progress. Each release should works well and accordingly to its documentation. Because the API has not been stabilized yet, breaking changes may occur. Therefore, before any upgrade, you are invited to read the CHANGELOG and check if any change can break your setup.

Please keep in mind this software has neither been subject to a peer review nor to a security audit.

Documentation

The wiki will provides you with an overview as well as guides.

For exhaustive references, the following man pages are available:

acmed (8)
acmed.toml (5)
tacd (8)

An easy way to read those pages without installing ACMEd is to downloads and pipe them to the man utility:

curl -sSf "https://codeberg.org/rbd/acmed/raw/branch/main/man/en/acmed.8" | man -l -
curl -sSf "https://codeberg.org/rbd/acmed/raw/branch/main/man/en/acmed.toml.5" | man -l -
curl -sSf "https://codeberg.org/rbd/acmed/raw/branch/main/man/en/tacd.8" | man -l -

Alternatively, using zsh, you can use the following variants. Useful on system where man is unable to read from stdin (yes BSD, that's you).

man =(curl -sSf "https://codeberg.org/rbd/acmed/raw/branch/main/man/en/acmed.8")
man =(curl -sSf "https://codeberg.org/rbd/acmed/raw/branch/main/man/en/acmed.toml.5")
man =(curl -sSf "https://codeberg.org/rbd/acmed/raw/branch/main/man/en/tacd.8")

Build from source

In order to compile ACMEd, you will need the Rust compiler and its package manager, Cargo. The minimum supported Rust version (MSRV) is 1.85, although it is recommended to use the latest stable one.

ACMEd depends OpenSSL 1.1.0 or higher.

On systems based on Debian/Ubuntu, you may need to install the libssl-dev, build-essential and pkg-config packages.

On Alpine Linux, you may need to install the openssl-dev and alpine-sdk packages.

$ make
$ make install

To build ACMEd and tacd inside a temporary Docker container, use the contrib/docker/build-docker.sh helper script. It currently supports Debian Buster / Stretch.

You can also build a container image for some k8s deployement, use the contrib/docker/build-docker-image.sh script. It supports the same targets as the build-docker.sh script.

When build succeed, you can start the container with docker run --rm -v /path/to/conf/dir:/etc/acmed acmed:buster.

Advanced options

You can specify a space or comma separated list of features to activate in the FEATURE variable. The possible features are:

openssl_dyn (default): use OpenSSL as the cryptographic library, dynamically linked (mutually exclusive with openssl_vendored).
openssl_vendored: use OpenSSL as the cryptographic library, statically linked (mutually exclusive with openssl_dyn).

You can also specify the target triple to build for in the TARGET variable. Please note that, if used, this variable must be specified for both make and make install.

For example, you can build statically linked binaries using the openssl_vendored feature and the x86_64-unknown-linux-musl target.

make FEATURES="openssl_vendored" TARGET="x86_64-unknown-linux-musl"

The following environment variables can be used to change default values at compile and/or install time:

PREFIX (install): system user prefix (default to /usr)
BINDIR (install): system binary directory (default to $PREFIX/bin)
DATADIR (install): system data directory (default to $PREFIX/share)
MAN5DIR (install): system directory where pages 5 manuals are located (default to $DATADIR/man/man5)
MAN8DIR (install): system directory where pages 8 manuals are located (default to $DATADIR/man/man8)
SYSCONFDIR (compile and install): system configuration directory (default to /etc)
VARLIBDIR (compile and install): directory for persistent data modified by ACMEd (default to /var/lib)
RUNSTATEDIR (compile): system run-time variable data (default to /run)
ACMED_DEFAULT_ACCOUNTS_DIR (compile): directory where account files are stored (default to $VARLIBDIR/acmed/accounts)
ACMED_DEFAULT_CERT_DIR (compile): directory where certificates and private keys are stored (default to $VARLIBDIR/acmed/certs)
ACMED_DEFAULT_CERT_FORMAT (compile): format for certificates and private keys files names (default to { name }_{ key_type }.{ file_type }.{ ext })
ACMED_DEFAULT_CONFIG_FILE (compile): main configuration file (default to $SYSCONFDIR/acmed/acmed.toml)
ACMED_DEFAULT_PID_FILE (compile): PID file for the main acmed process (default to $RUNSTATEDIR/acmed.pid)
TACD_DEFAULT_PID_FILE (compile): PID file for the tacd process (default to $RUNSTATEDIR/tacd.pid)

For example, the following will compile a binary that will use the /usr/share/etc/acmed/acmed.toml configuration file and will be installed in the /usr/local/bin directory :

make SYSCONFDIR="/usr/share/etc"
make BINDIR="/usr/local/bin" install

Packaging

Most of the time, when packaging, you want to install the program in a dedicated directory. This is possible using the DESTDIR variable.

make DESTDIR="/path/to/my/package/directory" install

Packager tip: If you package ACMEd in a way it does not run as root, you might want to create another package that provides the Polkit rule file located in the contrib/polkit directory. This package should depends on both acmed and Polkit.

Frequently Asked Questions

Why this project?

After testing multiple ACME clients, I found out none of them supported all the features I expected (see the key features above). It may have been possible to contribute or fork an existing project, however I believe those project made architectural choices incompatible with what i wanted, and therefore it would be as much or less work to start a new project from scratch.

Is it free and open-source software?

Yes, ACMEd is licensed under either the MIT or Apache 2.0 licenses. Some files that are not directly part of the source code itself, like the man pages, are distributed under the FSF All Permissive license.

This project is REUSE compliant. You will therefore find a copy of every license in the LICENSES directory and more details on the applicable license of every file in the REUSE.toml file.

Where is this project hosted?

At first this project was hosted on GitHub but has then been moved to Codeberg. GitHub has been kept as a mirror where changes are forced-push.

Can it automatically change my server configuration?

Short answer: No.

Long answer: At some points in a certificate's life, ACMEd triggers some hooks in order to let you customize how some actions are done, therefore you can use those hooks to modify any server configuration you wish. However, this may not be what you are looking for since it cannot proactively detect which certificates should be emitted since ACMEd only manages certificates that have already been declared in the configuration files.

How should I configure my TLS server?

You decide. ACMEd only retrieve the certificate for you, it does not impose any specific configuration or limitation on how to use it. For the record, if you are looking for security recommendations on TLS deployment, you can follow the ANSSI TLS guide (the english version might not be the latest version of this document, if possible use the french one).

Is it suitable for beginners?

It depends on your definition of a beginner. This software is intended to be used by system administr

Acmed

Install / Use

README