Repository files navigation

Boringtun is currently undergoing a restructuring. You should probably not rely on or link tothe master branch right now. Instead you should use the crates.io page.

• boringtun:
• boringtun-cli

BoringTun is an implementation of theWireGuard^® protocol designed for portability and speed.

BoringTun is successfully deployed on millions ofiOS andAndroid consumer devices as well as thousands of Cloudflare Linux servers.

The project consists of two parts:

• The executableboringtun-cli, auserspace WireGuardimplementation for Linux and macOS.
• The libraryboringtun that can be used to implement fast and efficient WireGuard client apps on various platforms, including iOS and Android. It implements the underlying WireGuard protocol, without the network or tunnel stacks, those can be implemented in a platform idiomatic way.

You can install this project usingcargo:

cargo install boringtun-cli

• Library only:cargo build --lib --no-default-features --release [--target $(TARGET_TRIPLE)]
• Executable:cargo build --bin boringtun-cli --release [--target $(TARGET_TRIPLE)]

By default the executable is placed in the./target/release folder. You can copy it to a desired location manually, or install it usingcargo install --bin boringtun --path ..

As per the specification, to start a tunnel use:

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

The tunnel can then be configured usingwg, as a regular WireGuard tunnel, or any other tool.

It is also possible to use withwg-quick by setting the environment variableWG_QUICK_USERSPACE_IMPLEMENTATION toboringtun. For example:

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

Testing this project has a few requirements:

• sudo: required to create tunnels. When you runcargo test you'll be prompted for your password.
• Docker: you can install ithere. If you are on Ubuntu/Debian you can runapt-get install docker.io.

_{Other platforms may be added in the future}

x86-64,aarch64 andarmv7 architectures are supported. The behaviour should be identical to that ofwireguard-go, with the following difference:

boringtun will drop privileges when started. When privileges are dropped it is not possible to setfwmark. Iffwmark is required, such as when usingwg-quick, run with--disable-drop-privileges or set the environment variableWG_SUDO=1.

You will need to give the executable theCAP_NET_ADMIN capability using:sudo setcap cap_net_admin+epi boringtun. sudo is not needed.

The behaviour is similar to that ofwireguard-go. Specifically the interface name must beutun[0-9]+ for an explicit interface name orutun to have the kernel select the lowest available. If you chooseutun as the interface name, and the environment variableWG_TUN_NAME_FILE is defined, then the actual name of the interface chosen by the kernel is written to the file specified by that variable.

The library exposes a set of C ABI bindings, those are defined in thewireguard_ffi.h header file. The C bindings can be used with C/C++, Swift (using a bridging header) or C# (usingDLLImport withCallingConvention set toCdecl).

The library exposes a set of Java Native Interface bindings, those are defined insrc/jni.rs.

The project is licensed under the3-Clause BSD License.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the 3-Clause BSD License, shall be licensed as above, without any additional terms or conditions.

If you want to contribute to this project, please read ourCONTRIBUTING.md.

_{WireGuard is a registered trademark of Jason A. Donenfeld. BoringTun is not sponsored or endorsed by Jason A. Donenfeld.}