NAME¶

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

SYNOPSIS¶

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]]...] [--balloon] [--network {user,bridge,loop}] [--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]] [envs ...]

DESCRIPTION¶

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

envs

Additional Makefile variables

OPTIONS¶

--version, -V

show program's version number and exit

--dry-run

Only show the commands without actually running them.

--skip-config, -s

[deprecated] Do not re-generate kernel .config

--no-virtme-ng-init

Fallback to the bash virtme-init (useful for debugging/development)

--gdb

Attach a debugging session to a running instance started with --debug

--snaps

Allow to execute snaps inside virtme-ng

--debug

Start the instance with debugging enabled (allow to generate crash dumps)

--kconfig, -k

Only override the kernel .config without building/running anything

--skip-modules, -S

Run a really fast build by skipping external modules (no external modules support)

--commit COMMIT, -c COMMIT

Use a kernel identified by a specific commit id, tag or branch

--config CONFIG, --custom CONFIG, -f CONFIG

Use one (or more) specific kernel .config snippet to override default config settings

--configitem CONFIGITEM

add a CONFIG_ITEM=val, after --config <fragments>, these override previous config settings

--compiler COMPILER

[deprecated] Compiler to be used as CC when building the kernel. Please set CC= and HOSTCC= variables in the virtme-ng command line instead.

--busybox PATH_TO_BUSYBOX

Use the specified busybox binary

--qemu QEMU

Use the specified QEMU binary

--name NAME

Set guest hostname and qemu -name flag

--user USER

Change user inside the guest (default is same user as the host)

--root ROOT

Pass a specific chroot to use inside the virtualized kernel (useful with --arch)

--root-release ROOT_RELEASE

Use a target Ubuntu release to create a new chroot (used with --root)

--rw

Give the guest read-write access to its root filesystem. WARNING: this can be dangerous for the host filesystem!

--force-9p

Use legacy 9p filesystem as rootfs

--disable-microvm

Avoid using the "microvm" QEMU architecture (only on x86_64)

--disable-kvm

Avoid using hardware virtualization / KVM

--cwd CWD

Change guest working directory (default is current working directory when possible)

--pwd

[deprecated] --pwd is set implicitly by default

--rodir RODIR

Supply a read-only directory to the guest.Use --rodir=path or --rodir=guestpath=hostpath

--rwdir RWDIR

Supply a read/write directory to the guest.Use --rwdir=path or --rwdir=guestpath=hostpath

--overlay-rwdir OVERLAY_RWDIR

Supply a directory that is r/w to the guest but read-only in the host.Use --overlay-rwdir=path.

--cpus CPUS, -p CPUS

Set guest CPU count (qemu -smp flag)

--memory MEMORY, -m MEMORY

Set guest memory size (qemu -m flag)

--numa MEM[,cpus=FIRST_CPU1[-LAST_CPU1]][,cpus=FIRST_CPU2[-LAST_CPU2]]...

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.

--balloon

Allow the host to ask the guest to release memory

--network {user,bridge,loop}, -n {user,bridge,loop}

Enable network access

--disk PATH, -D PATH

Add a file as virtio-scsi disk (can be used multiple times)

--exec EXEC, -e EXEC

Execute a command inside the kernel and exit

--append APPEND, -a APPEND

Additional kernel boot options (can be used multiple times)

--force-initramfs

Use an initramfs even if unnecessary

--sound

Enable audio device (if the architecture supports it)

--graphics, -g

Show graphical output instead of using a console.

--verbose, -v

Increase console output verbosity.

--quiet, -q

Override verbose mode (disable --verbose).

--qemu-opts QEMU_OPTS, -o QEMU_OPTS

Additional arguments for QEMU (can be used multiple times) or bundled together: --qemu-opts='...'

--build-host BUILD_HOST

Perform kernel build on a remote server (ssh access required)

--build-host-exec-prefix BUILD_HOST_EXEC_PREFIX

Prepend a command (e.g., chroot) to the make command executed on the remote build host

--build-host-vmlinux

Copy vmlinux back from the build host

--arch ARCH

Generate and test a kernel for a specific architecture (default is host architecture)

--cross-compile CROSS_COMPILE

Set cross-compile prefix

--force

Force reset git repository to target branch or commit (warning: this may drop uncommitted changes), and force kernel config override

--nvgpu [GPU PCI Address]

Add a passthrough NVIDIA GPU

ACTION¶

--run [RUN], -r [RUN]

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, -b

Build the kernel in the current directory (or remotely if used with --build-host)

--clean, -x

Clean the kernel repository (local or remote if used with --build-host)

--dump DUMP, -d DUMP

Generate a memory dump of the running kernel (instance needs to be started with --debug)

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 <luto@kernel.org>.

AUTHOR¶

virtme-ng is written by Andrea Righi <arighi@nvidia.com>

Based on virtme by Andy Lutomirski <luto@kernel.org>

DISTRIBUTION¶

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