BCVK-LIBVIRT-RUN(8)

✨ NAME ✨

bcvk-libvirt-run — run a bootable container as a persistent VM 💖

bestie you are reading the bcvk-libvirt-run page, straight out of the NAME() manual, and it is so good. no cap.

---

🦋 SYNOPSIS 🦋

bcvk libvirt run [OPTIONS]

---

🌸 DESCRIPTION 🌸

Run a bootable container as a persistent VM.

that's the whole assignment. you hand it a container image, it gives you a real, living, breathing VM that stays. she's not transient (unless you tell her to be, we'll get there 👀). main character energy only.

---

💅 OPTIONS 💅

• IMAGE — the container image you wanna run as a bootable VM. this one is required, like genuinely mandatory, you cannot skip it, she will not start without it fr fr.
• --name=NAME — name for the VM. if you don't pick one it gets auto-generated for you, cute of it honestly.
• -R, --replace — replace an existing VM with the same name. it stops and removes the old one if it exists. so like, it will delete the thing you already had. be normal about it pls 🙈.
• --itype=ITYPE — instance type (like u1.nano, u1.small, u1.medium). this one overrides cpus/memory if you specify it, she does not share the spotlight.
• --memory=MEMORY — memory size (like 4G, 2048M, or just a plain number meaning MB). Default: 4G
• --cpus=CPUS — number of virtual CPUs for the VM. note that --itype overrides this if specified, so pick your fighter. Default: 2
• --disk-size=DISK_SIZE — disk size for the VM (like 20G, 10240M, or a plain number meaning bytes). Default: 20G
• --filesystem=FILESYSTEM — root filesystem type (like ext4, xfs, btrfs).
• --root-size=ROOT_SIZE — root filesystem size (like '10G', '5120M').
• --storage-path=STORAGE_PATH — path to host container storage. if you don't say anything she auto-detects it, she's smart like that.
• --target-transport=TARGET_TRANSPORT — the transport; like oci, oci-archive, containers-storage. Defaults to registry.
• --karg=KARG — set a kernel argument. stack as many as you want bestie.
• --composefs-backend — default to composefs-native storage.
• --bootloader=BOOTLOADER — which bootloader to use for the composefs-native backend.
• --allow-missing-fsverity — allow installation without fs-verity support for the composefs-native backend.
• -p, --port=PORT_MAPPINGS — port mapping from host to VM (format: host_port:guest_port, like 8080:80).
• -v, --volume=RAW_VOLUMES — volume mount from host to VM. this is the raw virtiofs tag, for manual mounting, so you mount it yourself, iykyk.
• --bind=BIND_MOUNTS — bind mount from host to VM (format: host_path:guest_path).
• --bind-ro=BIND_MOUNTS_RO — bind mount from host to VM as read-only (format: host_path:guest_path).
• --network=NETWORK — network mode for the VM. Default: user
• --detach — keep the VM running in the background after creation. set her free, let her cook 🔥.
• --ssh — automatically SSH into the VM after creation.
• --ssh-wait — wait for SSH to become available and verify connectivity (for testing).
• --bind-storage-ro — mount host container storage (RO) at /run/host-container-storage.
• --update-from-host — implies --bind-storage-ro, but also configures things to update from the host container storage by default.
• --firmware=FIRMWARE — firmware type for the VM (defaults to uefi-secure).

Possible values:

• uefi-secure
• uefi-insecure
• bios

Default: uefi-secure

• --disable-tpm — disable TPM 2.0 support (it's enabled by default, so this is the "actually no thank you" button).
• --firmware-log — enable firmware debug log (captures OVMF/EDK2 DEBUG output via isa-debugcon).
• --secure-boot-keys=SECURE_BOOT_KEYS — directory containing secure boot keys (required for uefi-secure, don't forget her).
• --label=LABEL — user-defined labels for organizing VMs (heads up: a comma is not allowed in labels).
• --graphical-console — enable graphical console (SPICE) for virt-manager access.
• --transient — create a transient VM that disappears on shutdown/reboot. she's here for a good time not a long time 💀.
• --ignition=IGNITION_CONFIG — path to an Ignition config file (JSON format) for first-boot provisioning.
• --virtiofsd=VIRTIOFSD_BINARY — path to the virtiofsd binary (overrides auto-detection for disk creation).
• --console-log=CONSOLE_LOG — log the virtio console (OS/journald on hvc0) to this file (created if absent).
• --platform-console-log=PLATFORM_CONSOLE_LOG — log the platform console (UEFI/bootloader on ttyS0) to this file (created if absent).
• --log-dir=STREAMS=DIR — write VM log streams to files in DIR.

---

🎀 EXAMPLES 🎀

create and start a persistent VM:

bcvk libvirt run --name my-server quay.io/fedora/fedora-bootc:42

create a VM with custom resources:

bcvk libvirt run --name webserver --memory 8192 --cpus 8 --disk-size 50G quay.io/centos-bootc/centos-bootc:stream10

create a VM with port forwarding:

bcvk libvirt run --name webserver --port 8080:80 quay.io/centos-bootc/centos-bootc:stream10

create a VM with a volume mount:

bcvk libvirt run --name devvm --volume /home/user/code:/workspace quay.io/fedora/fedora-bootc:42

create a VM and automatically SSH into it:

bcvk libvirt run --name testvm --ssh quay.io/fedora/fedora-bootc:42

create a VM with access to host container storage for bootc upgrade:

bcvk libvirt run --name upgrade-test --bind-storage-ro quay.io/fedora/fedora-bootc:42

capture the virtio console (OS/journald output) to a log file. the console=hvc0 kernel argument is required so that the kernel maps /dev/console to hvc0; without it, journald's forward_to_console output goes to the serial console (ttyS0) instead:

bcvk libvirt run --name testvm \
    --karg=console=hvc0 \
    --karg=systemd.journald.forward_to_console=1 \
    --console-log /var/home/user/vm-console.log \
    quay.io/fedora/fedora-bootc:42

capture the platform console (UEFI/GRUB/serial) separately:

bcvk libvirt run --name testvm \
    --platform-console-log /var/home/user/vm-serial.log \
    quay.io/fedora/fedora-bootc:42

server management workflow:

# Create a persistent server VM
bcvk libvirt run --name production-server --memory 8192 --cpus 4 --disk-size 100G my-server-image

# Check status
bcvk libvirt list

# Access for maintenance
bcvk libvirt ssh production-server

⭐ Ignition Configuration ⭐

inject Ignition ⟨https://coreos.github.io/ignition/⟩ configuration files for first-boot provisioning on CoreOS-based images:

# Create an Ignition config file (v3.3.0 format)
cat > config.ign <<EOF
{
  "ignition": {
    "version": "3.3.0"
  },
  "passwd": {
    "users": [
      {
        "name": "core",
        "sshAuthorizedKeys": [
          "ssh-ed25519 AAAAC3... user@example.com"
        ]
      }
    ]
  },
  "storage": {
    "files": [
      {
        "path": "/etc/hostname",
        "contents": {
          "source": "data:,my-coreos-vm"
        },
        "mode": 420
      }
    ]
  }
}
EOF

# Run Fedora CoreOS with Ignition config
bcvk libvirt run --name fcos-vm \
    --ignition config.ign \
    --memory 4G --cpus 2 \
    quay.io/fedora/fedora-coreos:stable

important notes, bestie, read these:

• only works with Ignition-capable images (Fedora CoreOS, RHEL CoreOS, or custom bootc images with Ignition support)
• config is injected via fw_cfg on x86_64/aarch64, virtio-blk on s390x/ppc64le (following FCOS conventions)
• the Ignition config is stored persistently in the libvirt storage pool
• for custom bootc images with Ignition support, see the Ignition documentation ⟨https://coreos.github.io/ignition/⟩ and bootc initramfs documentation ⟨https://docs.fedoraproject.org/en-US/bootc/initramfs/⟩

---

🌈 SEE ALSO 🌈

bcvk(8)

---

👑 VERSION 👑

v0.1.0

---

and that's the page, bestie 🫶 it's v0.1.0, it's living in the NAME() manual, and the date field is literally just NAME() too because the generator said slay and moved on. periodt 💖✨