Skip to main content

Crate tun_rs

Crate tun_rs 

Source
Expand description

§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

§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
DeviceBuilderWindows, or Linux and non-target_env=ohos, or macOS, or FreeBSD, or OpenBSD, or NetBSD
This is a unified constructor of a device for various platforms. The specification of every API can be found by looking at the documentation of the concrete platform.
DeviceImpl
A TUN device using the TUN/TAP Linux driver.
GROTable
Generic Receive Offload (GRO) table for managing packet coalescing.
InterruptEventUnix and interruptible
Event object for interrupting blocking I/O operations.
SyncDevice
A transparent wrapper around DeviceImpl, providing synchronous I/O operations.

Enums§

LayerWindows, or Linux and non-target_env=ohos, or macOS, or FreeBSD, or OpenBSD, or NetBSD
Represents the OSI layer at which the TUN/TAP interface operates.

Constants§

IDEAL_BATCH_SIZE
Recommended batch size for packet operations with offload.
PACKET_INFORMATION_LENGTH
Length of the protocol information header used on some platforms.
VIRTIO_NET_HDR_LEN
Size of the virtio network header in bytes (12 bytes).

Traits§

ExpandBuffer
A trait for buffers that can be expanded and resized for offload operations.
ToIpv4AddressWindows, or Linux and non-target_env=ohos, or macOS, or FreeBSD, or OpenBSD, or NetBSD
Trait for converting various types into an IPv4 address.
ToIpv4NetmaskWindows, or Linux and non-target_env=ohos, or macOS, or FreeBSD, or OpenBSD, or NetBSD
Trait for converting various types into an IPv4 netmask (prefix length).
ToIpv6AddressWindows, or Linux and non-target_env=ohos, or macOS, or FreeBSD, or OpenBSD, or NetBSD
Trait for converting various types into an IPv6 address.
ToIpv6NetmaskWindows, or Linux and non-target_env=ohos, or macOS, or FreeBSD, or OpenBSD, or NetBSD
Trait for converting various types into an IPv6 netmask (prefix length).