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. It isn't
31 designed to run outside this environment and could do Bad Things to
32 your machine if you try it. The script contains some checks to try to
33 stop you from doing this.
35 Virt-p2v does not modify the physical machine, its disks,
40 After booting the live CD-R, you are presented with a series of
41 questions. This section explains each question.
47 Enter the name or IP address of the virtualization host. This is the
48 host running Xen (or any other virtualization system supported by
49 libvirt, eg. QEMU). This host should be accessible on the network and
50 running an SSH daemon (C<sshd>).
54 This is the port name or number of the SSH server on the remote host.
55 The default is C<22> which is the standard SSH port.
57 =item Remote directory
59 Enter the directory on the remote host where disk image(s) and
60 configuration file(s) must reside.
62 Note that if the remote host is running SELinux then you may not be
63 able to start a Xen guest unless its disk image(s) are located in the
64 default directory, C</var/lib/xen/images>.
68 Enter the remote SSH username to use to log in to the remote host.
70 If you use the default username of C<root> then you should ensure that
71 remote root logins are enabled on the remote host
72 (ie. C<PermitRootLogin yes> in C</etc/ssh/sshd_config>).
74 =item Network configuration
76 Choose the way that the live CD configures network access. The
81 =item Automatic configuration
83 In this mode, the live CD attempts to reuse the network configuration
84 from the physical machine's root filesystem. You should probably try
85 this method even though occasionally it does not work.
87 =item Ask for fixed IP address and gateway
89 In this mode the live CD will ask you for a fixed IP address and
90 gateway address, and will configure your chosen interface with these.
92 =item Configure from the shell
94 In this mode you will be dropped into a command shell and you will
95 need to issue the correct sequence of C</sbin/ifconfig> commands in
96 order to configure the network interface.
98 A typical sequence of commands which should bring up the network
101 /sbin/ifconfig eth0 AA.BB.CC.DD
102 /sbin/route add default gw GG.HH.II.JJ eth0
104 where C<AA.BB.CC.DD> is the IP address and C<GG.HH.II.JJ> is the
107 =item QEMU user network
109 This option configures the network for use inside a QEMU user network
110 (L<http://fabrice.bellard.free.fr/qemu/qemu-doc.html#SEC30>). It
111 should only be used by developers.
117 This question lists out all local block devices (hard disk drives and
118 similar) and asks you to choose which will be sent to the remote host.
119 You must send at least one block device.
123 This question lists out possible root filesystems and asks you to
124 choose the right one. Choose the filesystem which would normally be
125 mounted as C</> on the system.
127 Virt-p2v performs some autodetection and is in most cases able to work
128 out which filesystems are possible root filesystems. It displays what
129 it thinks is on each filesystem, but leaves it up to the user to make
132 The root filesystem is critical because it contains C</etc/fstab>.
133 This is used during P2V both to determine how other filesystems are
134 normally mounted on the machine, and because this file and others
135 under C</etc> may need to be modified during P2V conversion.
137 If the machine has more than one root filesystem (typically because
138 the machine is dual-booted with another operating system), then you
139 must choose only one of them to perform the P2V conversion on.
143 This question asks you to choose the hypervisor / virtualization
144 system in use on the remote host.
146 If you select I<Xen>, I<QEMU> or I<KVM> then virt-p2v will produce a
147 configuration file which is customized for the selected system. If
148 you select I<Other> then virt-p2v will produce a generic configuration
149 file which will probably require hand-modification to work.
151 See also L<http://libvirt.org/format.html>.
153 =item Machine architecture
155 This question asks you to choose the machine architecture. Virt-p2v
156 can normally detect this, so you should leave it as I<Auto-detect>.
160 This question asks you to choose the amount of memory (RAM) in
161 megabytes assigned to the virtual machine.
163 If the entry is left blank, then virt-p2v will try to autodetect how
164 much RAM is present in the physical machine and use that, and this is
165 probably a good choice for most simple migrations.
169 This question asks you to choose the number of virtual CPUs assigned
170 to the virtual machine. Choosing C<1> causes the virtual machine to
171 be uniprocessor, and choosing some number greater than 1 causes the
172 virtual machine to be SMP.
174 If the entry is left blank, then virt-p2v will try to autodetect how
175 many CPU cores are present in the physical machine and use that, and
176 this is probably a good choice for most simple migrations.
180 Here you should enter a MAC address for the virtual machine's emulated
181 network card. MAC addresses are written as C<aa:bb:cc:dd:ee:ff> where
182 C<aa>, C<bb> etc are hexadecimal octets.
184 Leaving it blank will cause virt-p2v to choose a random MAC address
185 within the C<00:16:3e:..> space reserved for Xen guests. These MAC
186 addresses are not tested for uniqueness so there is a very small
187 chance that they could coincide, which would leave a guest unable to
188 access the virtual network.
190 =item Verify and proceed
192 In this step you are asked to verify the settings above. If any are
193 incorrect, use the I<Back> button to navigate back to the setting. If
194 all settings are correct, use the I<OK> button to begin the P2V
197 =item Network autoconfiguration
199 If you selected network autoconfiguration above then virt-p2v tries to
200 autoconfigure the network and ping the remote host. It then asks
201 I<Did automatic network configuration work?>
203 You should answer C<y> here if it worked.
205 Answering C<n> will drop you into a command shell.
207 You can also switch to another virtual console if you need to perform
208 additional tests. See section B<GETTING A SHELL> below.
212 Unless you have set up an SSH key, or the SSH server on the remote
213 host allows passwordless logins, then for each file that has to be
214 transferred to the remote host you will need to confirm the identity
215 of the remote host and/or enter a password.
217 To understand more about this, please see the L<ssh(1)> manual page.
221 =head2 BOOTING P2V GUEST ON VIRTUALIZATION HOST
223 Once the P2V conversion has been completed, and assuming it was
224 successful, you will find a configuration file and one or more disk
225 images on the remote host.
227 The files will be located in the directory selected, usually
228 C</var/lib/xen/images>. The names of the files are made up of:
230 C<p2v-I<hostname>-I<YYYYMMDDHHMM>.conf> or
231 C<p2v-I<hostname>-I<YYYYMMDDHHMM>-hdI<X>.img>
233 To simply start up the guest, use the following commands as root:
235 virsh define p2v-foo-2008MMDDHHMM.conf
240 virsh -c qemu:///system define p2v-foo-2008MMDDHHMM.conf
241 virsh -c qemu:///system start foo
243 For other hypervisors you will need to edit the configuration file and
244 read L<http://libvirt.org/uri.html>.
246 =head1 GETTING A SHELL
248 During all stages of P2V questions and conversion you can get a root
249 shell on the physical machine. Use I<ALT> I<F2> keys to switch to the
250 second virtual console, then log in as I<root> with no password.
254 Virt-p2v writes a detailed log file to C</tmp/virt-p2v.log>. (Note
255 that this C</tmp> directory is a ramdisk on the live CD, not the same
256 as the C</tmp> directory of the physical machine, and more importantly
257 it disappears when the machine is rebooted).
259 If you are reporting a bug, please always supply this file.
261 =head1 SERVER REQUIREMENTS
263 The virtualization host (remote host) must be running an SSH daemon
264 (C<sshd>), accessible from the physical machine which is being
267 Previous versions of virt-p2v could use a special virt-p2v server.
268 However this capability has been removed since there was practically
271 =head1 BUILDING A CUSTOM LIVE CD
273 To build a custom live CD you must download the source for virt-p2v
274 from L<http://et.redhat.com/~rjones/virt-p2v/> or from the Mercurial
275 source repository (see website for details).
277 Please read the C<README> file to find the dependencies which are all
278 in Fedora > 8 or EPEL > 5.
280 The steps to creating a custom live CD are:
284 =item 1. Edit C<virt-p2v> and adjust defaults
286 Find the section "TO MAKE A CUSTOM virt-p2v SCRIPT ..." which is near
287 to the top of this file. Edit the defaults in this section as
290 =item 2. C<virt-p2v --test> to verify your changes
292 This command should not print anything at all. If it prints any
293 message, then you will need to fix the error by going back to the
296 =item 3. C<make build> or C<make update> to build a custom live CD
298 C<make build> will create a complete ISO from scratch. C<make update>
299 can be used to build a "quick" developer ISO by updating an existing
300 ISO image. See section B<ISO ATTACHMENTS> below for more details.
302 =item 4. Burn the ISO to a CD-R and test
306 =head2 EDITING DEFAULTS IN THE C<virt-p2v> SCRIPT
308 For each default, setting it to C<None> will ask the user. All of the
309 defaults are set to C<None> in the standard, uncustomized virt-p2v
310 script, and so the standard script asks all the questions.
312 You may edit C<virt-p2v> and change the defaults, in which case the
313 user will not be questioned. In this way you can make the script
314 partially or fully automated.
316 I<Note about OCaml code:> C<None> and C<Some foo> are similar to the
317 concept of a NULL pointer versus non-NULL pointer in other languages.
318 This a variant type defined as:
320 type E<945> option = None | Some of E<945>
326 If this is C<true> then we wait for a keypress after boot and at a
327 couple of other stages. If set to C<false> then we try not to wait
328 for any keypresses (so more automated live CDs are possible).
332 Set this to C<Some "hostname"> or C<Some "IP-address"> to
333 provide the name of the remote host.
337 Set this to C<Some port> (eg. C<Some 22>) to provide the port number
338 of the remote host's SSH daemon.
340 =item C<remote_directory>
342 Set this to C<Some "path"> (eg. C<Some "/var/lib/xen/images">) to
343 provide the directory where we update P2V converted images and
346 =item C<remote_username>
348 Set this to C<Some "username"> (eg. C<Some "root">) to provide the SSH
349 username to use on the remote system.
351 =item C<devices_to_send>
353 Set this to a list of block devices to send to the remote system.
354 For example, C<Some ["sda"; "sdb"]>.
356 =item C<root_filesystem>
358 Set this to the name of the root filesystem.
360 For a disk partition (eg. C</dev/sda1>), use:
362 Some (Part ("sda", "1"))
364 For a logical volume (eg. C</dev/VolGroup00/LogVol00>), use:
366 Some (LV ("VolGroup00", "LogVol00"))
370 Set this to the choice for network setup. Use one of:
376 for auto-configuration
380 to specify the interface, address, netmask and gateway statically
386 =item C<Some QEMUUserNet>
388 to use a QEMU user network (developers only)
392 =item C<static_network_config>
394 This setting only applies if C<network> is set to C<Some Static>,
395 in which case you should set this to the static network settings,
396 a tuple of (interface, address, netmask, gateway, nameserver):
398 Some ("eth0", "192.168.2.5", "255.255.255.0", "192.168.2.1", "192.168.2.1")
402 Set this to the choice of hypervisor or virtualization system. The
403 choices are: C<Some Xen>, C<Some QEMU> or C<Some KVM>.
405 =item C<architecture>
407 Set this to the architecture. The choices are:
408 C<Some I386> (i386 and up, 32 bit),
409 C<Some X86_64> (AMD and Intel x86-64, 64 bit),
410 C<Some IA64> (Intel IA64),
411 C<Some PPC> (PowerPC, 32 bit),
412 C<Some PPC64> (PowerPC, 64 bit),
413 C<Some SPARC> (Sun SPARC, 32 bit),
414 C<Some SPARC64> (Sun SPARC, 64 bit),
415 C<OtherArch "foo"> (a hypothetical architecture called I<foo>), or
416 C<UnknownArch> to auto-detect the architecture.
420 Set this to the size of memory in megabytes, eg. C<Some 256>. If you
421 set this to C<Some 0> then virt-p2v will try to autodetect the amount
422 of RAM installed on the physical machine.
426 Set this to the number of virtual CPUs, eg. C<Some 1>. If you set
427 this to C<Some 0> then virt-p2v will try to autodetect the number of
428 CPU cores on the physical machine.
432 Set this to the MAC address for the virtual network card, eg. C<Some
433 "aa:bb:cc:dd:ee:ff">. If you set this to C<Some ""> then virt-p2v
434 will choose a random MAC address within the C<00:16:3e:..> space
435 reserved for Xen guests. These MAC addresses are not tested for
436 uniqueness so there is a very small chance that they could coincide,
437 which would leave a guest unable to access the virtual network.
441 =head2 ISO ATTACHMENTS
443 Rebuilding a custom ISO is time-consuming. You can make a "quick"
444 developer ISO by updating an existing ISO image with a new custom
445 C<virt-p2v> script. This is useful for testing purposes.
447 From the source directory, assuming that you have downloaded or
448 built an existing C<virt-p2v-*.iso>, you can just do:
452 or the equivalent manual command:
454 ./iso-attach virt-p2v-VERSION.iso virt-p2v
456 =head1 BOOTING FROM A USB KEY INSTEAD OF A CD
458 If you wish to boot from a USB keydrive, use the livecd-iso-to-disk
461 livecd-iso-to-disk virt-p2v-$VERSION.iso /dev/sdX1
463 (Replace /dev/sdX1 with the actual USB device).
465 In my experience I also had to set up a suitable MBR:
467 cat /usr/lib/syslinux/mbr.bin > /dev/sdX
469 =head1 TESTING AN ISO UNDER QEMU OR KVM
471 If you have a virtual guest running under QEMU or KVM then
472 you can test the P2V conversion process on the guest.
474 (Technically this is a V2V -- virtual to virtual -- conversion).
476 From the source directory do:
478 make boot HDA=qemuimage.img
480 where C<qemuimage.img> is the name of the QEMU/KVM image.
482 You can also supply an C<HDB> parameter to specify a second disk.
486 Please direct questions to the et-mgmt-tools mailing list
487 L<http://www.redhat.com/mailman/listinfo/et-mgmt-tools>
488 <et-mgmt-tools @ redhat . com>
493 L<http://www.libvirt.org/ocaml/>,
494 L<http://www.libvirt.org/>,
495 L<http://et.redhat.com/~rjones/>,
496 L<http://caml.inria.fr/>
500 Richard W.M. Jones <rjones @ redhat . com>
504 (C) Copyright 2007-2008 Red Hat Inc., Richard W.M. Jones
507 This program is free software; you can redistribute it and/or modify
508 it under the terms of the GNU General Public License as published by
509 the Free Software Foundation; either version 2 of the License, or
510 (at your option) any later version.
512 This program is distributed in the hope that it will be useful,
513 but WITHOUT ANY WARRANTY; without even the implied warranty of
514 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
515 GNU General Public License for more details.
517 You should have received a copy of the GNU General Public License
518 along with this program; if not, write to the Free Software
519 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
521 =head1 REPORTING BUGS
523 Bugs can be viewed on the Red Hat Bugzilla page:
524 L<https://bugzilla.redhat.com/>.
526 If you find a bug in virt-p2v, please follow these steps to report it:
530 =item 1. Check for existing bug reports
532 Go to L<https://bugzilla.redhat.com/> and search for similar bugs.
533 Someone may already have reported the same bug, and they may even
536 =item 2. Capture debug and error messages
538 At the point where you get the error or unexpected behaviour,
539 go to the second virtual console (I<ALT> I<F2>) and look at
540 the logfile C</tmp/virt-p2v.log>. Please make sure that
541 this file is attached to your bug report.
543 =item 3. Get version of virt-p2v
545 The version is in the name of the ISO. If you have built a custom
546 virt-p2v ISO, please describe any changes that you have made.
548 =item 4. Submit a bug report.
550 Go to L<https://bugzilla.redhat.com/> and enter a new bug.
551 Please describe the problem in as much detail as possible.
553 Remember to include the version number (step 3) and to
554 attach the log file (step 2).
556 =item 5. Assign the bug to rjones @ redhat.com
558 Assign or reassign the bug to B<rjones @ redhat.com> (without the
559 spaces). You can also send me an email with the bug number if you
560 want a faster response.