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 77C3F70CA9 for ; Mon, 16 May 2022 18:28:25 +0200 (CEST) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 6E94B200E9 for ; Mon, 16 May 2022 18:27:55 +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 463E4200AB 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 1FA3D43617 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:32 +0000 Message-Id: <20220516162733.62060-6-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.209 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 5/6] docs: certificates 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:25 -0000 manually adapt to differences between PMG and PBS Signed-off-by: Stoiko Ivanov --- 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