Re: [Libguestfs] [v2v PATCH] docs/virt-v2v: document libvirt system instance startup

On Wed, Jun 28, 2023 at 01:31:53PM +0200, Laszlo Ersek wrote: > On 6/28/23 12:05, Richard W.M. Jones wrote: >> On Tue, Jun 27, 2023 at 07:14:36PM +0200, Laszlo Ersek wrote: >>> It has frequently tripped us up that on RHEL / Fedora, installing the >>> right set of libvirt RPMs (such as the one pulled in by >>> "libvirt-daemon-kvm") does not result in an immediately running libvirt >>> system instance. Document the need, and the simplest method, for starting >>> libvirt up manually. >>> >>> Thanks: Daniel Berrangé >>> Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=2182024 >>> Signed-off-by: Laszlo Ersek <lersek(a)redhat.com&gt; >>> --- >>> >>> Notes: >>> context:-U12 >>> >>> docs/virt-v2v.pod | 20 +++++++++++++++++++- >>> 1 file changed, 19 insertions(+), 1 deletion(-) >>> >>> diff --git a/docs/virt-v2v.pod b/docs/virt-v2v.pod >>> index 4d2f241ad723..2bd0b4425d80 100644 >>> --- a/docs/virt-v2v.pod >>> +++ b/docs/virt-v2v.pod >>> @@ -250,24 +250,26 @@ metadata. virt-v2v tries to guess the best default metadata. This is >>> usually adequate but you can get finer control (eg. of memory and >>> vCPUs) by using I<-i libvirtxml> instead. Only guests that use a single >>> disk can be imported this way. >>> >>> =item B<-i> B<libvirt> >>> >>> Set the input method to I<libvirt>. This is the default. >>> >>> In this mode you have to specify a libvirt guest name or UUID on the >>> command line. You may also specify a libvirt connection URI (see >>> I<-ic>). >>> >>> +See L</Starting the libvirt system instance> in addition. >>> + >> >> I would just say "below" instead of "in addition", it seems a bit >> more natural. >> >>> =item B<-i> B<libvirtxml> >>> >>> Set the input method to I<libvirtxml>. >>> >>> In this mode you have to pass a libvirt XML file on the command line. >>> This file is read in order to get metadata about the source guest >>> (such as its name, amount of memory), and also to locate the input >>> disks. See L</Minimal XML for -i libvirtxml option> below. >>> >>> =item B<-i> B<local> >>> >>> This is the same as I<-i disk>. >>> @@ -461,25 +463,26 @@ and guest metadata is created in the associated YAML file: >>> >>> /dir/name.yaml >>> >>> where C<name> is the guest name. >>> >>> =item B<-o> B<libvirt> >>> >>> Set the output method to I<libvirt>. This is the default. >>> >>> In this mode, the converted guest is created as a libvirt guest. You >>> may also specify a libvirt connection URI (see I<-oc>). >>> >>> -See L<virt-v2v-output-local(1)>. >>> +See L</Starting the libvirt system instance> and >>> +L<virt-v2v-output-local(1)> in addition. >> >> Same here. >> >>> =item B<-o> B<local> >>> >>> Set the output method to I<local>. >>> >>> In this mode, the converted guest is written to a local directory >>> specified by I<-os /dir> (the directory must exist). The converted >>> guest’s disks are written as: >>> >>> /dir/name-sda >>> /dir/name-sdb >>> [etc] >>> @@ -1373,24 +1376,26 @@ manually change ownership after virt-v2v has finished. >>> =item Writing to libvirt >>> >>> When using I<-o libvirt>, you may need to run virt-v2v as root so that >>> it can write to the libvirt system instance (ie. C<qemu:///system>) >>> and to the default location for disk images (usually >>> F</var/lib/libvirt/images>). >>> >>> You can avoid this by setting up libvirt connection authentication, >>> see L<http://libvirt.org/auth.html>;. Alternatively, use >>> I<-oc qemu:///session>, which will write to your per-user libvirt >>> instance. >>> >>> +See also L</Starting the libvirt system instance>. >>> + >>> =item Writing to Openstack >>> >>> Because of how Cinder volumes are presented as F</dev> block devices, >>> using I<-o openstack> normally requires that virt-v2v is run as root. >>> >>> =item Writing to Glance >>> >>> This does I<not> need root (in fact it probably won’t work), but may >>> require either a special user and/or for you to source a script that >>> sets authentication environment variables. Consult the Glance >>> documentation. >>> >>> @@ -1521,24 +1526,37 @@ displayed to the user. >>> The calling program should treat messages sent to stderr as error >>> messages. In addition, virt-v2v exits with a non-zero status >>> code if there was a fatal error. >>> >>> =back >>> >>> Virt-v2v E<le> 0.9.1 did not support the I<--machine-readable> >>> option at all. The option was added when virt-v2v was rewritten in 2014. >>> >>> It is possible to specify a format string for controlling the output; >>> see L<guestfs(3)/ADVANCED MACHINE READABLE OUTPUT>. >>> >>> +=head2 Starting the libvirt system instance >>> + >>> +If you have just installed the libvirt distribution packages, then >>> +dependent on your distribution and its vendor presets, the modular >>> +libvirt daemons providing the various services of the libvirt system >>> +instance may not be running yet. Therefore, if you intend to connect to >>> +the libvirt system instance with virt-v2v (see S<I<-i libvirt>> / >>> +I<-ic>, and/or S<I<-o libvirt>> / I<-oc>), first verify that the libvirt >>> +services are running, before invoking virt-v2v. For example, on Fedora >>> +and RHEL, you may have to start the related services individually with >>> +C<systemctl>, or (recommended) start them all with S<C<systemctl isolate >>> +multi-user.target>>. See L<https://bugzilla.redhat.com/2182024>;. >>> + >> >> I think this would be better if it showed the error message that is >> actually printed when it fails. Almost everyone will arrive here by >> searching for the error message, and therefore it's better to start >> with that. I think something like below gets straight to the point: >> >> =head2 Starting the libvirt system instance >> >> <<the error message here>> > > I don't think we have one particular error message to quote here. > > (1) If libguestfs fails to start the appliance via libvirt, or virt-v2v > fails to make a read-write connection to libvirtd (for -i libvirt or -o > libvirt), then those are all fatal errors, and whatever exception the > outermost handler reports, it will contain some variation of > > Failed to connect socket to '/var/run/libvirt/virtqemud-sock': No such file or directory > Failed to connect socket to '/var/run/libvirt/virtqemud-sock-ro': Connection refused > > (Note: already two socket pathnames and two possible errno values -- 4 > variations.) I think it just needs to give an example or two of the error. People will be able to work out the general pattern. > (2) If the logic from commit 4e7f20684373 fails to make a read-only > connection to libvirtd, we suppress that exception (only log it to the > verbose log), and the user only sees the consequent failure Looking at 4e7f20684373, I think the suppression of the error from the read-only connection was basically a coincidence. We want to get the qemu username from libvirt, we make a read-only connection, and because we're only doing a best effort attempt to chown the socket we ignore the error. But ... > Failed to connect to '/tmp/v2v.sKlulY/in0': Permission denied ... this suggests that maybe we really do want to chown the socket and we shouldn't be making it best-effort at all, but should fail if it's not possible. What do you think about that as a change?

(This yet again comes back to the ancient libvirt bug https://bugzilla.redhat.com/show_bug.cgi?id=890291) > There could be further failure modes. > > If we want to make this consistent (i.e., quote just one error message > in the docs), then at least we should undo the exception suppression > from commit 4e7f20684373 -- let that exception reach the outermost > handler. > > BTW, what's the right way to quote a long (likely to-be-wrapped) error > message in our POD docs? You can just use a long line if it's what is actually displayed. I was fairly sure that podwrapper checks for long lines and makes an exception for verbatim text, but I can't find that right now ... Rich.