more ACME documentation

Signed-off-by: Fabian Grünbichler <f.gruenbichler@proxmox.com>

diff --git a/certificate-managment.adoc b/certificate-managment.adoc
index 819745efa1351e75b5ada77ac02f51bfdc90e605..a219adb4c1f711fdb823855731144a86ef470ef0 100644 (file)
--- a/certificate-managment.adoc
+++ b/certificate-managment.adoc
@@ -9,9 +9,10 @@ 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 internal Certificate Authority (CA) and
+generates a self-signed certificate for each node. 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).
@@ -19,36 +20,35 @@ manpage).
 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,7 +61,7 @@ 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.
@@ -114,3 +114,11 @@ Setting pveproxy certificate and key
 Restarting pveproxy
 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.

diff --git a/pvenode.adoc b/pvenode.adoc
index 073a30180a25e6a1df4a40a0f8e0c613c9268832..6badd8d8e0ae967a2d0fe833fb6333e517d146bf 100644 (file)
--- a/pvenode.adoc
+++ b/pvenode.adoc
@@ -6,7 +6,7 @@ pvenode(1)
 NAME
 ----
 
-pvenode - {PVE} Node Management
+pvenode - Proxmox VE Node Management
 
 SYNOPSIS
 --------
@@ -23,7 +23,7 @@ Proxmox Node Management
 :pve-toplevel:
 endif::manvolnum[]
 
-The {PVE} node management tools (`pvenode`) allows to control node specific
+The {PVE} node management tool (`pvenode`) allows to control node specific
 settings and resources.
 
 Currently `pvenode` allows to set a node's description and to manage
@@ -44,7 +44,7 @@ pvenode acme cert order
 systemctl restart pveproxy
 -----
 
-Configure acme to get certificates.
+Setup ACME account and order a certificate for local node.
 
 // TODO: extend and improve chapter!
 

diff --git a/pveproxy.adoc b/pveproxy.adoc
index 472be848a63226d242ffa99d338cdc326ebd451a..fbb739483b425ea368f28b0f6e3d4c1c6235bb84 100644 (file)
--- a/pveproxy.adoc
+++ b/pveproxy.adoc
@@ -88,7 +88,7 @@ exchange algorithm is negotiated.
 Alternative HTTPS certificate
 -----------------------------
 
-You can change the certificate used, to an external one or to one obtained via
+You can change the certificate used to an external one or to one obtained via
 ACME.
 
 pveproxy uses `/etc/pve/local/pveproxy-ssl.pem` and