acmetool for Debian
===================

Please refer to the User's Guide for acmetool at

https://hlandau.github.io/acmetool/userguide

The format of acmetool's state directory is described in

/usr/share/doc/acmetool/SCHEMA.md.gz

For a general overview of Let's Encrypt see

https://letsencrypt.org/how-it-works/


Running systemd service
-----------------------

The acmetool Debian package ships a systemd service and timer to run
acmetool twice daily and renew certificates that are close to expiry.
The systemd service runs acmetool as user root (to permit restarting
services via hooks after renewal) but with restricted privileges.

As the first step, you may run

systemctl start acmetool.service

to populate /var/lib/acme/ with the initial directory schema. After
configuring acmetool as outlined below, rerun the above command to
request newly configured certificates and test your configuration.

The systemd service logs output to /var/log/acmetool/acmetool.log.

To customize the systemd service, you may run

systemctl edit acmetool.service

The following stanza enables verbose output for debugging:

[Service]
ExecStart=
ExecStart=/usr/bin/acmetool --batch --xlog.severity=debug reconcile

To revert your changes to the systemd service, you may run

systemctl revert acmetool.service

When satisfied with your setup, you may run

systemctl enable acmetool.timer
systemctl start acmetool.timer


Obtaining certificates
----------------------

Let's Encrypt provides a staging server that may be used to obtain test
certificates, which is useful for testing your setup repeatedly without
hitting the various rate limits enforced by the production server. These
certificates are signed by a fake CA and will not validate in a browser.

To use the staging server, create /var/lib/acme/conf/target with

request:
  provider: https://acme-staging-v02.api.letsencrypt.org/directory

To switch to the production server, change /var/lib/acme/conf/target to

request:
  provider: https://acme-v02.api.letsencrypt.org/directory

When requesting certificates for the first time, acmetool registers an
account on the Let’s Encrypt server and asks for your approval of the
Let’s Encrypt Subscriber Agreement and (optionally) your email address.

To automate account creation, create /var/lib/acme/conf/responses with

"acme-enter-email": "user@example.com"
"acme-agreement:https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf": true

You may specify the empty string ("") to register without email address.

To obtain a certificate for a given set of hostnames, create a file
with an arbitrary name, e.g., /var/lib/acme/desired/example.org with

satisfy:
  names:
  - example.org
  - www.example.org


Webroot mode
------------

To authorize your account for the requested hostnames, acmetool must
complete one out of multiple challenges that validate your control of
each hostname. If you are not running a web server on ports 80 and 443,
acmetool by default listens on either port to answer to challenges.

If you are already running a web server, you may use it to serve
challenge files that acmetool by default writes to the directory
/run/acme/acme-challenge/. Your web server on port 80 must be
configured to alias /.well-known/acme-challenge/ to the directory.

For the apache2 web server, this alias is enabled by default.

For the nginx web server, you may include the following snippet
for each virtual host for which you wish to obtain a certificate:

include snippets/acmetool.conf;


Hook scripts
------------

After obtaining a certificate, acmetool runs any executable files in
the directory /etc/acme/hooks/, e.g., to reload the nginx web server:

#!/bin/sh
[ "$1" = "live-updated" ] || exit 42 # unsupported event
systemctl reload nginx.service


Key permissions
---------------

By default, the directory /var/lib/acme/keys/ is accessible by the user
root only. For a daemon running under a non-root user, you may run

adduser mydaemon ssl-cert

and create a file /var/lib/acme/conf/perm with

keys 0640 0750 root ssl-cert

to make private keys readable to members of the group ssl-cert.
