Struct tun_tap::Iface

pub struct Iface { /* private fields */ }

The virtual interface.

This is the main structure of the crate, representing the actual virtual interface, either in TUN or TAP mode.

Implementations

impl Iface

pub fn new(ifname: &str, mode: Mode) -> Result<Self>

Creates a new virtual interface.

Parameters

• ifname: The requested name of the virtual device. If left empty, the kernel will provide some reasonable, currently unused name. It also can contain %d, which will be replaced by a number to ensure the name is unused. Even if it isn’t empty or doesn’t contain %d, the actual name may be different (for example truncated to OS-dependent length). Use name to find out the real name.
• mode: In which mode to create the device.

Errors

This may fail for various OS-dependent reasons. However, two most common are:

• The name is already taken.
• The process doesn’t have the needed privileges (eg. CAP_NETADM).

Examples

let iface = Iface::new("mytun", Mode::Tun).expect("Failed to create a TUN device");
let name = iface.name();
// Configure the device ‒ set IP address on it, bring it up.
let mut buffer = vec![0; 1504]; // MTU + 4 for the header
iface.recv(&mut buffer).unwrap();

pub fn without_packet_info(ifname: &str, mode: Mode) -> Result<Self>

Creates a new virtual interface without the prepended packet info.

Parameters

• ifname: The requested name of the virtual device. If left empty, the kernel will provide some reasonable, currently unused name. It also can contain %d, which will be replaced by a number to ensure the name is unused. Even if it isn’t empty or doesn’t contain %d, the actual name may be different (for example truncated to OS-dependent length). Use name to find out the real name.
• mode: In which mode to create the device.

Errors

This may fail for various OS-dependent reasons. However, two most common are:

• The name is already taken.
• The process doesn’t have the needed privileges (eg. CAP_NETADM).

Examples

let iface = Iface::without_packet_info("mytap", Mode::Tap).expect("Failed to create a TAP device");
let name = iface.name();
// Configure the device ‒ set IP address on it, bring it up.
let mut buffer = vec![0; 1500]; // MTU
iface.recv(&mut buffer).unwrap();

pub fn mode(&self) -> Mode

Returns the mode of the adapter.

It is always the same as the one passed to new.

pub fn name(&self) -> &str

Returns the real name of the adapter.

Use this to find out what the real name of the adapter is. The parameter of new is more of a wish than hard requirement and the name of the created device might be different. Therefore, always create the interface and then find out the actual name by this method before proceeding.

pub fn recv(&self, buf: &mut [u8]) -> Result<usize>

Receives a packet from the interface.

By default, blocks until a packet is sent into the virtual interface. At that point, the content of the packet is copied into the provided buffer.

If interface has been set to be non-blocking, this will fail with an error of kind WouldBlock instead of blocking if no packet is queued up.

Make sure the buffer is large enough. It is MTU of the interface (usually 1500, unless reconfigured) + 4 for the header in case that packet info is prepended, MTU + size of ethernet frame (38 bytes, unless VLan tags are enabled). If the buffer isn’t large enough, the packet gets truncated.

Result

On successful receive, the number of bytes copied into the buffer is returned.

pub fn send(&self, buf: &[u8]) -> Result<usize>

Sends a packet into the interface.

Sends a packet through the interface. The buffer must be valid representation of a packet (with appropriate headers).

If interface has been set to be non-blocking, this will fail with an error of kind WouldBlock instead of blocking if interface is not ready.

It is up to the caller to provide only packets that fit MTU.

Result

On successful send, the number of bytes sent in the packet is returned. Under normal circumstances, this should be the size of the packet passed.

Notes

The TUN/TAP is a network adapter. Therefore, many errors are handled simply by dropping packets. If you pass an invalid packet, it’ll likely suceed in sending it, but will be dropped somewhere in kernel due to failed validation. If you send packets too fast, they are likely to get dropped too. If you send a packet for address that is not assigned to any interface and not routed anywhere… you get the idea.

pub fn set_non_blocking(&self) -> Result<()>

Sets the interface to be non-blocking

Note the behaviour of send and recv will change if set.

Errors

This fails with an error in case of low-level OS errors (they shouldn’t usually happen).

Notes

If default features are excluded, include feature “libc” for this function to be available

Trait Implementations

impl AsRawFd for Iface

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Debug for Iface

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl IntoRawFd for Iface

fn into_raw_fd(self) -> RawFd

Consumes this object, returning the raw underlying file descriptor.