1virt-p2v(1)                 Virtualization Support                 virt-p2v(1)
2
3
4

NAME

6       virt-p2v - Convert a physical machine to use KVM
7

SYNOPSIS

9        virt-p2v
10
11        virt-p2v.iso
12

DESCRIPTION

14       Virt-p2v converts a physical machine to run virtualized on KVM, managed
15       by libvirt, OpenStack, oVirt, Red Hat Virtualisation (RHV), or one of
16       the other targets supported by virt-v2v(1).
17
18       Normally you don’t run the virt-p2v program directly.  Instead you have
19       to boot the physical machine using the bootable CD-ROM, ISO or PXE
20       image.  This bootable image contains the virt-p2v binary and runs it
21       automatically.  Booting from a CD-ROM/etc is required because the disks
22       which are being converted must be quiescent.  It is not safe to try to
23       convert a running physical machine where other programs may be
24       modifying the disk content at the same time.
25
26       This manual page documents running the virt-p2v program.  To create the
27       bootable image you should look at virt-p2v-make-disk(1) or
28       virt-p2v-make-kickstart(1).
29

NETWORK SETUP

31       Virt-p2v runs on the physical machine which you want to convert.  It
32       has to talk to another server called the "conversion server" which must
33       have virt-v2v(1) installed on it.  It always talks to the conversion
34       server over SSH:
35
36        ┌──────────────┐                  ┌─────────────────┐
37        │ virt-p2v     │                  │ virt-v2v        │
38        │ (physical    │  ssh connection  │ (conversion     │
39        │  server)   ╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍▶ server)       │
40        └──────────────┘                  └─────────────────┘
41
42       The virt-v2v program on the conversion server does the actual
43       conversion (physical to virtual, and virtual to virtual conversions are
44       sufficiently similar that we use the same program to do both).
45
46       The SSH connection is always initiated from the physical server.  All
47       data is transferred over the SSH connection.  In terms of firewall and
48       network configuration, you only need to ensure that the physical server
49       has access to a port (usually TCP port 22) on the conversion server.
50       Note that the physical machine may reconnect several times during the
51       conversion process.
52
53       The reverse port forwarding feature of ssh (ie. "ssh -R") is required
54       by virt-p2v, and it will not work if this is disabled on the conversion
55       server.  ("AllowTcpForwarding" must be "yes" in the sshd_config(5) file
56       on the conversion server).
57
58       The scp (secure copy) feature of ssh is required by virt-p2v so it can
59       send over small files (this is not the method by which disks are
60       copied).
61
62       The conversion server does not need to be a physical machine.  It could
63       be a virtual machine, as long as it has sufficient memory and disk
64       space to do the conversion, and as long as the physical machine can
65       connect directly to its SSH port.  (See also "Resource requirements" in
66       virt-v2v(1)).
67
68       Because all of the data on the physical server’s hard drive(s) has to
69       be copied over the network, the speed of conversion is largely
70       determined by the speed of the network between the two machines.
71

GUI INTERACTIVE CONFIGURATION

73       When you start virt-p2v, you'll see a graphical configuration dialog
74       that walks you through connection to the conversion server, asks for
75       the password, which local hard disks you want to convert, and other
76       things like the name of the guest to create and the number of virtual
77       CPUs to give it.
78
79   SSH CONFIGURATION DIALOG
80       When virt-p2v starts up in GUI mode, the first dialog looks like this:
81
82        ┌─────────────────────────────────────────────────────────────┐
83        │                           virt-p2v                          │
84        │                                                             │
85        │ Conversion server: [____________________________] : [22___] │
86        │                                                             │
87        │         User name: [root__________________________________] │
88        │                                                             │
89        │          Password: [______________________________________] │
90        │                                                             │
91        │  SSH Identity URL: [______________________________________] │
92        │                                                             │
93
94       In the fields above, you must enter the details of the conversion
95       server: the hostname, SSH port number, remote user name, and either the
96       password or SSH identity (private key) URL.  The conversion server must
97       have an up to date version of virt-v2v.
98
99       Normally you must log in to the conversion server as root, but if you
100       check the following box:
101
102        │                                                             │
103        │                    [ ] Use sudo when running virt-v2v       │
104        │                                                             │
105
106       then you can log in as another user, and virt-p2v will use the sudo(8)
107       command to elevate privileges to root.  Note that sudo must not require
108       a password.
109
110       It is also possible to run virt-v2v on the conversion server entirely
111       as non-root, but output modes may be limited.  Consult the virt-v2v(1)
112       manual page for details.
113
114       At the bottom of the dialog are these buttons:
115
116        │                                                             │
117        │                     [ Test connection ]                     │
118        │                                                             │
119        │ [ Configure network ] [ XTerm ] [ About virt-p2v ] [ Next ] │
120        │                                                             │
121        └─────────────────────────────────────────────────────────────┘
122
123       You must press the "Test connection" button first to test the SSH
124       connection to the conversion server.  If that is successful (ie. you
125       have supplied the correct server name, user name, password, etc., and a
126       suitable version of virt-v2v is available remotely) then press the
127       "Next" button to move to the next dialog.
128
129       You can use the "Configure network" button if you need to assign a
130       static IP address to the physical machine, or use Wifi, bonding or
131       other network features.
132
133       The "XTerm" button opens a shell which can be used for diagnostics,
134       manual network configuration, and so on.
135
136   DISK AND NETWORK CONFIGURATION DIALOG
137       The second configuration dialog lets you configure the details of
138       conversion, including what to convert and where to send the guest.
139
140       In the left hand column, starting at the top, the target properties let
141       you select the name of the guest (ie. after conversion) and how many
142       virtual CPUs and how much RAM to give it.  The defaults come from the
143       physical machine, and you can usually leave them unchanged:
144
145        ┌─────────────────────────────────────── ─ ─ ─ ─
146        │ Target properties:
147
148        │        Name: [hostname______________]
149
150        │     # vCPUs: [4_____________________]
151
152        │ Memory (MB): [16384_________________]
153
154
155       The second panel on the left controls the virt-v2v output options.  To
156       understand these options it is a really good idea to read the
157       virt-v2v(1) manual page.  You can leave the options at the default to
158       create a guest as a disk image plus libvirt XML file located in
159       /var/tmp on the conversion host.  This is a good idea if you are a
160       first-time virt-p2v user.
161
162
163        │ Virt-v2v output options:
164
165        │          Output to (-o): [local             ▼]
166
167        │      Output conn. (-oc): [___________________]
168
169        │    Output storage (-os): [/var/tmp___________]
170
171        │     Output format (-of): [___________________]
172
173        │ Output allocation (-oa): [sparse            ▼]
174
175
176       All output options and paths are relative to the conversion server (not
177       to the physical server).
178
179       Finally in the left hand column is an information box giving the
180       version of virt-p2v (on the physical server) and virt-v2v (on the
181       conversion server).  You should supply this information when reporting
182       bugs.
183
184       In the right hand column are three panels which control what hard
185       disks, removable media devices, and network interfaces, will be created
186       in the output guest.  Normally leaving these at the default settings is
187       fine.
188
189        ─ ─ ──────────────────────────────────────────────────┐
190            Fixed hard disks                                  │
191
192            Convert  Device                                   │
193            [✔]      sda                                      │
194                     1024G HITACHI                            │
195                     s/n 12345                                │
196            [✔]      sdb                                      │
197                     119G HITACHI                             │
198                     s/n 12346                                │
199
200
201       Normally you would want to convert all hard disks.  If you want
202       virt-p2v to completely ignore a local hard disk, uncheck it.  The hard
203       disk that contains the operating system must be selected.  If a hard
204       disk is part of a RAID array or LVM volume group (VG), then either all
205       hard disks in that array/VG must be selected, or none of them.
206
207
208            Removable media                                   │
209
210            Convert  Device                                   │
211            [✔]      sr0                                      │
212
213
214       If the physical machine has CD or DVD drives, then you can use the
215       Removable media panel to create corresponding drives on the guest after
216       conversion.  Note that any data CDs/DVDs which are mounted in the
217       drives are not copied over.
218
219       At the bottom of the dialog, the "Refresh disks" button instructs
220       virt-p2v to re-enumerate the fixed hard disks and the removable media
221       drives.  (Note that the button will also reset the currently active
222       selections in both of those panels.)  This button is useful in
223       combination with the "XTerm" button on the "SSH CONFIGURATION DIALOG":
224       in the XTerm window, you can expose further block devices to the kernel
225       (such as LUNs from iSCSI targets), and the "Refresh disks" button
226       allows virt-p2v to learn about all the block devices again.
227
228
229            Network interfaces                                │
230
231            Convert  Device Connect to virtual network        │
232            [✔]      em1    [default________________________] │
233            [ ]      wlp3s0 [default________________________] │
234
235
236       In the Network interfaces panel, select the network interfaces that
237       should be created in the guest after conversion.  You can also connect
238       these to target hypervisor networks (for further information about this
239       feature, see "Networks and bridges" in virt-v2v(1)).
240
241       On supported hardware, left-clicking on the device name (eg. "em1")
242       causes a light to start flashing on the physical interface, allowing
243       the interface to be identified by the operator.
244
245       When you are ready to begin the conversion, press the "Start
246       conversion" button:
247
248
249            [ Back ]  [ Refresh disks ]  [ Start conversion ] │
250
251        ─ ─ ──────────────────────────────────────────────────┘
252
253   CONVERSION RUNNING DIALOG
254       When conversion is running you will see this dialog:
255
256        ┌────────────────────────────────────────────────────────┐
257        │                      virt-p2v                          │
258        │                                                        │
259        │  ┌──────────────────────────────────────────────────┐  │
260        │  │                                                 ▲│  │
261        │  │                                                  │  │
262        │  │                                                  │  │
263        ∼  ∼                                                  ∼  ∼
264        │  │                                                  │  │
265        │  │                                                  │  │
266        │  │                                                 ▼│  │
267        │  └──────────────────────────────────────────────────┘  │
268        │                                                        │
269        │ Log files ... to /tmp/virt-p2v-xxx                     │
270        │                                                        │
271        │ Doing conversion ...                                   │
272        │                                                        │
273        │                                 [ Cancel conversion ]  │
274        │                                                        │
275        └────────────────────────────────────────────────────────┘
276
277       In the main scrolling area you will see messages from the virt-v2v
278       process.
279
280       Below the main area, virt-p2v shows you the location of the directory
281       on the conversion server that contains log files and other debugging
282       information.  Below that is the current status and a button for
283       cancelling conversion.
284
285       Once conversion has finished, you should shut down the physical
286       machine.  If conversion is successful, you should never reboot it.
287

KERNEL COMMAND LINE CONFIGURATION

289       If you don’t want to configure things using the graphical UI, an
290       alternative is to configure through the kernel command line.  This is
291       especially convenient if you are converting a lot of physical machines
292       which are booted using PXE.
293
294       Where exactly you set command line arguments depends on your PXE
295       implementation, but for pxelinux you put them in the "APPEND" field in
296       the pxelinux.cfg file.  For example:
297
298        DEFAULT p2v
299        TIMEOUT 20
300        PROMPT 0
301        LABEL p2v
302          KERNEL vmlinuz0
303          APPEND initrd=initrd0.img [....] p2v.server=conv.example.com p2v.password=secret p2v.o=libvirt
304
305       You have to set some or all of the following command line arguments:
306
307       p2v.remote.server=SERVER
308       p2v.server=SERVER
309           The name or IP address of the conversion server.
310
311           This is always required if you are using the kernel configuration
312           method.  If virt-p2v does not find this on the kernel command line
313           then it switches to the GUI (interactive) configuration method.
314
315       p2v.remote.port=PORT
316       p2v.port=PORT
317           The SSH port number on the conversion server (default: 22).
318
319       p2v.auth.username=USERNAME
320       p2v.username=USERNAME
321           The SSH username that we log in as on the conversion server
322           (default: "root").
323
324       p2v.auth.password=PASSWORD
325       p2v.password=PASSWORD
326           The SSH password that we use to log in to the conversion server.
327
328           The default is to try with no password.  If this fails then
329           virt-p2v will ask the user to type the password (probably several
330           times during conversion).
331
332           This setting is ignored if "p2v.auth.identity.url" is present.
333
334       p2v.auth.identity.url=URL
335       p2v.identity=URL
336           Provide a URL pointing to an SSH identity (private key) file.  The
337           URL is interpreted by curl(1) so any URL that curl supports can be
338           used here, including "https://" and "file://".  For more
339           information on using SSH identities, see "SSH IDENTITIES" below.
340
341           If "p2v.auth.identity.url" is present, it overrides
342           "p2v.auth.password".  There is no fallback.
343
344       p2v.auth.sudo
345       p2v.sudo
346           Use "p2v.sudo" to tell virt-p2v to use sudo(8) to gain root
347           privileges on the conversion server after logging in as a non-root
348           user (default: do not use sudo).
349
350       p2v.guestname=GUESTNAME
351       p2v.name=GUESTNAME
352           The name of the guest that is created.  The default is to try to
353           derive a name from the physical machine’s hostname (if possible)
354           else use a randomly generated name.
355
356       p2v.vcpu.phys_topo
357           Copy the physical machine's complete CPU topology (sockets, cores
358           and threads) to the guest.  Disabled by default.  If disabled, the
359           "p2v.vcpu.cores" setting takes effect.
360
361       p2v.vcpu.cores=N
362           This setting is ignored if "p2v.vcpu.phys_topo" is enabled.
363           Otherwise, it specifies the flat number of vCPU cores to give to
364           the guest (placing all of those cores into a single socket, and
365           exposing one thread per core).  The default value is the number of
366           online logical processors on the physical machine.
367
368       p2v.memory=n(M|G)
369           The size of the guest memory.  You must specify the unit such as
370           megabytes or gigabytes by using for example "p2v.memory=1024M" or
371           "p2v.memory=1G".
372
373           The default is to use the same amount of RAM as on the physical
374           machine.
375
376       p2v.cpu.vendor=VENDOR
377           The vCPU vendor, eg. "Intel" or "AMD".  The default is to use the
378           same CPU vendor as the physical machine.
379
380       p2v.cpu.model=MODEL
381           The vCPU model, eg. "IvyBridge".  The default is to use the same
382           CPU model as the physical machine.
383
384       p2v.cpu.acpi
385           Whether to enable ACPI in the remote virtual machine.  The default
386           is to use the same as the physical machine.
387
388       p2v.cpu.apic
389           Whether to enable APIC in the remote virtual machine.  The default
390           is to use the same as the physical machine.
391
392       p2v.cpu.pae
393           Whether to enable PAE in the remote virtual machine.  The default
394           is to use the same as the physical machine.
395
396       p2v.rtc.basis=(unknown|utc|localtime)
397           Set the basis of the Real Time Clock in the virtual machine.  The
398           default is to try to detect this setting from the physical machine.
399
400       p2v.rtc.offset=[+|-]HOURS
401           The offset of the Real Time Clock from UTC.  The default is to try
402           to detect this setting from the physical machine.
403
404       p2v.disks=sda,sdb,...
405           A list of physical hard disks to convert, for example:
406
407            p2v.disks=sda,sdc
408
409           The default is to convert all local hard disks that are found.
410
411       p2v.removable=sra,srb,...
412           A list of removable media to convert.  The default is to create
413           virtual removable devices for every physical removable device
414           found.  Note that the content of removable media is never copied
415           over.
416
417       p2v.interfaces=em1,...
418           A list of network interfaces to convert.  The default is to create
419           virtual network interfaces for every physical network interface
420           found.
421
422       p2v.network_map=interface:target,...
423       p2v.network=interface:target,...
424           Controls how network interfaces are connected to virtual networks
425           on the target hypervisor.  The default is to connect all network
426           interfaces to the target "default" network.
427
428           You give a comma-separated list of "interface:target" pairs, plus
429           optionally a default target.  For example:
430
431            p2v.network=em1:ovirtmgmt
432
433           maps interface "em1" to target network "ovirtmgmt".
434
435            p2v.network=em1:ovirtmgmt,em2:management,other
436
437           maps interface "em1" to "ovirtmgmt", and "em2" to "management", and
438           any other interface that is found to "other".
439
440       p2v.output.type=(libvirt|local|...)
441       p2v.o=(libvirt|local|...)
442           Set the output mode.  This is the same as the virt-v2v -o option.
443           See "OPTIONS" in virt-v2v(1).
444
445           If not specified, the default is "local", and the converted guest
446           is written to /var/tmp.
447
448       p2v.output.allocation=(none|sparse|preallocated)
449       p2v.oa=(none|sparse|preallocated)
450           Set the output allocation mode.  This is the same as the virt-v2v
451           -oa option.  See "OPTIONS" in virt-v2v(1).
452
453       p2v.output.connection=URI
454       p2v.oc=URI
455           Set the output connection libvirt URI.  This is the same as the
456           virt-v2v -oc option.  See "OPTIONS" in virt-v2v(1) and
457           http://libvirt.org/uri.html
458
459       p2v.output.format=(raw|qcow2|...)
460       p2v.of=(raw|qcow2|...)
461           Set the output format.  This is the same as the virt-v2v -of
462           option.  See "OPTIONS" in virt-v2v(1).
463
464       p2v.output.storage=STORAGE
465       p2v.os=STORAGE
466           Set the output storage.  This is the same as the virt-v2v -os
467           option.  See "OPTIONS" in virt-v2v(1).
468
469           If not specified, the default is /var/tmp (on the conversion
470           server).
471
472       p2v.pre=COMMAND
473       p2v.pre="COMMAND ARG ..."
474           Select a pre-conversion command to run.  Any command or script can
475           be specified here.  If the command contains spaces, you must quote
476           the whole command with double quotes.  The default is not to run
477           any command.
478
479       p2v.post=poweroff
480       p2v.post=reboot
481       p2v.post=COMMAND
482       p2v.post="COMMAND ARG ..."
483           Select a post-conversion command to run if conversion is
484           successful.  This can be any command or script.  If the command
485           contains spaces, you must quote the whole command with double
486           quotes.
487
488           If virt-p2v is running as root, and the command line was set from
489           /proc/cmdline (not --cmdline), then the default is to run the
490           poweroff(8) command.  Otherwise the default is not to run any
491           command.
492
493       p2v.fail=COMMAND
494       p2v.fail="COMMAND ARG ..."
495           Select a post-conversion command to run if conversion fails.  Any
496           command or script can be specified here.  If the command contains
497           spaces, you must quote the whole command with double quotes.  The
498           default is not to run any command.
499
500       ip=dhcp
501           Use DHCP for configuring the network interface (this is the
502           default).
503

SSH IDENTITIES

505       As a somewhat more secure alternative to password authentication, you
506       can use an SSH identity (private key) for authentication.
507
508       First create a key pair.  It must have an empty passphrase:
509
510        ssh-keygen -t rsa -N '' -f id_rsa
511
512       This creates a private key ("id_rsa") and a public key ("id_rsa.pub")
513       pair.
514
515       The public key should be appended to the "authorized_keys" file on the
516       virt-v2v conversion server (usually to "/root/.ssh/authorized_keys").
517
518       For distributing the private key, there are four scenarios from least
519       secure to most secure:
520
521       1.  Not using SSH identities at all, ie. password authentication.
522
523           Anyone who can sniff the PXE boot parameters from the network or
524           observe the password some other way can log in to the virt-v2v
525           conversion server.
526
527       2.  SSH identity embedded in the virt-p2v ISO or disk image.  In the
528           GUI, use:
529
530            │          Password: [    <leave this field blank>       ] │
531            │                                                          │
532            │  SSH Identity URL: [file:///var/tmp/id_rsa_____________] │
533
534           or on the kernel command line:
535
536            p2v.identity=file:///var/tmp/id_rsa
537
538           The SSH private key can still be sniffed from the network if using
539           standard PXE.
540
541       3.  SSH identity downloaded from a website.  In the GUI, use:
542
543            │          Password: [    <leave this field blank>       ] │
544            │                                                          │
545            │  SSH Identity URL: [https://internal.example.com/id_rsa] │
546
547           or on the kernel command line:
548
549            p2v.identity=https://internal.example.com/id_rsa
550
551           Anyone could still download the private key and use it to log in to
552           the virt-v2v conversion server, but you could provide some extra
553           security by configuring the web server to only allow connections
554           from P2V machines.
555
556           Note that ssh-keygen(1) creates the "id_rsa" (private key) file
557           with mode 0600.  If you simply copy the file to a webserver, the
558           webserver will not serve it.  It will reply with "403 Forbidden"
559           errors.  You will need to change the mode of the file to make it
560           publicly readable, for example by using:
561
562            chmod 0644 id_rsa
563
564       4.  SSH identity embedded in the virt-p2v ISO or disk image (like 2.),
565           and use of secure PXE, PXE over separate physical network, or
566           sneakernet to distribute virt-p2v to the physical machine.
567
568       Both virt-p2v-make-disk(1) and virt-p2v-make-kickstart(1) have the same
569       option --inject-ssh-identity for injecting the private key into the
570       virt-p2v disk image / ISO.  See also the following manual sections:
571
572       "ADDING AN SSH IDENTITY" in virt-p2v-make-disk(1)
573
574       "ADDING AN SSH IDENTITY" in virt-p2v-make-kickstart(1)
575

ACCESSING ISCSI DEVICES

577       In case the disk that contains the operating system, or other disks
578       that you want to convert, are LUNs of remote iSCSI targets, follow the
579       steps below so that virt-p2v can learn about said disks.  Note that
580       this procedure depends on the use of the GUI.
581
582       The guide below is roughly based on the RHEL9 product documentation.
583
584       1.  Open a shell in an XTerm window, using the "XTerm" button of the
585           "SSH CONFIGURATION DIALOG".
586
587           (Note that the XTerm window(s) persist while you advance to further
588           dialogs in virt-p2v, therefore it's unnecessary to jump back and
589           forth between virt-p2v dialogs just for entering additional shell
590           commands in the XTerm window(s).)
591
592       2.  Using "vi" or another text editor, set the iSCSI initiator name in
593           /etc/iscsi/initiatorname.iscsi, for example:
594
595            InitiatorName=iqn.1994-05.com.redhat:846e82c634
596
597           If the file does not exist, create it.  (Remember that this file is
598           part of the virt-p2v Live environment, therefore saving it does not
599           modify any hard disks.)
600
601       3.  Configure any further iSCSI initiator details completely that are
602           required by the iSCSI target that you intend to log in to; that is,
603           before you issue the first "iscsiadm" command below.  This includes
604           the CHAP user name and password if the target authenticates the
605           initiator with CHAP, and the reverse direction CHAP user name and
606           password too, if you want to ascertain the identity of the target
607           on the initiator as well (this is called "mutual authentication").
608
609           Completing the configuration at this stage is important because the
610           first "iscsiadm" command will start up the "iscsid" service, and
611           configuration changes with that service already running will not
612           (or may not) take effect until/unless you restart the service using
613           "systemctl".
614
615       4.  Discover the iSCSI targets offered by the desired host:
616
617            iscsiadm -m discovery -t st -p IP_ADDRESS
618
619           The command should respond with a two-column list of targets.  The
620           symbolic target names are in the right hand side column, for
621           example:
622
623                10.64.24.179:3260,1 iqn.2006-04.example:444
624
625       5.  Picking an appropriate target from the right hand side column of
626           the previous step's output, log in to the target:
627
628            iscsiadm -m node -T TARGET -l
629
630           This command will inform you whether the login attempt was
631           successful.
632
633       6.  In case the login succeeds, a scan for LUNs on the iSCSI target
634           will commence at once.  There are two pitfalls here.  One,
635           dependent on network characteristics, the scan may take several
636           (tens of) seconds.  Two, even if the login succeeds, ACLs on the
637           target may silently prevent the initiator from seeing particular
638           LUNs -- meaning that no new /dev/sdX nodes will appear.  This is
639           why it is important to get the initiator name (and, potentially,
640           CHAP authentication) correct at the very beginning of this
641           procedure.
642
643           Verify the results of the target scan with the "dmesg" command,
644           and/or with
645
646            ls -l /dev/disk/by-path/ip-*-iscsi-*-lun-*
647
648           If these symlinks exist, containing the "IP_ADDRESS" from step 4
649           and the "TARGET" name from step 5 in their filenames, then the
650           target scan has successfully found the corresponding LUNs.
651
652       7.  Once the remote LUNs have been successfully enumerated, click the
653           "Refresh disks" button in the "DISK AND NETWORK CONFIGURATION
654           DIALOG".
655

COMMON PROBLEMS

657   Timeouts
658       As described below (see "HOW VIRT-P2V WORKS") virt-p2v makes several
659       long-lived ssh connections to the conversion server.  If these
660       connections time out then virt-p2v will fail.
661
662       To test if a timeout might be causing problems, open an XTerm on the
663       virt-p2v machine, "ssh root@conversion-server", and leave it for at
664       least an hour.  If the session disconnects without you doing anything,
665       then there is a timeout which you should turn off.
666
667       Timeouts happen because:
668
669       "TIMEOUT" or "TMOUT" environment variable
670           Check if one of these environment variables is set in the root
671           shell on the conversion server.
672
673       sshd "ClientAlive*" setting
674           Check for "ClientAlive*" settings in "/etc/ssh/sshd_config" on the
675           conversion server.
676
677       Firewall or NAT settings
678           Check if there is a firewall or NAT box between virt-p2v and the
679           conversion server, and if this firewall drops idle connections
680           after a too-short time.
681
682           virt-p2v ≥ 1.36 attempts to work around firewall timeouts by
683           sending ssh keepalive messages every 5 minutes.
684

OPTIONS

686       --help
687           Display help.
688
689       --cmdline=CMDLINE
690           This is used for debugging. Instead of parsing the kernel command
691           line from /proc/cmdline, parse the string parameter "CMDLINE".
692
693       --colors
694       --colours
695           Use ANSI colour sequences to colourize messages.  This is the
696           default when the output is a tty.  If the output of the program is
697           redirected to a file, ANSI colour sequences are disabled unless you
698           use this option.
699
700       --iso
701           This flag is passed to virt-p2v when it is launched inside the
702           virt-p2v ISO environment, ie. when it is running on a real physical
703           machine (and thus not when testing).  It enables various dangerous
704           features such as the Shutdown popup button.
705
706       --test-disk=/PATH/TO/DISK.IMG
707           For testing or debugging purposes, replace /dev/sda with a local
708           file.  You must use an absolute path.  Note that the "Refresh
709           disks" button will be disabled in the "DISK AND NETWORK
710           CONFIGURATION DIALOG" of the GUI.
711
712       -v
713       --verbose
714           In libguestfs ≥ 1.33.41, debugging is always enabled on the
715           conversion server, and this option does nothing.
716
717       -V
718       --version
719           Display version number and exit.
720

HOW VIRT-P2V WORKS

722       Note this section is not normative.  We may change how virt-p2v works
723       at any time in the future.
724
725       As described above, virt-p2v runs on a physical machine, interrogates
726       the user or the kernel command line for configuration, and then
727       establishes one or more ssh connections to the virt-v2v conversion
728       server.  The ssh connections are interactive shell sessions to the
729       remote host, but the commands sent are generated entirely by virt-p2v
730       itself, not by the user.  For data transfer, virt-p2v will use the
731       reverse port forward feature of ssh (ie. "ssh -R").
732
733       It will first make one or more test connections, which are used to
734       query the remote version of virt-v2v and its features.  The test
735       connections are closed before conversion begins.
736
737        ┌──────────────┐                      ┌─────────────────┐
738        │ virt-p2v     │                      │ virt-v2v        │
739        │ (physical    │  control connection  │ (conversion     │
740        │  server)   ╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍▶ server)       │
741        └──────────────┘                      └─────────────────┘
742
743       Once virt-p2v is ready to start conversion, it will open a single ssh
744       control connection.  It first sends a mkdir command to create a
745       temporary directory on the conversion server.  The directory name is
746       randomly chosen and is displayed in the GUI.  It has the form:
747
748        /tmp/virt-p2v-YYYYMMDD-XXXXXXXX
749
750       where "YYYYMMDD" is the current date, and the ‘X’s are random
751       characters.
752
753       Into this directory are written various files which include:
754
755       dmesg
756       lscpu
757       lspci
758       lsscsi
759       lsusb
760           (before conversion)
761
762           The output of the corresponding commands (ie dmesg(1), lscpu(1)
763           etc) on the physical machine.
764
765           The dmesg output is useful for detecting problems such as missing
766           device drivers or firmware on the virt-p2v ISO.  The others are
767           useful for debugging novel hardware configurations.
768
769       environment
770           (before conversion)
771
772           The content of the environment where virt-v2v(1) will run.
773
774       name
775           (before conversion)
776
777           The name (usually the hostname) of the physical machine.
778
779       physical.xml
780           (before conversion)
781
782           Libvirt XML describing the physical machine.  It is used to pass
783           data about the physical source host to virt-v2v(1) via the -i
784           libvirtxml option.
785
786           Note this is not "real" libvirt XML (and must never be loaded into
787           libvirt, which would reject it anyhow).  Also it is not the same as
788           the libvirt XML which virt-v2v generates in certain output modes.
789
790       p2v-version
791       v2v-version
792           (before conversion)
793
794           The versions of virt-p2v and virt-v2v respectively.
795
796       status
797           (after conversion)
798
799           The final status of the conversion.  0 if the conversion was
800           successful.  Non-zero if the conversion failed.
801
802       time
803           (before conversion)
804
805           The start date/time of conversion.
806
807       virt-v2v-conversion-log.txt
808           (during/after conversion)
809
810           The conversion log.  This is just the output of the virt-v2v
811           command on the conversion server.  If conversion fails, you should
812           examine this log file, and you may be asked to supply the complete,
813           unedited log file in any bug reports or support tickets.
814
815       virt-v2v-wrapper.sh
816           (before conversion)
817
818           This is the wrapper script which is used when running virt-v2v.
819           For interest only, do not attempt to run this script yourself.
820
821       Before conversion actually begins, virt-p2v then makes one or more
822       further ssh connections to the server for data transfer.
823
824       The transfer protocol used currently is NBD (Network Block Device),
825       which is proxied over ssh.  The NBD server is nbdkit(1), with
826       nbdkit-file-plugin(1) and socket activation.
827
828       There is one ssh connection per physical hard disk on the source
829       machine (the common case — a single hard disk — is shown below):
830
831        ┌──────────────┐                      ┌─────────────────┐
832        │ virt-p2v     │                      │ virt-v2v        │
833        │ (physical    │  control connection  │ (conversion     │
834        │  server)   ╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍▶ server)       │
835        │              │                      │                 │
836        │              │  data connection     │                 │
837        │            ╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍▶               │
838        │ nbdkit  ← ─┘ │                      │└─ ← NBD         │
839        │ /dev/sda     │                      │     requests    │
840        ∼              ∼                      ∼                 ∼
841        └──────────────┘                      └─────────────────┘
842
843       Although the ssh data connection is originated from the physical server
844       and terminates on the conversion server, in fact NBD requests flow in
845       the opposite direction.  This is because the reverse port forward
846       feature of ssh ("ssh -R") is used to open a port on the loopback
847       interface of the conversion server which is proxied back by ssh to
848       nbdkit running on the physical machine.  The effect is that virt-v2v
849       via libguestfs can open nbd connections which directly read the hard
850       disk(s) of the physical server.
851
852       Two layers of protection are used to ensure that there are no writes to
853       the hard disks: Firstly, the nbdkit -r (readonly) option is used.
854       Secondly libguestfs creates an overlay on top of the NBD connection
855       which stores writes in a temporary file on the conversion file.
856
857       The long "virt-v2v -i libvirtxml physical.xml ..." command is wrapped
858       inside a wrapper script and uploaded to the conversion server.  The
859       final step is to run this wrapper script, in turn running the virt-v2v
860       command.  The virt-v2v command references the physical.xml file (see
861       above), which in turn references the NBD listening port(s) of the data
862       connection(s).
863
864       Output from the virt-v2v command (messages, debugging etc) is saved in
865       the log file on the conversion server.  Only informational messages are
866       sent back over the control connection to be displayed in the graphical
867       UI.
868

SEE ALSO

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

AUTHORS

875       Matthew Booth
876
877       John Eckersberg
878
879       Richard W.M. Jones http://people.redhat.com/~rjones/
880
881       Mike Latimer
882
883       Pino Toscano
884
885       Tingting Zheng
886
888       Copyright (C) 2009-2019 Red Hat Inc.
889

LICENSE

891       This program is free software; you can redistribute it and/or modify it
892       under the terms of the GNU General Public License as published by the
893       Free Software Foundation; either version 2 of the License, or (at your
894       option) any later version.
895
896       This program is distributed in the hope that it will be useful, but
897       WITHOUT ANY WARRANTY; without even the implied warranty of
898       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
899       General Public License for more details.
900
901       You should have received a copy of the GNU General Public License along
902       with this program.  If not, see <https://www.gnu.org/licenses/>.
903

BUGS

905       To get a list of bugs against libguestfs (which include virt-p2v), use
906       this link:
907       https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
908
909       To report a new bug against libguestfs, use this link:
910       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
911
912       When reporting a bug, please supply:
913
914       •   The version of virt-p2v.
915
916       •   Where you got virt-p2v (eg. which Linux distro, compiled from
917           source, etc)
918
919       •   Describe the bug accurately and give a way to reproduce it.
920
921
922
923virt-p2v-1.42.3                   2023-01-21                       virt-p2v(1)
Impressum