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 <ler...@redhat.com> > >> --- > >> > >> 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. -- Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones Read my programming and virtualization blog: http://rwmj.wordpress.com nbdkit - Flexible, fast NBD server with plugins https://gitlab.com/nbdkit/nbdkit _______________________________________________ Libguestfs mailing list Libguestfs@redhat.com https://listman.redhat.com/mailman/listinfo/libguestfs
