libguestfs/p2v/virt-p2v.pod

=head1 NAME

virt-p2v - Convert a physical machine to use KVM

=head1 SYNOPSIS

 virt-p2v

 virt-p2v.iso

=head1 DESCRIPTION

Virt-p2v converts a physical machine to run virtualized on KVM,
managed by libvirt, OpenStack, oVirt, Red Hat Virtualisation (RHV), or
one of the other targets supported by L<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.  Booting from a CD-ROM/etc is required because the
disks which are being converted must be quiescent.  It is not safe to
try to convert a running physical machine where other programs may be
modifying the disk content at the same time.

This manual page documents running the virt-p2v program.  To create
the bootable image you should look at L<virt-p2v-make-disk(1)> or
L<virt-p2v-make-kickstart(1)>.

=head1 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 L<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. C<ssh -R>) is required
by virt-p2v, and it will not work if this is disabled on the
conversion server.  (C<AllowTcpForwarding> must be C<yes> in the
L<sshd_config(5)> file on the conversion server).

The scp (secure copy) feature of ssh is required by virt-p2v so it can
send over small files (this is I<not> the method by which disks are
copied).

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.  (See also
L<virt-v2v(1)/Resource requirements>).

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.

=head1 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.

=head2 SSH CONFIGURATION DIALOG

When virt-p2v starts up in GUI mode, the first dialog looks like this:

 ┌─────────────────────────────────────────────────────────────┐
 │                           virt-p2v                          │
 │                                                             │
 │ Conversion server: [____________________________] : [22___] │
 │                                                             │
 │         User name: [root__________________________________] │
 │                                                             │
 │          Password: [______________________________________] │
 │                                                             │
 │  SSH Identity URL: [______________________________________] │
 │                                                             │

In the fields above, you must enter the details of the conversion
server: the hostname, SSH port number, remote user name, and either
the password or SSH identity (private key) URL.  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
L<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
L<virt-v2v(1)> manual page for details.

At the bottom of the dialog are these buttons:

 │                                                             │
 │                     [ Test connection ]                     │
 │                                                             │
 │ [ Configure network ] [ XTerm ] [ About virt-p2v ] [ Next ] │
 │                                                             │
 └─────────────────────────────────────────────────────────────┘

You must press the C<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
C<Next> button to move to the next dialog.

You can use the C<Configure network> button if you need to assign a
static IP address to the physical machine, or use Wifi, bonding or
other network features.

The C<XTerm> button opens a shell which can be used for diagnostics,
manual network configuration, and so on.

=head2 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
L<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
F</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
(I<not> to the physical server).

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                        │
     [✔]      sda                           │
              1024G HITACHI                 │
              s/n 12345                     │
     [✔]      sdb                           │
              119G HITACHI                  │
              s/n 12346                     │
                                            │

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 I<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 L<virt-v2v(1)/Networks and bridges>).

On supported hardware, left-clicking on the device name (eg. C<em1>)
causes a light to start flashing on the physical interface, allowing
the interface to be identified by the operator.

When you are ready to begin the conversion, press the
C<Start conversion> button:

                                            │
             [ Back ]  [ Start conversion ] │
                                            │
 ─ ─ ───────────────────────────────────────┘

=head2 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 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.

=head1 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 C<APPEND> field
in the F<pxelinux.cfg> file.  For example:

 DEFAULT p2v
 TIMEOUT 20
 PROMPT 0
 LABEL p2v
   KERNEL vmlinuz0
   APPEND initrd=initrd0.img [....] p2v.server=conv.example.com p2v.password=secret p2v.o=libvirt

You have to set some or all of the following command line arguments:

=over 4

__KERNEL_CONFIG__

=item B<p2v.pre=COMMAND>

=item B<p2v.pre="COMMAND ARG ...">

Select a pre-conversion command to run.  Any command or script can be
specified here.  If the command contains spaces, you must quote the
whole command with double quotes.  The default is not to run any
command.

=item B<p2v.post=poweroff>

=item B<p2v.post=reboot>

=item B<p2v.post=COMMAND>

=item B<p2v.post="COMMAND ARG ...">

Select a post-conversion command to run if conversion is successful.
This can be any command or script.  If the command contains spaces,
you must quote the whole command with double quotes.

I<If> virt-p2v is running as root, I<and> the command line was set
from F</proc/cmdline> (not I<--cmdline>), then the default is to run
the L<poweroff(8)> command.  Otherwise the default is not to run any
command.

=item B<p2v.fail=COMMAND>

=item B<p2v.fail="COMMAND ARG ...">

Select a post-conversion command to run if conversion fails.  Any
command or script can be specified here.  If the command contains
spaces, you must quote the whole command with double quotes.  The
default is not to run any command.

=item B<ip=dhcp>

Use DHCP for configuring the network interface (this is the default).

=begin comment

=item B<ip=ADDR:GATEWAY:NETMASK>

Set up a static IPv4 network configuration.

=end comment

=back

=head1 SSH IDENTITIES

As a somewhat more secure alternative to password authentication, you
can use an SSH identity (private key) for authentication.

First create a key pair.  It must have an empty passphrase:

 ssh-keygen -t rsa -N '' -f id_rsa

This creates a private key (C<id_rsa>) and a public key
(C<id_rsa.pub>) pair.

The public key should be appended to the C<authorized_keys> file on
the virt-v2v conversion server (usually to
C</root/.ssh/authorized_keys>).

For distributing the private key, there are four scenarios from least
secure to most secure:

=over 4

=item 1.

Not using SSH identities at all, ie. password authentication.

Anyone who can sniff the PXE boot parameters from the network or
observe the password some other way can log in to the virt-v2v
conversion server.

=item 2.

SSH identity embedded in the virt-p2v ISO or disk image.  In the GUI, use:

 │          Password: [    <leave this field blank>       ] │
 │                                                          │
 │  SSH Identity URL: [file:///var/tmp/id_rsa_____________] │

or on the kernel command line:

 p2v.identity=file:///var/tmp/id_rsa

The SSH private key can still be sniffed from the network if using
standard PXE.

=item 3.

SSH identity downloaded from a website.  In the GUI, use:

 │          Password: [    <leave this field blank>       ] │
 │                                                          │
 │  SSH Identity URL: [https://internal.example.com/id_rsa] │

or on the kernel command line:

 p2v.identity=https://internal.example.com/id_rsa

Anyone could still download the private key and use it to log in to
the virt-v2v conversion server, but you could provide some extra
security by configuring the web server to only allow connections from
P2V machines.

Note that L<ssh-keygen(1)> creates the C<id_rsa> (private key) file
with mode 0600.  If you simply copy the file to a webserver, the
webserver will not serve it.  It will reply with "403 Forbidden"
errors.  You will need to change the mode of the file to make it
publicly readable, for example by using:

 chmod 0644 id_rsa

=item 4.

SSH identity embedded in the virt-p2v ISO or disk image (like 2.),
I<and> use of secure PXE, PXE over separate physical network, or
sneakernet to distribute virt-p2v to the physical machine.

=back

Both L<virt-p2v-make-disk(1)> and L<virt-p2v-make-kickstart(1)> have
the same option I<--inject-ssh-identity> for injecting the private key
into the virt-p2v disk image / ISO.  See also the following manual
sections:

L<virt-p2v-make-disk(1)/ADDING AN SSH IDENTITY>

L<virt-p2v-make-kickstart(1)/ADDING AN SSH IDENTITY>

=head1 COMMON PROBLEMS

=head2 Timeouts

As described below (see L</HOW VIRT-P2V WORKS>) virt-p2v makes several
long-lived ssh connections to the conversion server.  If these
connections time out then virt-p2v will fail.

To test if a timeout might be causing problems, open an XTerm on the
virt-p2v machine, C<ssh root@I<conversion-server>>, and leave it for
at least an hour.  If the session disconnects without you doing
anything, then there is a timeout which you should turn off.

Timeouts happen because:

=over 4

=item C<TIMEOUT> or C<TMOUT> environment variable

Check if one of these environment variables is set in the root shell
on the conversion server.

=item sshd C<ClientAlive*> setting

Check for C<ClientAlive*> settings in C</etc/ssh/sshd_config> on the
conversion server.

=item Firewall or NAT settings

Check if there is a firewall or NAT box between virt-p2v and the
conversion server, and if this firewall drops idle connections after a
too-short time.

virt-p2v E<ge> 1.36 attempts to work around firewall timeouts by
sending ssh keepalive messages every 5 minutes.

=back

=head1 OPTIONS

=over 4

=item B<--help>

Display help.

=item B<--cmdline=CMDLINE>

This is used for debugging. Instead of parsing the kernel command line
from F</proc/cmdline>, parse the string parameter C<CMDLINE>.

=item B<--colors>

=item B<--colours>

Use ANSI colour sequences to colourize messages.  This is the default
when the output is a tty.  If the output of the program is redirected
to a file, ANSI colour sequences are disabled unless you use this
option.

=item B<--iso>

This flag is passed to virt-p2v when it is launched inside the
virt-p2v ISO environment, ie. when it is running on a real physical
machine (and thus not when testing).  It enables various dangerous
features such as the Shutdown popup button.

=item B<--nbd=server[,server...]>

Select which NBD server is used.  By default the following servers are
checked and the first one found is used:
I<--nbd=qemu-nbd,qemu-nbd-no-sa,nbdkit,nbdkit-no-sa>

=over 4

=item B<qemu-nbd>

Use qemu-nbd.

=item B<qemu-nbd-no-sa>

Use qemu-nbd, but disable socket activation.

=item B<nbdkit>

Use nbdkit with the file plugin (see: L<nbdkit-file-plugin(1)>).

=item B<nbdkit-no-sa>

Use nbdkit, but disable socket activation

=back

The C<*-no-sa> variants allow virt-p2v to fall back to older versions
of qemu-nbd and nbdkit which did not support
L<socket activation|http://0pointer.de/blog/projects/socket-activation.html>.

=item B<--test-disk=/PATH/TO/DISK.IMG>

For testing or debugging purposes, replace F</dev/sda> with a local
file.  You must use an absolute path.

=item B<-v>

=item B<--verbose>

In libguestfs E<ge> 1.33.41, debugging is always enabled on the
conversion server, and this option does nothing.

=item B<-V>

=item B<--version>

Display version number and exit.

=back

=head1 HOW VIRT-P2V WORKS

B<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. C<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 C<YYYYMMDD> is the current date, and the ‘X’s are random
characters.

Into this directory are written various files which include:

=over 4

=item F<dmesg>

=item F<lscpu>

=item F<lspci>

=item F<lsscsi>

=item F<lsusb>

I<(before conversion)>

The output of the corresponding commands (ie L<dmesg(1)>, L<lscpu(1)>
etc) on the physical machine.

The dmesg output is useful for detecting problems such as missing
device drivers or firmware on the virt-p2v ISO.  The others are useful
for debugging novel hardware configurations.

=item F<environment>

I<(before conversion)>

The content of the environment where L<virt-v2v(1)> will run.

=item F<name>

I<(before conversion)>

The name (usually the hostname) of the physical machine.

=item F<physical.xml>

I<(before conversion)>

Libvirt XML describing the physical machine.  It is used to pass data
about the physical source host to L<virt-v2v(1)> via the I<-i libvirtxml>
option.

Note this is not "real" libvirt XML (and must B<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.

=item F<p2v-version>

=item F<v2v-version>

I<(before conversion)>

The versions of virt-p2v and virt-v2v respectively.

=item F<status>

I<(after conversion)>

The final status of the conversion.  C<0> if the conversion was
successful.  Non-zero if the conversion failed.

=item F<time>

I<(before conversion)>

The start date/time of conversion.

=item F<virt-v2v-conversion-log.txt>

I<(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 B<complete>,
B<unedited> log file in any bug reports or support tickets.

=item F<virt-v2v-wrapper.sh>

I<(before conversion)>

This is the wrapper script which is used when running virt-v2v.  For
interest only, do not attempt to run this script yourself.

=back

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 NBD server is L<qemu-nbd(1)> by
default but others can be selected using the I<--nbd> command line
option.

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 (C<ssh -R>) is used to open a port on the
loopback interface of the conversion server which is proxied back by
ssh to the 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 I<-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 long S<C<virt-v2v -i libvirtxml physical.xml ...>> command is
wrapped inside a wrapper script and uploaded to the conversion server.
The final step is to run this wrapper script, in turn running the
virt-v2v command.  The virt-v2v command references the F<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.  Only informational
messages are sent back over the control connection to be displayed in
the graphical UI.

=head1 SEE ALSO

L<virt-p2v-make-disk(1)>,
L<virt-p2v-make-kickstart(1)>,
L<virt-p2v-make-kiwi(1)>,
L<virt-v2v(1)>,
L<qemu-nbd(1)>,
L<nbdkit(1)>, L<nbdkit-file-plugin(1)>,
L<ssh(1)>,
L<sshd(8)>,
L<sshd_config(5)>,
L<http://libguestfs.org/>.

=head1 AUTHORS

Matthew Booth

John Eckersberg

Richard W.M. Jones L<http://people.redhat.com/~rjones/>

Mike Latimer

Pino Toscano

Tingting Zheng

=head1 COPYRIGHT

Copyright (C) 2009-2019 Red Hat Inc.