Crate fctools 

fctools is a highly modular and exhaustive SDK for developing high-performance asynchronous production applications that leverage the capabilities of Firecracker microVMs.

Binary crates using fctools will need to enable a syscall backend. Libraries should not enable any syscall backend feature, and must instead expect binary crates to do so. The fctools crate without such a backend will compile but panic at runtime with the message “No syscall backend was enabled for fctools”. Binary crate developers must choose either the “nix-syscall-backend” or the “rustix-syscall-backend” feature. If the latter is enabled, the former is ignored, as only one syscall backend can exist at a time. The two features use their two respective crates: “nix” or “rustix”. As such, they are functionally equivalent, with the only difference being that “nix” uses C FFI to call into libc and perform syscalls, while “rustix” invokes syscalls directly without any FFI.

By default, only the runtime module that provides traits for supporting any asynchronous runtime is enabled. Binary crates using fctools should usually pull in either a built-in implementation of a Runtime via either the tokio-runtime or smol-runtime features, or install a third-party crate with its own implementation.

The rest of the crate that provides actual functionality is structured in a vertical fashion, with each layer introducing more useful and high-level features than the one preceding it. There are 6 such layers, from lowest to highest level of abstraction:

1. The process spawner layer, enabled via the process-spawner feature. It provides functionality for invoking the microVM process.
2. The VMM core layer, enabled via the vmm-core feature. It provides basic facilities for managing a VMM.
3. The VMM executor layer, enabled via the vmm-executor feature. It provides an executor trait that handles a VMM’s lifecycle, as well as introducing handling of VMM ownership models.
4. The VMM process layer, enabled via the vmm-process feature. It provides a VMM process abstraction over an underlying executor, introducing various useful features like making requests to the VMM’s HTTP API server.
5. The VM layer, enabled via the vm feature. It provides a wide range of high-level and opinionated facilities that build on top of a VMM process. These address concerns such as: high-level API server bindings, making snapshots, initializing VMs, shutting them down in a graceful and controlled fashion with timeouts and so on.
6. The extension layer, enabled via various features ending with -extension. These small extensions, each typically spanning under 500 lines of code, provide various real-world utilities useful for a microVM-based application.

Each higher layer is more opinionated and high-level than its predecessor, while offering more useful features. Depending on the needs of your application or library, you should decide which layers make sense for your use-case. Enabling the VM layer and all necessary extensions is usually a good start.

Modules

extension

A set of extensions to the rest of fctools’ functionality. These currently include:

process_spawnerprocess-spawner

runtime

Provides a set of traits that need to be implemented to have compatibility between fctools and an async runtime. Two built-in implementations are provided behind feature gates that are both disabled by default:

vmvm

Provides managed and high-level VM APIs that are most suitable for production applications that only need to concern themselves with the high-level details of a Firecracker VM. These abstractions is built on the vmm-core, vmm-executor and vmm-process features.

vmmvmm-core

Provides a wide variety of VMM-related APIs that concern themselves with the lower level of a “firecracker”/“jailer” process instead of the underlying VM itself.