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