Crate capsule

Source
Expand description

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"

§Using features

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"] }

Or, to enable the capturing of port traffic to pcap files automatically per-port, per-core, you can run a Capsule application with the pcap-dump feature flag turned on:

cargo run --features capsule/pcap-dump -- -f capsule-app.toml

§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.
  • metricsdefault and 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.
  • testilstestils
    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.
  • fieldmaptestils
    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.

Enums§

Traits§

  • SizeOf
    A trait for returning the size of a type in bytes.

Attribute Macros§

  • benchtestils
    Procedural macro for running DPDK based benches.
  • testtestils
    Procedural macro for running DPDK based tests.

Derive Macros§