Certificates for communication within the cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Each {PVE} installation creates its own Certificate Authority (CA) and generates
-certificates for each node. These are used for encrypted communication within
-the cluster.
+Each {PVE} cluster creates its own (self-signed) Certificate Authority (CA) and
+generates a certificate for each node and signs it by the previously created CA.
+These certificates are used
+for encrypted communication with the cluster's pveproxy service and the
+Shell/Console feature if SPICE is used.
-The CA certificate and key are stored in the `pmxcfs` (see the `pmxcfs(8)`
-manpage).
+The CA certificate and key are stored in the xref:chapter_pmxcfs[Proxmox Cluster File System (pmxcfs)].
Certificates for API and web GUI
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The API and web GUI are provided by `pveproxy`.
+The REST API and web GUI are provided by the `pveproxy` service, which runs on
+each node.
You have the following options for the certificate used by `pveproxy`:
-1. By default the node-specific certificate in `/etc/pve/local/pve-ssl.pem` is
-used. This certificate is signed by the cluster CA and therfore not trusted by
-browsers and operating systems by default.
-2. use an externally provided certificate (e.g. signed by an external CA).
-3. use ACME (Let's Encrypt) to get a trusted certificate with automatic renewal.
+1. By default the node-specific certificate in
+`/etc/pve/nodes/NODENAME/pve-ssl.pem` is used. This certificate is signed by
+the cluster CA and therefore not trusted by browsers and operating systems by
+default.
+2. use an externally provided certificate (e.g. signed by a commercial CA).
+3. use ACME (e.g., Let's Encrypt) to get a trusted certificate with automatic renewal.
-For Options 2 and 3 the file `/etc/pve/local/pveproxy-ssl.pem` (and
+For options 2 and 3 the file `/etc/pve/local/pveproxy-ssl.pem` (and
`/etc/pve/local/pveproxy-ssl.key`, which needs to be without password) is used.
Certificates are managed with the {PVE} Node management command
(see the `pvenode(1)` manpage).
-WARNING: Do not replace the automatically generated node certificate
-files in `/etc/pve/local/pve-ssl.pem` and `/etc/pve/local/pve-ssl.key` or
-the cluster CA files in `/etc/pve/pve-root-ca.pem` and
-`/etc/pve/priv/pve-root-ca.key`.
+WARNING: Do not replace or manually modify the automatically generated node
+certificate files in `/etc/pve/local/pve-ssl.pem` and
+`/etc/pve/local/pve-ssl.key` or the cluster CA files in
+`/etc/pve/pve-root-ca.pem` and `/etc/pve/priv/pve-root-ca.key`.
Getting trusted certificates via ACME
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
{PVE} includes an implementation of the **A**utomatic **C**ertificate
**M**anagement **E**nvironment **ACME** protocol, allowing {pve} admins to
-interface with Let's Encrypt, with which trusted certificates can be generated
-and setup easily.
-
-This enables you to get a Certificate that is accepted by Browsers for public
-facing nodes.
+interface with Let's Encrypt for easy setup of trusted TLS certificates which
+are accepted out of the box on most modern operating systems and browsers.
Currently the two ACME endpoints implemented are Let's Encrypt (LE) and its
staging environment (see https://letsencrypt.org), both using the standalone
1. **Port 80** of the node needs to be reachable from the internet.
2. There **must** be no other listener on port 80.
-3. Your (sub)domain needs to resolve to the public IP of the Node.
+3. The requested (sub)domain needs to resolve to a public IP of the Node.
4. You have to accept the ToS of Let's Encrypt.
At the moment the GUI uses only the default ACME account.
.Example: Sample `pvenode` invocation for using Let's Encrypt certificates
------------------
+----
root@proxmox:~# pvenode acme account register default mail@example.invalid
Directory endpoints:
0) Let's Encrypt V2 (https://acme-v02.api.letsencrypt.org/directory)
Setting pveproxy certificate and key
Restarting pveproxy
Task OK
------------------
+----
+
+Switching from the `staging` to the regular ACME directory
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Changing the ACME directory for an account is unsupported. If you want to switch
+an account from the `staging` ACME directory to the regular, trusted, one you
+need to deactivate it and recreate it.
+
+This procedure is also needed to change the default ACME account used in the GUI.
+
+.Example: Changing the `default` ACME account from the `staging` to the regular directory
+
+----
+root@proxmox:~# pvenode acme account info default
+Directory URL: https://acme-staging-v02.api.letsencrypt.org/directory
+Account URL: https://acme-staging-v02.api.letsencrypt.org/acme/acct/6332194
+Terms Of Service: https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf
+
+Account information:
+ID: xxxxxxx
+Contact:
+ - mailto:example@proxmox.com
+Creation date: 2018-07-31T08:41:44.54196435Z
+Initial IP: 192.0.2.1
+Status: valid
+
+root@proxmox:~# pvenode acme account deactivate default
+Renaming account file from '/etc/pve/priv/acme/default' to '/etc/pve/priv/acme/_deactivated_default_4'
+Task OK
+
+root@proxmox:~# pvenode acme account register default example@proxmox.com
+Directory endpoints:
+0) Let's Encrypt V2 (https://acme-v02.api.letsencrypt.org/directory)
+1) Let's Encrypt V2 Staging (https://acme-staging-v02.api.letsencrypt.org/directory)
+2) Custom
+Enter selection:
+0
+
+Attempting to fetch Terms of Service from 'https://acme-v02.api.letsencrypt.org/directory'..
+Terms of Service: https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf
+Do you agree to the above terms? [y|N]y
+
+Attempting to register account with 'https://acme-v02.api.letsencrypt.org/directory'..
+Generating ACME account key..
+Registering ACME account..
+Registration successful, account URL: 'https://acme-v02.api.letsencrypt.org/acme/acct/39335247'
+Task OK
+----
+
+Automatic renewal of ACME certificates
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If a node has been successfully configured with an ACME-provided certificate
+(either via pvenode or via the GUI), the certificate will be automatically
+renewed by the pve-daily-update.service. Currently, renewal will be attempted
+if the certificate has expired or will expire in the next 30 days.
projects / pve-docs.git / blobdiff