3 virt-p2v - P2V (physical to virtual machine) migration tool
11 virt-p2v is a live CD for migrating physical machines to virtual
14 In the simplest mode of operation, you take a pre-built live CD ISO
15 from the main website (L<http://et.redhat.com/~rjones/virt-p2v/>) and
16 burn it to a CD-R. Then insert the CD-R into the physical machine
17 which must be migrated, reboot, and follow the on-screen instructions.
18 See B<STANDARD USAGE> section below.
20 You may also build a customized live CD. Typically this will contain
21 things like server details specific to your organization, so that the
22 live CD can run mostly or completely automatically. See B<BUILDING A
23 CUSTOM LIVE CD> section below.
25 In both cases, files and disk images are transferred from the physical
26 machine over the network to the virtualization host machine over ssh.
27 Therefore C<sshd> must be running on the virtualization host, and must
28 be accessible to that host. See B<SERVER REQUIREMENTS> section below.
30 The C<virt-p2v> script must only be run from the live CD environment.
31 It isn't designed to run outside this environment and could do Bad
32 Things to your machine if you try it. The script contains some checks
33 to try to stop you from doing this.
35 Virt-p2v does not modify the physical machine, its disks,
38 USB key and PXE boot options are also available. See sections
39 B<PXE BOOTING> and B<BOOTING FROM A USB KEY>
44 After booting the live CD-R, you are presented with a series of
45 questions. This section explains each question.
51 Enter the name or IP address of the virtualization host. This is the
52 host running Xen (or any other virtualization system supported by
53 libvirt, eg. QEMU). This host should be accessible on the network and
54 running an SSH daemon (C<sshd>).
58 This is the port name or number of the SSH server on the remote host.
59 The default is C<22> which is the standard SSH port.
61 =item Remote directory
63 Enter the directory on the remote host where disk image(s) and
64 configuration file(s) must reside.
66 Note that if the remote host is running SELinux then you may not be
67 able to start a Xen guest unless its disk image(s) are located in the
68 default directory, C</var/lib/xen/images>.
72 Enter the remote SSH username to use to log in to the remote host.
74 If you use the default username of C<root> then you should ensure that
75 remote root logins are enabled on the remote host
76 (ie. C<PermitRootLogin yes> in C</etc/ssh/sshd_config>).
78 =item Network configuration
80 Choose the way that the live CD configures network access. The
85 =item Automatic configuration
87 In this mode, the live CD attempts to reuse the network configuration
88 from the physical machine's root filesystem. You should probably try
89 this method even though occasionally it does not work.
91 =item Ask for fixed IP address and gateway
93 In this mode the live CD will ask you for a fixed IP address and
94 gateway address, and will configure your chosen interface with these.
96 =item Configure from the shell
98 In this mode you will be dropped into a command shell and you will
99 need to issue the correct sequence of C</sbin/ifconfig> commands in
100 order to configure the network interface.
102 A typical sequence of commands which should bring up the network
105 /sbin/ifconfig eth0 AA.BB.CC.DD
106 /sbin/route add default gw GG.HH.II.JJ eth0
108 where C<AA.BB.CC.DD> is the IP address and C<GG.HH.II.JJ> is the
111 =item QEMU user network
113 This option configures the network for use inside a QEMU user network
114 (L<http://fabrice.bellard.free.fr/qemu/qemu-doc.html#SEC30>). It
115 should only be used by developers.
121 This question lists out all local block devices (hard disk drives and
122 similar) and asks you to choose which will be sent to the remote host.
123 You must send at least one block device.
127 This question lists out possible root filesystems and asks you to
128 choose the right one. Choose the filesystem which would normally be
129 mounted as C</> on the system.
131 Virt-p2v performs some autodetection and is in most cases able to work
132 out which filesystems are possible root filesystems. It displays what
133 it thinks is on each filesystem, but leaves it up to the user to make
136 The root filesystem is critical because it contains C</etc/fstab>.
137 This is used during P2V both to determine how other filesystems are
138 normally mounted on the machine, and because this file and others
139 under C</etc> may need to be modified during P2V conversion.
141 If the machine has more than one root filesystem (typically because
142 the machine is dual-booted with another operating system), then you
143 must choose only one of them to perform the P2V conversion on.
147 This question asks you to choose the hypervisor / virtualization
148 system in use on the remote host.
150 If you select I<Xen>, I<QEMU> or I<KVM> then virt-p2v will produce a
151 configuration file which is customized for the selected system. If
152 you select I<Other> then virt-p2v will produce a generic configuration
153 file which will probably require hand-modification to work.
155 See also L<http://libvirt.org/format.html>.
157 =item Machine architecture
159 This question asks you to choose the machine architecture. Virt-p2v
160 can normally detect this, so you should leave it as I<Auto-detect>.
164 This question asks you to choose the amount of memory (RAM) in
165 megabytes assigned to the virtual machine.
167 If the entry is left blank, then virt-p2v will try to autodetect how
168 much RAM is present in the physical machine and use that, and this is
169 probably a good choice for most simple migrations.
173 This question asks you to choose the number of virtual CPUs assigned
174 to the virtual machine. Choosing C<1> causes the virtual machine to
175 be uniprocessor, and choosing some number greater than 1 causes the
176 virtual machine to be SMP.
178 If the entry is left blank, then virt-p2v will try to autodetect how
179 many CPU cores are present in the physical machine and use that, and
180 this is probably a good choice for most simple migrations.
184 Here you should enter a MAC address for the virtual machine's emulated
185 network card. MAC addresses are written as C<aa:bb:cc:dd:ee:ff> where
186 C<aa>, C<bb> etc are hexadecimal octets.
188 Leaving it blank will cause virt-p2v to choose a random MAC address
189 within the C<00:16:3e:..> space reserved for Xen guests. These MAC
190 addresses are not tested for uniqueness so there is a very small
191 chance that they could coincide, which would leave a guest unable to
192 access the virtual network.
196 Choose whether to enable or disable compression on disk images as they
197 are copied across the network.
199 If enabled, the C<-C> option is passed to L<ssh(1)>. On fast networks
200 this can sometimes be slower.
202 NB: The disk image is still stored uncompressed on the remote host
203 however this option is set.
205 =item Verify and proceed
207 In this step you are asked to verify the settings above. If any are
208 incorrect, use the I<Back> button to navigate back to the setting. If
209 all settings are correct, use the I<OK> button to begin the P2V
212 =item Network autoconfiguration
214 If you selected network autoconfiguration above then virt-p2v tries to
215 autoconfigure the network and ping the remote host. It then asks
216 I<Did automatic network configuration work?>
218 You should answer C<y> here if it worked.
220 Answering C<n> will drop you into a command shell.
222 You can also switch to another virtual console if you need to perform
223 additional tests. See section B<GETTING A SHELL> below.
227 Unless you have set up an SSH key, or the SSH server on the remote
228 host allows passwordless logins, then for each file that has to be
229 transferred to the remote host you will need to confirm the identity
230 of the remote host and/or enter a password.
232 To understand more about this, please see the L<ssh(1)> manual page.
236 =head2 BOOTING P2V GUEST ON VIRTUALIZATION HOST
238 Once the P2V conversion has been completed, and assuming it was
239 successful, you will find a configuration file and one or more disk
240 images on the remote host.
242 The files will be located in the directory selected, usually
243 C</var/lib/xen/images>. The names of the files are made up of:
245 C<p2v-I<hostname>-I<YYYYMMDDHHMM>.conf> or
246 C<p2v-I<hostname>-I<YYYYMMDDHHMM>-hdI<X>.img>
248 To simply start up the guest, use the following commands as root:
250 virsh define p2v-foo-2008MMDDHHMM.conf
255 virsh -c qemu:///system define p2v-foo-2008MMDDHHMM.conf
256 virsh -c qemu:///system start foo
258 For other hypervisors you will need to edit the configuration file and
259 read L<http://libvirt.org/uri.html>.
261 =head1 GETTING A SHELL
263 During all stages of P2V questions and conversion you can get a root
264 shell on the physical machine. Use I<ALT> I<F2> keys to switch to the
265 second virtual console, then log in as I<root> with no password.
269 Virt-p2v writes a detailed log file to C</tmp/virt-p2v.log>. (Note
270 that this C</tmp> directory is a ramdisk on the live CD, not the same
271 as the C</tmp> directory of the physical machine, and more importantly
272 it disappears when the machine is rebooted).
274 If you are reporting a bug, please always supply this file.
276 =head1 SERVER REQUIREMENTS
278 The virtualization host (remote host) must be running an SSH daemon
279 (C<sshd>), accessible from the physical machine which is being
282 Previous versions of virt-p2v could use a special virt-p2v server.
283 However this capability has been removed since there was practically
286 =head1 BUILDING A CUSTOM LIVE CD
288 To build a custom live CD you must download the source for virt-p2v
289 from L<http://et.redhat.com/~rjones/virt-p2v/> or from the Mercurial
290 source repository (see website for details).
292 Please read the C<README> file to find the dependencies which are all
293 in Fedora > 8 or EPEL > 5.
295 The steps to creating a custom live CD are:
299 =item 1. Edit C<virt-p2v> and adjust defaults
301 Find the section "TO MAKE A CUSTOM virt-p2v SCRIPT ..." which is near
302 to the top of this file. Edit the defaults in this section as
305 =item 2. C<virt-p2v --test> to verify your changes
307 This command should not print anything at all. If it prints any
308 message, then you will need to fix the error by going back to the
311 =item 3. C<make build> or C<make update> to build a custom live CD
313 C<make build> will create a complete ISO from scratch. C<make update>
314 can be used to build a "quick" developer ISO by updating an existing
315 ISO image. See section B<ISO ATTACHMENTS> below for more details.
317 =item 4. Burn the ISO to a CD-R and test
321 =head2 EDITING DEFAULTS IN THE C<virt-p2v> SCRIPT
323 For each default, setting it to C<None> will ask the user. All of the
324 defaults are set to C<None> in the standard, uncustomized virt-p2v
325 script, and so the standard script asks all the questions.
327 You may edit C<virt-p2v> and change the defaults, in which case the
328 user will not be questioned. In this way you can make the script
329 partially or fully automated.
331 I<Note about OCaml code:> C<None> and C<Some foo> are similar to the
332 concept of a NULL pointer versus non-NULL pointer in other languages.
333 This a variant type defined as:
335 type E<945> option = None | Some of E<945>
341 If this is C<true> then we wait for a keypress after boot and at a
342 couple of other stages. If set to C<false> then we try not to wait
343 for any keypresses (so more automated live CDs are possible).
347 Set this to C<Some "hostname"> or C<Some "IP-address"> to
348 provide the name of the remote host.
352 Set this to C<Some port> (eg. C<Some 22>) to provide the port number
353 of the remote host's SSH daemon.
355 =item C<remote_directory>
357 Set this to C<Some "path"> (eg. C<Some "/var/lib/xen/images">) to
358 provide the directory where we update P2V converted images and
361 =item C<remote_username>
363 Set this to C<Some "username"> (eg. C<Some "root">) to provide the SSH
364 username to use on the remote system.
366 =item C<devices_to_send>
368 Set this to a list of block devices to send to the remote system.
369 For example, C<Some ["sda"; "sdb"]>.
371 =item C<root_filesystem>
373 Set this to the name of the root filesystem.
375 For a disk partition (eg. C</dev/sda1>), use:
377 Some (Part ("sda", "1"))
379 For a logical volume (eg. C</dev/VolGroup00/LogVol00>), use:
381 Some (LV ("VolGroup00", "LogVol00"))
385 Set this to the choice for network setup. Use one of:
391 for auto-configuration
395 to specify the interface, address, netmask and gateway statically
401 =item C<Some QEMUUserNet>
403 to use a QEMU user network (developers only)
407 =item C<static_network_config>
409 This setting only applies if C<network> is set to C<Some Static>,
410 in which case you should set this to the static network settings,
411 a tuple of (interface, address, netmask, gateway, nameserver):
413 Some ("eth0", "192.168.2.5", "255.255.255.0", "192.168.2.1", "192.168.2.1")
417 Set this to the choice of hypervisor or virtualization system. The
418 choices are: C<Some Xen>, C<Some QEMU> or C<Some KVM>.
420 =item C<architecture>
422 Set this to the architecture. The choices are:
423 C<Some I386> (i386 and up, 32 bit),
424 C<Some X86_64> (AMD and Intel x86-64, 64 bit),
425 C<Some IA64> (Intel IA64),
426 C<Some PPC> (PowerPC, 32 bit),
427 C<Some PPC64> (PowerPC, 64 bit),
428 C<Some SPARC> (Sun SPARC, 32 bit),
429 C<Some SPARC64> (Sun SPARC, 64 bit),
430 C<OtherArch "foo"> (a hypothetical architecture called I<foo>), or
431 C<UnknownArch> to auto-detect the architecture.
435 Set this to the size of memory in megabytes, eg. C<Some 256>. If you
436 set this to C<Some 0> then virt-p2v will try to autodetect the amount
437 of RAM installed on the physical machine.
441 Set this to the number of virtual CPUs, eg. C<Some 1>. If you set
442 this to C<Some 0> then virt-p2v will try to autodetect the number of
443 CPU cores on the physical machine.
447 Set this to the MAC address for the virtual network card, eg. C<Some
448 "aa:bb:cc:dd:ee:ff">. If you set this to C<Some ""> then virt-p2v
449 will choose a random MAC address within the C<00:16:3e:..> space
450 reserved for Xen guests. These MAC addresses are not tested for
451 uniqueness so there is a very small chance that they could coincide,
452 which would leave a guest unable to access the virtual network.
456 Set this to C<Some false> to disable compression, or C<Some true> to
457 enable compression, or C<None> to ask the user.
461 =head2 ISO ATTACHMENTS
463 Rebuilding a custom ISO is time-consuming. You can make a "quick"
464 developer ISO by updating an existing ISO image with a new custom
465 C<virt-p2v> script. This is useful for testing purposes.
467 From the source directory, assuming that you have downloaded or
468 built an existing C<virt-p2v-*.iso>, you can just do:
472 or the equivalent manual command:
474 ./iso-attach virt-p2v-VERSION.iso virt-p2v
476 Note that ISO attachments only work with real (and emulated) CD-Rs,
477 not with other methods of booting such as USB keys and PXE.
481 If you wish to boot over the network using PXE, use the
482 C<livecd-iso-to-pxeboot> script (part of C<livecd-tools>).
484 livecd-iso-to-pxeboot virt-p2v-$VERSION.iso
486 then copy the generated subdirectory C<tftpboot/> to the
487 right place for your PXE configuration.
489 Pre-built PXE boot images are also available on the website.
491 General configuration of DHCP, TFTP and PXE for network booting are
492 outside the scope of this document.
494 =head1 BOOTING FROM A USB KEY
496 If you wish to boot from a USB keydrive, use the C<livecd-iso-to-disk>
497 script (part of C<livecd-tools>):
499 livecd-iso-to-disk virt-p2v-$VERSION.iso /dev/sdX1
501 (Replace /dev/sdX1 with the actual USB device).
503 In my experience I also had to set up a suitable MBR:
505 cat /usr/lib/syslinux/mbr.bin > /dev/sdX
507 =head1 TESTING AN ISO UNDER QEMU OR KVM
509 If you have a virtual guest running under QEMU or KVM then
510 you can test the P2V conversion process on the guest.
512 (Technically this is a V2V -- virtual to virtual -- conversion).
514 From the source directory do:
516 make boot HDA=qemuimage.img
518 where C<qemuimage.img> is the name of the QEMU/KVM image.
520 You can also supply an C<HDB> parameter to specify a second disk.
524 Please direct questions to the et-mgmt-tools mailing list
525 L<http://www.redhat.com/mailman/listinfo/et-mgmt-tools>
526 <et-mgmt-tools @ redhat . com>
531 L<http://www.libvirt.org/ocaml/>,
532 L<http://www.libvirt.org/>,
533 L<http://et.redhat.com/~rjones/>,
534 L<http://caml.inria.fr/>
538 Richard W.M. Jones <rjones @ redhat . com>
542 (C) Copyright 2007-2008 Red Hat Inc., Richard W.M. Jones
545 This program is free software; you can redistribute it and/or modify
546 it under the terms of the GNU General Public License as published by
547 the Free Software Foundation; either version 2 of the License, or
548 (at your option) any later version.
550 This program is distributed in the hope that it will be useful,
551 but WITHOUT ANY WARRANTY; without even the implied warranty of
552 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
553 GNU General Public License for more details.
555 You should have received a copy of the GNU General Public License
556 along with this program; if not, write to the Free Software
557 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
559 =head1 REPORTING BUGS
561 Bugs can be viewed on the Red Hat Bugzilla page:
562 L<https://bugzilla.redhat.com/>.
564 If you find a bug in virt-p2v, please follow these steps to report it:
568 =item 1. Check for existing bug reports
570 Go to L<https://bugzilla.redhat.com/> and search for similar bugs.
571 Someone may already have reported the same bug, and they may even
574 =item 2. Capture debug and error messages
576 At the point where you get the error or unexpected behaviour,
577 go to the second virtual console (I<ALT> I<F2>) and look at
578 the logfile C</tmp/virt-p2v.log>. Please make sure that
579 this file is attached to your bug report.
581 =item 3. Get version of virt-p2v
583 The version is in the name of the ISO. If you have built a custom
584 virt-p2v ISO, please describe any changes that you have made.
586 =item 4. Submit a bug report.
588 Go to L<https://bugzilla.redhat.com/> and enter a new bug.
589 Please describe the problem in as much detail as possible.
591 Remember to include the version number (step 3) and to
592 attach the log file (step 2).
594 =item 5. Assign the bug to rjones @ redhat.com
596 Assign or reassign the bug to B<rjones @ redhat.com> (without the
597 spaces). You can also send me an email with the bug number if you
598 want a faster response.