#tun #tap #async #tokio

tokio-tun

Asynchronous allocation of TUN/TAP devices using tokio

21 releases

0.3.16 Sep 15, 2021
0.3.14 Jul 3, 2021
0.3.9 Mar 21, 2021
0.3.1 Dec 29, 2020
0.2.3 Oct 28, 2020

#86 in Asynchronous

Download history 15/week @ 2021-06-02 25/week @ 2021-06-09 18/week @ 2021-06-16 3/week @ 2021-06-23 20/week @ 2021-06-30 3/week @ 2021-07-07 23/week @ 2021-07-14 5/week @ 2021-07-21 47/week @ 2021-07-28 29/week @ 2021-08-04 38/week @ 2021-08-11 1/week @ 2021-08-18 18/week @ 2021-08-25 5/week @ 2021-09-01 22/week @ 2021-09-08 88/week @ 2021-09-15

76 downloads per month
Used in 3 crates

MIT/Apache

24KB
611 lines

Tokio TUN/TAP

Build crates.io Documentation examples

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

Getting Started

  • Create a tun device using TunBuilder and read from it in a loop:
#[tokio::main]
async fn main() -> Result<()> {
    let tun = TunBuilder::new()
        .name("")            // if name is empty, then it is set by kernel.
        .tap(false)          // false (default): TUN, true: TAP.
        .packet_info(false)  // false: IFF_NO_PI, default is true.
        .up()                // or set it up manually using `sudo ip link set <tun-name> up`.
        .try_build()?;       // or `.try_build_mq(queues)` for multi-queue support.

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

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

    let mut buf = [0u8; 1024];
    loop {
        let n = reader.read(&mut buf).await?;
        println!("reading {} bytes: {:?}", n, &buf[..n]);
    }
}
  • Run the code using sudo:
  sudo -E /path/to/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!.

Dependencies

~4.5MB
~78K SLoC