virt-p2v(1)

📦
version 1.42.4 · 11 versions
, in centos-stream 9

💅 virt-p2v(1) 💅

✨ NAME ✨

virt-p2v — convert a physical machine to use KVM

🌸 SYNOPSIS 🌸

 virt-p2v

 virt-p2v.iso

💖 DESCRIPTION 💖

Okay so 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 virt-v2v(1). It's giving "glow-up for your whole server," no cap.

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

Bestie, do not try to convert a live machine while other stuff is writing to the disk. The disks have to be quiet. That's the whole vibe check.

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). Iconic reuse, honestly. 💅

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). Do not skip this, bestie — it's not optional. 🫶

The scp (secure copy) feature of ssh is required by virt-p2v so it can send over small files (this is not the method by which disks are copied). Important distinction: small files, not the big disk data. ✨

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. So yeah — network go brrr, conversion go brrr. 🌈

🎀 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: [____________________________] : [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. Like, zero password prompts, bestie. 🙈

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 ] [ XTerm ] [ 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. No skipping ahead before the connection test passes, okay? 💅

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.

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

💽 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            ▼]
        │
        │     Misc. options (-oo): [___________________]
        │

All output options and paths are relative to the conversion server (not to the physical server). So yeah, /var/tmp means /var/tmp over there, not on the physical machine. 🎀

Note that the Misc. options text entry behaves differently from the other text entries -- its format is identical to that of the p2v.output.misc kernel command line option. Namely, the text entry contains a comma-separated list of miscellaneous, output-specific options. (Do not put spaces around the commas!) Each element in the list is of the form OPTION=VALUE, and each element is passed to virt-v2v as a standalone -oo OPTION=VALUE option.

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. Future you will thank present you for writing it down. ✨

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. This is a "all or nothing" situation, bestie — no half-selected RAID arrays. 💀

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

So at the very bottom of that dialog there's a "Refresh disks" button, and it tells virt-p2v to re-enumerate the fixed hard disks and the removable media drives, bestie ✨ (heads up though — the button also resets the currently active selections in both of those panels, so don't be shocked when your picks vanish 🙈). It's genuinely so useful when you pair it with the "XTerm" button over on the "SSH CONFIGURATION DIALOG": in that XTerm window you can expose further block devices to the kernel (think LUNs from iSCSI targets, iykyk), and then "Refresh disks" lets virt-p2v learn about all the block devices again. Teamwork 💅

                                                              │
            Network interfaces                                │
                                                              │
            Convert  Device Connect to virtual network        │
            [✔]      em1    [default________________________] │
            [ ]      wlp3s0 [default________________________] │
                                                              │

Now the Network interfaces panel 🦋 — this is where you pick which network interfaces should be created in the guest after conversion. You can also connect these to target hypervisor networks (for the full tea on that feature, go read "Networks and bridges" in virt-v2v(1) 👑).

On supported hardware, left-clicking on the device name (like em1 in the example above) causes a light to start flashing on the physical interface — literally a little beacon so the operator can identify which cable is which 🌈 iconic.

When you're ready to actually begin the conversion, hit the "Start conversion" button:

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

🎀 CONVERSION RUNNING DIALOG 🎀

When conversion is running you'll be looking at this:

        ┌────────────────────────────────────────────────────────┐
        │                      virt-p2v                          │
        │                                                        │
        │  ┌──────────────────────────────────────────────────┐  │
        │  │                                                 ▲│  │
        │  │                                                  │  │
        │  │                                                  │  │
        ∼  ∼                                                  ∼  ∼
        │  │                                                  │  │
        │  │                                                  │  │
        │  │                                                 ▼│  │
        │  └──────────────────────────────────────────────────┘  │
        │                                                        │
        │ Log files ... to /tmp/virt-p2v-xxx                     │
        │                                                        │
        │ Doing conversion ...                                   │
        │                                                        │
        │                                 [ Cancel conversion ]  │
        │                                                        │
        └────────────────────────────────────────────────────────┘

In the main scrolling area you get to watch messages stream in from the virt-v2v process — it's giving live commentary, lowkey hypnotic 😭

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 plus a button for cancelling conversion, so you always know what's up 🫶

Once conversion has finished, you should shut down the physical machine.

⚠️ If conversion is successful, you should never reboot it. Not once. Not "just to check". Nope 🛑💀

🐧 KERNEL COMMAND LINE CONFIGURATION 🐧

Okay so bestie, if you're sitting there like "the GUI is cute but I have forty machines to convert" — same. There's another way: you can configure everything through the kernel command line instead. This is especially convenient if you are converting a lot of physical machines which are booted using PXE. It's giving automation, it's giving scale, it's giving "I refuse to click Next forty times". 💅

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.remote.server=SERVER, 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. (So like, it'll bail to the clicky-clicky version — no drama, just noting it.)

  • p2v.remote.port=PORT, p2v.port=PORT — The SSH port number on the conversion server (default: 22).
  • p2v.auth.username=USERNAME, p2v.username=USERNAME — The SSH username that we log in as on the conversion server (default: "root").
  • p2v.auth.password=PASSWORD, 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.auth.identity.url" is present.

  • p2v.auth.identity.url=URL, 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.auth.identity.url" is present, it overrides "p2v.auth.password". There is no fallback. Like, none. Zero. Don't @ me.

  • p2v.auth.sudo, 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.guestname=GUESTNAME, 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.vcpu.phys_topo — Copy the physical machine's complete CPU topology (sockets, cores and threads) to the guest. Disabled by default. If disabled, the "p2v.vcpu.cores" setting takes effect. 🧠
  • p2v.vcpu.cores=N — This setting is ignored if "p2v.vcpu.phys_topo" is enabled. Otherwise, it specifies the flat number of vCPU cores to give to the guest (placing all of those cores into a single socket, and exposing one thread per core). The default value is the number of online logical processors on the physical machine. ⚡
  • p2v.memory=n(M|G) — The size of the guest memory. You must specify the unit such as megabytes or gigabytes by using for example "p2v.memory=1024M" or "p2v.memory=1G". 🍓

The default is to use the same amount of RAM as on the physical machine.

  • p2v.cpu.vendor=VENDOR — The vCPU vendor, eg. "Intel" or "AMD". The default is to use the same CPU vendor as the physical machine. 💻
  • p2v.cpu.model=MODEL — The vCPU model, eg. "IvyBridge". The default is to use the same CPU model as the physical machine.
  • p2v.cpu.acpi — Whether to enable ACPI in the remote virtual machine. The default is to use the same as the physical machine.
  • p2v.cpu.apic — Whether to enable APIC in the remote virtual machine. The default is to use the same as the physical machine.
  • p2v.cpu.pae — Whether to enable PAE in the remote virtual machine. The default is to use the same as the physical machine.
  • p2v.rtc.basis=(unknown|utc|localtime) — Set the basis of the Real Time Clock in the virtual machine. The default is to try to detect this setting from the physical machine. ⏰
  • p2v.rtc.offset=[+|-]HOURS — The offset of the Real Time Clock from UTC. The default is to try to detect this setting from the physical machine.
  • p2v.disks=sda,sdb,... — 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=sra,srb,... — 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. (Yeah, the device shows up, the stuff inside does not. Don't ask, it's just how it is. 🙈)
  • 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_map=interface:target,..., 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:ovirtmgmt

maps interface "em1" to target network "ovirtmgmt".

p2v.network=em1:ovirtmgmt,em2:management,other

maps interface "em1" to "ovirtmgmt", and "em2" to "management", and any other interface that is found to "other". 🌈

  • p2v.output.type=(libvirt|local|...), 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.output.allocation=(none|sparse|preallocated), p2v.oa=(none|sparse|preallocated) — Set the output allocation mode. This is the same as the virt-v2v -oa option. See "OPTIONS" in virt-v2v(1).
  • p2v.output.connection=URI, p2v.oc=URI — 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.output.format=(raw|qcow2|...), 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.output.storage=STORAGE, p2v.os=STORAGE — 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.output.misc=OPTION=VALUE,..., p2v.oo=OPTION=VALUE,... — Set miscellaneous output option(s) related to the selected output mode. This is the same as the virt-v2v -oo option; each "OPTION=VALUE" element in the list will be turned into a separate -oo OPTION=VALUE option on the virt-v2v command line. See "OPTIONS" in virt-v2v(1). 🎛️
  • 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 🔑

Okay bestie, so if passwords give you the ick, there's a glow-up option: use an SSH identity (that's a private key, iykyk) to log in instead. Way more secure, way more slay. 💅

First things first, you gotta make a key pair. It must have an empty passphrase — like, no passphrase at all, periodt:

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

This gives you a private key (id_rsa) and a public key (id_rsa.pub). Cute little matched set. 🎀

Now the public key should get appended to the authorized_keys file on the virt-v2v conversion server — usually that's /root/.ssh/authorized_keys.

And now for the private key, there are four whole scenarios, ranked from least secure to most secure. Buckle up. 🦋

  1. Not using SSH identities at all, aka password authentication.

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

  1. SSH identity embedded in the virt-p2v ISO or disk image. In the GUI, you'd do:
│          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

Heads up though — the SSH private key can still be sniffed from the network if you're on standard PXE. 😭

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

So technically anyone could still download that private key and use it to log in to the virt-v2v conversion server 😬 — but you can add some extra security by configuring the web server so it only allows connections from P2V machines. Clever, no cap.

Okay this next bit is the classic gotcha: ssh-keygen(1) creates the id_rsa (private key) file with mode 0600. If you just copy the file to a webserver, the webserver will not serve it — it'll reply with 403 Forbidden errors instead. Iconic behaviour tbh. You will need to change the mode of the file to make it publicly readable, for example: chmod 0644 id_rsa
  1. SSH identity embedded in the virt-p2v ISO or disk image (like scenario 2), plus use of secure PXE, PXE over a separate physical network, or sneakernet to get virt-p2v onto the physical machine. This is the final boss of security. 👑

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 these manual sections:

💾 ACCESSING ISCSI DEVICES 💾

So like, what if the disk holding the operating system — or other disks you wanna convert — are LUNs of remote iSCSI targets? 🫶 No stress. Just follow these steps so virt-p2v can learn about said disks. Note that this procedure depends on the use of the GUI.

The guide below is roughly based on the RHEL9 product documentation, for the record. 📚

  1. Open a shell in an XTerm window, using the "XTerm" button of the "SSH CONFIGURATION DIALOG".
(Note that the XTerm window(s) persist while you advance to further dialogs in virt-p2v, therefore it's unnecessary to jump back and forth between virt-p2v dialogs just for entering additional shell commands in the XTerm window(s). We love efficiency. ✨)
  1. Using "vi" or another text editor, set the iSCSI initiator name in /etc/iscsi/initiatorname.iscsi, for example:
InitiatorName=iqn.1994-05.com.redhat:846e82c634

If the file does not exist, create it. (Remember that this file is part of the virt-p2v Live environment, therefore saving it does not modify any hard disks. Everything stays in vibes-only mode. 💜)

  1. Configure any further iSCSI initiator details completely that are required by the iSCSI target that you intend to log in to — that is, before you issue the first "iscsiadm" command below. This includes the CHAP user name and password if the target authenticates the initiator with CHAP, and the reverse direction CHAP user name and password too, if you want to ascertain the identity of the target on the initiator as well (this is called "mutual authentication").
Getting the configuration done at this stage is important because the first "iscsiadm" command will start up the "iscsid" service, and configuration changes with that service already running will not (or may not) take effect until/unless you restart the service using "systemctl". So like, do it now, not later. 🙈
  1. Discover the iSCSI targets offered by the desired host:
iscsiadm -m discovery -t st -p IP_ADDRESS

The command should respond with a two-column list of targets. The symbolic target names are in the right hand side column, for example:

     10.64.24.179:3260,1 iqn.2006-04.example:444
  1. Picking an appropriate target from the right hand side column of the previous step's output, log in to the target:
iscsiadm -m node -T TARGET -l

This command will inform you whether the login attempt was successful. 🎯

  1. In case the login succeeds, a scan for LUNs on the iSCSI target will commence at once. There are two pitfalls here. One, dependent on network characteristics, the scan may take several (tens of) seconds. Two, even if the login succeeds, ACLs on the target may silently prevent the initiator from seeing particular LUNs — meaning that no new /dev/sdX nodes will appear. This is why it is important to get the initiator name (and, potentially, CHAP authentication) correct at the very beginning of this procedure. 😭

Verify the results of the target scan with the "dmesg" command, and/or with:

ls -l /dev/disk/by-path/ip-*-iscsi-*-lun-*

If these symlinks exist, containing the IP_ADDRESS from step 4 and the TARGET name from step 5 in their filenames, then the target scan has successfully found the corresponding LUNs. Slay. 💅

  1. Once the remote LUNs have been successfully enumerated, click the "Refresh disks" button in the "DISK AND NETWORK CONFIGURATION DIALOG".

😭 COMMON PROBLEMS 😭

⏰ Timeouts

As described below (see "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. Like, just give up on you. 💀

To test if a timeout might be causing problems, open an XTerm on the virt-p2v machine, run "ssh root@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. (Not you doing anything wrong — the session just ghosted you. 🥀)

Timeouts happen because:

  • "TIMEOUT" or "TMOUT" environment variable

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

  • sshd "ClientAlive*" setting

Check for "ClientAlive*" settings in "/etc/ssh/sshd_config" on the conversion server.

  • 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 ≥ 1.36 attempts to work around firewall timeouts by sending ssh keepalive messages every 5 minutes. Little "hey bestie u still there" pings. 🫶

✨ OPTIONS ✨

  • --help — Displays help. Your literal bestie when you're lost.
  • --cmdline=CMDLINE — This is used for debugging. Instead of parsing the kernel command line from /proc/cmdline, it parses the string parameter CMDLINE instead. Fancy. 🔥
  • --colors, --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. (Both spellings work, we're inclusive here. 🌈)
  • --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. ⚠️
  • --test-disk=/PATH/TO/DISK.IMG — For testing or debugging purposes, replace /dev/sda with a local file. You must use an absolute path. Note that the "Refresh disks" button will be disabled in the "DISK AND NETWORK CONFIGURATION DIALOG" of the GUI. 🧪
  • -v, --verbose — In libguestfs ≥ 1.33.41, debugging is always enabled on the conversion server, and this option does nothing. Rip, honestly. 💀
  • -V, --version — Display version number and exit. 👑

✨ HOW VIRT-P2V WORKS ✨

Okay so heads up bestie: this section is not normative. We may change how virt-p2v works at any time in the future. It's the vibe tour, not the contract 💅

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. Those 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"). Periodt.

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, lscpu, lspci, lsscsi, lsusb — (before conversion)

The output of the corresponding commands (ie. dmesg(1), 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. 🕵️‍♀️

  • environment — (before conversion)

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

  • 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. So like... don't be weird about it 🫶
  • p2v-version, v2v-version — (before conversion)

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

  • 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. No editing it down to the cute parts, okay? 😭

  • virt-v2v-wrapper.sh — (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.

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 nbdkit(1), with nbdkit-file-plugin(1) and socket activation. Obsessed with her honestly 🌸

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     │                 │
 │            ╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍▶               │
 │ nbdkit  ← ─┘ │                      │└─ ← NBD         │
 │ /dev/sda     │                      │     requests    │
 ∼              ∼                      ∼                 ∼
 └──────────────┘                      └─────────────────┘

Okay this next bit is giving plot twist energy: 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 nbdkit 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. Iconic behaviour, no notes 🔥

Two layers of protection are used to ensure that there are no writes to the hard disks: Firstly, the nbdkit -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 "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 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 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. The rest stays on the server doing its little job 💜

🌈 SEE ALSO 🌈

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

👑 AUTHORS 👑

Copyright (C) 2009-2019 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, see <https://www.gnu.org/licenses/>.

🦋 BUGS 🦋

To get a list of bugs against libguestfs (which include virt-p2v), 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 virt-p2v.
  • Where you got virt-p2v (eg. which Linux distro, compiled from source, etc)
  • Describe the bug accurately and give a way to reproduce it.

okay that's the whole page bestie, you ate that 💅✨ this one's the virt-p2v(1) manual page, source/version virt-p2v-1.42.4, dated 2024-11-05 — go forth and convert, ily 🫶💖

📦 where this page comes from