From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by lists.proxmox.com (Postfix) with ESMTPS id 8D00570CB7 for ; Mon, 16 May 2022 18:28:27 +0200 (CEST) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 846A320171 for ; Mon, 16 May 2022 18:27:57 +0200 (CEST) Received: from proxmox-new.maurer-it.com (proxmox-new.maurer-it.com [94.136.29.106]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by firstgate.proxmox.com (Proxmox) with ESMTPS id E533C200DE for ; Mon, 16 May 2022 18:27:53 +0200 (CEST) Received: from proxmox-new.maurer-it.com (localhost.localdomain [127.0.0.1]) by proxmox-new.maurer-it.com (Proxmox) with ESMTP id B6CD643617 for ; Mon, 16 May 2022 18:27:53 +0200 (CEST) From: Stoiko Ivanov To: pbs-devel@lists.proxmox.com Date: Mon, 16 May 2022 16:27:31 +0000 Message-Id: <20220516162733.62060-5-s.ivanov@proxmox.com> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20220516162733.62060-1-s.ivanov@proxmox.com> References: <20220516162733.62060-1-s.ivanov@proxmox.com> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-SPAM-LEVEL: Spam detection results: 0 AWL -0.208 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% KAM_ASCII_DIVIDERS 0.8 Spam that uses ascii formatting tricks KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record T_FILL_THIS_FORM_SHORT 0.01 Fill in a short form with personal information T_SCC_BODY_TEXT_LINE -0.01 - Subject: [pbs-devel] [PATCH proxmox-backup 4/6] docs: add certificate-management.rst X-BeenThere: pbs-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox Backup Server development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 16 May 2022 16:28:27 -0000 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 --- 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) `_ 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 `_ 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 + +.. tip:: + + Because of + `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 `_ + 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 `_. + +.. _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