Glossary
This page defines the words the rest of the guide relies on, in alphabetical order. Each entry is one or two sentences and links to the page that explains the subject in full. Some words mean slightly different things in etemenanki-app and in katana; where they do, the entry says so.
The term in parentheses after each headword is the one the Chinese pages use. Where it repeats the English word, as in generation（一代实例）, the Chinese pages keep the English word and add the gloss the first time it appears. “Kept in English” marks names that are never translated. The full list is in Chinese terminology at the end.
How the terms fit together
Section titled “How the terms fit together”Most of the vocabulary names a stage on the path a client connection takes through the proxy. The three stages marked katana exist only there; in etemenanki-app a flow goes straight from the inbound to the router, and from the router to the outbound.
flowchart LR C["Client"] --> L["Listener and transport"] L --> I["Inbound: protocol core"] I --> F["Flow, maybe sniffed"] F --> A["katana: admission"] A --> R["Router: rules, geodata"] R --> AU["katana: audit rules"] AU --> M["katana: meter"] M --> O["Outbound or balancer"] O --> D["Destination"]
Address family
Section titled “Address family”The address family (地址族) of an outbound, set with address_family, decides which IP versions it may use when it resolves a name and in which order it tries them: auto (the default), ipv4_only, ipv6_only, prefer_ipv4 or prefer_ipv6. For freedom it applies to each destination, for wireguard to destinations inside the tunnel, and for a proxy outbound to its server name. See address_family.
Admission
Section titled “Admission”Admission (准入) is katana’s check, made for every flow before it is routed, that the flow’s user is still in the node’s current user list. A user the panel has removed is refused here; an admitted flow receives the user’s lease and traffic counter. See How katana works.
Audit rule
Section titled “Audit rule”An audit rule (审计规则) is a regular expression katana tests against the host each flow asks for. A match refuses the flow and records a hit against the user. Rules come from the panel and from a local rule_list_path file. Hits on the panel’s own rules are reported to SSPanel, which keeps a detection log; hits on local rules, and every hit on Xboard or V2board, are not reported. See Destination audit.
Backpressure
Section titled “Backpressure”Backpressure (背压) is how a slow receiver slows down the sender. The per-connection runtime works with fixed-size buffers: while one side of a connection is not accepting data, it stops reading from the other side, so the sender waits instead of the proxy buffering more and more. The same holds for each flow inside a WireGuard outbound’s shared tunnel: the tunnel queues only a bounded amount per flow, so a flow whose destination stops reading makes only its own sender wait, and the other flows in the tunnel keep moving. The developer guide describes the mechanism.
Balancer
Section titled “Balancer”A balancer (负载均衡器), [[balancer]] in etemenanki-app, groups several outbounds under one tag that works wherever an outbound tag does. A TCP connect probe checks each member, every 30 seconds by default; failover picks the first healthy member, round_robin takes healthy members in turn, and when every member is down the first one is used. katana has no balancers. See Balancers.
Blackhole and block
Section titled “Blackhole and block”blackhole, also accepted as block, is the outbound that discards traffic, typically as the target of a blocking rule. The two programs treat TCP differently: etemenanki-app answers the client with success and then ends the stream without data, while katana refuses the flow before anything is dialed. Both drop UDP packets without an answer. See freedom and blackhole and katana routing.
Carrier connection
Section titled “Carrier connection”A carrier connection (承载连接) is the one client connection that carries a mux.cool session. Its own destination, v1.mux.cool:0, is a marker that is never dialed, and closing the carrier ends all of its sub-flows. See Mux and XUDP.
Circuit
Section titled “Circuit”A circuit (kept in English) is one proxied TCP stream or UDP association inside a Hysteria 2 QUIC connection. The client authenticates once per QUIC connection and then opens circuits on it; max_circuits caps them per listener. See Connection and circuit limits.
A codec (kept in English) is the client half of a proxy protocol: it writes the handshake to an upstream server, wraps outgoing data and unwraps what comes back. The socks, http, shadowsocks, trojan, vless and vmess outbounds are codecs running over a transport. See the developer guide.
Configuration check
Section titled “Configuration check”The configuration check (配置检查), --test, loads and builds a configuration without binding any port or contacting a panel, then prints Configuration OK. (etemenanki-app) or Configuration OK (katana), or the first error it finds. Problems that only appear at bind time, such as a port already in use, are not caught. See Command line.
Connector
Section titled “Connector”A connector (connector（连接器）) is what a protocol core calls when it needs an outbound connection for a flow. In etemenanki-app the connector routes the flow and asks the chosen outbound to dial it; in katana it also admits the user, applies the audit rules and wraps the connection in the meter. See the developer guide.
A core, or protocol core (协议核心（core）), is the server half of a protocol written as a sans-I/O state machine: it is handed the client’s bytes and answers with effects such as “open this destination”, “forward these bytes” or “close”, without touching a socket itself. Most inbound protocols are cores; the SOCKS inbound is the exception, with its own driver. See the developer guide.
custom_config
Section titled “custom_config”custom_config (kept in English) is the JSON field of an SSPanel node from which katana reads the node’s port, transport, TLS setting and related options. katana reads it when the panel reports version 2021.11 or later; with disable_custom_config = true, or on an older panel, it parses the older server string instead, and a newer panel that sends an empty custom_config is an error. See SSPanel.
Datagram
Section titled “Datagram”A datagram (数据报) is one UDP packet. When it is proxied, each datagram carries its own destination address, which is why both programs route UDP packet by packet rather than once per association. See How UDP reaches an outbound.
Debt (欠额) is the negative balance of a token bucket. katana charges every transfer in full, even when it is larger than the bucket holds, and the user’s next transfers wait until the refill has paid the debt back, so the average rate holds whatever the chunk size. See Debt instead of waiting for tokens.
Default route
Section titled “Default route”The default route (默认路由) is the outbound a flow takes when no rule matches. In etemenanki-app it is [route].default, or the first [[outbound]] in the file when default is not set; in katana it is [node.route].default, which defaults to direct. See Tags and the default route.
Dialer
Section titled “Dialer”A dialer (拨号器) opens the host’s outgoing TCP connections and UDP sockets. The TCP dialer tries a destination’s addresses one after another, allows each attempt 10 seconds, and keeps the first connection that succeeds. See the developer guide.
DNS resolver
Section titled “DNS resolver”The DNS resolver (DNS 解析器) turns domain names into addresses for the outbounds. [dns] selects the backend, system (the host resolver, the default), udp, tls (DNS over TLS) or https (DNS over HTTPS), and answers are cached. etemenanki-app builds one resolver per generation; katana shares one among all nodes. See DNS.
An ETag (kept in English) is the version marker a panel sends with a response. katana sends the last one back in If-None-Match, and a 304 Not Modified answer tells it that nothing changed, so it keeps what it already has. See ETags.
Fail closed
Section titled “Fail closed”To fail closed (fail closed（出错即拒绝）) is to refuse when something is wrong or unknown, instead of falling back to a permissive default. Both programs reject unknown keys, and unknown values for settings such as protocol, network and security, so a typo stops the configuration from loading rather than, for example, turning TLS off; katana also refuses a node that asks for a feature it does not implement. See Strict by design.
A flow (流) is one proxied request and the unit that routing, admission and metering work on: a TCP request, a sub-flow inside mux.cool, a UDP association or a Hysteria 2 stream. It carries the destination, the authenticated user, the client’s address and any sniffed domain. See Routing.
Freedom and direct
Section titled “Freedom and direct”freedom, also accepted as direct, is the outbound that connects from this host straight to the flow’s destination, resolving names with the DNS resolver. In katana both names are built into the outbound pool. See freedom and blackhole.
Generation
Section titled “Generation”A generation (generation（一代实例）) is everything etemenanki-app runs for one version of its configuration: the listeners and their accept loops, the router, the balancer probes and the DNS resolver. A reload builds and checks a new generation first, then stops the old one, which ends all of its connections, and starts the new one. katana does not swap its whole state this way; it rebuilds one node’s listener at a time, and only when a change needs it. See Hot reload.
Geodata
Section titled “Geodata”Geodata (地理数据) are the v2ray-format geoip.dat and geosite.dat files. A geoip code matches destination IP addresses in a list, !code those outside it; a geosite code matches a list of domains, and code@attr keeps only the entries with that attribute. Codes are case-insensitive, the file paths go in [route] or [node.route], and only the referenced codes are loaded. See Routing.
Handshake
Section titled “Handshake”A handshake (握手) is the exchange that opens a connection before any payload moves. On the TCP-based inbounds there are two layers, the transport handshake (TLS, the WebSocket upgrade, the HTTP/2 preface of gRPC) and the protocol handshake in which the client authenticates and names its destination, and each must finish within 10 seconds. See Limits.
Hot reload
Section titled “Hot reload”Hot reload (热重载) applies an edited configuration file without restarting the process; both programs watch the directory that holds the file. etemenanki-app replaces the whole generation when the file’s bytes change, which drops every connection, while katana applies only the difference, so many edits leave connections open. A file that fails to parse or build is logged, and the running configuration stays in place. In etemenanki-app the old generation is already stopped when the new one binds its ports, so an inbound whose port cannot be bound at that point is logged and stays down while the others serve. See Hot reload and katana hot reload.
Inbound
Section titled “Inbound”An inbound (入站) accepts client connections: a listener, a protocol (socks, http, shadowsocks, trojan, vless, vmess, hysteria2 or tun) and, for some protocols, a transport. In etemenanki-app you write each [[inbound]] yourself; in katana the panel’s description of the node plays that role. See Inbounds.
A lease (租约) is katana’s per-user handle for ending that user’s connections. When katana removes a user at a refresh, or the user’s credential moves to another user ID, it cancels the lease and every open connection of that user ends; users who stay keep their lease, and their connections survive the refresh. See What a user refresh keeps.
Leftover traffic
Section titled “Leftover traffic”Leftover traffic (遗留流量) is bytes counted for a user who has left the node’s user list, or on a counter that katana replaced after a speed-limit change. katana keeps these bytes and reports them in later cycles, merged into the same row by user ID, so no traffic is lost. See When users leave, change or come back.
Listener
Section titled “Listener”A listener (监听器) is the bound socket an inbound accepts connections on: a TCP port, a Unix socket path, or a UDP port for Hysteria 2. A tun inbound has no listener, because it owns a network device instead; katana runs one listener per node. See Inbounds.
Masquerade
Section titled “Masquerade”The masquerade (masquerade（伪装响应）) is the fixed HTTP/3 response a Hysteria 2 inbound gives to every request that is not a valid authentication, a wrong credential included. By default it is a plain 404 page not found. See Masquerade.
Matcher
Section titled “Matcher”A matcher (匹配条件) is one condition key inside a routing rule, such as domain_suffix, cidr, port, geosite or inbound_tag. A rule matches when any entry of any of its matchers matches; there is no way to require two conditions at once. See Routing.
The meter (计量器) is the wrapper katana puts around every outbound connection. It counts the user’s upload and download bytes for traffic accounting and paces them with the user’s token bucket. See How the limit is enforced.
mod_mu
Section titled “mod_mu”mod_mu (kept in English) is SSPanel’s node API, under /mod_mu/. With panel_type = "SSpanel", katana uses it to fetch node information, users and audit rules, and to post traffic and audit hits. See SSPanel.
mux.cool
Section titled “mux.cool”mux.cool (kept in English) is Xray’s multiplexing protocol, which carries many sub-flows over one VLESS, VMess or Trojan connection. Inbounds accept it automatically, up to 256 sub-flows per carrier; outbounds never send it. See Mux and XUDP.
A node (节点) is one proxy server entry in a panel, identified by its node ID. katana serves each [[node]] in its file with its own panel connection, listener and routing table. The file sets the node’s type, and the panel decides its port, transport, TLS setting and users (a Hysteria 2 node can take its port from [node.hysteria] instead). A node that cannot come up, for example because the panel is unreachable or the port is still taken, keeps trying: katana waits 1 second after the first failure and doubles the wait up to 60 seconds, or update_periodic if that is shorter, and an edit to the node’s entry retries at once. See Nodes and When a node fails to start.
Node identity
Section titled “Node identity”A node identity (节点身份) is the set of values that name the panel node a [[node]] entry serves: panel_type, api.host, api.node_id, api.key and, on NewV2board and V2board, the node type katana asks the panel for (vless when enable_vless = true on a V2ray, Vmess or Vless node, otherwise node_type in lowercase). Changing any of them in the file replaces the node with a fresh one instead of updating it. Every other edit reaches the running node, including the remaining [node.api] keys such as api.timeout, and an edit to [node.api] gives the node a new panel client. See Node identity.
Node tag
Section titled “Node tag”A node tag (节点 tag) is the name katana uses for a node in some log lines and to keep each node’s audit rules and hits apart: the node type, the listen address and the port, joined by underscores, for example V2ray_0.0.0.0_443. Because it contains the port, it changes when the panel moves the node to another port. See Nodes.
Node type
Section titled “Node type”The node type (节点类型), node_type in [node.api], tells katana what kind of node the panel describes: V2ray (VMess, or VLESS with enable_vless = true), Trojan, Shadowsocks or Hysteria2. It is compared case-insensitively, and vmess, vless, hysteria and hy2 are accepted as aliases; vless alone does not switch on VLESS. SSPanel nodes cannot be Shadowsocks. See Protocols.
Outbound
Section titled “Outbound”An outbound (出站) is where a flow leaves the proxy. freedom connects directly, blackhole discards, a proxy protocol relays through an upstream server, and wireguard sends through a WireGuard tunnel; each [[outbound]] has a tag that routing refers to. See Outbounds and, for the protocols katana offers, katana outbounds.
Outbound pool
Section titled “Outbound pool”The outbound pool (出站池) is the set of outbounds every katana node can route to: the built-in direct, freedom, block and blackhole, plus each top-level [[outbound]]. All nodes share one pool, and editing any [[outbound]] rebuilds it together with every node’s listener. See katana outbounds.
A panel (面板) is the web application that manages users, plans and nodes, such as Xboard, V2board or SSPanel. katana polls it for node settings and users and reports traffic back to it, over UniProxy or mod_mu. See Supported panels.
Permit
Section titled “Permit”A permit (许可（permit）) is one slot of a fixed-size limit, held for as long as the thing it counts exists. A stream inbound (one that accepts TCP or Unix-socket connections) allows 65,536 live connections, each holding its permit from accept until it closes, and 2,048 connections still in their handshake; a katana listener has the same two limits and adds 512 pre-authentication permits. Hysteria 2 and TUN inbounds have their own limits. See Limits and Connection guardrails.
Placeholder
Section titled “Placeholder”A placeholder (占位值) is an obviously fake value in an example, such as example.com, an address from 192.0.2.0/24, the UUID 11111111-2222-3333-4444-555555555555 or the password replace-with-a-long-random-password. The guide picks placeholders that the parser accepts, so --test checks the rest of the file, but you must replace each one before you put the configuration into service. See the full example in Configuration file and the katana quick start.
Poll cycle
Section titled “Poll cycle”The poll cycle (轮询周期) is katana’s control loop for one node. Every update_periodic seconds (default 60) the node fetches its settings and users from the panel, applies any change, refreshes its audit rules, and reports traffic and audit hits. An accepted edit to the node’s [node.api] keys, or to a local setting its listener is built from, such as listen_ip, the certificate or the route, runs one cycle at once instead of waiting for the timer. See The poll cycle.
Pre-shared key
Section titled “Pre-shared key”A pre-shared key (预共享密钥) is a secret both ends know in advance. Shadowsocks 2022 methods take base64 keys of the cipher’s key length, 16 or 32 bytes, and a shorter key is an error (generate one with openssl rand -base64 32, or 16 for the AES-128 method). A WireGuard outbound can add an optional preshared_key (pre_shared_key in katana). See Generating keys.
Rate limiting
Section titled “Rate limiting”Rate limiting (速率限制) is pacing traffic to a fixed rate. In this guide it is the mechanism behind katana’s speed limits: a token bucket per user on each node, shared by all of that user’s flows there. See Speed limits.
REALITY and XTLS
Section titled “REALITY and XTLS”REALITY and XTLS (both kept in English) are Xray features that neither program implements: the REALITY handshake and the XTLS flow modes such as Vision. etemenanki-app has no keys for them, and katana refuses a node whose panel settings turn on REALITY or set an XTLS flow. See Migrating from Xray.
The relay (中继) is the stage after the handshake, in which the proxy copies bytes between the client and the outbound in both directions until the connection ends. Payload reaches the destination only from this stage on; everything before it is handshake, sniffing, routing and dialing. See Limits.
Routing
Section titled “Routing”Routing (路由) picks an outbound for each flow. Rules (规则) are checked in the order they are written and the first one that matches wins; a flow that matches none takes the default route. A TCP flow is routed once, when it opens, and a UDP association packet by packet. See Routing and katana routing.
Runtime
Section titled “Runtime”The runtime (运行时) is the driver that runs one proxied connection as a single task. It reads the client’s transport, hands the bytes to the protocol core, carries out the effects the core returns, and owns every outbound connection the core opens. See the developer guide.
Salamander
Section titled “Salamander”Salamander (Salamander 混淆) is the Hysteria 2 obfuscation turned on with obfs = "salamander". Every QUIC packet is XORed with a keystream derived from obfs_password and a random per-packet salt, so the traffic no longer looks like QUIC; it hides the protocol but adds no encryption. See Obfuscation (Salamander).
Sans-I/O
Section titled “Sans-I/O”Sans-I/O (kept in English) describes protocol code that performs no input or output: it consumes bytes and returns decisions, while a separate runtime owns the sockets and timers. The kernel’s protocol cores and codecs are written this way, so each can be tested byte by byte without a network. See the developer guide.
Sniffing
Section titled “Sniffing”Sniffing (嗅探) reads a domain name from the first bytes of a flow that was addressed by IP: the SNI of a TLS ClientHello or the Host header of an HTTP request. Domain and geosite rules then match that name too, but the flow is still dialed to the original address. It waits at most 300 ms and reads at most 4 KiB, and it is on by default. See Sniffing and katana sniffing.
Speed limit
Section titled “Speed limit”A speed limit (限速) is a user’s bandwidth cap, in megabits per second, set by the panel for each user and, on SSPanel, also for the node; katana applies the smaller non-zero one and converts 1 Mbps to 125,000 bytes per second. [node.api].speed_limit replaces every panel limit on that node. See Speed limits.
Stream settings and transport
Section titled “Stream settings and transport”The stream settings (stream 设置), the [inbound.stream] and [outbound.stream] tables, choose the transport (传输层) a protocol runs over: tcp, tls, ws (WebSocket) or grpc, with security = "tls" adding TLS under WebSocket or gRPC. On inbounds only http, trojan, vless and vmess accept a transport; katana takes the transport from the panel. See Transports.
Sub-flow
Section titled “Sub-flow”A sub-flow (子流) is one flow inside a mux.cool carrier: a TCP stream, or with XUDP a UDP session, with its own destination. Each sub-flow is routed and sniffed on its own and, in katana, audited and metered on its own. See Mux and XUDP.
A tag (kept in English) is the name of an inbound, outbound or balancer, used by rules, by default and in log lines. Tags are compared exactly, including case; inbound tags must be unique among inbounds, and outbounds and balancers share one set of tags. See Tags and the default route.
Token bucket
Section titled “Token bucket”A token bucket (令牌桶) is katana’s per-user rate limiter. It refills at the user’s speed limit, holds at most one second of that rate, and is shared by all of the user’s flows on that node, in both directions; a transfer larger than the balance runs the bucket into debt. See One bucket per user.
Traffic accounting
Section titled “Traffic accounting”Traffic accounting (流量计费) is katana’s counting of each user’s upload and download bytes. The meter counts the plain payload on the outbound side, after the inbound protocol’s framing is removed, so protocol and transport overhead is not billed, and a refused flow costs nothing. See What is counted.
Traffic reporting
Section titled “Traffic reporting”Traffic reporting (流量上报) sends the counted bytes to the panel once per poll cycle, one row per user ID. On success katana subtracts exactly what it reported; on failure it keeps the bytes and sends them with the next report. See Traffic reporting.
A TUN inbound (kept in English), protocol = "tun", creates a layer-3 network interface and turns the TCP connections and UDP packets the host routes into it into flows. It exists only in etemenanki-app. See TUN.
UDP association
Section titled “UDP association”A UDP association (UDP 关联) is one client’s UDP session through an inbound: a SOCKS5 UDP ASSOCIATE, a UDP request over VLESS, VMess or Trojan, an XUDP sub-flow, or a Hysteria 2 UDP session. It has no single destination, so each packet is routed on its own address, and an association keeps one link per outbound it has routed to, at most 64 at a time. See How UDP reaches an outbound.
UniProxy
Section titled “UniProxy”UniProxy (kept in English) is the node API of Xboard and V2board, under /api/v1/server/UniProxy/. With panel_type = "NewV2board" or "V2board", katana calls config for the node’s settings, user for its users and push to report traffic. See Xboard and V2board.
Xray-core and XrayR
Section titled “Xray-core and XrayR”Xray-core is the Go proxy whose protocols and configuration model etemenanki-app follows, and XrayR is the Go panel node agent that katana is modelled on; both names are kept in English. Neither program reads their configuration files, which are JSON and YAML; both use TOML. See Migrating from Xray and Migrating from XrayR.
XUDP (kept in English) is the mux.cool extension that lets a UDP sub-flow carry a destination address with every packet, so one sub-flow can talk to several peers. Inbounds accept it; the XUDP global ID is read but not used to resume a session on a new connection. See Mux and XUDP.
Chinese terminology
Section titled “Chinese terminology”The Chinese pages translate every term in the table below exactly as shown, so that one idea always has one name. Configuration keys, values, command-line flags, type names, file paths, error messages and log lines are never translated.
| English | 中文 | Note |
|---|---|---|
| address family | 地址族 | |
| admission | 准入 | |
| audit (rule) | 审计（规则） | |
| backpressure | 背压 | |
| balancer | 负载均衡器 | |
| cancellation | 取消 | |
| carrier connection | 承载连接 | |
| certificate, private key | 证书，私钥 | |
| circuit | circuit | kept in English |
| codec | codec | kept in English |
| configuration check | 配置检查 | |
| connector | connector（连接器） | English word plus gloss |
| core (protocol core) | 协议核心（core） | |
| datagram | 数据报 | |
| debt | 欠额 | |
| default route | 默认路由 | |
| dialer | 拨号器 | |
| DNS resolver | DNS 解析器 | |
| fail closed | fail closed（出错即拒绝） | English phrase plus gloss |
| flow | 流 | |
| generation | generation（一代实例） | English word plus gloss |
| geodata | 地理数据 | geoip and geosite are kept |
| handshake | 握手 | |
| hot reload | 热重载 | |
| inbound / outbound | 入站 / 出站 | |
| invariant | 不变量 | |
| lease | 租约 | |
| leftover traffic | 遗留流量 | |
| listener | 监听器 | |
| masquerade | masquerade（伪装响应） | English word plus gloss |
| matcher | 匹配条件 | |
| meter | 计量器 | |
| node identity | 节点身份 | |
| node tag | 节点 tag | |
| node type | 节点类型 | |
| obfuscation | 混淆 | |
| outbound pool | 出站池 | |
| panel, node | 面板，节点 | |
| permit (semaphore) | 许可（permit） | |
| placeholder | 占位值 | |
| poll cycle | 轮询周期 | |
| pre-shared key | 预共享密钥 | |
| rate limiting | 速率限制 | |
| relay | 中继 | |
| routing, rule, matcher | 路由，规则，匹配条件 | |
| runtime | 运行时 | |
| sniffing | 嗅探 | |
| speed limit | 限速 | |
| sub-flow | 子流 | |
| tag | tag | kept in English |
| token bucket | 令牌桶 | |
| traffic accounting | 流量计费 | |
| traffic reporting | 流量上报 | |
| transport, stream settings | 传输层，stream 设置 | |
| UDP association | UDP 关联 | |
| user table | 用户表 |
These names are always kept in English: ETag, mod_mu, mux.cool, REALITY, Salamander, sans-I/O, SSPanel, TUN, UniProxy, V2board, Xboard, Xray-core, XrayR, XTLS and XUDP.