From 65b46ce56a110e798c9a21f99eb7969f5ca073e3 Mon Sep 17 00:00:00 2001 From: "Richard W.M. Jones" Date: Thu, 1 Jan 1970 00:00:00 +0000 Subject: [PATCH] Manual page with centralised documentation. --- .hgignore | 1 + MANIFEST | 4 + Makefile | 24 +++ README | 70 ++---- README.developers | 27 +-- virt-p2v | 47 +--- virt-p2v.1 | 617 ++++++++++++++++++++++++++++++++++++++++++++++++++++ virt-p2v.1.css | 159 ++++++++++++++ virt-p2v.1.html | 629 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ virt-p2v.1.txt | 439 +++++++++++++++++++++++++++++++++++++ virt-p2v.pod | 519 ++++++++++++++++++++++++++++++++++++++++++++ 11 files changed, 2418 insertions(+), 118 deletions(-) create mode 100644 virt-p2v.1 create mode 100644 virt-p2v.1.css create mode 100644 virt-p2v.1.html create mode 100644 virt-p2v.1.txt create mode 100644 virt-p2v.pod diff --git a/.hgignore b/.hgignore index 5d29e49..ac0b189 100644 --- a/.hgignore +++ b/.hgignore @@ -6,3 +6,4 @@ ^livecd\.ks$ ^livecd-test\.ks$ ^livecd-post\.sh$ +^pod2htm.* \ No newline at end of file diff --git a/MANIFEST b/MANIFEST index 8976fd6..1e3b8e8 100644 --- a/MANIFEST +++ b/MANIFEST @@ -11,4 +11,8 @@ MANIFEST README README.developers virt-p2v +virt-p2v.1 +virt-p2v.1.html +virt-p2v.1.txt +virt-p2v.pod virt-p2v-update-wrapper diff --git a/Makefile b/Makefile index 731783f..6d0a0c9 100644 --- a/Makefile +++ b/Makefile @@ -53,6 +53,7 @@ all: @echo " Boot built/named ISO (uses qemu)" @echo "make update Update an existing live CD ISO with new" @echo " virt-p2v script, without doing full rebuild" + @echo "make man Make man pages (needs POD)" # Build live CD. @@ -146,4 +147,27 @@ check-manifest: rm -f .orig-manifest .check-manifest; \ exit $$rv +# Manual page. + +MAN_SECTION := Virtualization Support + +man: virt-p2v.1 virt-p2v.1.txt virt-p2v.1.html + +virt-p2v.1: virt-p2v.pod + pod2man -c "$(MAN_SECTION)" --release "$(PACKAGE)-$(VERSION)" $< > $@ + +virt-p2v.1.txt: virt-p2v.pod + pod2text $< > $@ + +virt-p2v.1.html: virt-p2v.pod + pod2html -css virt-p2v.1.css $< > $@ + +# Website. + +WEBSITE_DIR := ../redhat/et-website/virt-p2v + +website: man dist + cp virt-p2v.1.html $(WEBSITE_DIR) + cp $(PACKAGE)-$(VERSION).tar.gz $(WEBSITE_DIR) + .PHONY: build boot checkroot \ No newline at end of file diff --git a/README b/README index 7886193..d03ce0a 100644 --- a/README +++ b/README @@ -3,12 +3,12 @@ $Id$ virt-p2v : P2V ("physical to virtual") migration tool ---------------------------------------------------------------------- -Written by: - Richard W.M. Jones +Written by Richard W.M. Jones -Copyright (C) 2007 Red Hat Inc. +Copyright (C) 2007-2008 Red Hat Inc. + + http://et.redhat.com/~rjones/virt-p2v/ - http://et.redhat.com/~rjones/virt-p2v/ Binaries ---------------------------------------------------------------------- @@ -16,67 +16,35 @@ Binaries Binaries are available from the website (live CD images which can be burned directly to a CD and booted on the p2v candidate machine). -http://et.redhat.com/~rjones/virt-p2v/ - -Building ----------------------------------------------------------------------- - -Requirements: - * livecd-creator (on Fedora the package is 'livecd-tools') - * qemu (only for testing) + http://et.redhat.com/~rjones/virt-p2v/download.html -(1) Edit Makefile - there is some general configuration at the - top which you may want to change. - -(2) 'make build' will build an ISO image called virt-p2v-$VERSION.iso - -(3) Burn the image on to a CD using standard tools. -Booting from USB device +Usage ---------------------------------------------------------------------- -If you wish to boot from a USB keydrive, use the livecd-iso-to-disk -tool: +Please read the manual page: - livecd-iso-to-disk virt-p2v-$VERSION.iso /dev/sdX1 + man virt-p2v +or make man; nroff -man virt-p2v.1 | less +or http://et.redhat.com/~rjones/virt-p2v/virt-p2v.1.html -(Replace /dev/sdX1 with the actual USB device). -In my experience I also had to set up a suitable MBR: - - cat /usr/lib/syslinux/mbr.bin > /dev/sdX - -Running +Building ---------------------------------------------------------------------- -Boot the candidate machine from the live CD or USB keydrive. - -You will need to have network access to another machine where it will -save the virtual disk images. That machine must have ssh access (sshd -service running). Note that the target machine is usually the Xen -host, but it doesn't need to be: you could copy the images to a -staging machine, and later copy them over to the Xen host. - -Note that the live CD doesn't modify any data on the candidate -machine. +Requirements: -Answer the questions. There is a tutorial and explanation of some of -the questions on the website which you may wish to follow: -http://et.redhat.com/~rjones/virt-p2v/ + * livecd-creator (on Fedora the package is 'livecd-tools') + * ocaml, ocaml-extlib, ocaml-pcre, ocaml-xml-light (all in Fedora) + * qemu and/or KVM (only for testing) -While the live CD is booted a shell is available on other virtual -consoles. Go to a virtual console using [ALT] [F2] and log in as root -with no password. +(1) Edit Makefile - there is some general configuration at the + top which you may want to change. -If it works, the result will be a configuration file and disk images -for each block device (hard disk) from the candidate machine, which -should boot directly or with the minimum of changes. +(2) 'make build' will build an ISO image called virt-p2v-$VERSION.iso -Booting P2V candidate under Xen ----------------------------------------------------------------------- +(3) Burn the image on to a CD using standard tools. - # virsh define p2v-foo-2008MMDDHHMM.conf - # virsh start foo Testing ---------------------------------------------------------------------- diff --git a/README.developers b/README.developers index f7b205e..232805e 100644 --- a/README.developers +++ b/README.developers @@ -1,5 +1,3 @@ -$Id$ - Background reading ---------------------------------------------------------------------- @@ -23,11 +21,6 @@ livecd-post.sh.in before the live CD is turned into an ISO. The shell script creates any extra files we need on the live CD. -p2v.init - - This is installed on the live CD as /etc/init.d/p2v, and it causes the - live CD to boot into the P2V configuration tool (see next). - virt-p2v This is the virt-p2v P2V configuration tool itself. It is @@ -39,6 +32,10 @@ inittab Replacement /etc/inittab. +iso-attach + + Attach newer virt-p2v scripts to pre-built ISOs (used by 'make update'). + General implementation plan ---------------------------------------------------------------------- @@ -65,23 +62,7 @@ this: dd if=/dev/disk | ssh -C xenhost 'cat > /var/lib/xen/images/disk.img' -If the user doesn't have sshd installed on the Xen host, then they can -also opt for a pure TCP transport: - - dd if=/dev/disk | nc xenhost port - - and on the remote host they do: - nc -kl port > /var/lib/xen/images/disks - For (c) we can use device-mapper snapshots to mount a ramdisk above the disks themselves. This allows us to make non-destructive changes to files, and still see the "modified" block device (d). A hairy script looks for candidate files to modify. - -Non-generic virt-p2v ----------------------------------------------------------------------- - -The above describes the generic virt-p2v, which asks users questions -after boot. It is also possible to build your own live CD, based on -virt-p2v, which has various settings compiled in so it runs -automatically. diff --git a/virt-p2v b/virt-p2v index edf637e..98febf1 100755 --- a/virt-p2v +++ b/virt-p2v @@ -70,62 +70,21 @@ let defaults = { *) greeting = true; - (* Remote host and port. Set to 'Some "host"' and 'Some "port"', - * else ask the user. + (* These are now documented in the man page virt-p2v(1). + * 'None' means ask the user. + * After changing them, run './virt-p2v --test' to check syntax. *) remote_host = None; remote_port = None; - - (* Remote directory. Set to 'Some "path"' to set up a - * directory path, else ask the user. - *) remote_directory = None; - - (* Remote username for ssh. Set to 'Some "username"', or None to - * ask the user. - *) remote_username = None; - - (* List of devices to send. Set to 'Some ["sda"; "sdb"]' for - * example to select /dev/sda and /dev/sdb. - *) devices_to_send = None; - - (* The root filesystem containing /etc/fstab. Set to - * 'Some (Part ("sda", "3"))' or 'Some (LV ("VolGroup00", "LogVol00"))' - * for example, else ask user. - *) root_filesystem = None; - - (* Network configuration: Set to 'Some Auto' (try to set it up - * automatically, or 'Some Shell' (give the user a shell). - *) network = None; - - (* Hypervisor: Set to 'Some Xen', 'Some QEMU' or 'Some KVM'. *) hypervisor = None; - - (* Architecture: Set to 'Some X86_64' (or another architecture). - * If set to 'Some UnknownArch' then we try to autodetect the - * right architecture. - *) architecture = None; - - (* Memory: Set to 'Some nn' with nn in megabytes. If set to 'Some 0' - * then we use same amount of RAM as installed in the physical machine. - *) memory = None; - - (* Virtual CPUs: Set to 'Some nn' where nn is the number of virtual CPUs. - * If set to 'Some 0' then we use the same as physical CPUs in the - * physical machine. - *) vcpus = None; - - (* MAC address: Set to 'Some "aa:bb:cc:dd:ee:ff"' where the string is - * the MAC address of the emulated network card. Set to 'Some ""' to - * choose a random MAC address. - *) mac_address = None; } (* END OF CUSTOM virt-p2v SCRIPT SECTION. *) diff --git a/virt-p2v.1 b/virt-p2v.1 new file mode 100644 index 0000000..59e9f10 --- /dev/null +++ b/virt-p2v.1 @@ -0,0 +1,617 @@ +.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sh \" Subsection heading +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. | will give a +.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to +.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' +.\" expand to `' in nroff, nothing in troff, for use with C<>. +.tr \(*W-|\(bv\*(Tr +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.\" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.hy 0 +.if n .na +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "VIRT-P2V 1" +.TH VIRT-P2V 1 "2008-02-04" "virt-p2v-0.9.1" "Virtualization Support" +.SH "NAME" +virt\-p2v \- P2V (physical to virtual machine) migration tool +.SH "SUMMARY" +.IX Header "SUMMARY" +virt\-p2v +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +virt\-p2v is a live \s-1CD\s0 for migrating physical machines to virtual +machine guests. +.PP +In the simplest mode of operation, you take a pre-built live \s-1CD\s0 \s-1ISO\s0 +from the main website () and +burn it to a \s-1CD\-R\s0. Then insert the CD-R into the physical machine +which must be migrated, reboot, and follow the on-screen instructions. +See \fB\s-1STANDARD\s0 \s-1USAGE\s0\fR section below. +.PP +You may also build a customized live \s-1CD\s0. Typically this will contain +things like server details specific to your organization, so that the +live \s-1CD\s0 can run mostly or completely automatically. See \fB\s-1BUILDING\s0 A +\&\s-1CUSTOM\s0 \s-1LIVE\s0 \s-1CD\s0\fR section below. +.PP +In both cases, files and disk images are transferred from the physical +machine over the network to the virtualization host machine over ssh. +Therefore \f(CW\*(C`sshd\*(C'\fR must be running on the virtualization host, and must +be accessible to that host. See \fB\s-1SERVER\s0 \s-1REQUIREMENTS\s0\fR section below. +.PP +The \f(CW\*(C`virt\-p2v\*(C'\fR script must only be run from the live \s-1CD\s0. It isn't +designed to run outside this environment and could do Bad Things to +your machine if you try it. The script contains some checks to try to +stop you from doing this. +.PP +Virt\-p2v does not modify the physical machine, its disks, +configuration etc. +.SH "STANDARD USAGE" +.IX Header "STANDARD USAGE" +After booting the live \s-1CD\-R\s0, you are presented with a series of +questions. This section explains each question. +.IP "Remote host" 4 +.IX Item "Remote host" +Enter the name or \s-1IP\s0 address of the virtualization host. This is the +host running Xen (or any other virtualization system supported by +libvirt, eg. \s-1QEMU\s0). This host should be accessible on the network and +running an \s-1SSH\s0 daemon (\f(CW\*(C`sshd\*(C'\fR). +.IP "Remote port" 4 +.IX Item "Remote port" +This is the port name or number of the \s-1SSH\s0 server on the remote host. +The default is \f(CW22\fR which is the standard \s-1SSH\s0 port. +.IP "Remote directory" 4 +.IX Item "Remote directory" +Enter the directory on the remote host where disk image(s) and +configuration file(s) must reside. +.Sp +Note that if the remote host is running SELinux then you may not be +able to start a Xen guest unless its disk image(s) are located in the +default directory, \f(CW\*(C`/var/lib/xen/images\*(C'\fR. +.IP "Remote username" 4 +.IX Item "Remote username" +Enter the remote \s-1SSH\s0 username to use to log in to the remote host. +.Sp +If you use the default username of \f(CW\*(C`root\*(C'\fR then you should ensure that +remote root logins are enabled on the remote host +(ie. \f(CW\*(C`PermitRootLogin yes\*(C'\fR in \f(CW\*(C`/etc/ssh/sshd_config\*(C'\fR). +.IP "Network configuration" 4 +.IX Item "Network configuration" +Choose the way that the live \s-1CD\s0 configures network access. The +current options are: +.RS 4 +.IP "Automatic configuration" 4 +.IX Item "Automatic configuration" +In this mode, the live \s-1CD\s0 attempts to reuse the network configuration +from the physical machine's root filesystem. You should probably try +this method even though occasionally it does not work. +.IP "Configure from the shell" 4 +.IX Item "Configure from the shell" +In this mode you will be dropped into a command shell and you will +need to issue the correct sequence of \f(CW\*(C`/sbin/ifconfig\*(C'\fR commands in +order to configure the network interface. +.Sp +A typical sequence of commands which should bring up the network +interface would be: +.Sp +.Vb 2 +\& /sbin/ifconfig eth0 AA.BB.CC.DD +\& /sbin/route add default gw GG.HH.II.JJ eth0 +.Ve +.Sp +where \f(CW\*(C`AA.BB.CC.DD\*(C'\fR is the \s-1IP\s0 address and \f(CW\*(C`GG.HH.II.JJ\*(C'\fR is the +gateway. +.RE +.RS 4 +.RE +.IP "Devices" 4 +.IX Item "Devices" +This question lists out all local block devices (hard disk drives and +similar) and asks you to choose which will be sent to the remote host. +You must send at least one block device. +.IP "Root device" 4 +.IX Item "Root device" +This question lists out possible root filesystems and asks you to +choose the right one. Choose the filesystem which would normally be +mounted as \f(CW\*(C`/\*(C'\fR on the system. +.Sp +Virt\-p2v performs some autodetection and is in most cases able to work +out which filesystems are possible root filesystems. It displays what +it thinks is on each filesystem, but leaves it up to the user to make +a final decision. +.Sp +The root filesystem is critical because it contains \f(CW\*(C`/etc/fstab\*(C'\fR. +This is used during P2V both to determine how other filesystems are +normally mounted on the machine, and because this file and others +under \f(CW\*(C`/etc\*(C'\fR may need to be modified during P2V conversion. +.Sp +If the machine has more than one root filesystem (typically because +the machine is dual-booted with another operating system), then you +must choose only one of them to perform the P2V conversion on. +.IP "Hypervisor" 4 +.IX Item "Hypervisor" +This question asks you to choose the hypervisor / virtualization +system in use on the remote host. +.Sp +If you select \fIXen\fR, \fI\s-1QEMU\s0\fR or \fI\s-1KVM\s0\fR then virt\-p2v will produce a +configuration file which is customized for the selected system. If +you select \fIOther\fR then virt\-p2v will produce a generic configuration +file which will probably require hand-modification to work. +.Sp +See also . +.IP "Machine architecture" 4 +.IX Item "Machine architecture" +This question asks you to choose the machine architecture. Virt\-p2v +can normally detect this, so you should leave it as \fIAuto-detect\fR. +.IP "Memory" 4 +.IX Item "Memory" +This question asks you to choose the amount of memory (\s-1RAM\s0) in +megabytes assigned to the virtual machine. +.Sp +If the entry is left blank, then virt\-p2v will try to autodetect how +much \s-1RAM\s0 is present in the physical machine and use that, and this is +probably a good choice for most simple migrations. +.IP "Virtual CPUs" 4 +.IX Item "Virtual CPUs" +This question asks you to choose the number of virtual CPUs assigned +to the virtual machine. Choosing \f(CW1\fR causes the virtual machine to +be uniprocessor, and choosing some number greater than 1 causes the +virtual machine to be \s-1SMP\s0. +.Sp +If the entry is left blank, then virt\-p2v will try to autodetect how +many \s-1CPU\s0 cores are present in the physical machine and use that, and +this is probably a good choice for most simple migrations. +.IP "\s-1MAC\s0 address" 4 +.IX Item "MAC address" +Here you should enter a \s-1MAC\s0 address for the virtual machine's emulated +network card. \s-1MAC\s0 addresses are written as \f(CW\*(C`aa:bb:cc:dd:ee:ff\*(C'\fR where +\&\f(CW\*(C`aa\*(C'\fR, \f(CW\*(C`bb\*(C'\fR etc are hexadecimal octets. +.Sp +Leaving it blank will cause virt\-p2v to choose a random \s-1MAC\s0 address +within the \f(CW\*(C`00:16:3e:..\*(C'\fR space reserved for Xen guests. These \s-1MAC\s0 +addresses are not tested for uniqueness so there is a very small +chance that they could coincide, which would leave a guest unable to +access the virtual network. +.IP "Verify and proceed" 4 +.IX Item "Verify and proceed" +In this step you are asked to verify the settings above. If any are +incorrect, use the \fIBack\fR button to navigate back to the setting. If +all settings are correct, use the \fI\s-1OK\s0\fR button to begin the P2V +conversion. +.IP "Network autoconfiguration" 4 +.IX Item "Network autoconfiguration" +If you selected network autoconfiguration above then virt\-p2v tries to +autoconfigure the network and ping the remote host. It then asks +\&\fIDid automatic network configuration work?\fR +.Sp +You should answer \f(CW\*(C`y\*(C'\fR here if it worked. +.Sp +Answering \f(CW\*(C`n\*(C'\fR will drop you into a command shell. +.Sp +You can also switch to another virtual console if you need to perform +additional tests. See section \fB\s-1GETTING\s0 A \s-1SHELL\s0\fR below. +.IP "\s-1SSH\s0 connection" 4 +.IX Item "SSH connection" +Unless you have set up an \s-1SSH\s0 key, or the \s-1SSH\s0 server on the remote +host allows passwordless logins, then for each file that has to be +transferred to the remote host you will need to confirm the identity +of the remote host and/or enter a password. +.Sp +To understand more about this, please see the \fIssh\fR\|(1) manual page. +.Sh "\s-1BOOTING\s0 P2V \s-1GUEST\s0 \s-1ON\s0 \s-1VIRTUALIZATION\s0 \s-1HOST\s0" +.IX Subsection "BOOTING P2V GUEST ON VIRTUALIZATION HOST" +Once the P2V conversion has been completed, and assuming it was +successful, you will find a configuration file and one or more disk +images on the remote host. +.PP +The files will be located in the directory selected, usually +\&\f(CW\*(C`/var/lib/xen/images\*(C'\fR. The names of the files are made up of: +.PP +\&\f(CW\*(C`p2v\-\f(CIhostname\f(CW\-\f(CI\s-1YYYYMMDDHHMM\s0\f(CW.conf\*(C'\fR or +\&\f(CW\*(C`p2v\-\f(CIhostname\f(CW\-\f(CI\s-1YYYYMMDDHHMM\s0\f(CW\-hd\f(CIX\f(CW.img\*(C'\fR +.PP +To simply start up the guest, use the following commands as root: +.PP +.Vb 2 +\& virsh define p2v-foo-2008MMDDHHMM.conf +\& virsh start foo +.Ve +.PP +For \s-1QEMU/KVM\s0 do: +.PP +.Vb 2 +\& virsh -c qemu:///system define p2v-foo-2008MMDDHHMM.conf +\& virsh -c qemu:///system start foo +.Ve +.PP +For other hypervisors you will need to edit the configuration file and +read . +.SH "GETTING A SHELL" +.IX Header "GETTING A SHELL" +During all stages of P2V questions and conversion you can get a root +shell on the physical machine. Use \fI\s-1ALT\s0\fR \fIF2\fR keys to switch to the +second virtual console, then log in as \fIroot\fR with no password. +.Sh "\s-1LOG\s0 \s-1FILE\s0" +.IX Subsection "LOG FILE" +Virt\-p2v writes a detailed log file to \f(CW\*(C`/tmp/virt\-p2v.log\*(C'\fR. (Note +that this \f(CW\*(C`/tmp\*(C'\fR directory is a ramdisk on the live \s-1CD\s0, not the same +as the \f(CW\*(C`/tmp\*(C'\fR directory of the physical machine, and more importantly +it disappears when the machine is rebooted). +.PP +If you are reporting a bug, please always supply this file. +.SH "SERVER REQUIREMENTS" +.IX Header "SERVER REQUIREMENTS" +The virtualization host (remote host) must be running an \s-1SSH\s0 daemon +(\f(CW\*(C`sshd\*(C'\fR), accessible from the physical machine which is being +migrated. +.PP +Previous versions of virt\-p2v could use a special virt\-p2v server. +However this capability has been removed since there was practically +no benefit. +.SH "BUILDING A CUSTOM LIVE CD" +.IX Header "BUILDING A CUSTOM LIVE CD" +To build a custom live \s-1CD\s0 you must download the source for virt\-p2v +from or from the Mercurial +source repository (see website for details). +.PP +Please read the \f(CW\*(C`README\*(C'\fR file to find the dependencies which are all +in Fedora > 8 or \s-1EPEL\s0 > 5. +.PP +The steps to creating a custom live \s-1CD\s0 are: +.ie n .IP "1. Edit ""virt\-p2v"" and adjust defaults" 4 +.el .IP "1. Edit \f(CWvirt\-p2v\fR and adjust defaults" 4 +.IX Item "1. Edit virt-p2v and adjust defaults" +Find the section \*(L"\s-1TO\s0 \s-1MAKE\s0 A \s-1CUSTOM\s0 virt\-p2v \s-1SCRIPT\s0 ...\*(R" which is near +to the top of this file. Edit the defaults in this section as +detailed below. +.ie n .IP "2. ""virt\-p2v \-\-test"" to verify your changes" 4 +.el .IP "2. \f(CWvirt\-p2v \-\-test\fR to verify your changes" 4 +.IX Item "2. virt-p2v --test to verify your changes" +This command should not print anything at all. If it prints any +message, then you will need to fix the error by going back to the +first step. +.ie n .IP "3. ""make build""\fR or \f(CW""make update"" to build a custom live \s-1CD\s0" 4 +.el .IP "3. \f(CWmake build\fR or \f(CWmake update\fR to build a custom live \s-1CD\s0" 4 +.IX Item "3. make build or make update to build a custom live CD" +\&\f(CW\*(C`make build\*(C'\fR will create a complete \s-1ISO\s0 from scratch. \f(CW\*(C`make update\*(C'\fR +can be used to build a \*(L"quick\*(R" developer \s-1ISO\s0 by updating an existing +\&\s-1ISO\s0 image. See section \fB\s-1ISO\s0 \s-1ATTACHMENTS\s0\fR below for more details. +.IP "4. Burn the \s-1ISO\s0 to a CD-R and test" 4 +.IX Item "4. Burn the ISO to a CD-R and test" +.ie n .Sh "\s-1EDITING\s0 \s-1DEFAULTS\s0 \s-1IN\s0 \s-1THE\s0 ""virt\-p2v"" \s-1SCRIPT\s0" +.el .Sh "\s-1EDITING\s0 \s-1DEFAULTS\s0 \s-1IN\s0 \s-1THE\s0 \f(CWvirt\-p2v\fP \s-1SCRIPT\s0" +.IX Subsection "EDITING DEFAULTS IN THE virt-p2v SCRIPT" +For each default, setting it to \f(CW\*(C`None\*(C'\fR will ask the user. All of the +defaults are set to \f(CW\*(C`None\*(C'\fR in the standard, uncustomized virt\-p2v +script, and so the standard script asks all the questions. +.PP +You may edit \f(CW\*(C`virt\-p2v\*(C'\fR and change the defaults, in which case the +user will not be questioned. In this way you can make the script +partially or fully automated. +.PP +\&\fINote about OCaml code:\fR \f(CW\*(C`None\*(C'\fR and \f(CW\*(C`Some foo\*(C'\fR are similar to the +concept of a \s-1NULL\s0 pointer versus non-NULL pointer in other languages. +This a variant type defined as: +.PP +type α option = None | Some of α +.ie n .IP """greeting""" 4 +.el .IP "\f(CWgreeting\fR" 4 +.IX Item "greeting" +If this is \f(CW\*(C`true\*(C'\fR then we wait for a keypress after boot and at a +couple of other stages. If set to \f(CW\*(C`false\*(C'\fR then we try not to wait +for any keypresses (so more automated live CDs are possible). +.ie n .IP """remote_host""" 4 +.el .IP "\f(CWremote_host\fR" 4 +.IX Item "remote_host" +Set this to \f(CW\*(C`Some "hostname"\*(C'\fR or \f(CW\*(C`Some "IP\-address"\*(C'\fR to +provide the name of the remote host. +.ie n .IP """remote_port""" 4 +.el .IP "\f(CWremote_port\fR" 4 +.IX Item "remote_port" +Set this to \f(CW\*(C`Some port\*(C'\fR (eg. \f(CW\*(C`Some 22\*(C'\fR) to provide the port number +of the remote host's \s-1SSH\s0 daemon. +.ie n .IP """remote_directory""" 4 +.el .IP "\f(CWremote_directory\fR" 4 +.IX Item "remote_directory" +Set this to \f(CW\*(C`Some "path"\*(C'\fR (eg. \f(CW\*(C`Some "/var/lib/xen/images"\*(C'\fR) to +provide the directory where we update P2V converted images and +configuration files. +.ie n .IP """remote_username""" 4 +.el .IP "\f(CWremote_username\fR" 4 +.IX Item "remote_username" +Set this to \f(CW\*(C`Some "username"\*(C'\fR (eg. \f(CW\*(C`Some "root"\*(C'\fR) to provide the \s-1SSH\s0 +username to use on the remote system. +.ie n .IP """devices_to_send""" 4 +.el .IP "\f(CWdevices_to_send\fR" 4 +.IX Item "devices_to_send" +Set this to a list of block devices to send to the remote system. +For example, \f(CW\*(C`Some ["sda"; "sdb"]\*(C'\fR. +.ie n .IP """root_filesystem""" 4 +.el .IP "\f(CWroot_filesystem\fR" 4 +.IX Item "root_filesystem" +Set this to the name of the root filesystem. +.Sp +For a disk partition (eg. \f(CW\*(C`/dev/sda1\*(C'\fR), use: +.Sp +.Vb 1 +\& Some (Part ("sda", "1")) +.Ve +.Sp +For a logical volume (eg. \f(CW\*(C`/dev/VolGroup00/LogVol00\*(C'\fR), use: +.Sp +.Vb 1 +\& Some (LV ("VolGroup00", "LogVol00")) +.Ve +.ie n .IP """network""" 4 +.el .IP "\f(CWnetwork\fR" 4 +.IX Item "network" +Set this to the choice for network setup. Use either \f(CW\*(C`Some Auto\*(C'\fR or +\&\f(CW\*(C`Some Shell\*(C'\fR for auto-configuration or shell (manual) configuration +respectively. +.ie n .IP """hypervisor""" 4 +.el .IP "\f(CWhypervisor\fR" 4 +.IX Item "hypervisor" +Set this to the choice of hypervisor or virtualization system. The +choices are: \f(CW\*(C`Some Xen\*(C'\fR, \f(CW\*(C`Some QEMU\*(C'\fR or \f(CW\*(C`Some KVM\*(C'\fR. +.ie n .IP """architecture""" 4 +.el .IP "\f(CWarchitecture\fR" 4 +.IX Item "architecture" +Set this to the architecture. The choices are: +\&\f(CW\*(C`Some I386\*(C'\fR (i386 and up, 32 bit), +\&\f(CW\*(C`Some X86_64\*(C'\fR (\s-1AMD\s0 and Intel x86\-64, 64 bit), +\&\f(CW\*(C`Some IA64\*(C'\fR (Intel \s-1IA64\s0), +\&\f(CW\*(C`Some PPC\*(C'\fR (PowerPC, 32 bit), +\&\f(CW\*(C`Some PPC64\*(C'\fR (PowerPC, 64 bit), +\&\f(CW\*(C`Some SPARC\*(C'\fR (Sun \s-1SPARC\s0, 32 bit), +\&\f(CW\*(C`Some SPARC64\*(C'\fR (Sun \s-1SPARC\s0, 64 bit), +\&\f(CW\*(C`OtherArch "foo"\*(C'\fR (a hypothetical architecture called \fIfoo\fR), or +\&\f(CW\*(C`UnknownArch\*(C'\fR to auto-detect the architecture. +.ie n .IP """memory""" 4 +.el .IP "\f(CWmemory\fR" 4 +.IX Item "memory" +Set this to the size of memory in megabytes, eg. \f(CW\*(C`Some 256\*(C'\fR. If you +set this to \f(CW\*(C`Some 0\*(C'\fR then virt\-p2v will try to autodetect the amount +of \s-1RAM\s0 installed on the physical machine. +.ie n .IP """vcpus""" 4 +.el .IP "\f(CWvcpus\fR" 4 +.IX Item "vcpus" +Set this to the number of virtual CPUs, eg. \f(CW\*(C`Some 1\*(C'\fR. If you set +this to \f(CW\*(C`Some 0\*(C'\fR then virt\-p2v will try to autodetect the number of +\&\s-1CPU\s0 cores on the physical machine. +.ie n .IP """mac_address""" 4 +.el .IP "\f(CWmac_address\fR" 4 +.IX Item "mac_address" +Set this to the \s-1MAC\s0 address for the virtual network card, eg. \f(CW\*(C`Some +"aa:bb:cc:dd:ee:ff"\*(C'\fR. If you set this to \f(CW\*(C`Some ""\*(C'\fR then virt\-p2v +will choose a random \s-1MAC\s0 address within the \f(CW\*(C`00:16:3e:..\*(C'\fR space +reserved for Xen guests. These \s-1MAC\s0 addresses are not tested for +uniqueness so there is a very small chance that they could coincide, +which would leave a guest unable to access the virtual network. +.Sh "\s-1ISO\s0 \s-1ATTACHMENTS\s0" +.IX Subsection "ISO ATTACHMENTS" +Rebuilding a custom \s-1ISO\s0 is time\-consuming. You can make a \*(L"quick\*(R" +developer \s-1ISO\s0 by updating an existing \s-1ISO\s0 image with a new custom +\&\f(CW\*(C`virt\-p2v\*(C'\fR script. This is useful for testing purposes. +.PP +From the source directory, assuming that you have downloaded or +built an existing \f(CW\*(C`virt\-p2v\-*.iso\*(C'\fR, you can just do: +.PP +.Vb 1 +\& make update +.Ve +.PP +or the equivalent manual command: +.PP +.Vb 1 +\& ./iso-attach virt-p2v-VERSION.iso virt-p2v +.Ve +.SH "BOOTING FROM A USB KEY INSTEAD OF A CD" +.IX Header "BOOTING FROM A USB KEY INSTEAD OF A CD" +If you wish to boot from a \s-1USB\s0 keydrive, use the livecd-iso-to-disk +tool: +.PP +.Vb 1 +\& livecd-iso-to-disk virt-p2v-$VERSION.iso /dev/sdX1 +.Ve +.PP +(Replace /dev/sdX1 with the actual \s-1USB\s0 device). +.PP +In my experience I also had to set up a suitable \s-1MBR:\s0 +.PP +.Vb 1 +\& cat /usr/lib/syslinux/mbr.bin > /dev/sdX +.Ve +.SH "TESTING AN ISO UNDER QEMU OR KVM" +.IX Header "TESTING AN ISO UNDER QEMU OR KVM" +If you have a virtual guest running under \s-1QEMU\s0 or \s-1KVM\s0 then +you can test the P2V conversion process on the guest. +.PP +(Technically this is a V2V \*(-- virtual to virtual \*(-- conversion). +.PP +From the source directory do: +.PP +.Vb 1 +\& make boot HDA=qemuimage.img +.Ve +.PP +where \f(CW\*(C`qemuimage.img\*(C'\fR is the name of the \s-1QEMU/KVM\s0 image. +.PP +You can also supply an \f(CW\*(C`HDB\*(C'\fR parameter to specify a second disk. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIvirsh\fR\|(1), +, +, +, + +.SH "AUTHORS" +.IX Header "AUTHORS" +Richard W.M. Jones +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +(C) Copyright 2007\-2008 Red Hat Inc., Richard W.M. Jones +http://libvirt.org/ +.PP +This program is free software; you can redistribute it and/or modify +it under the terms of the \s-1GNU\s0 General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. +.PP +This program is distributed in the hope that it will be useful, +but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of +\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0. See the +\&\s-1GNU\s0 General Public License for more details. +.PP +You should have received a copy of the \s-1GNU\s0 General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 675 Mass Ave, Cambridge, \s-1MA\s0 02139, \s-1USA\s0. +.SH "REPORTING BUGS" +.IX Header "REPORTING BUGS" +Bugs can be viewed on the Red Hat Bugzilla page: +. +.PP +If you find a bug in virt\-p2v, please follow these steps to report it: +.IP "1. Check for existing bug reports" 4 +.IX Item "1. Check for existing bug reports" +Go to and search for similar bugs. +Someone may already have reported the same bug, and they may even +have fixed it. +.IP "2. Capture debug and error messages" 4 +.IX Item "2. Capture debug and error messages" +At the point where you get the error or unexpected behaviour, +go to the second virtual console (\fI\s-1ALT\s0\fR \fIF2\fR) and look at +the logfile \f(CW\*(C`/tmp/virt\-p2v.log\*(C'\fR. Please make sure that +this file is attached to your bug report. +.IP "3. Get version of virt\-p2v" 4 +.IX Item "3. Get version of virt-p2v" +The version is in the name of the \s-1ISO\s0. If you have built a custom +virt\-p2v \s-1ISO\s0, please describe any changes that you have made. +.IP "4. Submit a bug report." 4 +.IX Item "4. Submit a bug report." +Go to and enter a new bug. +Please describe the problem in as much detail as possible. +.Sp +Remember to include the version number (step 3) and to +attach the log file (step 2). +.IP "5. Assign the bug to rjones @ redhat.com" 4 +.IX Item "5. Assign the bug to rjones @ redhat.com" +Assign or reassign the bug to \fBrjones @ redhat.com\fR (without the +spaces). You can also send me an email with the bug number if you +want a faster response. diff --git a/virt-p2v.1.css b/virt-p2v.1.css new file mode 100644 index 0000000..82a5eee --- /dev/null +++ b/virt-p2v.1.css @@ -0,0 +1,159 @@ +/* CSS for et.redhat.com/~rjones/ + * $Id: standard.css,v 1.10 2007/08/29 16:03:21 rjones Exp $ + */ + +body { + margin-left: 1em; +} + +body p, body ul { + margin-left: 2em; + width: 35em; +} + +/* Headings. */ + +h1 { + font-size: 120%; + border-bottom: 1px solid #eee; +} + +h2 { + font-size: 110%; +} + +h1, h2, h3, h4 { + color: #333; +} + +hr { display: none; } + +/* Code sections. */ + +code { + font-size: 120%; +} + +pre { + background-color: #fcfcfc; + /*border: 1px dotted #888;*/ + border-left: 6px solid #f0f0f0; + padding: 5px; + margin-left: 1em; + font-size: 120%; +} + +/* Notes. */ + +p.note { + margin-left: 2em; + margin-right: 1em; + /*border: 1px dotted #888;*/ + padding-left: 36px; + background: url(../images/note.png) no-repeat; +} + +p.warning { + margin-left: 2em; + margin-right: 1em; + border: 1px dotted #800; + padding-left: 36px; + background: url(../images/warning.png) no-repeat #fee; +} + +/* Highlighted text. */ + +span.highlight { + color: red; +} + +/* Images. */ + +img.frame_img { + border: 1px solid #888; + padding: 6px; +} + +/* Nice-looking tables. */ + +table.top_table { + border-collapse: collapse; +} + +table.top_table th { + vertical-align: top; + padding: 3px; + border-bottom: 1px solid #ddd; +} + +table.top_table td { + vertical-align: top; + padding: 3px; +} + +table.top_table td.number { + text-align: right; +} + +table.top_table th.divider { + text-align: center; + padding: 6px; + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; +} + +table.left_table { + border-collapse: collapse; +} + +table.left_table th { + text-align: right; + vertical-align: top; + padding: 3px; + padding-right: 1em; +} + +table.left_table td { + vertical-align: top; + padding: 3px; +} + +table.left_table td.number { + text-align: right; +} + +table.left_table th.divider { + text-align: center; + padding: 6px; + border-top: 1px solid #eee; + border-bottom: 1px solid #eee; +} + +/* Float-left images with text around. */ + +img.leftpara { + float: left; + clear: left; + margin-right: 1em; + margin-bottom: 1em; +} + +/*
    styled as menus. */ + +ul.menu { + width: 60em; + padding: 0px; + margin-left: 1em; + list-style: none; +} + +ul.menu li { + display: inline; + border-left: 1px solid #666; + padding-left: 5px; +} + +ul.menu li.first { + border-left: none; + padding-left: 0px; +} \ No newline at end of file diff --git a/virt-p2v.1.html b/virt-p2v.1.html new file mode 100644 index 0000000..a795e86 --- /dev/null +++ b/virt-p2v.1.html @@ -0,0 +1,629 @@ + + + + +virt-p2v - P2V migration tool + + + + + + + +

    + + + + + +
    +

    +

    +

    NAME

    +

    virt-p2v - P2V (physical to virtual machine) migration tool

    +

    +

    +
    +

    SUMMARY

    +

    virt-p2v

    +

    +

    +
    +

    DESCRIPTION

    +

    virt-p2v is a live CD for migrating physical machines to virtual +machine guests.

    +

    In the simplest mode of operation, you take a pre-built live CD ISO +from the main website (http://et.redhat.com/~rjones/virt-p2v/) and +burn it to a CD-R. Then insert the CD-R into the physical machine +which must be migrated, reboot, and follow the on-screen instructions. +See STANDARD USAGE section below.

    +

    You may also build a customized live CD. Typically this will contain +things like server details specific to your organization, so that the +live CD can run mostly or completely automatically. See BUILDING A +CUSTOM LIVE CD section below.

    +

    In both cases, files and disk images are transferred from the physical +machine over the network to the virtualization host machine over ssh. +Therefore sshd must be running on the virtualization host, and must +be accessible to that host. See SERVER REQUIREMENTS section below.

    +

    The virt-p2v script must only be run from the live CD. It isn't +designed to run outside this environment and could do Bad Things to +your machine if you try it. The script contains some checks to try to +stop you from doing this.

    +

    Virt-p2v does not modify the physical machine, its disks, +configuration etc.

    +

    +

    +
    +

    STANDARD USAGE

    +

    After booting the live CD-R, you are presented with a series of +questions. This section explains each question.

    +
    +
    Remote host + +
    +

    Enter the name or IP address of the virtualization host. This is the +host running Xen (or any other virtualization system supported by +libvirt, eg. QEMU). This host should be accessible on the network and +running an SSH daemon (sshd).

    +
    + +
    Remote port + +
    +

    This is the port name or number of the SSH server on the remote host. +The default is 22 which is the standard SSH port.

    +
    + +
    Remote directory + +
    +

    Enter the directory on the remote host where disk image(s) and +configuration file(s) must reside.

    +
    +
    +

    Note that if the remote host is running SELinux then you may not be +able to start a Xen guest unless its disk image(s) are located in the +default directory, /var/lib/xen/images.

    +
    + +
    Remote username + +
    +

    Enter the remote SSH username to use to log in to the remote host.

    +
    +
    +

    If you use the default username of root then you should ensure that +remote root logins are enabled on the remote host +(ie. PermitRootLogin yes in /etc/ssh/sshd_config).

    +
    + +
    Network configuration + +
    +

    Choose the way that the live CD configures network access. The +current options are:

    +
    +
    +
    Automatic configuration + +
    +

    In this mode, the live CD attempts to reuse the network configuration +from the physical machine's root filesystem. You should probably try +this method even though occasionally it does not work.

    +
    + +
    Configure from the shell + +
    +

    In this mode you will be dropped into a command shell and you will +need to issue the correct sequence of /sbin/ifconfig commands in +order to configure the network interface.

    +
    +
    +

    A typical sequence of commands which should bring up the network +interface would be:

    +
    +
    +
    + /sbin/ifconfig eth0 AA.BB.CC.DD
+ /sbin/route add default gw GG.HH.II.JJ eth0
    +
    +
    +

    where AA.BB.CC.DD is the IP address and GG.HH.II.JJ is the +gateway.

    +
    + +
    +
    Devices + +
    +

    This question lists out all local block devices (hard disk drives and +similar) and asks you to choose which will be sent to the remote host. +You must send at least one block device.

    +
    + +
    Root device + +
    +

    This question lists out possible root filesystems and asks you to +choose the right one. Choose the filesystem which would normally be +mounted as / on the system.

    +
    +
    +

    Virt-p2v performs some autodetection and is in most cases able to work +out which filesystems are possible root filesystems. It displays what +it thinks is on each filesystem, but leaves it up to the user to make +a final decision.

    +
    +
    +

    The root filesystem is critical because it contains /etc/fstab. +This is used during P2V both to determine how other filesystems are +normally mounted on the machine, and because this file and others +under /etc may need to be modified during P2V conversion.

    +
    +
    +

    If the machine has more than one root filesystem (typically because +the machine is dual-booted with another operating system), then you +must choose only one of them to perform the P2V conversion on.

    +
    + +
    Hypervisor + +
    +

    This question asks you to choose the hypervisor / virtualization +system in use on the remote host.

    +
    +
    +

    If you select Xen, QEMU or KVM then virt-p2v will produce a +configuration file which is customized for the selected system. If +you select Other then virt-p2v will produce a generic configuration +file which will probably require hand-modification to work.

    +
    +
    +

    See also http://libvirt.org/format.html.

    +
    + +
    Machine architecture + +
    +

    This question asks you to choose the machine architecture. Virt-p2v +can normally detect this, so you should leave it as Auto-detect.

    +
    + +
    Memory + +
    +

    This question asks you to choose the amount of memory (RAM) in +megabytes assigned to the virtual machine.

    +
    +
    +

    If the entry is left blank, then virt-p2v will try to autodetect how +much RAM is present in the physical machine and use that, and this is +probably a good choice for most simple migrations.

    +
    + +
    Virtual CPUs + +
    +

    This question asks you to choose the number of virtual CPUs assigned +to the virtual machine. Choosing 1 causes the virtual machine to +be uniprocessor, and choosing some number greater than 1 causes the +virtual machine to be SMP.

    +
    +
    +

    If the entry is left blank, then virt-p2v will try to autodetect how +many CPU cores are present in the physical machine and use that, and +this is probably a good choice for most simple migrations.

    +
    + +
    MAC address + +
    +

    Here you should enter a MAC address for the virtual machine's emulated +network card. MAC addresses are written as aa:bb:cc:dd:ee:ff where +aa, bb etc are hexadecimal octets.

    +
    +
    +

    Leaving it blank will cause virt-p2v to choose a random MAC address +within the 00:16:3e:.. space reserved for Xen guests. These MAC +addresses are not tested for uniqueness so there is a very small +chance that they could coincide, which would leave a guest unable to +access the virtual network.

    +
    + +
    Verify and proceed + +
    +

    In this step you are asked to verify the settings above. If any are +incorrect, use the Back button to navigate back to the setting. If +all settings are correct, use the OK button to begin the P2V +conversion.

    +
    + +
    Network autoconfiguration + +
    +

    If you selected network autoconfiguration above then virt-p2v tries to +autoconfigure the network and ping the remote host. It then asks +Did automatic network configuration work?

    +
    +
    +

    You should answer y here if it worked.

    +
    +
    +

    Answering n will drop you into a command shell.

    +
    +
    +

    You can also switch to another virtual console if you need to perform +additional tests. See section GETTING A SHELL below.

    +
    + +
    SSH connection + +
    +

    Unless you have set up an SSH key, or the SSH server on the remote +host allows passwordless logins, then for each file that has to be +transferred to the remote host you will need to confirm the identity +of the remote host and/or enter a password.

    +
    +
    +

    To understand more about this, please see the ssh(1) manual page.

    +
    + +
    +

    +

    +

    BOOTING P2V GUEST ON VIRTUALIZATION HOST

    +

    Once the P2V conversion has been completed, and assuming it was +successful, you will find a configuration file and one or more disk +images on the remote host.

    +

    The files will be located in the directory selected, usually +/var/lib/xen/images. The names of the files are made up of:

    +

    p2v-hostname-YYYYMMDDHHMM.conf or +p2v-hostname-YYYYMMDDHHMM-hdX.img

    +

    To simply start up the guest, use the following commands as root:

    +
    + virsh define p2v-foo-2008MMDDHHMM.conf
+ virsh start foo
    +

    For QEMU/KVM do:

    +
    + virsh -c qemu:///system define p2v-foo-2008MMDDHHMM.conf
+ virsh -c qemu:///system start foo
    +

    For other hypervisors you will need to edit the configuration file and +read http://libvirt.org/uri.html.

    +

    +

    +
    +

    GETTING A SHELL

    +

    During all stages of P2V questions and conversion you can get a root +shell on the physical machine. Use ALT F2 keys to switch to the +second virtual console, then log in as root with no password.

    +

    +

    +

    LOG FILE

    +

    Virt-p2v writes a detailed log file to /tmp/virt-p2v.log. (Note +that this /tmp directory is a ramdisk on the live CD, not the same +as the /tmp directory of the physical machine, and more importantly +it disappears when the machine is rebooted).

    +

    If you are reporting a bug, please always supply this file.

    +

    +

    +
    +

    SERVER REQUIREMENTS

    +

    The virtualization host (remote host) must be running an SSH daemon +(sshd), accessible from the physical machine which is being +migrated.

    +

    Previous versions of virt-p2v could use a special virt-p2v server. +However this capability has been removed since there was practically +no benefit.

    +

    +

    +
    +

    BUILDING A CUSTOM LIVE CD

    +

    To build a custom live CD you must download the source for virt-p2v +from http://et.redhat.com/~rjones/virt-p2v/ or from the Mercurial +source repository (see website for details).

    +

    Please read the README file to find the dependencies which are all +in Fedora &gt; 8 or EPEL &gt; 5.

    +

    The steps to creating a custom live CD are:

    +
      +
    1. Edit virt-p2v and adjust defaults + +

      Find the section ``TO MAKE A CUSTOM virt-p2v SCRIPT ...'' which is near +to the top of this file. Edit the defaults in this section as +detailed below.

      +
      2. +
    2. virt-p2v --test to verify your changes + +

      This command should not print anything at all. If it prints any +message, then you will need to fix the error by going back to the +first step.

      +
      3. +
    3. make build or make update to build a custom live CD + +

      make build will create a complete ISO from scratch. make update +can be used to build a ``quick'' developer ISO by updating an existing +ISO image. See section ISO ATTACHMENTS below for more details.

      +
      4. +
    4. Burn the ISO to a CD-R and test + +
    +

    +

    +

    EDITING DEFAULTS IN THE virt-p2v SCRIPT

    +

    For each default, setting it to None will ask the user. All of the +defaults are set to None in the standard, uncustomized virt-p2v +script, and so the standard script asks all the questions.

    +

    You may edit virt-p2v and change the defaults, in which case the +user will not be questioned. In this way you can make the script +partially or fully automated.

    +

    Note about OCaml code: None and Some foo are similar to the +concept of a NULL pointer versus non-NULL pointer in other languages. +This a variant type defined as:

    +

    type α option = None | Some of α

    +
    +
    greeting + +
    +

    If this is true then we wait for a keypress after boot and at a +couple of other stages. If set to false then we try not to wait +for any keypresses (so more automated live CDs are possible).

    +
    + +
    remote_host + +
    +

    Set this to Some "hostname" or Some "IP-address" to +provide the name of the remote host.

    +
    + +
    remote_port + +
    +

    Set this to Some port (eg. Some 22) to provide the port number +of the remote host's SSH daemon.

    +
    + +
    remote_directory + +
    +

    Set this to Some "path" (eg. Some "/var/lib/xen/images") to +provide the directory where we update P2V converted images and +configuration files.

    +
    + +
    remote_username + +
    +

    Set this to Some "username" (eg. Some "root") to provide the SSH +username to use on the remote system.

    +
    + +
    devices_to_send + +
    +

    Set this to a list of block devices to send to the remote system. +For example, Some ["sda"; "sdb"].

    +
    + +
    root_filesystem + +
    +

    Set this to the name of the root filesystem.

    +
    +
    +

    For a disk partition (eg. /dev/sda1), use:

    +
    +
    +
    + Some (Part ("sda", "1"))
    +
    +
    +

    For a logical volume (eg. /dev/VolGroup00/LogVol00), use:

    +
    +
    +
    + Some (LV ("VolGroup00", "LogVol00"))
    +
    + +
    network + +
    +

    Set this to the choice for network setup. Use either Some Auto or +Some Shell for auto-configuration or shell (manual) configuration +respectively.

    +
    + +
    hypervisor + +
    +

    Set this to the choice of hypervisor or virtualization system. The +choices are: Some Xen, Some QEMU or Some KVM.

    +
    + +
    architecture + +
    +

    Set this to the architecture. The choices are: +Some I386 (i386 and up, 32 bit), +Some X86_64 (AMD and Intel x86-64, 64 bit), +Some IA64 (Intel IA64), +Some PPC (PowerPC, 32 bit), +Some PPC64 (PowerPC, 64 bit), +Some SPARC (Sun SPARC, 32 bit), +Some SPARC64 (Sun SPARC, 64 bit), +OtherArch "foo" (a hypothetical architecture called foo), or +UnknownArch to auto-detect the architecture.

    +
    + +
    memory + +
    +

    Set this to the size of memory in megabytes, eg. Some 256. If you +set this to Some 0 then virt-p2v will try to autodetect the amount +of RAM installed on the physical machine.

    +
    + +
    vcpus + +
    +

    Set this to the number of virtual CPUs, eg. Some 1. If you set +this to Some 0 then virt-p2v will try to autodetect the number of +CPU cores on the physical machine.

    +
    + +
    mac_address + +
    +

    Set this to the MAC address for the virtual network card, eg. Some +"aa:bb:cc:dd:ee:ff". If you set this to Some "" then virt-p2v +will choose a random MAC address within the 00:16:3e:.. space +reserved for Xen guests. These MAC addresses are not tested for +uniqueness so there is a very small chance that they could coincide, +which would leave a guest unable to access the virtual network.

    +
    + +
    +

    +

    +

    ISO ATTACHMENTS

    +

    Rebuilding a custom ISO is time-consuming. You can make a ``quick'' +developer ISO by updating an existing ISO image with a new custom +virt-p2v script. This is useful for testing purposes.

    +

    From the source directory, assuming that you have downloaded or +built an existing virt-p2v-*.iso, you can just do:

    +
    + make update
    +

    or the equivalent manual command:

    +
    + ./iso-attach virt-p2v-VERSION.iso virt-p2v
    +

    +

    +
    +

    BOOTING FROM A USB KEY INSTEAD OF A CD

    +

    If you wish to boot from a USB keydrive, use the livecd-iso-to-disk +tool:

    +
    + livecd-iso-to-disk virt-p2v-$VERSION.iso /dev/sdX1
    +

    (Replace /dev/sdX1 with the actual USB device).

    +

    In my experience I also had to set up a suitable MBR:

    +
    + cat /usr/lib/syslinux/mbr.bin > /dev/sdX
    +

    +

    +
    +

    TESTING AN ISO UNDER QEMU OR KVM

    +

    If you have a virtual guest running under QEMU or KVM then +you can test the P2V conversion process on the guest.

    +

    (Technically this is a V2V -- virtual to virtual -- conversion).

    +

    From the source directory do:

    +
    + make boot HDA=qemuimage.img
    +

    where qemuimage.img is the name of the QEMU/KVM image.

    +

    You can also supply an HDB parameter to specify a second disk.

    +

    +

    +
    +

    SEE ALSO

    +

    virsh(1), +http://www.libvirt.org/ocaml/, +http://www.libvirt.org/, +http://et.redhat.com/~rjones/, +http://caml.inria.fr/

    +

    +

    +
    +

    AUTHORS

    +

    Richard W.M. Jones <rjones @ redhat . com>

    +

    +

    +
    +

    COPYRIGHT

    +

    (C) Copyright 2007-2008 Red Hat Inc., Richard W.M. Jones +http://libvirt.org/

    +

    This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version.

    +

    This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details.

    +

    You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

    +

    +

    +
    +

    REPORTING BUGS

    +

    Bugs can be viewed on the Red Hat Bugzilla page: +https://bugzilla.redhat.com/.

    +

    If you find a bug in virt-p2v, please follow these steps to report it:

    +
      +
    1. Check for existing bug reports + +

      Go to https://bugzilla.redhat.com/ and search for similar bugs. +Someone may already have reported the same bug, and they may even +have fixed it.

      +
      2. +
    2. Capture debug and error messages + +

      At the point where you get the error or unexpected behaviour, +go to the second virtual console (ALT F2) and look at +the logfile /tmp/virt-p2v.log. Please make sure that +this file is attached to your bug report.

      +
      3. +
    3. Get version of virt-p2v + +

      The version is in the name of the ISO. If you have built a custom +virt-p2v ISO, please describe any changes that you have made.

      +
      4. +
    4. Submit a bug report. + +

      Go to https://bugzilla.redhat.com/ and enter a new bug. +Please describe the problem in as much detail as possible.

      +

      Remember to include the version number (step 3) and to +attach the log file (step 2).

      +
      5. +
    5. Assign the bug to rjones @ redhat.com + +

      Assign or reassign the bug to rjones @ redhat.com (without the +spaces). You can also send me an email with the bug number if you +want a faster response.

      +
      6. +
    + + + + diff --git a/virt-p2v.1.txt b/virt-p2v.1.txt new file mode 100644 index 0000000..5b33f74 --- /dev/null +++ b/virt-p2v.1.txt @@ -0,0 +1,439 @@ +NAME + virt-p2v - P2V (physical to virtual machine) migration tool + +SUMMARY + virt-p2v + +DESCRIPTION + virt-p2v is a live CD for migrating physical machines to virtual machine + guests. + + In the simplest mode of operation, you take a pre-built live CD ISO from + the main website () and burn it + to a CD-R. Then insert the CD-R into the physical machine which must be + migrated, reboot, and follow the on-screen instructions. See STANDARD + USAGE section below. + + You may also build a customized live CD. Typically this will contain + things like server details specific to your organization, so that the + live CD can run mostly or completely automatically. See BUILDING A + CUSTOM LIVE CD section below. + + In both cases, files and disk images are transferred from the physical + machine over the network to the virtualization host machine over ssh. + Therefore "sshd" must be running on the virtualization host, and must be + accessible to that host. See SERVER REQUIREMENTS section below. + + The "virt-p2v" script must only be run from the live CD. It isn't + designed to run outside this environment and could do Bad Things to your + machine if you try it. The script contains some checks to try to stop + you from doing this. + + Virt-p2v does not modify the physical machine, its disks, configuration + etc. + +STANDARD USAGE + After booting the live CD-R, you are presented with a series of + questions. This section explains each question. + + Remote host + Enter the name or IP address of the virtualization host. This is the + host running Xen (or any other virtualization system supported by + libvirt, eg. QEMU). This host should be accessible on the network + and running an SSH daemon ("sshd"). + + Remote port + This is the port name or number of the SSH server on the remote + host. The default is 22 which is the standard SSH port. + + Remote directory + Enter the directory on the remote host where disk image(s) and + configuration file(s) must reside. + + Note that if the remote host is running SELinux then you may not be + able to start a Xen guest unless its disk image(s) are located in + the default directory, "/var/lib/xen/images". + + Remote username + Enter the remote SSH username to use to log in to the remote host. + + If you use the default username of "root" then you should ensure + that remote root logins are enabled on the remote host (ie. + "PermitRootLogin yes" in "/etc/ssh/sshd_config"). + + Network configuration + Choose the way that the live CD configures network access. The + current options are: + + Automatic configuration + In this mode, the live CD attempts to reuse the network + configuration from the physical machine's root filesystem. You + should probably try this method even though occasionally it does + not work. + + Configure from the shell + In this mode you will be dropped into a command shell and you + will need to issue the correct sequence of "/sbin/ifconfig" + commands in order to configure the network interface. + + A typical sequence of commands which should bring up the network + interface would be: + + /sbin/ifconfig eth0 AA.BB.CC.DD + /sbin/route add default gw GG.HH.II.JJ eth0 + + where "AA.BB.CC.DD" is the IP address and "GG.HH.II.JJ" is the + gateway. + + Devices + This question lists out all local block devices (hard disk drives + and similar) and asks you to choose which will be sent to the remote + host. You must send at least one block device. + + Root device + This question lists out possible root filesystems and asks you to + choose the right one. Choose the filesystem which would normally be + mounted as "/" on the system. + + Virt-p2v performs some autodetection and is in most cases able to + work out which filesystems are possible root filesystems. It + displays what it thinks is on each filesystem, but leaves it up to + the user to make a final decision. + + The root filesystem is critical because it contains "/etc/fstab". + This is used during P2V both to determine how other filesystems are + normally mounted on the machine, and because this file and others + under "/etc" may need to be modified during P2V conversion. + + If the machine has more than one root filesystem (typically because + the machine is dual-booted with another operating system), then you + must choose only one of them to perform the P2V conversion on. + + Hypervisor + This question asks you to choose the hypervisor / virtualization + system in use on the remote host. + + If you select *Xen*, *QEMU* or *KVM* then virt-p2v will produce a + configuration file which is customized for the selected system. If + you select *Other* then virt-p2v will produce a generic + configuration file which will probably require hand-modification to + work. + + See also . + + Machine architecture + This question asks you to choose the machine architecture. Virt-p2v + can normally detect this, so you should leave it as *Auto-detect*. + + Memory + This question asks you to choose the amount of memory (RAM) in + megabytes assigned to the virtual machine. + + If the entry is left blank, then virt-p2v will try to autodetect how + much RAM is present in the physical machine and use that, and this + is probably a good choice for most simple migrations. + + Virtual CPUs + This question asks you to choose the number of virtual CPUs assigned + to the virtual machine. Choosing 1 causes the virtual machine to be + uniprocessor, and choosing some number greater than 1 causes the + virtual machine to be SMP. + + If the entry is left blank, then virt-p2v will try to autodetect how + many CPU cores are present in the physical machine and use that, and + this is probably a good choice for most simple migrations. + + MAC address + Here you should enter a MAC address for the virtual machine's + emulated network card. MAC addresses are written as + "aa:bb:cc:dd:ee:ff" where "aa", "bb" etc are hexadecimal octets. + + Leaving it blank will cause virt-p2v to choose a random MAC address + within the "00:16:3e:.." space reserved for Xen guests. These MAC + addresses are not tested for uniqueness so there is a very small + chance that they could coincide, which would leave a guest unable to + access the virtual network. + + Verify and proceed + In this step you are asked to verify the settings above. If any are + incorrect, use the *Back* button to navigate back to the setting. If + all settings are correct, use the *OK* button to begin the P2V + conversion. + + Network autoconfiguration + If you selected network autoconfiguration above then virt-p2v tries + to autoconfigure the network and ping the remote host. It then asks + *Did automatic network configuration work?* + + You should answer "y" here if it worked. + + Answering "n" will drop you into a command shell. + + You can also switch to another virtual console if you need to + perform additional tests. See section GETTING A SHELL below. + + SSH connection + Unless you have set up an SSH key, or the SSH server on the remote + host allows passwordless logins, then for each file that has to be + transferred to the remote host you will need to confirm the identity + of the remote host and/or enter a password. + + To understand more about this, please see the ssh(1) manual page. + + BOOTING P2V GUEST ON VIRTUALIZATION HOST + Once the P2V conversion has been completed, and assuming it was + successful, you will find a configuration file and one or more disk + images on the remote host. + + The files will be located in the directory selected, usually + "/var/lib/xen/images". The names of the files are made up of: + + "p2v-*hostname*-*YYYYMMDDHHMM*.conf" or + "p2v-*hostname*-*YYYYMMDDHHMM*-hd*X*.img" + + To simply start up the guest, use the following commands as root: + + virsh define p2v-foo-2008MMDDHHMM.conf + virsh start foo + + For QEMU/KVM do: + + virsh -c qemu:///system define p2v-foo-2008MMDDHHMM.conf + virsh -c qemu:///system start foo + + For other hypervisors you will need to edit the configuration file and + read . + +GETTING A SHELL + During all stages of P2V questions and conversion you can get a root + shell on the physical machine. Use *ALT* *F2* keys to switch to the + second virtual console, then log in as *root* with no password. + + LOG FILE + Virt-p2v writes a detailed log file to "/tmp/virt-p2v.log". (Note that + this "/tmp" directory is a ramdisk on the live CD, not the same as the + "/tmp" directory of the physical machine, and more importantly it + disappears when the machine is rebooted). + + If you are reporting a bug, please always supply this file. + +SERVER REQUIREMENTS + The virtualization host (remote host) must be running an SSH daemon + ("sshd"), accessible from the physical machine which is being migrated. + + Previous versions of virt-p2v could use a special virt-p2v server. + However this capability has been removed since there was practically no + benefit. + +BUILDING A CUSTOM LIVE CD + To build a custom live CD you must download the source for virt-p2v from + or from the Mercurial source + repository (see website for details). + + Please read the "README" file to find the dependencies which are all in + Fedora > 8 or EPEL > 5. + + The steps to creating a custom live CD are: + + 1. Edit "virt-p2v" and adjust defaults + Find the section "TO MAKE A CUSTOM virt-p2v SCRIPT ..." which is + near to the top of this file. Edit the defaults in this section as + detailed below. + + 2. "virt-p2v --test" to verify your changes + This command should not print anything at all. If it prints any + message, then you will need to fix the error by going back to the + first step. + + 3. "make build" or "make update" to build a custom live CD + "make build" will create a complete ISO from scratch. "make update" + can be used to build a "quick" developer ISO by updating an existing + ISO image. See section ISO ATTACHMENTS below for more details. + + 4. Burn the ISO to a CD-R and test + + EDITING DEFAULTS IN THE "virt-p2v" SCRIPT + For each default, setting it to "None" will ask the user. All of the + defaults are set to "None" in the standard, uncustomized virt-p2v + script, and so the standard script asks all the questions. + + You may edit "virt-p2v" and change the defaults, in which case the user + will not be questioned. In this way you can make the script partially or + fully automated. + + *Note about OCaml code:* "None" and "Some foo" are similar to the + concept of a NULL pointer versus non-NULL pointer in other languages. + This a variant type defined as: + + type α option = None | Some of α + + "greeting" + If this is "true" then we wait for a keypress after boot and at a + couple of other stages. If set to "false" then we try not to wait + for any keypresses (so more automated live CDs are possible). + + "remote_host" + Set this to "Some "hostname"" or "Some "IP-address"" to provide the + name of the remote host. + + "remote_port" + Set this to "Some port" (eg. "Some 22") to provide the port number + of the remote host's SSH daemon. + + "remote_directory" + Set this to "Some "path"" (eg. "Some "/var/lib/xen/images"") to + provide the directory where we update P2V converted images and + configuration files. + + "remote_username" + Set this to "Some "username"" (eg. "Some "root"") to provide the SSH + username to use on the remote system. + + "devices_to_send" + Set this to a list of block devices to send to the remote system. + For example, "Some ["sda"; "sdb"]". + + "root_filesystem" + Set this to the name of the root filesystem. + + For a disk partition (eg. "/dev/sda1"), use: + + Some (Part ("sda", "1")) + + For a logical volume (eg. "/dev/VolGroup00/LogVol00"), use: + + Some (LV ("VolGroup00", "LogVol00")) + + "network" + Set this to the choice for network setup. Use either "Some Auto" or + "Some Shell" for auto-configuration or shell (manual) configuration + respectively. + + "hypervisor" + Set this to the choice of hypervisor or virtualization system. The + choices are: "Some Xen", "Some QEMU" or "Some KVM". + + "architecture" + Set this to the architecture. The choices are: "Some I386" (i386 and + up, 32 bit), "Some X86_64" (AMD and Intel x86-64, 64 bit), "Some + IA64" (Intel IA64), "Some PPC" (PowerPC, 32 bit), "Some PPC64" + (PowerPC, 64 bit), "Some SPARC" (Sun SPARC, 32 bit), "Some SPARC64" + (Sun SPARC, 64 bit), "OtherArch "foo"" (a hypothetical architecture + called *foo*), or "UnknownArch" to auto-detect the architecture. + + "memory" + Set this to the size of memory in megabytes, eg. "Some 256". If you + set this to "Some 0" then virt-p2v will try to autodetect the amount + of RAM installed on the physical machine. + + "vcpus" + Set this to the number of virtual CPUs, eg. "Some 1". If you set + this to "Some 0" then virt-p2v will try to autodetect the number of + CPU cores on the physical machine. + + "mac_address" + Set this to the MAC address for the virtual network card, eg. "Some + "aa:bb:cc:dd:ee:ff"". If you set this to "Some """ then virt-p2v + will choose a random MAC address within the "00:16:3e:.." space + reserved for Xen guests. These MAC addresses are not tested for + uniqueness so there is a very small chance that they could coincide, + which would leave a guest unable to access the virtual network. + + ISO ATTACHMENTS + Rebuilding a custom ISO is time-consuming. You can make a "quick" + developer ISO by updating an existing ISO image with a new custom + "virt-p2v" script. This is useful for testing purposes. + + From the source directory, assuming that you have downloaded or built an + existing "virt-p2v-*.iso", you can just do: + + make update + + or the equivalent manual command: + + ./iso-attach virt-p2v-VERSION.iso virt-p2v + +BOOTING FROM A USB KEY INSTEAD OF A CD + If you wish to boot from a USB keydrive, use the livecd-iso-to-disk + tool: + + livecd-iso-to-disk virt-p2v-$VERSION.iso /dev/sdX1 + + (Replace /dev/sdX1 with the actual USB device). + + In my experience I also had to set up a suitable MBR: + + cat /usr/lib/syslinux/mbr.bin > /dev/sdX + +TESTING AN ISO UNDER QEMU OR KVM + If you have a virtual guest running under QEMU or KVM then you can test + the P2V conversion process on the guest. + + (Technically this is a V2V -- virtual to virtual -- conversion). + + From the source directory do: + + make boot HDA=qemuimage.img + + where "qemuimage.img" is the name of the QEMU/KVM image. + + You can also supply an "HDB" parameter to specify a second disk. + +SEE ALSO + virsh(1), , , + , + +AUTHORS + Richard W.M. Jones + +COPYRIGHT + (C) Copyright 2007-2008 Red Hat Inc., Richard W.M. Jones + http://libvirt.org/ + + This program is free software; you can redistribute it and/or modify it + under the terms of the GNU General Public License as published by the + Free Software Foundation; either version 2 of the License, or (at your + option) any later version. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General + Public License for more details. + + You should have received a copy of the GNU General Public License along + with this program; if not, write to the Free Software Foundation, Inc., + 675 Mass Ave, Cambridge, MA 02139, USA. + +REPORTING BUGS + Bugs can be viewed on the Red Hat Bugzilla page: + . + + If you find a bug in virt-p2v, please follow these steps to report it: + + 1. Check for existing bug reports + Go to and search for similar bugs. + Someone may already have reported the same bug, and they may even + have fixed it. + + 2. Capture debug and error messages + At the point where you get the error or unexpected behaviour, go to + the second virtual console (*ALT* *F2*) and look at the logfile + "/tmp/virt-p2v.log". Please make sure that this file is attached to + your bug report. + + 3. Get version of virt-p2v + The version is in the name of the ISO. If you have built a custom + virt-p2v ISO, please describe any changes that you have made. + + 4. Submit a bug report. + Go to and enter a new bug. Please + describe the problem in as much detail as possible. + + Remember to include the version number (step 3) and to attach the + log file (step 2). + + 5. Assign the bug to rjones @ redhat.com + Assign or reassign the bug to rjones @ redhat.com (without the + spaces). You can also send me an email with the bug number if you + want a faster response. + diff --git a/virt-p2v.pod b/virt-p2v.pod new file mode 100644 index 0000000..5d82b38 --- /dev/null +++ b/virt-p2v.pod @@ -0,0 +1,519 @@ +=head1 NAME + +virt-p2v - P2V (physical to virtual machine) migration tool + +=head1 SUMMARY + +virt-p2v + +=head1 DESCRIPTION + +virt-p2v is a live CD for migrating physical machines to virtual +machine guests. + +In the simplest mode of operation, you take a pre-built live CD ISO +from the main website (L) and +burn it to a CD-R. Then insert the CD-R into the physical machine +which must be migrated, reboot, and follow the on-screen instructions. +See B section below. + +You may also build a customized live CD. Typically this will contain +things like server details specific to your organization, so that the +live CD can run mostly or completely automatically. See B section below. + +In both cases, files and disk images are transferred from the physical +machine over the network to the virtualization host machine over ssh. +Therefore C must be running on the virtualization host, and must +be accessible to that host. See B section below. + +The C script must only be run from the live CD. It isn't +designed to run outside this environment and could do Bad Things to +your machine if you try it. The script contains some checks to try to +stop you from doing this. + +Virt-p2v does not modify the physical machine, its disks, +configuration etc. + +=head1 STANDARD USAGE + +After booting the live CD-R, you are presented with a series of +questions. This section explains each question. + +=over 4 + +=item Remote host + +Enter the name or IP address of the virtualization host. This is the +host running Xen (or any other virtualization system supported by +libvirt, eg. QEMU). This host should be accessible on the network and +running an SSH daemon (C). + +=item Remote port + +This is the port name or number of the SSH server on the remote host. +The default is C<22> which is the standard SSH port. + +=item Remote directory + +Enter the directory on the remote host where disk image(s) and +configuration file(s) must reside. + +Note that if the remote host is running SELinux then you may not be +able to start a Xen guest unless its disk image(s) are located in the +default directory, C. + +=item Remote username + +Enter the remote SSH username to use to log in to the remote host. + +If you use the default username of C then you should ensure that +remote root logins are enabled on the remote host +(ie. C in C). + +=item Network configuration + +Choose the way that the live CD configures network access. The +current options are: + +=over 4 + +=item Automatic configuration + +In this mode, the live CD attempts to reuse the network configuration +from the physical machine's root filesystem. You should probably try +this method even though occasionally it does not work. + +=item Configure from the shell + +In this mode you will be dropped into a command shell and you will +need to issue the correct sequence of C commands in +order to configure the network interface. + +A typical sequence of commands which should bring up the network +interface would be: + + /sbin/ifconfig eth0 AA.BB.CC.DD + /sbin/route add default gw GG.HH.II.JJ eth0 + +where C is the IP address and C is the +gateway. + +=back + +=item Devices + +This question lists out all local block devices (hard disk drives and +similar) and asks you to choose which will be sent to the remote host. +You must send at least one block device. + +=item Root device + +This question lists out possible root filesystems and asks you to +choose the right one. Choose the filesystem which would normally be +mounted as C on the system. + +Virt-p2v performs some autodetection and is in most cases able to work +out which filesystems are possible root filesystems. It displays what +it thinks is on each filesystem, but leaves it up to the user to make +a final decision. + +The root filesystem is critical because it contains C. +This is used during P2V both to determine how other filesystems are +normally mounted on the machine, and because this file and others +under C may need to be modified during P2V conversion. + +If the machine has more than one root filesystem (typically because +the machine is dual-booted with another operating system), then you +must choose only one of them to perform the P2V conversion on. + +=item Hypervisor + +This question asks you to choose the hypervisor / virtualization +system in use on the remote host. + +If you select I, I or I then virt-p2v will produce a +configuration file which is customized for the selected system. If +you select I then virt-p2v will produce a generic configuration +file which will probably require hand-modification to work. + +See also L. + +=item Machine architecture + +This question asks you to choose the machine architecture. Virt-p2v +can normally detect this, so you should leave it as I. + +=item Memory + +This question asks you to choose the amount of memory (RAM) in +megabytes assigned to the virtual machine. + +If the entry is left blank, then virt-p2v will try to autodetect how +much RAM is present in the physical machine and use that, and this is +probably a good choice for most simple migrations. + +=item Virtual CPUs + +This question asks you to choose the number of virtual CPUs assigned +to the virtual machine. Choosing C<1> causes the virtual machine to +be uniprocessor, and choosing some number greater than 1 causes the +virtual machine to be SMP. + +If the entry is left blank, then virt-p2v will try to autodetect how +many CPU cores are present in the physical machine and use that, and +this is probably a good choice for most simple migrations. + +=item MAC address + +Here you should enter a MAC address for the virtual machine's emulated +network card. MAC addresses are written as C where +C, C etc are hexadecimal octets. + +Leaving it blank will cause virt-p2v to choose a random MAC address +within the C<00:16:3e:..> space reserved for Xen guests. These MAC +addresses are not tested for uniqueness so there is a very small +chance that they could coincide, which would leave a guest unable to +access the virtual network. + +=item Verify and proceed + +In this step you are asked to verify the settings above. If any are +incorrect, use the I button to navigate back to the setting. If +all settings are correct, use the I button to begin the P2V +conversion. + +=item Network autoconfiguration + +If you selected network autoconfiguration above then virt-p2v tries to +autoconfigure the network and ping the remote host. It then asks +I + +You should answer C here if it worked. + +Answering C will drop you into a command shell. + +You can also switch to another virtual console if you need to perform +additional tests. See section B below. + +=item SSH connection + +Unless you have set up an SSH key, or the SSH server on the remote +host allows passwordless logins, then for each file that has to be +transferred to the remote host you will need to confirm the identity +of the remote host and/or enter a password. + +To understand more about this, please see the L manual page. + +=back + +=head2 BOOTING P2V GUEST ON VIRTUALIZATION HOST + +Once the P2V conversion has been completed, and assuming it was +successful, you will find a configuration file and one or more disk +images on the remote host. + +The files will be located in the directory selected, usually +C. The names of the files are made up of: + +C-I.conf> or +C-I-hdI.img> + +To simply start up the guest, use the following commands as root: + + virsh define p2v-foo-2008MMDDHHMM.conf + virsh start foo + +For QEMU/KVM do: + + virsh -c qemu:///system define p2v-foo-2008MMDDHHMM.conf + virsh -c qemu:///system start foo + +For other hypervisors you will need to edit the configuration file and +read L. + +=head1 GETTING A SHELL + +During all stages of P2V questions and conversion you can get a root +shell on the physical machine. Use I I keys to switch to the +second virtual console, then log in as I with no password. + +=head2 LOG FILE + +Virt-p2v writes a detailed log file to C. (Note +that this C directory is a ramdisk on the live CD, not the same +as the C directory of the physical machine, and more importantly +it disappears when the machine is rebooted). + +If you are reporting a bug, please always supply this file. + +=head1 SERVER REQUIREMENTS + +The virtualization host (remote host) must be running an SSH daemon +(C), accessible from the physical machine which is being +migrated. + +Previous versions of virt-p2v could use a special virt-p2v server. +However this capability has been removed since there was practically +no benefit. + +=head1 BUILDING A CUSTOM LIVE CD + +To build a custom live CD you must download the source for virt-p2v +from L or from the Mercurial +source repository (see website for details). + +Please read the C file to find the dependencies which are all +in Fedora > 8 or EPEL > 5. + +The steps to creating a custom live CD are: + +=over 4 + +=item 1. Edit C and adjust defaults + +Find the section "TO MAKE A CUSTOM virt-p2v SCRIPT ..." which is near +to the top of this file. Edit the defaults in this section as +detailed below. + +=item 2. C to verify your changes + +This command should not print anything at all. If it prints any +message, then you will need to fix the error by going back to the +first step. + +=item 3. C or C to build a custom live CD + +C will create a complete ISO from scratch. C +can be used to build a "quick" developer ISO by updating an existing +ISO image. See section B below for more details. + +=item 4. Burn the ISO to a CD-R and test + +=back + +=head2 EDITING DEFAULTS IN THE C SCRIPT + +For each default, setting it to C will ask the user. All of the +defaults are set to C in the standard, uncustomized virt-p2v +script, and so the standard script asks all the questions. + +You may edit C and change the defaults, in which case the +user will not be questioned. In this way you can make the script +partially or fully automated. + +I C and C are similar to the +concept of a NULL pointer versus non-NULL pointer in other languages. +This a variant type defined as: + +type E<945> option = None | Some of E<945> + +=over 4 + +=item C + +If this is C then we wait for a keypress after boot and at a +couple of other stages. If set to C then we try not to wait +for any keypresses (so more automated live CDs are possible). + +=item C + +Set this to C or C to +provide the name of the remote host. + +=item C + +Set this to C (eg. C) to provide the port number +of the remote host's SSH daemon. + +=item C + +Set this to C (eg. C) to +provide the directory where we update P2V converted images and +configuration files. + +=item C + +Set this to C (eg. C) to provide the SSH +username to use on the remote system. + +=item C + +Set this to a list of block devices to send to the remote system. +For example, C. + +=item C + +Set this to the name of the root filesystem. + +For a disk partition (eg. C), use: + + Some (Part ("sda", "1")) + +For a logical volume (eg. C), use: + + Some (LV ("VolGroup00", "LogVol00")) + +=item C + +Set this to the choice for network setup. Use either C or +C for auto-configuration or shell (manual) configuration +respectively. + +=item C + +Set this to the choice of hypervisor or virtualization system. The +choices are: C, C or C. + +=item C + +Set this to the architecture. The choices are: +C (i386 and up, 32 bit), +C (AMD and Intel x86-64, 64 bit), +C (Intel IA64), +C (PowerPC, 32 bit), +C (PowerPC, 64 bit), +C (Sun SPARC, 32 bit), +C (Sun SPARC, 64 bit), +C (a hypothetical architecture called I), or +C to auto-detect the architecture. + +=item C + +Set this to the size of memory in megabytes, eg. C. If you +set this to C then virt-p2v will try to autodetect the amount +of RAM installed on the physical machine. + +=item C + +Set this to the number of virtual CPUs, eg. C. If you set +this to C then virt-p2v will try to autodetect the number of +CPU cores on the physical machine. + +=item C + +Set this to the MAC address for the virtual network card, eg. C. If you set this to C then virt-p2v +will choose a random MAC address within the C<00:16:3e:..> space +reserved for Xen guests. These MAC addresses are not tested for +uniqueness so there is a very small chance that they could coincide, +which would leave a guest unable to access the virtual network. + +=back + +=head2 ISO ATTACHMENTS + +Rebuilding a custom ISO is time-consuming. You can make a "quick" +developer ISO by updating an existing ISO image with a new custom +C script. This is useful for testing purposes. + +From the source directory, assuming that you have downloaded or +built an existing C, you can just do: + + make update + +or the equivalent manual command: + + ./iso-attach virt-p2v-VERSION.iso virt-p2v + +=head1 BOOTING FROM A USB KEY INSTEAD OF A CD + +If you wish to boot from a USB keydrive, use the livecd-iso-to-disk +tool: + + livecd-iso-to-disk virt-p2v-$VERSION.iso /dev/sdX1 + +(Replace /dev/sdX1 with the actual USB device). + +In my experience I also had to set up a suitable MBR: + + cat /usr/lib/syslinux/mbr.bin > /dev/sdX + +=head1 TESTING AN ISO UNDER QEMU OR KVM + +If you have a virtual guest running under QEMU or KVM then +you can test the P2V conversion process on the guest. + +(Technically this is a V2V -- virtual to virtual -- conversion). + +From the source directory do: + + make boot HDA=qemuimage.img + +where C is the name of the QEMU/KVM image. + +You can also supply an C parameter to specify a second disk. + +=head1 SEE ALSO + +L, +L, +L, +L, +L + +=head1 AUTHORS + +Richard W.M. Jones + +=head1 COPYRIGHT + +(C) Copyright 2007-2008 Red Hat Inc., Richard W.M. Jones +http://libvirt.org/ + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +=head1 REPORTING BUGS + +Bugs can be viewed on the Red Hat Bugzilla page: +L. + +If you find a bug in virt-p2v, please follow these steps to report it: + +=over 4 + +=item 1. Check for existing bug reports + +Go to L and search for similar bugs. +Someone may already have reported the same bug, and they may even +have fixed it. + +=item 2. Capture debug and error messages + +At the point where you get the error or unexpected behaviour, +go to the second virtual console (I I) and look at +the logfile C. Please make sure that +this file is attached to your bug report. + +=item 3. Get version of virt-p2v + +The version is in the name of the ISO. If you have built a custom +virt-p2v ISO, please describe any changes that you have made. + +=item 4. Submit a bug report. + +Go to L and enter a new bug. +Please describe the problem in as much detail as possible. + +Remember to include the version number (step 3) and to +attach the log file (step 2). + +=item 5. Assign the bug to rjones @ redhat.com + +Assign or reassign the bug to B (without the +spaces). You can also send me an email with the bug number if you +want a faster response. + +=back -- 1.8.3.1