[pbs-devel] [PATCH proxmox-backup 4/6] docs: add certificate-management.rst

[Stoiko Ivanov <s.ivanov@proxmox.com>]

the file certificate-managment.rst is generated from the pmg-docs repo

by running:
```
asciidoc -b $(pwd)/asciidoc/pmg-docbook \
-f asciidoc/asciidoc-pmg.conf -o - pmg-ssl-certificate.adoc | \
pandoc -f docbook -t rst --shift-heading-level-by=1 \
-o certificate-mangement-auto.rst

sed -ri 's/__/_/' certificate-mangement-auto.rst
sed -ri 's/\{pmg\}/`Proxmox Backup`_/g' certificate-mangement-auto.rst
sed -ri 's/\{PMG\}/`Proxmox Backup`_/g' certificate-mangement-auto.rst
sed -ri 's/Proxmox Mail Gateway/`Proxmox Backup`_/g' \
certificate-mangement-auto.rst
sed -ri 's/pmg-([a-zA-Z0-9_-]*).png/pbs-\1.png/g' \
certificate-mangement-auto.rst
sed -ri 's/pmgproxy/proxmox-backup-proxy/g' \
certificate-mangement-auto.rst
sed -ri 's/pmgconfig/proxmox-backup-manager/g' \
certificate-mangement-auto.rst
sed -ri 's/pmg-daily/proxmox-backup-daily-update/g' \
certificate-mangement-auto.rst
sed -ri 's/\/etc\/pmg\/node.conf/\/etc\/proxmox-backup\/node.cfg/g' \
certificate-mangement-auto.rst
sed -ri 's/\/etc\/pmg\/acme/\/etc\/proxmox-backup\/acme/g' \
certificate-mangement-auto.rst
sed -ri \
's/\/etc\/pmg\/pmg-api.pem/\/etc\/proxmox-backup\/proxy.pem/g' \
certificate-mangement-auto.rst
sed -ri 's/screenshot/screenshots/g' certificate-mangement-auto.rst

Signed-off-by: Stoiko Ivanov <s.ivanov@proxmox.com>
---
 docs/certificate-management.rst | 359 ++++++++++++++++++++++++++++++++
 docs/conf.py                    |   1 +
 docs/sysadmin.rst               |   2 +
 3 files changed, 362 insertions(+)
 create mode 100644 docs/certificate-management.rst

diff --git a/docs/certificate-management.rst b/docs/certificate-management.rst
new file mode 100644
index 00000000..e09be966
--- /dev/null
+++ b/docs/certificate-management.rst
@@ -0,0 +1,359 @@
+.. _sysadmin_certificate_management:
+
+Certificate Management
+----------------------
+
+Access to the web-based administration interface is always encrypted
+through ``https``. Each `Proxmox Backup`_ host creates by default its
+own (self-signed) certificate. This certificate is used for encrypted
+communication with the host’s ``proxmox-backup-proxy`` service, for any API call
+between a user and the web-interface or between nodes in a cluster.
+
+Certificate verification in a `Proxmox Backup`_ cluster is done based
+on pinning the certificate fingerprints in the cluster configuration and
+verifying that they match on connection.
+
+.. _sysadmin_certs_api_gui:
+
+Certificates for the API and SMTP
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`Proxmox Backup`_ uses two different certificates:
+
+-  ``/etc/proxmox-backup/proxy.pem``: the required certificate used for Proxmox
+   Mail Gateway API requests.
+
+-  ``/etc/pmg/pmg-tls.pem``: the optional certificate used for SMTP TLS
+   connections, see `mailproxy TLS
+   configuration <#proxmox-backup-manager_mailproxy_tls>`_
+   `??? <#proxmox-backup-manager_mailproxy_tls>`_ for details.
+
+You have the following options for these certificates:
+
+1. Keep using the default self-signed certificate in
+   ``/etc/proxmox-backup/proxy.pem``.
+
+2. Use an externally provided certificate (for example, signed by a
+   commercial Certificate Authority (CA)).
+
+3. Use an ACME provider like Let’s Encrypt to get a trusted certificate
+   with automatic renewal; this is also integrated in the Proxmox Mail
+   Gateway API and web interface.
+
+Certificates are managed through the `Proxmox Backup`_
+web-interface/API or using the the ``proxmox-backup-manager`` CLI tool.
+
+.. _sysadmin_certs_upload_custom:
+
+Upload Custom Certificate
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you already have a certificate which you want to use for a Proxmox
+Mail Gateway host, you can simply upload that certificate over the web
+interface.
+
+|pbs-gui-certs-upload-custom.png|
+
+Note that any certificate key files must not be password protected.
+
+.. _sysadmin_certs_get_trusted_acme_cert:
+
+Trusted certificates via Let’s Encrypt (ACME)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`Proxmox Backup`_ includes an implementation of the **A**\ utomatic
+**C**\ ertificate **M**\ anagement **E**\ nvironment (**ACME**)
+protocol, allowing `Proxmox Backup`_ admins to use an ACME provider
+like Let’s Encrypt for easy setup of TLS certificates, which are
+accepted and trusted by modern operating systems and web browsers out of
+the box.
+
+Currently, the two ACME endpoints implemented are the `Let’s Encrypt
+(LE) <https://letsencrypt.org>`_ production and staging environments.
+Our ACME client supports validation of ``http-01`` challenges using a
+built-in web server and validation of ``dns-01`` challenges using a DNS
+plugin supporting all the DNS API endpoints
+`acme.sh <https://acme.sh>`_ does.
+
+.. _sysadmin_certs_acme_account:
+
+ACME Account
+^^^^^^^^^^^^
+
+|pbs-gui-acme-create-account.png|
+
+You need to register an ACME account per cluster, with the endpoint you
+want to use. The email address used for that account will serve as the
+contact point for renewal-due or similar notifications from the ACME
+endpoint.
+
+You can register or deactivate ACME accounts over the web interface
+``Certificates -> ACME Accounts`` or using the ``proxmox-backup-manager`` command
+line tool.
+
+::
+
+    proxmox-backup-manager acme account register <account-name> <mail@example.com>
+
+.. tip::
+
+   Because of
+   `rate-limits <https://letsencrypt.org/docs/rate-limits/>`_ you
+   should use LE ``staging`` for experiments or if you use ACME for the
+   very first time until all is working there, and only then switch over
+   to the production directory.
+
+.. _sysadmin_certs_acme_plugins:
+
+ACME Plugins
+^^^^^^^^^^^^
+
+The ACME plugin’s role is to provide automatic verification that you,
+and thus the `Proxmox Backup`_ cluster under your operation, are the
+real owner of a domain. This is the basic building block of automatic
+certificate management.
+
+The ACME protocol specifies different types of challenges, for example
+the ``http-01``, where a web server provides a file with a specific
+token to prove that it controls a domain. Sometimes this isn’t possible,
+either because of technical limitations or if the address of a record is
+not reachable from the public internet. The ``dns-01`` challenge can be
+used in such cases. This challenge is fulfilled by creating a certain
+DNS record in the domain’s zone.
+
+|pbs-gui-acme-create-challenge-plugin.png|
+
+`Proxmox Backup`_ supports both of those challenge types out of the
+box, you can configure plugins either over the web interface under
+``Certificates -> ACME Challenges``, or using the
+``proxmox-backup-manager acme plugin add`` command.
+
+ACME Plugin configurations are stored in ``/etc/proxmox-backup/acme/plugins.cfg``.
+A plugin is available for all nodes in the cluster.
+
+.. _domains:
+
+Domains
+^^^^^^^
+
+You can add new or manage existing domain entries under
+``Certificates``, or using the ``proxmox-backup-manager`` command.
+
+|pbs-gui-acme-add-domain.png|
+
+After configuring the desired domain(s) for a node and ensuring that the
+desired ACME account is selected, you can order your new certificate
+over the web-interface. On success, the interface will reload after
+roughly 10 seconds.
+
+Renewal will happen
+`automatically <#sysadmin_certs_acme_automatic_renewal>`_ `Automatic
+renewal of ACME
+certificates <#sysadmin_certs_acme_automatic_renewal>`_.
+
+.. _sysadmin_certs_acme_http_challenge:
+
+ACME HTTP Challenge Plugin
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There is always an implicitly configured ``standalone`` plugin for
+validating ``http-01`` challenges via the built-in web server spawned on
+port 80.
+
+.. note::
+
+   The name ``standalone`` means that it can provide the validation on
+   its own, without any third party service. So this plugin also works
+   for cluster nodes.
+
+There are a few prerequisites to use this for certificate management
+with Let’s Encrypts ACME.
+
+-  You have to accept the ToS of Let’s Encrypt to register an account.
+
+-  **Port 80** of the node needs to be reachable from the internet.
+
+-  There **must** be no other listener on port 80.
+
+-  The requested (sub)domain needs to resolve to a public IP of the
+   `Proxmox Backup`_ host.
+
+.. _sysadmin_certs_acme_dns_challenge:
+
+ACME DNS API Challenge Plugin
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On systems where external access for validation via the ``http-01``
+method is not possible or desired, it is possible to use the ``dns-01``
+validation method. This validation method requires a DNS server that
+allows provisioning of ``TXT`` records via an API.
+
+.. _sysadmin_certs_acme_dns_api_config:
+
+Configuring ACME DNS APIs for validation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+`Proxmox Backup`_ re-uses the DNS plugins developed for the
+``acme.sh``  [1]_ project. Please refer to its documentation for details
+on configuration of specific APIs.
+
+The easiest way to configure a new plugin with the DNS API is using the
+web interface (``Certificates -> ACME Accounts/Challenges``).
+
+|pbs-gui-acme-create-challenge-plugin.png|
+
+Here you can add a new challenge plugin by selecting your API provider
+and entering the credential data to access your account over their API.
+
+.. tip::
+
+   See the acme.sh `How to use DNS
+   API <https://github.com/acmesh-official/acme.sh/wiki/dnsapi#how-to-use-dns-api>`_
+   wiki for more detailed information about getting API credentials for
+   your provider. Configuration values do not need to be quoted with
+   single or double quotes; for some plugins that is even an error.
+
+As there are many DNS providers and API endpoints, `Proxmox Backup`_
+automatically generates the form for the credentials, but not all
+providers are annotated yet. For those you will see a bigger text area,
+into which you simply need to copy all the credential’s
+``KEY``\ =\ ``VALUE`` pairs.
+
+.. _dns_validation_through_cname_alias:
+
+DNS Validation through CNAME Alias
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A special ``alias`` mode can be used to handle validation on a different
+domain/DNS server, in case your primary/real DNS does not support
+provisioning via an API. Manually set up a permanent ``CNAME`` record
+for ``_acme-challenge.domain1.example`` pointing to
+``_acme-challenge.domain2.example``, and set the ``alias`` property in
+the `Proxmox Backup`_ node configuration file ``/etc/proxmox-backup/node.cfg``
+to ``domain2.example`` to allow the DNS server of ``domain2.example`` to
+validate all challenges for ``domain1.example``.
+
+.. _sysadmin_certs_acme_dns_wildcard:
+
+Wildcard Certificates
+^^^^^^^^^^^^^^^^^^^^^
+
+Wildcard DNS names start with a ``*.`` prefix and are considered valid
+for all (one-level) subdomain names of the verified domain. So a
+certificate for ``*.domain.example`` is valid for ``foo.domain.example``
+and ``bar.domain.example``, but not for ``baz.foo.domain.example``.
+
+Currently, you can only create wildcard certificates with the `DNS
+challenge
+type <https://letsencrypt.org/docs/challenge-types/#dns-01-challenge>`_.
+
+.. _combination_of_plugins:
+
+Combination of Plugins
+^^^^^^^^^^^^^^^^^^^^^^
+
+Combining ``http-01`` and ``dns-01`` validation is possible in case your
+node is reachable via multiple domains with different requirements / DNS
+provisioning capabilities. Mixing DNS APIs from multiple providers or
+instances is also possible by specifying different plugin instances per
+domain.
+
+.. tip::
+
+   Accessing the same service over multiple domains increases complexity
+   and should be avoided if possible.
+
+.. _sysadmin_certs_acme_automatic_renewal:
+
+Automatic renewal of ACME certificates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If a node has been successfully configured with an ACME-provided
+certificate (either via proxmox-backup-manager or via the web-interface/API), the
+certificate will be renewed automatically by the ``proxmox-backup-daily-update.service``.
+Currently, renewal is triggered if the certificate either has already
+expired or if it will expire in the next 30 days.
+
+.. _manually_change_certificate_over_command_line:
+
+Manually Change Certificate over Command-Line
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want to get rid of certificate verification warnings, you have to
+generate a valid certificate for your server.
+
+Log in to your `Proxmox Backup`_ via ssh or use the console:
+
+::
+
+   openssl req -newkey rsa:2048 -nodes -keyout key.pem -out req.pem
+
+Follow the instructions on the screen, for example:
+
+::
+
+   Country Name (2 letter code) [AU]: AT
+   State or Province Name (full name) [Some-State]:Vienna
+   Locality Name (eg, city) []:Vienna
+   Organization Name (eg, company) [Internet Widgits Pty Ltd]: Proxmox GmbH
+   Organizational Unit Name (eg, section) []:`Proxmox Backup`_
+   Common Name (eg, YOUR name) []: yourproxmox.yourdomain.com
+   Email Address []:support@yourdomain.com
+
+   Please enter the following 'extra' attributes to be sent with your certificate request
+   A challenge password []: not necessary
+   An optional company name []: not necessary
+
+After you have finished the certificate request, you have to send the
+file ``req.pem`` to your Certification Authority (CA). The CA will issue
+the certificate (BASE64 encoded), based on your request – save this file
+as ``cert.pem`` to your `Proxmox Backup`_.
+
+To activate the new certificate, do the following on your Proxmox Mail
+Gateway:
+
+::
+
+   cat key.pem cert.pem >/etc/proxmox-backup/proxy.pem
+
+Then restart the API servers:
+
+::
+
+   systemctl restart proxmox-backup-proxy
+
+Test your new certificate, using your browser.
+
+.. note::
+
+   To transfer files to and from your `Proxmox Backup`_, you can use
+   secure copy: If your desktop runs Linux, you can use the ``scp``
+   command line tool. If your desktop PC runs windows, please use an scp
+   client like WinSCP (see https://winscp.net/).
+
+.. _change_certificate_for_cluster_setups:
+
+Change Certificate for Cluster Setups
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you change the API certificate of an active cluster node manually,
+you also need to update the pinned fingerprint inside the cluster
+configuration.
+
+You can do that by executing the following command on the host where the
+certificate changed:
+
+::
+
+   pmgcm update-fingerprints
+
+Note, this will be done automatically if using the integrated ACME (for
+example, through Let’s Encrypt) feature.
+
+.. [1]
+   acme.sh https://github.com/acmesh-official/acme.sh
+
+.. |pbs-gui-certs-upload-custom.png| image:: images/screenshots/pbs-gui-certs-upload-custom.png
+.. |pbs-gui-acme-create-account.png| image:: images/screenshots/pbs-gui-acme-create-account.png
+.. |pbs-gui-acme-create-challenge-plugin.png| image:: images/screenshots/pbs-gui-acme-create-challenge-plugin.png
+.. |pbs-gui-acme-add-domain.png| image:: images/screenshots/pbs-gui-acme-add-domain.png
diff --git a/docs/conf.py b/docs/conf.py
index a7c2b8bd..2c212dee 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -108,6 +108,7 @@ today_fmt = '%A, %d %B %Y'
 exclude_patterns = [
     '_build', 'Thumbs.db', '.DS_Store',
     '*/man1.rst',
+    'certificate-management.rst',
     'config/*/man5.rst',
     'epilog.rst',
     'pbs-copyright.rst',
diff --git a/docs/sysadmin.rst b/docs/sysadmin.rst
index 21b7840c..7440d201 100644
--- a/docs/sysadmin.rst
+++ b/docs/sysadmin.rst
@@ -28,6 +28,8 @@ please refer to the standard Debian documentation.
 
 .. include:: system-booting.rst
 
+.. include:: certificate-management.rst
+
 .. include:: services.rst
 
 .. include:: command-line-tools.rst
-- 
2.30.2