VNG(1) virtme-ng VNG(1)

vng - Quickly run kernels inside a virtualized snapshot of your live system

vng [-h] [--version] [--run [RUN] | --build | --clean | --dump DUMP] [--dry-run] [--skip-config] [--no-virtme-ng-init] [--gdb] [--snaps] [--debug] [--kconfig] [--skip-modules] [--commit COMMIT] [--config CONFIG] [--configitem CONFIGITEM] [--compiler COMPILER] [--busybox PATH_TO_BUSYBOX] [--qemu QEMU] [--name NAME] [--user USER] [--root ROOT] [--root-release ROOT_RELEASE] [--rw] [--force-9p] [--disable-microvm] [--disable-kvm] [--cwd CWD] [--pwd] [--rodir RODIR] [--rwdir RWDIR] [--overlay-rwdir OVERLAY_RWDIR] [--cpus CPUS] [--memory MEMORY] [--numa MEM[,cpus=FIRST_CPU1[-LAST_CPU1]][,cpus=FIRST_CPU2[-LAST_CPU2]]...] [--numa-distance SRC,DST=VAL] [--balloon] [--network NETWORK] [--net-mac-address NET_MAC_ADDRESS] [--disk PATH] [--exec EXEC] [--append APPEND] [--force-initramfs] [--sound] [--graphics] [--verbose] [--quiet] [--qemu-opts QEMU_OPTS] [--build-host BUILD_HOST] [--build-host-exec-prefix BUILD_HOST_EXEC_PREFIX] [--build-host-vmlinux] [--arch ARCH] [--cross-compile CROSS_COMPILE] [--force] [--nvgpu [GPU PCI Address]] [--console [PORT]] [--console-client [PORT]] [--ssh [PORT]] [--ssh-client [PORT]] [--remote-cmd COMMAND] [envs ...]

Build and run kernels inside a virtualized snapshot of your live system

Additional Makefile variables

show program's version number and exit
Only show the commands without actually running them.
[deprecated] Do not re-generate kernel .config
Fallback to the bash virtme-init (useful for debugging/development)
Attach a debugging session to a running instance started with --debug
Allow to execute snaps inside virtme-ng
Start the instance with debugging enabled (allow to generate crash dumps)
Only override the kernel .config without building/running anything
Run a really fast build by skipping external modules (no external modules support)
Use a kernel identified by a specific commit id, tag or branch
Use one (or more) specific kernel .config snippet to override default config settings
add a CONFIG_ITEM=val, after --config <fragments>, these override previous config settings
[deprecated] Compiler to be used as CC when building the kernel. Please set CC= and HOSTCC= variables in the virtme-ng command line instead.
Use the specified busybox binary
Use the specified QEMU binary
Set guest hostname and qemu -name flag
Change user inside the guest (default is same user as the host)
Pass a specific chroot to use inside the virtualized kernel (useful with --arch)
Use a target Ubuntu release to create a new chroot (used with --root)
Give the guest read-write access to its root filesystem. WARNING: this can be dangerous for the host filesystem!
Use legacy 9p filesystem as rootfs
Avoid using the "microvm" QEMU architecture (only on x86_64)
Avoid using hardware virtualization / KVM
Change guest working directory (default is current working directory when possible)
[deprecated] --pwd is set implicitly by default
Supply a read-only directory to the guest.Use --rodir=path or --rodir=guestpath=hostpath
Supply a read/write directory to the guest.Use --rwdir=path or --rwdir=guestpath=hostpath
Supply a directory that is r/w to the guest but read-only in the host.Use --overlay-rwdir=path.
Set guest CPU count (qemu -smp flag)
Set guest memory size (qemu -m flag)
Create a NUMA node in the guest. Use this option multiple times to create more NUMA nodes. The total memory size assigned to NUMA nodes must match the guest memory size (specified with --memory/-m). This option implicitly disables the microvm architecture.
Set a distance of VAL between NUMA node SRC_NODE and DST_NODE. Use this option multiple times to define multiple distances between NUMA nodes. This option is used only together with --numa.
Allow the host to ask the guest to release memory
Enable network access: user, bridge(=<br>), loop
The MAC address to assign to the NIC interface, e.g. 52:54:00:12:34:56. The last octet will be incremented for the next network devices.
Add a file as virtio-scsi disk (can be used multiple times)
Execute a command inside the kernel and exit
Additional kernel boot options (can be used multiple times)
Use an initramfs even if unnecessary
Enable audio device (if the architecture supports it)
Show graphical output instead of using a console.
Increase console output verbosity.
Override verbose mode (disable --verbose).
Additional arguments for QEMU (can be used multiple times) or bundled together: --qemu-opts='...'
Perform kernel build on a remote server (ssh access required)
Prepend a command (e.g., chroot) to the make command executed on the remote build host
Copy vmlinux back from the build host
Generate and test a kernel for a specific architecture (default is host architecture)
Set cross-compile prefix
Force reset git repository to target branch or commit (warning: this may drop uncommitted changes), and force kernel config override
Add a passthrough NVIDIA GPU

Run a specified kernel; --run can accept one of the following arguments: 1) nothing (in this case it'll try to boot the same kernel running on the host), 2) a kernel binary (like ./arch/x86/boot/bzImage), 3) a directory (where it'll try to find a valid kernel binary file), 4) an upstream version, for example `vng --run v6.6.17` (in this case vng will download a precompiled upstream kernel from the Ubuntu mainline repository)
Build the kernel in the current directory (or remotely if used with --build-host)
Clean the kernel repository (local or remote if used with --build-host)
Generate a memory dump of the running kernel (instance needs to be started with --debug)

Enable a server to communicate later from the host using '--console-client'. By default, a simple console will be offered using a VSOCK connection, and 'socat' for the proxy.
Connect to a VM launched with the '--console' option for a remote control.
Enable SSH server to communicate later from the host to using '--ssh-client'.
Connect to a VM launched with the '--ssh' option for a remote control.
To start in the VM a different command than the default one (--server), or to launch this command instead of a prompt (--client).

virtme-ng is a tool that allows to easily and quickly recompile and test a Linux kernel, starting from the source code. It allows to re‐ compile the kernel in a few minutes (rather than hours), then the kernel is automatically started in a virtualized environment that is an exact copy-on-write copy of your live system, which means that any changes made to the virtualized environment do not affect the host system.

In order to do this, a minimal config is produced (with the bare minimum support to test the kernel inside qemu), then the selected kernel is automatically built and started inside qemu, using the filesystem of the host as a copy-on-write snapshot.

This means that you can safely destroy the entire filesystem, crash the kernel, etc. without affecting the host.

NOTE: kernels produced with virtme-ng are lacking lots of features, in order to reduce the build time to the minimum and still provide you a usable kernel capable of running your tests and experiments.

virtme-ng is based on virtme, written by Andy Lutomirski <luto@kernel.org>.

virtme-ng is written by Andrea Righi <arighi@nvidia.com>
Based on virtme by Andy Lutomirski <luto@kernel.org>

The latest version of virtme-ng may be downloaded from https://github.com/arighi/virtme-ng

2025-01-03 virtme-ng 1.32