2 virt-p2v - P2V (physical to virtual machine) migration tool
8 virt-p2v is a live CD for migrating physical machines to virtual machine
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
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.
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.
27 The "virt-p2v" script must only be run from the live CD environment. It
28 isn't designed to run outside this environment and could do Bad Things
29 to your machine if you try it. The script contains some checks to try to
30 stop you from doing this.
32 Virt-p2v does not modify the physical machine, its disks, configuration
35 USB key and PXE boot options are also available. See sections PXE
36 BOOTING and BOOTING FROM A USB KEY below.
39 After booting the live CD-R, you are presented with a series of
40 questions. This section explains each question.
43 Enter the name or IP address of the virtualization host. This is the
44 host running Xen (or any other virtualization system supported by
45 libvirt, eg. QEMU). This host should be accessible on the network
46 and running an SSH daemon ("sshd").
49 This is the port name or number of the SSH server on the remote
50 host. The default is 22 which is the standard SSH port.
53 Enter the directory on the remote host where disk image(s) and
54 configuration file(s) must reside.
56 Note that if the remote host is running SELinux then you may not be
57 able to start a Xen guest unless its disk image(s) are located in
58 the default directory, "/var/lib/xen/images".
61 Enter the remote SSH username to use to log in to the remote host.
63 If you use the default username of "root" then you should ensure
64 that remote root logins are enabled on the remote host (ie.
65 "PermitRootLogin yes" in "/etc/ssh/sshd_config").
68 Choose the way that the live CD configures network access. The
71 Automatic configuration
72 In this mode, the live CD attempts to reuse the network
73 configuration from the physical machine's root filesystem. You
74 should probably try this method even though occasionally it does
77 Ask for fixed IP address and gateway
78 In this mode the live CD will ask you for a fixed IP address and
79 gateway address, and will configure your chosen interface with
82 Configure from the shell
83 In this mode you will be dropped into a command shell and you
84 will need to issue the correct sequence of "/sbin/ifconfig"
85 commands in order to configure the network interface.
87 A typical sequence of commands which should bring up the network
90 /sbin/ifconfig eth0 AA.BB.CC.DD
91 /sbin/route add default gw GG.HH.II.JJ eth0
93 where "AA.BB.CC.DD" is the IP address and "GG.HH.II.JJ" is the
97 This option configures the network for use inside a QEMU user
99 (<http://fabrice.bellard.free.fr/qemu/qemu-doc.html#SEC30>). It
100 should only be used by developers.
103 This question lists out all local block devices (hard disk drives
104 and similar) and asks you to choose which will be sent to the remote
105 host. You must send at least one block device.
108 This question lists out possible root filesystems and asks you to
109 choose the right one. Choose the filesystem which would normally be
110 mounted as "/" on the system.
112 Virt-p2v performs some autodetection and is in most cases able to
113 work out which filesystems are possible root filesystems. It
114 displays what it thinks is on each filesystem, but leaves it up to
115 the user to make a final decision.
117 The root filesystem is critical because it contains "/etc/fstab".
118 This is used during P2V both to determine how other filesystems are
119 normally mounted on the machine, and because this file and others
120 under "/etc" may need to be modified during P2V conversion.
122 If the machine has more than one root filesystem (typically because
123 the machine is dual-booted with another operating system), then you
124 must choose only one of them to perform the P2V conversion on.
127 This question asks you to choose the hypervisor / virtualization
128 system in use on the remote host.
130 If you select *Xen*, *QEMU* or *KVM* then virt-p2v will produce a
131 configuration file which is customized for the selected system. If
132 you select *Other* then virt-p2v will produce a generic
133 configuration file which will probably require hand-modification to
136 See also <http://libvirt.org/format.html>.
139 This question asks you to choose the machine architecture. Virt-p2v
140 can normally detect this, so you should leave it as *Auto-detect*.
143 This question asks you to choose the amount of memory (RAM) in
144 megabytes assigned to the virtual machine.
146 If the entry is left blank, then virt-p2v will try to autodetect how
147 much RAM is present in the physical machine and use that, and this
148 is probably a good choice for most simple migrations.
151 This question asks you to choose the number of virtual CPUs assigned
152 to the virtual machine. Choosing 1 causes the virtual machine to be
153 uniprocessor, and choosing some number greater than 1 causes the
154 virtual machine to be SMP.
156 If the entry is left blank, then virt-p2v will try to autodetect how
157 many CPU cores are present in the physical machine and use that, and
158 this is probably a good choice for most simple migrations.
161 Here you should enter a MAC address for the virtual machine's
162 emulated network card. MAC addresses are written as
163 "aa:bb:cc:dd:ee:ff" where "aa", "bb" etc are hexadecimal octets.
165 Leaving it blank will cause virt-p2v to choose a random MAC address
166 within the "00:16:3e:.." space reserved for Xen guests. These MAC
167 addresses are not tested for uniqueness so there is a very small
168 chance that they could coincide, which would leave a guest unable to
169 access the virtual network.
172 Choose whether to enable or disable compression on disk images as
173 they are copied across the network.
175 If enabled, the "-C" option is passed to ssh(1). On fast networks
176 this can sometimes be slower.
178 NB: The disk image is still stored uncompressed on the remote host
179 however this option is set.
182 In this step you are asked to verify the settings above. If any are
183 incorrect, use the *Back* button to navigate back to the setting. If
184 all settings are correct, use the *OK* button to begin the P2V
187 Network autoconfiguration
188 If you selected network autoconfiguration above then virt-p2v tries
189 to autoconfigure the network and ping the remote host. It then asks
190 *Did automatic network configuration work?*
192 You should answer "y" here if it worked.
194 Answering "n" will drop you into a command shell.
196 You can also switch to another virtual console if you need to
197 perform additional tests. See section GETTING A SHELL below.
200 Unless you have set up an SSH key, or the SSH server on the remote
201 host allows passwordless logins, then for each file that has to be
202 transferred to the remote host you will need to confirm the identity
203 of the remote host and/or enter a password.
205 To understand more about this, please see the ssh(1) manual page.
207 BOOTING P2V GUEST ON VIRTUALIZATION HOST
208 Once the P2V conversion has been completed, and assuming it was
209 successful, you will find a configuration file and one or more disk
210 images on the remote host.
212 The files will be located in the directory selected, usually
213 "/var/lib/xen/images". The names of the files are made up of:
215 "p2v-*hostname*-*YYYYMMDDHHMM*.conf" or
216 "p2v-*hostname*-*YYYYMMDDHHMM*-hd*X*.img"
218 To simply start up the guest, use the following commands as root:
220 virsh define p2v-foo-2008MMDDHHMM.conf
225 virsh -c qemu:///system define p2v-foo-2008MMDDHHMM.conf
226 virsh -c qemu:///system start foo
228 For other hypervisors you will need to edit the configuration file and
229 read <http://libvirt.org/uri.html>.
232 During all stages of P2V questions and conversion you can get a root
233 shell on the physical machine. Use *ALT* *F2* keys to switch to the
234 second virtual console, then log in as *root* with no password.
237 Virt-p2v writes a detailed log file to "/tmp/virt-p2v.log". (Note that
238 this "/tmp" directory is a ramdisk on the live CD, not the same as the
239 "/tmp" directory of the physical machine, and more importantly it
240 disappears when the machine is rebooted).
242 If you are reporting a bug, please always supply this file.
245 The virtualization host (remote host) must be running an SSH daemon
246 ("sshd"), accessible from the physical machine which is being migrated.
248 Previous versions of virt-p2v could use a special virt-p2v server.
249 However this capability has been removed since there was practically no
252 BUILDING A CUSTOM LIVE CD
253 To build a custom live CD you must download the source for virt-p2v from
254 <http://et.redhat.com/~rjones/virt-p2v/> or from the Mercurial source
255 repository (see website for details).
257 Please read the "README" file to find the dependencies which are all in
258 Fedora > 8 or EPEL > 5.
260 The steps to creating a custom live CD are:
262 1. Edit "virt-p2v" and adjust defaults
263 Find the section "TO MAKE A CUSTOM virt-p2v SCRIPT ..." which is
264 near to the top of this file. Edit the defaults in this section as
267 2. "virt-p2v --test" to verify your changes
268 This command should not print anything at all. If it prints any
269 message, then you will need to fix the error by going back to the
272 3. "make build" or "make update" to build a custom live CD
273 "make build" will create a complete ISO from scratch. "make update"
274 can be used to build a "quick" developer ISO by updating an existing
275 ISO image. See section ISO ATTACHMENTS below for more details.
277 4. Burn the ISO to a CD-R and test
279 EDITING DEFAULTS IN THE "virt-p2v" SCRIPT
280 For each default, setting it to "None" will ask the user. All of the
281 defaults are set to "None" in the standard, uncustomized virt-p2v
282 script, and so the standard script asks all the questions.
284 You may edit "virt-p2v" and change the defaults, in which case the user
285 will not be questioned. In this way you can make the script partially or
288 *Note about OCaml code:* "None" and "Some foo" are similar to the
289 concept of a NULL pointer versus non-NULL pointer in other languages.
290 This a variant type defined as:
292 type α option = None | Some of α
295 If this is "true" then we wait for a keypress after boot and at a
296 couple of other stages. If set to "false" then we try not to wait
297 for any keypresses (so more automated live CDs are possible).
300 Set this to "Some "hostname"" or "Some "IP-address"" to provide the
301 name of the remote host.
304 Set this to "Some port" (eg. "Some 22") to provide the port number
305 of the remote host's SSH daemon.
308 Set this to "Some "path"" (eg. "Some "/var/lib/xen/images"") to
309 provide the directory where we update P2V converted images and
313 Set this to "Some "username"" (eg. "Some "root"") to provide the SSH
314 username to use on the remote system.
317 Set this to a list of block devices to send to the remote system.
318 For example, "Some ["sda"; "sdb"]".
321 Set this to the name of the root filesystem.
323 For a disk partition (eg. "/dev/sda1"), use:
325 Some (Part ("sda", "1"))
327 For a logical volume (eg. "/dev/VolGroup00/LogVol00"), use:
329 Some (LV ("VolGroup00", "LogVol00"))
332 Set this to the choice for network setup. Use one of:
335 for auto-configuration
338 to specify the interface, address, netmask and gateway
345 to use a QEMU user network (developers only)
347 "static_network_config"
348 This setting only applies if "network" is set to "Some Static", in
349 which case you should set this to the static network settings, a
350 tuple of (interface, address, netmask, gateway, nameserver):
352 Some ("eth0", "192.168.2.5", "255.255.255.0", "192.168.2.1", "192.168.2.1")
355 Set this to the choice of hypervisor or virtualization system. The
356 choices are: "Some Xen", "Some QEMU" or "Some KVM".
359 Set this to the architecture. The choices are: "Some I386" (i386 and
360 up, 32 bit), "Some X86_64" (AMD and Intel x86-64, 64 bit), "Some
361 IA64" (Intel IA64), "Some PPC" (PowerPC, 32 bit), "Some PPC64"
362 (PowerPC, 64 bit), "Some SPARC" (Sun SPARC, 32 bit), "Some SPARC64"
363 (Sun SPARC, 64 bit), "OtherArch "foo"" (a hypothetical architecture
364 called *foo*), or "UnknownArch" to auto-detect the architecture.
367 Set this to the size of memory in megabytes, eg. "Some 256". If you
368 set this to "Some 0" then virt-p2v will try to autodetect the amount
369 of RAM installed on the physical machine.
372 Set this to the number of virtual CPUs, eg. "Some 1". If you set
373 this to "Some 0" then virt-p2v will try to autodetect the number of
374 CPU cores on the physical machine.
377 Set this to the MAC address for the virtual network card, eg. "Some
378 "aa:bb:cc:dd:ee:ff"". If you set this to "Some """ then virt-p2v
379 will choose a random MAC address within the "00:16:3e:.." space
380 reserved for Xen guests. These MAC addresses are not tested for
381 uniqueness so there is a very small chance that they could coincide,
382 which would leave a guest unable to access the virtual network.
385 Set this to "Some false" to disable compression, or "Some true" to
386 enable compression, or "None" to ask the user.
389 Rebuilding a custom ISO is time-consuming. You can make a "quick"
390 developer ISO by updating an existing ISO image with a new custom
391 "virt-p2v" script. This is useful for testing purposes.
393 From the source directory, assuming that you have downloaded or built an
394 existing "virt-p2v-*.iso", you can just do:
398 or the equivalent manual command:
400 ./iso-attach virt-p2v-VERSION.iso virt-p2v
402 Note that ISO attachments only work with real (and emulated) CD-Rs, not
403 with other methods of booting such as USB keys and PXE.
406 If you wish to boot over the network using PXE, use the
407 "livecd-iso-to-pxeboot" script (part of "livecd-tools").
409 livecd-iso-to-pxeboot virt-p2v-$VERSION.iso
411 then copy the generated subdirectory "tftpboot/" to the right place for
412 your PXE configuration.
414 Pre-built PXE boot images are also available on the website.
416 General configuration of DHCP, TFTP and PXE for network booting are
417 outside the scope of this document.
419 BOOTING FROM A USB KEY
420 If you wish to boot from a USB keydrive, use the "livecd-iso-to-disk"
421 script (part of "livecd-tools"):
423 livecd-iso-to-disk virt-p2v-$VERSION.iso /dev/sdX1
425 (Replace /dev/sdX1 with the actual USB device).
427 In my experience I also had to set up a suitable MBR:
429 cat /usr/lib/syslinux/mbr.bin > /dev/sdX
431 TESTING AN ISO UNDER QEMU OR KVM
432 If you have a virtual guest running under QEMU or KVM then you can test
433 the P2V conversion process on the guest.
435 (Technically this is a V2V -- virtual to virtual -- conversion).
437 From the source directory do:
439 make boot HDA=qemuimage.img
441 where "qemuimage.img" is the name of the QEMU/KVM image.
443 You can also supply an "HDB" parameter to specify a second disk.
446 Please direct questions to the et-mgmt-tools mailing list
447 <http://www.redhat.com/mailman/listinfo/et-mgmt-tools> <et-mgmt-tools @
451 virsh(1), <http://www.libvirt.org/ocaml/>, <http://www.libvirt.org/>,
452 <http://et.redhat.com/~rjones/>, <http://caml.inria.fr/>
455 Richard W.M. Jones <rjones @ redhat . com>
458 (C) Copyright 2007-2008 Red Hat Inc., Richard W.M. Jones
461 This program is free software; you can redistribute it and/or modify it
462 under the terms of the GNU General Public License as published by the
463 Free Software Foundation; either version 2 of the License, or (at your
464 option) any later version.
466 This program is distributed in the hope that it will be useful, but
467 WITHOUT ANY WARRANTY; without even the implied warranty of
468 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
469 Public License for more details.
471 You should have received a copy of the GNU General Public License along
472 with this program; if not, write to the Free Software Foundation, Inc.,
473 675 Mass Ave, Cambridge, MA 02139, USA.
476 Bugs can be viewed on the Red Hat Bugzilla page:
477 <https://bugzilla.redhat.com/>.
479 If you find a bug in virt-p2v, please follow these steps to report it:
481 1. Check for existing bug reports
482 Go to <https://bugzilla.redhat.com/> and search for similar bugs.
483 Someone may already have reported the same bug, and they may even
486 2. Capture debug and error messages
487 At the point where you get the error or unexpected behaviour, go to
488 the second virtual console (*ALT* *F2*) and look at the logfile
489 "/tmp/virt-p2v.log". Please make sure that this file is attached to
492 3. Get version of virt-p2v
493 The version is in the name of the ISO. If you have built a custom
494 virt-p2v ISO, please describe any changes that you have made.
496 4. Submit a bug report.
497 Go to <https://bugzilla.redhat.com/> and enter a new bug. Please
498 describe the problem in as much detail as possible.
500 Remember to include the version number (step 3) and to attach the
503 5. Assign the bug to rjones @ redhat.com
504 Assign or reassign the bug to rjones @ redhat.com (without the
505 spaces). You can also send me an email with the bug number if you
506 want a faster response.