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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 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).
 
 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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 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`:
 
 
 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).
 
 `/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
 
 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
 
 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.
 
 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.
 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
 -----------------
 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
 ----
 
 NAME
 ----
 

-pvenode - {PVE} Node Management
+pvenode - Proxmox VE Node Management

 
 SYNOPSIS
 --------
 
 SYNOPSIS
 --------


@@ -23,7 +23,7 @@ Proxmox Node Management
 :pve-toplevel:
 endif::manvolnum[]
 
 :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
 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
 -----
 
 systemctl restart pveproxy
 -----
 

-Configure acme to get certificates.
+Setup ACME account and order a certificate for local node.

 
 // TODO: extend and improve chapter!
 
 
 // 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
 -----------------------------
 
 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
 ACME.
 
 pveproxy uses `/etc/pve/local/pveproxy-ssl.pem` and