maddy

  1# Automatic certificate management via ACME
  2
  3Maddy supports obtaining certificates using ACME protocol.
  4
  5To use it, create a configuration name for `tls.loader.acme`
  6and reference it from endpoints that should use automatically
  7configured certificates:
  8
  9```
 10tls.loader.acme local_tls {
 11    email put-your-email-here@example.org
 12    agreed # indicate your agreement with Let's Encrypt ToS
 13    challenge dns-01
 14}
 15
 16smtp tcp://127.0.0.1:25 {
 17    tls &local_tls
 18    ...
 19}
 20```
 21
 22You can also use a global `tls` directive to use automatically
 23obtained certificates for all endpoints:
 24
 25```
 26tls {
 27    loader acme {
 28        email maddy-acme@example.org
 29        agreed
 30        challenge dns-01
 31    }
 32}
 33```
 34
 35Note: `tls &local_tls` as a global directive won't work because
 36global directives are initialized before other configuration blocks.
 37
 38Currently the only supported challenge is `dns-01` one therefore
 39you also need to configure the DNS provider:
 40
 41```
 42tls.loader.acme local_tls {
 43    email maddy-acme@example.org
 44    agreed
 45    challenge dns-01
 46    dns PROVIDER_NAME {
 47        ...
 48    }
 49}
 50```
 51
 52See below for supported providers and necessary configuration
 53for each.
 54
 55## Configuration directives
 56
 57```
 58tls.loader.acme {
 59    debug off
 60    hostname example.maddy.invalid
 61    store_path /var/lib/maddy/acme
 62    ca https://acme-v02.api.letsencrypt.org/directory
 63    test_ca https://acme-staging-v02.api.letsencrypt.org/directory
 64    email test@maddy.invalid
 65    agreed off
 66    challenge dns-01
 67    dns ...
 68}
 69```
 70
 71### debug _boolean_
 72Default: global directive value
 73
 74Enable debug logging.
 75
 76---
 77
 78### hostname _str_
 79**Required.**<br>
 80Default: global directive value
 81
 82Domain name to issue certificate for.
 83
 84---
 85
 86### store_path _path_
 87Default: `state_dir/acme`
 88
 89Where to store issued certificates and associated metadata.
 90Currently only filesystem-based store is supported.
 91
 92---
 93
 94### ca _url_
 95Default: Let's Encrypt production CA
 96
 97URL of ACME directory to use.
 98
 99---
100
101### test_ca _url_
102Default: Let's Encrypt staging CA
103
104URL of ACME directory to use for retries should
105primary CA fail.
106
107maddy will keep attempting to issues certificates
108using `test_ca` until it succeeds then it will switch
109back to the one configured via 'ca' option.
110
111This avoids rate limit issues with production CA.
112
113---
114
115### override_domain _domain_
116Default: not set
117
118Override the domain to set the TXT record on for DNS-01 challenge.
119This is to delegate the challenge to a different domain.
120
121See https://www.eff.org/deeplinks/2018/02/technical-deep-dive-securing-automation-acme-dns-challenge-validation
122for explanation why this might be useful.
123
124---
125
126### email _str_
127Default: not set
128
129Email to pass while registering an ACME account.
130
131---
132
133### agreed _boolean_
134Default: false
135
136Whether you agreed to ToS of the CA service you are using.
137
138---
139
140### challenge `dns-01`
141Default: not set
142
143Challenge(s) to use while performing domain verification.
144
145## DNS providers
146
147Support for some providers is not provided by standard builds.
148To be able to use these, you need to compile maddy
149with "libdns_PROVIDER" build tag.
150E.g.
151```
152./build.sh --tags 'libdns_googleclouddns'
153```
154
155- gandi
156
157```
158dns gandi {
159    api_token "token"
160}
161```
162
163- digitalocean
164
165```
166dns digitalocean {
167    api_token "..."
168}
169```
170
171- cloudflare
172
173See [https://github.com/libdns/cloudflare#authenticating](https://github.com/libdns/cloudflare#authenticating)
174
175```
176dns cloudflare {
177    api_token "..."
178}
179```
180
181- vultr
182
183```
184dns vultr {
185    api_token "..."
186}
187```
188
189- hetzner
190
191```
192dns hetzner {
193    api_token "..."
194}
195```
196
197- namecheap
198
199```
200dns namecheap {
201    api_key "..."
202    api_username "..."
203
204    # optional: API endpoint, production one is used if not set.
205    endpoint "https://api.namecheap.com/xml.response"
206
207    # optional: your public IP, discovered using icanhazip.com if not set
208    client_ip 1.2.3.4
209}
210```
211
212- googleclouddns (non-default)
213
214```
215dns googleclouddns {
216    project "project_id"
217    service_account_json "path"
218}
219```
220
221- route53 (non-default)
222
223```
224dns route53 {
225    secret_access_key "..."
226    access_key_id "..."
227    # or use environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
228}
229```
230
231- leaseweb (non-default)
232
233```
234dns leaseweb {
235    api_key "key"
236}
237```
238
239- metaname (non-default)
240
241```
242dns metaname {
243    api_key "key"
244    account_ref "reference"
245}
246```
247
248- alidns (non-default)
249
250```
251dns alidns {
252    key_id "..."
253    key_secret "..."
254}
255```
256
257- namedotcom (non-default)
258
259```
260dns namedotcom {
261    user "..."
262    token "..."
263}
264```
265
266- rfc2136 (non-default)
267
268```
269dns rfc2136 {
270    key_name "..."
271    # Secret
272    key "..."
273    # HMAC algorithm used to generate the key, lowercase, e.g. hmac-sha512
274    key_alg "..."
275    # server to which the dynamic update will be sent, e.g. 127.0.0.1
276    # you can also specify the port: 127.0.0.1:53
277    server "..."
278}
279```
280
281- acmedns (non-default)
282
283```
284dns acmedns {
285    username "..."
286    password "..."
287    subdomain "..."
288    server_url "..."
289}
290```