Fast Assessment Laboratory for Computers On Networks

Falcon is a Rust API for creating network topologies composed of Propolis VMs interconnected by simnet links. It's designed to be used for both automated testing and as a development environment for networked systems.

• Falcon runs on Helios >= 1.0.20707
• Falcon uses propolis which requires hardware virtualization support. Running Falcon on bare metal is recommended. While nested virt can be made to work, it often requires wizardry and is known to have flaky behaviors.

To get a ready-to-go Falcon project use the falcon-template.

cargo generate --git https://github.com/oxidecomputer/falcon-template --name duo

This will create a cargo project with the following topology.

use libfalcon::{cli::run, error::Error, Runner, unit::gb};
#[tokio::main]
async fn main() -> Result<(), Error> {
    let mut d = Runner::new("duo");
    // nodes
    let violin = d.node("violin", "helios-2.5", 4, gb(4));
    let piano = d.node("piano", "helios-2.5", 4, gb(4));
    // links
    d.link(violin, piano);
    run(&mut d).await?;
    Ok(())
}

The following will launch the VMs in your topology and do some basic setup. When the call returns, your topology is ready to use.

cargo build
pfexec ./target/debug/duo launch

Once the topology is up, you can access the nodes via serial connection. Tap the enter key a few times after running the serial command below. To exit the console use ctl-q.

./target/debug/duo serial violin

pfexec ./target/debug/duo destroy

• The primary reference documentation is in the wiki.
• Working examples.

This assumes that that the instructions in the install section have been run.

cargo build
cargo test -- --test-threads 1
cargo test -- --test-threads 1 --ignored

Note that cargo test will automatically use pfexec to run tests; this is configured in .cargo/config.toml.

By default, topology and configuration for a falcon deployment is placed into a hardcoded $PWD/.falcon directory. However, users can override this by setting the Runner::falcon_dir variable inside their code, and/or by passing a --falcon-dir <DIR> parameter to most CLI commands. This allows tests and code to be run independently as long as the names of the runners and nodes are unique.