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 7DDE76BD0C for ; Thu, 18 Mar 2021 14:28:30 +0100 (CET) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 7440A19BCF for ; Thu, 18 Mar 2021 14:28:00 +0100 (CET) Received: from proxmox-new.maurer-it.com (proxmox-new.maurer-it.com [212.186.127.180]) (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 ADD2E19BC5 for ; Thu, 18 Mar 2021 14:27:58 +0100 (CET) Received: from proxmox-new.maurer-it.com (localhost.localdomain [127.0.0.1]) by proxmox-new.maurer-it.com (Proxmox) with ESMTP id 7607B462E1 for ; Thu, 18 Mar 2021 14:27:58 +0100 (CET) From: Stoiko Ivanov To: pve-devel@lists.proxmox.com Date: Thu, 18 Mar 2021 14:27:51 +0100 Message-Id: <20210318132751.23281-1-s.ivanov@proxmox.com> X-Mailer: git-send-email 2.20.1 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-SPAM-LEVEL: Spam detection results: 0 AWL 0.063 Adjusted score from AWL reputation of From: address KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment RCVD_IN_DNSWL_MED -2.3 Sender listed at https://www.dnswl.org/, medium trust SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record URIBL_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to URIBL was blocked. See http://wiki.apache.org/spamassassin/DnsBlocklists#dnsbl-block for more information. [letsencrypt.org, acme.sh] Subject: [pve-devel] [PATCH docs] certs: improve wording and styling X-BeenThere: pve-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox VE development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 18 Mar 2021 13:28:30 -0000 porting over the changes done in pmg-docs Signed-off-by: Stoiko Ivanov --- certificate-management.adoc | 31 +++++++++++++++---------------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/certificate-management.adoc b/certificate-management.adoc index 00633a1..065433d 100644 --- a/certificate-management.adoc +++ b/certificate-management.adoc @@ -67,13 +67,14 @@ Trusted certificates via Let's Encrypt (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 for easy setup of trusted TLS certificates which -are accepted out of the box on most modern operating systems and browsers. +use an ACME provider like Let's Encrypt for easy setup of TLS certificates +which are accepted and trusted on modern operating systems and web browsers +out of the box. -Currently the two ACME endpoints implemented are the +Currently, the two ACME endpoints implemented are the https://letsencrypt.org[Let's Encrypt (LE)] production and its staging environment. Our ACME client supports validation of `http-01` challenges using -a built-in webserver and validation of `dns-01` challenges using a DNS plugin +a built-in web server and validation of `dns-01` challenges using a DNS plugin supporting all the DNS API endpoints https://acme.sh[acme.sh] does. [[sysadmin_certs_acme_account]] @@ -83,7 +84,7 @@ ACME Account [thumbnail="screenshot/gui-datacenter-acme-register-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 server as contact point for +use. The email address used for that account will serve as contact point for renewal-due or similar notifications from the ACME endpoint. You can register and deactivate ACME accounts over the web interface @@ -104,12 +105,11 @@ the {pve} cluster under your operation, are the real owner of a domain. This is the basis building block for automatic certificate management. The ACME protocol specifies different types of challenges, for example the -`http-01` where a webserver provides a file with a certain value to prove that -it controls a domain. Sometimes this isn't possible, either because of -technical limitations or if the address a domain points to is not reachable -from the public internet. For such cases, one could use the `dns-01` challenge. -This challenge also provides a certain value, but through a DNS record on the -authority name server of the domain, rather than over a text file. +`http-01` where a web server provides a file with a certain content to prove +that it controls a domain. Sometimes this isn't possible, either because of +technical limitations or if the address of a record to is not reachable from +the public internet. The `dns-01` challenge can be used in these cases. This +challenge is fulfilled by creating a certain DNS record in the domain's zone. [thumbnail="screenshot/gui-datacenter-acme-overview.png"] @@ -168,9 +168,8 @@ Configuring ACME DNS APIs for validation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ {PVE} re-uses the DNS plugins developed for the `acme.sh` -footnote:[acme.sh https://github.com/acmesh-official/acme.sh] -project, please refer to its documentation for details on configuration of -specific APIs. +footnote:[acme.sh https://github.com/acmesh-official/acme.sh] 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 (`Datacenter -> ACME`). @@ -185,8 +184,8 @@ https://github.com/acmesh-official/acme.sh/wiki/dnsapi#how-to-use-dns-api[How to wiki for more detailed information about getting API credentials for your provider. -As there are so many API endpoints {pve} autogenerates the form for the -credentials, but not all providers are annotated yet. For those you will see a +As there are many DNS providers and API endpoints {pve} automatically generates +the form for the credentials for some providers. For the others you will see a bigger text area, simply copy all the credentials `KEY`=`VALUE` pairs in there. DNS Validation through CNAME Alias -- 2.20.1