STRATUM Migrate

stratum-migrate converts a VMware-exported OVA file or unpacked OVF directory into a STRATUM Arsenal bundle (.stratumarsenal).

The frontend is a static Go binary with no runtime library dependencies. It invokes one external conversion engine:

• virt-v2v — enterprise, guest-aware migration. It inspects Windows or Linux, modifies the guest for KVM, installs available VirtIO support, and writes qcow2 disks.
• qemu-img — fast disk-format conversion. It does not modify the guest OS or install drivers.

Recommended enterprise migration

stratum-migrate \
  --backend virt-v2v \
  --report finance-server-migration.json \
  --preserve-v2v-diagnostics \
  finance-server.ova

The default backend is auto: use virt-v2v when it is installed, otherwise use qemu-img.

For a predictable enterprise workflow, explicitly select --backend virt-v2v so a missing or incompatible installation fails instead of silently selecting the fast path.

Fast offline conversion

stratum-migrate \
  --backend qemu-img \
  --disk-bus sata \
  --report finance-server-migration.json \
  finance-server.ova

The qemu-img backend defaults to migration-safe SATA/AHCI for most disks. This is more likely to boot an unmodified Windows guest than changing the boot disk directly to VirtIO.

Requirements

The Go binary itself is static. Install the selected external engine on the migration host.

Enterprise backend

Required:

virt-v2v
libguestfs runtime/appliance support
qemu-img

To install virt-v2v, run the package manager install command for your specific Linux distribution: sudo dnf install virt-v2v (Fedora/RHEL/CentOS), sudo apt install virt-v2v (Ubuntu 22.04 and newer), or sudo apt-get install libguestfs-tools (older Ubuntu/Debian versions). To install libguestfs, run the package manager install command for your specific Linux distribution: sudo dnf install libguestfs-tools (Fedora/RHEL/CentOS), sudo apt install libguestfs-tools (Debian/Ubuntu), or sudo zypper in guestfs-tools on openSUSE. To install qemu-img, run the package manager install command for your specific Linux distribution: sudo apt install qemu-utils, etc...

Strongly recommended for Windows guests:

virtio-win drivers, commonly under /usr/share/virtio-win
qemu-img for post-conversion qcow2 verification

Verify the host before a migration:

virt-v2v --version
virt-v2v --machine-readable | grep -E '^(input:ova|output:local|convert:windows|convert:linux)$'
qemu-img --version

stratum-migrate verifies that a detected virt-v2v advertises input:ova and output:local when machine-readable capabilities are available.

Fast backend

Required:

qemu-img

Input

The source must be one of:

/path/to/guest.ova
/path/to/unpacked-ovf-directory/

For virt-v2v, the appliance must be a VMware-exported OVA or VMware OVF folder. Virt-v2v's OVA support is VMware-specific.

When using a source OVA with the enterprise backend, STRATUM Migrate extracts only the OVF metadata needed to build the Arsenal template. Virt-v2v reads the original OVA, validates its manifest, inspects the guest, and performs the disk conversion. This avoids a second full VMDK extraction by the frontend.

When using an unpacked OVF directory, STRATUM Migrate verifies local .mf checksums before conversion unless --skip-manifest-check is supplied.

Output

finance-server-1.0.0.stratumarsenal
├── manifest.json
└── payload
    ├── templates
    │   └── finance-server
    │       └── canvas.yml
    └── vm-images
        └── finance-server-1.0.0
            ├── virtioa.qcow2
            ├── virtiob.qcow2
            └── migration-source/        # optional audit material

Backend behavior

--backend virt-v2v

The generated command is equivalent to:

virt-v2v \
  -i ova SOURCE \
  -o local -os OUTPUT_DIRECTORY \
  -of qcow2 -oa sparse \
  -on TEMPLATE_NAME \
  --root first \
  --block-driver virtio-blk \
  --parallel 2

STRATUM Migrate then:

1. Reads the libvirt XML generated by virt-v2v.
2. Preserves the converted disk order from that XML.
3. Detects the target disk bus, NIC model, and UEFI mode.
4. Renames disks to STRATUM names such as virtioa.qcow2 and virtiob.qcow2.
5. Runs qemu-img check and qemu-img info when qemu-img is available.
6. Builds and validates the .stratumarsenal package.

Useful options:

--v2v-parallel 4
--v2v-parallel 0     # omit --parallel for older virt-v2v releases
--v2v-root first
--v2v-root /dev/sda2
--v2v-block-driver virtio-blk
--v2v-block-driver virtio-scsi
--v2v-tmpdir /large-fast-volume/virt-v2v-temp

For multi-boot guests, use a specific root device after inspecting the appliance rather than relying on first.

Additional virt-v2v customization arguments can be passed without a shell:

stratum-migrate \
  --backend virt-v2v \
  --virt-v2v-arg=--no-fstrim \
  guest.ova

Repeat --virt-v2v-arg for every argument token. Managed input/output options cannot be overridden through this mechanism.

--backend qemu-img

This backend converts each attached OVF disk to qcow2 using:

compat=1.1,lazy_refcounts=on

It supports vmdk, raw, qcow2, vdi, vhdx, vpc, and qed inputs recognized by qemu-img. Gzip-compressed OVF disk references are decompressed before conversion.

Disk policies:

auto       SATA/AHCI, except source IDE remains IDE
preserve   Preserve SATA/SCSI/IDE where STRATUM supports it
sata       Force SATA/AHCI
scsi       Force SCSI
virtio     Force VirtIO block
ide        Force IDE

UEFI and VMware NVRAM

A VMware .nvram file is not a STRATUM OVMF variable store and must not be renamed to uefi-vars.fd.

STRATUM Migrate detects BIOS, UEFI, and Secure Boot from the appliance metadata. The bundle sets the STRATUM firmware mode, and STRATUM creates a fresh native OVMF variable store on first boot.

Consequences:

• VMware-specific EFI boot variables are not migrated.
• A guest may need to rediscover its EFI bootloader.
• Keep the powered-off VMware source until the migrated VM has booted and been validated.

For audit retention only:

--preserve-vmware-nvram

The source file is stored under migration-source/vmware-nvram/ and is never used as runtime firmware state.

VMware vTPM, BitLocker, and sealed secrets

VMware vTPM state and secrets cannot be converted into a new STRATUM TPM identity. When the OVF declares a vTPM, the default --tpm auto enables a fresh STRATUM TPM 2.0 device and emits a warning.

Before migration:

• Suspend or decrypt TPM-sealed workloads where policy permits.
• Export BitLocker recovery keys.
• Confirm application-level keys and certificates are recoverable.
• Expect a recovery-key prompt on first boot for TPM-bound Windows volumes.

TPM policy overrides:

--tpm auto
--tpm none
--tpm tpm2

Network identity

Virt-v2v preserves source MAC addresses in its generated metadata because guest network configuration can depend on them. A STRATUM Arsenal template/image bundle does not carry a deployed node's MAC identity, so STRATUM assigns MAC addresses when the node is deployed.

Plan for guest network-interface renaming, static-IP reassignment, firewall bindings, and software licensing tied to a source MAC address.

Virt-v2v does not generally move a static guest configuration to a different subnet automatically.

Migration diagnostics

Create a JSON report:

--report migration.json

Include the virt-v2v log and generated libvirt XML inside the bundle for an auditable migration record:

--preserve-v2v-diagnostics

They are stored under:

migration-source/virt-v2v/converted-domain.xml
migration-source/virt-v2v/virt-v2v.log

Review these files before distributing a bundle outside the organization; they can contain host paths, operating-system details, MAC addresses, and conversion diagnostics.

Large migrations

Virt-v2v requires space for converted disks and potentially large temporary overlays. Use a dedicated fast volume:

mkdir -p /migration/virt-v2v-tmp
stratum-migrate \
  --backend virt-v2v \
  --v2v-tmpdir /migration/virt-v2v-tmp \
  --output /migration/bundles/finance-1.0.0.stratumarsenal \
  finance.ova

Also account for the final Arsenal ZIP package. The converter writes the package to OUTPUT.partial and atomically renames it after successful validation.

Common examples

Enterprise Windows migration:

stratum-migrate \
  --backend virt-v2v \
  --name windows-finance \
  --version 1.0.0 \
  --v2v-block-driver virtio-blk \
  --v2v-parallel 4 \
  --v2v-tmpdir /migration/tmp \
  --report windows-finance.json \
  --preserve-v2v-diagnostics \
  windows-finance.ova

Enterprise Linux migration using VirtIO SCSI:

stratum-migrate \
  --backend virt-v2v \
  --v2v-block-driver virtio-scsi \
  --version 2.0.0 \
  linux-app.ova

Unmodified legacy guest using SATA:

stratum-migrate \
  --backend qemu-img \
  --disk-bus sata \
  legacy-appliance/

Build

make test
make release VERSION=1.0.0

The release build uses:

CGO_ENABLED=0
-trimpath
-s -w -buildid=

Binaries are generated for Linux amd64 and arm64.

Verify the amd64 binary is static:

file dist/stratum-migrate-linux-amd64
ldd dist/stratum-migrate-linux-amd64

ldd should report that it is not a dynamic executable.

Security properties

• OVA extraction rejects absolute paths, path traversal, symlinks, hard links, devices, and FIFOs.
• OVF file references cannot escape the appliance directory.
• External commands are executed as argument arrays, not through a shell.
• Output is written to partial files and renamed only after success.
• Converted qcow2 disks are checked when qemu-img is available.
• The completed bundle is reopened and structurally validated.
• No VMware NVRAM or vTPM state is treated as native STRATUM state.

Scope

Version 1.0 accepts exported OVA files and unpacked OVF directories. It does not connect directly to vCenter or ESXi. Direct VDDK, VMX-over-SSH, and vCenter sources can be added later without changing the STRATUM bundle stage.