Crate tappers

Expand description

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§