Provided by: libguestfs-tools_1.32.2-4ubuntu2.2_amd64 bug

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.  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 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.  ("AllowTcpForwarding" must be
       "yes" in the sshd_config(5) file 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.  (See also "RESOURCE
       REQUIREMENTS" in virt-v2v(1)).

       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: [_________________________________] │
        │                                                        │
        │  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 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 ]                     │
        │                                                        │
        │ [ Configure network ] [ About virt-p2v  ] [ 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.

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

   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 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:

       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).

           This setting is ignored if "p2v.identity" is present.

       p2v.identity=URL
           Provide a URL pointing to an SSH identity (private key) file.  The URL is interpreted
           by curl(1) so any URL that curl supports can be used here, including "https://" and
           "file://".  For more information on using SSH identities, see "SSH IDENTITIES" below.

           If "p2v.identity" is present, it overrides "p2v.password".  There is no fallback.

       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 must specify the unit as either 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).

       p2v.pre=COMMAND
       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.

       p2v.post=poweroff
       p2v.post=reboot
       p2v.post=COMMAND
       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.

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

       p2v.fail=COMMAND
       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.

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

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 ("id_rsa") and a public key ("id_rsa.pub") pair.

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

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

       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.

       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.

       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.

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

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

       "ADDING AN SSH IDENTITY" in virt-p2v-make-disk(1)

       "ADDING AN SSH IDENTITY" in virt-p2v-make-kickstart(1)

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:

       dmesg
           (before conversion)

           The dmesg output from the physical machine.  Useful for detecting problems such as
           missing device drivers or firmware on the virt-p2v ISO.

       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),
       sshd(8), sshd_config(5), http://libguestfs.org/.

AUTHORS

       Matthew Booth

       John Eckersberg

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

       Mike Latimer

       Pino Toscano

       Tingting Zheng

COPYRIGHT

       Copyright (C) 2009-2016 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.