Converts a Linux guest to run on KVM/virtio. Removes source hypervisor tools, injects virtio drivers into the initramfs, remaps device names, and fixes the bootloader configuration.
Guest disk backends: ../architecture/backends.md.
cmd/kc-convert-linux/main.go — orchestrator in pkg/cmd/convert-linux/pipeline.go.
| Flag | Required | Default | Description |
|---|---|---|---|
--input |
yes | Path to PipelineData JSON (from kc-prepare) | |
--output |
no | convert-out.json |
Path to write PipelineData JSON (with convert section added) |
--mount-root |
no | /tmp/kc-guest |
Host directory where guest filesystems are mounted |
--offline |
no | false |
Skip network firstboot when no local package matches (local packages are always tried first) |
--packages-dir |
no | /usr/share/kc-packages |
Host tree of staged qemu-guest-agent packages (see layout below) |
--virtio-win-dir |
no | Ignored (accepted so Linux and Windows converters share a CLI) | |
--backend |
no | direct |
Guest disk backend: direct or guestfs (Linux), qemu (Linux or macOS) |
--log-level |
no | info |
Log level (debug, info, warn, error) |
The converter always searches for a matching local package first, regardless
of the --offline flag. The decision flow is:
- Local package found -- copy it into the guest (
/var/lib/kc-packages/) and install at firstboot viarpm -ivhordpkg -i. No network required. - No local package found,
--offline=false(default) -- add a firstboot script that installs viadnf/yum/apt/zypperafter network is up. - No local package found,
--offline=true-- skip guest-agent installation entirely (no firstboot script added).
kc-v2v passes --offline when V2V_offline=true so convertor pods use
image-staged packages without falling back to network install.
Default base: /usr/share/kc-packages (--packages-dir to override). Stage a
local tree with build/kc-v2v/stage-linux-packages.sh
(first argument is the destination).
/usr/share/kc-packages/rpm/el8/x86_64/qemu-guest-agent-*.rpm
/usr/share/kc-packages/rpm/el9/x86_64/qemu-guest-agent-*.rpm
/usr/share/kc-packages/rpm/el10/x86_64/qemu-guest-agent-*.rpm
Selection uses inspect distro + major_version: prefer exact el{major}, else nearest lower elN that exists. Only one RPM is copied into the guest.
The kc-v2v image stages el8/el9/el10 x86_64 RPMs via build/kc-v2v/stage-linux-packages.sh. Legacy flat layout $base/rpm/$arch/ remains supported for one-off mounts.
Debian/SUSE guests are not covered by the baked matrix; without a matching local package, --offline skips agent install.
| # | Block | Type | Package | Description |
|---|---|---|---|---|
| 1 | Distro | pluggable: DistroHandler |
pkg/convert-linux/distro/ |
Classify OS family |
| 2 | Package Format | strict | pkg/convert-linux/distro/ |
Determine package format (rpm/deb) |
| 3 | Package Manager | strict | pkg/convert-linux/distro/ |
Determine package manager name |
| 4 | Bootloader | pluggable: BootloaderHandler |
pkg/convert-linux/bootloader/ |
Detect boot config format (grub2, bls) |
| 5 | Kernel Scan | pluggable: KernelScanner |
pkg/convert-linux/kernel/ |
Scan installed kernels |
| 6 | Remap | pluggable: DeviceRemapper |
pkg/convert-linux/remap/ |
Rewrite block device names in /etc/fstab, /etc/crypttab, and bootloader kernel args |
| 7 | UEFI | pluggable: UEFIEditor |
pkg/common/uefi/ |
Update UEFI boot entries on ESP partitions |
| 8 | Kernel Select | strict | pkg/convert-linux/kernel/ |
Select best virtio-capable kernel |
| 9 | Console Config | strict | pkg/convert-linux/bootconfig/ |
Configure serial console kernel args |
| 10 | Display Config | strict | pkg/convert-linux/bootconfig/ |
Configure virtio video kernel args |
| 11 | Hypervisor | pluggable: LinuxCleanup |
pkg/convert-linux/hypervisor/ |
Remove source hypervisor tools; EC2 masks IMDS net hooks |
| 11b | Network (networkd) | networkd.Detect |
pkg/convert-linux/network/networkd/ |
Virtio DHCP + wait-online for systemd-networkd-primary guests |
| 12 | Guest Agent | pluggable | pkg/convert-linux/guestagent/ |
Install qemu-guest-agent, local or firstboot network packages |
| 13 | Guest Cleanup | strict | pkg/convert-linux/guestcleanup/ |
Remove blkid/LVM caches and update modprobe aliases |
| 14 | Initramfs | strict | pkg/convert-linux/initramfs/ |
Rebuild initramfs with virtio drivers |
| 15 | Static IP / NIC Naming | pluggable: NICNamer / networkd |
pkg/convert-linux/nicnaming/, pkg/convert-linux/network/networkd/, pkg/convert-linux/network/staticip/ |
networkd guests: MAC .network files; others: nicnaming + staticip firstboot |
| 16 | SELinux Relabel | strict | pkg/convert-linux/selinux/ |
Offline SELinux relabel via setfiles |
| 17 | GuestCaps | strict | pkg/convert-linux/guestcaps/ |
Derive guest capabilities for KVM |
Block numbers match the pipeline comments in pkg/cmd/convert-linux/pipeline.go.
Distro handlers (rhel, debian, suse), package format/manager lookup, and
offline QGA selection are documented in
guest-os-handlers.md.
PipelineDataJSON (from kc-prepare): OS info, disk layout, mount paths (inpreparesection)- Mounted guest filesystem at
--mount-root
Example: examples/prepare-output-complete.json.
ConverterOutput JSON containing:
guest_caps-- guest capabilities derived during conversion:block_bus--virtiooride(fallback when no virtio modules found)net_bus--virtioore1000- virtio feature flags (RNG, balloon, socket, etc.)
machine_type--q35(x86_64) orvirt(aarch64)
Example: examples/convert-output-linux.json.
| Interface | Implementations |
|---|---|
DistroHandler |
rhel, debian, suse, ... |
BootloaderHandler |
grub2, bls |
KernelScanner |
rpm, deb |
DeviceRemapper |
standard |
LinuxCleanup |
vmware, virtualbox, citrix, parallels, xen, kudzu, hyperv, ec2, nutanix, ... |
GuestAgent |
qemu-ga |
PackageSource |
directory (local RPM/DEB packages) |
FirstbootHandler |
systemd |
NICNamer |
nm, netplan, ifcfg, wicked, dhclient, nmdhcp |
UEFIEditor |
grub-fallback |
The converter rebuilds the guest initramfs using the guest's own tooling
via RunInGuest:
- Back up the existing initramfs (
{path}.pre-v2v) - Try
dracut --force --no-hostonly --no-hostonly-cmdline --add-drivers "virtio ..." {path} {version}(RHEL/Fedora/SUSE) - Fall back to
update-initramfs -u -k {version}(Debian/Ubuntu) - Fall back to
mkinitramfs -o {path} {version}(older Debian)
This approach uses the guest's native module compression, dependency resolution, and firmware inclusion rather than custom CPIO manipulation.
- ../architecture/conversion-paths-linux.md — Linux hypervisor cleanup and distro install matrices
- ../architecture/guest-os-handlers.md — distro handler classification