NAME¶
virt-p2v - Convert a physical machine to use KVM
SYNOPSIS¶
virt-p2v
virt-p2v.iso
DESCRIPTION¶
Virt-p2v converts a physical machine to run virtualized on KVM, managed by
libvirt, OpenStack, oVirt, Red Hat Enterprise Virtualisation (RHEV), or one of
the other targets supported by
virt-v2v(1).
Normally you don't run the virt-p2v program directly. Instead you have to boot
the physical machine using the bootable CD-ROM, ISO or PXE image. This
bootable image contains the virt-p2v binary and runs it automatically.
This manual page documents running the virt-p2v program. To create the bootable
image you should look at
virt-p2v-make-disk(1) or
virt-p2v-make-kickstart(1).
NETWORK SETUP¶
Virt-p2v runs on the physical machine which you want to convert. It has to talk
to another server called the "conversion server" which must have
virt-v2v(1) installed on it. It always talks to the conversion server
over SSH:
┌──────────────┐ ┌─────────────────┐
│ virt-p2v │ │ virt-v2v │
│ (physical │ ssh connection │ (conversion │
│ server) ╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍▶ server) │
└──────────────┘ └─────────────────┘
The virt-v2v program on the conversion server does the actual conversion
(physical to virtual, and virtual to virtual conversions are sufficiently
similar that we use the same program to do both).
The SSH connection is always initiated from the physical server. All data is
transferred over the SSH connection. In terms of firewall and network
configuration, you only need to ensure that the physical server has access to
a port (usually TCP port 22) on the conversion server. Note that the physical
machine may reconnect several times during the conversion process.
The reverse port forwarding feature of ssh (ie. "ssh -R") is required
by virt-p2v, and it will not work if this is disabled on the conversion
server.
The conversion server does not need to be a physical machine. It could be a
virtual machine, as long as it has sufficient memory and disk space to do the
conversion, and as long as the physical machine can connect directly to its
SSH port.
Because all of the data on the physical server's hard drive(s) has to be copied
over the network, the speed of conversion is largely determined by the speed
of the network between the two machines.
GUI INTERACTIVE CONFIGURATION¶
When you start virt-p2v, you'll see a graphical configuration dialog that walks
you through connection to the conversion server, asks for the password, which
local hard disks you want to convert, and other things like the name of the
guest to create and the number of virtual CPUs to give it.
SSH CONFIGURATION DIALOG¶
When virt-p2v starts up in GUI mode, the first dialog looks like this:
┌────────────────────────────────────────────────────────┐
│ virt-p2v │
│ │
│ Conversion server: [_________________________________] │
│ │
│ SSH port: [22_______________________________] │
│ │
│ User name: [root_____________________________] │
│ │
│ Password: [_________________________________] │
│ │
In the fields above, you must enter the hostname, SSH port number, remote user
name and password of the conversion server. The conversion server must have an
up to date version of virt-v2v.
Normally you must log in to the conversion server as root, but if you check the
following box:
│ │
│ [ ] Use sudo when running virt-v2v │
│ │
then you can log in as another user, and virt-p2v will use the
sudo(8)
command to elevate privileges to root. Note that sudo must not require a
password.
It is also possible to run virt-v2v on the conversion server entirely as
non-root, but output modes may be limited. Consult the
virt-v2v(1)
manual page for details.
At the bottom of the dialog are these buttons:
│ │
│ [ Test connection ] │
│ │
│ [ About ] [ Next ] │
│ │
└────────────────────────────────────────────────────────┘
You must press the "Test connection" button first to test the SSH
connection to the conversion server. If that is successful (ie. you have
supplied the correct server name, user name, password, etc., and a suitable
version of virt-v2v is available remotely) then press the "Next"
button to move to the next dialog.
DISK AND NETWORK CONFIGURATION DIALOG¶
The second configuration dialog lets you configure the details of conversion,
including what to convert and where to send the guest.
In the left hand column, starting at the top, the target properties let you
select the name of the guest (ie. after conversion) and how many virtual CPUs
and how much RAM to give it. The defaults come from the physical machine, and
you can usually leave them unchanged:
┌─────────────────────────────────────── ─ ─ ─ ─
│ Target properties:
│
│ Name: [hostname______________]
│
│ # vCPUs: [4_____________________]
│
│ Memory (MB): [16384_________________]
│
The second panel on the left controls the virt-v2v output options. To understand
these options it is a really good idea to read the
virt-v2v(1) manual
page. You can leave the options at the default to create a guest as a disk
image plus libvirt XML file located in "/var/tmp" on the conversion
host. This is a good idea if you are a first-time virt-p2v user.
│
│ Virt-v2v output options:
│
│ Output to (-o): [local ▼]
│
│ Output conn. (-oc): [___________________]
│
│ Output storage (-os): [/var/tmp___________]
│
│ Output format (-of): [___________________]
│
│ Output allocation (-oa): [sparse ▼]
│
All output options and paths are relative to the conversion server (
not
to the physical server).
The final option in this panel enables server-side debugging. This produces a
lot of output, but is essential if you are tracking down virt-p2v or virt-v2v
problems, and can generally be left enabled:
│
│ [✔] Enable server-side debugging
│
Finally in the left hand column is an information box giving the version of
virt-p2v (on the physical server) and virt-v2v (on the conversion server). You
should supply this information when reporting bugs.
In the right hand column are three panels which control what hard disks,
removable media devices, and network interfaces, will be created in the output
guest. Normally leaving these at the default settings is fine.
─ ─ ───────────────────────────────────────┐
Fixed hard disks │
│
Convert Device Size (GB) Model │
[✔] sda 1024 HITACHI │
[✔] sdb 119 HITACHI │
│
Normally you would want to convert all hard disks. If you want virt-p2v to
completely ignore a local hard disk, uncheck it. The hard disk that contains
the operating system must be selected. If a hard disk is part of a RAID array
or LVM volume group (VG), then either all hard disks in that array/VG must be
selected, or none of them.
│
Removable media │
│
Convert Device │
[✔] sr0 │
│
If the physical machine has CD or DVD drives, then you can use the Removable
media panel to create corresponding drives on the guest after conversion. Note
that any data CDs/DVDs which are mounted in the drives are
not copied
over.
│
Network interfaces │
│
Convert Device Connect to ... |
[✔] em1 [default_____________] │
[ ] wlp3s0 [default_____________] │
│
In the Network interfaces panel, select the network interfaces that should be
created in the guest after conversion. You can also connect these to target
hypervisor networks (for further information about this feature, see
"NETWORKS AND BRIDGES" in
virt-v2v(1)).
When you are ready to begin the conversion, press the "Start
conversion" button:
│
[ Back ] [ Start conversion ] │
│
─ ─ ───────────────────────────────────────┘
CONVERSION RUNNING DIALOG¶
When conversion is running you will see this dialog:
┌────────────────────────────────────────────────────────┐
│ virt-p2v │
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ ▲│ │
│ │ │ │
│ │ │ │
∼ ∼ ∼ ∼
│ │ │ │
│ │ │ │
│ │ ▼│ │
│ └──────────────────────────────────────────────────┘ │
│ │
│ Log files ... to /tmp/virt-p2v-xxx │
│ │
│ Doing conversion ... │
│ │
│ [ Cancel conversion ] │
│ │
└────────────────────────────────────────────────────────┘
In the main scrolling area you will see log messages from the virt-v2v process.
Below the main area, virt-p2v shows you the location of the directory on the
conversion server that contains log files and other debugging information.
Below that is the current status and a button for cancelling conversion.
Once conversion has finished, you should shut down the physical machine. If
conversion is successful, you should never reboot it.
KERNEL COMMAND LINE CONFIGURATION¶
If you don't want to configure things using the graphical UI, an alternative is
to configure through the kernel command line. This is especially convenient if
you are converting a lot of physical machines which are booted using PXE.
Where exactly you set command line arguments depends on your PXE implementation,
but for pxelinux you put them in the "APPEND" field in the
"pxelinux.cfg" file. For example:
DEFAULT p2v
TIMEOUT 20
PROMPT 0
LABEL p2v
KERNEL virt-p2v-vmlinuz
APPEND initrd=virt-p2v-initrd p2v.server=conv.example.com p2v.password=secret p2v.o=libvirt
You have to set some or all of the following command line arguments:
- p2v.server=SERVER
- The name or IP address of the conversion server.
This is always required if you are using the kernel configuration method. If
virt-p2v does not find this on the kernel command line then it switches to
the GUI (interactive) configuration method.
- p2v.port=NN
- The SSH port number on the conversion server (default: 22).
- p2v.username=USERNAME
- The SSH username that we log in as on the conversion server (default:
"root").
- p2v.password=PASSWORD
- The SSH password that we use to log in to the conversion server.
The default is to try with no password. If this fails then virt-p2v will ask
the user to type the password (probably several times during conversion).
Note that virt-p2v does not support authentication using key distribution at
this time.
- p2v.sudo
- Use "p2v.sudo" to tell virt-p2v to use sudo(8) to gain
root privileges on the conversion server after logging in as a non-root
user (default: do not use sudo).
- p2v.name=GUESTNAME
- The name of the guest that is created. The default is to try to derive a
name from the physical machine's hostname (if possible) else use a
randomly generated name.
- p2v.vcpus=NN
- The number of virtual CPUs to give to the guest. The default is to use the
same as the number of physical CPUs.
- p2v.memory=NN(M|G)
- The size of the guest memory. You can specify this in megabytes or
gigabytes by using (eg) "p2v.memory=1024M" or
"p2v.memory=1G". The default is to use the same amount of RAM as
on the physical machine.
- p2v.debug
- Use this to enable full debugging of virt-v2v.
If asked to diagnose a problem with virt-p2v, you should add
"p2v.debug" to the kernel command line, and examine the log file
which is left in "/tmp" on the conversion server.
- p2v.disks=sdX,sdY,..
- A list of physical hard disks to convert, for example:
p2v.disks=sda,sdc
The default is to convert all local hard disks that are found.
- p2v.removable=srX,srY,..
- A list of removable media to convert. The default is to create virtual
removable devices for every physical removable device found. Note that the
content of removable media is never copied over.
- p2v.interfaces=em1,..
- A list of network interfaces to convert. The default is to create virtual
network interfaces for every physical network interface found.
- p2v.network=interface:target,...
- Controls how network interfaces are connected to virtual networks on the
target hypervisor. The default is to connect all network interfaces to the
target "default" network.
You give a comma-separated list of "interface:target" pairs, plus
optionally a default target. For example:
p2v.network=em1:rhevm
maps interface "em1" to target network "rhevm".
p2v.network=em1:rhevm,em2:management,other
maps interface "em1" to "rhevm", and "em2" to
"management", and any other interface that is found to
"other".
- p2v.o=[libvirt|local|...]
- Set the output mode. This is the same as the virt-v2v -o option.
See "OPTIONS" in virt-v2v(1).
If not specified, the default is "local", and the converted guest
is written to "/var/tmp".
- p2v.oa=sparse|preallocated
- Set the output allocation mode. This is the same as the virt-v2v
-oa option. See "OPTIONS" in virt-v2v(1).
- p2v.oc=...
- Set the output connection libvirt URI. This is the same as the virt-v2v
-oc option. See "OPTIONS" in virt-v2v(1) and
http://libvirt.org/uri.html
- p2v.of=raw|qcow2|...
- Set the output format. This is the same as the virt-v2v -of option.
See "OPTIONS" in virt-v2v(1).
- p2v.os=...
- Set the output storage. This is the same as the virt-v2v -os
option. See "OPTIONS" in virt-v2v(1).
If not specified, the default is "/var/tmp" (on the conversion
server).
- ip=dhcp
- Use DHCP for configuring the network interface (this is the default).
OPTIONS¶
- --help
- Display help.
- --cmdline=CMDLINE
- This is used for debugging. Instead of parsing the kernel command line
from "/proc/cmdline", parse the string parameter
"CMDLINE".
- -v
- --verbose
- Enable debugging (on the conversion server).
- -V
- --version
- Display version number and exit.
HOW VIRT-P2V WORKS¶
Note this section is not normative. We may change how virt-p2v works at
any time in the future.
As described above, virt-p2v runs on a physical machine, interrogates the user
or the kernel command line for configuration, and then establishes one or more
ssh connections to the virt-v2v conversion server. The ssh connections are
interactive shell sessions to the remote host, but the commands sent are
generated entirely by virt-p2v itself, not by the user. For data transfer,
virt-p2v will use the reverse port forward feature of ssh (ie. "ssh
-R").
It will first make one or more test connections, which are used to query the
remote version of virt-v2v and its features. The test connections are closed
before conversion begins.
┌──────────────┐ ┌─────────────────┐
│ virt-p2v │ │ virt-v2v │
│ (physical │ control connection │ (conversion │
│ server) ╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍▶ server) │
└──────────────┘ └─────────────────┘
Once virt-p2v is ready to start conversion, it will open a single ssh control
connection. It first sends a mkdir command to create a temporary directory on
the conversion server. The directory name is randomly chosen and is displayed
in the GUI. It has the form:
/tmp/virt-p2v-YYYYMMDD-XXXXXXXX
where "YYYYMMDD" is the current date, and the X's are random
characters.
Into this directory are written various files which include:
- "name"
- before conversion
The name (usually the hostname) of the physical machine.
- "physical.xml"
- before conversion
Libvirt XML describing the physical machine. It is used to pass data about
the physical source host to virt-v2v(1) via the -i
libvirtxml option.
Note this is not "real" libvirt XML (and must never be
loaded into libvirt, which would reject it anyhow). Also it is not the
same as the libvirt XML which virt-v2v generates in certain output
modes.
- "status"
- after conversion
The final status of the conversion. 0 if the conversion was successful.
Non-zero if the conversion failed.
- "time"
- before conversion
The start date/time of conversion.
- "virt-v2v-conversion-log.txt"
- during/after conversion
The conversion log. This is just the output of the virt-v2v command on the
conversion server. If conversion fails, you should examine this log file,
and you may be asked to supply the complete, unedited log
file in any bug reports or support tickets.
Before conversion actually begins, virt-p2v then makes one or more further ssh
connections to the server for data transfer. The transfer protocol used
currently is NBD (Network Block Device), which is proxied over ssh. The server
is
qemu-nbd(1). There is one ssh connection per physical hard disk on
the source machine (the common case — a single hard disk — is
shown below):
┌──────────────┐ ┌─────────────────┐
│ virt-p2v │ │ virt-v2v │
│ (physical │ control connection │ (conversion │
│ server) ╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍▶ server) │
│ │ │ │
│ │ data connection │ │
│ ╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍▶ │
│qemu-nbd ← ─┘ │ │└─ ← NBD │
│/dev/sda │ │ requests │
∼ ∼ ∼ ∼
└──────────────┘ └─────────────────┘
Although the ssh data connection is originated from the physical server and
terminates on the conversion server, in fact NBD requests flow in the opposite
direction. This is because the reverse port forward feature of ssh ("ssh
-R") is used to open a port on the loopback interface of the conversion
server which is proxied back by ssh to the qemu-nbd server running on the
physical machine. The effect is that virt-v2v via libguestfs can open nbd
connections which directly read the hard disk(s) of the physical server.
Two layers of protection are used to ensure that there are no writes to the hard
disks: Firstly, the qemu-nbd
-r (readonly) option is used. Secondly
libguestfs creates an overlay on top of the NBD connection which stores writes
in a temporary file on the conversion file.
The final step is to send the
"virt-v2v -i libvirtxml physical.xml ..."
command to the conversion server over the control connection. This references
the "physical.xml" file (see above), which in turn references the
NBD listening port(s) of the data connection(s).
Output from the virt-v2v command (messages, debugging etc) is saved both in the
log file on the conversion server, and sent over the control connection to be
displayed in the graphical UI.
SEE ALSO¶
virt-p2v-make-disk(1),
virt-p2v-make-kickstart(1),
virt-v2v(1),
qemu-nbd(1),
ssh(1),
http://libguestfs.org/.
AUTHORS¶
Richard W.M. Jones
http://people.redhat.com/~rjones/
Matthew Booth
COPYRIGHT¶
Copyright (C) 2009-2014 Red Hat Inc.
LICENSE¶
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., 51 Franklin
Street, Fifth Floor, Boston, MA 02110-1301 USA.
BUGS¶
To get a list of bugs against libguestfs, use this link:
https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
To report a new bug against libguestfs, use this link:
https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
When reporting a bug, please supply:
- •
- The version of libguestfs.
- •
- Where you got libguestfs (eg. which Linux distro, compiled from source,
etc)
- •
- Describe the bug accurately and give a way to reproduce it.
- •
- Run libguestfs-test-tool(1) and paste the complete, unedited
output into the bug report.
