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)