gnirehtet

Gnirehtet works by registering an Android client as a VPN to intercept device network traffic.

Data Flow:

1. The client (on Android) exchanges raw IPv4 packets as byte[] with the relay server.
2. The client maintains a TCP connection to the relay server.
3. This connection is established via adb using reverse port redirection:

   adb reverse localabstract:gnirehtet tcp:31416

   This ensures connections to localhost:31416 on the device are redirected to port 31416 on the host computer.

Relay Server Role:

• The relay server receives IP packets from connected clients.
• It opens standard sockets on the host to relay data in both directions.
• It performs translation between Layer 3 (device side) and Layer 5 (network side) of the OSI model.
• It acts similarly to a port-restricted cone NAT, opening connections on behalf of private peers.

The Gnirehtet relay server is implemented in two flavors:

• Java version: A Java 8 project located in relay-java/ using Java NIO.
• Rust version: A Rust project located in relay-rust/ using the mio crate.

Both versions use asynchronous I/O and are essentially single-threaded, meaning no synchronization is required to handle packets. The server uses a Selector to manage multiple socket channels: the server socket (listening on port 31416), client sockets, and TCP/UDP network connections.

The project exposes specific Gradle tasks to build individual parts:

• debugJava and releaseJava: Builds the Android application and the Java relay server.
• debugRust and releaseRust: Builds the Android application and the Rust relay server.

Alternatively, you can build the Rust relay server directly using cargo for convenience. To build a release version of the Rust relay server:

cd relay-rust
cargo build --release

The resulting binary will be located in target/release/gnirehtet.

To generate a gnirehtet.exe binary on a Linux system, follow these steps:

1. Install the cross-compile toolchain (Debian/Ubuntu):

   sudo apt install gcc-mingw-w64-x86-64
   rustup target add x86_64-pc-windows-gnu

2. Configure Cargo by adding the following to your ~/.cargo/config file:

   [target.x86_64-pc-windows-gnu]
   linker = "x86_64-w64-mingw32-gcc"
   ar = "x86_64-w64-mingw32-gcc-ar"

3. Run the build command:

   cargo build --release --target=x86_64-pc-windows-gnu

The output will be in target/x86_64-pc-windows-gnu/release/gnirehtet.exe.

sudo apt install gcc-mingw-w64-x86-64
rustup target add x86_64-pc-windows-gnu
# (Update ~/.cargo/config as described in documentation)
cargo build --release --target=x86_64-pc-windows-gnu

The simplest way to activate reverse tethering for a single device is using the run command.

Note: On Windows, use gnirehtet instead of ./gnirehtet.

• Single device: ./gnirehtet run (remains active until Ctrl+C).
• All connected devices: ./gnirehtet autorun (enables tethering for all current and future connected devices).
• Windows shortcut: Double-click gnirehtet-run.cmd to run without opening a terminal manually.

You can build the Android application and both the Java and Rust relay servers (in debug and release versions) using gradle.

If you have gradle installed globally, use gradle build. Otherwise, use the included Gradle wrapper ./gradlew build.

To develop on Gnirehtet, you need the following dependencies installed:

1. Android SDK (via Android Studio).
2. JDK 8 (openjdk-8-jdk).
3. Rust environment (required for building the Rust relay server).

You can install Rust using the following commands:

wget https://sh.rustup.rs -O rustup-init
sh rustup-init

Gnirehtet is available in two flavors: Rust (recommended for lower CPU/memory usage) and Java (requires Java 8 JRE).

Using Homebrew (macOS/Linux)

To install the Rust version:

brew install gnirehtet

Manual Download

Download the latest release from the GitHub releases page and extract the archive for your platform.

Gnirehtet requires adb (version 1.0.36 or newer) with adb reverse support.

• Debian-based Linux: Install android-tools-adb or openjdk-8-jre (if using the Java version).
• Windows: If you only need adb for this app, download the Android SDK platform-tools and extract adb.exe, AdbWinApi.dll, and AdbWinUsbApi.dll into the gnirehtet directory.
• Device Setup: Ensure USB debugging is enabled on your Android device.

To develop the Android application or the Java relay server using Android Studio:

1. Open Android Studio.
2. Select File → Import… and choose the Gnirehtet project directory.

Once imported, you can use the IDE to develop, execute Gradle tasks, and run tests with visual results.

You can override default paths using the following environment variables:

• ADB: Defines a custom path to the adb executable.
• GNIREHTET_APK: Defines a custom path to the gnirehtet.apk file.

ADB=/path/to/my/adb ./gnirehtet run
GNIREHTET_APK=/usr/share/gnirehtet/gnirehtet.apk ./gnirehtet run

Each client holds a Router (Router in Java or Rust) responsible for directing packets to the correct connection. A connection is identified by a ConnectionId (or connection in Rust) derived from five properties in the IP and transport headers:

• protocol
• source address
• source port
• destination address
• destination port