2016-01-10 15:20:59 +01:00
ACERTMGR
========
This is an automated certificate manager using ACME/letsencrypt.
Running ACERTMGR
----------------
The main file acertmgr.py is intended to be run regularly (e.g. as daily cron job) as root.
2016-01-11 20:15:31 +01:00
Requirements
------------
2016-04-04 01:44:21 +02:00
* Python (2.7+ and 3.3+ should work)
2016-01-21 16:43:05 +01:00
* python-dateutil
2016-01-11 20:22:36 +01:00
* PyYAML
2016-04-04 09:11:04 +02:00
* pyOpenSSL
2016-01-11 20:15:31 +01:00
2016-02-13 00:54:28 +01:00
Initial Setup
-------------
2016-04-04 01:44:21 +02:00
First, you need to provide two key files for the ACME protocol:
2016-02-13 00:54:28 +01:00
* The account key is expected at `/etc/acme/account.key`
* The domain key is expected at `/etc/acme/server.key` (note: only one domain key is required for all domains used in the same instance of acertmgr)
If you are missing these keys, you can create them using `openssl genrsa 4096 > /etc/acme/account.key` and `openssl genrsa 4096 > /etc/acme/server.key` respectively.
2016-04-09 20:53:23 +02:00
* Do not forget to set proper permissions of the keys using `chmod 0400 /etc/acme/*.key`
2016-02-13 00:54:28 +01:00
2016-04-04 01:44:21 +02:00
Secondly, you should download the letsencrypt CA certificate:
* wget -O /etc/acme/lets-encrypt-x3-cross-signed.pem https://letsencrypt.org/certs/lets-encrypt-x3-cross-signed.pem
* The path to this file must be entered in the configuration, see below.
Thirdly, you should decide which challenge mode you want to use with acertmgr
2016-02-13 00:54:28 +01:00
* webdir: In this mode, challenges are put into a directory, and served by an existing webserver. Make sure the target directory exists!
* standalone: In this mode, challenges are completed by acertmgr directly.
This starts a webserver to solve the challenges, which can be used standalone or together with an existing webserver that forwards request to a specified local port.
Finally, you need to setup the configuration files, as shown in the next section.
2016-04-04 19:11:46 +02:00
While testing, you can use the acme-staging authority instead, so you avoid issuing too many certificates.
2016-02-13 00:54:28 +01:00
2016-01-10 15:20:59 +01:00
Configuration
-------------
The main configuration is read from `/etc/acme/acme.conf` , domains for which certificates should be obtained/renewed should be configured in `/etc/acme/domains.d/{fqdn}.conf` .
All configuration files use yaml syntax.
* Example global configuration file:
2016-01-10 15:27:08 +01:00
```yaml
---
2016-01-10 15:20:59 +01:00
2016-01-10 15:27:08 +01:00
mode: webdir
2016-01-10 15:48:16 +01:00
#mode: standalone
2016-02-13 00:54:28 +01:00
#port: 13135
2016-01-10 17:29:26 +01:00
webdir: /var/www/acme-challenge/
2016-04-04 19:11:46 +02:00
authority: "https://acme-v01.api.letsencrypt.org"
#authority: "https://acme-staging.api.letsencrypt.org"
2016-01-10 17:29:26 +01:00
defaults:
2016-04-04 01:44:21 +02:00
cafile: /etc/acme/lets-encrypt-x3-cross-signed.pem
2016-01-10 15:27:08 +01:00
```
2016-01-10 15:20:59 +01:00
* Example domain configuration file:
2016-01-10 15:27:08 +01:00
```yaml
---
mail.example.com:
2016-02-21 11:18:32 +01:00
- path: /etc/postfix/ssl/mail.key
user: postfix
group: postfix
perm: '400'
format: key
action: '/etc/init.d/postfix reload'
2016-01-21 16:43:05 +01:00
- path: /etc/postfix/ssl/mail.crt
user: postfix
2016-01-10 15:27:08 +01:00
group: postfix
perm: '400'
2016-02-21 11:18:32 +01:00
format: crt
action: '/etc/init.d/postfix reload'
2016-01-21 16:43:05 +01:00
- path: /etc/dovecot/ssl/mail.crt
user: dovecot
2016-01-10 15:27:08 +01:00
group: dovecot
perm: '400'
2016-02-21 11:18:32 +01:00
action: '/etc/init.d/dovecot reload'
2016-04-04 01:45:12 +02:00
jabber.example.com:
- path: /etc/ejabberd/server.pem
user: jabber
group: jabber
perm: '400'
format: key,crt,ca
2016-04-04 09:11:04 +02:00
action: '/etc/init.d/ejabberd restart'
2016-04-04 01:45:12 +02:00
2016-04-04 01:49:23 +02:00
www.example.com example.com:
2016-04-04 01:45:12 +02:00
- path: /var/www/ssl/cert.pem
user: apache
group: apache
perm: '400'
action: '/etc/init.d/apache2 reload'
format: crt,ca
- path: /var/www/ssl/key.pem
user: apache
group: apache
perm: '400'
action: '/etc/init.d/apache2 reload'
format: key
2016-01-10 15:27:08 +01:00
```
2016-01-10 15:56:04 +01:00
Security
--------
Please keep the following in mind when using this software:
* DO read the source code, since it is intended to be run as root
* Make sure that your configuration files are NOT writable by other users - arbitrary commands can be executed after updating certificates