Coder Social home page Coder Social logo

boringtun's Introduction

boringtun logo banner

BoringTun

Warning

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

  • boringtun: crates.io
  • boringtun-cli crates.io

BoringTun is an implementation of the WireGuard® protocol designed for portability and speed.

BoringTun is successfully deployed on millions of iOS and Android consumer devices as well as thousands of Cloudflare Linux servers.

The project consists of two parts:

  • The executable boringtun-cli, a userspace WireGuard implementation for Linux and macOS.
  • The library boringtun 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.

Installation

You can install this project using cargo:

cargo install boringtun-cli

Building

  • 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 using cargo install --bin boringtun --path ..

Running

As per the specification, to start a tunnel use:

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

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

It is also possible to use with wg-quick by setting the environment variable WG_QUICK_USERSPACE_IMPLEMENTATION to boringtun. For example:

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

Testing

Testing this project has a few requirements:

  • sudo: required to create tunnels. When you run cargo test you'll be prompted for your password.
  • Docker: you can install it here. If you are on Ubuntu/Debian you can run apt-get install docker.io.

Supported platforms

Target triple Binary Library
x86_64-unknown-linux-gnu
aarch64-unknown-linux-gnu
armv7-unknown-linux-gnueabihf
x86_64-apple-darwin
x86_64-pc-windows-msvc
aarch64-apple-ios
armv7-apple-ios
armv7s-apple-ios
aarch64-linux-android
arm-linux-androideabi

Other platforms may be added in the future

Linux

x86-64, aarch64 and armv7 architectures are supported. The behaviour should be identical to that of wireguard-go, with the following difference:

boringtun will drop privileges when started. When privileges are dropped it is not possible to set fwmark. If fwmark is required, such as when using wg-quick, run with --disable-drop-privileges or set the environment variable WG_SUDO=1.

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

macOS

The behaviour is similar to that of wireguard-go. Specifically the interface name must be utun[0-9]+ for an explicit interface name or utun to have the kernel select the lowest available. If you choose utun as the interface name, and the environment variable WG_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.


FFI bindings

The library exposes a set of C ABI bindings, those are defined in the wireguard_ffi.h header file. The C bindings can be used with C/C++, Swift (using a bridging header) or C# (using DLLImport with CallingConvention set to Cdecl).

JNI bindings

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

License

The project is licensed under the 3-Clause BSD License.

Contribution

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 our CONTRIBUTING.md.


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

boringtun's People

Contributors

0xadd1e avatar agrover avatar an-p avatar aosemp avatar ashleygwilliams avatar bbockelm avatar bestmike007 avatar cbranch avatar csabol avatar dependabot[bot] avatar jeff-hiner avatar kloepper avatar kornelski avatar lcruz99 avatar lpraneis avatar lu-zero avatar marcoieni avatar naga-cf avatar noah-kennedy avatar phillyqueso avatar poupas avatar robinhundt avatar sabify avatar schultetwin1 avatar thomaseizinger avatar vkrasnov avatar wasserfuhr avatar wiresock avatar zachwalton avatar zaid3tech avatar

Watchers

 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.