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