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 52C546384A for ; Wed, 26 Jan 2022 10:48:34 +0100 (CET) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 3F1EC622A for ; Wed, 26 Jan 2022 10:48:04 +0100 (CET) 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) server-digest SHA256) (No client certificate requested) by firstgate.proxmox.com (Proxmox) with ESMTPS id C4EF2621E for ; Wed, 26 Jan 2022 10:48:02 +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 28BE745070 for ; Wed, 26 Jan 2022 10:47:56 +0100 (CET) Message-ID: <02d4a79b-b5bb-73e3-9676-162b285551aa@proxmox.com> Date: Wed, 26 Jan 2022 10:47:54 +0100 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101 Thunderbird/91.5.1 Content-Language: en-US To: Fabian Ebner , pve-devel@lists.proxmox.com References: <20211126164446.2558368-1-a.lauterer@proxmox.com> <20211126164446.2558368-2-a.lauterer@proxmox.com> <33cce4e5-9f53-cba2-6279-f1923d108221@proxmox.com> From: Aaron Lauterer In-Reply-To: <33cce4e5-9f53-cba2-6279-f1923d108221@proxmox.com> Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 8bit X-SPAM-LEVEL: Spam detection results: 0 AWL -0.151 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment NICE_REPLY_A -0.001 Looks like a legit reply (A) POISEN_SPAM_PILL 0.1 Meta: its spam POISEN_SPAM_PILL_1 0.1 random spam to be learned in bayes POISEN_SPAM_PILL_3 0.1 random spam to be learned in bayes 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. [asciidoctor.org, github.io] Subject: Re: [pve-devel] [PATCH docs 2/3] storage: rbd: cephs: update authentication section 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: Wed, 26 Jan 2022 09:48:34 -0000 On 1/24/22 14:48, Fabian Ebner wrote: > Am 26.11.21 um 17:44 schrieb Aaron Lauterer: >> It is not needed anymore to place the keyring/secret file manually in >> the correct location as it can be done with pvesm and the GUI/API now. >> >> Signed-off-by: Aaron Lauterer >> --- >> >> Since both sectons share the same footnote, I tried to get them to share >> the same with footnote:[here some text] and footnote:[] to >> reference it as explained in the asciidoc documentation [0]. >> Unfortunately I did not get it to work, most likely because they are >> both in separate files? >> I rather err on having the same footnote twice than missing it in one >> place. >> >> >> >> [0] https://docs.asciidoctor.org/asciidoc/latest/macros/footnote/ >> > > Maybe the idea from the "Externalizing a footnote" section with using document attributes works? Turns out that there is asciidoc and asciidoctor. We use the former, but searching the internet will result in more prominent results for the latter in my experience. They do have slightly different syntax. With that realization and using the correct documentation ( https://asciidoc-py.github.io/userguide.html#X92 ) it is working now. > >>   pve-storage-cephfs.adoc | 31 ++++++++++++++++++------------- >>   pve-storage-rbd.adoc    | 28 +++++++++++++++++++--------- >>   2 files changed, 37 insertions(+), 22 deletions(-) >> >> diff --git a/pve-storage-cephfs.adoc b/pve-storage-cephfs.adoc >> index c67f089..2437859 100644 >> --- a/pve-storage-cephfs.adoc >> +++ b/pve-storage-cephfs.adoc >> @@ -71,31 +71,36 @@ disabled. >>   Authentication >>   ~~~~~~~~~~~~~~ >> -If you use `cephx` authentication, which is enabled by default, you need to copy >> -the secret from your external Ceph cluster to a Proxmox VE host. >> +If you use `cephx` authentication, which is enabled by default, you need to provide >> +the secret from the external Ceph cluster. >> -Create the directory `/etc/pve/priv/ceph` with >> +The secret file is expected to be located at >> - mkdir /etc/pve/priv/ceph >> + /etc/pve/priv/ceph/.secret >> -Then copy the secret >> +You can copy the secret with >> - scp cephfs.secret :/etc/pve/priv/ceph/.secret >> + scp :/etc/ceph/cephfs.secret /local/path/to/.secret > > IMHO this is a bit confusing. We tell the user an explicit path where the key should be, and then suggest copying it to some location which might or might not be the same as already mentioned. After reading the next paragraph it might be clearer, but IMHO the structure should be "To add via CLI, do scp + pvesm. To add via GUI, do ...". And/or maybe make it clear that pvesm will put the keyring there? > >> -The secret must be renamed to match your ``. Copying the >> -secret generally requires root privileges. The file must only contain the >> -secret key itself, as opposed to the `rbd` backend which also contains a >> -`[client.userid]` section. >> +If you use the `pvesm` CLI tool to configure the external RBD storage, use the >> +`--keyring` parameter, which needs to be a path to the secret file that you >> +copied. >> + >> +When configuring an external RBD storage via the GUI, you can copy and paste >> +the secret into the appropriate field. >> + >> +The secret is only the key itself, as opposed to the `rbd` backend which also >> +contains a `[client.userid]` section. >>   A secret can be received from the Ceph cluster (as Ceph admin) by issuing the >>   command below, where `userid` is the client ID that has been configured to >>   access the cluster. For further information on Ceph user management, see the >> -Ceph docs footnote:[Ceph user management >> -{cephdocs-url}/rados/operations/user-management/]. >> +Ceph docs.footnote:[Ceph user management >> +{cephdocs-url}/rados/operations/user-management/] >>    ceph auth get-key client.userid > cephfs.secret >> -If Ceph is installed locally on the PVE cluster, that is, it was set up using >> +If Ceph is installed locally on the {pve} cluster, that is, it was set up using >>   `pveceph`, this is done automatically. >>   Storage Features >> diff --git a/pve-storage-rbd.adoc b/pve-storage-rbd.adoc >> index bbc80e2..1f14b7c 100644 >> --- a/pve-storage-rbd.adoc >> +++ b/pve-storage-rbd.adoc >> @@ -69,23 +69,33 @@ TIP: You can use the `rbd` utility to do low-level management tasks. >>   Authentication >>   ~~~~~~~~~~~~~~ >> -If you use `cephx` authentication, you need to copy the keyfile from your >> -external Ceph cluster to a Proxmox VE host. >> +If you use `cephx` authentication, which is enabled by default, you need to >> +provide the keyring from the external Ceph cluster. >> -Create the directory `/etc/pve/priv/ceph` with >> +The keyring file is expected to be at > > Nit: "to be located at" like above sounds better > >> - mkdir /etc/pve/priv/ceph >> + /etc/pve/priv/ceph/.keyring >> -Then copy the keyring >> +You can copy the keyring with >> - scp :/etc/ceph/ceph.client.admin.keyring /etc/pve/priv/ceph/.keyring >> + scp :/etc/ceph/ceph.client.admin.keyring /local/path/to/.keyring > > Same as above. > >> -The keyring must be named to match your ``. Copying the >> -keyring generally requires root privileges. >> +If you use the `pvesm` CLI tool to configure the external RBD storage, use the >> +`--keyring` parameter, which needs to be a path to the keyring file that you >> +copied. >> -If Ceph is installed locally on the PVE cluster, this is done automatically by >> +When configuring an external RBD storage via the GUI, you can copy and paste the >> +keyring into the appropriate field. >> + >> +If Ceph is installed locally on the {pve} cluster, this is done automatically by >>   'pveceph' or in the GUI. >> +TIP: Creating a keyring with only the needed capabilities is recommend when >> +connecting to an external cluster. For further information on Ceph user >> +management, see the Ceph docs.footnote:[Ceph user management >> +{cephdocs-url}/rados/operations/user-management/] >> + >> + >>   Storage Features >>   ~~~~~~~~~~~~~~~~