Global Parameters

cmd_socket_path = pathname;

Unix domain socket path. The default value is "/var/run/bmd.sock".

cmd_socket_mode = mode;

File mode bits in octal number. The default value is "0600."

vars_directory = dirname;

The directory to write UEFI variables. The default value is "/usr/local/var/cache/bmd".

nmdm_offset = noffset;

The offset of auto assigned nmdm number. The default value is "200".

pid_file = filepath;

The file to write bmd(8) pid. The default value is "/var/run/bmd.pid".

Vm Parameters

boot = no | yes | oneshot | always;

no

Do not boot at bmd(8) starts. This is the default.

yes

Boot at bmd(8) starts or reloads configurations.

oneshot

Boot at bmd(8) starts and never reboots.

always

Boot at bmd(8) starts or reloads configurations. And always reboots the VM after successful shutdown. If the VM exits with an error, bmd(8) does not reboot again.

boot_delay = delay_second;

Specify the boot delay time in seconds. The default value is "0".

comport = com_device;

Alias to the 'com1' parameter.

com1 = com_device;

Specify com1 port device (e.g. /dev/nmdm0B). "auto" assigns a nmdm device automatically.

com2 = com_device;

Specify com2 port device as same as com1.

com3 = com_device;

Specify com3 port device as same as com1.

com4 = com_device;

Specify com4 port device as same as com1.

debug_port = port_number;

Gdb debug port.

disk = (+=) [type:] [options:] filename;

The type is one of "nvme", "ahci", "ahci-hd", "virtio-blk" or can be omitted to specify the default type "virtio-blk". The options are one or colon separated strings of follows :

nocache

Open the file with O_DIRECT.

direct

Open the file using O_SYNC.

readonly

Force the file to be opened read-only.

nodelete

Disable emulation of guest trim requests via DIOCGDELETE requests.

noexist

Disable disk image check while loading the configuration. The bmd will continue to load the configuration and boot normally even if the disk image isn't present. The disk image must be supplied before VM boot.

The filename is disk image filename (e.g. /var/images/vm-disk-0) or device file (e.g. /dev/zvol/zpool/vm-disk-1).

sharefs = (+=) “[readonly:] sharename = pathname”;

Export pathname under the name of sharename to the guest VM via “virtio-9p” device. Write access will be denied, if readonly option is set. Note that the value of ‘sharefs’ key must contain a equal character ‘=’. It must be escaped by a backslash or enclosed in double quotes.

err_logfile = filename;

Open the log file for the bhyve messages. This file is written with the VM owner privilege.

graphics = yes | no;

Set "yes" to use frame a buffer device. The default is "no".

graphics_listen = address;

Set the vnc listen address. The default value is "0.0.0.0".

graphics_port = port_num;

Set the vnc port number. The default value is "5900".

graphics_password = password;

Set the password for vnc access. This is not set by default.

graphics_res = width x height;

Set the vnc resolution. The default value is "1280x720".

graphics_vga = on | off | io;

Set the vga conf of bhyve. The default is "io".

graphics_wait = yes | no;

Wait for vnc connection before booting. The default is "no".

hostbridge = standard | amd;

Set the hostbridge device. The default is "standard".

install = yes | no;

Set "yes" to boot from ISO. The install mode VM will never restart, it always quits the bhyve execution. After the installation has finished, change this configuration to "no". The default is "no".

installcmd = install_cmd;

Install script for grub-bhyve. Setting "auto" inspects iso image. e.g. "kopenbsd -h com0 (cd0)/6.9/amd64/bsd.rd"

iso = (+=) image_filepath;

ISO image filename.

keymap = keymap;

Keymap for vnc.

loadcmd = load_cmd;

Boot script for grub-bhyve. Setting "auto" inspects disk image. e.g. "kopenbsd -h com0 -r sd0a (hd0,gpt4)/bsd"

loader = bhyveload | grub | uefi;

Specify boot loader. This parameter is mandatory.

loader_timeout = timeout_sec;

Loader timeout in seconds. If set to 0 or negative value, timeout is disabled. The default value is "15".

bhyve_env = (+=) “Environment_definition”;

Specify an environment variable for the bhyve process. Note that Environment_definition must contain a equal character '='. It must be escaped by a backslash or enclosed in double quotes. e.g. "BHYVE_TMPDIR=/tmp"

bhyveload_loader = OS_loader_path;

Specify the path to the OS loader. It is passed with "-l" to the bhyveload. If omitted, the default OS loader "/boot/userboot.so" is used.

bhyveload_env = (+=) “Environment_definition”;

Specify an environment variable for the FreeBSD boot loader. It is passed with "-e" to the bhyveload. Note that Environment_definition must contain a equal character ‘=’. It must be escaped by a backslash or enclosed in double quotes. e.g. "machdep.hyperthreading_allowed=0"

memory = memsize[K|k|M|m|G|g|T|t];

Specify physical memory size. This parameter is mandatory.

name = vmname;

Change the virtual machine name from vm section name;

ncpu = num_sockets [:num_cores [:num_threads]];

Set the number of CPUs or CPU topology for VM. The default value is 1 for each parameters. e.g. 1:4:2 specifies cpus=8,sockets=1,cores=4,threads=2 to the bhyve.

cpu_pin = (+=) vcpu:hostcpu;

Pin guest's virtual CPU vcpu to hostcpu. Host CPUs and guest virtual CPUs are numberd starting from 0. The number of vcpu must be smaller than ncpu value. The number of hostcpu must be smaller than hw.ncpu sysctl(8) value.

network = (+=) [type:] [wol:] [[MAC address]:] bridge;

The type is one of "e1000", "virtio-net" or can be omitted to specify the default type "virtio-net". If the wol flag is set, the daemon waits for a Wake on LAN packet and boots the VM if received. The wol flag requires a MAC address to be supplied. The MAC address is an ASCII string in ethers(5) format and must be embraced by '[' ']' and followed by ':'. The MAC address can be omitted to be assigned by the bhyve(8). Bridge is a bridge name that a tap interface to be added. If a bridge name starts with ‘vale’, the network interface will be joined to the vale(4) switch and no tap interface will be assigned. The vale port is named "vm${ID}p${nic_id}". e.g. "bridge1" or "vale1".

owner = user_name [: group_name];

The owner of VM. The owner is permitted to control the VM via bmdctl(8). If group_name is specified, users of group_name are also permitted. The default value is as same as the file owner in which vm section is written. Setting owner is permitted if the file owner is root privileged user or the user_name is as same as the file owner.

passthru = (+=) bus/slot/function;

PCI passthrough device id. e.g. “1/0/130”. This implicitly sets ‘wired_memory’ to true.

reboot_on_change = yes | no;

Set "yes" to force ACPI reboot if VM config file is change. The default is "no".

stop_timeout = timeout_sec;

VM exit timeout in seconds. if expired, force to kill VM. The default value is "300". This timeout will never be disabled.

tpm = [type:] dev [: version];

Specify a TPM device for the VM. The dev paramter is a tpm device name (e.g. "/dev/tpm0") for the passthru device or a UNIX Domain Socket pathname for the TPM software instance. The type parameter is one of "passthru" and "swtpm". The default value is "passthru". The default value of the version is "2.0".

utctime = yes | no;

Set "yes" for RTC to keep UTC time. Set "no" for RTC to keep localtime. The default value is "yes".

virt_random = yes | no;

Set "yes" to add a virtio random device. The default is "no".

wired_memory = yes | no;

Set "yes" to wire VM memory. The default is "no".

x2apic = yes | no;

Set "yes" to configure the guest local APIC in x2APIC mode. The default is "no". This option is available on the amd64 platform.

xhci_mouse = yes | no;

Set "yes" to use xhci tablet. The default is "no".

hda = (+=) [play_dev] [: rec_dev];

Set High Definition Audio devices. Typically, ‘/dev/dsp0’ is used for both play_dev and rec_dev. The rec_dev must follow a colon (:). If you omit a play_dev, start with a colon, and rec_dev follows.

String format

Parameter values, including vm names and template names, can be single tokens or quoted strings. A token is any sequence of characters that are not considered special in the syntax of the configuration file (such as a semicolon or whitespace). If a value contains anything more than letters, numbers, dots, dashes and underscores, it is advisable to put quote marks around that value. Either single or double quotes may be used.

Special characters may be quoted by preceding them with a backslash. Common C-style backslash character codes are also supported, including control characters and octal or hex ASCII codes. A backslash at the end of a line will ignore the subsequent newline and continue the string at the start of the next line.

Variables

A string may use shell-style variable substitution. A variable name preceded by a dollar sign, and possibly enclosed in braces, will be replaced with the value of variable. Variable substitution occurs in unquoted tokens or in double-quoted strings, but not in single-quote strings.

A variable is defined in the way that the variable name is preceded with a dollar sign:

$pathname = "/var/spool/vm/images";

Variables belongs to either global or vm scope. The global scope variables are defined in the global section and referred in all other sections. The vm scope variable is defined in vm sections and available for the vm configurations. Variables in template section belongs to vm scope that applies the template. Vm scope variables before applying templates is available in the template. Variables defined in a template can be referred after applying the template. The following pre-defined variables are available.

Arithmetic Expansion

Like sh(1), Arithmetic expansion provides a mechanism for evaluating an arithmetic expression:

The allowed expressions are a subset of sh(1), summarized blow.

Macros

2 macros are available.

.apply template_name [(arg1, ...), template_name2];

Apply the template(s) with optional arguments. This macro can be written in the vm and template sections.

.include include_pattern;

Include another configuration file(s). This macro must be written outside of the sections. This is only one exception not to be written in the sections. The include_pattern can contain special characters ‘*’, ‘?’, or ‘[’, ‘]’ that matches as same as shell wildcard. The include_pattern can contain global scope variable which is defined earlier than this macro.