From: Stoiko Ivanov <s.ivanov@proxmox.com>
To: pbs-devel@lists.proxmox.com
Subject: [pbs-devel] [PATCH proxmox-backup 5/6] docs: certificates
Date: Mon, 16 May 2022 16:27:32 +0000 [thread overview]
Message-ID: <20220516162733.62060-6-s.ivanov@proxmox.com> (raw)
In-Reply-To: <20220516162733.62060-1-s.ivanov@proxmox.com>
manually adapt to differences between PMG and PBS
Signed-off-by: Stoiko Ivanov <s.ivanov@proxmox.com>
---
docs/certificate-management.rst | 70 ++++++++++-----------------------
1 file changed, 21 insertions(+), 49 deletions(-)
diff --git a/docs/certificate-management.rst b/docs/certificate-management.rst
index e09be966..ea7748d3 100644
--- a/docs/certificate-management.rst
+++ b/docs/certificate-management.rst
@@ -3,32 +3,28 @@
Certificate Management
----------------------
-Access to the web-based administration interface is always encrypted
-through ``https``. Each `Proxmox Backup`_ host creates by default its
+Access to the API and thus 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.
+communication with the host’s ``proxmox-backup-proxy`` service, for any API
+call between a user or backup-client and the web-interface.
-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.
+Certificate verification when sending backups to a `Proxmox Backup`_ server
+is either done based on pinning the certificate fingerprints in the storage/remote
+configuration, or by using certificates, signed by a trusted certificate authority.
.. _sysadmin_certs_api_gui:
Certificates for the API and SMTP
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-`Proxmox Backup`_ uses two different certificates:
+`Proxmox Backup`_ stores it certificate and key in:
-- ``/etc/proxmox-backup/proxy.pem``: the required certificate used for Proxmox
- Mail Gateway API requests.
+- ``/etc/proxmox-backup/proxy.pem``
-- ``/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.
+- ``/etc/proxmox-backup/proxy.key``
-You have the following options for these certificates:
+You have the following options for the certificate:
1. Keep using the default self-signed certificate in
``/etc/proxmox-backup/proxy.pem``.
@@ -37,8 +33,8 @@ You have the following options for these certificates:
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.
+ with automatic renewal; this is also integrated in the `Proxmox Backup`_
+ API and web interface.
Certificates are managed through the `Proxmox Backup`_
web-interface/API or using the the ``proxmox-backup-manager`` CLI tool.
@@ -109,7 +105,7 @@ 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
+and thus the `Proxmox Backup`_ server under your operation, are the
real owner of a domain. This is the basic building block of automatic
certificate management.
@@ -129,7 +125,6 @@ box, you can configure plugins either over the web interface under
``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:
@@ -146,10 +141,7 @@ 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>`_.
+Renewal will happen `automatically <#sysadmin-certs-acme-automatic-renewal>`_
.. _sysadmin_certs_acme_http_challenge:
@@ -163,8 +155,7 @@ 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.
+ its own, without any third party service.
There are a few prerequisites to use this for certificate management
with Let’s Encrypts ACME.
@@ -269,7 +260,7 @@ 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 (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.
@@ -296,7 +287,7 @@ Follow the instructions on the screen, for example:
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`_
+ Organizational Unit Name (eg, section) []:Proxmox Backup
Common Name (eg, YOUR name) []: yourproxmox.yourdomain.com
Email Address []:support@yourdomain.com
@@ -309,12 +300,12 @@ 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:
+To activate the new certificate, do the following on your `Proxmox Backup`_
::
- cat key.pem cert.pem >/etc/proxmox-backup/proxy.pem
+ cp key.pem /etc/proxmox-backup/proxy.key
+ cp cert.pem /etc/proxmox-backup/proxy.pem
Then restart the API servers:
@@ -331,25 +322,6 @@ Test your new certificate, using your browser.
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
--
2.30.2
next prev parent reply other threads:[~2022-05-16 16:28 UTC|newest]
Thread overview: 8+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-05-16 16:27 [pbs-devel] [PATCH proxmox-backup 0/6] docs: cleanup and add certificate docs Stoiko Ivanov
2022-05-16 16:27 ` [pbs-devel] [PATCH proxmox-backup 1/6] docs: silence duplicate label warnings Stoiko Ivanov
2022-05-16 16:27 ` [pbs-devel] [PATCH proxmox-backup 2/6] docs: cleanup and readd command-line-tools Stoiko Ivanov
2022-05-16 16:27 ` [pbs-devel] [PATCH proxmox-backup 3/6] docs: use case-matching keys for glossary Stoiko Ivanov
2022-05-16 16:27 ` [pbs-devel] [PATCH proxmox-backup 4/6] docs: add certificate-management.rst Stoiko Ivanov
2022-05-16 16:27 ` Stoiko Ivanov [this message]
2022-05-16 16:27 ` [pbs-devel] [PATCH proxmox-backup 6/6] docs: certs: add screenshots Stoiko Ivanov
2022-05-16 17:28 ` [pbs-devel] applied: [PATCH proxmox-backup 0/6] docs: cleanup and add certificate docs Thomas Lamprecht
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20220516162733.62060-6-s.ivanov@proxmox.com \
--to=s.ivanov@proxmox.com \
--cc=pbs-devel@lists.proxmox.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox