Tokio TUN/TAP

Asynchronous allocation of TUN/TAP devices in Rust using tokio. Use async-tun for async-std version.

Getting Started

• Create a tun device using Tun::builder() and read from it in a loop:

#[tokio::main]
async fn main() {
    let tun = Arc::new(
        Tun::builder()
            .name("")            // if name is empty, then it is set by kernel.
            .tap()               // uses TAP instead of TUN (default).
            .packet_info()       // avoids setting IFF_NO_PI.
            .up()                // or set it up manually using `sudo ip link set <tun-name> up`.
            .build()
            .unwrap()
            .pop()
            .unwrap(),
    );

    println!("tun created, name: {}, fd: {}", tun.name(), tun.as_raw_fd());

    let (mut reader, mut _writer) = tokio::io::split(tun);

    // Writer: simply clone Arced Tun.
    let tun_c = tun.clone();
    tokio::spawn(async move{
        let buf = b"data to be written";
        tun_c.send_all(buf).await.unwrap();
    });

    // Reader
    let mut buf = [0u8; 1024];
    loop {
        let n = tun.recv(&mut buf).await.unwrap();
        println!("reading {} bytes: {:?}", n, &buf[..n]);
    }
}

• Run the code using sudo:

sudo -E $(which cargo) run

• Set the address of device (address and netmask could also be set using TunBuilder):

sudo ip a add 10.0.0.1/24 dev <tun-name>

• Ping to read packets:

ping 10.0.0.2

• Display devices and analyze the network traffic:

ip tuntap
sudo tshark -i <tun-name>

Supported Platforms

• Linux
• FreeBSD
• Android
• OSX
• iOS
• Windows

Examples

• read: Split tun to (reader, writer) pair and read packets from reader.
• read-mq: Read from multi-queue tun using tokio::select!.

sudo -E $(which cargo) run --example read
sudo -E $(which cargo) run --example read-mq