rust-bhyve

A userspace virtual machine monitor (VMM) for illumos bhyve, written in Rust. It runs on SmartOS and other illumos distributions, on x86_64.

Experimental. This is not production-supported software, and no release is published. Live migration is not authenticated and does not carry FPU/XSAVE state. Read SECURITY.md before you run an untrusted guest on it.

The binaries

• rshyve takes the command line that the SmartOS bhyve zone brand builds, so a zone can run it in place of /usr/sbin/bhyve. It boots UEFI firmware or a Linux kernel directly, and supplies virtio, NVMe, an AHCI CD-ROM, a VNC framebuffer, a vTPM, PCI passthrough, a control socket and live migration. It is not all of bhyve: some flags and device options are refused, and some are accepted and ignored.
• firehyve is a microVM over the same crates. It boots a Linux kernel directly and supplies virtio devices and a serial console only: no firmware, no migration, no control socket. It refuses at startup most options that it cannot honor. The options that the bhyve zone brand puts on every zone (a boot ROM, extra serial backends, a frame buffer and an xHCI tablet) are accepted, logged and ignored.
• fhrun runs a Linux binary inside a firehyve microVM, like a child process.

docs/features.md lists what each binary supports, with its limits.

Quick start

rshyve -c 2 -m 2G \
  -s 4,virtio-blk,/dev/zvol/rdsk/zones/disk0 \
  -s 6,virtio-net-viona,net0 \
  -l bootrom,/usr/share/bhyve/uefi-rom.bin \
  -l com1,stdio \
  myvm

Build

The binaries run only on illumos. Build them on an illumos host:

git clone --recurse-submodules https://github.com/TritonDataCenter/rshyve
cd rust-bhyve
cargo build --workspace --locked --release
cargo test --workspace --locked --no-fail-fast

The unit tests also run on Linux and macOS. docs/testing.md gives the prerequisites, how to boot a test guest, and the test harness scripts.

To use rshyve for the zones on a SmartOS node, install it on the node and point the zone at it. docs/platform.md tells how. No prebuilt platform image is published.

Status

Tested on SmartOS with bhyve API v18. docs/features.md lists the configurations that were tested and the known caveats. docs/roadmap.md lists the open work.

Documentation

• Architecture: workspace layout, key types, data flow
• Feature reference: what each binary supports, with limits
• CLI reference: flags and control commands
• Devices: PCI, LPC and kernel-emulated devices
• Live migration: protocol, state and the orchestrator contract
• Metadata agent: guest configuration over COM2
• Platform integration: running rshyve for SmartOS zones
• UEFI firmware: the FreeBSD edk2 firmware and variable stores
• fhrun: the manifest and the exit codes
• Testing: build, unit tests, test guests, harnesses
• Roadmap: open work
• firehyve boot measurements: a draft measurement report
• Open security findings

Built on Propolis

This project uses code from Propolis, the bhyve VMM of Oxide Computer Company. The bhyve and viona ioctl bindings, the address-space manager and the PS/2 device models come from Propolis with few changes. Parts of the PCI, UART and VM-exit layers are derived from it. Both projects use MPL-2.0.

Each derived file has a header that names its upstream file. THIRD_PARTY.md lists the files with their measured similarity, and tools/propolis-derivation.py measures them again against a Propolis checkout.

Contributing

CONTRIBUTING.md covers the build, what CI proves and what it does not, the repository gates, and the commit style. CHANGELOG.md records the changes that an operator would notice.

Security

Report vulnerabilities privately. See SECURITY.md.

License

MPL-2.0. The full text is in LICENSE.

Parts of this code are copied or derived from Propolis, Copyright Oxide Computer Company, under MPL-2.0. libtpms is vendored under the 3-clause BSD license. NOTICE has the attribution, and THIRD_PARTY.md has the exact provenance.