[Libguestfs] [PATCH 6/9] Documentation: Update virt-v2v man page
Matthew Booth
mbooth at redhat.com
Fri Feb 12 09:39:19 UTC 2010
Correct example command lines
Add references to ESX
Add preparation steps for both ESX and Xen guests
Remove reference to reged
Additional minor cleanups
---
v2v/virt-v2v.pl | 251 ++++++++++++++++++++++++++++++++----------------------
1 files changed, 149 insertions(+), 102 deletions(-)
diff --git a/v2v/virt-v2v.pl b/v2v/virt-v2v.pl
index a0559e9..84f67f1 100755
--- a/v2v/virt-v2v.pl
+++ b/v2v/virt-v2v.pl
@@ -48,67 +48,16 @@ virt-v2v - Convert a guest to use KVM
=head1 SYNOPSIS
- virt-v2v guest-domain.xml
+ virt-v2v -f virt-v2v.conf -i libvirtxml guest-domain.xml
- virt-v2v -f virt-v2v.conf guest-domain.xml
-
- virt-v2v -ic qemu:///system guest-domain
+ virt-v2v -f virt-v2v.conf -ic esx://esx.server/ -op transfer guest-domain
=head1 DESCRIPTION
-Virt-v2v converts guests from one virtualization hypervisor to
-another. Currently it is limited in what it can convert. See the
-table below.
-
-=begin html
-
-<table border="1" style="border-collapse: collapse">
- <tr>
- <th>Source</th>
- <th>Target</th>
- </tr>
-
- <tr>
- <td valign="top" style="padding: 0 0.5em 0 0.5em">
- <p>Xen domain managed by libvirt</p>
- <p>Guest
- <ul>
- <li>PV or FV Kernel</li>
- <li>with or without PV drivers</li>
- <li>RHEL 3.x, 4.x, 5.x</li>
- </ul>
- </p>
- </td>
- <td valign="top" style="padding: 0 0.5em 0 0.5em">
- <p>KVM domain managed by libvirt</p>
- <p>Guest
- <ul>
- <li>with virtio drivers if support by guest</li>
- </ul>
- </p>
- </td>
- </tr>
-</table>
-
-=end html
-
-=begin :man
-
- -------------------------------+----------------------------
- SOURCE | TARGET
- -------------------------------+----------------------------
- Xen domain managed by | KVM domain managed by
- libvirt | libvirt
- |
- Guest: | Guest:
- - PV or FV kernel | - with virtio drivers
- - with or without PV drivers | if supported by guest
- - RHEL 3.x, 4.x, 5.x |
- |
- |
- -------------------------------+----------------------------
-
-=end :man
+virt-v2v converts guests from a foreign hypervisor to run on KVM, managed by
+libvirt. It can currently convert Red Hat Enterprise Linux and Fedora guests
+running on Xen and VMware ESX. It will enable VirtIO drivers in the converted
+guest if possible.
=head1 OPTIONS
@@ -120,8 +69,8 @@ my $input_method = "libvirt";
=item B<-i input>
-Specifies how the conversion source metadata can be obtained. The default is
-C<libvirt>. Supported options are:
+Specifies what input method to use to obtain the guest for conversion. The
+default is C<libvirt>. Supported options are:
=over
@@ -131,7 +80,7 @@ Guest argument is the name of a libvirt domain.
=item I<libvirtxml>
-Guest argument is the path to an XML file describing a libvirt domain.
+Guest argument is the path to an XML file containing a libvirt domain.
=back
@@ -151,6 +100,7 @@ my $input_transport;
=item B<-it method>
Species the transport method used to obtain raw storage from the source guest.
+This is currently only a placeholder, and does nothing.
=cut
@@ -161,6 +111,10 @@ my $output_uri = "qemu:///system";
Specifies the libvirt connection to use to create the converted guest. If
ommitted, this defaults to qemu:///system.
+B<N.B.> virt-v2v must be able to write directly to storage described by this
+libvirt connection. This makes writing to a remote connection impractical at
+present.
+
=cut
my $output_pool;
@@ -174,7 +128,7 @@ guest.
my $config_file;
-=item B<-f file>
+=item B<-f file> | B<--config file>
Load the virt-v2v configuration from I<file>. There is no default.
@@ -493,64 +447,159 @@ sub inspect_guest
return $os;
}
-=head1 PREPARING TO RUN VIRT-V2V
+=head1 PREPARING TO CONVERT A GUEST
+
+=head2 Xen guests
+
+The following steps are required before converting a Xen guest. Note that only
+local Xen guests are currently supported. These steps are not required for
+conversions from ESX, and will not be required for remote Xen guests when we
+support that.
-=head2 Backup the guest
+=head3 Backup the guest
-Virt-v2v converts guests 'in-place': it will make changes to a guest directly
-without creating a backup. It is recommended that virt-v2v be run against a
-copy.
+If converting a local guest using the libvirtxml input method, the guest will be
+converted in place: it will make changes to a guest directly without creating a
+backup. It is recommended that virt-v2v be run against a copy.
The L<v2v-snapshot(1)> tool can be used to convert a guest to use a snapshot
for storage prior to running virt-v2v against it. This snapshot can then be
committed to the original storage after the conversion is confirmed as
successful.
-The L<virt-clone(1)> tool can make a complete copy of a guest, including all its
-storage.
-
-=head2 Obtain domain XML for the guest domain
+=head3 Obtain domain XML for the guest domain
-Virt-v2v uses a libvirt domain description to determine the current
+virt-v2v uses a libvirt domain description to determine the current
configuration of the guest, including the location of its storage. This should
be obtained from the host running the guest pre-conversion by running:
virsh dumpxml <domain> > <domain>.xml
-=head1 CONVERTING A GUEST
+This will require a reboot if the host running Xen is the same host that will
+run KVM. This is because libvirt needs to connect to a running xen hypervisor to
+obtain its metadata.
+
+=head2 ESX guests
+
+=head3 Create a local storage pool for transferred storage
+
+virt-v2v copies the guest storage to the local machine during import from an ESX
+server. It creates new storage in a locally defined libvirt pool. This pool can
+be defined using any libvirt tool, and can be of any type.
+
+The simplest way to create a new pool is with virt-manager(1). Pools can be
+defined from the Storage tab under Host Details.
+
+=head2 All guests
+
+=head3 Create local network interfaces
+
+The local machine must have an appropriate network for the converted guest
+to connect to. This is likely to be a bridge interface. A bridge interface can
+be created using standard tools on the host.
+
+Since version 0.8.3, virt-manager(1) can also create and manage bridges.
+
+=head1 CONVERTING A LOCAL XEN GUEST
+
+The following requires that the domain XML is available locally, and that the
+storage referred to in the domain XML is available locally at the same paths.
+
+To perform the conversion, run:
+
+ virt-v2v -f virt-v2v.conf -i libvirtxml <domain>.xml
+
+where C<< <domain>.xml >> is the path to the exported guest domain's xml. virt-v2v.conf should specify:
+
+=over
+
+=item *
+
+a mapping for the guest's network configuration.
+
+=item *
+
+app definitions for any required replacement kernels.
-In the simplest case, virt-v2v can be run as follows:
+=back
+
+See L<virt-v2v.conf(5)> for details.
- virt-v2v <domain>.xml
+You can avoid having to specify replacement kernels by ensuring that the guest
+has a fully virt kernel installed prior to conversion. Note that it doesn't have
+to be the default kernel.
-where C<< <domain>.xml >> is the path to the exported guest domain's xml. This
-is the simplest form of conversion. It can only be used when the guest has an
-installed kernel which will boot on KVM, i.e. a guest with only paravirtualised
-Xen kernels installed will not work. Virtio will be configured if it is
-supported, otherwise the guest will be configured to use non-virtio drivers. See
-L</GUEST DRIVERS> for details of which drivers will be used.
+=head2 CONVERTING A GUEST FROM VMWARE ESX
+
+virt-v2v can convert a guest from VMware ESX, including transferring its
+storage.
-Virt-v2v can also be configured to install new software into a guest. This might
-be necessary if the guest will not boot on KVM without modification, or if you
-want to upgrade it to support virtio during conversion. Doing this requires
-specifying a configuration file describing where to find the new software. In
-this case, virt-v2v is called as:
+B<N.B.> virt-v2v does not transfer snapshots from ESX. Only the latest flat
+storage is transferred.
- virt-v2v -s <virt-v2v.conf> <domain>.xml
+The guest MUST be shut down in ESX before conversion starts. virt-v2v will not
+proceed if the guest is still running. To convert the guest, run:
-See L<virt-v2v.conf(5)> for details of this configuration file. During the
-conversion process, if virt-v2v does not detect that the guest is capable of
-supporting virtio it will try to upgrade components to resolve this. On Linux
-guests this will involve upgrading the kernel, and may involve upgrading
-dependent parts of userspace.
+ virt-v2v -f virt-v2v.conf -ic esx://<esx.server>/ -op <pool> <domain>
+
+where:
+
+=over
-To text boot the new guest in KVM, run:
+=item *
- virsh start <domain>
- virt-viewer <domain>
+E<lt>esx.serverE<gt> is the hostname of the ESX server hosting the guest to be
+converted.
-If you have created a guest snapshot using L<v2v-snapshot(1)>, it can be
-committed or rolled back at this stage.
+B<N.B.> This hostname must match the hostname reported in the ESX server's SSL
+certificate, or verification will fail.
+
+=item *
+
+E<lt>poolE<gt> is the name of the local storage pool where copies of the guest's
+storage will be created.
+
+=item *
+
+E<lt>domainE<gt> is the name of the guest on the ESX server which is to be
+converted.
+
+=back
+
+virt-v2v.conf should specify a mapping for the guest's network configuration.
+See L<virt-v2v.conf(5)> for details.
+
+=head3 Authenticating to the ESX server
+
+Connecting to the ESX server will require authentication. virt-v2v supports
+password authentication when connecting to ESX. It reads passwords from
+$HOME/.netrc. The format of this file is described in L<netrc(5)>. An example
+entry is:
+
+ machine esx01.example.com login root password s3cr3t
+
+=head3 Connecting to an ESX server with an invalid certificate
+
+In non-production environments, the ESX server may have a non-valid certificate,
+for example a self-signed certificate. In this case, certificate checking can be
+explicitly disabled by adding '?no_verify=1' to the connection URI as shown
+below:
+
+ ... -ic esx://<esx.server>/?no_verify=1 ...
+
+=head1 RUNNING THE CONVERTED GUEST
+
+On successful completion, virt-v2v will create a new libvirt domain for the
+converted guest with the same name as the original guest. It can be started as
+usual using libvirt tools, for example virt-manager(1).
+
+=head1 POST-CONVERSION TASKS
+
+=head2 Guest network configuration
+
+virt-v2v cannot currently reconfigure a guest's network configuration. If the
+converted guest is not connected to the same subnet as the source, its network
+configuration may have to be updated.
=head1 GUEST CONFIGURATION CHANGES
@@ -597,7 +646,7 @@ root device, whether it is using virtio or not.
=head1 GUEST DRIVERS
-Virt-v2v will install the following drivers in a Linux guest:
+Virt-v2v will configure the following drivers in a Linux guest:
=head2 VirtIO
@@ -615,12 +664,10 @@ Additionally, initrd will preload the virtio_pci driver.
=head1 SEE ALSO
-L<v2v-snapshot(1)>
+L<virt-manager(1)>,
+L<v2v-snapshot(1)>,
L<http://libguestfs.org/>.
-For Windows registry parsing we require the C<reged> program
-from L<http://home.eunet.no/~pnordahl/ntpasswd/>.
-
=head1 AUTHOR
Richard W.M. Jones L<http://et.redhat.com/~rjones/>
@@ -629,7 +676,7 @@ Matthew Booth <mbooth at redhat.com>
=head1 COPYRIGHT
-Copyright (C) 2009 Red Hat Inc.
+Copyright (C) 2009,2010 Red Hat Inc.
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
--
1.6.6
More information about the Libguestfs
mailing list