[libguestfs PATCH] guestfs.pod: document encrypted RBD disk limitation
Under "REMOTE STORAGE", the "NETWORK BLOCK DEVICE" section already documents some limitations. Turns out we need to describe a quirky exception for accessing encrypted RBD disks, too. Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=2033247 Signed-off-by: Laszlo Ersek <lersek@redhat.com> --- lib/guestfs.pod | 33 ++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/lib/guestfs.pod b/lib/guestfs.pod index b04c28d62750..1ad44e7c2878 100644 --- a/lib/guestfs.pod +++ b/lib/guestfs.pod @@ -679,6 +679,39 @@ servers. The server string is documented in L</guestfs_add_drive_opts>. The C<username> and C<secret> parameters are also optional, and if not given, then no authentication will be used. +An encrypted RBD disk -- I<directly> opening which would require the +C<username> and C<secret> parameters -- cannot be accessed if the +following conditions all hold: + +=over 4 + +=item * + +the L<backend|/BACKEND> is libvirt, + +=item * + +the image specified by the C<filename> parameter is different from the +encrypted RBD disk, + +=item * + +the image specified by the C<filename> parameter has L<qcow2 +format|/COMMON VIRTUAL DISK IMAGE FORMATS>, + +=item * + +the encrypted RBD disk is specified as a backing file at some level in +the qcow2 backing chain. + +=back + +This limitation is due to libvirt's (justified) separate handling of +disks vs. secrets. When the RBD username and secret are provided inside +a qcow2 backing file specification, libvirt does not construct an +ephemeral secret object from those, for Ceph authentication. Refer to +L<https://bugzilla.redhat.com/2033247>. + =head3 FTP, HTTP AND TFTP Libguestfs can access remote disks over FTP, FTPS, HTTP, HTTPS base-commit: 8a111cb82a3fcd7d98e428de57ceb048628e0051 -- 2.19.1.3.g30247aa5d201
On Wed, May 18, 2022 at 10:30:14AM +0200, Laszlo Ersek wrote:
Under "REMOTE STORAGE", the "NETWORK BLOCK DEVICE" section already documents some limitations. Turns out we need to describe a quirky exception for accessing encrypted RBD disks, too.
Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=2033247 Signed-off-by: Laszlo Ersek <lersek@redhat.com> --- lib/guestfs.pod | 33 ++++++++++++++++++++ 1 file changed, 33 insertions(+)
diff --git a/lib/guestfs.pod b/lib/guestfs.pod index b04c28d62750..1ad44e7c2878 100644 --- a/lib/guestfs.pod +++ b/lib/guestfs.pod @@ -679,6 +679,39 @@ servers. The server string is documented in L</guestfs_add_drive_opts>. The C<username> and C<secret> parameters are also optional, and if not given, then no authentication will be used.
+An encrypted RBD disk -- I<directly> opening which would require the +C<username> and C<secret> parameters -- cannot be accessed if the +following conditions all hold: + +=over 4 + +=item * + +the L<backend|/BACKEND> is libvirt, + +=item * + +the image specified by the C<filename> parameter is different from the +encrypted RBD disk, + +=item * + +the image specified by the C<filename> parameter has L<qcow2 +format|/COMMON VIRTUAL DISK IMAGE FORMATS>, + +=item * + +the encrypted RBD disk is specified as a backing file at some level in +the qcow2 backing chain. + +=back + +This limitation is due to libvirt's (justified) separate handling of +disks vs. secrets. When the RBD username and secret are provided inside +a qcow2 backing file specification, libvirt does not construct an +ephemeral secret object from those, for Ceph authentication. Refer to +L<https://bugzilla.redhat.com/2033247>. + =head3 FTP, HTTP AND TFTP
Seems fine. I had to look at perlpod(1) to check that the piped L<> references were correct, but they seem to be! Acked-by: Richard W.M. Jones <rjones@redhat.com> Rich. -- Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones Read my programming and virtualization blog: http://rwmj.wordpress.com virt-top is 'top' for virtual machines. Tiny program with many powerful monitoring features, net stats, disk stats, logging, etc. http://people.redhat.com/~rjones/virt-top
On 05/18/22 11:30, Richard W.M. Jones wrote:
On Wed, May 18, 2022 at 10:30:14AM +0200, Laszlo Ersek wrote:
Under "REMOTE STORAGE", the "NETWORK BLOCK DEVICE" section already documents some limitations. Turns out we need to describe a quirky exception for accessing encrypted RBD disks, too.
Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=2033247 Signed-off-by: Laszlo Ersek <lersek@redhat.com> --- lib/guestfs.pod | 33 ++++++++++++++++++++ 1 file changed, 33 insertions(+)
diff --git a/lib/guestfs.pod b/lib/guestfs.pod index b04c28d62750..1ad44e7c2878 100644 --- a/lib/guestfs.pod +++ b/lib/guestfs.pod @@ -679,6 +679,39 @@ servers. The server string is documented in L</guestfs_add_drive_opts>. The C<username> and C<secret> parameters are also optional, and if not given, then no authentication will be used.
+An encrypted RBD disk -- I<directly> opening which would require the +C<username> and C<secret> parameters -- cannot be accessed if the +following conditions all hold: + +=over 4 + +=item * + +the L<backend|/BACKEND> is libvirt, + +=item * + +the image specified by the C<filename> parameter is different from the +encrypted RBD disk, + +=item * + +the image specified by the C<filename> parameter has L<qcow2 +format|/COMMON VIRTUAL DISK IMAGE FORMATS>, + +=item * + +the encrypted RBD disk is specified as a backing file at some level in +the qcow2 backing chain. + +=back + +This limitation is due to libvirt's (justified) separate handling of +disks vs. secrets. When the RBD username and secret are provided inside +a qcow2 backing file specification, libvirt does not construct an +ephemeral secret object from those, for Ceph authentication. Refer to +L<https://bugzilla.redhat.com/2033247>. + =head3 FTP, HTTP AND TFTP
Seems fine. I had to look at perlpod(1) to check that the piped L<> references were correct, but they seem to be!
Yeah, I recalled both piped-but-https-references, and non-piped-local references, from the PODs, so I figured I'd try piped-local -- and the rendered HTML (which I reviewed in Firefox) confirmed they were going to work!
Acked-by: Richard W.M. Jones <rjones@redhat.com>
Rich.
Thanks! Laszlo
On 05/18/22 11:30, Richard W.M. Jones wrote:
On Wed, May 18, 2022 at 10:30:14AM +0200, Laszlo Ersek wrote:
Under "REMOTE STORAGE", the "NETWORK BLOCK DEVICE" section already documents some limitations. Turns out we need to describe a quirky exception for accessing encrypted RBD disks, too.
Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=2033247 Signed-off-by: Laszlo Ersek <lersek@redhat.com> --- lib/guestfs.pod | 33 ++++++++++++++++++++ 1 file changed, 33 insertions(+)
diff --git a/lib/guestfs.pod b/lib/guestfs.pod index b04c28d62750..1ad44e7c2878 100644 --- a/lib/guestfs.pod +++ b/lib/guestfs.pod @@ -679,6 +679,39 @@ servers. The server string is documented in L</guestfs_add_drive_opts>. The C<username> and C<secret> parameters are also optional, and if not given, then no authentication will be used.
+An encrypted RBD disk -- I<directly> opening which would require the +C<username> and C<secret> parameters -- cannot be accessed if the +following conditions all hold: + +=over 4 + +=item * + +the L<backend|/BACKEND> is libvirt, + +=item * + +the image specified by the C<filename> parameter is different from the +encrypted RBD disk, + +=item * + +the image specified by the C<filename> parameter has L<qcow2 +format|/COMMON VIRTUAL DISK IMAGE FORMATS>, + +=item * + +the encrypted RBD disk is specified as a backing file at some level in +the qcow2 backing chain. + +=back + +This limitation is due to libvirt's (justified) separate handling of +disks vs. secrets. When the RBD username and secret are provided inside +a qcow2 backing file specification, libvirt does not construct an +ephemeral secret object from those, for Ceph authentication. Refer to +L<https://bugzilla.redhat.com/2033247>. + =head3 FTP, HTTP AND TFTP
Seems fine. I had to look at perlpod(1) to check that the piped L<> references were correct, but they seem to be!
Acked-by: Richard W.M. Jones <rjones@redhat.com>
Rich.
Commit 544bb0ff5079 ("guestfs.pod: document encrypted RBD disk limitation", 2022-05-19). Thanks Laszlo
participants (2)
-
Laszlo Ersek -
Richard W.M. Jones