Install

This page covers installing the two programs on a Linux host: etemenanki-app, the standalone proxy, and katana, the panel node agent. You can download a prebuilt x86_64 binary or build either one from source. At the end you have the binary in /usr/local/bin, a directory under /etc for its configuration, and a binary that reports its version.

Each program is a single executable. There is no installer and no service unit. Neither program keeps state on disk: the only file either one creates is the socket of an etemenanki-app inbound that you configure to listen on a Unix socket path. So the only directory you need to create is the one that holds your configuration.

Choose a build

	etemenanki-app	katana
Prebuilt binary	Artifact of the Build CI workflow (x86_64 Linux, glibc)	Release assets -gnu and -musl (x86_64 Linux), each with a .sha256 file
Build from source	Needs only the Etemenanki repository	Needs the katana repository and read access to a private Cargo registry
OpenSSL at run time	The CI build links the system libssl.so.3	Built in; neither release asset loads a system OpenSSL
Hysteria 2	Always compiled in	Always compiled in (Hysteria 2 nodes; katana has no Hysteria 2 outbound)
TUN inbound	Always compiled in	Not compiled in; katana has no TUN inbound

If you are only trying the software out, the prebuilt binary is the shortest path. Build from source when you need another CPU architecture, an etemenanki-app without a system OpenSSL, or a revision that has no prebuilt binary.

Supported platforms

Program	Operating systems	Prebuilt	Notes
etemenanki-app	Linux. CI builds for no other operating system.	x86_64 Linux	Unix only: the listener code uses Unix sockets unconditionally, so it does not compile on Windows. The TUN inbound installs routes only on Linux; elsewhere a non-empty routes list fails with tun routes are installed only on Linux; add them with the OS route tool.
katana	Linux	x86_64 Linux, -gnu and -musl	The release workflow builds no other platform or architecture.

The prebuilt glibc binaries (etemenanki-app, and katana -gnu) are compiled on Ubuntu 22.04 against glibc 2.35. A host with glibc 2.35 or newer runs them; on an older glibc they may fail to start with a version `GLIBC_2.xx' not found error. The katana -musl binary has no glibc requirement.

Install a prebuilt binary

etemenanki-app

etemenanki-app has no tagged releases. The Build workflow in the Etemenanki repository compiles etemenanki-app for x86_64-unknown-linux-gnu on every push to main, and also for every pull request, and uploads it as a workflow artifact named etemenanki-app. Take the artifact from a run on main, not from a pull-request run. You need read access to the repository to download it.

1. Open the most recent successful Build run on main and download the etemenanki-app artifact. GitHub packs artifacts into a zip file and does not keep the executable bit, so unpack it first:

   unzip etemenanki-app.zip

   With the GitHub CLI, look up the latest successful Build run on main and download its artifact. gh run download unpacks the zip for you, but the executable bit is still lost:

   RUN_ID=$(gh run list --repo OWNER/Etemenanki --workflow Build --branch main \
     --status success --limit 1 --json databaseId --jq '.[0].databaseId')
   gh run download "$RUN_ID" --repo OWNER/Etemenanki --name etemenanki-app

2. The CI binary loads OpenSSL 3 (libssl.so.3) from the system. On Debian 12 and Ubuntu 22.04 it lives in the libssl3 package, and on Debian 13 and Ubuntu 24.04 in libssl3t64. Most installations already have it:

   sudo apt-get install -y libssl3   # libssl3t64 on Debian 13 and Ubuntu 24.04

3. Install the binary. install -m 0755 sets the executable bit that the zip lost:

   sudo install -m 0755 etemenanki-app /usr/local/bin/etemenanki-app

4. Check that it runs:

   etemenanki-app --version

   etemenanki-app 2.0.0

Note

The workflow publishes no checksum file for the artifact, and artifacts expire after the repository’s artifact retention period. If you need a binary you can verify and keep, build it from source.

katana

Every v* tag of the katana repository produces a release with four assets. VERSION below is the tag, for example v3.0.1.

Asset	What it is
katana-VERSION-linux-x86_64-gnu	Dynamically linked against glibc. OpenSSL is compiled in; the release job fails if the binary links libssl or libcrypto dynamically.
katana-VERSION-linux-x86_64-gnu.sha256	SHA-256 checksum of the file above.
katana-VERSION-linux-x86_64-musl	Fully static: no program interpreter and no shared-library dependencies. Runs on any x86_64 Linux, including Alpine.
katana-VERSION-linux-x86_64-musl.sha256	SHA-256 checksum of the file above.

Both assets are built from the same source with the same features. Pick -musl on Alpine, on a host whose glibc is older than 2.35, or when you want a binary with no run-time library dependencies. Pick -gnu if you rely on glibc behaviour, for example name resolution through NSS modules configured in /etc/nsswitch.conf: katana’s default system DNS backend calls the C library’s getaddrinfo, and musl’s version reads /etc/hosts and /etc/resolv.conf directly instead of loading NSS modules.

The assets are plain executables, not archives.

1. Download the binary and its checksum file into the same directory. From the release page, or with the GitHub CLI (you need read access to the repository):

   VERSION=v3.0.1
   gh release download "$VERSION" --repo OWNER/katana \
     --pattern "katana-$VERSION-linux-x86_64-musl*"

2. Verify the checksum. The .sha256 file names the asset by its original file name, so run the check in the download directory before you rename anything:

   sha256sum -c "katana-$VERSION-linux-x86_64-musl.sha256"

   katana-v3.0.1-linux-x86_64-musl: OK

   Anything other than OK means the download is incomplete or damaged. Download it again; do not install it.

3. Install it under the name katana:

   sudo install -m 0755 "katana-$VERSION-linux-x86_64-musl" /usr/local/bin/katana

4. Check that it runs:

   katana --version

   katana 3.0.1

Note

The checksum files are produced by the same CI job as the binaries and published next to them. They detect a truncated or corrupted download; they do not prove who built the file.

Upgrading in place

Use install, not cp, to replace a binary that is running. install removes the old file and writes a new one, so the running process keeps its copy until you restart it. cp tries to overwrite the running file in place and fails with Text file busy.

Build from source

Toolchain

Both programs use Rust edition 2024 and pin no toolchain. Use the current stable Rust from rustup. The locked dependencies need Rust 1.91 or newer (the WireGuard netstack, smoltcp 0.13, declares that minimum). With an older compiler Cargo stops before compiling anything, with an error that the installed rustc is not supported by the locked packages; the list includes smoltcp@0.13.1 requires rustc 1.91. Update with:

rustup update stable

Both projects set lto = true in their release profile, so a release build takes several minutes and a good deal of memory. Build with --locked so Cargo uses exactly the dependency versions in Cargo.lock and stops instead of changing them.

etemenanki-app

etemenanki-app builds from the Etemenanki repository alone. Its kernel crates (etemenanki-concepts, etemenanki-environment, etemenanki-protocols) are path dependencies inside the same workspace, and every other locked dependency comes from crates.io, so no registry credentials are needed.

Hysteria 2 and the TUN inbound are always compiled in: app/Cargo.toml enables the hysteria and tun features of etemenanki-protocols, and there is nothing to switch on.

TLS for every TCP transport (tls, and ws or grpc with TLS) comes from OpenSSL. Hysteria 2 is the exception: its QUIC stack uses rustls. You can link the system’s OpenSSL (the default, and what CI does) or compile a private copy into the binary.

1. Install the build dependencies. On Debian and Ubuntu:

   # system OpenSSL (default)
   sudo apt-get install -y build-essential pkg-config libssl-dev

   # vendored OpenSSL instead: no libssl-dev needed, but OpenSSL's own build needs perl and make
   sudo apt-get install -y build-essential perl make

   A C compiler is needed either way: some dependencies compile C code of their own, for example ring, the cryptography library under the Hysteria 2 QUIC stack.

2. From the root of the Etemenanki checkout, build the etemenanki-app package:

   # links the system libssl.so.3
   cargo build --release --locked -p etemenanki-app

   # compiles OpenSSL into the binary
   cargo build --release --locked -p etemenanki-app \
     --features etemenanki-protocols/vendored-openssl

   The binary is written to target/release/etemenanki-app.

3. Install it:

   sudo install -m 0755 target/release/etemenanki-app /usr/local/bin/etemenanki-app
   etemenanki-app --version

For a vendored build, ldd /usr/local/bin/etemenanki-app | grep ssl prints nothing.

Vendored OpenSSL and trusted roots

A vendored OpenSSL looks for trusted CA certificates in its compile-time directory, /usr/local/ssl, not in your distribution’s certificate store. With a vendored build, every TLS client that verifies against the system roots (a TLS outbound without ca_file, and the tls and https DNS backends without ca_file) fails certificate verification unless you point OpenSSL at the store. Set this in the service environment (the path is the Debian and Ubuntu one):

SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt

With ca_file set, verification works on either build: the file’s certificates are added to the trust store. Hysteria 2 outbounds are not affected, because rustls loads the system store itself. A build that links the system OpenSSL uses the system store and needs nothing.

katana

katana does not contain the kernel. It depends on the etemenanki-concepts, etemenanki-environment and etemenanki-protocols crates as published to a private Cargo registry, so building it needs read access to that registry as well as to the katana repository.

The katana repository’s .cargo/config.toml already declares the registry and uses Cargo’s token credential provider. Give Cargo the token you were issued, either once with cargo login --registry <name>, or per build in the CARGO_REGISTRIES_<NAME>_TOKEN environment variable, where <name> is the registry name in that file. Without access, the build stops when Cargo contacts the registry, before anything is compiled.

katana always compiles OpenSSL in (it enables etemenanki-protocols/vendored-openssl and reqwest’s vendored native-tls), so it needs no OpenSSL headers. Hysteria 2 is always compiled in.

1. Install the build dependencies. On Debian and Ubuntu:

   sudo apt-get install -y build-essential perl make

2. From the root of the katana checkout, build the glibc binary:

   cargo build --release --locked

   The binary is written to target/release/katana.

   To build the static binary the release workflow ships, add the musl target and its C toolchain:

   rustup target add x86_64-unknown-linux-musl
   sudo apt-get install -y musl-tools
   CC_x86_64_unknown_linux_musl=musl-gcc \
     cargo build --release --locked --target x86_64-unknown-linux-musl

   That binary is written to target/x86_64-unknown-linux-musl/release/katana.

3. Install it:

   sudo install -m 0755 target/release/katana /usr/local/bin/katana
   katana --version

Trusted roots for DNS over TLS and HTTPS

Because OpenSSL is compiled in, it looks for trusted CA certificates in /usr/local/ssl rather than in the system store. katana’s panel connection finds the system store on its own, and katana’s outbounds carry no TLS. The tls and https DNS backends do not find it: if you use either without ca_file, set SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt (Debian and Ubuntu path) in the service environment. This applies to the release binaries too.

Confirm the installation

Both programs accept the same options:

Flag	Meaning
-V, --version	Print the program name and version, then exit.
-h, --help	Print the options, then exit.
-c, --config <CONFIG>	Path of the TOML configuration file. Default: config.toml in the current directory.
--test	Load and build the configuration, print whether it is valid, and exit without binding any listener.

--version is the quickest check that the binary runs on this host at all: a missing shared library or a too-old glibc shows up here, before any configuration is involved. The version is the crate version the binary was built from.

etemenanki-app --version     # etemenanki-app 2.0.0
katana --version             # katana 3.0.1

--version shows only the program’s own crate version. The kernel crates (etemenanki-concepts, etemenanki-environment, etemenanki-protocols) have versions of their own, and a kernel release does not always bump etemenanki-app. An etemenanki-app built from the current release still reports 2.0.0, but it contains etemenanki-protocols 2.0.2. katana 3.0.1 is built against etemenanki-protocols 2.0.1. The two differ only in how SOCKS handles UDP associations. Most of that change is in the SOCKS inbound, which katana does not have. The rest lets a SOCKS client’s dual-stack UDP socket hear an IPv4 relay, and katana’s socks outbound binds its UDP socket in the relay’s own address family, so it does not need that. To see which kernel versions a source build contains, look them up in the Cargo.lock of the checkout you built from.

Once you have a configuration, --test is the next check. etemenanki-app prints Configuration OK. and katana prints Configuration OK when the file is valid. The next page, Your first proxy, writes a configuration and tests it.

Suggested file layout

Neither program has a built-in location for its files. etemenanki-app and katana read the configuration from -c, and every other file (certificates, CA bundles, geodata, katana’s audit rule list) from the path you write in the configuration. The layout below keeps each program’s files in one directory under /etc:

• Directoryusr/local/bin/

  • etemenanki-app
  • katana
• Directoryetc/

  • Directoryetemenanki/

    • config.toml the file you pass with -c
    • Directorycerts/

      • fullchain.pem certificate chain for TLS inbounds
      • privkey.pem private key, readable only by the service
    • geoip.dat only if rules use geoip
    • geosite.dat only if rules use geosite
  • Directorykatana/

    • config.toml
    • Directorycerts/

      • fullchain.pem
      • privkey.pem
    • geoip.dat
    • geosite.dat
    • rules.txt local audit rules, if you set rule_list_path

Use absolute paths

Neither program resolves paths relative to the configuration file. A relative path such as geoip = "geoip.dat" is opened relative to the process’s working directory, so a config that passes --test in /etc/etemenanki can fail when a service manager starts the program from /. --test then reports only configuration invalid: No such file or directory (os error 2) (etemenanki-app) or configuration error: No such file or directory (os error 2) (katana), without the file name. Write every path in the configuration as an absolute path, and pass -c an absolute path too.

A few details about these files:

• Private keys. Keep the key readable by the service’s user only, for example sudo install -m 0600 privkey.pem /etc/etemenanki/certs/, and change the owner if the service does not run as root.
• Geodata. Both programs read v2ray-format geoip.dat and geosite.dat files. The v2fly projects publish them: geoip.dat, and dlc.dat, which you save as geosite.dat. You need them only if a rule uses a geoip or geosite matcher; a rule that does, without the file configured, is a configuration error.
• Hot reload. Both programs watch the directory that contains the configuration file. etemenanki-app reloads only when the bytes of the configuration file itself change, so replacing a certificate alone does not reload it. See Hot reload.

Troubleshooting

Symptom	Cause	Fix
error while loading shared libraries: libssl.so.3: cannot open shared object file	The etemenanki-app CI binary, or a default source build, needs the system OpenSSL 3.	Install libssl3 (libssl3t64 on Debian 13 and Ubuntu 24.04), or build with --features etemenanki-protocols/vendored-openssl.
version `GLIBC_2.xx' not found	The host’s glibc is older than the one the binary was built against.	For katana, use the -musl asset. For etemenanki-app, build from source on the host.
sha256sum: katana-…: No such file or directory	The binary was renamed or saved in another directory before the check.	Keep the original name and run sha256sum -c in the directory that holds both files.
Cargo stops with smoltcp@0.13.1 requires rustc 1.91	The Rust toolchain is too old for the locked dependencies.	rustup update stable.
Could not find openssl via pkg-config or Could not find directory of OpenSSL installation	A default etemenanki-app build cannot find the OpenSSL development files.	Install pkg-config and libssl-dev, or build with the vendored OpenSSL feature.
katana’s build fails when Cargo contacts the private registry	Cargo has no token for the private registry, or the token has no access.	Set the token as described in Build from source.
configuration invalid: No such file or directory (os error 2), or katana’s configuration error: … with the same text	A relative path in the configuration, opened from a different working directory.	Use absolute paths.
TLS outbounds or DNS over TLS or HTTPS fail certificate verification with a vendored OpenSSL	The vendored OpenSSL looks for roots in /usr/local/ssl.	Set SSL_CERT_FILE, or set ca_file.

Next steps

With the binary installed, write a configuration and run it. Running the programs as a service, including privileges for low ports and TUN, is covered on Running. The katana configuration and panel setup are described in the katana section of this guide.

Your first proxyWrite a minimal etemenanki-app configuration, check it with --test and send traffic through it.

RunningRun the programs as a service, reload configuration and upgrade binaries.

Configuration fileHow etemenanki-app reads its TOML file, and what it rejects.

Hot reloadWhat changes when you edit the configuration of a running etemenanki-app.