Skip to content

README.md

Latest commit

 

History

History
291 lines (245 loc) · 10.9 KB

README.md

File metadata and controls

291 lines (245 loc) · 10.9 KB

GitHub Release AUR version Gentoo GURU Crates.io

DPIBreak

Fast and easy-to-use tool for circumventing Deep Packet Inspection (DPI) on HTTPS connections. While your actual data is encrypted over HTTPS, there is a limitation: the TLS ClientHello packet - which contains the destination domain (aka SNI) - must be sent in plaintext during the initial handshake. DPI equipment inspects it at intermediate routers and drops the connection if its SNI is on their blacklist.

The goal of DPIBreak is to manipulate outgoing TLS ClientHello packets in a standards-compliant way, so that DPI equipment can no longer detect the destination domain while the actual server still can.

  • Unlike VPNs, it requires no external server. All processing happens entirely on your machine.
  • It takes effect immediately on all HTTPS connections when launched, and reverts automatically when stopped.
  • Only the small packets needed for this manipulation are touched. All other data packets (e.g., video streaming) pass through without any processing, resulting in very low overhead, which is itself negligible compared to typical internet latency.
  • It supports both Linux and Windows with same circumvention logic.

Oh, and if it matters to you: it is built in Rust. Fast and lightweight as a native binary, without the memory vulnerabilities that are important to privileged network tools.

TL;DR: this tool lets you access ISP-blocked sites at virtually the same speed as an unrestricted connection, with minimal setup.

Features

For more information, please refer to dpibreak(1). (Though you probably won't need it. :)

fragment (default)

Split the TLS ClientHello into smaller pieces so that DPI equipment cannot read the SNI from a single packet. The server reassembles them normally.

fake

Enable fake ClientHello packet (with SNI www.microsoft.com) injection before sending each packet fragmented. For typical usage, use --fake-autottl.

I live in South Korea, and Korean ISP-level DPI was bypassable without this feature. However, the internal DPI at my university was not. With this feature enabled, the university's DPI was also successfully bypassed, so I expect it to be helpful in many other use cases as well.

Note

--fake-autottl may not work correctly for servers with non-standard default TTL values. See #20 for details and workarounds.

Quickstart

Windows

  • Download latest release and unzip it.
  • Double-click dpibreak.exe or start_fake.bat (To use fake).
  • Run service_install.bat with administrator privileges to automatically run per boot (To remove, run service_remove.bat).
  • See WINDOWS_GUIDE.txt for more information (This file includes a Korean translation!).

Linux

Copy this to your terminal and press ENTER.

curl -fsSL https://raw.githubusercontent.com/dilluti0n/dpibreak/master/install.sh | sh

This script automates the manual installation process. View source.

Usage:

sudo dpibreak
sudo dpibreak -D                  # run as daemon
sudo pkill dpibreak               # to stop daemon
sudo dpibreak --fake-autottl      # enable fake packet injection
sudo dpibreak -D --fake-autottl
dpibreak --help
man 1 dpibreak                    # manual

That's it. For manual installation, removal, and package managers, see Installation.

Installation

Manual

Download latest release tarball from here.

tar -xf DPIBreak-X.Y.Z-x86_64-unknown-linux-musl.tar.gz
cd DPIBreak-X.Y.Z-x86_64-unknown-linux-musl
sudo make install

To uninstall:

curl -fsSL https://raw.githubusercontent.com/dilluti0n/dpibreak/master/install.sh | sh -s -- uninstall

# Or if you have extracted tarball:
sudo make uninstall

Arch

Available in the AUR as dpibreak (stable) and dpibreak-git (latest commit).

Using an AUR helper (e.g., yay)

If yay is not installed, set it up first:

sudo pacman -S --needed base-devel git
git clone https://aur.archlinux.org/yay.git
cd yay && makepkg -si

Then install dpibreak:

yay -S dpibreak

Manual

git clone https://aur.archlinux.org/dpibreak.git
cd dpibreak && makepkg -si

Gentoo

Available in the GURU repository.

sudo eselect repository enable guru
sudo emaint sync -r guru
echo 'net-misc/dpibreak ~amd64' | sudo tee -a /etc/portage/package.accept_keywords/dpibreak
sudo emerge --ask net-misc/dpibreak

For rust developers (crates.io)

Requirements: libnetfilter_queue development files (e.g.,libnetfilter-queue-dev on Ubuntu/Debian).

cargo install dpibreak

Note: cargo installs to user directory, so sudo might not see it. Use full path or link it:

# Option 1: Run with full path
sudo ~/.cargo/bin/dpibreak

# Option 2: Symlink to system bin (Recommended)
sudo ln -s ~/.cargo/bin/dpibreak /usr/local/bin/dpibreak
sudo dpibreak

Issue tab

Tip

All issues go here: https://github.com/dilluti0n/dpibreak/issues

  • See dpibreak(1)#BUGS (or unsee it and use issue tab like reddit thread).
  • You can also search and find workaround for known issues from here.

To produce release zip/tarball

Release builds and deployments are automated via GitHub Actions. See .github/workflows/release.yml for details. Compilation requires Rust toolchain. See https://www.rust-lang.org/learn/get-started.

Windows:

  1. Download WinDivert:
Invoke-WebRequest -Uri "https://reqrypt.org/download/WinDivert-2.2.2-A.zip" -OutFile WinDivert.zip
Expand-Archive -Path WinDivert.zip -DestinationPath .\
Remove-Item .\WinDivert.zip
  1. .\build.ps1 zipball

Linux: make tarball

Release zip/tarball should be ready on directory dist.

Built upon

See more

Afterword

Why did I build DPIBreak? There are plenty of alternative tools out there, anyway.

At first, I was looking for a Linux equivalent of GoodByeDPI. Something that activates globally on launch and exits cleanly, with no other setup needed.

I found zapret first. It's powerful and comprehensive, supports not only HTTPS but also UDP packets for discord/wireguard and more. But that breadth might be overkill if all you need is HTTPS bypass. At the time, I just wanted quick access to blocked sites, and a Windows desktop was the easier way out. So the whole process of downloading, setting it up, and learning how to use it felt like too much hassle. In the end, I gave up on it.

SpoofDPI was easier to understand, as it operates as a local proxy. Operating as a proxy makes the tool easily portable to Android and macOS (which SpoofDPI primarily targets). Also, unlike the low-level packet manipulation used by DPIBreak and zapret, it's considerably safer to run.

However, it means you need to connect each application to the local proxy explicitly. Though aliasing each tool - digging through docs for Chromium, curl, yt-dlp and others to set up proxy flags - solved the repetitive typing, some unnecessary overhead still bothered me. Every byte of traffic, not just the handshake but also the actual downloaded data, routes through the local proxy in userspace before re-entering the kernel stack. And that's why I did not consider adding TPROXY rules on my firewall to route every 443 packet to SpoofDPI over aliasing each application.

So I built DPIBreak to bring GoodByeDPI experience to Linux: launch it, works globally, no per-app configuration, no proxy flags, and without having to think twice about overhead on large downloads. Only handshake packets are intercepted via netfilter_queue, and everything else passes through the kernel untouched.

The initial implementation adopted the bypass approach once described in SpoofDPI's README, which was proven to work for my ISP's DPI. It held up well, until I hit a stricter DPI environment on my university network. That's when I added fake support (referencing zapret's approach), and built HopTab - a 128-entry IP-hop cache - to make --fake-autottl viable without measurable overhead.

I use this as my daily driver. Hopefully it's useful to you too.

Copyright 2025-2026 Dilluti0n.

This program is free software, released under the GNU General Public License, version 3 or later.