[−][src]Crate capsule

A framework for network function development. Written in Rust, inspired by NetBricks and built on Intel's Data Plane Development Kit.

The goal of Capsule is to offer an ergonomic framework for network function development that traditionally has high barriers of entry for developers. We've created a tool to efficiently manipulate network packets while being type-safe, memory-safe, and thread-safe. Building on DPDK and Rust, Capsule offers:

a fast packet processor that uses minimum number of CPU cycles.
a rich packet type system that guarantees memory-safety and thread-safety.
a declarative programming model that emphasizes simplicity.
an extensible and testable framework that is easy to develop and maintain.

Getting started

The easiest way to start developing Capsule applications is to use the Vagrant virtual machine and the Docker sandbox provided by the Capsule team. The sandbox is preconfigured with all the necessary tools and libraries for Capsule development, including:

For more information on getting started, please check out Capsule's README, as well as our sandbox repo for developer environments.

Adding Capsule as a Cargo dependency

[dependencies]
capsule = "0.1"

To enable test/bench features for example, you can include Capsule in your Cargo dependencies with the testils feature flag:

[dev-dependencies]
capsule = { version = "0.1", features = ["testils"] }

Feature flags

default: Enables metrics by default.
metrics: Enables automatic metrics collection.
pcap-dump: Enables capturing port traffic to (.pcap) files.
testils: Enables utilities for unit testing and benchmarking.
full: Enables all features.

Examples

kni: Kernel NIC interface example.
nat64: IPv6 to IPv4 NAT gateway example.
ping4d: Ping4 daemon example.
pktdump: Packet dump example.
signals: Linux signal handling example.
skeleton: Base skeleton example.
syn-flood: TCP SYN flood example.

Modules

batch	Combinators that can be applied to batches of packets within a pipeline.
config	Toml-based configuration for use with Capsule applications.
metrics	`feature="default"` and `feature="metrics"` Exposes framework metrics, including port, kni, mempool, and pipeline metrics.
net	Common network utilities.
packets	Packet types for reading and writing various network protocols.
testils	`feature="testils"` Utilities for unit tests and benchmarks.

Macros

compose	Composes the batch builders for the `group_by` combinator.
ensure	Exits a function early with an `Error` if the condition is not satisfied.
fieldmap	Defines a mapping of fields to their default values.

Structs

KniRx	The KNI receive handle. Because the underlying interface is single threaded, we must ensure that only one rx handle is created for each interface.
KniTxQueue	In memory queue for the cores to deliver packets that are destined for the kernel. Then another pipeline will collect these and forward them on in a thread safe way.
Mbuf	A DPDK message buffer that carries the network packet.
PortQueue	The receive and transmit queue abstraction. Instead of modeling them as two standalone queues, in the run-to-completion mode, they are modeled as a queue pair associated with the core that runs the pipeline from receive to send.
Runtime	The Capsule runtime.

bench	`feature="testils"` Procedural macro for running DPDK based benches.
test	`feature="testils"` Procedural macro for running DPDK based tests.

Derive Macros

SizeOf

Derive macro for SizeOf.