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

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 at 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.)

(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

  Failed to connect to '/tmp/v2v.sKlulY/in0': Permission denied

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?
> 
>   If you have just installed libvirt and virt-v2v then you may see the
>   error above.  This is caused by libvirt daemons that provide various
>   services not running straight after installation.  (This may depend
>   on your distribution and vendor presets).
> 
>   To fix this do:
> 
>   <<commands you need to run to fix it>>
> 
>   See also <<link to BZ>>
> 
> Rich.
> 
Laszlo

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 at 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