Polished phrasing Signed-off-by: Aaron Lauterer <a.laute...@proxmox.com> --- certificate-management.adoc | 88 +++++++++++++++++++++---------------- 1 file changed, 50 insertions(+), 38 deletions(-)
diff --git a/certificate-management.adoc b/certificate-management.adoc index 81660b2..d128c30 100644 --- a/certificate-management.adoc +++ b/certificate-management.adoc @@ -9,61 +9,70 @@ endif::wiki[] Certificates for communication within the cluster ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Each {PVE} cluster creates its own (self-signed) Certificate Authority (CA) and -generates a certificate for each node which gets signed by the aforementioned -CA. These certificates are used for encrypted communication with the cluster's -`pveproxy` service and the Shell/Console feature if SPICE is used. +Each {PVE} cluster creates its own (self-signed) Certificate Authority +(CA). For each node a certificate is created and signed by the CA. +These certificates are used for the encrypted communication within the +cluster. In particular for the `pveproxy` service and the +Shell/Console features if SPICE is used. -The CA certificate and key are stored in the xref:chapter_pmxcfs[Proxmox Cluster File System (pmxcfs)]. +The CAs certificate and key are stored in the +xref:chapter_pmxcfs[Proxmox Cluster File System (pmxcfs)]. Certificates for API and web GUI ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The REST API and web GUI are provided by the `pveproxy` service, which runs on -each node. +The REST API and web based GUI are provided by the `pveproxy` service +which runs on each node. -You have the following options for the certificate used by `pveproxy`: +The following options are available for the certificate used by +`pveproxy`: 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 -`/etc/pve/local/pveproxy-ssl.key`, which needs to be without password) is used. +`/etc/pve/nodes/NODENAME/pve-ssl.pem` is used. This certificate is +signed by the cluster CA and therefore is 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., https://letsencrypt.org/[Let's Encrypt]) to get a +trusted certificate with automatic renewal. + +If option 2 or 3 are used the certificate has to be stored in +`/etc/pve/local/pveproxy-ssl.pem`. The accompanying key file has to be +stored in `/etc/pve/local/pveproxy-ssl.key` and should not have a +password set. Certificates are managed with the {PVE} Node management command (see the `pvenode(1)` manpage). -WARNING: Do not replace or manually modify the automatically generated node -certificate files in `/etc/pve/local/pve-ssl.pem` and +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 for easy setup of trusted TLS certificates which -are accepted out of the box on most modern operating systems and browsers. +**M**anagement **E**nvironment (ACME) protocol. This enables {pve} +admins to interface with https://letsencrypt.org/[Let's Encrypt] for +an 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 -HTTP challenge. +Currently the two ACME endpoints implemented are Let's Encrypt (LE) +and its `staging` environment (see https://letsencrypt.org), both use +the standalone HTTP challenge. -Because of https://letsencrypt.org/docs/rate-limits/[rate-limits] you should use -LE `staging` for experiments. +Because of https://letsencrypt.org/docs/rate-limits/[rate-limits] you +should use Let's Encrypts `staging` endpoint for experiments. 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. The requested (sub)domain needs to resolve to a 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. +At the moment the GUI uses the default ACME account. .Example: Sample `pvenode` invocation for using Let's Encrypt certificates @@ -114,14 +123,16 @@ Restarting pveproxy Task OK ---- -Switching from the `staging` to the regular ACME directory -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Switching from the `staging` to the regular ACME endpoint +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -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. +Changing the ACME endpoint for an account is not supported. If an +account needs to be switched from the `staging` endpoint to the +regular, trusted, one it first needs to be deactivated and then +recreated. -This procedure is also needed to change the default ACME account used in the GUI. +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 @@ -165,7 +176,8 @@ 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. +If a node has been successfully configured with an ACME-provided +certificate (either via `pvenode` or via the GUI), the certificate +will automatically be renewed by the `pve-daily-update.service`. +Currently renewal will be attempted if the certificate has expired or +will expire within the next 30 days. -- 2.20.1 _______________________________________________ pve-devel mailing list pve-devel@pve.proxmox.com https://pve.proxmox.com/cgi-bin/mailman/listinfo/pve-devel