B4

[Documentation] [Документация (RU)] [Telegram]

B4 (Bye Bye Big Bro) is a Linux service that bypasses DPI-based blocking. It runs on routers, servers and desktops and rewrites packets so DPI equipment cannot classify the connection, while the destination server still gets valid data. Installed on a router, it covers every device on the network with nothing configured on the clients.

Configuration is built from sets. A set is a list of targets (domains, IPs/CIDRs, geosite/geoip categories, ports, LAN devices) plus the bypass techniques, DNS handling and routing applied to them. Sets are edited in the built-in web UI on port 7000 and applied to the running service without a restart.

If you don't know which technique your provider needs, Discovery tests strategies against your own connection and saves the working one as a set. The Watchdog re-runs it when a site breaks.

Features

• Ten fragmentation strategies: combo, hybrid, tcp, ip, tls, oob, disorder, extsplit, firstbyte, none, plus a random strategy pool
• Fake packet injection: decoy ClientHellos, TCP desync bursts, window manipulation, fake SYN, SACK stripping, ClientHello mutation
• RST protection - detects forged resets by TTL/flag/option fingerprint and drops them
• DNS: per-set redirect to a plain resolver or DoH, hosts-style pins, fragmented queries, DNS-over-TCP interception, healing of answers pointing at dead addresses
• Routing: send a set's traffic out a chosen interface (VPN, WireGuard, second WAN), through an upstream SOCKS5 proxy, or block it
• Block mode for network-wide ad and tracker blocking
• Telegram: built-in MTProto proxy, plus a transparent Telegram-over-WebSocket bridge for stock clients
• Discovery finds a working strategy, Watchdog re-heals broken domains, DPI Detector reports what the provider is doing
• Escalation chains: when a set stops working for a host, that host moves to a heavier backup set
• Per-device rules by MAC
• Works on both iptables and nftables, picking the backend automatically, and handles IPv4 and IPv6
• Web UI in English and Russian

Requirements

• Linux, kernel 3.13+, root access
• NFQUEUE support in the kernel, or TUN mode if it has none
• iptables or nft, plus ip. ipset is needed for routing features on iptables-only systems
• ~64 MB free RAM, ~30 MB disk

[!IMPORTANT] On OpenWrt and most router firmware, netfilter flow offloading puts established connections on a fast path that skips the hooks B4 uses. If bypass appears to do nothing, run install.sh --sysinfo.

Installation

Run as root (sudo -i, or pipe into sudo sh).

curl -fsSL https://raw.githubusercontent.com/DanielLavrushin/b4/main/install.sh | sudo sh

wget -qO- https://raw.githubusercontent.com/DanielLavrushin/b4/main/install.sh | sudo sh

Then open http://<device-ip>:7000.

Installer options

./install.sh                         # interactive wizard
./install.sh v1.77.0                 # specific version
./install.sh --quiet                 # non-interactive, all defaults
./install.sh --arch=mipsle_softfloat # force architecture
./install.sh --platform=openwrt      # force platform
./install.sh --sysinfo               # system diagnostics
./install.sh --help                  # full usage

[!WARNING] --remove --quiet deletes the config directory and geodata without asking. A run without a terminal on standard input behaves as --quiet, except --remove, which refuses unless --quiet is given explicitly.

First run

1. Open the web UI, go to Discovery, type a blocked site and press Start. Takes 1-10 minutes.
2. On a successful result click Use this configuration, then Create a new set.
3. Open the site. On the Traffic page, connections to that domain now show the set name.

Docs: Quickstart

Supported platforms

Architectures: amd64, 386, arm64, armv5, armv6, armv7, mips, mipsle, mips_softfloat, mipsle_softfloat, mips64, mips64le, loong64, ppc64, ppc64le, riscv64, s390x.

Docs: Linux · OpenWrt · Merlin · Keenetic · MikroTik · Docker

Docker

docker run -d --name b4 --network host \
  --cap-add NET_ADMIN --cap-add NET_RAW --cap-add SYS_MODULE \
  -v /etc/b4:/etc/b4 \
  lavrushin/b4:latest

services:
  b4:
    image: lavrushin/b4:latest
    container_name: b4
    network_mode: host
    cap_add:
      - NET_ADMIN
      - NET_RAW
      - SYS_MODULE
    volumes:
      - ./config:/etc/b4
    restart: unless-stopped

Linux hosts only, and --network host is mandatory. The config is auto-discovered at /etc/b4/b4.json - do not override it with --config or it gets written inside the container and lost on recreation. Self-update and restart from the web UI do not work in Docker; pull a new image instead.

Images: lavrushin/b4 and ghcr.io/daniellavrushin/b4.

Sets

A set is a list of targets plus what to do with traffic matching them. A set can target any combination of domains, IPs and CIDRs, GeoSite and GeoIP categories, destination ports, LAN devices by MAC, and TLS or IP version.

Sets are evaluated top-down and the first match wins, so specific sets go above general ones. Two sets listing the same domain is a silent conflict - only the first applies.

Docs: Sets · Targets

GeoSite / GeoIP

Rather than listing domains by hand, a set can target whole categories - youtube, category-ads-all, a country's address ranges - from the v2ray/xray geosite and geoip databases. This is how most people cover a service and everything it talks to.

Download the databases from Settings → Geodat Settings (Loyalsoldier, RUNET Freedom, b4geoip, or your own URL), or let the installer fetch them during setup, then add categories under Sets → Targets. They can be refreshed on a schedule.

Docs: Geo data

Bypass techniques

On top of the split: fake ClientHello injection, TCP desync, window manipulation, fake SYN, TCP-MD5, SACK stripping, ClientHello mutation, sequence overlap, packet duplication and MSS clamping.

Matched UDP and QUIC is either fragmented and faked like TCP, dropped, or rejected with an ICMP unreachable so the browser falls back to TCP straight away. QUIC Initial packets are decrypted to read the SNI. STUN and Discord voice packets are left alone by default.

Docs: Splitting · Faking · RST Protection · UDP

DNS

B4 intercepts plain DNS on port 53 and answers matched domains itself. Per set: redirect to a plain resolver or DoH endpoint, hosts-style pins, fragmented queries, and HealDNS to strip unreachable addresses out of answers.

A device running its own DoH/DoT (Chrome Secure DNS, Android Private DNS) bypasses all of it - turn that off on the client or block it.

Docs: DNS

Routing and blocking

Besides mangling packets, a set can pick a routing mode:

Destination IPs are learned from DNS answers and live traffic, so CDNs that rotate DNS keep working. Block mode with a geosite ads category gives network-wide ad blocking.

The two proxy modes need TPROXY support in the kernel.

Docs: Routing · Blocking

Telegram

Two independent features, under Settings → Telegram.

MTProto proxy - a fake-TLS proxy Telegram clients connect to directly, with named revocable secrets and a tg://proxy share link. Disabled by default, port 3128.

Telegram over WebSocket - a routing mode you pick on a set, working as a transparent bridge. Clients keep using stock Telegram with no proxy configured, and B4 carries their traffic over WebSocket, Cloudflare-proxied domains, or your own Cloudflare Worker when direct TCP is blocked. It runs on its own; the proxy above does not need to be enabled.

Docs: MTProto / Telegram

Discovery, Watchdog, DPI Detector

Discovery tests bypass strategies against your real network on an isolated queue, tunes the parameters of whatever works, and checks for DNS poisoning and IP-level blocks along the way, asking other regions' DNS answers for an address the block does not cover. Results apply as sets without a restart, and the set is previewed before it is created.

Watchdog fetches the domains you list periodically. After enough consecutive failures it re-runs Discovery for that domain, verifies the result, and rolls back if it does not hold. Disabled by default.

DPI Detector runs read-only probes and reports what the provider is doing: DNS integrity and availability, domain reachability, where connections get throttled, which SNI values pass, and Telegram speed.

Web interface and REST API

The web UI and the REST API share one port, 7000 by default.

Most changes apply on save. Some settings on the Core and System tabs take effect only after a restart, and the UI marks them.

[!CAUTION] The web UI and REST API are unauthenticated until you set both a username and a password under Settings → System → Web Server. Do not expose port 7000 to the internet without them; the Expose to internet switch on that screen refuses to open the port until both are set, and HTTPS keeps them off the wire in plain text.

HTTPS is enabled by pointing the same screen at a certificate and key. The installer detects router certificates on OpenWrt and Asus Merlin and offers to turn it on.

The API reference is on the docs site: https://docs.b4core.app/swagger

Docs: Security · Dashboard · Connections (RU) · Logs (RU)

SOCKS5 proxy

B4 also ships a SOCKS5 server for applications that support it. Enable it under Settings → Core → SOCKS5; it listens on port 1080 by default and routes through the bypass engine.

curl --socks5 127.0.0.1:1080 https://example.com

Leaving the username and password empty means no authentication, and it binds all interfaces by default. SOCKS5 changes apply on save, without a restart.

Import from zapret or byedpi

Paste an existing nfqws or ciadpi command line into Sets → Import and B4 translates it into equivalent sets, with a per-option report of what was mapped exactly, approximated or lost. Only zapret and byedpi are supported.

Docs: Import from another tool

Configuration file

Everything lives in one JSON file, created on first run and migrated automatically on upgrade. Back it up from Settings → System → Backup.

[!IMPORTANT] B4 does not watch the config file. Editing it by hand while the service runs has no effect and gets overwritten. Edit while stopped, or use the web UI.

Docs: Configuration file (RU) · Core settings · System settings

TUN mode

For kernels without NFQUEUE support, switch the engine mode to TUN interface under Settings → Core → Packet Engine. B4 creates its own TUN device and steers traffic into it with policy routing, running the same packet engine.

[!IMPORTANT] TUN mode is a fallback, not an equal alternative. Roughly 60% of the feature set works there: B4 installs none of its usual firewall rules, so anything built on them is unavailable. Discovery and the Watchdog's auto-healing do not run, and IPv6 is not forwarded. Use NFQUEUE where the kernel supports it.

Command line

Domains, sets and geosite categories are config-file and web UI only; there are no flags for them.

b4 --help                    # print help
b4 --version                 # version, commit, build date
b4 --config /path/b4.json    # use a specific config file
b4 --verbose debug           # debug | trace | info | silent
b4 --web-port 8080           # override the web UI port (0 disables it)
b4 --clear-tables            # remove b4's firewall rules and exit

Also accepted: --queue-num, --threads, --mark, --ipv4, --ipv6, --tables-monitor-interval, --log-dir, --syslog, -i/--instaflush.

Docs: CLI parameters (RU)

Updating and uninstalling

# to the latest version
curl -fsSL https://raw.githubusercontent.com/DanielLavrushin/b4/main/install.sh | sudo sh -s -- --update

# to a specific version
curl -fsSL https://raw.githubusercontent.com/DanielLavrushin/b4/main/install.sh | sudo sh -s -- --update v1.43.0

# uninstall
curl -fsSL https://raw.githubusercontent.com/DanielLavrushin/b4/main/install.sh | sudo sh -s -- --remove

Updating from the web UI also works, except in Docker.

Troubleshooting

install.sh --sysinfo reports the kernel, platform, service status, firewall backend, NFQUEUE and conntrack probes, flow-offload state and missing tools. The same data is in the web UI under Settings → System → Service → System Info.

Common causes when bypass appears to do nothing:

• Flow offloading (OpenWrt and most router firmware). Established flows skip B4's hooks. Disable it, or guard it with ct original packets ge 40 flow offload @ft in /usr/share/firewall4/templates/ruleset.uc followed by fw4 restart.
• Client-side DoH/DoT. A device resolving names itself bypasses every DNS feature.
• Missing kernel modules. B4 names the module and package it needs. If NFQUEUE cannot be made to work at all, fall back to TUN mode and its limitations.
• Set order. First match wins. The Traffic page shows which set actually matched.

For bug reports: on the Logs page click Start trace, reproduce the problem, then stop and download. The bundle has the build version, system diagnostics and a redacted summary of the enabled sets.

Building from source

Requires Go 1.25.14, Node 22 and pnpm 10.

git clone https://github.com/daniellavrushin/b4.git
cd b4

# Build the web UI first - it gets embedded into the binary
make build-ui

# Build for the current platform (VERSION is required)
make build VERSION=1.77.0

make build-all      # all release architectures into out/assets/
make linux-arm64    # a single architecture
make help           # all targets

install.sh is generated. Edit the sources under installer/ and run make build-installer.

Documentation

https://docs.b4core.app/ · Русская версия

A few English pages (DPI Detector, Connections, Logs and the Advanced section) are still being translated. Use the language switcher for the Russian originals.

Contributing

Contributions are accepted through GitHub pull requests.

Community projects

Maintained outside this repository:

• luci-app-b4 by BugOldfag - adds b4 management to the LuCI interface on OpenWrt
• b4-mikrotik by wiktorbgu - container image packaged for MikroTik RouterOS, with an OpenRC-supervised service, startup selection of the firewall backend and a fix for the routing rule priorities RouterOS 7.22 passes into containers

Credits

Based on research from:

• youtubeUnblock - C-based DPI bypass
• GoodbyeDPI - Windows DPI circumvention
• zapret - Advanced DPI bypass techniques
• byedpi - proxy-based DPI bypass
• dpi-detector - DPI/TSPU detection techniques and test target lists (the DPI Detector feature is based on this project)
• Ladon - reactive Anti-DPI detection engine; its failure-classification approach (telling server-side rejection apart from DPI interference) informed the Watchdog feature
• tg-ws-proxy - Telegram MTProto-over-WebSocket bridging
• ori - GoodCheck ideas in Discovery

License

This project is provided for educational purposes. Users are responsible for compliance with applicable laws and regulations. The authors are not responsible for misuse of this software.