firestack

README

Firestack

A userspace TCP/UDP connection monitor, firewall, DNS resolver, and WireGuard client for Android.

Firestack is built specifically for Rethink DNS + Firewall + VPN. gVisor/netstack provides a SOCKS-like interface (similar to badvpn's tun2socks) for TCP and UDP connections over a tun-device.

Firestack is a hard-fork of Google's outline-go-tun2socks project.

DNS

Firestack supports DNS over HTTPS, DNS over TLS, Oblivious DNS over HTTPS, DNSCrypt v3, and plain old DNS upstreams.

WireGuard

Firestack runs WireGuard in userspace. When running multiple WireGuard tunnels at once, only TCP and UDP are forwarded to the tunnels; but otherwise ICMP and DNS are as well. ARP / IGMP / SCTP / RTP and other IP protocols are not forwarded to WireGuard tunnels.

 

WireGuard integration was sponsored by FOSS United.

Releases

Firestack is released as an Android Library (aar) and can be integrated into your Android builds via Jitpack (ref) or Maven Central (OSSRH).

    // add this to your project's build.gradle
    allprojects {
        repositories {
            ...
            // if consuming from maven central
            // ref: central.sonatype.org/consume
            mavenCentral()
            ...
            // if consuming from jitpack
            // ref: docs.jitpack.io/android/#installing
            maven { url 'https://jitpack.io' }
            ...
        }
    }

    // add the dep to your app's build.gradle
    dependencies {
        ...
        // maven central (stripped)
        implementation 'com.celzero:firestack:Tag@aar'
        ...
        // jitpack (stripped)
        implementation 'com.github.celzero:firestack:Tag@aar'
        // jitpack (debug symbols)
        implementation 'com.github.celzero:firestack:Tag:debug@aar'
        ...
    }

API

The APIs aren't stable and hence left undocumented, but you can look at Rethink DNS + Firewall + VPN codebase: (GoVpnAdapter, BraveVpnService) to see how to integrate with Firestack on Android.

Build

Firestack only supports Android. Instructions for other platforms are left as-is, but they may or may not work.

Prerequisites

• macOS host (iOS, macOS)
• make
• Go >= 1.22
• A C compiler (e.g.: clang, gcc)

Firestack APIs are available only on Android builds for now. iOS and Linux support planned but nothing concrete yet.

Android

• sdkmanager
  1. Download the command line tools from developer.android.com.
  2. Unzip the pacakge as ~/Android/Sdk/cmdline-tools/latest/. Make sure sdkmanager is located at ~/Android/Sdk/cmdline-tools/latest/bin/sdkmanager
• Android NDK 28+

  # Install the NDK (exact NDK version obtained from `sdkmanager --list`)
  ~/Android/Sdk/cmdline-tools/latest/bin/sdkmanager "platforms;android-36" "ndk;28.2.13676358"
  # Set up the environment variables:
  export ANDROID_NDK_HOME=~/Android/Sdk/ndk/28.2.13676358 ANDROID_HOME=~/Android/Sdk
  

• gomobile (installed as needed by make)

Apple (iOS and macOS)

• Xcode
• gomobile (installed as needed by make)

Linux and Windows

We build binaries for Linux and Windows from source without any custom integrations. xgo and Docker are required to support cross-compilation.

• Docker (for XGO)
• xgo (installed as needed by make)
• ghcr.io/crazy-max/xgo Docker image (~6.8GB pulled by xgo).

Make

# creates build/intra/{tun2socks.aar,tun2socks-sources.jar}
make clean && make intra

If needed, you can extract the jni files into build/android/jni with:

unzip build/android/tun2socks.aar 'jni/*' -d build/android