Libguestfs - May 2022 - [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 at 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 at 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 at 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