[pve-devel] [PATCH docs] add documentation for certificate managment

[Stoiko Ivanov]

* new section about certificate management in sysadmin chapter.
* adaptation of pveproxy and pvenode documentation

Signed-off-by: Stoiko Ivanov <s.ivanov at proxmox.com>
Co-authored-by: René Jochum <r.jochum at proxmox.com>
---
 certificate-managment.adoc | 116 +++++++++++++++++++++++++++++++++++++++++++++
 pvenode.adoc               |  26 +++++++---
 pveproxy.adoc              |  29 ++++--------
 sysadmin.adoc              |   3 ++
 4 files changed, 148 insertions(+), 26 deletions(-)
 create mode 100644 certificate-managment.adoc

diff --git a/certificate-managment.adoc b/certificate-managment.adoc
new file mode 100644
index 0000000..819745e
--- /dev/null
+++ b/certificate-managment.adoc
@@ -0,0 +1,116 @@
+[[sysadmin_certificate_management]]
+Certificate Management
+----------------------
+ifdef::wiki[]
+:pve-toplevel:
+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.
+
+The CA certificate and key are stored in the `pmxcfs` (see the `pmxcfs(8)`
+manpage).
+
+Certificates for API and web GUI
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The API and web GUI are provided 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.
+
+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`.
+
+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.
+
+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.
+
+Because of https://letsencrypt.org/docs/rate-limits/[rate-limits] you should use
+LE `staging` 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. Your (sub)domain needs to resolve to the 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 at proxmox:~# pvenode acme account register default mail at example.invalid
+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:
+1
+
+Attempting to fetch Terms of Service from 'https://acme-staging-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-staging-v02.api.letsencrypt.org/directory'..
+Generating ACME account key..
+Registering ACME account..
+Registration successful, account URL: 'https://acme-staging-v02.api.letsencrypt.org/acme/acct/xxxxxxx'
+Task OK
+root at proxmox:~# pvenode acme account list
+default
+root at proxmox:~# pvenode config set --acme domains=example.invalid
+root at proxmox:~# pvenode acme cert order
+Loading ACME account details
+Placing ACME order
+Order URL: https://acme-staging-v02.api.letsencrypt.org/acme/order/xxxxxxxxxxxxxx
+
+Getting authorization details from
+'https://acme-staging-v02.api.letsencrypt.org/acme/authz/xxxxxxxxxxxxxxxxxxxxx-xxxxxxxxxxxxx-xxxxxxx'
+... pending!
+Setting up webserver
+Triggering validation
+Sleeping for 5 seconds
+Status is 'valid'!
+
+All domains validated!
+
+Creating CSR
+Finalizing order
+Checking order status
+valid!
+
+Downloading certificate
+Setting pveproxy certificate and key
+Restarting pveproxy
+Task OK
+-----------------
diff --git a/pvenode.adoc b/pvenode.adoc
index dce428f..073a301 100644
--- a/pvenode.adoc
+++ b/pvenode.adoc
@@ -6,7 +6,7 @@ pvenode(1)
 NAME
 ----
 
-pvenode - Proxmox VE Node Management
+pvenode - {PVE} Node Management
 
 SYNOPSIS
 --------
@@ -26,11 +26,25 @@ endif::manvolnum[]
 The {PVE} node management tools (`pvenode`) allows to control node specific
 settings and resources.
 
-Currently the `pvenode` tool allows to manage the node's SSL certificates used
-for API and the web GUI. It 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.
+Currently `pvenode` allows to set a node's description and to manage
+the node's SSL certificates used for the API and the web GUI through `pveproxy`.
+
+EXAMPLES
+--------
+`pvenode cert set certificate.crt certificate.key -force`
+
+Install an externally provided certificate. Both files need to be PEM encoded.
+`certificate.key` contains the private key and `certificate.crt` contains the
+whole certificate chain.
+
+-----
+pvenode acme account register default mail at example.invalid
+pvenode config set --acme domains=example.invalid
+pvenode acme cert order
+systemctl restart pveproxy
+-----
+
+Configure acme to get certificates.
 
 // TODO: extend and improve chapter!
 
diff --git a/pveproxy.adoc b/pveproxy.adoc
index 5b83106..472be84 100644
--- a/pveproxy.adoc
+++ b/pveproxy.adoc
@@ -88,26 +88,15 @@ exchange algorithm is negotiated.
 Alternative HTTPS certificate
 -----------------------------
 
-By default, pveproxy uses the certificate `/etc/pve/local/pve-ssl.pem`
-(and private key `/etc/pve/local/pve-ssl.key`) for HTTPS connections.
-This certificate is signed by the cluster CA certificate, and therefor
-not trusted by browsers and operating systems by default.
-
-In order to use a different certificate and private key for HTTPS,
-store the server certificate and any needed intermediate / CA
-certificates in PEM format in the file `/etc/pve/local/pveproxy-ssl.pem`
-and the associated private key in PEM format without a password in the
-file `/etc/pve/local/pveproxy-ssl.key`.
-
-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`.
-
-NOTE: There is a detailed HOWTO for configuring commercial HTTPS certificates
-on the {webwiki-url}HTTPS_Certificate_Configuration_(Version_4.x_and_newer)[wiki],
-including setup instructions for obtaining certificates from the popular free
-Let's Encrypt certificate authority.
+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
+`/etc/pve/local/pveproxy-ssl.key`, if present, and falls back to
+`/etc/pve/local/pve-ssl.pem` and `/etc/pve/local/pve-ssl.key`.
+The private key may not use a passphrase.
+
+See the Host System Administration chapter of the documentation for details.
 
 ifdef::manvolnum[]
 include::pve-copyright.adoc[]
diff --git a/sysadmin.adoc b/sysadmin.adoc
index 421ab94..0ba4bf1 100644
--- a/sysadmin.adoc
+++ b/sysadmin.adoc
@@ -50,6 +50,7 @@ See Also
 
 * link:/wiki/ZFS_on_Linux[ZFS on Linux]
 
+* link:/wiki/Certificate_Management[Certificate Managment]
 endif::wiki[]
 
 
@@ -71,6 +72,8 @@ include::local-lvm.adoc[]
 
 include::local-zfs.adoc[]
 
+include::certificate-managment.adoc[]
+
 endif::wiki[]
 
 
-- 
2.11.0