honk

English | 中文

honk is an experimental Rust transparent-proxy engine for Linux. Its eBPF datapath and configuration syntax are inspired by dae; its outbound groups, multi-protocol dialers, and Clash-compatible API follow sing-box designs. It is an independent implementation, not a line-for-line port.

Early alpha (v0.0.1-alpha), not recommended for production. Expect breaking changes, incomplete features, and limited real-world validation.

Capabilities

• Transparent TCP/UDP: LAN-forwarded and host-originated traffic through TC eBPF, dae0/daens, and compiled routing on Linux 6.12+.
• Outbounds: SOCKS5, Shadowsocks/2022, Trojan, AnyTLS, Hysteria2, TUIC, Juicity, VMess, and VLESS, plus built-in direct and block. VMess is TCP-only; protocol-specific limits are in the node reference.
• Groups: Selector, URLTest, LoadBalance, Fallback, and Score. Score uses business observations and bounded validation; select it with policy: score. Omitted policy remains Selector. See the group reference.
• DNS: UDP, TCP, DoT, DoH, DoQ, and DoH3 upstreams, optionally through a node or group, with routing and caching.
• Configuration and control: dae syntax, subscriptions, reload, a Clash-compatible REST/WebSocket API, and the honk-tool CLI toolbox.

Implemented does not mean fully reviewed; see review status. There is no FakeIP engine, full mihomo parity, or Windows/macOS datapath.

Getting started

Real transparent proxying requires root, Linux 6.12+, the required kernel options, and bpffs. Initial deployment changes network hooks, namespaces, and sysctls; keep an out-of-band management path available.

1. Follow the startup guide for kernel checks, installation, a direct-only configuration, and connectivity verification.
2. Download a matching binary from Releases, or follow the guide's source-build prerequisites. Release binaries embed the eBPF object; source builds require the ebpf feature. Plain cargo build --release does not enable the real datapath.
3. Add nodes, groups, routing, and DNS using the configuration guide. The repository provides full and minimal development examples; adapt interfaces and node addresses before use.

The documentation index links all bilingual guides, references, and subsystem designs. Start with the architecture overview, node reference, or API reference for details.

Operational notes

• UDP NFQUEUE is enabled by default: it holds ambiguous LAN-forwarded first packets before conntrack/NAT. Set global.nfqueue_enable: false to disable it; changing this setting requires a restart. Mock mode, builds without ebpf, or an unavailable queue disable staging for that process with a warning. honk exclusively owns queue 320 and nftables inet honk_nfqueue / udp_decision; same-namespace firewall managers must not modify them. See the NFQUEUE design.
• VLESS upgrade: vless_mode is removed and all VLESS node IDs are re-derived. Migrate static links and cached/provider content before upgrading, especially offline; keep usable name-based Selector choices and persisted delay samples. UDP permission, packet encoding, and multiplexing are independent settings. See the migration guide and VLESS design.

Development

The workspace contains configuration, shared eBPF types, NFQUEUE, outbound, core, and tooling crates. The kernel program in crates/honk-ebpf is built separately. Build prerequisites and commands are in the startup guide and Justfile.

For unprivileged userspace development, use mock mode. --mock-ebpf does not intercept traffic and is not a datapath test.

Debug builds

Maintainer debug.* tags update the rolling Debug prerelease, not Latest. These are release-profile binaries, not Cargo debug-profile builds. The rolling tag and assets are replaced; source tags remain, and release notes record the source commit and workflow run. Pending intermediate runs may be superseded.

Publication requires all eight expected archives to be present and nonempty. If artifacts have expired or been deleted, use Re-run all jobs. Publication is not transactional; a failed update may leave the tag, notes, and assets inconsistent until recovery.

Review status

Most userspace subsystems were largely AI-authored with partial maintainer review; the maintainer's primary focus is eBPF. These checkboxes record maintainer review, not feature availability:

• eBPF routing, maps, and semantics
• Control plane
• AnyTLS / Shadowsocks (including 2022) / SOCKS5
• RPRX (VLESS / XTLS / XHTTP / WSS / REALITY) exclude XHTTP
• Trojan-GFW (needs UoT implementation)
• DNS logic
• Configuration parser (dae extensions)
• Reload logic
• Tooling

No test.1 release tag will be published until all currently unreviewed code has been reviewed and any unverified AI-generated implementation has been addressed.

TODO

• Evaluate AF_XDP and XDP paths for further performance gains
• Add a honk-specific REST API beyond Clash compatibility
• Add inbound support

Track other work in Issues and Discussions.

Acknowledgments

• dae / daed-rs — eBPF transparent proxy lineage
• sing-box — outbound group and Clash API patterns
• daeuniverse/outbound — protocol reference
• juicity-rs by Markson Pigeonzilla Plus — Juicity protocol reference, wire-format alignment, and live interop testing
• aya-rs — Rust eBPF

License

SPDX-License-Identifier: GPL-3.0-only
Copyright (c) 2025, glassyiris <honk@catmint.cc> and honk contributors

The development-only dae parser oracle links dae (AGPL-3.0-only). It is never shipped or linked into honk-core.