virt-v2v-output-local(1)

1virt-v2v-output-local(1)    Virtualization Support    virt-v2v-output-local(1)
2
3
4

NAME

6       virt-v2v-output-local - Using virt-v2v to convert guests to local files
7       or libvirt
8

SYNOPSIS

10        virt-v2v [-i* options] [-o libvirt] -os POOL
11
12        virt-v2v [-i* options] -o local -os DIRECTORY
13
14        virt-v2v [-i* options] -o qemu -os DIRECTORY [--qemu-boot]
15
16        virt-v2v [-i* options] -o json -os DIRECTORY
17                               [-oo json-disks-pattern=PATTERN]
18
19        virt-v2v [-i* options] -o null
20

DESCRIPTION

22       This page documents how to use virt-v2v(1) to convert guests to local
23       files or to a locally running libvirt instance.  There are four output
24       modes you can select on the virt-v2v command line:
25
26       -o libvirt -os "POOL"
27       -os "POOL"
28           This converts the guest to a libvirt directory pool call "POOL",
29           and instantiates the guest in libvirt (but does not start it
30           running).  See "OUTPUT TO LIBVIRT" below.
31
32           -o libvirt is the default if no -o option is given, so you can omit
33           it.
34
35       -o local -os "DIRECTORY"
36           This converts the guest to files in "DIRECTORY".  A libvirt XML
37           file is also created, but unlike -o libvirt the guest is not
38           instantiated in libvirt, only files are created.
39
40           The files will be called:
41
42            NAME-sda, NAME-sdb, etc.      Guest disk(s).
43            NAME.xml                      Libvirt XML.
44
45           where "NAME" is the guest name.
46
47       -o qemu -os "DIRECTORY"
48       -o qemu -os "DIRECTORY" --qemu-boot
49           This converts the guest to files in "DIRECTORY".  Unlike -o local
50           above, a shell script is created which contains the raw qemu
51           command you would need to boot the guest.  However the shell script
52           is not run, unless you also add the --qemu-boot option.
53
54       -o json -os "DIRECTORY"
55           This converts the guest to files in "DIRECTORY".  The metadata
56           produced is a JSON file containing the majority of the data
57           virt-v2v gathers during the conversion.  See "OUTPUT TO JSON"
58           below.
59
60       -o null
61           The guest is converted, but the final result is thrown away and no
62           metadata is created.  This is mainly useful for testing.
63

OUTPUT TO LIBVIRT

65       The -o libvirt option lets you upload the converted guest to a libvirt-
66       managed host.  There are several limitations:
67
68       •   You can only use a local libvirt connection [see below for how to
69           workaround this].
70
71       •   The -os pool option must specify a directory pool, not anything
72           more exotic such as iSCSI [but see below].
73
74       •   You can only upload to a KVM hypervisor.
75
76   Workaround for output to a remote libvirt instance and/or a non-directory
77       storage pool
78       1.  Use virt-v2v in -o local mode to convert the guest disks and
79           metadata into a local temporary directory:
80
81            virt-v2v [...] -o local -os /var/tmp
82
83           This creates two (or more) files in /var/tmp called:
84
85            /var/tmp/NAME.xml     # the libvirt XML (metadata)
86            /var/tmp/NAME-sda     # the guest’s first disk
87
88           (for "NAME" substitute the guest’s name).
89
90       2.  Upload the converted disk(s) into the storage pool called "POOL":
91
92            size=$(stat -c%s /var/tmp/NAME-sda)
93            virsh vol-create-as POOL NAME-sda $size --format raw
94            virsh vol-upload --pool POOL NAME-sda /var/tmp/NAME-sda
95
96       3.  Edit /var/tmp/NAME.xml to change /var/tmp/NAME-sda to the pool
97           name.  In other words, locate the following bit of XML:
98
99            <disk type='file' device='disk'>
100              <driver name='qemu' type='raw' />
101              <source file='/var/tmp/NAME-sda' />
102              <target dev='hda' bus='ide' />
103            </disk>
104
105           and change two things: The "type='file'" attribute must be changed
106           to "type='volume'", and the "<source>" element must be changed to
107           include "pool" and "volume" attributes:
108
109            <disk type='volume' device='disk'>
110              ...
111              <source pool='POOL' volume='NAME-sda' />
112              ...
113            </disk>
114
115       4.  Define the final guest in libvirt:
116
117            virsh define /var/tmp/NAME.xml
118

OUTPUT TO JSON

120       The -o json option produces the following files by default:
121
122        NAME.json                     JSON metadata.
123        NAME-sda, NAME-sdb, etc.      Guest disk(s).
124
125       where "NAME" is the guest name.
126
127       It is possible to change the pattern of the disks using the -oo
128       json-disks-pattern=... option: it allows parameters in form of "%{...}"
129       variables, for example:
130
131        -oo json-disks-pattern=disk%{DiskNo}.img
132
133       Recognized variables are:
134
135       "%{DiskNo}"
136           The index of the disk, starting from 1.
137
138       "%{DiskDeviceName}"
139           The destination device of the disk, e.g. "sda", "sdb", etc.
140
141       "%{GuestName}"
142           The name of the guest.
143
144       Using a pattern it is possible use subdirectories for the disks, even
145       with names depending on variables; for example:
146
147        -oo json-disks-pattern=%{GuestName}-%{DiskNo}/disk.img
148
149       The default pattern is "%{GuestName}-%{DiskDeviceName}".
150
151       If the literal "%{...}" text is needed, it is possible to avoid the
152       escape it with a leading "%"; for example,
153       "%%{GuestName}-%{DiskNo}.img" will create file names for the disks like
154       "%%{GuestName}-1.img", "%%{GuestName}-2.img", etc.
155

AUTHOR

160       Richard W.M. Jones
161

COPYRIGHT

163       Copyright (C) 2009-2020 Red Hat Inc.
164

LICENSE

166       This program is free software; you can redistribute it and/or modify it
167       under the terms of the GNU General Public License as published by the
168       Free Software Foundation; either version 2 of the License, or (at your
169       option) any later version.
170
171       This program is distributed in the hope that it will be useful, but
172       WITHOUT ANY WARRANTY; without even the implied warranty of
173       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
174       General Public License for more details.
175
176       You should have received a copy of the GNU General Public License along
177       with this program; if not, write to the Free Software Foundation, Inc.,
178       51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
179

BUGS

181       To get a list of bugs against libguestfs, use this link:
182       https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
183
184       To report a new bug against libguestfs, use this link:
185       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
186
187       When reporting a bug, please supply:
188
189       •   The version of libguestfs.
190
191       •   Where you got libguestfs (eg. which Linux distro, compiled from
192           source, etc)
193
194       •   Describe the bug accurately and give a way to reproduce it.
195
196       •   Run libguestfs-test-tool(1) and paste the complete, unedited output
197           into the bug report.
198
199
200
201virt-v2v-1.44.0                   2021-04-30          virt-v2v-output-local(1)