Crate tappers

Tappers is a networking library that provides cross-platform support for TUN, TAP and virtual Ethernet (vETH) interfaces in Rust.

The Tun and Tap structs found in the root of this crate are designed to work across all supported platforms (Linux/MacOS/Windows/*BSD). Additional OS-specific functionality is provided via the linux, macos, unix and wintun modules.

Examples

To create a TUN device and begin synchronously receiving packets from it:

use std::net::Ipv4Addr;
use tappers::Tun;

let mut tun = Tun::new()?;
tun.add_addr(Ipv4Addr::new(10, 100, 0, 1))?;
tun.set_up()?; // Enables the TUN device to exchange packets

let mut recv_buf = [0; 65536];

loop {
    let amount = tun.recv(&mut recv_buf)?;
    println!("Received packet: {:?}", &recv_buf[0..amount]);
}

Likewise, to create a TAP device and begin receiving packets from it:

use std::net::Ipv6Addr;
use tappers::Tap;

// Create a new TAP device with a unique identifier
let mut tap = Tap::new()?;
// Assign an IP address to the TAP device
tap.add_addr(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff))?;
// Enable the TAP device to begin receiving packets
tap.set_up()?;

let mut recv_buf = [0; 65536];

loop {
    // Receive a single link-layer packet from the TAP device
    let amount = tap.recv(&mut recv_buf)?;
    println!("Received packet: {:?}", &recv_buf[0..amount]);
}

Tappers additionally allows for more complex configuration of interfaces:

use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
use tappers::{AddAddressV4, AddAddressV6, AddressInfo, DeviceState, Interface, Tap};

// Select an existing (or new) TAP interface name to open
let tap_name = Interface::new("tap10")?;

// Open the TAP device of the name "tap10" (or create it if it doesn't exist)
let mut tap = Tap::new_named(tap_name)?;

// Add a new address with associated info to the TAP device
let new_addr = Ipv4Addr::new(10, 100, 0, 1);
let mut addr_req = AddAddressV4::new(new_addr);
addr_req.set_netmask(24);
addr_req.set_broadcast(Ipv4Addr::new(10, 100, 0, 255));

tap.add_addr(addr_req)?;

// Retrieve information on the IPv4/IPv6 addresses bound to the TAP device
let addrs = tap.addrs()?;
for addr_info in addrs {
    println!("IP address: {}", addr_info.address());
    if let Some(netmask) = addr_info.netmask() {
        println!("Netmask: {}", netmask);
    }
    if let Some(broadcast) = addr_info.broadcast() {
        println!("Broadcast: {}", broadcast);
    }
}

// Remove an address from the TAP device
tap.remove_addr(IpAddr::V4(new_addr))?;

// Configure whether the TAP device performs non-blocking reads/writes
tap.set_nonblocking(true)?;

// Bring the device up to enable packet exchange
tap.set_state(DeviceState::Up);

let mut buf = [0; 65536];

// Receive packets from the interface
let amount = tap.recv(&mut buf)?;

// Send packets over the interface
let amount = tap.send(&buf[..amount])?;

// Bring the device down to disable packet exchange
tap.set_state(DeviceState::Down);

// The TUN device represented by `tun` is automatically be removed from the system when dropped.

Modules

• async_stdasync-std
  Async Tun/Tap interfaces compatible with async-std.
• linuxLinux
  Linux-specific TUN/TAP interfaces.
• macosmacOS
  MacOS-specific TUN/TAP interfaces.
• miomio and non-Windows
  Async Tun/Tap interfaces compatible with mio.
• smolsmol
  Async Tun/Tap interfaces compatible with smol.
• tokiotokio
  Async Tun/Tap interfaces compatible with tokio.
• unixDragonFly BSD or FreeBSD or NetBSD or OpenBSD
  TUN/TAP interface for various other Unix systems.
• wintunWindows and wintun
  (Windows) TUN-specific interfaces provided by the wintun driver.

Structs

• AddAddressV4
  An information type used to add an IPv4 address and its associated information (desination address, netmask, etc.) to an interface.
• AddAddressV6
  An information type used to add an IPv6 address and its associated information (desination address, netmask, etc.) to an interface.
• AddrConversionError
  An error in converting data into a MAC address.
• AddressInfoV4
  Information associated with an interface IPv4 address.
• AddressInfoV6
  Information associated with an interface IPv6 address.
• Interface
  An identifier associated with a particular network device.
• MacAddr
  A MAC (Media Access Control) address.
• TapNon-Windows
  A cross-platform TAP interface, suitable for tunnelling link-layer packets.
• TunNon-Windows or wintun
  A cross-platform TUN interface, suitable for tunnelling network-layer packets.

Enums

• AddAddress
  An information type used to add an address and its associated information (desination address, netmask, etc.) to an interface.
• AddressInfo
  Information associated with an interface IP address.
• DeviceState
  The device state of an Interface.

Type Aliases

• Netmask