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