X-Git-Url: https://git.proxmox.com/?p=pve-docs.git;a=blobdiff_plain;f=certificate-managment.adoc;h=7970f61c396724e404295b199e275aa571adb2ed;hp=819745efa1351e75b5ada77ac02f51bfdc90e605;hb=94958b8b9230d5b9b5e2e70c481f115b18a5fa0b;hpb=aeecd9ea39bc5cbd84244cff34c7daba1045a1fb diff --git a/certificate-managment.adoc b/certificate-managment.adoc index 819745e..7970f61 100644 --- a/certificate-managment.adoc +++ b/certificate-managment.adoc @@ -9,46 +9,46 @@ endif::wiki[] 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 @@ -61,14 +61,14 @@ There are a few prerequisites to use Let's Encrypt: 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) @@ -113,4 +113,60 @@ Downloading certificate 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.