Struct DeviceBuilder 

pub struct DeviceBuilder { /* private fields */ }

Available on Windows, or Linux and non-target_env=ohos, or macOS, or FreeBSD, or OpenBSD, or NetBSD only.

This is a unified constructor of a device for various platforms. The specification of every API can be found by looking at the documentation of the concrete platform.

Implementations

impl DeviceBuilder

pub fn new() -> Self

Creates a new DeviceBuilder instance with default settings.

pub fn name<S: Into<String>>(self, dev_name: S) -> Self

Sets the device name.

pub fn mtu(self, mtu: u16) -> Self

Sets the device MTU (Maximum Transmission Unit).

pub fn mac_addr(self, mac_addr: [u8; 6]) -> Self

Available on Windows or Linux or FreeBSD or OpenBSD or macOS or NetBSD only.

Sets the MAC address for the device (effective only in L2 mode).

pub fn ipv4<IPv4: ToIpv4Address, Netmask: ToIpv4Netmask>( self, address: IPv4, mask: Netmask, destination: Option<IPv4>, ) -> Self

Configures the IPv4 address for the device.

• address: The IPv4 address of the device.
• mask: The subnet mask or prefix length.
• destination: Optional destination address for point-to-point links.

Example

use std::net::Ipv4Addr;
use tun_rs::DeviceBuilder;
DeviceBuilder::new().ipv4(Ipv4Addr::new(10, 0, 0, 12), 24, None);

pub fn ipv6<IPv6: ToIpv6Address, Netmask: ToIpv6Netmask>( self, address: IPv6, mask: Netmask, ) -> Self

Configures a single IPv6 address for the device.

• address: The IPv6 address.
• mask: The subnet mask or prefix length.

Example

use tun_rs::DeviceBuilder;
DeviceBuilder::new().ipv6("CDCD:910A:2222:5498:8475:1111:3900:2021", 64);

pub fn ipv6_tuple<IPv6: ToIpv6Address, Netmask: ToIpv6Netmask>( self, addrs: &[(IPv6, Netmask)], ) -> Self

Configures multiple IPv6 addresses in batch.

Accepts a slice of (IPv6 address, netmask) tuples.

Example

use tun_rs::DeviceBuilder;
DeviceBuilder::new().ipv6_tuple(&[
    ("CDCD:910A:2222:5498:8475:1111:3900:2022", 64),
    ("CDCD:910A:2222:5498:8475:1111:3900:2023", 64),
]);

pub fn layer(self, layer: Layer) -> Self

Sets the operating layer (L2 or L3) for the device.

• L2 corresponds to TAP
• L3 corresponds to TUN

pub fn tx_queue_len(self, tx_queue_len: u32) -> Self

Available on Linux only.

Sets the transmit queue length on Linux.

pub fn offload(self, offload: bool) -> Self

Available on Linux only.

Enables TUN offloads on Linux. After enabling, use recv_multiple/send_multiple for data transmission.

pub fn multi_queue(self, multi_queue: bool) -> Self

Available on Linux only.

Enables multi-queue support on Linux.

pub fn packet_information(self, packet_information: bool) -> Self

Available on macOS or Linux or FreeBSD or OpenBSD or NetBSD only.

Enables or disables packet information for the network driver(TUN) on macOS, Linux, freebsd, openbsd, netbsd.

This option is disabled by default (false).

Note

There is no native way to enable/disable packet information on macOS. The elimination of the packet information on macOS according to this setting is processed by this library. The set value v can be retrieved by ignore_packet_info, the returned value is !v.

pub fn enable(self, enable: bool) -> Self

Enables or disables the network interface upon creation.

By default, newly created TUN/TAP devices are enabled (brought up). Use this method to control whether the device should be automatically enabled or left in a disabled state.

Arguments

• enable - true to enable the device (default), false to leave it disabled

Example

use tun_rs::DeviceBuilder;

// Create a device but leave it disabled initially
let dev = DeviceBuilder::new()
    .ipv4("10.0.0.1", 24, None)
    .enable(false)  // Don't enable the device yet
    .build_sync()?;

// Later, enable it manually using platform-specific methods
// dev.enabled(true)?;

See Also

• inherit_enable_state - Preserve existing device state

pub fn inherit_enable_state(self) -> Self

Preserves the existing enable state of the network interface.

When reusing an existing device, this method prevents the builder from explicitly setting the device’s enable/disable state. The device will retain whatever state it currently has in the system.

This is particularly useful when:

• Reconnecting to an existing TUN/TAP device
• You want to preserve the current system configuration
• Avoiding unnecessary state changes that might disrupt existing connections

Example

use tun_rs::DeviceBuilder;

// Reuse an existing device and keep its current enabled state
let dev = DeviceBuilder::new()
    .name("tun0")
    .ipv4("10.0.0.1", 24, None)
    .with(|builder| {
        builder.reuse_dev(true)
    })
    .inherit_enable_state()  // Don't change the existing enable state
    .build_sync()?;

See Also

• enable - Explicitly enable or disable the device

pub fn build_sync(self) -> Result<SyncDevice>

Builds a synchronous device instance and applies all configuration parameters.

pub fn build_async(self) -> Result<AsyncDevice>

Available on crate features async_io or async_tokio only.

Builds an asynchronous device instance.

This method is available only when either async_io or async_tokio feature is enabled.

Note

Choose one of the two async runtimes; otherwise, a compile error will be incurred if both are enabled.

pub fn with<F: FnMut(&mut DeviceBuilderGuard<'_>)>(self, f: F) -> Self

To conveniently set the platform-specific parameters without breaking the calling chain.

Ergonomic

For example:

use tun_rs::DeviceBuilder;
let builder = DeviceBuilder::new().name("tun1");
#[cfg(target_os = "macos")]
let builder = builder.associate_route(false);
#[cfg(windows)]
let builder = builder.wintun_log(false);
let dev = builder.build_sync().unwrap();

This is tedious and breaks the calling chain.

With with, we can just set platform-specific parameters as follows without breaking the calling chain:

use tun_rs::DeviceBuilder;
let dev = DeviceBuilder::new().name("tun1").with(|opt|{
   #[cfg(windows)]
   opt.wintun_log(false);
   #[cfg(target_os = "macos")]
   opt.associate_route(false).packet_information(false);
}).build_sync().unwrap();

Trait Implementations

impl Default for DeviceBuilder

fn default() -> DeviceBuilder

Returns the “default value” for a type.