Crate riptun

riptun is a library for creating, managing, and leveraging TUN/TAP devices.

The implementation exposes both a synchronous interface via the Tun and Queue structs, as well as an asynchronous interface via a set of feature flagged structs. See the Features and Examples sections for more information on the async implementations and how to use them.

Getting started

The simplest way to get started with riptun is to manage a single queue synchronous TUN device:

Lets start by disabling the async support as we won’t be using it:

riptun = { version = "0.1", default-features = false, features = [] }

The following example program will create a new TUN device named rip%d, where the %d will be replaced with an appropriate value by the OS. The exact device name along with the actual TUN device is then returned for use. We then loop forever reading packets and printing them to stdout:

use riptun::Tun;

// First lets create a new single queue tun.
let tun = match Tun::new("rip%d", 1) {
    Ok(tun) => tun,
    Err(err) => {
        println!("[ERROR] => {}", err);
        return;
    }
};

// Lets make sure we print the real name of our new TUN device.
println!("[INFO] => Created TUN '{}'!", tun.name());

// Create a buffer to read packets into, and setup the queue to receive from.
let mut buffer: [u8; 1500] = [0x00; 1500];
let queue = 0;

// Loop forever reading packets off the queue.
loop {
    // Receive the next packet from the specified queue.
    let read = match tun.recv_via(queue, &mut buffer) {
        Ok(read) => read,
        Err(err) => {
            println!("[ERROR] => {}", err);
            return;
        }
    };

    // Print out the amount of data received and the bytes read off the queue.
    println!(
        "[INFO] => Received packet data ({}B): {:?}",
        read,
        &buffer[..read]
    );
}

Once the rip%d device is created, you will need to add an IP address to it. On Linux this can be done like:

sudo ip addr add 203.0.113.2/24 brd 203.0.113.255 dev rip0
sudo ip link set dev rip0 up

Examples

There is a suite of included examples demonstrating the functionality of riptun. Note that the following examples will require elevated privileges to configure and create the actual Tun interface itself. This generally means root or Administrator privileges across unix and windows platforms.

As in the Getting Started section above, all the examples will require assigning an IP address to the created interface, you can do so by running:

sudo ip addr add 203.0.113.2/24 brd 203.0.113.255 dev rip0
sudo ip link set dev rip0 up

Sync

The synchronous mode of operation is detailed in the sync example. The implementation leverages a multi-queue Tun device. Then creates a new thread for each queue, and loops forever reading packets from each one.

You can run this example using the following and get similar output if you have the right permissions:

cargo run --no-default-features --example sync
[INFO] => Created new virtual device: rip0

Mio

The mio integration allows for registering and deregistering Queue instances with a Poll Registry. The mio example shows how to leverage this integration for a multi-threaded async version of the Sync example above.

You can run this example using the following and get similar output if you have the right permissions:

cargo run --no-default-features --features mio-impl --example mio
[INFO] => Created new virtual device: rip0

Smol and async-std

riptun exposes an async-io integration via the AsyncStdTun and AsyncStdQueue structs. These can be used interchangeably across both smol and async-std.

The std example describes how to leverage a multi-queue device using a single thread of operation. While using the async-std runtime.

You can run the std example using the following and get similar output if you have the right permissions:

cargo run --no-default-features --features async-std-example --example std
[INFO] => Created new virtual device: rip0

The smol example describes how to leverage a multi-queue device using a single thread, but with multiple concurrent tasks. While using the smol runtime.

You can run the smol example using the following and get similar output if you have the right permissions:

cargo run --no-default-features --features smol-example --example smol
[INFO] => Created new virtual device: rip0

Tokio

The riptun tokio integration is exposed via the TokioTun and TokioQueue structs. The tokio example demonstrates how to leverage both multi-threaded and concurrent operation simultaneously.

You can run this example using the following and get similar output if you have the right permissions:

cargo run --no-default-features --features tokio-example --example tokio
[INFO] => Created new virtual device: rip0

Features

The async support is enabled by default, and riptun can be used out of the box across mio, tokio, async-std, and smol. However to reduce library size, you can enable and disable each of the integrations using feature flags:

• The async-std-impl feature exposes the AsyncStdQueue/AsyncStdTun structs.
• The tokio-impl feature exposes the TokioQueue/TokioTun structs.
• The mio-impl enables registration of Queue structs in a mio poll registry.

Platform support

The riptun library is designed to be as platform agnostic as possible. Unfortunately each platform requires special handling, so each platform must be implemented manually. The current and planned platform support is detailed bellow.

Platform/Architecture support matrix:

Target	Sync Supported	Async Supported
x86_64-unknown-linux-gnu	✅	✅
aarch64-unknown-linux-gnu	✅	✅
armv7-unknown-linux-gnueabihf	✅	✅
armv7-unknown-linux-gnueabi	✅	✅
arm-unknown-linux-gnueabihf	✅	✅
arm-unknown-linux-gnueabi	✅	✅
x86_64-pc-windows-msvc	❌	❌
aarch64-pc-windows-msvc	❌	❌
x86_64-apple-darwin	❌	❌
aarch64-apple-darwin	❌	❌
x86_64-unknown-freebsd	❌	❌
aarch64-unknown-freebsd	❌	❌
x86_64-unknown-netbsd	❌	❌
aarch64-unknown-netbsd	❌	❌
x86_64-unknown-openbsd	❌	❌
aarch64-unknown-openbsd	❌	❌

Structs

AsyncStdQueue

An async wrapper around the Queue object leveraging the Async struct internally for async functionality.

AsyncStdTun

An asynchronous virtual TUN device based on the async-std/smol ecosystems.

Queue

A raw TUN/TAP queue wrapping all I/O for both sync and async operations.

TokioQueue

An async wrapper around the Queue object leveraging the AsyncFd struct internally for async functionality within the tokio ecosystem.

TokioTun

An asynchronous virtual TUN device based on the tokio ecosystem.

Tun

A named virtual device comprised of one or more virutal queues.

Enums

Error

Represents store errors based on user configuration or general operations.

Type Aliases

Result

Custom Result wrapper to simplify usage.