.TH VNG "1" "2025\-01\-03" "virtme\-ng 1.32" "virtme\-ng" .SH NAME vng \- Quickly run kernels inside a virtualized snapshot of your live system .SH SYNOPSIS .B 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 ...] .SH DESCRIPTION Build and run kernels inside a virtualized snapshot of your live system .TP \fBenvs\fR Additional Makefile variables .SH OPTIONS .TP \fB\-\-version\fR, \fB\-V\fR show program's version number and exit .TP \fB\-\-dry\-run\fR Only show the commands without actually running them. .TP \fB\-\-skip\-config\fR, \fB\-s\fR [deprecated] Do not re\-generate kernel .config .TP \fB\-\-no\-virtme\-ng\-init\fR Fallback to the bash virtme\-init (useful for debugging/development) .TP \fB\-\-gdb\fR Attach a debugging session to a running instance started with \-\-debug .TP \fB\-\-snaps\fR Allow to execute snaps inside virtme\-ng .TP \fB\-\-debug\fR Start the instance with debugging enabled (allow to generate crash dumps) .TP \fB\-\-kconfig\fR, \fB\-k\fR Only override the kernel .config without building/running anything .TP \fB\-\-skip\-modules\fR, \fB\-S\fR Run a really fast build by skipping external modules (no external modules support) .TP \fB\-\-commit\fR \fI\,COMMIT\/\fR, \fB\-c\fR \fI\,COMMIT\/\fR Use a kernel identified by a specific commit id, tag or branch .TP \fB\-\-config\fR \fI\,CONFIG\/\fR, \fB\-\-custom\fR \fI\,CONFIG\/\fR, \fB\-f\fR \fI\,CONFIG\/\fR Use one (or more) specific kernel .config snippet to override default config settings .TP \fB\-\-configitem\fR \fI\,CONFIGITEM\/\fR add a CONFIG_ITEM=val, after \-\-config , these override previous config settings .TP \fB\-\-compiler\fR \fI\,COMPILER\/\fR [deprecated] Compiler to be used as CC when building the kernel. Please set CC= and HOSTCC= variables in the virtme\-ng command line instead. .TP \fB\-\-busybox\fR \fI\,PATH_TO_BUSYBOX\/\fR Use the specified busybox binary .TP \fB\-\-qemu\fR \fI\,QEMU\/\fR Use the specified QEMU binary .TP \fB\-\-name\fR \fI\,NAME\/\fR Set guest hostname and qemu \-name flag .TP \fB\-\-user\fR \fI\,USER\/\fR Change user inside the guest (default is same user as the host) .TP \fB\-\-root\fR \fI\,ROOT\/\fR Pass a specific chroot to use inside the virtualized kernel (useful with \-\-arch) .TP \fB\-\-root\-release\fR \fI\,ROOT_RELEASE\/\fR Use a target Ubuntu release to create a new chroot (used with \-\-root) .TP \fB\-\-rw\fR Give the guest read\-write access to its root filesystem. WARNING: this can be dangerous for the host filesystem! .TP \fB\-\-force\-9p\fR Use legacy 9p filesystem as rootfs .TP \fB\-\-disable\-microvm\fR Avoid using the "microvm" QEMU architecture (only on x86_64) .TP \fB\-\-disable\-kvm\fR Avoid using hardware virtualization / KVM .TP \fB\-\-cwd\fR \fI\,CWD\/\fR Change guest working directory (default is current working directory when possible) .TP \fB\-\-pwd\fR [deprecated] \-\-pwd is set implicitly by default .TP \fB\-\-rodir\fR \fI\,RODIR\/\fR Supply a read\-only directory to the guest.Use \-\-rodir=path or \-\-rodir=guestpath=hostpath .TP \fB\-\-rwdir\fR \fI\,RWDIR\/\fR Supply a read/write directory to the guest.Use \-\-rwdir=path or \-\-rwdir=guestpath=hostpath .TP \fB\-\-overlay\-rwdir\fR \fI\,OVERLAY_RWDIR\/\fR Supply a directory that is r/w to the guest but read\-only in the host.Use \-\-overlay\-rwdir=path. .TP \fB\-\-cpus\fR \fI\,CPUS\/\fR, \fB\-p\fR \fI\,CPUS\/\fR Set guest CPU count (qemu \-smp flag) .TP \fB\-\-memory\fR \fI\,MEMORY\/\fR, \fB\-m\fR \fI\,MEMORY\/\fR Set guest memory size (qemu \-m flag) .TP \fB\-\-numa\fR \fI\,MEM[,cpus=FIRST_CPU1[\-LAST_CPU1]][,cpus=FIRST_CPU2[\-LAST_CPU2]]...\/\fR 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. .TP \fB\-\-numa\-distance\fR \fI\,SRC,DST=VAL\/\fR 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. .TP \fB\-\-balloon\fR Allow the host to ask the guest to release memory .TP \fB\-\-network\fR \fI\,NETWORK\/\fR, \fB\-n\fR \fI\,NETWORK\/\fR Enable network access: user, bridge(=
), loop .TP \fB\-\-net\-mac\-address\fR \fI\,NET_MAC_ADDRESS\/\fR 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. .TP \fB\-\-disk\fR \fI\,PATH\/\fR, \fB\-D\fR \fI\,PATH\/\fR Add a file as virtio\-scsi disk (can be used multiple times) .TP \fB\-\-exec\fR \fI\,EXEC\/\fR, \fB\-e\fR \fI\,EXEC\/\fR Execute a command inside the kernel and exit .TP \fB\-\-append\fR \fI\,APPEND\/\fR, \fB\-a\fR \fI\,APPEND\/\fR Additional kernel boot options (can be used multiple times) .TP \fB\-\-force\-initramfs\fR Use an initramfs even if unnecessary .TP \fB\-\-sound\fR Enable audio device (if the architecture supports it) .TP \fB\-\-graphics\fR, \fB\-g\fR Show graphical output instead of using a console. .TP \fB\-\-verbose\fR, \fB\-v\fR Increase console output verbosity. .TP \fB\-\-quiet\fR, \fB\-q\fR Override verbose mode (disable \-\-verbose). .TP \fB\-\-qemu\-opts\fR \fI\,QEMU_OPTS\/\fR, \fB\-o\fR \fI\,QEMU_OPTS\/\fR Additional arguments for QEMU (can be used multiple times) or bundled together: \-\-qemu\-opts='...' .TP \fB\-\-build\-host\fR \fI\,BUILD_HOST\/\fR Perform kernel build on a remote server (ssh access required) .TP \fB\-\-build\-host\-exec\-prefix\fR \fI\,BUILD_HOST_EXEC_PREFIX\/\fR Prepend a command (e.g., chroot) to the make command executed on the remote build host .TP \fB\-\-build\-host\-vmlinux\fR Copy vmlinux back from the build host .TP \fB\-\-arch\fR \fI\,ARCH\/\fR Generate and test a kernel for a specific architecture (default is host architecture) .TP \fB\-\-cross\-compile\fR \fI\,CROSS_COMPILE\/\fR Set cross\-compile prefix .TP \fB\-\-force\fR Force reset git repository to target branch or commit (warning: this may drop uncommitted changes), and force kernel config override .TP \fB\-\-nvgpu\fR \fI\,[GPU PCI Address]\/\fR Add a passthrough NVIDIA GPU .SH ACTION .TP \fB\-\-run\fR \fI\,[RUN]\/\fR, \fB\-r\fR \fI\,[RUN]\/\fR 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) .TP \fB\-\-build\fR, \fB\-b\fR Build the kernel in the current directory (or remotely if used with \-\-build\-host) .TP \fB\-\-clean\fR, \fB\-x\fR Clean the kernel repository (local or remote if used with \-\-build\-host) .TP \fB\-\-dump\fR \fI\,DUMP\/\fR, \fB\-d\fR \fI\,DUMP\/\fR Generate a memory dump of the running kernel (instance needs to be started with \-\-debug) .SH REMOTE CONSOLE .TP \fB\-\-console\fR \fI\,[PORT]\/\fR 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. .TP \fB\-\-console\-client\fR \fI\,[PORT]\/\fR Connect to a VM launched with the '\-\-console' option for a remote control. .TP \fB\-\-ssh\fR \fI\,[PORT]\/\fR Enable SSH server to communicate later from the host to using '\-\-ssh\-client'. .TP \fB\-\-ssh\-client\fR \fI\,[PORT]\/\fR Connect to a VM launched with the '\-\-ssh' option for a remote control. .TP \fB\-\-remote\-cmd\fR \fI\,COMMAND\/\fR To start in the VM a different command than the default one (\-\-server), or to launch this command instead of a prompt (\-\-client). .SH COMMENTS 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 . .SH AUTHOR .nf virtme-ng is written by Andrea Righi .fi .nf Based on virtme by Andy Lutomirski .fi .SH DISTRIBUTION The latest version of virtme\-ng may be downloaded from .UR https://github.com/arighi/virtme\-ng .UE