Use "Javascript include" for filters.
[libguestfs-talks.git] / 2017-v2v-internals / NOTES
1 Quick demo:
2
3   $ virt-v2v -i ova RHEL.ova -o local -os /var/tmp
4
5 OVA was exported from VMware.  Convenient to use OVAs for the demo
6 because it doesn't require a running VMware server.
7
8 Output is stored locally, but in a more realistic scenario you would
9 point virt-v2v directly at RHV, Glance or other targets.
10
11 No need to run it as root unless it needs to be run as root to
12 access something.
13
14 Input mode and an output mode
15 -----------------------------
16
17 There's an input mode, an output mode, and a conversion step between
18 them.
19
20     virt-v2v -i ova RHEL.ova
21              -i vmx guest.vmx
22              -i libvirt -ic vpx://vcenter.example.com/Datacenter/esxi guest
23              -i disk disk.img
24
25              -o local -os /var/tmp
26              -o libvirt
27              -o rhv -os esd:/mnt
28              -o glance
29              -o qemu   \__ for testing
30              -o null   /
31
32
33 Overlay on top of input, conversion, then qemu-img convert
34 ----------------------------------------------------------
35
36 Conversion is actually done first, but the "delta" is stored in an
37 overlay, which is a local qcow2 file in /var/tmp.  The source is never
38 touched.
39
40 The second step is a copy made to the target using ‘qemu-img convert’.
41
42 The copy is the long step, and we want to do the conversion first
43 because conversion is the most likely part to fail.
44
45 ‘fstrim’ is used to reduce the amount of data copied.  Blank areas and
46 deleted files are almost never copied.
47
48
49 Source
50 ------
51
52 Virt-v2v has an internal structure that reflects the command line.
53
54 https://github.com/libguestfs/libguestfs
55   - v2v subdirectory is the source of virt-v2v
56   - p2v subdirectory is the source of virt-p2v
57   - About 33 K LoC in virt-v2v & virt-p2v
58   - About 860 K LoC if you include all parts of the libguestfs ecosystem
59     (tools, utilities, libraries, hivex, supermin, nbdkit)
60
61 Before compiling, read: http://libguestfs.org/guestfs-building.1.html
62 Very important indeed and it will save you a lot of time and hassle.
63
64 It's written in OCaml and C.  OCaml is a very fast, natively compiled,
65 actively developed ML derivative.
66
67 When reading OCaml code, always start with the .mli file -- the
68 interface.  Then read the .ml file -- the implementation -- if you
69 need it.
70
71
72 Input modules
73 -------------
74
75 Input_ova
76 (-i ova)
77
78 Input_vmx
79 (-i vmx)
80                              source structure
81 Input_libvirt*               + inspection data
82 (VMware, Xen, ...)
83
84 Input_disk
85 (-i disk)
86
87
88 Source + inspection
89 -------------------
90
91 This is very abbreviated.  In the real structure there are dozens
92 of fields and sub-structures.
93
94 It's like libvirt XML, but more limited.
95
96 Inspection data is collected from the source automatically and it
97 contains a very large amount of detail about the guest, including type
98 (Linux, Windows), architecture, applications installed and so on.
99
100
101 Conversion modules
102 ------------------
103
104 source + inspection        Convert_linux
105
106                            Convert_windows
107
108 Remember that the conversion step is done up-front.  The inspection
109 data tells us whether we need to use the Linux or Windows module.
110 Only a limited set of Linux distros are supported, but almost any
111 Windows version is supported.
112
113
114 Conversion of Linux
115 -------------------
116
117 * Removes guest additions.
118
119 * Picks a kernel with virtio support and adjusts the bootloader to use it.
120   It can also handle guests with no virtio support and Do The Right Thing.
121
122 * Changes devices names in configuration files (eg. /dev/vdaX).
123
124 * Rebuilds the initramfs.
125
126
127 Conversion of Windows
128 ---------------------
129
130 Much more complex than Linux conversion.  Unlike Linux conversions,
131 we will actually install virtio-win drivers.
132
133 * Removes some guest additions and Xen drivers.
134
135 * Dozens of changes to the Windows Registry.
136
137 * Changes to the BCD.
138
139 * The installations and changes are continued in a "firstboot" script
140   which runs on first boot of the guest in the new environment.
141
142 Auxiliary programs: pnp_wait.exe, rhsrvany.exe, rhev-apt.exe, vmdp.exe [SUSE].
143
144
145 Output module
146 -------------
147
148 Output_glance
149 (-o glance)
150
151 Output_rhv / Output_vdsm
152 (for RHV)
153
154 Output_libvirt
155 (-o libvirt)
156
157 Output_local, Output_null, Output_qemu
158 (-o local, -o null, -o qemu)
159
160
161 Unlike input modules which collect data and create the "source"
162 struct, the purpose of output modules is more to manage the final
163 copy/qemu-img convert step.
164
165 Output modules also create the final metadata.  The metadata is
166 influenced by the conversion step: for example if virtio drivers could
167 not be installed then the metadata will specify emulated (eg. IDE)
168 devices.
169
170
171 Managing the process
172 --------------------
173
174 V2v module manages the whole process end to end.  It's the "main
175 program" of virt-v2v.
176
177
178 Libraries and utilities
179 -----------------------
180
181
182
183
184
185 Tests
186 -----
187
188 virt-v2v has (at least?) 3 test suites:
189
190 * An internal test suite run by doing ‘make check’
191
192 * An external test suite of proprietary images
193
194 * AvocadoVT tests maintained by QE
195
196 We'll probably move (2) into (3) at some point.
197
198
199
200 Other topics
201 ------------
202
203 Don't want to talk about these, but don't want to forget about them
204 either, since they are complex and important topics on their own.
205
206 * virt-p2v
207
208 * --in-place conversions
209
210
211 Final notes
212 -----------
213
214 http://libguestfs.org
215
216 https://github.com/libguestfs/libguestfs
217
218 http://libguestfs.org/guestfs-building.1.html
219
220 IRC: #libguestfs on Freenode (public)
221
222 IRC: #v2v (internal)
223
224 Mail: libguestfs@redhat.com (public)
225       v2v-devel (internal)