virt-qemu-run

Run a QEMU virtual machine

$ virt-qemu-run [path/to/guest.xml]

$ virt-qemu-run [[-r|--root]] [path/to/directory] [path/to/guest.xml]

$ virt-qemu-run [[-v|--verbose]] [path/to/guest.xml]

$ virt-qemu-run [[-h|--help]]

virt-qemu-run [OPTIONS] disk.img [COMMAND [ARG...]]

-a file, --add file
    Add an extra disk image to the guest. This disk will be accessible during the command execution.

-A file, --add-ro file
    Add an extra disk image as read-only to the guest environment.

--arch guest-arch
    Specify the guest architecture (e.g., x86_64, i686). Defaults to the host architecture.

-c URI, --connect URI
    Connect to a specified libvirt URI. This is usually only needed for debugging libvirt drivers.

--debug
    Enable debug messages, showing verbose information about the internal operations.

--extra-args args
    Pass extra arguments to the guest kernel command line.

--filesystem type
    Explicitly specify the filesystem type for the primary disk image (e.g., ext4, xfs).

-g, --gui
    Show the QEMU graphical interface. This is rarely useful for virt-qemu-run.

--ignore-timestamps
    Do not update the disk image's timestamps, useful for testing.

-i, --iso
    Treat the primary disk image as an ISO filesystem image.

--key device:key
    Provide a decryption key for a LUKS-encrypted device within the disk image.

--label device:label
    Mount a device with a specific filesystem label instead of its path.

-m memsize, --memsize memsize
    Set the guest memory size in megabytes (MB).

--ro
    Mount the primary disk image read-only, preventing any modifications.

--rw
    Mount the primary disk image read-write (this is the default behavior).

--selinux
    Enable SELinux support within the guest environment.

--trace
    Enable libguestfs API tracing, showing all calls to the libguestfs API.

--verbose
    Enable verbose messages during operation.

-V, --version
    Display the version number of virt-qemu-run and exit.

virt-qemu-run is a specialized tool within the libguestfs suite designed to execute commands directly inside a virtual machine's disk image without requiring a full VM boot. It achieves this by leveraging QEMU's capabilities to access and manipulate disk contents directly. Primarily used for testing libguestfs itself, it's generally not recommended for typical users who should instead use higher-level tools like guestfish. The command creates a minimal guest environment, redirects standard I/O, and uses the guest's kernel and initrd to run the specified command. It's a lightweight way to interact with a disk image's internal operating system.

virt-qemu-run is primarily an internal tool for libguestfs development and testing.
It does not provide a full virtual machine environment; networking or complex hardware interactions are not typically supported.
Running arbitrary commands on untrusted disk images could pose security risks, as the command is executed with significant privileges within the minimal guest environment.
It requires a guest kernel and initrd to be available on the host system to boot the minimal environment.

If no COMMAND is specified, virt-qemu-run will default to executing a small helper script named virt-qemu-run-helper inside the guest, typically running /bin/sh -c 'virt-qemu-run-helper'. This script is provided by libguestfs and sets up the minimal environment.

The command exits with 0 upon successful execution of the specified command within the guest. A non-zero exit status indicates an error or a failure in executing the command inside the guest, or an issue with virt-qemu-run itself.

libguestfs, which includes virt-qemu-run, was initiated by Richard Jones around 2008. This utility serves as a low-level testing component within the project, designed to validate the core functionalities of libguestfs which involve direct manipulation of virtual machine disk images. Its development is closely tied to the evolution and expansion of the libguestfs library itself, ensuring the reliability of disk image operations without the overhead of full VM emulation.

guestfish(1), libguestfs(3), libguestfs-tools(1), qemu-system-x86_64(1)