BoringTun

On Linux, boringtun drops privileges by default. To allow the executable to manage network interfaces without running the entire process as root, grant it the CAP_NET_ADMIN capability:

sudo setcap cap_net_admin+epi boringtun

To start a tunnel using the CLI, use the following command syntax:

boringtun-cli [-f/--foreground] INTERFACE-NAME

Once the tunnel is running, you can configure it using standard WireGuard tools like wg or wg-quick.

You can install the userspace WireGuard executable boringtun-cli for Linux and macOS using cargo.

cargo install boringtun-cli

Use cargo build to compile the project. You can target the library only or the CLI executable. Use --target $(TARGET_TRIPLE) to specify a target architecture.

• Library only: Builds the boringtun crate without default features.
• Executable: Builds the boringtun-cli binary.

By default, the executable is placed in ./target/release. You can install it manually using cargo install --bin boringtun --path ..

You can use boringtun-cli as the userspace implementation for wg-quick by setting the WG_QUICK_USERSPACE_IMPLEMENTATION environment variable to boringtun-cli.

Note: If you need to set fwmark (common with wg-quick), you must also set WG_SUDO=1 or run with the --disable-drop-privileges flag.

sudo WG_QUICK_USERSPACE_IMPLEMENTATION=boringtun-cli WG_SUDO=1 wg-quick up CONFIGURATION

The boringtun library provides bindings for cross-platform integration:

• C ABI (FFI): Defined in wireguard_ffi.h. Use these for C/C++, Swift (via bridging headers), or C# (using [DllImport] with CallingConvention.Cdecl).
• JNI: Java Native Interface bindings are available for Android/Java integration, defined in src/jni.rs.

The DeviceConfig struct allows you to tune the performance and behavior of the BoringTun device.

Key fields:

• n_threads: Number of worker threads to spawn (defaults to 4).
• use_connected_socket: If true, uses a connected UDP socket for peers to improve performance (defaults to true).
• use_multi_queue: (Linux only) Enables multi-queue support for the TUN interface.
• uapi_fd: (Linux only) A file descriptor for the User API interface.

let config = DeviceConfig {
    n_threads: 8,
    use_connected_socket: true,
    #[cfg(target_os = "linux")]
    use_multi_queue: true,
    #[cfg(target_os = "linux")]
    uapi_fd: -1,
};

On macOS, the interface name must follow the utun[0-9]+ pattern.

• Use an explicit name like utun0.
• Use utun to let the kernel select the lowest available interface.
• If you use utun, you can define the WG_TUN_NAME_FILE environment variable to write the chosen interface name to a specific file.

To start a BoringTun device, use DeviceHandle::new. This function creates a new TUN interface with the specified name, initializes the device with the provided configuration, and spawns the requested number of worker threads. It also automatically opens a listening UDP socket on a random port.

Returns a DeviceHandle which owns the interface and manages the background threads.

Get performance and health metrics for the tunnel connection. Returns a tuple containing:

• Option<Duration>: Time since the last successful handshake.
• usize: Total bytes sent (tx_bytes).
• usize: Total bytes received (rx_bytes).
• f32: Estimated packet loss.
• Option<u32>: Last Round Trip Time (RTT).

Process a received UDP datagram from the network.

To handle all resulting packets (e.g., when the tunnel needs to respond with a handshake or cookie), you should call decapsulate repeatedly with an empty datagram until it returns TunnResult::Done.

Returns a TunnResult which may indicate:

• WriteToNetwork: A packet that needs to be sent back to the network (e.g., a handshake response).
• WriteToTunnelV4 / WriteToTunnelV6: A decrypted IP packet and its source address to be injected into the tunnel interface.
• Done: Processing complete.
• Err: A WireGuardError occurred.