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

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.
+
 =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.
 
 =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>.
+
 =head1 FILES
 
 =over 4
 
 =item F</usr/share/virtio-win>
 
 (Optional)
 
 If this directory is present, then virtio drivers for Windows guests
 will be found from this directory and installed in the guest during
 conversion.
 

base-commit: 4f47d6431cab97c09bd42279e29c378e6e65fc03

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

  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.

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
Fedora Windows cross-compiler. Compile Windows programs, test, and
build Windows installers. Over 100 libraries supported.
http://fedoraproject.org/wiki/MinGW