.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Podwrapper::Man 2.4.0 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "virt-v2v-in-place 1" .TH virt-v2v-in-place 1 2024-03-15 virt-v2v-2.4.0 "Virtualization Support" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME virt\-v2v\-in\-place \- Convert a guest to use KVM in\-place .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& virt\-v2v\-in\-place \-i disk [other \-i* options] filename \& \& virt\-v2v\-in\-place \-i libvirt|libvirtxml [other \-i* options] guest .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" Virt\-v2v\-in\-place converts a single guest from a foreign hypervisor to run on KVM. It does this conversion in place, modifying the original disk. .PP This manual page only documents the differences between this tool and virt\-v2v. You should read \fBvirt\-v2v\fR\|(1) first. .SS "Selecting the input disk" .IX Subsection "Selecting the input disk" You normally run virt\-v2v with one or more \fI\-i*\fR options controlling the input mode. Virt\-v2v\-in\-place can only convert guests stored in local files. .PP This command will do an in-place conversion of \fIfilename.img\fR: .PP .Vb 1 \& virt\-v2v\-in\-place \-i disk filename.img .Ve .PP If the guest has been copied to local libvirt then: .PP .Vb 1 \& virt\-v2v\-in\-place \-i libvirt guest .Ve .SH EXAMPLES .IX Header "EXAMPLES" .SH OPTIONS .IX Header "OPTIONS" .IP \fB\-\-help\fR 4 .IX Item "--help" Display help. .IP "\fB\-b\fR ..." 4 .IX Item "-b ..." .PD 0 .IP "\fB\-\-bridge\fR ..." 4 .IX Item "--bridge ..." .PD See \fI\-\-network\fR below. .IP "\fB\-\-block\-driver\fR \fBvirtio-blk\fR" 4 .IX Item "--block-driver virtio-blk" .PD 0 .IP "\fB\-\-block\-driver\fR \fBvirtio-scsi\fR" 4 .IX Item "--block-driver virtio-scsi" .PD When choosing a block driver for Windows guests, prefer \f(CW\*(C`virtio\-blk\*(C'\fR or \&\f(CW\*(C`virtio\-scsi\*(C'\fR. The default is \f(CW\*(C`virtio\-blk\*(C'\fR. .Sp Note this has no effect for Linux guests at the moment. That may be added in future. .IP \fB\-\-colors\fR 4 .IX Item "--colors" .PD 0 .IP \fB\-\-colours\fR 4 .IX Item "--colours" .PD 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. .IP \fB\-\-echo\-keys\fR 4 .IX Item "--echo-keys" When prompting for keys and passphrases, virt\-v2v normally turns echoing off so you cannot see what you are typing. If you are not worried about Tempest attacks and there is no one else in the room you can specify this flag to see what you are typing. .Sp Note this options only applies to keys and passphrases for encrypted devices and partitions, not for passwords used to connect to remote servers. .IP "\fB\-i\fR \fBdisk\fR" 4 .IX Item "-i disk" Set the input method to \fIdisk\fR. .Sp In this mode you can read a virtual machine disk image with no metadata. virt\-v2v tries to guess the best default metadata. This is usually adequate but you can get finer control (eg. of memory and vCPUs) by using \fI\-i libvirtxml\fR instead. Only guests that use a single disk can be imported this way. .IP "\fB\-i\fR \fBlibvirt\fR" 4 .IX Item "-i libvirt" Set the input method to \fIlibvirt\fR. This is the default. .Sp In this mode you have to specify a libvirt guest name or UUID on the command line. You may also specify a libvirt connection URI (see \&\fI\-ic\fR). .IP "\fB\-i\fR \fBlibvirtxml\fR" 4 .IX Item "-i libvirtxml" Set the input method to \fIlibvirtxml\fR. .Sp In this mode you have to pass a libvirt XML file on the command line. This file is read in order to get metadata about the source guest (such as its name, amount of memory), and also to locate the input disks. See "Minimal XML for \-i libvirtxml option" below. .IP "\fB\-i\fR \fBlocal\fR" 4 .IX Item "-i local" This is the same as \fI\-i disk\fR. .IP "\fB\-ic\fR libvirtURI" 4 .IX Item "-ic libvirtURI" Specify a libvirt connection URI to use when reading the guest. This is only used when \fI\-i\ libvirt\fR. .Sp Only local libvirt connections to locally stored disks can be used. .IP "\fB\-if\fR format" 4 .IX Item "-if format" For \fI\-i disk\fR only, this specifies the format of the input disk image. For other input methods you should specify the input format in the metadata. .IP "\fB\-io\fR OPTION=VALUE" 4 .IX Item "-io OPTION=VALUE" Set input option(s) related to the current input mode or transport. To display short help on what options are available you can use: .Sp .Vb 1 \& virt\-v2v\-in\-place \-it disk \-io "?" .Ve .IP "\fB\-ip\fR filename" 4 .IX Item "-ip filename" Supply a file containing a password to be used when connecting to the source. If this is omitted then the input hypervisor may ask for the password interactively. Note the file should contain the whole password, \fBwithout any trailing newline\fR, and for security the file should have mode \f(CW0600\fR so that others cannot read it. .IP "\fB\-\-key\fR SELECTOR" 4 .IX Item "--key SELECTOR" Specify a key for LUKS, to automatically open a LUKS device when using the inspection. .RS 4 .IP "\fB\-\-key\fR NAME\fB:key:\fRKEY_STRING" 4 .IX Item "--key NAME:key:KEY_STRING" .PD 0 .IP "\fB\-\-key\fR UUID\fB:key:\fRKEY_STRING" 4 .IX Item "--key UUID:key:KEY_STRING" .IP "\fB\-\-key\fR \fBall:key:\fRKEY_STRING" 4 .IX Item "--key all:key:KEY_STRING" .PD \&\f(CW\*(C`NAME\*(C'\fR is the libguestfs device name (eg. \f(CW\*(C`/dev/sda1\*(C'\fR). \f(CW\*(C`UUID\*(C'\fR is the device UUID. \f(CW\*(C`all\*(C'\fR means try the key against any encrypted device. .Sp Use the specified \f(CW\*(C`KEY_STRING\*(C'\fR as passphrase. .IP "\fB\-\-key\fR NAME\fB:file:\fRFILENAME" 4 .IX Item "--key NAME:file:FILENAME" .PD 0 .IP "\fB\-\-key\fR UUID\fB:file:\fRFILENAME" 4 .IX Item "--key UUID:file:FILENAME" .IP "\fB\-\-key\fR \fBall:file:\fRFILENAME" 4 .IX Item "--key all:file:FILENAME" .PD Read the passphrase from \fIFILENAME\fR. .IP "\fB\-\-key\fR NAME\fB:clevis\fR" 4 .IX Item "--key NAME:clevis" .PD 0 .IP "\fB\-\-key\fR UUID\fB:clevis\fR" 4 .IX Item "--key UUID:clevis" .IP "\fB\-\-key\fR \fBall:clevis\fR" 4 .IX Item "--key all:clevis" .PD Attempt passphrase-less unlocking for the device with Clevis, over the network. Please refer to "ENCRYPTED DISKS" in \fBguestfs\fR\|(3) for more information on network-bound disk encryption (NBDE). .Sp Note that if any such option is present on the command line, QEMU user networking will be automatically enabled for the libguestfs appliance. .RE .RS 4 .RE .IP \fB\-\-keys\-from\-stdin\fR 4 .IX Item "--keys-from-stdin" Read key or passphrase parameters from stdin. The default is to try to read passphrases from the user by opening \fI/dev/tty\fR. .Sp If there are multiple encrypted devices then you may need to supply multiple keys on stdin, one per line. .Sp Note \fI\-\-keys\-from\-stdin\fR only applies to keys and passphrases for encrypted devices and partitions, not for passwords used to connect to remote servers. .IP "\fB\-\-mac\fR aa:bb:cc:dd:ee:ff\fB:network:\fRout" 4 .IX Item "--mac aa:bb:cc:dd:ee:ff:network:out" .PD 0 .IP "\fB\-\-mac\fR aa:bb:cc:dd:ee:ff\fB:bridge:\fRout" 4 .IX Item "--mac aa:bb:cc:dd:ee:ff:bridge:out" .PD Map source NIC MAC address to a network or bridge. .Sp See "Networks and bridges" in \fBvirt\-v2v\fR\|(1). .IP "\fB\-\-mac\fR aa:bb:cc:dd:ee:ff\fB:ip:\fRipaddr[,gw[,len[,ns,ns,...]]]" 4 .IX Item "--mac aa:bb:cc:dd:ee:ff:ip:ipaddr[,gw[,len[,ns,ns,...]]]" Force a particular interface (controlled by its MAC address) to have a static IP address after boot. .Sp The fields in the parameter are: \f(CW\*(C`ipaddr\*(C'\fR is the IP address. \f(CW\*(C`gw\*(C'\fR is the optional gateway IP address. \f(CW\*(C`len\*(C'\fR is the subnet mask length (an integer). The final parameters are zero or more nameserver IP addresses. .Sp This option can be supplied zero or more times. .Sp You only need to use this option for certain broken guests such as Windows which are unable to preserve MAC to static IP address mappings automatically. You don't need to use it if Windows is using DHCP. It is currently ignored for Linux guests since they do not have this problem. .IP \fB\-\-machine\-readable\fR 4 .IX Item "--machine-readable" .PD 0 .IP \fB\-\-machine\-readable\fR=format 4 .IX Item "--machine-readable=format" .PD This option is used to make the output more machine friendly when being parsed by other programs. See "Machine readable output" in \fBvirt\-v2v\fR\|(1). .IP "\fB\-n\fR in:out" 4 .IX Item "-n in:out" .PD 0 .IP "\fB\-n\fR out" 4 .IX Item "-n out" .IP "\fB\-\-network\fR in:out" 4 .IX Item "--network in:out" .IP "\fB\-\-network\fR out" 4 .IX Item "--network out" .IP "\fB\-b\fR in:out" 4 .IX Item "-b in:out" .IP "\fB\-b\fR out" 4 .IX Item "-b out" .IP "\fB\-\-bridge\fR in:out" 4 .IX Item "--bridge in:out" .IP "\fB\-\-bridge\fR out" 4 .IX Item "--bridge out" .PD Map network (or bridge) called \f(CW\*(C`in\*(C'\fR to network (or bridge) called \&\f(CW\*(C`out\*(C'\fR. If no \f(CW\*(C`in:\*(C'\fR prefix is given, all other networks (or bridges) are mapped to \f(CW\*(C`out\*(C'\fR. .Sp See "Networks and bridges" in \fBvirt\-v2v\fR\|(1). .IP \fB\-\-print\-source\fR 4 .IX Item "--print-source" Print information about the source guest and stop. This option is useful when you are setting up network and bridge maps. See "Networks and bridges" in \fBvirt\-v2v\fR\|(1). .IP \fB\-q\fR 4 .IX Item "-q" .PD 0 .IP \fB\-\-quiet\fR 4 .IX Item "--quiet" .PD This disables progress bars and other unnecessary output. .IP "\fB\-\-root ask\fR" 4 .IX Item "--root ask" .PD 0 .IP "\fB\-\-root single\fR" 4 .IX Item "--root single" .IP "\fB\-\-root first\fR" 4 .IX Item "--root first" .IP "\fB\-\-root\fR /dev/sdX" 4 .IX Item "--root /dev/sdX" .IP "\fB\-\-root\fR /dev/VG/LV" 4 .IX Item "--root /dev/VG/LV" .PD Choose the root filesystem to be converted. .Sp In the case where the virtual machine is dual-boot or multi-boot, or where the VM has other filesystems that look like operating systems, this option can be used to select the root filesystem (a.k.a. \f(CW\*(C`C:\*(C'\fR drive or \fI/\fR) of the operating system that is to be converted. The Windows Recovery Console, certain attached DVD drives, and bugs in libguestfs inspection heuristics, can make a guest look like a multi-boot operating system. .Sp The default in virt\-v2v ≤ 0.7.1 was \fI\-\-root\ single\fR, which causes virt\-v2v to die if a multi-boot operating system is found. .Sp Since virt\-v2v ≥ 0.7.2 the default is now \fI\-\-root\ ask\fR: If the VM is found to be multi-boot, then virt\-v2v will stop and list the possible root filesystems and ask the user which to use. This requires that virt\-v2v is run interactively. .Sp \&\fI\-\-root\ first\fR means to choose the first root device in the case of a multi-boot operating system. Since this is a heuristic, it may sometimes choose the wrong one. .Sp You can also name a specific root device, eg. \fI\-\-root\ /dev/sda2\fR would mean to use the second partition on the first hard drive. If the named root device does not exist or was not detected as a root device, then virt\-v2v will fail. .Sp Note that there is a bug in grub which prevents it from successfully booting a multiboot system if virtio is enabled. Grub is only able to boot an operating system from the first virtio disk. Specifically, \&\fI/boot\fR must be on the first virtio disk, and it cannot chainload an OS which is not in the first virtio disk. .IP \fB\-v\fR 4 .IX Item "-v" .PD 0 .IP \fB\-\-verbose\fR 4 .IX Item "--verbose" .PD Enable verbose messages for debugging. .IP \fB\-V\fR 4 .IX Item "-V" .PD 0 .IP \fB\-\-version\fR 4 .IX Item "--version" .PD Display version number and exit. .IP \fB\-\-wrap\fR 4 .IX Item "--wrap" Wrap error, warning, and informative messages. This is the default when the output is a tty. If the output of the program is redirected to a file, wrapping is disabled unless you use this option. .IP \fB\-x\fR 4 .IX Item "-x" Enable tracing of libguestfs API calls. .SS "Minimal XML for \-i libvirtxml option" .IX Subsection "Minimal XML for -i libvirtxml option" When using the \fI\-i libvirtxml\fR option, you have to supply some libvirt XML. Writing this from scratch is hard, so the template below is helpful. .PP \&\fBNote this should only be used for testing and/or where you know what you're doing!\fR If you have libvirt metadata for the guest, always use that instead. .PP .Vb 10 \& \& NAME \& 1048576 \& 2 \& \& hvm \& \& \& \& \& \& \& \& \& \& \& \& \& \& \& \& \& \& \& \& .Ve .SH FILES .IX Header "FILES" Files used are the same as for virt\-v2v. See "FILES" in \fBvirt\-v2v\fR\|(1). .SH "ENVIRONMENT VARIABLES" .IX Header "ENVIRONMENT VARIABLES" Environment variables used are the same as for virt\-v2v. See "ENVIRONMENT VARIABLES" in \fBvirt\-v2v\fR\|(1). .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBvirt\-v2v\fR\|(1), \&\fBvirt\-p2v\fR\|(1), \&\fBguestfs\fR\|(3), \&\fBguestfish\fR\|(1), \&\fBqemu\-img\fR\|(1), \&\fBnbdkit\fR\|(1), http://libguestfs.org/. .SH AUTHORS .IX Header "AUTHORS" Matthew Booth .PP Cédric Bosdonnat .PP Laszlo Ersek .PP Tomáš Golembiovský .PP Shahar Havivi .PP Richard W.M. Jones .PP Roman Kagan .PP Mike Latimer .PP Nir Soffer .PP Pino Toscano .PP Xiaodai Wang .PP Ming Xie .PP Tingting Zheng .SH COPYRIGHT .IX Header "COPYRIGHT" Copyright (C) 2009\-2022 Red Hat Inc. .SH LICENSE .IX Header "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. .PP 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. .PP 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. .SH BUGS .IX Header "BUGS" To get a list of bugs against libguestfs, use this link: https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools .PP To report a new bug against libguestfs, use this link: https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools .PP When reporting a bug, please supply: .IP \(bu 4 The version of libguestfs. .IP \(bu 4 Where you got libguestfs (eg. which Linux distro, compiled from source, etc) .IP \(bu 4 Describe the bug accurately and give a way to reproduce it. .IP \(bu 4 Run \fBlibguestfs\-test\-tool\fR\|(1) and paste the \fBcomplete, unedited\fR output into the bug report.