acme-tiny-core Fedora package

This package contains only the upstream python script - for those who prefer their own framework for cert maintenance.

acme-tiny Fedora package

The Fedora package for acme-tiny adds a tiny framework to make issuing and renewing Let's Encrypt certificates convenient. It does not alter your configuration in any way, other than to drop an acme.conf apache config snippet into /etc/httpd/conf.d and provide a systemd service.

If you want a package that tries to do everything for you as root, consider the certbot package.

The ACME protocol will work with other certificate authorities, but acme-tiny is currently hardwired to use letencrypt.org - which is also currently the only ACME certificate authority recognized in most browsers.

These instructions assume you are using letsencrypt for the first time with this acme-tiny package. For example, you should not already have an account key for the domains it will manage. If you do, see README.md for instructions on converting it. Put any existing account key in PEM format in /var/lib/acme/private, readable by the acme user (only!).

The web server must already serve your domains on HTTP

If you cannot access your web domains locally with commands like curl and wget, then this framework won't work. Acme-tiny will work with any web server package, but if you are not using apache (httpd package), you must provide the equivalent of /etc/httpd/conf.d/acme.conf to map /var/www/challenges to the ACME URL location. The web server can even be on a remote machine - provided you have somehow arranged for it to serve files from /var/www/challenges (perhaps via NFS).

If you are using Apache, and restrict access to <location "/">, then this will override the acme.conf global config snippet, and you must explicitly make the ACME URL (http://your.domain.here/.well-known/acme-challenge/) publicly accessible.

Put your CSRs in /var/lib/acme/csr

You can use existing CSRs, or generate a new one using openssl. Put all CSRs to be issued and renewed by acme-tiny in /var/lib/acme/csr. I like to symlink the CSRs into /var/lib/acme/csr, just make sure the acme user can read them (and follow the symlink). The details for openssl are beyond the scope of this documentation, but this should work for creating a certificate for a single domain:

cd /etc/pki/tls
ln -s /var/lib/acme/csr .
openssl req -new -nodes -keyout private/your.domain.key \
    -out csr/your.domain.csr
chmod 0400 private/your.domain.key

If you have an existing key, replace -nodes -keyout with -key. The default openssl config will ask you for data, be sure to give the domain you will be serving when it asks for "Common Name". It is possible to cover multiple domains with a single certificate using openssl. First, add a section to the end of /etc/pki/tls/openssl.cnf defining your extension:

[MYSERV]
subjectAltName=DNS:your.domain,DNS:www.your.domain

Then add -reqexts MYSERV to the openssl command line. One of the domains must match the common name.

Make sure the CSR can be read by the acme user.

Issue the certificate

The timer service in acme-tiny will check the certificate for all CSRs in csr every 24 hours, and issue or renew the certificate if it is missing or about to expire (in 7 days by default). You don't have to wait for the timer, however. Use

systemctl start acme-tiny

to run the service now. The certificate should appear in /var/lib/acme/certs, and errors will be in journalctl. Alternatively, run /usr/libexec/acme-tiny/sign as the acme user, and errors will go to your terminal.

Use the certificate

The default httpd config uses a self-signed localhost certificate for https. Edit /etc/httpd/conf.d/ssl.conf and change SSLCertificateFile and SSLCertificateChainFile to /var/lib/acme/certs/your.domain.crt (or use a symlink to /etc/pki/tls/certs). Change SSLCertificateKeyFile to /etc/pki/tls/private/your.domain.key.

Obviously, you can change the locations to suit your sysadmin tastes.

Some SSL apps, like dovecot, require SSL certificates to be tagged in selinux.

semanage fcontext -a -f 'all files' -t cert_t '/var/lib/acme/certs(/.*)?'
restorecon -rv /var/lib/acme/certs

The above will permanently change the selinux tag to work with dovecot and other apps.

Sendmail is a special problem - it insists that any certificates it loads be only writable by root. This is at odds with the privilege separation of the acme user. (Obviously, the private key must be accessible only by root.) You can, of course, copy the crt file to /etc/pki/tls/certs as root and change the mode. But this has to be done every time the cert is renewed.
The systemd acme-tiny.service runs acme-tiny-notify.service afterward which executes as root. It calls /usr/libexec/acme-tiny/notify for each nenewed cert. (This used to be /etc/acme-tiny/notify.sh - which is now a symlink.)

Suppose /var/lib/acme/certs/mail.crt is renewed, where mail.crt is the certificate sendmail will use. The notify script sees the reference to /etc/pki/tls/certs/mail.crt in /etc/mail/*.cf, and copies the renewed cert to /etc/pki/tls/certs. Sendmail can then load it from there and be happy. This also solves the file context problem.

The notify script has built in support for the httpd, sendmail, and dovecot packages for Fedora. To avoid restarting services multiple times, the notify script records in /var/lib/acme/.notify when it last restarted each service.

By dropping scripts with names ending in .sh in /etc/acme-tiny/notify.d, additional packages (e.g. nginx) can be supported.

This new system should be compatible with older incrond configs, but the additional /etc/acme-tiny/notify.sh calls from incrond are redundant. Making them redundant, incidentally fixes BZ#1839904. There could still be a race condition missed in testing, so I would disable your old acme incrontab.

Logging and Error Reporting

Under systemd, errors and certs signed are logged with the acme-tiny syslog identifier.

Virtual Hosts

Most web servers can handle multiple logical web hosts - configuring that is beyond the scope of this document. Each virtual host may need to have its own certificate for SSL. They can all share the same key file (see above for how to use an existing key for certificate requests), or use different keys. Note that apache can load certs directly from /var/lib/acme/certs, and so notify.sh simply does apachectl graceful.

Put all the CSRs in /var/lib/acme/csr and the acme-tiny service will keep them all renewed. This also works for certificates used by other SSL applications, such as dovecot, sendmail, jabberd, or znc.