kvmtool(1)

📦 version 0.20170904, in ubuntu jammy

🦋 NAME 🦋

kvmtool — running KVM guests. that's the whole name section, bestie. short, sweet, iconic. 💅

✨ SYNOPSIS ✨

lkvm COMMAND [ARGS]

like, you give it a command, you give it args, it does the thing. 🫶

🌸 DESCRIPTION 🌸

okay so real talk: kvmtool is a userland tool for creating and controlling KVM guests. userland = it lives out here with us, not in the kernel. creating guests, controlling guests, that's the entire job description and honestly? it ate. 💖

👑 KVMTOOL COMMANDS 👑

💫 run

lkvm run -k <kernel-image> [-c <cores>] [-m <MiB>] [-p <command line>]
         [-i <initrd>] [-d <image file>] [--console serial|virtio|hv]
         [--dev <node>] [--debug] [--debug-single-step] [--debug-ioport]

Run a guest. that's the main character command right there. ⭐

  • -k, --kernel <image file> — the virtual machine kernel. yes you literally have to give it a kernel, it's not gonna manifest one out of vibes. 🧚
  • -c, --cpus <n> — the number of virtual CPUs to run. more cores, more chaos, no cap.
  • -m, --mem <n> — virtual machine memory size, in MiB. (MiB, not MB, don't @ me.)
  • -p, --params <parameters> — extra kernel command line arguments. sprinkle them in like glitter. ✨
  • -i, --initrd <image file> — initial RAM disk image.
  • -d, --disk <image file|directory> — a disk image file or a rootfs directory. your choice, both slay.
  • --console serial|virtio|hv — which console to use. pick one of serial, virtio, or hv.
  • --dev <device node> — KVM device file, for when you don't wanna use the default /dev/kvm. rebels only. 🙈
  • --debug — enable debug messages.
  • --debug-single-step — enable single stepping.
  • --debug-ioport — enable ioport debugging.

🎀 setup <name>

Set up a new virtual machine. This creates a new rootfs in the .lkvm folder of your home directory.

so like, it makes a folder in your home dir. your home. your .lkvm. keep that in mind, it comes back later. 💀

⏸️ pause --all|--name <name>

Pause a virtual machine. (yes, mid-sentence, no warning, just paused. it's giving ghosted.)

  • -a, --all — pause all running instances. all of them. every single one. 😭
  • -n, --name <name> — pause that specified instance. for a list of running instances, see lkvm list.

▶️ resume --all|--name <name>

Resume a previously paused virtual machine. we're back, bestie. 🌈

  • -a, --all — resume all running instances.
  • -n, --name <name> — resume that specified instance. for a list of running instances, see lkvm list.

📋 list [-i] [-r]

Print a list of running instances on the host. This is restricted to instances started by the current user, as it looks in the .lkvm folder in your home directory to find the socket files.

ngl, it can only see your instances, because it goes digging in .lkvm in your home directory for the socket files. that's the vibe check and you passed it. 💜
  • -i, --run — list all running instances.
  • -r, --rootfs — list rootfs instances.

🔍 debug --all|--name <guest name> [--dump] [--nmi <n>] [--sysrq <rq>]

Print debug information from a running VM instance. detective mode: activated. 🕵️ (okay not an emoji from the approved list but the energy is real)

  • -a, --all — debug all running instances.
  • -n, --name <guest name> — debug the specified instance.
  • -d, --dump — generate a debug dump from guest.
  • -m, --nmi <VCPU nr> — generate an NMI on the specified virtual CPU.
  • -s, --sysrq <sysrq> — inject a Linux sysrq into the guest.

🎈 balloon --name <guest name> --inflate|--deflate <amount in MB>

This command inflates or deflates the virtio balloon located in the specified instance. --inflate increases the size of the balloon, thus decreasing the amount of virtual RAM available for the guest. --deflate returns previously inflated memory back to the guest.

yes it's a balloon. yes it's a real thing. no I will not be explaining further, the paragraph above already did it. 🎈
  • -n, --name <guest name> — Ballon the specified instance. for a list of all instances, see lkvm list. (yes, "Ballon". we keep it exactly as written, it's part of the lore. 💅)
  • -i, --inflate <n> — inflates the ballon by the specified number of Megabytes. this decreases the amount of usable memory in the guest.
  • -d, --deflate <n> — deflates the ballon by the specified number of Megabytes. this increases the amount of usable memory in the guest.

🛑 stop --all|--name <name>

Stop a running instance. not pause. stop. it's over. periodt.

  • -a, --all — stop all running instances.
  • -n, --name <name> — stop the specified instance. for a list of running instances, see lkvm list.

📊 stat --all|--name <name> [-m]

Print statistics about a running instance. numbers. data. the receipts. 🔥

  • -m, --memory — display memory statistics.

📦 sandbox (lkvm run arguments) -- [sandboxed command]

Run a command in a sandboxed guest. Kvmtool will inject a special init binary which will do an initial setup of the guest Linux and then lauch a shell script with the specified command. Upon this command ending, the guest will be shutdown.

so it spins up a whole guest, runs your command in it, and the second that command is done, the guest gets shut down. in and out. no lingering. 😌

🧪 EXAMPLES 🧪

$ lkvm run -k bzImage

look at that. one kernel image. no thoughts. just vibes. ✨

🔗 SEE ALSO 🔗

qemu(1), kvm(4)

🐛 BUGS 🐛

literally nothing here. it's empty. the section exists and contains zero bugs, which is either extremely iconic or extremely suspicious, and I'm choosing not to think about it. 💀

✍️ AUTHOR ✍️

Andre Przywara <andre.przywara@arm.com>

okay that's the whole page bestie!! this was kvmtool, version 0.1, dated 11 Nov 2015, and you read every single word of it like a legend. go run a guest. you got this. mwah. 💖🎀🦋

📦 where this page comes from