]>
Commit | Line | Data |
---|---|---|
aeecd9ea SI |
1 | [[sysadmin_certificate_management]] |
2 | Certificate Management | |
3 | ---------------------- | |
4 | ifdef::wiki[] | |
5 | :pve-toplevel: | |
6 | endif::wiki[] | |
7 | ||
8 | ||
9 | Certificates for communication within the cluster | |
10 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
11 | ||
94958b8b | 12 | Each {PVE} cluster creates its own (self-signed) Certificate Authority (CA) and |
1a58a3c9 TL |
13 | generates a certificate for each node which gets signed by the aforementioned |
14 | CA. These certificates are used for encrypted communication with the cluster's | |
15 | `pveproxy` service and the Shell/Console feature if SPICE is used. | |
aeecd9ea | 16 | |
2971c735 | 17 | The CA certificate and key are stored in the xref:chapter_pmxcfs[Proxmox Cluster File System (pmxcfs)]. |
aeecd9ea SI |
18 | |
19 | Certificates for API and web GUI | |
20 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
21 | ||
0e9c6c13 FG |
22 | The REST API and web GUI are provided by the `pveproxy` service, which runs on |
23 | each node. | |
aeecd9ea SI |
24 | |
25 | You have the following options for the certificate used by `pveproxy`: | |
26 | ||
0e9c6c13 FG |
27 | 1. By default the node-specific certificate in |
28 | `/etc/pve/nodes/NODENAME/pve-ssl.pem` is used. This certificate is signed by | |
29 | the cluster CA and therefore not trusted by browsers and operating systems by | |
30 | default. | |
31 | 2. use an externally provided certificate (e.g. signed by a commercial CA). | |
32 | 3. use ACME (e.g., Let's Encrypt) to get a trusted certificate with automatic renewal. | |
aeecd9ea | 33 | |
0e9c6c13 | 34 | For options 2 and 3 the file `/etc/pve/local/pveproxy-ssl.pem` (and |
aeecd9ea SI |
35 | `/etc/pve/local/pveproxy-ssl.key`, which needs to be without password) is used. |
36 | ||
37 | Certificates are managed with the {PVE} Node management command | |
38 | (see the `pvenode(1)` manpage). | |
39 | ||
0e9c6c13 FG |
40 | WARNING: Do not replace or manually modify the automatically generated node |
41 | certificate files in `/etc/pve/local/pve-ssl.pem` and | |
42 | `/etc/pve/local/pve-ssl.key` or the cluster CA files in | |
43 | `/etc/pve/pve-root-ca.pem` and `/etc/pve/priv/pve-root-ca.key`. | |
aeecd9ea SI |
44 | |
45 | Getting trusted certificates via ACME | |
46 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
47 | {PVE} includes an implementation of the **A**utomatic **C**ertificate | |
48 | **M**anagement **E**nvironment **ACME** protocol, allowing {pve} admins to | |
0e9c6c13 FG |
49 | interface with Let's Encrypt for easy setup of trusted TLS certificates which |
50 | are accepted out of the box on most modern operating systems and browsers. | |
aeecd9ea SI |
51 | |
52 | Currently the two ACME endpoints implemented are Let's Encrypt (LE) and its | |
53 | staging environment (see https://letsencrypt.org), both using the standalone | |
54 | HTTP challenge. | |
55 | ||
56 | Because of https://letsencrypt.org/docs/rate-limits/[rate-limits] you should use | |
57 | LE `staging` for experiments. | |
58 | ||
59 | There are a few prerequisites to use Let's Encrypt: | |
60 | ||
61 | 1. **Port 80** of the node needs to be reachable from the internet. | |
62 | 2. There **must** be no other listener on port 80. | |
0e9c6c13 | 63 | 3. The requested (sub)domain needs to resolve to a public IP of the Node. |
aeecd9ea SI |
64 | 4. You have to accept the ToS of Let's Encrypt. |
65 | ||
66 | At the moment the GUI uses only the default ACME account. | |
67 | ||
68 | .Example: Sample `pvenode` invocation for using Let's Encrypt certificates | |
69 | ||
b0014034 | 70 | ---- |
aeecd9ea SI |
71 | root@proxmox:~# pvenode acme account register default mail@example.invalid |
72 | Directory endpoints: | |
73 | 0) Let's Encrypt V2 (https://acme-v02.api.letsencrypt.org/directory) | |
74 | 1) Let's Encrypt V2 Staging (https://acme-staging-v02.api.letsencrypt.org/directory) | |
75 | 2) Custom | |
76 | Enter selection: | |
77 | 1 | |
78 | ||
79 | Attempting to fetch Terms of Service from 'https://acme-staging-v02.api.letsencrypt.org/directory'.. | |
80 | Terms of Service: https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf | |
81 | Do you agree to the above terms? [y|N]y | |
82 | ||
83 | Attempting to register account with 'https://acme-staging-v02.api.letsencrypt.org/directory'.. | |
84 | Generating ACME account key.. | |
85 | Registering ACME account.. | |
86 | Registration successful, account URL: 'https://acme-staging-v02.api.letsencrypt.org/acme/acct/xxxxxxx' | |
87 | Task OK | |
88 | root@proxmox:~# pvenode acme account list | |
89 | default | |
90 | root@proxmox:~# pvenode config set --acme domains=example.invalid | |
91 | root@proxmox:~# pvenode acme cert order | |
92 | Loading ACME account details | |
93 | Placing ACME order | |
94 | Order URL: https://acme-staging-v02.api.letsencrypt.org/acme/order/xxxxxxxxxxxxxx | |
95 | ||
96 | Getting authorization details from | |
97 | 'https://acme-staging-v02.api.letsencrypt.org/acme/authz/xxxxxxxxxxxxxxxxxxxxx-xxxxxxxxxxxxx-xxxxxxx' | |
98 | ... pending! | |
99 | Setting up webserver | |
100 | Triggering validation | |
101 | Sleeping for 5 seconds | |
102 | Status is 'valid'! | |
103 | ||
104 | All domains validated! | |
105 | ||
106 | Creating CSR | |
107 | Finalizing order | |
108 | Checking order status | |
109 | valid! | |
110 | ||
111 | Downloading certificate | |
112 | Setting pveproxy certificate and key | |
113 | Restarting pveproxy | |
114 | Task OK | |
d75e644b | 115 | ---- |
0e9c6c13 | 116 | |
19b04e77 | 117 | Switching from the `staging` to the regular ACME directory |
b0014034 | 118 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
19b04e77 SI |
119 | |
120 | Changing the ACME directory for an account is unsupported. If you want to switch | |
121 | an account from the `staging` ACME directory to the regular, trusted, one you | |
122 | need to deactivate it and recreate it. | |
123 | ||
124 | This procedure is also needed to change the default ACME account used in the GUI. | |
125 | ||
126 | .Example: Changing the `default` ACME account from the `staging` to the regular directory | |
127 | ||
d75e644b | 128 | ---- |
19b04e77 SI |
129 | root@proxmox:~# pvenode acme account info default |
130 | Directory URL: https://acme-staging-v02.api.letsencrypt.org/directory | |
131 | Account URL: https://acme-staging-v02.api.letsencrypt.org/acme/acct/6332194 | |
132 | Terms Of Service: https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf | |
133 | ||
134 | Account information: | |
135 | ID: xxxxxxx | |
136 | Contact: | |
137 | - mailto:example@proxmox.com | |
138 | Creation date: 2018-07-31T08:41:44.54196435Z | |
139 | Initial IP: 192.0.2.1 | |
140 | Status: valid | |
141 | ||
142 | root@proxmox:~# pvenode acme account deactivate default | |
143 | Renaming account file from '/etc/pve/priv/acme/default' to '/etc/pve/priv/acme/_deactivated_default_4' | |
144 | Task OK | |
d75e644b | 145 | |
19b04e77 SI |
146 | root@proxmox:~# pvenode acme account register default example@proxmox.com |
147 | Directory endpoints: | |
148 | 0) Let's Encrypt V2 (https://acme-v02.api.letsencrypt.org/directory) | |
149 | 1) Let's Encrypt V2 Staging (https://acme-staging-v02.api.letsencrypt.org/directory) | |
150 | 2) Custom | |
151 | Enter selection: | |
152 | 0 | |
153 | ||
154 | Attempting to fetch Terms of Service from 'https://acme-v02.api.letsencrypt.org/directory'.. | |
155 | Terms of Service: https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf | |
156 | Do you agree to the above terms? [y|N]y | |
157 | ||
158 | Attempting to register account with 'https://acme-v02.api.letsencrypt.org/directory'.. | |
159 | Generating ACME account key.. | |
160 | Registering ACME account.. | |
161 | Registration successful, account URL: 'https://acme-v02.api.letsencrypt.org/acme/acct/39335247' | |
162 | Task OK | |
d75e644b | 163 | ---- |
19b04e77 | 164 | |
0e9c6c13 FG |
165 | Automatic renewal of ACME certificates |
166 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
167 | ||
168 | If a node has been successfully configured with an ACME-provided certificate | |
169 | (either via pvenode or via the GUI), the certificate will be automatically | |
170 | renewed by the pve-daily-update.service. Currently, renewal will be attempted | |
171 | if the certificate has expired or will expire in the next 30 days. |