---
name: "bhyve_config"
section: "5"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/bhyve_config"
---

# bhyve\_config(5)

bhyve configuration variables

## NAME

**bhyve\_config** – bhyve configuration variables

## DESCRIPTION

[bhyve(8)](/bhyve/8.md) uses a hierarchical tree of configuration variables to describe global and per-device settings. Internal nodes in this tree do not have a value, only leaf nodes have values. This manual describes the configuration variables understood by [bhyve(8)](/bhyve/8.md). If additional variables are defined, [bhyve(8)](/bhyve/8.md) will ignore them and will not emit errors for unknown variables. However, these additional variables can be referenced by other variables as described below.

## VARIABLE VALUES

Configuration variable values are stored as strings. A configuration variable value may refer to one or more other configuration values by name. Instances of the pattern ‘%(*var*)’ are replaced by the value of the configuration variable *var*. To avoid unwanted expansion, ‘%’ characters can be escaped by a leading ‘%’. For example, if a configuration variable *disk* uses the value */dev/zvol/bhyve/%(name)*, then the final value of the *disk* variable will be set to the path of a ZFS volume whose name matches the name of the virtual machine on the pool *bhyve*.

Some configuration variables may be interpreted as a boolean value. For those variables the following case-insensitive values may be used to indicate true:

- true

- on

- yes

- 1

The following values may be used to indicate false:

- false

- off

- no

- 0

Some configuration variables may be interperted as an integer. For those variables, any syntax supported by [strtol(3)](/strtol/3.md) may be used.

## GLOBAL SETTINGS

### Architecture Neutral Settings

| | | | |
| --- | --- | --- | --- |
| **Name** | **Format** | **Default** | **Description** |
| *name* | string |  |  |
| *cpus* | integer | 1 |  |
| *cores* | integer | 1 |  |
| *threads* | integer | 1 |  |
| *sockets* | integer | 1 |  |
| *memory.guest\_in\_core* | bool | false |  |
| *memory.size* | string | 256M |  |
| *memory.wired* | bool | false |  |
| *bootrom* | path |  |  |
| *bootvars* | path |  |  |
| *acpi\_tables* | bool | true |  |
| *acpi\_tables\_in\_memory* | bool | true |  |
| *destroy\_on\_poweroff* | bool | false |  |
| *gdb.address* | string | localhost |  |
| *gdb.port* | integer | 0 |  |
| *gdb.wait* | bool | false |  |
| *keyboard.layout* | string |  |  |
| *pci.enable\_bars* | bool |  |  |
| *rtc.use\_localtime* | bool | true |  |
| *uuid* | string |  |  |
| *virtio.msix* | bool | true |  |
| *config.dump* | bool | false |  |
| *bios.vendor* | string | BHYVE |  |
| *bios.version* | string | 14.0 |  |
| *bios.release\_date* | string | 10/17/2021 |  |
| *system.family\_name* | string | Virtual Machine |  |
| *system.manufacturer* | string | FreeBSD |  |
| *system.product\_name* | string | BHYVE |  |
| *system.serial\_number* | string | None |  |
| *system.sku* | string | None |  |
| *system.version* | string | 1.0 |  |
| *board.manufacturer* | string | FreeBSD |  |
| *board.product\_name* | string | BHYVE |  |
| *board.version* | string | 1.0 |  |
| *board.serial\_number* | string | None |  |
| *board.asset\_tag* | string | None |  |
| *board.location* | string | None |  |
| *chassis.manufacturer* | string | FreeBSD |  |
| *chassis.version* | string | 1.0 |  |
| *chassis.serial\_number* | string | None |  |
| *chassis.asset\_tag* | string | None |  |
| *chassis.sku* | string | None |  |
| *oemstring.N* | string | none |  |
| *rundir* | String | */var/run/bhyve/* |  |
| *monitor.enabled* | bool | false |  |
| *monitor.no\_reboot* | bool | false |  |
| *vcpu.N.cpuset* | string | none |  |

### x86-Specific Settings

| | | | |
| --- | --- | --- | --- |
| **Name** | **Format** | **Default** | **Description** |
| *x86.mptable* | bool | true |  |
| *x86.x2apic* | bool | false |  |
| *x86.strictio* | bool | false |  |
| *x86.strictmsr* | bool | true |  |
| *x86.verbosemsr* | bool | false |  |
| *x86.vmexit\_on\_hlt* | bool | false |  |
| *x86.vmexit\_on\_pause* | bool | false |  |
| *domains.N.size* | string |  |  |
| *domains.N.cpus* | string |  |  |
| *domains.N.domain\_policy* | string |  |  |

### arm64 and RISC-V Specific Settings

| | | | |
| --- | --- | --- | --- |
| **Name** | **Format** | **Default** | **Description** |
| *console* | string |  |  |

## DEVICE SETTINGS

Device settings are stored under a device node. The device node's name is set by the parent bus of the device.

### PCI Device Settings

PCI devices are described by a device node named “pci.*bus*.*slot*.*function*” where each of *bus*, *slot*, and *function* are formatted as decimal values with no padding. All PCI device nodes must contain a configuration variable named “device” which specifies the device model to use. The following PCI device models are supported:

- hostbridge

  Provide a simple PCI-Host bridge device. This is usually configured at pci0:0:0 and is required by most guest operating systems.

- ahci

  AHCI storage controller.

- e1000

  Intel e82545 network interface.

- fbuf

  VGA framebuffer device attached to VNC server.

- lpc

  LPC PCI-ISA bridge with COM1-COM4 16550 serial ports, a boot ROM, and, optionally, a TPM module, a fw\_cfg type, and a debug/test device. This device must be configured on bus 0.

- hda

  High Definition audio controller.

- nvme

  NVM Express (NVMe) controller.

- passthru

  PCI pass-through device.

- uart

  PCI 16550 serial device.

- virtio-9p

  VirtIO 9p (VirtFS) interface.

- virtio-blk

  VirtIO block storage interface.

- virtio-console

  VirtIO console interface.

- virtio-input

  VirtIO input interface.

- virtio-net

  VirtIO network interface.

- virtio-rnd

  VirtIO RNG interface.

- virtio-scsi

  VirtIO SCSI interface.

- xhci

  Extensible Host Controller Interface (XHCI) USB controller.

### USB Device Settings

USB controller devices contain zero or more child USB devices attached to slots. Each USB device stores its settings in a node named “slot.*N*” under the controller's device node. *N* is the number of the slot to which the USB device is attached. Note that USB slot numbers begin at 1. All USB device nodes must contain a configuration variable named “device” which specifies the device model to use. The following USB device models are supported:

- tablet

  A USB tablet device which provides precise cursor synchronization when using VNC.

### Block Device Settings

Block devices use the following settings to configure their backing store. These settings are stored in the configuration node of the respective device.

| | | | |
| --- | --- | --- | --- |
| **Name** | **Format** | **Default** | **Description** |
| path | string |  |  |
| nocache | bool | false |  |
| nodelete | bool | false |  |
| sync | bool | false |  |
| direct | bool | false |  |
| ro | bool | false |  |
| sectorsize | *logical*\[/*physical*\] |  |  |

### Network Backend Settings

Network devices use the following settings to configure their backend. The backend is responsible for passing packets between the device model and a desired destination. Configuring a backend requires setting the *backend* variable. The type of a backend can either be set explicitly via the *type* variable or it can be inferred from the value of *backend*.

The following types of backends are supported:

- tap

  Use the [tap(4)](/tap/4.md) interface named in *backend* as the backend.

- netgraph

  Use a [netgraph(4)](/netgraph/4.md) socket hook as the backend. This backend uses the following additional variables:

  | | | | |
  | --- | --- | --- | --- |
  | **Name** | **Format** | **Default** | **Description** |
  | *path* | string |  |  |
  | *peerhook* | string |  |  |
  | *socket* | string |  |  |
  | *hook* | string | vmlink |  |

- netmap

  Use [netmap(4)](/netmap/4.md) either on a network interface or a port on a [vale(4)](/vale/4.md) bridge as the backend. The value of *backend* is passed to **nm\_open** to connect to a netmap port.

- slirp

  Use the slirp backend to provide a userspace network stack. The *hostfwd* variable is used to configure how packets from the host are translated before being sent to the guest.

  | | | | |
  | --- | --- | --- | --- |
  | **Name** | **Format** | **Default** | **Description** |
  | *hostfwd* | string |  |  |

If *type* is not specified explicitly, then it is inferred from *backend* based on the following patterns:

| | |
| --- | --- |
| **Pattern** | **Type** |
| tap*N* | tap |
| vmnet*N* | tap |
| netgraph | netgraph |
| netmap:*interface* | netmap |
| vale*bridge*:*port* | netmap |

### UART Device Settings

| | | | |
| --- | --- | --- | --- |
| **Name** | **Format** | **Default** | **Description** |
| *path* | path |  |  |
| *tcp* |  |

### Host Bridge Settings

| | | | |
| --- | --- | --- | --- |
| **Name** | **Format** | **Default** | **Description** |
| *pcireg.\** | integer |  |  |

### AHCI Controller Settings

AHCI controller devices contain zero or more ports each of which provides a storage device. Each port stores its settings in a node named “port.*N*” under the controller's device node. The *N* values are formatted as successive decimal values starting with 0. In addition to the block device settings described above, each port supports the following settings:

| | | | |
| --- | --- | --- | --- |
| **Name** | **Format** | **Default** | **Description** |
| *type* | string |  |  |
| *nmrr* | integer | 0 |  |
| *ser* | string | generated |  |
| *rev* | string | 001 |  |
| *model* | string |  |  |

### e1000 Settings

In addition to the network backend settings, Intel e82545 network interfaces support the following variables:

| | | | |
| --- | --- | --- | --- |
| **Name** | **Format** | **Default** | **Description** |
| *mac* | MAC address | generated |  |

### Frame Buffer Settings

| | | | |
| --- | --- | --- | --- |
| **Name** | **Format** | **Default** | **Description** |
| *wait* | bool | false |  |
| *rfb* |  |
| *rfb* |  |
| *vga* | string | io |  |
| *w* | integer | 1024 |  |
| *h* | integer | 768 |  |
| *password* | string |  |  |

### High Definition Audio Settings

| | | | |
| --- | --- | --- | --- |
| **Name** | **Format** | **Default** | **Description** |
| *play* | path |  |  |
| *rec* | path |  |  |

### LPC Device Settings

The LPC bridge stores its configuration under a top-level *lpc* node rather than under the PCI LPC device's node. The following nodes are available under *lpc*:

| | | | |
| --- | --- | --- | --- |
| **Name** | **Format** | **Default** | **Description** |
| *com1* | node |  |  |
| *com2* | node |  |  |
| *com3* | node |  |  |
| *com4* | node |  |  |
| *fwcfg* | string | bhyve |  |
| *pc-testdev* | bool | false |  |
| *pcireg.\** | integer |  |  |

### TPM Device Settings

The TPM device stores its configuration under a top-level *tpm* node rather than under the LPC TPM device's node. Only one TPM device is supported. The following nodes are available under *tpm*:

| | | | |
| --- | --- | --- | --- |
| **Name** | **Format** | **Default** | **Description** |
| *tpm.path* | string |  |  |
| *tpm.type* | string |  |  |
| *tpm.version* | string | 2.0 |  |

### NVMe Controller Settings

Each NVMe controller supports a single storage device. The device can be backed either by a memory disk described by the *ram* variable, or a block device using the block device settings described above. In addition, each controller supports the following settings:

| | | | |
| --- | --- | --- | --- |
| **Name** | **Format** | **Default** | **Description** |
| *maxq* | integer | 16 |  |
| *qsz* | integer | 2058 |  |
| *ioslots* | integer | 8 |  |
| *sectsz* | integer |  |  |
| *ser* | string |  |  |
| *eui64* | integer |  |  |
| *dsm* | string | auto |  |
| *ram* | integer |  |  |

### PCI Passthrough Settings

The ppt(4) device driver must be attached to the PCI device being passed through. The device to pass through can be identified either by name or its host PCI bus location.

| | | | |
| --- | --- | --- | --- |
| **Name** | **Format** | **Default** | **Description** |
| *bus* | integer |  |  |
| *slot* | integer |  |  |
| *func* | integer |  |  |
| *pptdev* | string |  |  |
| *rom* | path |  |  |

### VirtIO 9p Settings

Each VirtIO 9p device exposes a single filesystem from a host path.

| | | | |
| --- | --- | --- | --- |
| **Name** | **Format** | **Default** | **Description** |
| *sharename* | string |  |  |
| *path* | path |  |  |
| *ro* | bool | false |  |

### VirtIO Block Device Settings

In addition to the block device settings described above, each VirtIO block device supports the following settings:

| | | | |
| --- | --- | --- | --- |
| **Name** | **Format** | **Default** | **Description** |
| *ser* | string | generated |  |

### VirtIO Console Device Settings

Each VirtIO Console device contains one or more console ports. Each port stores its settings in a node named “port.*N*” under the controller's device node. The *N* values are formatted as successive decimal values starting with 0. Each port supports the following settings:

| | | | |
| --- | --- | --- | --- |
| **Name** | **Format** | **Default** | **Description** |
| *name* | string |  |  |
| *path* | path |  |  |

### VirtIO Input Interface Settings

Each VirtIO Input device contains one input event device. All input events of the input event device are send to the guest by VirtIO Input interface. VirtIO Input Interfaces support the following variables:

| | | | |
| --- | --- | --- | --- |
| **Name** | **Format** | **Default** | **Description** |
| *path* | path |  |  |

### VirtIO Network Interface Settings

In addition to the network backend settings, VirtIO network interfaces support the following variables:

| | | | |
| --- | --- | --- | --- |
| **Name** | **Format** | **Default** | **Description** |
| *mac* | MAC address | generated |  |
| *mtu* | integer | 1500 |  |

### VirtIO SCSI Settings

| | | | |
| --- | --- | --- | --- |
| **Name** | **Format** | **Default** | **Description** |
| *backend* | string | ctl |  |
| *ctl\_ringsz* | integer | 64 |  |
| *evt\_ringsz* | integer | 64 |  |
| *req\_ringsz* | integer | 64 |  |
| *num\_queues* | integer | 1 |  |
| *seg\_max* | integer | 64 |  |
| *thr\_per\_q* | integer | 16 |  |
| *target* | \[*ID*:\]path | /dev/cam/ctl |  |

The *target* variable may be specified multiple times with different *path* arguments to configure multiple distinct SCSI targets. If not explicitly configured, the target *ID*s will be assigned sequentially beginning with the highest target *ID* configured so far, or 0 for the first target configured. The target *ID*s must be unique within each virtio-scsi instance.

The meaning of the *path* argument is specific to each backend:

| | | |
| --- | --- | --- |
| **Backend** | **Path** | **Description** |
| ctl | */dev/cam/ctl*\[*pp*.*vp*\] |  |

The following backend-specific variables are supported for VirtIO SCSI:

| | | | | |
| --- | --- | --- | --- | --- |
| **Backend** | **Name** | **Format** | **Default** | **Description** |
| ctl | *iid* | integer | 0 |  |

## SEE ALSO

[expand\_number(3)](/expand_number/3.md), [getaddrinfo(3)](/getaddrinfo/3.md), [strtol(3)](/strtol/3.md), [netgraph(4)](/netgraph/4.md), [netmap(4)](/netmap/4.md), [ng\_socket(4)](/ng_socket/4.md), [tap(4)](/tap/4.md), [vale(4)](/vale/4.md), [vmnet(4)](/vmnet/4.md), [bhyve(8)](/bhyve/8.md)