On 6/28/23 14:38, Richard W.M. Jones wrote: > 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?
Yep, that's my point exactly. Laszlo > > (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. > _______________________________________________ Libguestfs mailing list Libguestfs@redhat.com https://listman.redhat.com/mailman/listinfo/libguestfs
