github.com/teknogeek/dnscontrol/v2@v2.10.1-0.20200227202244-ae299b55ba42/docs/get-certs.md

github.com/teknogeek/dnscontrol/v2@v2.10.1-0.20200227202244-ae299b55ba42/docs/get-certs.md (about)

1 ---
2 layout: default
3 title: Let's Encrypt Certificate generation
4 ---
5
6 # *Let's Encrypt* Certificate generation
7
8 DNSControl will generate/renew Let's Encrypt certificates using DNS
9 validation. It is not a complete certificate management system, but
10 can perform the renewal steps for the system you create. If you
11 are looking for a complete system, we recommend
12 [certbot](https://certbot.eff.org/).
13
14 The `dnscontrol get-certs` command will obtain or renew TLS
15 certificates for your managed domains via
16 [*Let's Encrypt*](https://letsencrypt.org). This can be extremely useful in
17 situations where other acme clients are problematic. Specifically,
18 this may be useful if:
19
20 - You are already managing DNS records with DNSControl.
21 - You have a large number of domains or DNS providers in complicated configurations.
22 - You want **wildcard** certificates, which *require* DNS validation.
23
24 At Stack Overflow we have dual-hosted DNS i.e. zones having
25 nameservers at two different DNS providers. Most Let's Encrypt systems
26 do not support DNS validation in that case. DNSControl's `get-certs`
27 command leverages the core DNSControl commands when issueing
28 certificates, therefore dual-hosted DNS is supported.
29
30 ## General Process
31
32 The `get-certs` command does the following steps:
33
34 1. Determine which certificates you would like issued, and which names should belong to each one.
35 1. Look for existing certs on disk, and see if they have sufficient time remaining until expiration, and that the names match.
36 1. If updates are needed:
37 1. Request a new certificate from the acme server.
38 1. Receive a list of validations to fill.
39 1. For each validation (usually one per name on the cert):
40 1. Create a TXT record on the domain with a given secret value.
41 1. Wait until the authoritative name servers all return the correct value (polls locally).
42 1. Tell the acme server to validate the record.
43 1. Receive a new certificate and save it to disk
44
45 Because DNS propagation times vary from provider to provider, and
46 validations are (currently) done serially, this process may take some
47 time.
48
49 ## certs.json
50
51 This file should be provided to specify which names you would like to get certificates for. You can
52 specify any number of certificates, with up to 100 SAN entries each. Subject names can contain wildcards if you wish.
53
54 The format of the file is a simple json array of objects:
55
56 ```
57 [
58 {
59 "cert_name": "mainCert",
60 "names": [
61 "example.com.com",
62 "www.example.com"
63 ]
64 },
65 {
66 "cert_name": "wildcardCert",
67 "names": [
68 "example.com",
69 "*.example.com",
70 "*.foo.example.com",
71 "otherdomain.tld",
72 "*.otherdomain.tld"
73 ]
74 }
75 ]
76 ```
77
78 `dnscontrol get-certs` will attempt to issue any certificates referenced by this file, and will renew or re-issue if the certificate we already have is
79 close to expiry or if the set of subject names changes for a cert.
80
81 ## Working directory layout
82 The `get-certs` command is designed to be run from a working directory that contains all of the data we need,
83 and stores all of the certificates and other data we generate.
84
85 You may store this directory in source control or wherever you like. At Stack Overflow we have a dedicated repository for
86 certificates, but we take care to always encrypt any private keys with [black box](https://github.com/StackExchange/blackbox) before committing.
87
88 The working directory should generally contain:
89
90 - `certificates` folder for storing all obtained certificates.
91 - `.letsencrypt` folder for storing *Let's Encrypt* account keys, registrations, and other metadata.
92 - `certs.json` to describe what certificates to issue.
93 - `dnsconfig.js` and `creds.json` are the main files for other dnscontrol commands.
94
95 ```
96 ┏━━.letsencrypt
97 ┃ ┗━(*Let's Encrypt* account keys and metadata)
98 ┃
99 ┣━━certificates
100 ┃ ┣━━mainCert
101 ┃ ┃ ┣━mainCert.crt
102 ┃ ┃ ┣━mainCert.json
103 ┃ ┃ ┗━mainCert.key
104 ┃ ┗━━wildcardCert
105 ┃ ┣━wildcardCert.crt
106 ┃ ┣━wildcardCert.json
107 ┃ ┗━wildcardCert.key
108 ┃
109 ┣━━certs.json
110 ┣━━creds.json
111 ┗━━dnsconfig.js
112 ```
113 ## Command line flags
114
115 ### Required Flags
116
117 - `-email test@example.com`: Email address to use for *Let's Encrypt* account registration.
118 - `--agreeTOS`: Indicates that you agree to the [*Let's Encrypt* Subscriber Agreement](https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf)
119
120 ### Optional Flags
121
122 - `-acme {url}`: URL of the acme server you wish to use. For *Let's Encrypt* you can use the presets `live` or `staging` for the standard services. If you are using a custom boulder instance or other acme server, you may specify the full **directory** url. Must be an acme **v2** server.
123 - `-renew {n}`: `get-certs` will renew certs with less than this many **days** remaining. The default is 15, and certs will be renewed when they are within 15 days of expiration.
124 - `-dir {d}`: Root directory holding all certificate and account data as described above. Default is current working directory.
125 - `-certConfig {j}`: Location of certificate config json file as described above. Default is `./certs.json`
126 - `-skip {p}`: DNS Provider names (comma separated) to skip using as challenge providers. We use this to avoid unnecessary changes to our backup or internal dns providers that wouldn't be a part of the validation flow.
127 - `--verbose`: enable some extra logging from the [acme library](https://github.com/xenolf/lego) that we use.
128 - `-js {dnsconfig.js}`, `-creds {creds.json}` and other flags to find your dns configuration are the same as used for `dnscontrol preview` or `push`. `get-certs` needs to read the dns config so it knows which providers manage which domains, and so it can make sure it is not going to make any destructive changes to your domains. If the `get-certs` command needs to fill a challenge on a domain that has pending corrections, it will abort for safety. You can run `dnscontrol preview` and `dnscontrol push` at that point to verify and push the pending corrections, and then proceed with issuing certificates.
129
130 ## Workflow
131
132 This command is intended to be just a small part of a full certificate automation workflow. It only issues certificates, and explicitly does not deal with certificate storage or deployment. We urge caution to secure your private keys for your certificates, as well as the *Let's Encrypt* account private key. We use [black box](https://github.com/StackExchange/blackbox) to securely store private keys in the certificate repo.
133
134 This command is intended to be run as frequently as you desire. One workflow would be to check all certificates into a git repository and run a nightly build that:
135
136 1. Clones the cert repo, and the dns config repo (if separate).
137 2. Decrypt or otherwise obtain the *Let's Encrypt* account private key. Dnscontrol does not need to read any certificate private keys to check or issue certificates.
138 3. Run `dnscontrol get-certs` with appropriate flags.
139 4. Encrypt or store any new or updated private keys.
140 5. Commit and push any changes to the cert repo.
141 6. Take care to not leave any plain-text private keys on disk.
142
143 The push to the certificate repo can trigger further automation to deploy certs to load balancers, cdns, applications and so forth.
144
145 ## Example script
146
147 ```
148
149 #!/bin/bash
150
151 set -e
152
153 # get and decrypt the files
154 [ insert your own code here ]
155
156 dnscontrol get-certs \
157 -email "CHANGE_THIS@example.com" \
158 --acme live \
159 --skip bind --renew 31 \
160 --verbose \
161 --agreeTOS --vault --notify
162
163 # Encrypt and save the files
164 [ insert your own code here ]
165 ```