smoltcp

Since smoltcp is a freestanding stack, testing in userspace on Linux requires a persistent tap interface. This allows a specific user to manipulate raw frames without requiring constant superuser privileges. Use the following commands to create and configure tap0 with IPv4 and IPv6 support:

sudo ip tuntap add name tap0 mode tap user $USER
sudo ip link set tap0 up
sudo ip addr add 192.168.69.100/24 dev tap0
sudo ip -6 addr add fe80::100/64 dev tap0
sudo ip -6 addr add fdaa::100/64 dev tap0
sudo ip -6 route add fe80::/64 dev tap0
sudo ip -6 route add fdaa::/64 dev tap0

To use smoltcp in your Rust project, add it to your Cargo.toml dependencies.

By default, smoltcp assumes a hosted environment. For bare-metal or resource-constrained systems, it is recommended to disable default features and enable only the specific ones you need.

# Standard installation
[dependencies]
smoltcp = "0.10.0"

# Recommended for bare-metal: disable default features and pick specific ones
[dependencies]
smoltcp = { version = "0.10.0", default-features = false, features = ["log"] }

Certain configuration settings affecting buffer sizes and counts are set at compile time. You can configure these using two methods:

1. Cargo Features: Enable a feature following the pattern <name>-<value>. Note that names must be lowercase and use dashes instead of underscores (e.g., iface-max-addr-count-3).
2. Environment Variables: Set a variable named SMOLTCP_<VALUE> during build (e.g., SMOLTCP_IFACE_MAX_ADDR_COUNT=3 cargo build). You can also set these in the [env] section of .cargo/config.toml.

Precedence: Environment variables take precedence over Cargo features. If two different Cargo features attempt to set the same configuration to different values, compilation will fail.

smoltcp requires specific feature flags to be enabled to function. Depending on your requirements, you must satisfy the following constraints:

IP Layer Requirements

You must enable at least one of these IP protocol features:

• proto-ipv4
• proto-ipv6
• proto-sixlowpan

Socket Layer Requirements

If you enable the socket feature, you must also enable at least one specific socket type:

• socket-raw
• socket-udp
• socket-tcp
• socket-icmp
• socket-dhcpv4
• socket-dns

Medium/Interface Requirements

If you enable the socket feature, you must also enable a compatible medium:

• medium-ip
• medium-ethernet
• medium-ieee802154

Logging Constraints

You can use either defmt or log for logging, but not both. Enabling both will cause a compilation error.

The server example emulates a network host that responds to various requests (Ping, UDP, TCP) on specific ports. It is useful for testing resource exhaustion due to its small buffer sizes (64 bytes for most ports).

Usage: cargo run --example server -- --tap <INTERFACE>

Example:

cargo run --example server -- --tap tap0

Supported Services:

• ICMP: Responds to pings.
• UDP Port 6969: Responds with reversed chunks of input.
• TCP Port 6969: Responds "hello" and closes.
• TCP Port 6970: Responds with reversed chunks of input.
• TCP Port 6971: Sinks data; has keep-alive and user timeouts enabled.
• TCP Port 6972: Sources data.

The client example emulates a host that initiates basic requests and responds with reversed chunks of input.

Usage: cargo run --example client -- --tap <INTERFACE> <ADDRESS> <PORT>

Example:

cargo run --example client -- --tap tap0 192.168.69.1 1234

The benchmark example implements a simple throughput benchmark by establishing a connection to itself and reading or writing large amounts of data.

Usage: cargo run --release --example benchmark -- --tap <INTERFACE> [reader|writer]

Example (Reader):

cargo run -q --release --example benchmark -- --tap tap0 reader

Example (Writer):

cargo run -q --release --example benchmark -- --tap tap0 writer

The ping example implements a minimal version of the ping utility using raw sockets. It sends 4 ICMP ECHO_REQUEST packets at one-second intervals.

Usage: cargo run --example ping -- --tap <INTERFACE> <ADDRESS>

Example:

cargo run --example ping -- --tap tap0 192.168.69.100

The tcpdump example is a clone of the tcpdump utility. Unlike other examples, it uses raw sockets and can be used on regular interfaces (e.g., eth0) or the tap0 interface.

cargo build --example tcpdump
sudo ./target/debug/examples/tcpdump eth0