make dinstall: skip mediawiki deb for now
[pve-docs.git] / certificate-management.adoc
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
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.
16
17 The CA certificate and key are stored in the xref:chapter_pmxcfs[Proxmox Cluster File System (pmxcfs)].
18
19 Certificates for API and web GUI
20 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
21
22 The REST API and web GUI are provided by the `pveproxy` service, which runs on
23 each node.
24
25 You have the following options for the certificate used by `pveproxy`:
26
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.
33
34 For options 2 and 3 the file `/etc/pve/local/pveproxy-ssl.pem` (and
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
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`.
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
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.
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.
63 3. The requested (sub)domain needs to resolve to a public IP of the Node.
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
70 ----
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
115 ----
116
117 Switching from the `staging` to the regular ACME directory
118 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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
128 ----
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
145
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
163 ----
164
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.