[pve-devel] [PATCH docs 10/10] Rewrite Certificate Management

[Aaron Lauterer]

Polished phrasing

Signed-off-by: Aaron Lauterer <a.lauterer at 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