Reference

Overview

Falcon is a Rust API for creating network topologies composed of VMs on illumos. Virtual machines are created using Propolis. Networks between virtual machines are created using a combination of simnet and veth virtual network devices.

Falcon keeps all of the state needed to manage a topology in a local folder called .falcon that is created when a topology is launched and deleted when a topology is destroyed. There is no global state that Falcon explicitly tracks. There is however implicit global state, such a network interfaces created by Falcon and Propolis processes. Because of this, falcon topologies running on the same host must have distinct names to avoid network interface name collisions.

This Wiki is a reference for the feature set Falcon exposes for managing and interacting with network system topologies. For a quick start introduction see the quick stat section of the README.

When a topology is built, a CLI program is produced for managing that topology. The name of the program executable depends on your cargo configuration. In this wiki, we'll refer to the generated topology management executable as $topo.

VM serial console access

To attach to the serial console of a node called violin

$topo serial violin

This will attach your current console's stdin/stdout to the serial console of the violin VM. Initially, there will be no output, tap the enter key a few times to reveal the VM's terminal prompt.

To leave a serial session use ctl-q.

P9 file system mounts

Falcon supports mounting files from the host into guest VMs. Currently, mounts are read-only; writes from the guest back to the host are not supported.

let violin = d.node("violin", "helios", 2, gb(2));
d.mount("./cargo-bay", "/opt/cargo-bay", violin)?;

This example will create a P9 filesystem device on the violin VM that provides access to the host's local folder cargo-bay with the p9fs tag /opt/cargo-bay in the guest.

Helios guests

Helios does not yet have p9fs filesystem support. However, a helios guest can access these files as follows.

mkdir /opt/cargo-bay
cd /opt/cargo-bay
p9kp pull

Which will run a user-space program that pulls the mounted files to the /opt/cargo-bay location. This is not an active guest mount, so if the files in the host change, another p9kp pull must be run.

Linux guests

To mount the filesystem in Linux

mount -t 9p -o ro /opt/cargo-bay /opt/cargo-bay

Starting and stopping VMs

Starting and stopping virtual machines amounts to starting and stopping the associated hypervisor instance. Falcon provides two commands hyperstart and hyperstop that will start and stop VMs. These commands can also be used to recover from unexpected events such as a power loss on your workstation. Hyperstop is also a good way to stop a topology if you don't want it taking up CPU and memory resources, but want to pick back up with it later right where you left off.

Both commands take a VM name by default, but also come with an --all switch to act over an entire topology.

Virtual machine image management

Falcon comes with two base images

• Helios-1.0
• Debian-11.0

These are pre-built images that are installed by the setup-base-images.sh script. If you need an entirely new base image that is not derived from either of these you can make your own base image. If you want to save the state of a VM in one of your active topologies as a new base image, you can snapshot that image.

Make your own base images

Helios

The helios base image that comes with Falcon is created using the helios-engvm image creation machinery. The source for that image is the JSON specifications with "masaka" in the title located here. There are three important things to note about this image. If you don't need Plan 9 filesystem support for mounting files from the host into guests, you don't need to worry about the first two.

• The vio9p kernel module package install which comes from this illumos branch which adds a bit of packaging around JMC's virtfs kernel module work. The way I get this to build with helios-engvm is by adding a local onu repo and running a local package depo from the helios build machinery as described in the README here.

• The p9kp program. This comes from a build of the p9fs repository. It is the program that allows a user to copy mounted files from the host from within the guest.

• UEFI must be set to true for your machine to be bootable in propolis.

Linux

The base Debian-11 machine that comes with Falcon is an unmodified copy of a Debian "nocloud" cloud image. This is a small UEFI bootable Debian cloud image with a password-less root login by default.

VM snapshotting

The Falcon CLI comes with a snapshot command that can be used to create a new base image from an existing node. The following will snapshot the VM image associated with the node violin to a new base image called helios-dev.

$topo snapshot violin helios-dev

It is recommended to hyperstop a node before imaging it. Snapshotting an underlying ZFS volume from a running node may produce unexpected results.