[Libguestfs] [PATCH 6/9] Documentation: Update virt-v2v man page

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(a)redhat.com&gt; =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