User Guide
This guide is for the people who deploy and operate the software. It covers two programs that share one proxy kernel.
etemenanki-app
Section titled “etemenanki-app”A standalone proxy in the spirit of Xray, driven by a single TOML file.
- Inbounds accept client connections: SOCKS 4/4a/5, HTTP, Shadowsocks (AEAD and 2022), Trojan, VLESS, VMess, Hysteria 2, and a TUN device.
- Outbounds carry each connection onwards: direct (
freedom),blackhole, the same proxy protocols acting as clients, and WireGuard. - Routing picks an outbound for every flow with first-match rules over domains, IP ranges, ports, network, source address and inbound tag. UDP is routed packet by packet.
- The configuration is strict. Unknown keys and unknown values are errors, so a typo stops the proxy instead of silently changing what it does.
etemenanki-app --test -c config.tomlchecks a file without starting anything.
katana
Section titled “katana”An XrayR-compatible node agent for proxy panels.
- It talks to Xboard / V2board through the UniProxy API, or to SSPanel through mod_mu.
- The panel decides the node’s protocol (VMess, VLESS, Trojan, Shadowsocks or Hysteria 2), its port and transport, and its users. katana’s own file says how to reach the panel and holds everything local: certificates, outbounds, routing and limits.
- It enforces per-user speed limits, refuses destinations that match audit rules, and reports each user’s traffic back to the panel.
- One process can serve many nodes, each with its own panel connection.
Which one do I need?
Section titled “Which one do I need?”| You want to… | Run |
|---|---|
| Run your own proxy server or client from a config file | etemenanki-app |
| Serve nodes whose users and settings are managed in a panel | katana |
| Check that an upstream, such as a WireGuard endpoint, really passes traffic, without touching a production node | etemenanki-app, as a throwaway local SOCKS proxy |
Where to go next
Section titled “Where to go next”InstallGet etemenanki-app and katana onto a server, prebuilt or from source.
Your first proxyA working etemenanki-app in five minutes, then a routing rule.
The etemenanki-app configuration fileHow the TOML file is organised and validated, and where each part is explained.
katanaWhat the panel decides, what your file decides, and how a node runs.
RecipesComplete, checked configurations for common setups.
ReferenceEvery configuration key, the command line and error messages.
Conventions in this guide
Section titled “Conventions in this guide”- Configuration snippets are TOML, with keys spelled exactly as the programs expect them.
- Addresses, keys, passwords and UUIDs in examples are placeholders:
example.com,192.0.2.0/24,2001:db8::/32and obviously fake keys. Replace them with your own values. - Complete example files are checked with the programs’
--testmode before they are published.