1 [[sysadmin_certificate_management]]
9 Certificates for communication within the cluster
10 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
12 Each {PVE} cluster creates its own (self-signed) Certificate Authority (CA) and
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.
17 The CA certificate and key are stored in the xref:chapter_pmxcfs[Proxmox Cluster File System (pmxcfs)].
19 Certificates for API and web GUI
20 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
22 The REST API and web GUI are provided by the `pveproxy` service, which runs on
25 You have the following options for the certificate used by `pveproxy`:
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
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
33 renewal, this is also integrated in the {pve} API and Webinterface.
35 For options 2 and 3 the file `/etc/pve/local/pveproxy-ssl.pem` (and
36 `/etc/pve/local/pveproxy-ssl.key`, which needs to be without password) is used.
38 NOTE: Keep in mind that `/etc/pve/local` is a node specific symlink to
39 `/etc/pve/nodes/NODENAME`.
41 Certificates are managed with the {PVE} Node management command
42 (see the `pvenode(1)` manpage).
44 WARNING: Do not replace or manually modify the automatically generated node
45 certificate files in `/etc/pve/local/pve-ssl.pem` and
46 `/etc/pve/local/pve-ssl.key` or the cluster CA files in
47 `/etc/pve/pve-root-ca.pem` and `/etc/pve/priv/pve-root-ca.key`.
49 Getting trusted certificates via ACME
50 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
51 {PVE} includes an implementation of the **A**utomatic **C**ertificate
52 **M**anagement **E**nvironment **ACME** protocol, allowing {pve} admins to
53 interface with Let's Encrypt for easy setup of trusted TLS certificates which
54 are accepted out of the box on most modern operating systems and browsers.
56 Currently the two ACME endpoints implemented are Let's Encrypt (LE) and its
57 staging environment (see https://letsencrypt.org), both using the standalone
60 Because of https://letsencrypt.org/docs/rate-limits/[rate-limits] you should use
61 LE `staging` for experiments.
63 There are a few prerequisites to use Let's Encrypt:
65 1. **Port 80** of the node needs to be reachable from the internet.
66 2. There **must** be no other listener on port 80.
67 3. The requested (sub)domain needs to resolve to a public IP of the Node.
68 4. You have to accept the ToS of Let's Encrypt.
70 At the moment the GUI uses only the default ACME account.
72 .Example: Sample `pvenode` invocation for using Let's Encrypt certificates
75 root@proxmox:~# pvenode acme account register default mail@example.invalid
77 0) Let's Encrypt V2 (https://acme-v02.api.letsencrypt.org/directory)
78 1) Let's Encrypt V2 Staging (https://acme-staging-v02.api.letsencrypt.org/directory)
83 Attempting to fetch Terms of Service from 'https://acme-staging-v02.api.letsencrypt.org/directory'..
84 Terms of Service: https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf
85 Do you agree to the above terms? [y|N]y
87 Attempting to register account with 'https://acme-staging-v02.api.letsencrypt.org/directory'..
88 Generating ACME account key..
89 Registering ACME account..
90 Registration successful, account URL: 'https://acme-staging-v02.api.letsencrypt.org/acme/acct/xxxxxxx'
92 root@proxmox:~# pvenode acme account list
94 root@proxmox:~# pvenode config set --acme domains=example.invalid
95 root@proxmox:~# pvenode acme cert order
96 Loading ACME account details
98 Order URL: https://acme-staging-v02.api.letsencrypt.org/acme/order/xxxxxxxxxxxxxx
100 Getting authorization details from
101 'https://acme-staging-v02.api.letsencrypt.org/acme/authz/xxxxxxxxxxxxxxxxxxxxx-xxxxxxxxxxxxx-xxxxxxx'
104 Triggering validation
105 Sleeping for 5 seconds
108 All domains validated!
112 Checking order status
115 Downloading certificate
116 Setting pveproxy certificate and key
121 Switching from the `staging` to the regular ACME directory
122 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
124 Changing the ACME directory for an account is unsupported. If you want to switch
125 an account from the `staging` ACME directory to the regular, trusted, one you
126 need to deactivate it and recreate it.
128 This procedure is also needed to change the default ACME account used in the GUI.
130 .Example: Changing the `default` ACME account from the `staging` to the regular directory
133 root@proxmox:~# pvenode acme account info default
134 Directory URL: https://acme-staging-v02.api.letsencrypt.org/directory
135 Account URL: https://acme-staging-v02.api.letsencrypt.org/acme/acct/6332194
136 Terms Of Service: https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf
141 - mailto:example@proxmox.com
142 Creation date: 2018-07-31T08:41:44.54196435Z
143 Initial IP: 192.0.2.1
146 root@proxmox:~# pvenode acme account deactivate default
147 Renaming account file from '/etc/pve/priv/acme/default' to '/etc/pve/priv/acme/_deactivated_default_4'
150 root@proxmox:~# pvenode acme account register default example@proxmox.com
152 0) Let's Encrypt V2 (https://acme-v02.api.letsencrypt.org/directory)
153 1) Let's Encrypt V2 Staging (https://acme-staging-v02.api.letsencrypt.org/directory)
158 Attempting to fetch Terms of Service from 'https://acme-v02.api.letsencrypt.org/directory'..
159 Terms of Service: https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf
160 Do you agree to the above terms? [y|N]y
162 Attempting to register account with 'https://acme-v02.api.letsencrypt.org/directory'..
163 Generating ACME account key..
164 Registering ACME account..
165 Registration successful, account URL: 'https://acme-v02.api.letsencrypt.org/acme/acct/39335247'
169 Automatic renewal of ACME certificates
170 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
172 If a node has been successfully configured with an ACME-provided certificate
173 (either via pvenode or via the GUI), the certificate will be automatically
174 renewed by the pve-daily-update.service. Currently, renewal will be attempted
175 if the certificate has expired already, or will expire in the next 30 days.