How to use BoringTun with wg-quick on Linux?

Set the environment variable WG_QUICK_USERSPACE_IMPLEMENTATION to boringtun-cli and WG_SUDO=1, then run wg-quick up with your configuration, as detailed in the README. This integrates BoringTun into standard WireGuard workflows.

Is BoringTun faster than wireguard-go?

BoringTun, written in Rust, is designed for high performance and often outperforms wireguard-go in userspace benchmarks. However, kernel WireGuard might still offer better latency and throughput for kernel-integrated use cases.

How do I integrate BoringTun into an Android app?

Use the JNI bindings provided in the library; build for supported targets like aarch64-linux-android and link the native code via Java Native Interface, implementing the platform-specific network stack as needed.

Can BoringTun run on Windows?

The library supports Windows via the x86_64-pc-windows-msvc target for integration, but the CLI tool is not available, so you'll need to handle the tunnel implementation separately in your application.

What's the deal with privilege dropping and fwmark in BoringTun?

Privilege dropping enhances security but disables fwmark by default; if fwmark is needed (e.g., for routing with wg-quick), use --disable-drop-privileges or set WG_SUDO=1, as explained in the Linux section of the README.

How stable is BoringTun for production use?

It's deployed at scale by Cloudflare and in consumer apps, but the README cautions about ongoing restructuring—rely on stable crates.io releases, not the master branch, to avoid instability in critical deployments.

BoringTun or kernel WireGuard for server performance?

BoringTun offers portability and userspace flexibility, ideal for cross-platform apps, but kernel WireGuard may provide better raw performance on Linux servers due to direct kernel integration and lower overhead.

boringtun — Rust WireGuard VPN Implementation

What is boringtun?

BoringTun is a userspace implementation of the WireGuard® VPN protocol, written in Rust for portability and speed. It provides both a standalone CLI tool for Linux and macOS and a library for building WireGuard clients on platforms like iOS and Android, enabling secure, modern VPN connections without relying on platform-specific network stacks.

Target Audience

Developers building VPN clients for mobile platforms (iOS, Android) or needing a portable, high-performance WireGuard implementation for server environments. It's also suitable for system administrators or DevOps engineers who require a userspace WireGuard tunnel on Linux or macOS that integrates with standard tools like wg and wg-quick.

Value Proposition

Developers choose BoringTun for its cross-platform library that separates WireGuard protocol logic from network stacks, allowing flexible integration, and its high-performance Rust implementation that is deployed at scale on millions of devices and Cloudflare servers. It offers security features like privilege dropping on Linux and compatibility with existing WireGuard tooling.

Userspace WireGuard® Implementation in Rust

Use Cases

Best For

Building WireGuard VPN client applications for iOS and Android using a portable Rust library.
Implementing a userspace WireGuard tunnel on Linux or macOS via a standalone CLI tool (boringtun-cli).
Integrating WireGuard protocol functionality into C/C++, Swift, Java, or C# projects via FFI or JNI bindings.
Deploying high-performance WireGuard connections on server environments, such as Cloudflare's infrastructure.
Creating secure VPN solutions for consumer devices that require cross-platform support and efficiency.
Using WireGuard with wg-quick on Linux while maintaining security through privilege dropping or custom fwmark settings.

Not Ideal For

Systems requiring kernel-level WireGuard integration for maximum network throughput and native OS support
Teams seeking a turnkey VPN solution with graphical configuration interfaces or extensive end-user documentation
Projects that must use Windows as the primary platform for the standalone CLI tool
Environments where Rust toolchain adoption or maintenance is impractical due to infrastructure constraints

Pros & Cons

Pros

High Performance Rust Core

Built in Rust for efficiency and speed, proven at scale on millions of consumer devices and Cloudflare servers, ensuring reliable performance in both mobile and server environments.

Cross-Platform Library

Provides a portable Rust library for implementing WireGuard clients on iOS, Android, and other platforms without relying on platform-specific network stacks, enabling flexible app development.

Security with Privilege Dropping

On Linux, automatically drops privileges after tunnel creation to reduce attack surface, with options to retain them via --disable-drop-privileges or WG_SUDO=1 for advanced use cases like fwmark.

Standard Tool Compatibility

Works seamlessly with existing WireGuard tools like wg and wg-quick, as noted in the README for configuration and integration, minimizing learning curves for administrators.

Flexible Integration Bindings

Exposes C ABI and JNI bindings for integration with C/C++, Swift, Java, and C# projects, facilitating use in diverse codebases without reimplementing protocol logic.

Cons

Development Instability Warning

The README explicitly warns that the master branch is undergoing restructuring and is not stable for reliance, forcing users to depend on crates.io releases for production use.

Linux Privilege Limitations

Privilege dropping can interfere with fwmark settings required by wg-quick, necessitating workarounds like --disable-drop-privileges or WG_SUDO=1, which complicate security and setup.

No Windows CLI Support

While the library supports Windows, the boringtun-cli executable is only available for Linux and macOS, limiting standalone userspace tunnel usage on Windows systems.

Complex Testing Requirements

Testing requires sudo and Docker, as stated in the README, adding overhead for development and CI pipelines compared to simpler, pure-Rust test setups.

Frequently Asked Questions

What is boringtun?

Target Audience

Value Proposition

Use Cases

Best For

Building WireGuard VPN client applications for iOS and Android using a portable Rust library.
Implementing a userspace WireGuard tunnel on Linux or macOS via a standalone CLI tool (boringtun-cli).
Integrating WireGuard protocol functionality into C/C++, Swift, Java, or C# projects via FFI or JNI bindings.
Deploying high-performance WireGuard connections on server environments, such as Cloudflare's infrastructure.
Creating secure VPN solutions for consumer devices that require cross-platform support and efficiency.
Using WireGuard with wg-quick on Linux while maintaining security through privilege dropping or custom fwmark settings.

Not Ideal For

Systems requiring kernel-level WireGuard integration for maximum network throughput and native OS support
Teams seeking a turnkey VPN solution with graphical configuration interfaces or extensive end-user documentation
Projects that must use Windows as the primary platform for the standalone CLI tool
Environments where Rust toolchain adoption or maintenance is impractical due to infrastructure constraints

Pros & Cons

Pros

High Performance Rust Core

Built in Rust for efficiency and speed, proven at scale on millions of consumer devices and Cloudflare servers, ensuring reliable performance in both mobile and server environments.

Cross-Platform Library

Provides a portable Rust library for implementing WireGuard clients on iOS, Android, and other platforms without relying on platform-specific network stacks, enabling flexible app development.

Security with Privilege Dropping

On Linux, automatically drops privileges after tunnel creation to reduce attack surface, with options to retain them via --disable-drop-privileges or WG_SUDO=1 for advanced use cases like fwmark.

Standard Tool Compatibility

Works seamlessly with existing WireGuard tools like wg and wg-quick, as noted in the README for configuration and integration, minimizing learning curves for administrators.

Flexible Integration Bindings

Exposes C ABI and JNI bindings for integration with C/C++, Swift, Java, and C# projects, facilitating use in diverse codebases without reimplementing protocol logic.

Cons

Development Instability Warning

The README explicitly warns that the master branch is undergoing restructuring and is not stable for reliance, forcing users to depend on crates.io releases for production use.

Linux Privilege Limitations

Privilege dropping can interfere with fwmark settings required by wg-quick, necessitating workarounds like --disable-drop-privileges or WG_SUDO=1, which complicate security and setup.

No Windows CLI Support

While the library supports Windows, the boringtun-cli executable is only available for Linux and macOS, limiting standalone userspace tunnel usage on Windows systems.

Complex Testing Requirements

Testing requires sudo and Docker, as stated in the README, adding overhead for development and CI pipelines compared to simpler, pure-Rust test setups.

Frequently Asked Questions

boringtun

What is boringtun?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?

boringtun

What is boringtun?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?