Struct Iface

Source

pub struct Iface { /* private fields */ }

Expand description

The virtual interface.

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

Implementations§

Source §

impl Iface

Source

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();

Source

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();

Source

pub fn mode(&self) -> Mode

Returns the mode of the adapter.

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

Source

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.

Source

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.

Source

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.

Source