virt-p2v.1.txt

   1 NAME
   2     virt-p2v - P2V (physical to virtual machine) migration tool
   3
   4 SUMMARY
   5     virt-p2v
   6
   7 DESCRIPTION
   8     virt-p2v is a live CD for migrating physical machines to virtual machine
   9     guests.
  10
  11     In the simplest mode of operation, you take a pre-built live CD ISO from
  12     the main website (<http://et.redhat.com/~rjones/virt-p2v/>) and burn it
  13     to a CD-R. Then insert the CD-R into the physical machine which must be
  14     migrated, reboot, and follow the on-screen instructions. See STANDARD
  15     USAGE section below.
  16
  17     You may also build a customized live CD. Typically this will contain
  18     things like server details specific to your organization, so that the
  19     live CD can run mostly or completely automatically. See BUILDING A
  20     CUSTOM LIVE CD section below.
  21
  22     In both cases, files and disk images are transferred from the physical
  23     machine over the network to the virtualization host machine over ssh.
  24     Therefore "sshd" must be running on the virtualization host, and must be
  25     accessible to that host. See SERVER REQUIREMENTS section below.
  26
  27     The "virt-p2v" script must only be run from the live CD. It isn't
  28     designed to run outside this environment and could do Bad Things to your
  29     machine if you try it. The script contains some checks to try to stop
  30     you from doing this.
  31
  32     Virt-p2v does not modify the physical machine, its disks, configuration
  33     etc.
  34
  35 STANDARD USAGE
  36     After booting the live CD-R, you are presented with a series of
  37     questions. This section explains each question.
  38
  39     Remote host
  40         Enter the name or IP address of the virtualization host. This is the
  41         host running Xen (or any other virtualization system supported by
  42         libvirt, eg. QEMU). This host should be accessible on the network
  43         and running an SSH daemon ("sshd").
  44
  45     Remote port
  46         This is the port name or number of the SSH server on the remote
  47         host. The default is 22 which is the standard SSH port.
  48
  49     Remote directory
  50         Enter the directory on the remote host where disk image(s) and
  51         configuration file(s) must reside.
  52
  53         Note that if the remote host is running SELinux then you may not be
  54         able to start a Xen guest unless its disk image(s) are located in
  55         the default directory, "/var/lib/xen/images".
  56
  57     Remote username
  58         Enter the remote SSH username to use to log in to the remote host.
  59
  60         If you use the default username of "root" then you should ensure
  61         that remote root logins are enabled on the remote host (ie.
  62         "PermitRootLogin yes" in "/etc/ssh/sshd_config").
  63
  64     Network configuration
  65         Choose the way that the live CD configures network access. The
  66         current options are:
  67
  68         Automatic configuration
  69             In this mode, the live CD attempts to reuse the network
  70             configuration from the physical machine's root filesystem. You
  71             should probably try this method even though occasionally it does
  72             not work.
  73
  74         Configure from the shell
  75             In this mode you will be dropped into a command shell and you
  76             will need to issue the correct sequence of "/sbin/ifconfig"
  77             commands in order to configure the network interface.
  78
  79             A typical sequence of commands which should bring up the network
  80             interface would be:
  81
  82              /sbin/ifconfig eth0 AA.BB.CC.DD
  83              /sbin/route add default gw GG.HH.II.JJ eth0
  84
  85             where "AA.BB.CC.DD" is the IP address and "GG.HH.II.JJ" is the
  86             gateway.
  87
  88     Devices
  89         This question lists out all local block devices (hard disk drives
  90         and similar) and asks you to choose which will be sent to the remote
  91         host. You must send at least one block device.
  92
  93     Root device
  94         This question lists out possible root filesystems and asks you to
  95         choose the right one. Choose the filesystem which would normally be
  96         mounted as "/" on the system.
  97
  98         Virt-p2v performs some autodetection and is in most cases able to
  99         work out which filesystems are possible root filesystems. It
 100         displays what it thinks is on each filesystem, but leaves it up to
 101         the user to make a final decision.
 102
 103         The root filesystem is critical because it contains "/etc/fstab".
 104         This is used during P2V both to determine how other filesystems are
 105         normally mounted on the machine, and because this file and others
 106         under "/etc" may need to be modified during P2V conversion.
 107
 108         If the machine has more than one root filesystem (typically because
 109         the machine is dual-booted with another operating system), then you
 110         must choose only one of them to perform the P2V conversion on.
 111
 112     Hypervisor
 113         This question asks you to choose the hypervisor / virtualization
 114         system in use on the remote host.
 115
 116         If you select *Xen*, *QEMU* or *KVM* then virt-p2v will produce a
 117         configuration file which is customized for the selected system. If
 118         you select *Other* then virt-p2v will produce a generic
 119         configuration file which will probably require hand-modification to
 120         work.
 121
 122         See also <http://libvirt.org/format.html>.
 123
 124     Machine architecture
 125         This question asks you to choose the machine architecture. Virt-p2v
 126         can normally detect this, so you should leave it as *Auto-detect*.
 127
 128     Memory
 129         This question asks you to choose the amount of memory (RAM) in
 130         megabytes assigned to the virtual machine.
 131
 132         If the entry is left blank, then virt-p2v will try to autodetect how
 133         much RAM is present in the physical machine and use that, and this
 134         is probably a good choice for most simple migrations.
 135
 136     Virtual CPUs
 137         This question asks you to choose the number of virtual CPUs assigned
 138         to the virtual machine. Choosing 1 causes the virtual machine to be
 139         uniprocessor, and choosing some number greater than 1 causes the
 140         virtual machine to be SMP.
 141
 142         If the entry is left blank, then virt-p2v will try to autodetect how
 143         many CPU cores are present in the physical machine and use that, and
 144         this is probably a good choice for most simple migrations.
 145
 146     MAC address
 147         Here you should enter a MAC address for the virtual machine's
 148         emulated network card. MAC addresses are written as
 149         "aa:bb:cc:dd:ee:ff" where "aa", "bb" etc are hexadecimal octets.
 150
 151         Leaving it blank will cause virt-p2v to choose a random MAC address
 152         within the "00:16:3e:.." space reserved for Xen guests. These MAC
 153         addresses are not tested for uniqueness so there is a very small
 154         chance that they could coincide, which would leave a guest unable to
 155         access the virtual network.
 156
 157     Verify and proceed
 158         In this step you are asked to verify the settings above. If any are
 159         incorrect, use the *Back* button to navigate back to the setting. If
 160         all settings are correct, use the *OK* button to begin the P2V
 161         conversion.
 162
 163     Network autoconfiguration
 164         If you selected network autoconfiguration above then virt-p2v tries
 165         to autoconfigure the network and ping the remote host. It then asks
 166         *Did automatic network configuration work?*
 167
 168         You should answer "y" here if it worked.
 169
 170         Answering "n" will drop you into a command shell.
 171
 172         You can also switch to another virtual console if you need to
 173         perform additional tests. See section GETTING A SHELL below.
 174
 175     SSH connection
 176         Unless you have set up an SSH key, or the SSH server on the remote
 177         host allows passwordless logins, then for each file that has to be
 178         transferred to the remote host you will need to confirm the identity
 179         of the remote host and/or enter a password.
 180
 181         To understand more about this, please see the ssh(1) manual page.
 182
 183   BOOTING P2V GUEST ON VIRTUALIZATION HOST
 184     Once the P2V conversion has been completed, and assuming it was
 185     successful, you will find a configuration file and one or more disk
 186     images on the remote host.
 187
 188     The files will be located in the directory selected, usually
 189     "/var/lib/xen/images". The names of the files are made up of:
 190
 191     "p2v-*hostname*-*YYYYMMDDHHMM*.conf" or
 192     "p2v-*hostname*-*YYYYMMDDHHMM*-hd*X*.img"
 193
 194     To simply start up the guest, use the following commands as root:
 195
 196      virsh define p2v-foo-2008MMDDHHMM.conf
 197      virsh start foo
 198
 199     For QEMU/KVM do:
 200
 201      virsh -c qemu:///system define p2v-foo-2008MMDDHHMM.conf
 202      virsh -c qemu:///system start foo
 203
 204     For other hypervisors you will need to edit the configuration file and
 205     read <http://libvirt.org/uri.html>.
 206
 207 GETTING A SHELL
 208     During all stages of P2V questions and conversion you can get a root
 209     shell on the physical machine. Use *ALT* *F2* keys to switch to the
 210     second virtual console, then log in as *root* with no password.
 211
 212   LOG FILE
 213     Virt-p2v writes a detailed log file to "/tmp/virt-p2v.log". (Note that
 214     this "/tmp" directory is a ramdisk on the live CD, not the same as the
 215     "/tmp" directory of the physical machine, and more importantly it
 216     disappears when the machine is rebooted).
 217
 218     If you are reporting a bug, please always supply this file.
 219
 220 SERVER REQUIREMENTS
 221     The virtualization host (remote host) must be running an SSH daemon
 222     ("sshd"), accessible from the physical machine which is being migrated.
 223
 224     Previous versions of virt-p2v could use a special virt-p2v server.
 225     However this capability has been removed since there was practically no
 226     benefit.
 227
 228 BUILDING A CUSTOM LIVE CD
 229     To build a custom live CD you must download the source for virt-p2v from
 230     <http://et.redhat.com/~rjones/virt-p2v/> or from the Mercurial source
 231     repository (see website for details).
 232
 233     Please read the "README" file to find the dependencies which are all in
 234     Fedora &gt; 8 or EPEL &gt; 5.
 235
 236     The steps to creating a custom live CD are:
 237
 238     1. Edit "virt-p2v" and adjust defaults
 239         Find the section "TO MAKE A CUSTOM virt-p2v SCRIPT ..." which is
 240         near to the top of this file. Edit the defaults in this section as
 241         detailed below.
 242
 243     2. "virt-p2v --test" to verify your changes
 244         This command should not print anything at all. If it prints any
 245         message, then you will need to fix the error by going back to the
 246         first step.
 247
 248     3. "make build" or "make update" to build a custom live CD
 249         "make build" will create a complete ISO from scratch. "make update"
 250         can be used to build a "quick" developer ISO by updating an existing
 251         ISO image. See section ISO ATTACHMENTS below for more details.
 252
 253     4. Burn the ISO to a CD-R and test
 254
 255   EDITING DEFAULTS IN THE "virt-p2v" SCRIPT
 256     For each default, setting it to "None" will ask the user. All of the
 257     defaults are set to "None" in the standard, uncustomized virt-p2v
 258     script, and so the standard script asks all the questions.
 259
 260     You may edit "virt-p2v" and change the defaults, in which case the user
 261     will not be questioned. In this way you can make the script partially or
 262     fully automated.
 263
 264     *Note about OCaml code:* "None" and "Some foo" are similar to the
 265     concept of a NULL pointer versus non-NULL pointer in other languages.
 266     This a variant type defined as:
 267
 268     type α option = None | Some of α
 269
 270     "greeting"
 271         If this is "true" then we wait for a keypress after boot and at a
 272         couple of other stages. If set to "false" then we try not to wait
 273         for any keypresses (so more automated live CDs are possible).
 274
 275     "remote_host"
 276         Set this to "Some "hostname"" or "Some "IP-address"" to provide the
 277         name of the remote host.
 278
 279     "remote_port"
 280         Set this to "Some port" (eg. "Some 22") to provide the port number
 281         of the remote host's SSH daemon.
 282
 283     "remote_directory"
 284         Set this to "Some "path"" (eg. "Some "/var/lib/xen/images"") to
 285         provide the directory where we update P2V converted images and
 286         configuration files.
 287
 288     "remote_username"
 289         Set this to "Some "username"" (eg. "Some "root"") to provide the SSH
 290         username to use on the remote system.
 291
 292     "devices_to_send"
 293         Set this to a list of block devices to send to the remote system.
 294         For example, "Some ["sda"; "sdb"]".
 295
 296     "root_filesystem"
 297         Set this to the name of the root filesystem.
 298
 299         For a disk partition (eg. "/dev/sda1"), use:
 300
 301          Some (Part ("sda", "1"))
 302
 303         For a logical volume (eg. "/dev/VolGroup00/LogVol00"), use:
 304
 305          Some (LV ("VolGroup00", "LogVol00"))
 306
 307     "network"
 308         Set this to the choice for network setup. Use either "Some Auto" or
 309         "Some Shell" for auto-configuration or shell (manual) configuration
 310         respectively.
 311
 312     "hypervisor"
 313         Set this to the choice of hypervisor or virtualization system. The
 314         choices are: "Some Xen", "Some QEMU" or "Some KVM".
 315
 316     "architecture"
 317         Set this to the architecture. The choices are: "Some I386" (i386 and
 318         up, 32 bit), "Some X86_64" (AMD and Intel x86-64, 64 bit), "Some
 319         IA64" (Intel IA64), "Some PPC" (PowerPC, 32 bit), "Some PPC64"
 320         (PowerPC, 64 bit), "Some SPARC" (Sun SPARC, 32 bit), "Some SPARC64"
 321         (Sun SPARC, 64 bit), "OtherArch "foo"" (a hypothetical architecture
 322         called *foo*), or "UnknownArch" to auto-detect the architecture.
 323
 324     "memory"
 325         Set this to the size of memory in megabytes, eg. "Some 256". If you
 326         set this to "Some 0" then virt-p2v will try to autodetect the amount
 327         of RAM installed on the physical machine.
 328
 329     "vcpus"
 330         Set this to the number of virtual CPUs, eg. "Some 1". If you set
 331         this to "Some 0" then virt-p2v will try to autodetect the number of
 332         CPU cores on the physical machine.
 333
 334     "mac_address"
 335         Set this to the MAC address for the virtual network card, eg. "Some
 336         "aa:bb:cc:dd:ee:ff"". If you set this to "Some """ then virt-p2v
 337         will choose a random MAC address within the "00:16:3e:.." space
 338         reserved for Xen guests. These MAC addresses are not tested for
 339         uniqueness so there is a very small chance that they could coincide,
 340         which would leave a guest unable to access the virtual network.
 341
 342   ISO ATTACHMENTS
 343     Rebuilding a custom ISO is time-consuming. You can make a "quick"
 344     developer ISO by updating an existing ISO image with a new custom
 345     "virt-p2v" script. This is useful for testing purposes.
 346
 347     From the source directory, assuming that you have downloaded or built an
 348     existing "virt-p2v-*.iso", you can just do:
 349
 350      make update
 351
 352     or the equivalent manual command:
 353
 354      ./iso-attach virt-p2v-VERSION.iso virt-p2v
 355
 356 BOOTING FROM A USB KEY INSTEAD OF A CD
 357     If you wish to boot from a USB keydrive, use the livecd-iso-to-disk
 358     tool:
 359
 360      livecd-iso-to-disk virt-p2v-$VERSION.iso /dev/sdX1
 361
 362     (Replace /dev/sdX1 with the actual USB device).
 363
 364     In my experience I also had to set up a suitable MBR:
 365
 366      cat /usr/lib/syslinux/mbr.bin > /dev/sdX
 367
 368 TESTING AN ISO UNDER QEMU OR KVM
 369     If you have a virtual guest running under QEMU or KVM then you can test
 370     the P2V conversion process on the guest.
 371
 372     (Technically this is a V2V -- virtual to virtual -- conversion).
 373
 374     From the source directory do:
 375
 376      make boot HDA=qemuimage.img
 377
 378     where "qemuimage.img" is the name of the QEMU/KVM image.
 379
 380     You can also supply an "HDB" parameter to specify a second disk.
 381
 382 SEE ALSO
 383     virsh(1), <http://www.libvirt.org/ocaml/>, <http://www.libvirt.org/>,
 384     <http://et.redhat.com/~rjones/>, <http://caml.inria.fr/>
 385
 386 AUTHORS
 387     Richard W.M. Jones <rjones @ redhat . com>
 388
 389 COPYRIGHT
 390     (C) Copyright 2007-2008 Red Hat Inc., Richard W.M. Jones
 391     http://libvirt.org/
 392
 393     This program is free software; you can redistribute it and/or modify it
 394     under the terms of the GNU General Public License as published by the
 395     Free Software Foundation; either version 2 of the License, or (at your
 396     option) any later version.
 397
 398     This program is distributed in the hope that it will be useful, but
 399     WITHOUT ANY WARRANTY; without even the implied warranty of
 400     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
 401     Public License for more details.
 402
 403     You should have received a copy of the GNU General Public License along
 404     with this program; if not, write to the Free Software Foundation, Inc.,
 405     675 Mass Ave, Cambridge, MA 02139, USA.
 406
 407 REPORTING BUGS
 408     Bugs can be viewed on the Red Hat Bugzilla page:
 409     <https://bugzilla.redhat.com/>.
 410
 411     If you find a bug in virt-p2v, please follow these steps to report it:
 412
 413     1. Check for existing bug reports
 414         Go to <https://bugzilla.redhat.com/> and search for similar bugs.
 415         Someone may already have reported the same bug, and they may even
 416         have fixed it.
 417
 418     2. Capture debug and error messages
 419         At the point where you get the error or unexpected behaviour, go to
 420         the second virtual console (*ALT* *F2*) and look at the logfile
 421         "/tmp/virt-p2v.log". Please make sure that this file is attached to
 422         your bug report.
 423
 424     3. Get version of virt-p2v
 425         The version is in the name of the ISO. If you have built a custom
 426         virt-p2v ISO, please describe any changes that you have made.
 427
 428     4. Submit a bug report.
 429         Go to <https://bugzilla.redhat.com/> and enter a new bug. Please
 430         describe the problem in as much detail as possible.
 431
 432         Remember to include the version number (step 3) and to attach the
 433         log file (step 2).
 434
 435     5. Assign the bug to rjones @ redhat.com
 436         Assign or reassign the bug to rjones @ redhat.com (without the
 437         spaces). You can also send me an email with the bug number if you
 438         want a faster response.
 439