]>
Commit | Line | Data |
---|---|---|
8c889e95 TL |
1 | [[sysadmin_certificate_management]] |
2 | Certificate Management | |
3 | ---------------------- | |
81b3c41f | 4 | |
b908760c DW |
5 | Access to the web-based administration interface is always encrypted through |
6 | `https`. Each {pmg} host creates by default its own (self-signed) certificate. | |
c7fd1dd8 | 7 | This certificate is used for encrypted communication with the host's `pmgproxy` |
b908760c DW |
8 | service, for any API call between a user and the web-interface or between nodes |
9 | in a cluster. | |
c7fd1dd8 TL |
10 | |
11 | Certificate verification in a {pmg} cluster is done based on pinning the | |
12 | certificate fingerprints in the cluster configuration and verifying that they | |
13 | match on connection. | |
8c889e95 TL |
14 | |
15 | [[sysadmin_certs_api_gui]] | |
16 | Certificates for the API and SMTP | |
17 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
18 | ||
b908760c | 19 | {pmg} uses two different certificates: |
8c889e95 TL |
20 | |
21 | * `/etc/pmg/pmg-api.pem`: the required certificate used for {pmg} API requests. | |
22 | * `/etc/pmg/pmg-tls.pem`: the optional certificate used for SMTP TLS | |
23 | connections, see xref:pmgconfig_mailproxy_tls[mailproxy TLS configuration] | |
24 | for details. | |
25 | ||
b908760c | 26 | You have the following options for these certificates: |
8c889e95 | 27 | |
b908760c DW |
28 | 1. Keep using the default self-signed certificate in `/etc/pmg/pmg-api.pem`. |
29 | 2. Use an externally provided certificate (for example, signed by a commercial | |
8c889e95 | 30 | Certificate Authority (CA)). |
b908760c DW |
31 | 3. Use an ACME provider like Let's Encrypt to get a trusted certificate with |
32 | automatic renewal; this is also integrated in the {pmg} API and web interface. | |
8c889e95 TL |
33 | |
34 | Certificates are managed through the {pmg} web-interface/API or using the | |
35 | the `pmgconfig` CLI tool. | |
36 | ||
37 | [[sysadmin_certs_upload_custom]] | |
38 | Upload Custom Certificate | |
39 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
40 | ||
41 | If you already have a certificate which you want to use for a {pmg} host, you | |
b908760c | 42 | can simply upload that certificate over the web interface. |
8c889e95 TL |
43 | |
44 | [thumbnail="pmg-gui-certs-upload-custom.png"] | |
45 | ||
ce64ae40 | 46 | Note that any certificate key files must not be password protected. |
8c889e95 TL |
47 | |
48 | [[sysadmin_certs_get_trusted_acme_cert]] | |
49 | Trusted certificates via Let's Encrypt (ACME) | |
50 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
51 | ||
52 | {PMG} includes an implementation of the **A**utomatic **C**ertificate | |
b908760c DW |
53 | **M**anagement **E**nvironment (**ACME**) protocol, allowing {pmg} admins to |
54 | use an ACME provider like Let's Encrypt for easy setup of TLS certificates, | |
55 | which are accepted and trusted by modern operating systems and web browsers | |
d7457185 | 56 | out of the box. |
8c889e95 | 57 | |
c7fd1dd8 | 58 | Currently, the two ACME endpoints implemented are the |
b908760c DW |
59 | https://letsencrypt.org[Let's Encrypt (LE)] production and staging |
60 | environments. Our ACME client supports validation of `http-01` challenges using | |
c7fd1dd8 | 61 | a built-in web server and validation of `dns-01` challenges using a DNS plugin |
8c889e95 TL |
62 | supporting all the DNS API endpoints https://acme.sh[acme.sh] does. |
63 | ||
64 | [[sysadmin_certs_acme_account]] | |
65 | ACME Account | |
66 | ^^^^^^^^^^^^ | |
67 | ||
68 | [thumbnail="pmg-gui-acme-create-account.png"] | |
69 | ||
b908760c DW |
70 | You need to register an ACME account per cluster, with the endpoint you want to |
71 | use. The email address used for that account will serve as the contact point for | |
8c889e95 TL |
72 | renewal-due or similar notifications from the ACME endpoint. |
73 | ||
74 | You can register or deactivate ACME accounts over the web interface | |
75 | `Certificates -> ACME Accounts` or using the `pmgconfig` command line tool. | |
76 | ---- | |
77 | pmgconfig acme account register <account-name> <mail@example.com> | |
78 | ---- | |
79 | ||
80 | TIP: Because of https://letsencrypt.org/docs/rate-limits/[rate-limits] you | |
81 | should use LE `staging` for experiments or if you use ACME for the very first | |
82 | time until all is working there, and only then switch over to the production | |
83 | directory. | |
84 | ||
85 | [[sysadmin_certs_acme_plugins]] | |
86 | ACME Plugins | |
87 | ^^^^^^^^^^^^ | |
88 | ||
b908760c | 89 | The ACME plugin's role is to provide automatic verification that you, and thus |
8c889e95 | 90 | the {pmg} cluster under your operation, are the real owner of a domain. This is |
b908760c | 91 | the basic building block of automatic certificate management. |
8c889e95 TL |
92 | |
93 | The ACME protocol specifies different types of challenges, for example the | |
b908760c | 94 | `http-01`, where a web server provides a file with a specific token to prove |
c7fd1dd8 | 95 | that it controls a domain. Sometimes this isn't possible, either because of |
d7457185 | 96 | technical limitations or if the address of a record is not reachable from the |
b908760c | 97 | public internet. The `dns-01` challenge can be used in such cases. This |
d7457185 | 98 | challenge is fulfilled by creating a certain DNS record in the domain's zone. |
8c889e95 TL |
99 | |
100 | [thumbnail="pmg-gui-acme-create-challenge-plugin.png"] | |
101 | ||
c7fd1dd8 TL |
102 | {pmg} supports both of those challenge types out of the box, you can configure |
103 | plugins either over the web interface under `Certificates -> ACME Challenges`, | |
104 | or using the `pmgconfig acme plugin add` command. | |
8c889e95 | 105 | |
c7fd1dd8 | 106 | ACME Plugin configurations are stored in `/etc/pmg/acme/plugins.cfg`. |
8c889e95 TL |
107 | A plugin is available for all nodes in the cluster. |
108 | ||
109 | Domains | |
110 | ^^^^^^^ | |
111 | ||
112 | You can add new or manage existing domain entries under `Certificates`, or | |
113 | using the `pmgconfig` command. | |
114 | ||
115 | [thumbnail="pmg-gui-acme-add-domain.png"] | |
116 | ||
117 | After configuring the desired domain(s) for a node and ensuring that the | |
118 | desired ACME account is selected, you can order your new certificate over the | |
b908760c | 119 | web-interface. On success, the interface will reload after roughly 10 seconds. |
8c889e95 TL |
120 | |
121 | Renewal will happen xref:sysadmin_certs_acme_automatic_renewal[automatically]. | |
122 | ||
123 | [[sysadmin_certs_acme_http_challenge]] | |
124 | ACME HTTP Challenge Plugin | |
125 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
126 | ||
127 | There is always an implicitly configured `standalone` plugin for validating | |
b908760c | 128 | `http-01` challenges via the built-in web server spawned on port 80. |
8c889e95 | 129 | |
b908760c DW |
130 | NOTE: The name `standalone` means that it can provide the validation on its |
131 | own, without any third party service. So this plugin also works for cluster | |
8c889e95 TL |
132 | nodes. |
133 | ||
b908760c | 134 | There are a few prerequisites to use this for certificate management with Let's |
8c889e95 TL |
135 | Encrypts ACME. |
136 | ||
137 | * You have to accept the ToS of Let's Encrypt to register an account. | |
138 | * **Port 80** of the node needs to be reachable from the internet. | |
139 | * There **must** be no other listener on port 80. | |
140 | * The requested (sub)domain needs to resolve to a public IP of the {pmg} host. | |
141 | ||
142 | ||
143 | [[sysadmin_certs_acme_dns_challenge]] | |
144 | ACME DNS API Challenge Plugin | |
145 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
146 | ||
147 | On systems where external access for validation via the `http-01` method is | |
148 | not possible or desired, it is possible to use the `dns-01` validation method. | |
149 | This validation method requires a DNS server that allows provisioning of `TXT` | |
150 | records via an API. | |
151 | ||
152 | [[sysadmin_certs_acme_dns_api_config]] | |
153 | Configuring ACME DNS APIs for validation | |
154 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
155 | ||
c7fd1dd8 | 156 | {pmg} re-uses the DNS plugins developed for the `acme.sh` |
b908760c | 157 | footnote:[acme.sh https://github.com/acmesh-official/acme.sh] project. Please |
c7fd1dd8 | 158 | refer to its documentation for details on configuration of specific APIs. |
8c889e95 TL |
159 | |
160 | The easiest way to configure a new plugin with the DNS API is using the web | |
161 | interface (`Certificates -> ACME Accounts/Challenges`). | |
162 | ||
163 | [thumbnail="pmg-gui-acme-create-challenge-plugin.png"] | |
164 | ||
b908760c DW |
165 | Here you can add a new challenge plugin by selecting your API provider and |
166 | entering the credential data to access your account over their API. | |
8c889e95 TL |
167 | |
168 | TIP: See the acme.sh | |
169 | https://github.com/acmesh-official/acme.sh/wiki/dnsapi#how-to-use-dns-api[How to use DNS API] | |
170 | wiki for more detailed information about getting API credentials for your | |
171 | provider. Configuration values do not need to be quoted with single or double | |
b908760c | 172 | quotes; for some plugins that is even an error. |
8c889e95 | 173 | |
b908760c DW |
174 | As there are many DNS providers and API endpoints, {pmg} automatically generates |
175 | the form for the credentials, but not all providers are annotated yet. For those | |
176 | you will see a bigger text area, into which you simply need to copy all the | |
177 | credential's `KEY`=`VALUE` pairs. | |
8c889e95 TL |
178 | |
179 | DNS Validation through CNAME Alias | |
180 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
181 | ||
b908760c | 182 | A special `alias` mode can be used to handle validation on a different |
8c889e95 TL |
183 | domain/DNS server, in case your primary/real DNS does not support provisioning |
184 | via an API. Manually set up a permanent `CNAME` record for | |
b908760c | 185 | `_acme-challenge.domain1.example` pointing to `_acme-challenge.domain2.example`, |
8c889e95 TL |
186 | and set the `alias` property in the {pmg} node configuration file |
187 | `/etc/pmg/node.conf` to `domain2.example` to allow the DNS server of | |
188 | `domain2.example` to validate all challenges for `domain1.example`. | |
189 | ||
3419e609 SI |
190 | [[sysadmin_certs_acme_dns_wildcard]] |
191 | Wildcard Certificates | |
192 | ^^^^^^^^^^^^^^^^^^^^^ | |
193 | ||
194 | Wildcard DNS names start with a `*.` prefix and are considered valid for all | |
195 | (one-level) subdomain names of the verified domain. So a certificate for | |
b908760c | 196 | `*.domain.example` is valid for `foo.domain.example` and |
3419e609 SI |
197 | `bar.domain.example`, but not for `baz.foo.domain.example`. |
198 | ||
b908760c | 199 | Currently, you can only create wildcard certificates with the |
3419e609 SI |
200 | https://letsencrypt.org/docs/challenge-types/#dns-01-challenge[DNS challenge type]. |
201 | ||
8c889e95 TL |
202 | |
203 | Combination of Plugins | |
204 | ^^^^^^^^^^^^^^^^^^^^^^ | |
205 | ||
206 | Combining `http-01` and `dns-01` validation is possible in case your node is | |
207 | reachable via multiple domains with different requirements / DNS provisioning | |
208 | capabilities. Mixing DNS APIs from multiple providers or instances is also | |
209 | possible by specifying different plugin instances per domain. | |
210 | ||
211 | TIP: Accessing the same service over multiple domains increases complexity and | |
212 | should be avoided if possible. | |
213 | ||
214 | [[sysadmin_certs_acme_automatic_renewal]] | |
215 | Automatic renewal of ACME certificates | |
216 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
217 | ||
218 | If a node has been successfully configured with an ACME-provided certificate | |
219 | (either via pmgconfig or via the web-interface/API), the certificate will be | |
b908760c DW |
220 | renewed automatically by the `pmg-daily.service`. Currently, renewal is |
221 | triggered if the certificate either has already expired or if it will expire in | |
222 | the next 30 days. | |
8c889e95 TL |
223 | |
224 | Manually Change Certificate over Command-Line | |
225 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
81b3c41f | 226 | |
ce64ae40 SI |
227 | If you want to get rid of certificate verification warnings, you have to |
228 | generate a valid certificate for your server. | |
81b3c41f | 229 | |
b908760c | 230 | Log in to your {pmg} via ssh or use the console: |
81b3c41f DM |
231 | |
232 | ---- | |
233 | openssl req -newkey rsa:2048 -nodes -keyout key.pem -out req.pem | |
234 | ---- | |
235 | ||
b908760c | 236 | Follow the instructions on the screen, for example: |
81b3c41f DM |
237 | |
238 | ---- | |
239 | Country Name (2 letter code) [AU]: AT | |
240 | State or Province Name (full name) [Some-State]:Vienna | |
241 | Locality Name (eg, city) []:Vienna | |
242 | Organization Name (eg, company) [Internet Widgits Pty Ltd]: Proxmox GmbH | |
243 | Organizational Unit Name (eg, section) []:Proxmox Mail Gateway | |
244 | Common Name (eg, YOUR name) []: yourproxmox.yourdomain.com | |
245 | Email Address []:support@yourdomain.com | |
246 | ||
247 | Please enter the following 'extra' attributes to be sent with your certificate request | |
248 | A challenge password []: not necessary | |
249 | An optional company name []: not necessary | |
250 | ---- | |
251 | ||
b908760c | 252 | After you have finished the certificate request, you have to send the file |
81b3c41f | 253 | `req.pem` to your Certification Authority (CA). The CA will issue the |
b908760c | 254 | certificate (BASE64 encoded), based on your request – save this file as |
f7198e12 | 255 | `cert.pem` to your {pmg}. |
81b3c41f | 256 | |
f7198e12 | 257 | To activate the new certificate, do the following on your {pmg}: |
81b3c41f DM |
258 | |
259 | ---- | |
260 | cat key.pem cert.pem >/etc/pmg/pmg-api.pem | |
261 | ---- | |
262 | ||
f7198e12 | 263 | Then restart the API servers: |
81b3c41f DM |
264 | |
265 | ---- | |
266 | systemctl restart pmgproxy | |
267 | ---- | |
268 | ||
b908760c | 269 | Test your new certificate, using your browser. |
81b3c41f | 270 | |
b908760c DW |
271 | NOTE: To transfer files to and from your {pmg}, you can use secure copy: If your |
272 | desktop runs Linux, you can use the `scp` command line tool. If your desktop PC | |
273 | runs windows, please use an scp client like WinSCP (see https://winscp.net/). | |
0fe083dc DM |
274 | |
275 | Change Certificate for Cluster Setups | |
276 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
277 | ||
8c889e95 TL |
278 | If you change the API certificate of an active cluster node manually, you also |
279 | need to update the pinned fingerprint inside the cluster configuration. | |
0fe083dc | 280 | |
8c889e95 TL |
281 | You can do that by executing the following command on the host where the |
282 | certificate changed: | |
0fe083dc DM |
283 | |
284 | ---- | |
8c889e95 | 285 | pmgcm update-fingerprints |
0fe083dc | 286 | ---- |
8c889e95 TL |
287 | |
288 | Note, this will be done automatically if using the integrated ACME (for | |
289 | example, through Let's Encrypt) feature. |