microvm.balloonMem

Amount of balloon memory in megabytes

The way virtio-balloon works is that this is the memory size that the host can request to be freed by the VM. Initial booting of the VM allocates mem+balloonMem megabytes of RAM.

Type: signed integer

Default: 0

Declared by:

microvm.binScripts

Script snippets that end up in the runner package’s bin/ directory

Type: attribute set of strings concatenated with “\n”

Default: { }

Declared by:

microvm.cloud-hypervisor.extraArgs

Extra arguments to pass to cloud-hypervisor.

Type: list of string

Default: [ ]

Declared by:

microvm.cpu

What CPU to emulate, if any. If different from the host architecture, it will have a serious performance hit.

Note: Only supported with qemu.

Type: null or string

Default: null

Declared by:

microvm.crosvm.extraArgs

Extra arguments to pass to crosvm.

Type: list of string

Default: [ ]

Declared by:

microvm.crosvm.pivotRoot

A Hypervisor’s sandbox directory

Type: null or string

Default: null

Declared by:

microvm.declaredRunner

Generated Hypervisor declared by config.microvm.hypervisor

Type: package

Default: "config.microvm.runner.${config.microvm.hypervisor}"

Declared by:

microvm.devices

PCI/USB devices that are passed from the host to the MicroVM

Type: list of (submodule)

Default: [ ]

Example:

[ {
  bus = "pci";
  path = "0000:01:00.0";
} {
  bus = "pci";
  path = "0000:01:01.0";
} {
  # QEMU only
  bus = "usb";
  path = "vendorid=0xabcd,productid=0x0123";
} ]

Declared by:

microvm.devices.*.bus

Device is either on the pci or the usb bus

Type: one of “pci”, “usb”

Declared by:

microvm.devices.*.path

Identification of the device on its bus

Type: string

Declared by:

microvm.forwardPorts

When using the SLiRP user networking (default), this option allows to forward ports to/from the host/guest.

Warning: If the NixOS firewall on the virtual machine is enabled, you also have to open the guest ports to enable the traffic between host and guest.

Note: Currently QEMU supports only IPv4 forwarding.

Type: list of (submodule)

Default: [ ]

Example:

[ # forward local port 2222 -> 22, to ssh into the VM
  { from = "host"; host.port = 2222; guest.port = 22; }

  # forward local port 80 -> 10.0.2.10:80 in the VLAN
  { from = "guest";
    guest.address = "10.0.2.10"; guest.port = 80;
    host.address = "127.0.0.1"; host.port = 80;
  }
]

Declared by:

microvm.forwardPorts.*.from

Controls the direction in which the ports are mapped:

  • <literal>“host”</literal> means traffic from the host ports is forwarded to the given guest port.

  • <literal>“guest”</literal> means traffic from the guest ports is forwarded to the given host port.

Type: one of “host”, “guest”

Default: "host"

Declared by:

microvm.forwardPorts.*.guest.address

The IPv4 address on the guest VLAN.

Type: string

Default: ""

Declared by:

microvm.forwardPorts.*.guest.port

The guest port to be mapped.

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Declared by:

microvm.forwardPorts.*.host.address

The IPv4 address of the host.

Type: string

Default: ""

Declared by:

microvm.forwardPorts.*.host.port

The host port to be mapped.

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Declared by:

microvm.forwardPorts.*.proto

The protocol to forward.

Type: one of “tcp”, “udp”

Default: "tcp"

Declared by:

microvm.graphics.enable

Enable GUI support.

MicroVMs with graphics are intended for the interactive use-case. They cannot be started through systemd jobs.

Support in Hypervisors:

  • qemu starts a Gtk window with the framebuffer of the virtio-gpu

Type: boolean

Default: false

Declared by:

microvm.graphics.socket

Path of vhost-user socket

Type: string

Default: "$HOSTNAME-gpu.sock"

Declared by:

microvm.guest.enable

Whether to enable the microvm.nix guest module at all.

Type: boolean

Default: true

Declared by:

microvm.hugepageMem

Whether to use hugepages as memory backend. (Currently only respected if using cloud-hypervisor)

Type: boolean

Default: false

Declared by:

microvm.hypervisor

Which hypervisor to use for this MicroVM

Choose one of: qemu, cloud-hypervisor, firecracker, crosvm, kvmtool, stratovirt, alioth

Type: one of “qemu”, “cloud-hypervisor”, “firecracker”, “crosvm”, “kvmtool”, “stratovirt”, “alioth”

Default: "qemu"

Declared by:

microvm.initrdPath

Path to the initrd file in the initrd package

Type: path

Default: "${config.system.build.initialRamdisk}/${config.system.boot.loader.initrdFile}"

Declared by:

microvm.interfaces

Network interfaces

Type: list of (submodule)

Default: [ ]

Declared by:

microvm.interfaces.*.bridge

Attach network interface to host bridge interface for type = “bridge”

Type: null or string

Default: null

Declared by:

microvm.interfaces.*.id

Interface name on the host

Type: string

Declared by:

microvm.interfaces.*.mac

MAC address of the guest’s network interface

Type: string

Declared by:

Attach network interface to host interface for type = “macvlan”

Type: string

Declared by:

microvm.interfaces.*.macvtap.mode

The MACVLAN mode to use

Type: one of “private”, “vepa”, “bridge”, “passthru”, “source”

Declared by:

microvm.interfaces.*.type

Interface type

Type: one of “user”, “tap”, “macvtap”, “bridge”

Declared by:

microvm.kernel

Kernel package to use for MicroVM runners. Better set boot.kernelPackages instead.

Type: package

Default: "${config.boot.kernelPackages.kernel}"

Declared by:

microvm.kernelParams

Includes boot.kernelParams but doesn’t end up in toplevel, thereby allowing references to toplevel

Type: list of string

Declared by:

microvm.mem

Amount of RAM in megabytes

Type: signed integer

Default: 512

Declared by:

microvm.preStart

Commands to run before starting the hypervisor

Type: strings concatenated with “\n”

Default: ""

Declared by:

microvm.prettyProcnames

Set a recognizable process name right before executing the Hyperisor.

Type: boolean

Default: true

Declared by:

microvm.qemu.extraArgs

Extra arguments to pass to qemu.

Type: list of string

Default: [ ]

Declared by:

microvm.qemu.machine

QEMU machine model, eg. microvm, or q35

Get a full list with qemu-system-x86_64 -M help

This has a default declared with lib.mkDefault because it depends on ${pkgs.system}.

Type: string

Declared by:

microvm.qemu.machineOpts

Overwrite the default machine model options.

Type: null or (attribute set of string)

Default: null

Declared by:

microvm.qemu.serialConsole

Whether to enable the virtual serial console on qemu.

Type: boolean

Default: true

Declared by:

microvm.runner

Generated Hypervisor runner for this NixOS

Type: attribute set of package

Declared by:

microvm.shares

Shared directory trees

Type: list of (submodule)

Default: [ ]

Declared by:

microvm.shares.*.mountPoint

Where to mount the share inside the container

Type: path

Declared by:

microvm.shares.*.proto

Protocol for this share

Type: one of “9p”, “virtiofs”

Default: "9p"

Declared by:

microvm.shares.*.securityModel

What security model to use for the shared directory

Type: one of “passthrough”, “none”, “mapped”, “mapped-file”

Default: "none"

Declared by:

microvm.shares.*.socket

Socket for communication with virtiofs daemon

Type: null or string

Default: null

Declared by:

microvm.shares.*.source

Path to shared directory tree

Type: non-empty string

Declared by:

microvm.shares.*.tag

Unique virtiofs daemon tag

Type: string

Declared by:

microvm.socket

Hypervisor control socket path

Type: null or string

Default: "${hostName}.sock"

Declared by:

microvm.storeOnDisk

Whether to boot with the storeDisk, that is, unless the host’s /nix/store is a microvm.share.

Type: boolean

Default: true

Declared by:

microvm.user

User to switch to when started as root

Type: null or string

Default: null

Declared by:

microvm.vcpu

Number of virtual CPU cores

Type: signed integer

Default: 1

Declared by:

microvm.virtiofsd.extraArgs

Extra command-line switch to pass to virtiofsd.

Type: list of string

Default: [ ]

Declared by:

microvm.virtiofsd.inodeFileHandles

When to use file handles to reference inodes instead of O_PATH file descriptors (never, prefer, mandatory)

Allows you to overwrite default behavior in case you hit “too many open files” on eg. ZFS. https://gitlab.com/virtio-fs/virtiofsd/-/issues/121

Type: null or one of “never”, “prefer”, “mandatory”

Default: null

Declared by:

microvm.virtiofsd.threadPoolSize

The amounts of threads virtiofsd should spawn. This option also takes the special string \nproc`` which spawns as many threads as the host has cores.

Type: string or (unsigned integer, meaning >=0)

Default: "`nproc`"

Declared by:

microvm.volumes

Disk images

Type: list of (submodule)

Default: [ ]

Declared by:

microvm.volumes.*.autoCreate

Created image on host automatically before start?

Type: boolean

Default: true

Declared by:

microvm.volumes.*.direct

Whether to set O_DIRECT on the disk.

Type: boolean

Default: false

Declared by:

microvm.volumes.*.fsType

Filesystem for automatic creation and mounting

Type: string

Default: "ext4"

Declared by:

microvm.volumes.*.image

Path to disk image on the host

Type: string

Declared by:

microvm.volumes.*.label

Label of the volume, if any. Only applicable if autoCreate is true; otherwise labeling of the volume must be done manually

Type: null or string

Default: null

Declared by:

microvm.volumes.*.mkfsExtraArgs

Set extra Filesystem creation parameters

Type: list of string

Default: [ ]

Declared by:

microvm.volumes.*.mountPoint

If and where to mount the volume inside the container

Type: null or path

Declared by:

microvm.volumes.*.readOnly

Turn off write access

Type: boolean

Default: false

Declared by:

microvm.volumes.*.serial

User-configured serial number for the disk

Type: null or string

Default: null

Declared by:

microvm.volumes.*.size

Volume size if created automatically

Type: signed integer

Declared by:

microvm.vsock.cid

Virtual Machine address; setting it enables AF_VSOCK

The following are reserved:

  • 0: Hypervisor
  • 1: Loopback
  • 2: Host

Type: null or signed integer

Default: null

Declared by:

microvm.writableStoreOverlay

Path to the writable /nix/store overlay.

If set to a filesystem path, the initrd will mount /nix/store as an overlay filesystem consisting of the read-only part as a host share or from the built storeDisk, and this configuration option as the writable overlay part. This allows you to build nix derivations inside the VM.

Make sure that the path points to a writable filesystem (tmpfs, volume, or share).

Type: null or string

Default: null

Example: "/nix/.rw-store"

Declared by: