qemu-sanity-check - Man Page

run a simple sanity check on qemu and the Linux kernel

Summary

qemu-sanity-check [options]

Description

qemu-sanity-check is a short shell script that test-boots a Linux kernel under qemu, making sure it boots up to userspace.  The idea is to test the Linux kernel and/or qemu to make sure they are working.

You can use the command on its own:

 qemu-sanity-check

In this case, the script will look for a suitable qemu binary on the $PATH and the latest Linux kernel in /boot (or /lib/modules/VERSION/vmlinuz on some distros) and try to boot that kernel on that qemu.

You can also specify a qemu binary or a Linux kernel (either or both options can be omitted):

 qemu-sanity-check --qemu=/path/to/qemu --kernel=/path/to/vmlinuz

KVM

KVM (kvm or qemu-kvm) can be used in place of qemu.

Kernel Drivers

No kernel modules or special drivers are required except as noted below.  The test uses an initramfs containing a static binary, so the kernel is not required to locate block devices, use virtio, mount filesystems, etc.

The kernel must support only the following, compiled in (not as modules):

  • A serial port (usually: CONFIG_SERIAL_8250=y)
  • Initrd/initramfs (CONFIG_BLK_DEV_INITRD=y)

Options

--help

Display short help message and exit.

--accel=kvm
--accel=tcg
--accel=kvm:tcg

This sets the -machine accel=... parameter which is passed to qemu.

If not set, then kvm:tcg is the default, which means to try to use KVM (hardware-assisted virtualization), and fall back to software emulation if KVM is not possible.

Other typical values of this parameter are: tcg, which means to force software emulation.  kvm, which means to force KVM and fail if KVM is unavailable.

--cpu=CPU

Set the qemu --cpu option.  If not set then a suitable default is picked depending on the architecture and whether KVM is available. You can also use --cpu= to let qemu pick the default.

-i INITRD
--initrd=INITRD

Use the initramfs image named INITRD instead of the default.

-k VMLINUZ
--kernel=VMLINUZ

Use the kernel image VMLINUZ instead of searching for the latest kernel installed in /boot.

-m MACHINE
--machine=MACHINE

Set the qemu -m (machine type) option.  If not set then a suitable default is picked depending on the architecture.  You can also use --machine= to let qemu pick the default.

-q QEMU
--qemu=QEMU

Use the qemu (or KVM) binary QEMU instead of searching $PATH for a suitable binary.

-t TIMEOUT
--timeout=TIMEOUT

Specify a timeout instead of the default which is 10m (10 minutes).

The syntax for the TIMEOUT is described in full in the man page for timeout(1).

-v
--verbose

Print extra debugging information.

-V
--version

Display version and exit.

Exit Status

The exit status is 0 if the Linux kernel booted as far as userspace under qemu; or if the --help or --version options were used.

The exit status is 1 if the kernel boot failed under qemu.

The exit status is 2 if the script itself failed (eg. incorrect command line options were used, a suitable kernel could not be found).

Files

/usr/lib64/qemu-sanity-check/initrd

The default location for the small initramfs image that is used to test that userspace has been reached.

See Also

<http://qemu.org>, <http://kernel.org>

Authors

Richard W.M. Jones <rjones@redhat.com>

Info

2024-07-19 qemu-sanity-check-1.1.6 Virtualization Support