1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
|
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.
|
