strogo / propolis

Rust-based userspace for illumos bhyve

Propolis

Propolis is a rust-based userspace for illumos bhyve.

Building

Given the current tight coupling of the bhyve-api component to the ioctl interface presented by the bhyve kernel component, running on recent illumos bits is required.

At a minimum, the build must include the fix for 14024. (Present since commit 52fac30)

The main propolis crate is structured as a library providing the building blocks to create bhyve backed VM instances. It also provides a number of emulated devices that can be exposed to guests (e.g. serial port, virtio devices, NVMe).

propolis-server

Propolis is mostly intended to be used via a REST API to drive all of its functionality. The standard cargo build will produce a propolis-server binary you can run:

Running

# propolis-server run <config_file> <ip:port>

Example Server Configuration

Note: the goal is to move the device config from the toml to instead be configured via REST API calls.

bootrom = "/path/to/bootrom/OVMF_CODE.fd"

[block_dev.alpine_iso]
type = "file"
path = "/path/to/alpine-extended-3.12.0-x86_64.iso"

[dev.block0]
driver = "pci-virtio-block"
block_dev = "alpine_iso"
pci-path = "0.4.0"

[dev.net0]
driver = "pci-virtio-viona"
vnic = "vnic_name"
pci-path = "0.5.0"

propolis-cli

Once you've got propolis-server running you can interact with it via the REST API with any of the usual suspects (e.g. cURL, wget). Alternatively, there's a propolis-cli binary to make things a bit easier:

Running

# propolis-cli -s <propolis ip> -p <propolis port> new <VM name>
# propolis-cli -s <propolis ip> -p <propolis port> state <VM name> run
# propolis-cli -s <propolis ip> -p <propolis port> serial <VM name>

propolis-standalone

Server frontend aside, we also provide a standalone binary for quick prototyping, propolis-standalone. It uses a static toml configuration:

Running

# propolis-standalone <config_file>

Example configuration:

[main]
name = "testvm"
cpus = 4
bootrom = "/path/to/bootrom/OVMF_CODE.fd"
memory = 1024

[block_dev.alpine_iso]
type = "file"
path = "/path/to/alpine-extended-3.12.0-x86_64.iso"

[dev.block0]
driver = "pci-virtio-block"
block_dev = "alpine_iso"
pci-path = "0.4.0"

[dev.net0]
driver = "pci-virtio-viona"
vnic = "vnic_name"
pci-path = "0.5.0"

Propolis will not destroy the VM instance on exit. If one exists with the specified name on start-up, it will be destroyed and and created fresh.

Propolis will create a unix domain socket, available at "./ttya", which acts as a serial port. One such tool for accessing this serial port is sercons, though others (such as "screen") would also work.

Quickstart to Alpine

In the aforementioned config files, there are three major components that need to be supplied: The OVMF file, the ISO, and the VNIC.

Since this is a configuration file, you can supply whatever you'd like, but here are some options to get up-and-running quickly:

OVMF

Using a bootrom from Linux works here - you can either build your own OVMF, or you can use a pre-built.

$ sudo apt-get install ovmf && dpkg -L ovmf | grep OVMF_CODE.fd

ISO

Although there are many options for ISOs, an easy option that should work is the Alpine Linux distribution.

These distributions are lightweight, and they have varients custom-built for virtual machines.

The "extendend" variant contains more useful tools, but will require a modification of the kernel arguments when booting to see the console on the serial port. From Grub, this can be accomplished by pressing "e" (to edit), adding "console=ttyS0" to the line starting with "/boot/vmlinuz-lts", and pressing "Control + x" to boot with these parameters.

VNIC

To see your current network interfaces, you can use the following:

$ dladm show-link

To create a vnic, you can use one of your physical devices (like "e1000g0", if you have an ethernet connection) as a link for a VNIC. This can be done as follows:

NIC_NAME="vnic_prop0"
NIC_MAC="02:08:20:ac:e9:16"
NIC_LINK="e1000g0"

if ! dladm show-vnic $NIC_NAME 2> /dev/null; then
  dladm create-vnic -t -l $NIC_LINK -m $NIC_MAC $NIC_NAME
fi

License

Unless otherwise noted, all components are licensed under the Mozilla Public License Version 2.0.