=head1 NAME

virt-v2v-in-place - Convert a guest to use KVM in-place

=head1 SYNOPSIS

 virt-v2v-in-place -i disk [other -i* options]
                   [virt-customize options]
                   filename
                   [-O output.xml]

 virt-v2v-in-place -i libvirt|libvirtxml [other -i* options]
                   [virt-customize options]
                   guest
                   [-O output.xml]

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

This manual page only documents the differences between this tool and
virt-v2v.  You should read L<virt-v2v(1)> first.

=head2 Selecting the input disk

You normally run virt-v2v with one or more I<-i*> options controlling
the input mode.  Virt-v2v-in-place can only convert guests stored in
local files.

This command will do an in-place conversion of F<filename.img>:

 virt-v2v-in-place -i disk filename.img

If the guest has been copied to local libvirt then:

 virt-v2v-in-place -i libvirt guest

=head2 Output XML

Optionally use the I<-O> option to write post-conversion metadata
about the guest to an XML file.  This is in the same format as
L<virt-v2v-inspector(1)>.  This can be used, for example, to find out
what operating system and firmware was found inside the guest during
conversion.

=head2 Exit code

If virt-v2v-in-place fails it will return a non-zero (error) exit
code.  In this case, the disk image will be in an B<unknown, possibly
corrupted state>.

If the image contains important information you should ensure you have
a backup before trying a virt-v2v-in-place conversion.  And you should
check the exit code is zero before using the disk image after a
conversion.

=head1 EXAMPLES

=head1 OPTIONS

=over 4

=item B<--help>

Display help.

=item B<-b> ...

=item B<--bridge> ...

See I<--network> below.

ifelse(ENABLE_BLOCK_DRIVER, yes, `

=item B<--block-driver> B<virtio-blk>

=item B<--block-driver> B<virtio-scsi>

When choosing a block driver for Windows guests, prefer C<virtio-blk> or
C<virtio-scsi>.  The default is C<virtio-blk>.

Note this has no effect for Linux guests at the moment.  That may be
added in future.
')

=item B<--collect> GUEST[B<:>LOCAL]

=item B<--collect-output> PATH/TO/OUTPUTB<.tar.xz>

See L<virt-v2v(1)/Collecting files for later diagnostics>

=item B<--colors>

=item B<--colours>

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

=item B<--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.

Note this options only applies to keys and passphrases for encrypted
devices and partitions, not for passwords used to connect to remote
servers.

=item B<-i> B<disk>

Set the input method to I<disk>.

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 I<-i libvirtxml> instead.  Only guests that use a single
disk can be imported this way.

=item B<-i> B<libvirt>

Set the input method to I<libvirt>.  This is the default.

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

=item B<-i> B<libvirtxml>

Set the input method to I<libvirtxml>.

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 L</Minimal XML for -i libvirtxml option> below.

=item B<-i> B<local>

This is the same as I<-i disk>.

=item B<-ic> libvirtURI

Specify a libvirt connection URI to use when reading the guest.  This
is only used when S<I<-i libvirt>>.

Only local libvirt connections to locally stored disks can be used.

=item B<-if> format

For I<-i disk> only, this specifies the format of the input disk
image.  For other input methods you should specify the input
format in the metadata.

=item B<-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:

 virt-v2v-in-place -it disk -io "?"

=item B<-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, B<without any trailing newline>, and for security the file
should have mode C<0600> so that others cannot read it.

__INCLUDE:key-option.pod__

__INCLUDE:keys-from-stdin-option.pod__

Note I<--keys-from-stdin> only applies to keys and passphrases for
encrypted devices and partitions, not for passwords used to connect to
remote servers.

=item B<--mac> aa:bb:cc:dd:ee:ffB<:network:>out

=item B<--mac> aa:bb:cc:dd:ee:ffB<:bridge:>out

Map source NIC MAC address to a network or bridge.

See L<virt-v2v(1)/Networks and bridges>.

=item B<--mac> aa:bb:cc:dd:ee:ffB<:ip:>ipaddr[,gw[,len[,ns,ns,...]]]

Force a particular interface (controlled by its MAC address) to have a
static IP address after boot.

The fields in the parameter are: C<ipaddr> is the IP address.  C<gw>
is the optional gateway IP address.  C<len> is the subnet mask length
(an integer).  The final parameters are zero or more nameserver IP
addresses.

This option can be supplied zero or more times.

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.

=item B<--machine-readable>

=item B<--machine-readable>=format

This option is used to make the output more machine friendly
when being parsed by other programs.  See
L<virt-v2v(1)/Machine readable output>.

=item B<-m> MB

=item B<--memsize> MB

Change the amount of memory allocated when doing the conversion.
Virt-v2v-in-place will usually choose a suitable default.  Increase
this if you see that the conversion step is running out of memory.

=item B<-n> in:out

=item B<-n> out

=item B<--network> in:out

=item B<--network> out

=item B<-b> in:out

=item B<-b> out

=item B<--bridge> in:out

=item B<--bridge> out

Map network (or bridge) called C<in> to network (or bridge) called
C<out>.  If no C<in:> prefix is given, all other networks (or bridges)
are mapped to C<out>.

See L<virt-v2v(1)/Networks and bridges>.

=item B<--no-fstrim>

Do not trim the filesystem.  See L<virt-v2v(1)/Trimming>.

=item B<-O> output.xml

=item B<-O ->

If this option is present, write post-conversion metadata about the
guest to the named XML file, or to stdout if I<-O -> is used.  This is
in the same format as L<virt-v2v-inspector(1)>.

=item B<--print-source>

Print information about the source guest and stop.  This option is
useful when you are setting up network and bridge maps.
See L<virt-v2v(1)/Networks and bridges>.

=item B<-q>

=item B<--quiet>

This disables progress bars and other unnecessary output.

=item B<--root> ...

Choose the root filesystem to be converted.  See the documentation of
this option in L<virt-v2v(1)>.

=item B<--smp> N

Change the number of virtual CPUs used when doing the conversion.
Virt-v2v-in-place will usually choose a suitable default.

Increasing this beyond 8 may improve conversion performance, if your
host has sufficient physical CPUs.  You may also need to increase the
memory size (I<--memsize> option).

=item B<-v>

=item B<--verbose>

Enable verbose messages for debugging.

=item B<-V>

=item B<--version>

Display version number and exit.

=item B<--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.

=item B<-x>

Enable tracing of libguestfs API calls.

=back

=head2 Minimal XML for -i libvirtxml option

When using the I<-i libvirtxml> option, you have to supply some
libvirt XML.  Writing this from scratch is hard, so the template below
is helpful.

B<Note this should only be used for testing and/or where you know what
you're doing!>  If you have libvirt metadata for the guest, always use
that instead.

 <domain type='kvm'>
   <name> NAME </name>
   <memory>1048576</memory>
   <vcpu>2</vcpu>
   <os>
     <type>hvm</type>
     <boot dev='hd'/>
   </os>
   <features>
     <acpi/>
     <apic/>
     <pae/>
   </features>
   <devices>
     <disk type='file' device='disk'>
       <driver name='qemu' type='raw'/>
       <source file='/path/to/disk/image'/>
       <target dev='hda' bus='ide'/>
       <checksum method='sha256' fail='error'>123123...</checksum>
     </disk>
     <interface type='network'>
       <mac address='52:54:00:01:02:03'/>
       <source network='default'/>
       <model type='rtl8139'/>
     </interface>
   </devices>
 </domain>

=head2 Disk checksum

The optional E<lt>checksumE<gt> field specifies the expected hash of
the corresponding disk.  It can be specified by management tools in
order to do end-to-end data integrity checks.

Note this is the checksum of the raw format content of the disk.  If
the disk is in a container format (eg. qcow2) it is the checksum of
the content, I<not> of the container.

The checksum method attribute can be C<md5>, C<sha256> or C<sha512>.

The fail attribute can be C<error> to fail the conversion if the
checksum does not match; C<warn> to print a warning but continue;
C<ignore> to ignore the checksum and not even compute it; or C<print>
to print the actual checksum and continue.  The default is
C<fail=warn>.

Computing the checksum of a remote (eg HTTP) source can be slow and
expensive.

=head1 FILES

Files used are the same as for virt-v2v.  See L<virt-v2v(1)/FILES>.

=head1 ENVIRONMENT VARIABLES

Environment variables used are the same as for virt-v2v.  See
L<virt-v2v(1)/ENVIRONMENT VARIABLES>.

=head1 SEE ALSO

L<virt-v2v(1)>,
L<virt-p2v(1)>,
L<guestfs(3)>,
L<guestfish(1)>,
L<qemu-img(1)>,
L<nbdkit(1)>,
L<http://libguestfs.org/>.

=head1 AUTHORS

Matthew Booth

Cédric Bosdonnat

Laszlo Ersek

Tomáš Golembiovský

Shahar Havivi

Richard W.M. Jones

Roman Kagan

Mike Latimer

Nir Soffer

Pino Toscano

Xiaodai Wang

Ming Xie

Tingting Zheng

=head1 COPYRIGHT

Copyright (C) 2009-2025 Red Hat Inc.
