Crate tun_rs 

tun-rs: Cross-platform TUN/TAP Library

A high-performance, cross-platform Rust library for creating and managing TUN (Layer 3) and TAP (Layer 2) network interfaces. This library provides both synchronous and asynchronous APIs with support for advanced features like offload (TSO/GSO) on Linux and multi-queue support.

Features

• Multi-platform Support: Windows, Linux, macOS, FreeBSD, OpenBSD, NetBSD, Android, iOS, tvOS, and OpenHarmony
• TUN and TAP Modes: Support for both Layer 3 (TUN) and Layer 2 (TAP) interfaces
• Multiple IP Addresses: Configure multiple IPv4 and IPv6 addresses on a single interface
• Async Runtime Integration: Optional integration with Tokio or async-io/async-std
• Advanced Linux Features:
  • Offload support (TSO/GSO) for improved performance
  • Multi-queue support for parallel packet processing
  • Generic Receive Offload (GRO) for packet coalescing
• Platform Consistency: Uniform packet format across platforms (optional packet information header)
• Mobile Support: Direct file descriptor support for iOS (PacketTunnelProvider) and Android (VpnService)

Device Types

The library provides three main device types:

1. SyncDevice: Synchronous I/O operations, suitable for single-threaded or blocking code
2. AsyncDevice: Asynchronous I/O operations, requires the async feature flag
3. BorrowedDevice: Borrowed file descriptor variants that don’t take ownership

Quick Start

Basic Synchronous Example

Create a TUN interface with IPv4 and IPv6 addresses:

use tun_rs::DeviceBuilder;

let dev = DeviceBuilder::new()
    .name("utun7")
    .ipv4("10.0.0.12", 24, None)
    .ipv6("CDCD:910A:2222:5498:8475:1111:3900:2021", 64)
    .mtu(1400)
    .build_sync()
    .unwrap();

let mut buf = [0; 65535];
loop {
    let len = dev.recv(&mut buf).unwrap();
    println!("Received packet: {:?}", &buf[..len]);
}

Asynchronous Example (with Tokio)

Add to your Cargo.toml:

[dependencies]
tun-rs = { version = "2", features = ["async"] }

Then use async I/O:

use tun_rs::DeviceBuilder;

let dev = DeviceBuilder::new()
    .ipv4("10.0.0.1", 24, None)
    .build_async()?;

let mut buf = vec![0; 65536];
loop {
    let len = dev.recv(&mut buf).await?;
    println!("Received: {:?}", &buf[..len]);
}

Mobile Platforms (iOS/Android)

For iOS and Android, use the file descriptor from the system VPN APIs:

#[cfg(unix)]
{
    use tun_rs::SyncDevice;
    // On iOS: from PacketTunnelProvider.packetFlow
    // On Android: from VpnService.Builder.establish()
    let fd = 7799; // Example value only - obtain from platform VPN APIs
    let dev = unsafe { SyncDevice::from_fd(fd).unwrap() };

    let mut buf = [0; 65535];
    loop {
        let len = dev.recv(&mut buf).unwrap();
        println!("Received packet: {:?}", &buf[..len]);
    }
}

Advanced Features

Multiple IP Addresses

You can add multiple IPv4 and IPv6 addresses to an interface:

let dev = DeviceBuilder::new()
    .ipv4("10.0.0.1", 24, None)
    .build_async()?;

dev.add_address_v4("10.1.0.1", 24)?;
dev.add_address_v4("10.2.0.1", 24)?;
dev.add_address_v6("CDCD:910A:2222:5498:8475:1111:3900:2021", 64)?;

Linux Offload (TSO/GSO)

On Linux, enable offload for improved throughput:

#[cfg(target_os = "linux")]
{
    use tun_rs::{DeviceBuilder, GROTable, IDEAL_BATCH_SIZE, VIRTIO_NET_HDR_LEN};

    let dev = DeviceBuilder::new()
        .offload(true)  // Enable TSO/GSO
        .ipv4("10.0.0.1", 24, None)
        .build_sync()?;

    let mut original_buffer = vec![0; VIRTIO_NET_HDR_LEN + 65535];
    let mut bufs = vec![vec![0u8; 1500]; IDEAL_BATCH_SIZE];
    let mut sizes = vec![0; IDEAL_BATCH_SIZE];

    loop {
        let num = dev.recv_multiple(&mut original_buffer, &mut bufs, &mut sizes, 0)?;
        for i in 0..num {
            println!("Packet {}: {:?}", i, &bufs[i][..sizes[i]]);
        }
    }
}

Platform-Specific Notes

Windows

• TUN mode requires the Wintun driver
• TAP mode requires tap-windows
• Administrator privileges required

Linux

• Requires the tun kernel module (modprobe tun)
• Root privileges required for creating interfaces
• Supports advanced features: offload, multi-queue

macOS

• TUN interfaces are named utunN
• TAP mode uses a pair of feth interfaces
• Routes are automatically configured

BSD (FreeBSD, OpenBSD, NetBSD)

• Routes are automatically configured
• Platform-specific syscall interfaces

Feature Flags

• async (alias for async_tokio): Enable async support with Tokio runtime
• async_tokio: Use Tokio for async I/O operations
• async_io: Use async-io for async operations (async-std, smol, etc.)
• async_framed: Enable framed I/O with futures
• interruptible: Enable interruptible I/O operations
• experimental: Enable experimental features (unstable)

Safety

This library uses unsafe code in several places:

• File descriptor manipulation on Unix platforms
• FFI calls to platform-specific APIs (Windows, BSD)
• Direct memory access for performance-critical operations

All unsafe code is carefully audited and documented with safety invariants.

Performance Considerations

• Use recv_multiple/send_multiple on Linux with offload enabled for best throughput
• Enable multi-queue on Linux for parallel packet processing across CPU cores
• Consider the async API for high-concurrency scenarios
• Adjust MTU based on your network requirements (default varies by platform)

Error Handling

All I/O operations return std::io::Result with platform-specific error codes. Common error scenarios include:

• Permission denied (need root/administrator)
• Device name conflicts
• Platform-specific driver issues
• Invalid configuration parameters

Modules

async_framed(async_io or async_tokio) and async_framed

Structs

AsyncDeviceUnix and non-macOS

An async Tun/Tap device wrapper around a Tun/Tap device.

BorrowedAsyncDeviceasync_io or async_tokio

A borrowed asynchronous TUN/TAP device.

BorrowedSyncDeviceUnix

DeviceImplUnix and neither Windows, nor macOS, nor Linux and non-target_env=ohos, nor FreeBSD, nor OpenBSD, nor NetBSD

A TUN device for Android/iOS/…

InterruptEventUnix and interruptible

Event object for interrupting blocking I/O operations.

SyncDevice

A transparent wrapper around DeviceImpl, providing synchronous I/O operations.

Constants

PACKET_INFORMATION_LENGTH

Length of the protocol information header used on some platforms.