/ Security

An automatic certificate acquisition tool for ACME

An automatic certificate acquisition tool for ACME

acmetool

acmetool is an easy-to-use command line tool for automatically acquiring certificates from ACME servers (such as Let's Encrypt). Designed to flexibly integrate into your webserver setup to enable automatic verification. Unlike the official Let's Encrypt client, this doesn't modify your web server configuration.

acme

  • Zero-downtime autorenewal
  • Supports any webserver
  • Fully automatable
  • Single-file dependency-free binary
  • Idempotent
  • Fast setup

You can perform verifications using port 80 or 443 (if you don't yet have a server running on one of them); via webroot; by configuring your webserver to proxy requests for /.well-known/acme-challenge/ to a special port (402) which acmetool can listen on; or by configuring your webserver not to listen on port 80, and instead running acmetool's built in HTTPS redirector (and challenge responder) on port 80. This is useful if all you want to do with port 80 is redirect people to port 443.

You can run acmetool on a cron job to renew certificates automatically (acmetool --batch). The preferred certificate for a given hostname is always at /var/lib/acme/live/HOSTNAME/{cert,chain,fullchain,privkey}. You can configure acmetool to reload your webserver automatically when it renews a certificate.

acmetool is intended to be "magic-free". All of acmetool's state is stored in a simple, comprehensible directory of flat files. The schema for this directory is documented.

acmetool is intended to work like "make". The state directory expresses target domain names, and whenever acmetool is invoked, it ensures that valid certificates are available to meet those names. Certificates which will expire soon are renewed. acmetool is thus idempotent and minimises the use of state.

acmetool can optionally be used without running it as root. If you have existing certificates issued using the official client, acmetool can import those certificates, keys and account keys (acmetool import-le).

acmetool supports both RSA and ECDSA keys and certificates. acmetool's notification hooks system allows you to write arbitrary shell scripts to be executed when new certificates are obtained. By default, this is used to reload webservers automatically, but it can also be used to distribute certificates to other servers or for other purposes.

GitHub