virt-p2v.1

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "VIRT-P2V 1"
 132 .TH VIRT-P2V 1 "2008-02-12" "virt-p2v-0.9.6" "Virtualization Support"
 133 .SH "NAME"
 134 virt\-p2v \- P2V (physical to virtual machine) migration tool
 135 .SH "SUMMARY"
 136 .IX Header "SUMMARY"
 137 virt\-p2v
 138 .SH "DESCRIPTION"
 139 .IX Header "DESCRIPTION"
 140 virt\-p2v is a live \s-1CD\s0 for migrating physical machines to virtual
 141 machine guests.
 142 .PP
 143 In the simplest mode of operation, you take a pre-built live \s-1CD\s0 \s-1ISO\s0
 144 from the main website (<http://et.redhat.com/~rjones/virt\-p2v/>) and
 145 burn it to a \s-1CD\-R\s0.  Then insert the CD-R into the physical machine
 146 which must be migrated, reboot, and follow the on-screen instructions.
 147 See \fB\s-1STANDARD\s0 \s-1USAGE\s0\fR section below.
 148 .PP
 149 You may also build a customized live \s-1CD\s0.  Typically this will contain
 150 things like server details specific to your organization, so that the
 151 live \s-1CD\s0 can run mostly or completely automatically.  See \fB\s-1BUILDING\s0 A
 152 \&\s-1CUSTOM\s0 \s-1LIVE\s0 \s-1CD\s0\fR section below.
 153 .PP
 154 In both cases, files and disk images are transferred from the physical
 155 machine over the network to the virtualization host machine over ssh.
 156 Therefore \f(CW\*(C`sshd\*(C'\fR must be running on the virtualization host, and must
 157 be accessible to that host.  See \fB\s-1SERVER\s0 \s-1REQUIREMENTS\s0\fR section below.
 158 .PP
 159 The \f(CW\*(C`virt\-p2v\*(C'\fR script must only be run from the live \s-1CD\s0 environment.
 160 It isn't designed to run outside this environment and could do Bad
 161 Things to your machine if you try it.  The script contains some checks
 162 to try to stop you from doing this.
 163 .PP
 164 Virt\-p2v does not modify the physical machine, its disks,
 165 configuration etc.
 166 .PP
 167 \&\s-1USB\s0 key and \s-1PXE\s0 boot options are also available.  See sections
 168 \&\fB\s-1PXE\s0 \s-1BOOTING\s0\fR and \fB\s-1BOOTING\s0 \s-1FROM\s0 A \s-1USB\s0 \s-1KEY\s0\fR
 169 below.
 170 .SH "STANDARD USAGE"
 171 .IX Header "STANDARD USAGE"
 172 After booting the live \s-1CD\-R\s0, you are presented with a series of
 173 questions.  This section explains each question.
 174 .IP "Remote host" 4
 175 .IX Item "Remote host"
 176 Enter the name or \s-1IP\s0 address of the virtualization host.  This is the
 177 host running Xen (or any other virtualization system supported by
 178 libvirt, eg. \s-1QEMU\s0).  This host should be accessible on the network and
 179 running an \s-1SSH\s0 daemon (\f(CW\*(C`sshd\*(C'\fR).
 180 .IP "Remote port" 4
 181 .IX Item "Remote port"
 182 This is the port name or number of the \s-1SSH\s0 server on the remote host.
 183 The default is \f(CW22\fR which is the standard \s-1SSH\s0 port.
 184 .IP "Remote directory" 4
 185 .IX Item "Remote directory"
 186 Enter the directory on the remote host where disk image(s) and
 187 configuration file(s) must reside.
 188 .Sp
 189 Note that if the remote host is running SELinux then you may not be
 190 able to start a Xen guest unless its disk image(s) are located in the
 191 default directory, \f(CW\*(C`/var/lib/xen/images\*(C'\fR.
 192 .IP "Remote username" 4
 193 .IX Item "Remote username"
 194 Enter the remote \s-1SSH\s0 username to use to log in to the remote host.
 195 .Sp
 196 If you use the default username of \f(CW\*(C`root\*(C'\fR then you should ensure that
 197 remote root logins are enabled on the remote host
 198 (ie. \f(CW\*(C`PermitRootLogin yes\*(C'\fR in \f(CW\*(C`/etc/ssh/sshd_config\*(C'\fR).
 199 .IP "Network configuration" 4
 200 .IX Item "Network configuration"
 201 Choose the way that the live \s-1CD\s0 configures network access.  The
 202 current options are:
 203 .RS 4
 204 .IP "Automatic configuration" 4
 205 .IX Item "Automatic configuration"
 206 In this mode, the live \s-1CD\s0 attempts to reuse the network configuration
 207 from the physical machine's root filesystem.  You should probably try
 208 this method even though occasionally it does not work.
 209 .IP "Ask for fixed \s-1IP\s0 address and gateway" 4
 210 .IX Item "Ask for fixed IP address and gateway"
 211 In this mode the live \s-1CD\s0 will ask you for a fixed \s-1IP\s0 address and
 212 gateway address, and will configure your chosen interface with these.
 213 .IP "Configure from the shell" 4
 214 .IX Item "Configure from the shell"
 215 In this mode you will be dropped into a command shell and you will
 216 need to issue the correct sequence of \f(CW\*(C`/sbin/ifconfig\*(C'\fR commands in
 217 order to configure the network interface.
 218 .Sp
 219 A typical sequence of commands which should bring up the network
 220 interface would be:
 221 .Sp
 222 .Vb 2
 223 \& /sbin/ifconfig eth0 AA.BB.CC.DD
 224 \& /sbin/route add default gw GG.HH.II.JJ eth0
 225 .Ve
 226 .Sp
 227 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
 228 gateway.
 229 .IP "\s-1QEMU\s0 user network" 4
 230 .IX Item "QEMU user network"
 231 This option configures the network for use inside a \s-1QEMU\s0 user network
 232 (<http://fabrice.bellard.free.fr/qemu/qemu\-doc.html#SEC30>).  It
 233 should only be used by developers.
 234 .RE
 235 .RS 4
 236 .RE
 237 .IP "Devices" 4
 238 .IX Item "Devices"
 239 This question lists out all local block devices (hard disk drives and
 240 similar) and asks you to choose which will be sent to the remote host.
 241 You must send at least one block device.
 242 .IP "Root device" 4
 243 .IX Item "Root device"
 244 This question lists out possible root filesystems and asks you to
 245 choose the right one.  Choose the filesystem which would normally be
 246 mounted as \f(CW\*(C`/\*(C'\fR on the system.
 247 .Sp
 248 Virt\-p2v performs some autodetection and is in most cases able to work
 249 out which filesystems are possible root filesystems.  It displays what
 250 it thinks is on each filesystem, but leaves it up to the user to make
 251 a final decision.
 252 .Sp
 253 The root filesystem is critical because it contains \f(CW\*(C`/etc/fstab\*(C'\fR.
 254 This is used during P2V both to determine how other filesystems are
 255 normally mounted on the machine, and because this file and others
 256 under \f(CW\*(C`/etc\*(C'\fR may need to be modified during P2V conversion.
 257 .Sp
 258 If the machine has more than one root filesystem (typically because
 259 the machine is dual-booted with another operating system), then you
 260 must choose only one of them to perform the P2V conversion on.
 261 .IP "Hypervisor" 4
 262 .IX Item "Hypervisor"
 263 This question asks you to choose the hypervisor / virtualization
 264 system in use on the remote host.
 265 .Sp
 266 If you select \fIXen\fR, \fI\s-1QEMU\s0\fR or \fI\s-1KVM\s0\fR then virt\-p2v will produce a
 267 configuration file which is customized for the selected system.  If
 268 you select \fIOther\fR then virt\-p2v will produce a generic configuration
 269 file which will probably require hand-modification to work.
 270 .Sp
 271 See also <http://libvirt.org/format.html>.
 272 .IP "Machine architecture" 4
 273 .IX Item "Machine architecture"
 274 This question asks you to choose the machine architecture.  Virt\-p2v
 275 can normally detect this, so you should leave it as \fIAuto-detect\fR.
 276 .IP "Memory" 4
 277 .IX Item "Memory"
 278 This question asks you to choose the amount of memory (\s-1RAM\s0) in
 279 megabytes assigned to the virtual machine.
 280 .Sp
 281 If the entry is left blank, then virt\-p2v will try to autodetect how
 282 much \s-1RAM\s0 is present in the physical machine and use that, and this is
 283 probably a good choice for most simple migrations.
 284 .IP "Virtual CPUs" 4
 285 .IX Item "Virtual CPUs"
 286 This question asks you to choose the number of virtual CPUs assigned
 287 to the virtual machine.  Choosing \f(CW1\fR causes the virtual machine to
 288 be uniprocessor, and choosing some number greater than 1 causes the
 289 virtual machine to be \s-1SMP\s0.
 290 .Sp
 291 If the entry is left blank, then virt\-p2v will try to autodetect how
 292 many \s-1CPU\s0 cores are present in the physical machine and use that, and
 293 this is probably a good choice for most simple migrations.
 294 .IP "\s-1MAC\s0 address" 4
 295 .IX Item "MAC address"
 296 Here you should enter a \s-1MAC\s0 address for the virtual machine's emulated
 297 network card.  \s-1MAC\s0 addresses are written as \f(CW\*(C`aa:bb:cc:dd:ee:ff\*(C'\fR where
 298 \&\f(CW\*(C`aa\*(C'\fR, \f(CW\*(C`bb\*(C'\fR etc are hexadecimal octets.
 299 .Sp
 300 Leaving it blank will cause virt\-p2v to choose a random \s-1MAC\s0 address
 301 within the \f(CW\*(C`00:16:3e:..\*(C'\fR space reserved for Xen guests.  These \s-1MAC\s0
 302 addresses are not tested for uniqueness so there is a very small
 303 chance that they could coincide, which would leave a guest unable to
 304 access the virtual network.
 305 .IP "Compression" 4
 306 .IX Item "Compression"
 307 Choose whether to enable or disable compression on disk images as they
 308 are copied across the network.
 309 .Sp
 310 If enabled, the \f(CW\*(C`\-C\*(C'\fR option is passed to \fIssh\fR\|(1).  On fast networks
 311 this can sometimes be slower.
 312 .Sp
 313 \&\s-1NB:\s0 The disk image is still stored uncompressed on the remote host
 314 however this option is set.
 315 .IP "Verify and proceed" 4
 316 .IX Item "Verify and proceed"
 317 In this step you are asked to verify the settings above.  If any are
 318 incorrect, use the \fIBack\fR button to navigate back to the setting.  If
 319 all settings are correct, use the \fI\s-1OK\s0\fR button to begin the P2V
 320 conversion.
 321 .IP "Network autoconfiguration" 4
 322 .IX Item "Network autoconfiguration"
 323 If you selected network autoconfiguration above then virt\-p2v tries to
 324 autoconfigure the network and ping the remote host.  It then asks
 325 \&\fIDid automatic network configuration work?\fR
 326 .Sp
 327 You should answer \f(CW\*(C`y\*(C'\fR here if it worked.
 328 .Sp
 329 Answering \f(CW\*(C`n\*(C'\fR will drop you into a command shell.
 330 .Sp
 331 You can also switch to another virtual console if you need to perform
 332 additional tests.  See section \fB\s-1GETTING\s0 A \s-1SHELL\s0\fR below.
 333 .IP "\s-1SSH\s0 connection" 4
 334 .IX Item "SSH connection"
 335 Unless you have set up an \s-1SSH\s0 key, or the \s-1SSH\s0 server on the remote
 336 host allows passwordless logins, then for each file that has to be
 337 transferred to the remote host you will need to confirm the identity
 338 of the remote host and/or enter a password.
 339 .Sp
 340 To understand more about this, please see the \fIssh\fR\|(1) manual page.
 341 .Sh "\s-1BOOTING\s0 P2V \s-1GUEST\s0 \s-1ON\s0 \s-1VIRTUALIZATION\s0 \s-1HOST\s0"
 342 .IX Subsection "BOOTING P2V GUEST ON VIRTUALIZATION HOST"
 343 Once the P2V conversion has been completed, and assuming it was
 344 successful, you will find a configuration file and one or more disk
 345 images on the remote host.
 346 .PP
 347 The files will be located in the directory selected, usually
 348 \&\f(CW\*(C`/var/lib/xen/images\*(C'\fR.  The names of the files are made up of:
 349 .PP
 350 \&\f(CW\*(C`p2v\-\f(CIhostname\f(CW\-\f(CI\s-1YYYYMMDDHHMM\s0\f(CW.conf\*(C'\fR or
 351 \&\f(CW\*(C`p2v\-\f(CIhostname\f(CW\-\f(CI\s-1YYYYMMDDHHMM\s0\f(CW\-hd\f(CIX\f(CW.img\*(C'\fR
 352 .PP
 353 To simply start up the guest, use the following commands as root:
 354 .PP
 355 .Vb 2
 356 \& virsh define p2v-foo-2008MMDDHHMM.conf
 357 \& virsh start foo
 358 .Ve
 359 .PP
 360 For \s-1QEMU/KVM\s0 do:
 361 .PP
 362 .Vb 2
 363 \& virsh -c qemu:///system define p2v-foo-2008MMDDHHMM.conf
 364 \& virsh -c qemu:///system start foo
 365 .Ve
 366 .PP
 367 For other hypervisors you will need to edit the configuration file and
 368 read <http://libvirt.org/uri.html>.
 369 .SH "GETTING A SHELL"
 370 .IX Header "GETTING A SHELL"
 371 During all stages of P2V questions and conversion you can get a root
 372 shell on the physical machine.  Use \fI\s-1ALT\s0\fR \fIF2\fR keys to switch to the
 373 second virtual console, then log in as \fIroot\fR with no password.
 374 .Sh "\s-1LOG\s0 \s-1FILE\s0"
 375 .IX Subsection "LOG FILE"
 376 Virt\-p2v writes a detailed log file to \f(CW\*(C`/tmp/virt\-p2v.log\*(C'\fR.  (Note
 377 that this \f(CW\*(C`/tmp\*(C'\fR directory is a ramdisk on the live \s-1CD\s0, not the same
 378 as the \f(CW\*(C`/tmp\*(C'\fR directory of the physical machine, and more importantly
 379 it disappears when the machine is rebooted).
 380 .PP
 381 If you are reporting a bug, please always supply this file.
 382 .SH "SERVER REQUIREMENTS"
 383 .IX Header "SERVER REQUIREMENTS"
 384 The virtualization host (remote host) must be running an \s-1SSH\s0 daemon
 385 (\f(CW\*(C`sshd\*(C'\fR), accessible from the physical machine which is being
 386 migrated.
 387 .PP
 388 Previous versions of virt\-p2v could use a special virt\-p2v server.
 389 However this capability has been removed since there was practically
 390 no benefit.
 391 .SH "BUILDING A CUSTOM LIVE CD"
 392 .IX Header "BUILDING A CUSTOM LIVE CD"
 393 To build a custom live \s-1CD\s0 you must download the source for virt\-p2v
 394 from <http://et.redhat.com/~rjones/virt\-p2v/> or from the Mercurial
 395 source repository (see website for details).
 396 .PP
 397 Please read the \f(CW\*(C`README\*(C'\fR file to find the dependencies which are all
 398 in Fedora &gt; 8 or \s-1EPEL\s0 &gt; 5.
 399 .PP
 400 The steps to creating a custom live \s-1CD\s0 are:
 401 .ie n .IP "1. Edit ""virt\-p2v"" and adjust defaults" 4
 402 .el .IP "1. Edit \f(CWvirt\-p2v\fR and adjust defaults" 4
 403 .IX Item "1. Edit virt-p2v and adjust defaults"
 404 Find the section \*(L"\s-1TO\s0 \s-1MAKE\s0 A \s-1CUSTOM\s0 virt\-p2v \s-1SCRIPT\s0 ...\*(R" which is near
 405 to the top of this file.  Edit the defaults in this section as
 406 detailed below.
 407 .ie n .IP "2. ""virt\-p2v \-\-test"" to verify your changes" 4
 408 .el .IP "2. \f(CWvirt\-p2v \-\-test\fR to verify your changes" 4
 409 .IX Item "2. virt-p2v --test to verify your changes"
 410 This command should not print anything at all.  If it prints any
 411 message, then you will need to fix the error by going back to the
 412 first step.
 413 .ie n .IP "3. ""make build""\fR or \f(CW""make update"" to build a custom live \s-1CD\s0" 4
 414 .el .IP "3. \f(CWmake build\fR or \f(CWmake update\fR to build a custom live \s-1CD\s0" 4
 415 .IX Item "3. make build or make update to build a custom live CD"
 416 \&\f(CW\*(C`make build\*(C'\fR will create a complete \s-1ISO\s0 from scratch.  \f(CW\*(C`make update\*(C'\fR
 417 can be used to build a \*(L"quick\*(R" developer \s-1ISO\s0 by updating an existing
 418 \&\s-1ISO\s0 image.  See section \fB\s-1ISO\s0 \s-1ATTACHMENTS\s0\fR below for more details.
 419 .IP "4. Burn the \s-1ISO\s0 to a CD-R and test" 4
 420 .IX Item "4. Burn the ISO to a CD-R and test"
 421 .ie n .Sh "\s-1EDITING\s0 \s-1DEFAULTS\s0 \s-1IN\s0 \s-1THE\s0 ""virt\-p2v"" \s-1SCRIPT\s0"
 422 .el .Sh "\s-1EDITING\s0 \s-1DEFAULTS\s0 \s-1IN\s0 \s-1THE\s0 \f(CWvirt\-p2v\fP \s-1SCRIPT\s0"
 423 .IX Subsection "EDITING DEFAULTS IN THE virt-p2v SCRIPT"
 424 For each default, setting it to \f(CW\*(C`None\*(C'\fR will ask the user.  All of the
 425 defaults are set to \f(CW\*(C`None\*(C'\fR in the standard, uncustomized virt\-p2v
 426 script, and so the standard script asks all the questions.
 427 .PP
 428 You may edit \f(CW\*(C`virt\-p2v\*(C'\fR and change the defaults, in which case the
 429 user will not be questioned.  In this way you can make the script
 430 partially or fully automated.
 431 .PP
 432 \&\fINote about OCaml code:\fR  \f(CW\*(C`None\*(C'\fR and \f(CW\*(C`Some foo\*(C'\fR are similar to the
 433 concept of a \s-1NULL\s0 pointer versus non-NULL pointer in other languages.
 434 This a variant type defined as:
 435 .PP
 436 type α option = None | Some of α
 437 .ie n .IP """greeting""" 4
 438 .el .IP "\f(CWgreeting\fR" 4
 439 .IX Item "greeting"
 440 If this is \f(CW\*(C`true\*(C'\fR then we wait for a keypress after boot and at a
 441 couple of other stages.  If set to \f(CW\*(C`false\*(C'\fR then we try not to wait
 442 for any keypresses (so more automated live CDs are possible).
 443 .ie n .IP """remote_host""" 4
 444 .el .IP "\f(CWremote_host\fR" 4
 445 .IX Item "remote_host"
 446 Set this to \f(CW\*(C`Some "hostname"\*(C'\fR or \f(CW\*(C`Some "IP\-address"\*(C'\fR to
 447 provide the name of the remote host.
 448 .ie n .IP """remote_port""" 4
 449 .el .IP "\f(CWremote_port\fR" 4
 450 .IX Item "remote_port"
 451 Set this to \f(CW\*(C`Some port\*(C'\fR (eg. \f(CW\*(C`Some 22\*(C'\fR) to provide the port number
 452 of the remote host's \s-1SSH\s0 daemon.
 453 .ie n .IP """remote_directory""" 4
 454 .el .IP "\f(CWremote_directory\fR" 4
 455 .IX Item "remote_directory"
 456 Set this to \f(CW\*(C`Some "path"\*(C'\fR (eg. \f(CW\*(C`Some "/var/lib/xen/images"\*(C'\fR) to
 457 provide the directory where we update P2V converted images and
 458 configuration files.
 459 .ie n .IP """remote_username""" 4
 460 .el .IP "\f(CWremote_username\fR" 4
 461 .IX Item "remote_username"
 462 Set this to \f(CW\*(C`Some "username"\*(C'\fR (eg. \f(CW\*(C`Some "root"\*(C'\fR) to provide the \s-1SSH\s0
 463 username to use on the remote system.
 464 .ie n .IP """devices_to_send""" 4
 465 .el .IP "\f(CWdevices_to_send\fR" 4
 466 .IX Item "devices_to_send"
 467 Set this to a list of block devices to send to the remote system.
 468 For example, \f(CW\*(C`Some ["sda"; "sdb"]\*(C'\fR.
 469 .ie n .IP """root_filesystem""" 4
 470 .el .IP "\f(CWroot_filesystem\fR" 4
 471 .IX Item "root_filesystem"
 472 Set this to the name of the root filesystem.
 473 .Sp
 474 For a disk partition (eg. \f(CW\*(C`/dev/sda1\*(C'\fR), use:
 475 .Sp
 476 .Vb 1
 477 \& Some (Part ("sda", "1"))
 478 .Ve
 479 .Sp
 480 For a logical volume (eg. \f(CW\*(C`/dev/VolGroup00/LogVol00\*(C'\fR), use:
 481 .Sp
 482 .Vb 1
 483 \& Some (LV ("VolGroup00", "LogVol00"))
 484 .Ve
 485 .ie n .IP """network""" 4
 486 .el .IP "\f(CWnetwork\fR" 4
 487 .IX Item "network"
 488 Set this to the choice for network setup.  Use one of:
 489 .RS 4
 490 .ie n .IP """Some Auto""" 4
 491 .el .IP "\f(CWSome Auto\fR" 4
 492 .IX Item "Some Auto"
 493 for auto-configuration
 494 .ie n .IP """Some Static""" 4
 495 .el .IP "\f(CWSome Static\fR" 4
 496 .IX Item "Some Static"
 497 to specify the interface, address, netmask and gateway statically
 498 .ie n .IP """Some Shell""" 4
 499 .el .IP "\f(CWSome Shell\fR" 4
 500 .IX Item "Some Shell"
 501 to launch a shell
 502 .ie n .IP """Some QEMUUserNet""" 4
 503 .el .IP "\f(CWSome QEMUUserNet\fR" 4
 504 .IX Item "Some QEMUUserNet"
 505 to use a \s-1QEMU\s0 user network (developers only)
 506 .RE
 507 .RS 4
 508 .RE
 509 .ie n .IP """static_network_config""" 4
 510 .el .IP "\f(CWstatic_network_config\fR" 4
 511 .IX Item "static_network_config"
 512 This setting only applies if \f(CW\*(C`network\*(C'\fR is set to \f(CW\*(C`Some Static\*(C'\fR,
 513 in which case you should set this to the static network settings,
 514 a tuple of (interface, address, netmask, gateway, nameserver):
 515 .Sp
 516 .Vb 1
 517 \& Some ("eth0", "192.168.2.5", "255.255.255.0", "192.168.2.1", "192.168.2.1")
 518 .Ve
 519 .ie n .IP """hypervisor""" 4
 520 .el .IP "\f(CWhypervisor\fR" 4
 521 .IX Item "hypervisor"
 522 Set this to the choice of hypervisor or virtualization system.  The
 523 choices are: \f(CW\*(C`Some Xen\*(C'\fR, \f(CW\*(C`Some QEMU\*(C'\fR or \f(CW\*(C`Some KVM\*(C'\fR.
 524 .ie n .IP """architecture""" 4
 525 .el .IP "\f(CWarchitecture\fR" 4
 526 .IX Item "architecture"
 527 Set this to the architecture.  The choices are:
 528 \&\f(CW\*(C`Some I386\*(C'\fR (i386 and up, 32 bit),
 529 \&\f(CW\*(C`Some X86_64\*(C'\fR (\s-1AMD\s0 and Intel x86\-64, 64 bit),
 530 \&\f(CW\*(C`Some IA64\*(C'\fR (Intel \s-1IA64\s0),
 531 \&\f(CW\*(C`Some PPC\*(C'\fR (PowerPC, 32 bit),
 532 \&\f(CW\*(C`Some PPC64\*(C'\fR (PowerPC, 64 bit),
 533 \&\f(CW\*(C`Some SPARC\*(C'\fR (Sun \s-1SPARC\s0, 32 bit),
 534 \&\f(CW\*(C`Some SPARC64\*(C'\fR (Sun \s-1SPARC\s0, 64 bit),
 535 \&\f(CW\*(C`OtherArch "foo"\*(C'\fR (a hypothetical architecture called \fIfoo\fR), or
 536 \&\f(CW\*(C`UnknownArch\*(C'\fR to auto-detect the architecture.
 537 .ie n .IP """memory""" 4
 538 .el .IP "\f(CWmemory\fR" 4
 539 .IX Item "memory"
 540 Set this to the size of memory in megabytes, eg. \f(CW\*(C`Some 256\*(C'\fR.  If you
 541 set this to \f(CW\*(C`Some 0\*(C'\fR then virt\-p2v will try to autodetect the amount
 542 of \s-1RAM\s0 installed on the physical machine.
 543 .ie n .IP """vcpus""" 4
 544 .el .IP "\f(CWvcpus\fR" 4
 545 .IX Item "vcpus"
 546 Set this to the number of virtual CPUs, eg. \f(CW\*(C`Some 1\*(C'\fR.  If you set
 547 this to \f(CW\*(C`Some 0\*(C'\fR then virt\-p2v will try to autodetect the number of
 548 \&\s-1CPU\s0 cores on the physical machine.
 549 .ie n .IP """mac_address""" 4
 550 .el .IP "\f(CWmac_address\fR" 4
 551 .IX Item "mac_address"
 552 Set this to the \s-1MAC\s0 address for the virtual network card, eg. \f(CW\*(C`Some
 553 "aa:bb:cc:dd:ee:ff"\*(C'\fR.  If you set this to \f(CW\*(C`Some ""\*(C'\fR then virt\-p2v
 554 will choose a random \s-1MAC\s0 address within the \f(CW\*(C`00:16:3e:..\*(C'\fR space
 555 reserved for Xen guests.  These \s-1MAC\s0 addresses are not tested for
 556 uniqueness so there is a very small chance that they could coincide,
 557 which would leave a guest unable to access the virtual network.
 558 .ie n .IP """compression""" 4
 559 .el .IP "\f(CWcompression\fR" 4
 560 .IX Item "compression"
 561 Set this to \f(CW\*(C`Some false\*(C'\fR to disable compression, or \f(CW\*(C`Some true\*(C'\fR to
 562 enable compression, or \f(CW\*(C`None\*(C'\fR to ask the user.
 563 .Sh "\s-1ISO\s0 \s-1ATTACHMENTS\s0"
 564 .IX Subsection "ISO ATTACHMENTS"
 565 Rebuilding a custom \s-1ISO\s0 is time\-consuming.  You can make a \*(L"quick\*(R"
 566 developer \s-1ISO\s0 by updating an existing \s-1ISO\s0 image with a new custom
 567 \&\f(CW\*(C`virt\-p2v\*(C'\fR script.  This is useful for testing purposes.
 568 .PP
 569 From the source directory, assuming that you have downloaded or
 570 built an existing \f(CW\*(C`virt\-p2v\-*.iso\*(C'\fR, you can just do:
 571 .PP
 572 .Vb 1
 573 \& make update
 574 .Ve
 575 .PP
 576 or the equivalent manual command:
 577 .PP
 578 .Vb 1
 579 \& ./iso-attach virt-p2v-VERSION.iso virt-p2v
 580 .Ve
 581 .PP
 582 Note that \s-1ISO\s0 attachments only work with real (and emulated) CD\-Rs,
 583 not with other methods of booting such as \s-1USB\s0 keys and \s-1PXE\s0.
 584 .SH "PXE BOOTING"
 585 .IX Header "PXE BOOTING"
 586 If you wish to boot over the network using \s-1PXE\s0, use the
 587 \&\f(CW\*(C`livecd\-iso\-to\-pxeboot\*(C'\fR script (part of \f(CW\*(C`livecd\-tools\*(C'\fR).
 588 .PP
 589 .Vb 1
 590 \& livecd-iso-to-pxeboot virt-p2v-$VERSION.iso
 591 .Ve
 592 .PP
 593 then copy the generated subdirectory \f(CW\*(C`tftpboot/\*(C'\fR to the
 594 right place for your \s-1PXE\s0 configuration.
 595 .PP
 596 Pre-built \s-1PXE\s0 boot images are also available on the website.
 597 .PP
 598 General configuration of \s-1DHCP\s0, \s-1TFTP\s0 and \s-1PXE\s0 for network booting are
 599 outside the scope of this document.
 600 .SH "BOOTING FROM A USB KEY"
 601 .IX Header "BOOTING FROM A USB KEY"
 602 If you wish to boot from a \s-1USB\s0 keydrive, use the \f(CW\*(C`livecd\-iso\-to\-disk\*(C'\fR
 603 script (part of \f(CW\*(C`livecd\-tools\*(C'\fR):
 604 .PP
 605 .Vb 1
 606 \& livecd-iso-to-disk virt-p2v-$VERSION.iso /dev/sdX1
 607 .Ve
 608 .PP
 609 (Replace /dev/sdX1 with the actual \s-1USB\s0 device).
 610 .PP
 611 In my experience I also had to set up a suitable \s-1MBR:\s0
 612 .PP
 613 .Vb 1
 614 \& cat /usr/lib/syslinux/mbr.bin > /dev/sdX
 615 .Ve
 616 .SH "TESTING AN ISO UNDER QEMU OR KVM"
 617 .IX Header "TESTING AN ISO UNDER QEMU OR KVM"
 618 If you have a virtual guest running under \s-1QEMU\s0 or \s-1KVM\s0 then
 619 you can test the P2V conversion process on the guest.
 620 .PP
 621 (Technically this is a V2V \*(-- virtual to virtual \*(-- conversion).
 622 .PP
 623 From the source directory do:
 624 .PP
 625 .Vb 1
 626 \& make boot HDA=qemuimage.img
 627 .Ve
 628 .PP
 629 where \f(CW\*(C`qemuimage.img\*(C'\fR is the name of the \s-1QEMU/KVM\s0 image.
 630 .PP
 631 You can also supply an \f(CW\*(C`HDB\*(C'\fR parameter to specify a second disk.
 632 .SH "MAILING LIST"
 633 .IX Header "MAILING LIST"
 634 Please direct questions to the et-mgmt-tools mailing list
 635 <http://www.redhat.com/mailman/listinfo/et\-mgmt\-tools>
 636 <et\-mgmt\-tools @ redhat . com>
 637 .SH "SEE ALSO"
 638 .IX Header "SEE ALSO"
 639 \&\fIvirsh\fR\|(1),
 640 <http://www.libvirt.org/ocaml/>,
 641 <http://www.libvirt.org/>,
 642 <http://et.redhat.com/~rjones/>,
 643 <http://caml.inria.fr/>
 644 .SH "AUTHORS"
 645 .IX Header "AUTHORS"
 646 Richard W.M. Jones <rjones @ redhat . com>
 647 .SH "COPYRIGHT"
 648 .IX Header "COPYRIGHT"
 649 (C) Copyright 2007\-2008 Red Hat Inc., Richard W.M. Jones
 650 http://libvirt.org/
 651 .PP
 652 This program is free software; you can redistribute it and/or modify
 653 it under the terms of the \s-1GNU\s0 General Public License as published by
 654 the Free Software Foundation; either version 2 of the License, or
 655 (at your option) any later version.
 656 .PP
 657 This program is distributed in the hope that it will be useful,
 658 but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of
 659 \&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0.  See the
 660 \&\s-1GNU\s0 General Public License for more details.
 661 .PP
 662 You should have received a copy of the \s-1GNU\s0 General Public License
 663 along with this program; if not, write to the Free Software
 664 Foundation, Inc., 675 Mass Ave, Cambridge, \s-1MA\s0 02139, \s-1USA\s0.
 665 .SH "REPORTING BUGS"
 666 .IX Header "REPORTING BUGS"
 667 Bugs can be viewed on the Red Hat Bugzilla page:
 668 <https://bugzilla.redhat.com/>.
 669 .PP
 670 If you find a bug in virt\-p2v, please follow these steps to report it:
 671 .IP "1. Check for existing bug reports" 4
 672 .IX Item "1. Check for existing bug reports"
 673 Go to <https://bugzilla.redhat.com/> and search for similar bugs.
 674 Someone may already have reported the same bug, and they may even
 675 have fixed it.
 676 .IP "2. Capture debug and error messages" 4
 677 .IX Item "2. Capture debug and error messages"
 678 At the point where you get the error or unexpected behaviour,
 679 go to the second virtual console (\fI\s-1ALT\s0\fR \fIF2\fR) and look at
 680 the logfile \f(CW\*(C`/tmp/virt\-p2v.log\*(C'\fR.  Please make sure that
 681 this file is attached to your bug report.
 682 .IP "3. Get version of virt\-p2v" 4
 683 .IX Item "3. Get version of virt-p2v"
 684 The version is in the name of the \s-1ISO\s0.  If you have built a custom
 685 virt\-p2v \s-1ISO\s0, please describe any changes that you have made.
 686 .IP "4. Submit a bug report." 4
 687 .IX Item "4. Submit a bug report."
 688 Go to <https://bugzilla.redhat.com/> and enter a new bug.
 689 Please describe the problem in as much detail as possible.
 690 .Sp
 691 Remember to include the version number (step 3) and to
 692 attach the log file (step 2).
 693 .IP "5. Assign the bug to rjones @ redhat.com" 4
 694 .IX Item "5. Assign the bug to rjones @ redhat.com"
 695 Assign or reassign the bug to \fBrjones @ redhat.com\fR (without the
 696 spaces).  You can also send me an email with the bug number if you
 697 want a faster response.