Merge pull request #786 from Dimasssss/patch-1

Update install.sh

.github/FUNDING.yml

@@ -0,0 +1,16 @@
+# These are supported funding model platforms
+
+github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
+thanks_dev: # Replace with a single thanks.dev username
+custom:
+  - https://nowpayments.io/donation?api_key=2bf1afd2-abc2-49f9-a012-f1e715b37223

.github/workflows/build.yml

@@ -36,4 +36,10 @@ jobs:
             ${{ runner.os }}-cargo-
 
       - name: Build Release
-        run: cargo build --release --verbose
+        run: cargo build --release --verbose
+
+      - name: Upload binary artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: telemt
+          path: target/release/telemt

.github/workflows/release.yml

@@ -151,6 +151,14 @@ jobs:
           mkdir -p dist
           cp "target/${{ matrix.target }}/release/${{ env.BINARY_NAME }}" dist/telemt
 
+          if [ "${{ matrix.target }}" = "aarch64-unknown-linux-gnu" ]; then
+            STRIP_BIN=aarch64-linux-gnu-strip
+          else
+            STRIP_BIN=strip
+          fi
+
+          "${STRIP_BIN}" dist/telemt
+
           cd dist
           tar -czf "${{ matrix.asset }}.tar.gz" \
             --owner=0 --group=0 --numeric-owner \
@@ -279,6 +287,14 @@ jobs:
           mkdir -p dist
           cp "target/${{ matrix.target }}/release/${{ env.BINARY_NAME }}" dist/telemt
 
+          if [ "${{ matrix.target }}" = "aarch64-unknown-linux-musl" ]; then
+            STRIP_BIN=aarch64-linux-musl-strip
+          else
+            STRIP_BIN=strip
+          fi
+
+          "${STRIP_BIN}" dist/telemt
+
           cd dist
           tar -czf "${{ matrix.asset }}.tar.gz" \
             --owner=0 --group=0 --numeric-owner \

AGENTS.md

@@ -191,6 +191,11 @@ When facing a non-trivial modification, follow this sequence:
 4. **Implement**: Make the minimal, isolated change.
 5. **Verify**: Explain why the change preserves existing behavior and architectural integrity.
 
+When the repository contains a `PLAN.md` for the current task, maintain it as
+a working checkbox plan while implementing changes. Mark completed and partial
+items in `PLAN.md` as the code changes land, so the remaining work stays
+explicit and future passes do not waste time rediscovering status.
+
 ---
 
 ### 9. Context Awareness
@@ -222,10 +227,9 @@ Your response MUST consist of two sections:
 
 **Section 2: `## Changes`**
 
-- For each modified or created file: the filename on a separate line in backticks, followed by the code block.
-- For files **under 200 lines**: return the full file with all changes applied.
-- For files **over 200 lines**: return only the changed functions/blocks with at least 3 lines of surrounding context above and below. If the user requests the full file, provide it.
-- New files: full file content.
+- For each modified or created file: the filename on a separate line in backticks, followed by a concise description of what changed.
+- Do not include full file contents or long code blocks in `## Changes` unless the user explicitly asks for code text.
+- If code snippets are necessary, include only the minimal relevant excerpt.
 - End with a suggested git commit message in English.
 
 #### Reporting Out-of-Scope Issues
@@ -429,4 +433,3 @@ Every patch must be **atomic and production-safe**.
 * **No transitional states** — no placeholders, incomplete refactors, or temporary inconsistencies.
 
 **Invariant:** After any single patch, the repository remains fully functional and buildable.
-

CODE_OF_CONDUCT.md

@@ -3,50 +3,39 @@
 ## Purpose
 
 **Telemt exists to solve technical problems.**
+- Telemt is open to contributors who want to learn, improve and build meaningful systems together.
+- It is a place for building, testing, reasoning, documenting, and improving systems.
+- Discussions that advance this work are in scope, discussions that divert it are not.
+- Technology has consequences, responsibility is inherent.
 
-Telemt is open to contributors who want to learn, improve and build meaningful systems together.
+> **Absicht bestimmt die Form**
 
-It is a place for building, testing, reasoning, documenting, and improving systems.
-
-Discussions that advance this work are in scope. Discussions that divert it are not.
-
-Technology has consequences. Responsibility is inherent.
-
-> **Zweck bestimmt die Form.**
-
-> Purpose defines form.
+> Design follows intent
 
 ---
 
 ## Principles
 
 * **Technical over emotional**
-
-  Arguments are grounded in data, logs, reproducible cases, or clear reasoning.
+  - Arguments are grounded in data, logs, reproducible cases, or clear reasoning.
 
 * **Clarity over noise**
-
-  Communication is structured, concise, and relevant.
+  - Communication is structured, concise, and relevant.
 
 * **Openness with standards**
-
-  Participation is open. The work remains disciplined.
+  - Participation is open. The work remains disciplined.
 
 * **Independence of judgment**
-
-  Claims are evaluated on technical merit, not affiliation or posture.
+  - Claims are evaluated on technical merit, not affiliation or posture.
 
 * **Responsibility over capability**
-
-  Capability does not justify careless use.
+  - Capability does not justify careless use.
 
 * **Cooperation over friction**
-
-  Progress depends on coordination, mutual support, and honest review.
+  - Progress depends on coordination, mutual support, and honest review.
 
 * **Good intent, rigorous method**
-
-  Assume good intent, but require rigor.
+  - Assume good intent, but require rigor.
 
 > **Aussagen gelten nach ihrer Begründung.**
 
@@ -68,7 +57,9 @@ Participants are expected to:
 
 Precision is learned.
 
-New contributors are welcome. They are expected to grow into these standards. Existing contributors are expected to make that growth possible.
+- New contributors are welcome
+- They are expected to grow into these standards
+- Existing contributors are expected to make that growth possible
 
 > **Wer behauptet, belegt.**
 
@@ -112,7 +103,7 @@ Security is both technical and behavioral.
 
 ---
 
-## 6. Openness
+## Openness
 
 Telemt is open to contributors of different backgrounds, experience levels, and working styles.
 
@@ -148,10 +139,9 @@ Judgment should be exercised with restraint, consistency, and institutional resp
 
 All decisions are expected to serve the durability, clarity, and integrity of Telemt.
 
-> **Ordnung ist Voraussetzung der Funktion.**
-
-> Order is the precondition of function.
+> **Klarheit vor Zustimmung - Bestand vor Beifall**
 
+> Clarity above approval - substantiality before success
 ---
 
 ## Enforcement
@@ -171,42 +161,41 @@ Actions are taken to maintain function, continuity, and signal quality.
 
 ## Final
 
-Telemt is built on discipline, structure, and shared intent.
-- Signal over noise.
-- Facts over opinion.
-- Systems over rhetoric.
+**Telemt is built on discipline, structure, and shared intent**
+- Signal over noise
+- Facts over opinion
+- Systems over rhetoric
+- Work is collective
+- Outcomes are shared
+- Responsibility is distributed
+- Precision is learned
+- Rigor is expected
+- Help is part of the work
 
-- Work is collective.
-- Outcomes are shared.
-- Responsibility is distributed.
+> **Ordnung ist Voraussetzung der Freiheit**
 
-- Precision is learned.
-- Rigor is expected.
-- Help is part of the work.
-
-> **Ordnung ist Voraussetzung der Freiheit.**
-
-- If you contribute — contribute with care.
-- If you speak — speak with substance.
-- If you engage — engage constructively.
+- If you contribute — contribute with care
+- If you speak — speak with substance
+- If you engage — engage constructively
 
 ---
 
 ## After All
 
-Systems outlive intentions.
-- What is built will be used.
-- What is released will propagate.
-- What is maintained will define the future state.
+Systems outlive intentions
+- What is built will be used
+- What is released will propagate
+- What is maintained will define the future state
 
-There is no neutral infrastructure, only infrastructure shaped well or poorly.
+There is no neutral infrastructure, only infrastructure shaped well or poorly
 
-> **Jedes System trägt Verantwortung.**
+> **Ordnung → Umsetzung → Ergebnis**
 
-> Every system carries responsibility.
+> Order → Implementation → Result
 
-- Stability requires discipline.
-- Freedom requires structure.
-- Trust requires honesty.
+- Stability requires discipline
+- Freedom requires structure
+- Trust requires honesty
+
+In the end: the system reflects its contributors
 
-In the end: the system reflects its contributors.

Cargo.lock

@@ -90,9 +90,9 @@ checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"
 
 [[package]]
 name = "arc-swap"
-version = "1.9.0"
+version = "1.9.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a07d1f37ff60921c83bdfc7407723bdefe89b44b98a9b772f225c8f9d67141a6"
+checksum = "6a3a1fd6f75306b68087b831f025c712524bcb19aad54e557b1129cfa0a2b207"
 dependencies = [
  "rustversion",
 ]
@@ -173,9 +173,9 @@ checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
 
 [[package]]
 name = "aws-lc-rs"
-version = "1.16.2"
+version = "1.16.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a054912289d18629dc78375ba2c3726a3afe3ff71b4edba9dedfca0e3446d1fc"
+checksum = "0ec6fb3fe69024a75fa7e1bfb48aa6cf59706a101658ea01bfd33b2b248a038f"
 dependencies = [
  "aws-lc-sys",
  "zeroize",
@@ -183,9 +183,9 @@ dependencies = [
 
 [[package]]
 name = "aws-lc-sys"
-version = "0.39.1"
+version = "0.40.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "83a25cf98105baa966497416dbd42565ce3a8cf8dbfd59803ec9ad46f3126399"
+checksum = "f50037ee5e1e41e7b8f9d161680a725bd1626cb6f8c7e901f91f942850852fe7"
 dependencies = [
  "cc",
  "cmake",
@@ -228,9 +228,9 @@ checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a"
 
 [[package]]
 name = "bitflags"
-version = "2.11.0"
+version = "2.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "843867be96c8daad0d758b57df9392b6d8d271134fce549de6ce169ff98a92af"
+checksum = "c4512299f36f043ab09a583e57bceb5a5aab7a73db1805848e8fef3c9e8c78b3"
 
 [[package]]
 name = "blake3"
@@ -299,9 +299,9 @@ dependencies = [
 
 [[package]]
 name = "cc"
-version = "1.2.58"
+version = "1.2.60"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e1e928d4b69e3077709075a938a05ffbedfa53a84c8f766efbf8220bb1ff60e1"
+checksum = "43c5703da9466b66a946814e1adf53ea2c90f10063b86290cc9eb67ce3478a20"
 dependencies = [
  "find-msvc-tools",
  "jobserver",
@@ -346,7 +346,7 @@ checksum = "6f8d983286843e49675a4b7a2d174efe136dc93a18d69130dd18198a6c167601"
 dependencies = [
  "cfg-if",
  "cpufeatures 0.3.0",
- "rand_core 0.10.0",
+ "rand_core 0.10.1",
 ]
 
 [[package]]
@@ -416,9 +416,9 @@ dependencies = [
 
 [[package]]
 name = "clap"
-version = "4.6.0"
+version = "4.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b193af5b67834b676abd72466a96c1024e6a6ad978a1f484bd90b85c94041351"
+checksum = "1ddb117e43bbf7dacf0a4190fef4d345b9bad68dfc649cb349e7d17d28428e51"
 dependencies = [
  "clap_builder",
 ]
@@ -805,9 +805,9 @@ dependencies = [
 
 [[package]]
 name = "fastrand"
-version = "2.3.0"
+version = "2.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "37909eebbb50d72f9059c3b6d82c0463f2ff062c9e95845c43a6c9c0355411be"
+checksum = "9f1f227452a390804cdb637b74a86990f2a7d7ba4b7d5693aac9b4dd6defd8d6"
 
 [[package]]
 name = "fiat-crypto"
@@ -997,7 +997,7 @@ dependencies = [
  "cfg-if",
  "libc",
  "r-efi 6.0.0",
- "rand_core 0.10.0",
+ "rand_core 0.10.1",
  "wasip2",
  "wasip3",
 ]
@@ -1068,6 +1068,12 @@ dependencies = [
  "foldhash 0.2.0",
 ]
 
+[[package]]
+name = "hashbrown"
+version = "0.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4f467dd6dccf739c208452f8014c75c18bb8301b050ad1cfb27153803edb0f51"
+
 [[package]]
 name = "heck"
 version = "0.5.0"
@@ -1096,7 +1102,7 @@ dependencies = [
  "idna",
  "ipnet",
  "once_cell",
- "rand 0.9.2",
+ "rand 0.9.4",
  "ring",
  "thiserror 2.0.18",
  "tinyvec",
@@ -1118,7 +1124,7 @@ dependencies = [
  "moka",
  "once_cell",
  "parking_lot",
- "rand 0.9.2",
+ "rand 0.9.4",
  "resolv-conf",
  "smallvec",
  "thiserror 2.0.18",
@@ -1213,15 +1219,14 @@ dependencies = [
 
 [[package]]
 name = "hyper-rustls"
-version = "0.27.7"
+version = "0.27.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e3c93eb611681b207e1fe55d5a71ecf91572ec8a6705cdb6857f7d8d5242cf58"
+checksum = "33ca68d021ef39cf6463ab54c1d0f5daf03377b70561305bb89a8f83aab66e0f"
 dependencies = [
  "http",
  "hyper",
  "hyper-util",
  "rustls",
- "rustls-pki-types",
  "tokio",
  "tokio-rustls",
  "tower-service",
@@ -1385,12 +1390,12 @@ dependencies = [
 
 [[package]]
 name = "indexmap"
-version = "2.13.0"
+version = "2.14.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7714e70437a7dc3ac8eb7e6f8df75fd8eb422675fc7678aff7364301092b1017"
+checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9"
 dependencies = [
  "equivalent",
- "hashbrown 0.16.1",
+ "hashbrown 0.17.0",
  "serde",
  "serde_core",
 ]
@@ -1401,7 +1406,7 @@ version = "0.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "bd5b3eaf1a28b758ac0faa5a4254e8ab2705605496f1b1f3fbbc3988ad73d199"
 dependencies = [
- "bitflags 2.11.0",
+ "bitflags 2.11.1",
  "inotify-sys",
  "libc",
 ]
@@ -1534,9 +1539,9 @@ dependencies = [
 
 [[package]]
 name = "js-sys"
-version = "0.3.94"
+version = "0.3.95"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2e04e2ef80ce82e13552136fabeef8a5ed1f985a96805761cbb9a2c34e7664d9"
+checksum = "2964e92d1d9dc3364cae4d718d93f227e3abb088e747d92e0395bfdedf1c12ca"
 dependencies = [
  "cfg-if",
  "futures-util",
@@ -1578,9 +1583,9 @@ checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2"
 
 [[package]]
 name = "libc"
-version = "0.2.184"
+version = "0.2.185"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "48f5d2a454e16a5ea0f4ced81bd44e4cfc7bd3a507b61887c99fd3538b28e4af"
+checksum = "52ff2c0fe9bc6cb6b14a0592c2ff4fa9ceb83eea9db979b0487cd054946a2b8f"
 
 [[package]]
 name = "linux-raw-sys"
@@ -1611,9 +1616,9 @@ checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
 
 [[package]]
 name = "lru"
-version = "0.16.3"
+version = "0.16.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a1dc47f592c06f33f8e3aea9591776ec7c9f9e4124778ff8a3c3b87159f7e593"
+checksum = "7f66e8d5d03f609abc3a39e6f08e4164ebf1447a732906d39eb9b99b7919ef39"
 dependencies = [
  "hashbrown 0.16.1",
 ]
@@ -1705,7 +1710,7 @@ version = "0.31.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5d6d0705320c1e6ba1d912b5e37cf18071b6c2e9b7fa8215a1e8a7651966f5d3"
 dependencies = [
- "bitflags 2.11.0",
+ "bitflags 2.11.1",
  "cfg-if",
  "cfg_aliases",
  "libc",
@@ -1728,7 +1733,7 @@ version = "8.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4d3d07927151ff8575b7087f245456e549fea62edf0ec4e565a5ee50c8402bc3"
 dependencies = [
- "bitflags 2.11.0",
+ "bitflags 2.11.1",
  "fsevent-sys",
  "inotify",
  "kqueue",
@@ -1746,7 +1751,7 @@ version = "2.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "42b8cfee0e339a0337359f3c88165702ac6e600dc01c0cc9579a92d62b08477a"
 dependencies = [
- "bitflags 2.11.0",
+ "bitflags 2.11.1",
 ]
 
 [[package]]
@@ -2012,9 +2017,9 @@ checksum = "4b45fcc2344c680f5025fe57779faef368840d0bd1f42f216291f0dc4ace4744"
 dependencies = [
  "bit-set",
  "bit-vec",
- "bitflags 2.11.0",
+ "bitflags 2.11.1",
  "num-traits",
- "rand 0.9.2",
+ "rand 0.9.4",
  "rand_chacha",
  "rand_xorshift",
  "regex-syntax",
@@ -2059,7 +2064,7 @@ dependencies = [
  "bytes",
  "getrandom 0.3.4",
  "lru-slab",
- "rand 0.9.2",
+ "rand 0.9.4",
  "ring",
  "rustc-hash",
  "rustls",
@@ -2108,9 +2113,9 @@ checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
 
 [[package]]
 name = "rand"
-version = "0.9.2"
+version = "0.9.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6db2770f06117d490610c7488547d543617b21bfa07796d7a12f6f1bd53850d1"
+checksum = "44c5af06bb1b7d3216d91932aed5265164bf384dc89cd6ba05cf59a35f5f76ea"
 dependencies = [
  "rand_chacha",
  "rand_core 0.9.5",
@@ -2118,13 +2123,13 @@ dependencies = [
 
 [[package]]
 name = "rand"
-version = "0.10.0"
+version = "0.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bc266eb313df6c5c09c1c7b1fbe2510961e5bcd3add930c1e31f7ed9da0feff8"
+checksum = "d2e8e8bcc7961af1fdac401278c6a831614941f6164ee3bf4ce61b7edb162207"
 dependencies = [
  "chacha20 0.10.0",
  "getrandom 0.4.2",
- "rand_core 0.10.0",
+ "rand_core 0.10.1",
 ]
 
 [[package]]
@@ -2157,9 +2162,9 @@ dependencies = [
 
 [[package]]
 name = "rand_core"
-version = "0.10.0"
+version = "0.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0c8d0fd677905edcbeedbf2edb6494d676f0e98d54d5cf9bda0b061cb8fb8aba"
+checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69"
 
 [[package]]
 name = "rand_xorshift"
@@ -2172,9 +2177,9 @@ dependencies = [
 
 [[package]]
 name = "rayon"
-version = "1.11.0"
+version = "1.12.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "368f01d005bf8fd9b1206fb6fa653e6c4a81ceb1466406b81792d87c5677a58f"
+checksum = "fb39b166781f92d482534ef4b4b1b2568f42613b53e5b6c160e24cfbfa30926d"
 dependencies = [
  "either",
  "rayon-core",
@@ -2196,7 +2201,7 @@ version = "0.5.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d"
 dependencies = [
- "bitflags 2.11.0",
+ "bitflags 2.11.1",
 ]
 
 [[package]]
@@ -2326,7 +2331,7 @@ version = "1.1.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b6fe4565b9518b83ef4f91bb47ce29620ca828bd32cb7e408f0062e9930ba190"
 dependencies = [
- "bitflags 2.11.0",
+ "bitflags 2.11.1",
  "errno",
  "libc",
  "linux-raw-sys",
@@ -2335,9 +2340,9 @@ dependencies = [
 
 [[package]]
 name = "rustls"
-version = "0.23.37"
+version = "0.23.38"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "758025cb5fccfd3bc2fd74708fd4682be41d99e5dff73c377c0646c6012c73a4"
+checksum = "69f9466fb2c14ea04357e91413efb882e2a6d4a406e625449bc0a5d360d53a21"
 dependencies = [
  "aws-lc-rs",
  "once_cell",
@@ -2399,9 +2404,9 @@ checksum = "f87165f0995f63a9fbeea62b64d10b4d9d8e78ec6d7d51fb2125fda7bb36788f"
 
 [[package]]
 name = "rustls-webpki"
-version = "0.103.10"
+version = "0.103.13"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "df33b2b81ac578cabaf06b89b0631153a3f416b0a886e8a7a1707fb51abbd1ef"
+checksum = "61c429a8649f110dddef65e2a5ad240f747e85f7758a6bccc7e5777bd33f756e"
 dependencies = [
  "aws-lc-rs",
  "ring",
@@ -2474,7 +2479,7 @@ version = "3.7.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b7f4bc775c73d9a02cde8bf7b2ec4c9d12743edf609006c7facc23998404cd1d"
 dependencies = [
- "bitflags 2.11.0",
+ "bitflags 2.11.1",
  "core-foundation",
  "core-foundation-sys",
  "libc",
@@ -2493,9 +2498,9 @@ dependencies = [
 
 [[package]]
 name = "semver"
-version = "1.0.27"
+version = "1.0.28"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d767eb0aabc880b29956c35734170f26ed551a859dbd361d140cdbeca61ab1e2"
+checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd"
 
 [[package]]
 name = "sendfd"
@@ -2615,7 +2620,7 @@ dependencies = [
  "notify",
  "percent-encoding",
  "pin-project",
- "rand 0.9.2",
+ "rand 0.9.4",
  "sealed",
  "sendfd",
  "serde",
@@ -2646,7 +2651,7 @@ dependencies = [
  "chacha20poly1305",
  "hkdf",
  "md-5",
- "rand 0.9.2",
+ "rand 0.9.4",
  "ring-compat",
  "sha1",
 ]
@@ -2741,6 +2746,12 @@ version = "2.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292"
 
+[[package]]
+name = "symlink"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a7973cce6668464ea31f176d85b13c7ab3bba2cb3b77a2ed26abd7801688010a"
+
 [[package]]
 name = "syn"
 version = "2.0.117"
@@ -2780,7 +2791,7 @@ checksum = "7b2093cf4c8eb1e67749a6762251bc9cd836b6fc171623bd0a9d324d37af2417"
 
 [[package]]
 name = "telemt"
-version = "3.3.37"
+version = "3.4.11"
 dependencies = [
  "aes",
  "anyhow",
@@ -2812,7 +2823,7 @@ dependencies = [
  "num-traits",
  "parking_lot",
  "proptest",
- "rand 0.10.0",
+ "rand 0.10.1",
  "regex",
  "reqwest",
  "rustls",
@@ -2970,9 +2981,9 @@ checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
 
 [[package]]
 name = "tokio"
-version = "1.50.0"
+version = "1.52.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "27ad5e34374e03cfffefc301becb44e9dc3c17584f414349ebe29ed26661822d"
+checksum = "b67dee974fe86fd92cc45b7a95fdd2f99a36a6d7b0d431a231178d3d670bbcc6"
 dependencies = [
  "bytes",
  "libc",
@@ -2988,9 +2999,9 @@ dependencies = [
 
 [[package]]
 name = "tokio-macros"
-version = "2.6.1"
+version = "2.7.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5c55a2eff8b69ce66c84f85e1da1c233edc36ceb85a2058d11b0d6a3c7e7569c"
+checksum = "385a6cb71ab9ab790c5fe8d67f1645e6c450a7ce006a33de03daa956cf70a496"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -3123,7 +3134,7 @@ version = "0.6.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d4e6559d53cc268e5031cd8429d05415bc4cb4aefc4aa5d6cc35fbf5b924a1f8"
 dependencies = [
- "bitflags 2.11.0",
+ "bitflags 2.11.1",
  "bytes",
  "futures-util",
  "http",
@@ -3160,11 +3171,12 @@ dependencies = [
 
 [[package]]
 name = "tracing-appender"
-version = "0.2.4"
+version = "0.2.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "786d480bce6247ab75f005b14ae1624ad978d3029d9113f0a22fa1ac773faeaf"
+checksum = "050686193eb999b4bb3bc2acfa891a13da00f79734704c4b8b4ef1a10b368a3c"
 dependencies = [
  "crossbeam-channel",
+ "symlink",
  "thiserror 2.0.18",
  "time",
  "tracing-subscriber",
@@ -3239,9 +3251,9 @@ checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"
 
 [[package]]
 name = "typenum"
-version = "1.19.0"
+version = "1.20.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "562d481066bde0658276a35467c4af00bdc6ee726305698a55b86e61d7ad82bb"
+checksum = "40ce102ab67701b8526c123c1bab5cbe42d7040ccfd0f64af1a385808d2f43de"
 
 [[package]]
 name = "unarray"
@@ -3297,9 +3309,9 @@ checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
 
 [[package]]
 name = "uuid"
-version = "1.23.0"
+version = "1.23.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5ac8b6f42ead25368cf5b098aeb3dc8a1a2c05a3eee8a9a1a68c640edbfc79d9"
+checksum = "ddd74a9687298c6858e9b88ec8935ec45d22e8fd5e6394fa1bd4e99a87789c76"
 dependencies = [
  "getrandom 0.4.2",
  "js-sys",
@@ -3354,11 +3366,11 @@ checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
 
 [[package]]
 name = "wasip2"
-version = "1.0.2+wasi-0.2.9"
+version = "1.0.3+wasi-0.2.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9517f9239f02c069db75e65f174b3da828fe5f5b945c4dd26bd25d89c03ebcf5"
+checksum = "20064672db26d7cdc89c7798c48a0fdfac8213434a1186e5ef29fd560ae223d6"
 dependencies = [
- "wit-bindgen",
+ "wit-bindgen 0.57.1",
 ]
 
 [[package]]
@@ -3367,14 +3379,14 @@ version = "0.4.0+wasi-0.3.0-rc-2026-01-06"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5428f8bf88ea5ddc08faddef2ac4a67e390b88186c703ce6dbd955e1c145aca5"
 dependencies = [
- "wit-bindgen",
+ "wit-bindgen 0.51.0",
 ]
 
 [[package]]
 name = "wasm-bindgen"
-version = "0.2.117"
+version = "0.2.118"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0551fc1bb415591e3372d0bc4780db7e587d84e2a7e79da121051c5c4b89d0b0"
+checksum = "0bf938a0bacb0469e83c1e148908bd7d5a6010354cf4fb73279b7447422e3a89"
 dependencies = [
  "cfg-if",
  "once_cell",
@@ -3385,9 +3397,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-futures"
-version = "0.4.67"
+version = "0.4.68"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "03623de6905b7206edd0a75f69f747f134b7f0a2323392d664448bf2d3c5d87e"
+checksum = "f371d383f2fb139252e0bfac3b81b265689bf45b6874af544ffa4c975ac1ebf8"
 dependencies = [
  "js-sys",
  "wasm-bindgen",
@@ -3395,9 +3407,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro"
-version = "0.2.117"
+version = "0.2.118"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7fbdf9a35adf44786aecd5ff89b4563a90325f9da0923236f6104e603c7e86be"
+checksum = "eeff24f84126c0ec2db7a449f0c2ec963c6a49efe0698c4242929da037ca28ed"
 dependencies = [
  "quote",
  "wasm-bindgen-macro-support",
@@ -3405,9 +3417,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro-support"
-version = "0.2.117"
+version = "0.2.118"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dca9693ef2bab6d4e6707234500350d8dad079eb508dca05530c85dc3a529ff2"
+checksum = "9d08065faf983b2b80a79fd87d8254c409281cf7de75fc4b773019824196c904"
 dependencies = [
  "bumpalo",
  "proc-macro2",
@@ -3418,9 +3430,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-shared"
-version = "0.2.117"
+version = "0.2.118"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "39129a682a6d2d841b6c429d0c51e5cb0ed1a03829d8b3d1e69a011e62cb3d3b"
+checksum = "5fd04d9e306f1907bd13c6361b5c6bfc7b3b3c095ed3f8a9246390f8dbdee129"
 dependencies = [
  "unicode-ident",
 ]
@@ -3453,7 +3465,7 @@ version = "0.244.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "47b807c72e1bac69382b3a6fb3dbe8ea4c0ed87ff5629b8685ae6b9a611028fe"
 dependencies = [
- "bitflags 2.11.0",
+ "bitflags 2.11.1",
  "hashbrown 0.15.5",
  "indexmap",
  "semver",
@@ -3461,9 +3473,9 @@ dependencies = [
 
 [[package]]
 name = "web-sys"
-version = "0.3.94"
+version = "0.3.95"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cd70027e39b12f0849461e08ffc50b9cd7688d942c1c8e3c7b22273236b4dd0a"
+checksum = "4f2dfbb17949fa2088e5d39408c48368947b86f7834484e87b73de55bc14d97d"
 dependencies = [
  "js-sys",
  "wasm-bindgen",
@@ -3481,18 +3493,18 @@ dependencies = [
 
 [[package]]
 name = "webpki-root-certs"
-version = "1.0.6"
+version = "1.0.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "804f18a4ac2676ffb4e8b5b5fa9ae38af06df08162314f96a68d2a363e21a8ca"
+checksum = "f31141ce3fc3e300ae89b78c0dd67f9708061d1d2eda54b8209346fd6be9a92c"
 dependencies = [
  "rustls-pki-types",
 ]
 
 [[package]]
 name = "webpki-roots"
-version = "1.0.6"
+version = "1.0.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "22cfaf3c063993ff62e73cb4311efde4db1efb31ab78a3e5c457939ad5cc0bed"
+checksum = "52f5ee44c96cf55f1b349600768e3ece3a8f26010c05265ab73f945bb1a2eb9d"
 dependencies = [
  "rustls-pki-types",
 ]
@@ -3841,6 +3853,12 @@ dependencies = [
  "wit-bindgen-rust-macro",
 ]
 
+[[package]]
+name = "wit-bindgen"
+version = "0.57.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e"
+
 [[package]]
 name = "wit-bindgen-core"
 version = "0.51.0"
@@ -3890,7 +3908,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9d66ea20e9553b30172b5e831994e35fbde2d165325bec84fc43dbf6f4eb9cb2"
 dependencies = [
  "anyhow",
- "bitflags 2.11.0",
+ "bitflags 2.11.1",
  "indexmap",
  "log",
  "serde",
@@ -3922,9 +3940,9 @@ dependencies = [
 
 [[package]]
 name = "writeable"
-version = "0.6.2"
+version = "0.6.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9edde0db4769d2dc68579893f2306b26c6ecfbe0ef499b013d731b7b9247e0b9"
+checksum = "1ffae5123b2d3fc086436f8834ae3ab053a283cfac8fe0a0b8eaae044768a4c4"
 
 [[package]]
 name = "x25519-dalek"

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "telemt"
-version = "3.3.37"
+version = "3.4.11"
 edition = "2024"
 
 [features]
@@ -98,4 +98,3 @@ harness = false
 [profile.release]
 lto = "fat"
 codegen-units = 1
-

Dockerfile

@@ -77,6 +77,34 @@ COPY config.toml /app/config.toml
 
 EXPOSE 443 9090 9091
 
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 CMD ["/app/telemt", "healthcheck", "/app/config.toml", "--mode", "liveness"]
+
+ENTRYPOINT ["/app/telemt"]
+CMD ["config.toml"]
+
+# ==========================
+# Production Netfilter Profile
+# ==========================
+FROM debian:12-slim AS prod-netfilter
+
+RUN set -eux; \
+    apt-get update; \
+    apt-get install -y --no-install-recommends \
+        ca-certificates \
+        conntrack \
+        nftables \
+        iptables; \
+    rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY --from=minimal /telemt /app/telemt
+COPY config.toml /app/config.toml
+
+EXPOSE 443 9090 9091
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 CMD ["/app/telemt", "healthcheck", "/app/config.toml", "--mode", "liveness"]
+
 ENTRYPOINT ["/app/telemt"]
 CMD ["config.toml"]
 
@@ -94,5 +122,7 @@ USER nonroot:nonroot
 
 EXPOSE 443 9090 9091
 
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 CMD ["/app/telemt", "healthcheck", "/app/config.toml", "--mode", "liveness"]
+
 ENTRYPOINT ["/app/telemt"]
 CMD ["config.toml"]

LICENSE

@@ -1,4 +1,4 @@
-###### TELEMT Public License 3 ######
+######## TELEMT LICENSE 3.3 #########
 ##### Copyright (c) 2026 Telemt #####
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -14,11 +14,15 @@ are preserved and complied with.
 The canonical version of this License is the English version.
 Official translations are provided for informational purposes only
 and for convenience, and do not have legal force. In case of any
-discrepancy, the English version of this License shall prevail.
-Available versions:
-- English in Markdown: docs/LICENSE/LICENSE.md
-- German: docs/LICENSE/LICENSE.de.md
-- Russian: docs/LICENSE/LICENSE.ru.md
+discrepancy, the English version of this License shall prevail
+
+/----------------------------------------------------------\
+| Language    | Location                                   |
+|-------------|--------------------------------------------|
+| English     | docs/LICENSE/TELEMT-LICENSE.en.md          |
+| German      | docs/LICENSE/TELEMT-LICENSE.de.md          |
+| Russian     | docs/LICENSE/TELEMT-LICENSE.ru.md          |
+\----------------------------------------------------------/
 
 ### License Versioning Policy
 

README.md

@@ -1,182 +1,57 @@
 # Telemt - MTProxy on Rust + Tokio
 
+[![Latest Release](https://img.shields.io/github/v/release/telemt/telemt?color=neon)](https://github.com/telemt/telemt/releases/latest) [![Stars](https://img.shields.io/github/stars/telemt/telemt?style=social)](https://github.com/telemt/telemt/stargazers) [![Forks](https://img.shields.io/github/forks/telemt/telemt?style=social)](https://github.com/telemt/telemt/network/members)
+
+[🇷🇺 README на русском](https://github.com/telemt/telemt/blob/main/README.ru.md)
+
 ***Löst Probleme, bevor andere überhaupt wissen, dass sie existieren*** / ***It solves problems before others even realize they exist***
 
-[**Telemt Chat in Telegram**](https://t.me/telemtrs)
+> [!NOTE]
+>
+> Fixed TLS ClientHello is now available in official clients for Desktop / Android / iOS
+>
+> To work with EE-MTProxy, please update your client!
 
-**Telemt** is a fast, secure, and feature-rich server written in Rust: it fully implements the official Telegram proxy algo and adds many production-ready improvements such as:
-- [ME Pool + Reader/Writer + Registry + Refill + Adaptive Floor + Trio-State + Generation Lifecycle](https://github.com/telemt/telemt/blob/main/docs/model/MODEL.en.md)
-- [Full-covered API w/ management](https://github.com/telemt/telemt/blob/main/docs/API.md)
-- Anti-Replay on Sliding Window
-- Prometheus-format Metrics
-- TLS-Fronting and TCP-Splicing for masking from "prying" eyes
+<p align="center">
+  <a href="https://t.me/telemtrs">
+    <img src="https://github.com/user-attachments/assets/30b7e7b9-974a-4e3d-aab6-b58a85de4507" width="240"/>
+  </a>
+</p>
 
-⚓ Our implementation of **TLS-fronting** is one of the most deeply debugged, focused, advanced and *almost* **"behaviorally consistent to real"**:  we are confident we have it right - [see evidence on our validation and traces](#recognizability-for-dpi-and-crawler)
+**Telemt** is a fast, secure, and feature-rich server written in Rust: it fully implements the official Telegram proxy algo and adds many production-ready improvements
 
-⚓ Our ***Middle-End Pool*** is fastest by design in standard scenarios, compared to other implementations of connecting to the Middle-End Proxy: non dramatically, but usual
+### One-command Install and Update
+```bash
+curl -fsSL https://raw.githubusercontent.com/telemt/telemt/main/install.sh | sh
+```
+- [Quick Start Guide](docs/Quick_start/QUICK_START_GUIDE.en.md)
+- [Инструкция по быстрому запуску](docs/Quick_start/QUICK_START_GUIDE.ru.md)
+
+## Features
+Our implementation of **TLS-fronting** is one of the most deeply debugged, focused, advanced and *almost* **"behaviorally consistent to real"**:  we are confident we have it right - [see evidence on our validation and traces](docs/FAQ.en.md#recognizability-for-dpi-and-crawler)
+
+Our ***Middle-End Pool*** is fastest by design in standard scenarios, compared to other implementations of connecting to the Middle-End Proxy: non dramatically, but usual
 
 - Full support for all official MTProto proxy modes:
-  - Classic
-  - Secure - with `dd` prefix
-  - Fake TLS - with `ee` prefix + SNI fronting
-- Replay attack protection
-- Optional traffic masking: forward unrecognized connections to a real web server, e.g. GitHub 🤪
-- Configurable keepalives + timeouts + IPv6 and "Fast Mode"
-- Graceful shutdown on Ctrl+C
-- Extensive logging via `trace` and `debug` with `RUST_LOG` method
-
-# GOTO
-- [Quick Start Guide](#quick-start-guide)
-- [FAQ](#faq)
-  - [Recognizability for DPI and crawler](#recognizability-for-dpi-and-crawler)
-    - [Client WITH secret-key accesses the MTProxy resource:](#client-with-secret-key-accesses-the-mtproxy-resource)
-    - [Client WITHOUT secret-key gets transparent access to the specified resource:](#client-without-secret-key-gets-transparent-access-to-the-specified-resource)
-  - [Telegram Calls via MTProxy](#telegram-calls-via-mtproxy)
-  - [How does DPI see MTProxy TLS?](#how-does-dpi-see-mtproxy-tls)
-  - [Whitelist on IP](#whitelist-on-ip)
-  - [Too many open files](#too-many-open-files)
-- [Build](#build)
-- [Why Rust?](#why-rust)
-- [Issues](#issues)
-- [Roadmap](#roadmap)
-
-
-## Quick Start Guide
-- [Quick Start Guide RU](docs/QUICK_START_GUIDE.ru.md)
-- [Quick Start Guide EN](docs/QUICK_START_GUIDE.en.md)
+  - Classic;
+  - Secure - with `dd` prefix;
+  - Fake TLS - with `ee` prefix + SNI fronting;
+- Replay attack protection;
+- Optional traffic masking: forward unrecognized connections to a real web server, e.g. GitHub 🤪;
+- Configurable keepalives + timeouts + IPv6 and "Fast Mode";
+- Graceful shutdown on Ctrl+C;
+- Extensive logging via `trace` and `debug` with `RUST_LOG` method.
 
 ## FAQ
-
 - [FAQ RU](docs/FAQ.ru.md)
 - [FAQ EN](docs/FAQ.en.md)
 
-### Recognizability for DPI and crawler
-Since version 1.1.0.0, we have debugged masking perfectly: for all clients without "presenting" a key, 
-we transparently direct traffic to the target host!
-
-- We consider this a breakthrough aspect, which has no stable analogues today
-- Based on this: if `telemt` configured correctly, **TLS mode is completely identical to real-life handshake + communication** with a specified host
-- Here is our evidence:
-    - 212.220.88.77 - "dummy" host, running `telemt`
-    - `petrovich.ru` - `tls` + `masking` host, in HEX: `706574726f766963682e7275`
-    - **No MITM + No Fake Certificates/Crypto** = pure transparent *TCP Splice* to "best" upstream: MTProxy or tls/mask-host:
-      - DPI see legitimate HTTPS to `tls_host`, including *valid chain-of-trust* and entropy
-      - Crawlers completely satisfied receiving responses from `mask_host`
-  #### Client WITH secret-key accesses the MTProxy resource:
-  
-  <img width="360" height="439" alt="telemt" src="https://github.com/user-attachments/assets/39352afb-4a11-4ecc-9d91-9e8cfb20607d" />
-  
-  #### Client WITHOUT secret-key gets transparent access to the specified resource:
-    - with trusted certificate
-    - with original handshake
-    - with full request-response way
-    - with low-latency overhead
-```bash
-root@debian:~/telemt# curl -v -I --resolve petrovich.ru:443:212.220.88.77 https://petrovich.ru/
-* Added petrovich.ru:443:212.220.88.77 to DNS cache
-* Hostname petrovich.ru was found in DNS cache
-*   Trying 212.220.88.77:443...
-* Connected to petrovich.ru (212.220.88.77) port 443 (#0)
-* ALPN: offers h2,http/1.1
-* TLSv1.3 (OUT), TLS handshake, Client hello (1):
-*  CAfile: /etc/ssl/certs/ca-certificates.crt
-*  CApath: /etc/ssl/certs
-* TLSv1.3 (IN), TLS handshake, Server hello (2):
-* TLSv1.3 (IN), TLS handshake, Encrypted Extensions (8):
-* TLSv1.3 (IN), TLS handshake, Certificate (11):
-* TLSv1.3 (IN), TLS handshake, CERT verify (15):
-* TLSv1.3 (IN), TLS handshake, Finished (20):
-* TLSv1.3 (OUT), TLS change cipher, Change cipher spec (1):
-* TLSv1.3 (OUT), TLS handshake, Finished (20):
-* SSL connection using TLSv1.3 / TLS_AES_256_GCM_SHA384
-* ALPN: server did not agree on a protocol. Uses default.
-* Server certificate:
-*  subject: C=RU; ST=Saint Petersburg; L=Saint Petersburg; O=STD Petrovich; CN=*.petrovich.ru
-*  start date: Jan 28 11:21:01 2025 GMT
-*  expire date: Mar  1 11:21:00 2026 GMT
-*  subjectAltName: host "petrovich.ru" matched cert's "petrovich.ru"
-*  issuer: C=BE; O=GlobalSign nv-sa; CN=GlobalSign RSA OV SSL CA 2018
-*  SSL certificate verify ok.
-* using HTTP/1.x
-> HEAD / HTTP/1.1
-> Host: petrovich.ru
-> User-Agent: curl/7.88.1
-> Accept: */*
-> 
-* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
-* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
-* old SSL session ID is stale, removing
-< HTTP/1.1 200 OK
-HTTP/1.1 200 OK
-< Server: Variti/0.9.3a
-Server: Variti/0.9.3a
-< Date: Thu, 01 Jan 2026 00:0000 GMT
-Date: Thu, 01 Jan 2026 00:0000 GMT
-< Access-Control-Allow-Origin: *
-Access-Control-Allow-Origin: *
-< Content-Type: text/html
-Content-Type: text/html
-< Cache-Control: no-store
-Cache-Control: no-store
-< Expires: Thu, 01 Jan 2026 00:0000 GMT
-Expires: Thu, 01 Jan 2026 00:0000 GMT
-< Pragma: no-cache
-Pragma: no-cache
-< Set-Cookie: ipp_uid=XXXXX/XXXXX/XXXXX==; Expires=Tue, 31 Dec 2040 23:59:59 GMT; Domain=.petrovich.ru; Path=/
-Set-Cookie: ipp_uid=XXXXX/XXXXX/XXXXX==; Expires=Tue, 31 Dec 2040 23:59:59 GMT; Domain=.petrovich.ru; Path=/
-< Content-Type: text/html
-Content-Type: text/html
-< Content-Length: 31253
-Content-Length: 31253
-< Connection: keep-alive
-Connection: keep-alive
-< Keep-Alive: timeout=60
-Keep-Alive: timeout=60
-
-< 
-* Connection #0 to host petrovich.ru left intact
-
-```
-- We challenged ourselves, we kept trying and we didn't only *beat the air*: now, we have something to show you
-  - Do not just take our word for it? - This is great and we respect that: you can build your own `telemt` or download a build and check it right now
-### Telegram Calls via MTProxy
-- Telegram architecture **does NOT allow calls via MTProxy**, but only via SOCKS5, which cannot be obfuscated
-### How does DPI see MTProxy TLS?
-- DPI sees MTProxy in Fake TLS (ee) mode as TLS 1.3
-- the SNI you specify sends both the client and the server;
-- ALPN is similar to HTTP 1.1/2;
-- high entropy, which is normal for AES-encrypted traffic;
-### Whitelist on IP
-- MTProxy cannot work when there is: 
-  - no IP connectivity to the target host: Russian Whitelist on Mobile Networks - "Белый список"
-  - OR all TCP traffic is blocked
-  - OR high entropy/encrypted traffic is blocked: content filters at universities and critical infrastructure
-  - OR all TLS traffic is blocked
-  - OR specified port is blocked: use 443 to make it "like real"
-  - OR provided SNI is blocked: use "officially approved"/innocuous name
-- like most protocols on the Internet; 
-- these situations are observed:
-  - in China behind the Great Firewall
-  - in Russia on mobile networks, less in wired networks
-  - in Iran during "activity"
-### Too many open files
-- On a fresh Linux install the default open file limit is low; under load `telemt` may fail with `Accept error: Too many open files`
-- **Systemd**: add `LimitNOFILE=65536` to the `[Service]` section (already included in the example above)
-- **Docker**: add `--ulimit nofile=65536:65536` to your `docker run` command, or in `docker-compose.yml`:
-```yaml
-ulimits:
-  nofile:
-    soft: 65536
-    hard: 65536
-```
-- **System-wide** (optional): add to `/etc/security/limits.conf`:
-```
-*       soft    nofile  1048576
-*       hard    nofile  1048576
-root    soft    nofile  1048576
-root    hard    nofile  1048576
-```
-
+# Learn more about Telemt
+- [Our Architecture](docs/Architecture)
+- [All Config Options](docs/Config_params)
+- [How to build your own Telemt?](#build)
+- [Running on BSD](docs/Quick_start/OPENBSD_QUICK_START_GUIDE.en.md)
+- [Why Rust?](#why-rust)
 
 ## Build
 ```bash
@@ -187,9 +62,8 @@ cd telemt
 # Starting Release Build
 cargo build --release
 
-# Low-RAM devices (1 GB, e.g. NanoPi Neo3 / Raspberry Pi Zero 2):
-# release profile uses lto = "thin" to reduce peak linker memory.
-# If your custom toolchain overrides profiles, avoid enabling fat LTO.
+# Current release profile uses lto = "fat" for maximum optimization (see Cargo.toml).
+# On low-RAM systems (~1 GB) you can override it to "thin".
 
 # Move to /bin
 mv ./target/release/telemt /bin
@@ -199,12 +73,6 @@ chmod +x /bin/telemt
 telemt config.toml
 ```
 
-### OpenBSD
-- Build and service setup guide: [OpenBSD Guide (EN)](docs/OPENBSD.en.md)
-- Example rc.d script: [contrib/openbsd/telemt.rcd](contrib/openbsd/telemt.rcd)
-- Status: OpenBSD sandbox hardening with `pledge(2)` and `unveil(2)` is not implemented yet.
-
-
 ## Why Rust?
 - Long-running reliability and idempotent behavior
 - Rust's deterministic resource management - RAII 
@@ -212,23 +80,26 @@ telemt config.toml
 - Memory safety and reduced attack surface
 - Tokio's asynchronous architecture
 
-## Issues
-- ✅ [SOCKS5 as Upstream](https://github.com/telemt/telemt/issues/1) -> added Upstream Management
-- ✅ [iOS - Media Upload Hanging-in-Loop](https://github.com/telemt/telemt/issues/2)
+## Support Telemt
 
-## Roadmap
-- Public IP in links
-- Config Reload-on-fly
-- Bind to device or IP for outbound/inbound connections
-- Adtag Support per SNI / Secret
-- Fail-fast on start + Fail-soft on runtime (only WARN/ERROR)
-- Zero-copy, minimal allocs on hotpath
-- DC Healthchecks + global fallback
-- No global mutable state
-- Client isolation + Fair Bandwidth
-- Backpressure-aware IO
-- "Secret Policy" - SNI / Secret Routing :D
-- Multi-upstream Balancer and Failover
-- Strict FSM per handshake
-- Session-based Antireplay with Sliding window, non-broking reconnects
-- Web Control: statistic, state of health, latency, client experience...
+Telemt is free, open-source, and built in personal time.
+If it helps you — consider supporting continued development.
+
+Any cryptocurrency (BTC, ETH, USDT, 350+ coins):
+
+<p align="center">
+  <a href="https://nowpayments.io/donation?api_key=2bf1afd2-abc2-49f9-a012-f1e715b37223" target="_blank" rel="noreferrer noopener">
+    <img src="https://nowpayments.io/images/embeds/donation-button-white.svg" alt="Cryptocurrency & Bitcoin donation button by NOWPayments" height="80">
+  </a>
+</p>
+
+Monero (XMR) directly:
+
+```
+8Bk4tZEYPQWSypeD2hrUXG2rKbAKF16GqEN942ZdAP5cFdSqW6h4DwkP5cJMAdszzuPeHeHZPTyjWWFwzeFdjuci3ktfMoB
+```
+
+All donations go toward infrastructure, development and research
+
+
+![telemt_scheme](docs/assets/telemt.png)

README.ru.md

@@ -0,0 +1,109 @@
+# Telemt — MTProxy на Rust + Tokio
+
+[![Latest Release](https://img.shields.io/github/v/release/telemt/telemt?color=neon)](https://github.com/telemt/telemt/releases/latest) [![Stars](https://img.shields.io/github/stars/telemt/telemt?style=social)](https://github.com/telemt/telemt/stargazers) [![Forks](https://img.shields.io/github/forks/telemt/telemt?style=social)](https://github.com/telemt/telemt/network/members) [![Telegram](https://img.shields.io/badge/Telegram-Chat-24a1de?logo=telegram&logoColor=24a1de)](https://t.me/telemtrs)
+
+***Решает проблемы раньше, чем другие узнают об их существовании***
+
+> [!NOTE]
+>
+> Исправленный TLS ClientHello доступен в Telegram для настольных ПК, Android и iOS.
+> 
+> Пожалуйста, обновите клиентское приложение для работы с EE-MTProxy.
+
+<p align="center">
+  <a href="https://t.me/telemtrs">
+    <img src="/docs/assets/telegram_button.svg" width="150"/>
+  </a>
+</p>
+
+**Telemt** — это быстрый, безопасный и функциональный сервер, написанный на Rust. Он полностью реализует официальный алгоритм прокси Telegram и добавляет множество улучшений для продакшена:
+
+## Установка и обновление одной командой
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/telemt/telemt/main/install.sh | sh
+```
+
+- [Инструкция по быстрому запуску](docs/Quick_start/QUICK_START_GUIDE.ru.md)
+- [Quick Start Guide](docs/Quick_start/QUICK_START_GUIDE.en.md)
+
+Реализация **TLS-fronting** максимально приближена к поведению реального HTTPS-трафика (подробнее - [FAQ](docs/FAQ.ru.md#распознаваемость-для-dpi-и-сканеров)).
+
+***Middle-End Pool*** оптимизирован для высокой производительности.
+
+- Поддержка всех режимов MTProto proxy:
+  - Classic;
+  - Secure (префикс `dd`);
+  - Fake TLS (префикс `ee` + SNI fronting);
+- Защита от replay-атак;
+- Маскировка трафика (перенаправление неизвестных подключений на реальные сайты);
+- Настраиваемые keepalive, таймауты, IPv6 и «быстрый режим»;
+- Корректное завершение работы (Ctrl+C);
+- Подробное логирование через `trace` и `debug`.
+
+# Подробнее о Telemt
+- [FAQ](#faq)
+- [Архитектура](docs/Architecture)
+- [Параметры конфигурационного файла](docs/Config_params)
+- [Сборка](#build)
+- [Установка на BSD](#%D1%83%D1%81%D1%82%D0%B0%D0%BD%D0%BE%D0%B2%D0%BA%D0%B0-%D0%BD%D0%B0-bsd)
+- [Почему Rust?](#why-rust)
+
+## FAQ
+- [FAQ RU](docs/FAQ.ru.md)
+- [FAQ EN](docs/FAQ.en.md)
+
+## Сборка
+```bash
+# Клонируйте репозиторий
+git clone https://github.com/telemt/telemt 
+# Смените каталог на telemt
+cd telemt
+# Начните процесс сборки
+cargo build --release
+
+# В текущем release-профиле используется lto = "fat" для максимальной оптимизации (см. Cargo.toml).
+# На системах с малым объёмом RAM (~1 ГБ) можно переопределить это значение на "thin".
+
+# Перейдите в каталог /bin
+mv ./target/release/telemt /bin
+# Сделайте файл исполняемым
+chmod +x /bin/telemt
+# Запустите!
+telemt config.toml
+```
+
+## Установка на BSD
+- Руководство по сборке и настройке на английском языке [OpenBSD Guide (EN)](docs/Quick_start/OPENBSD_QUICK_START_GUIDE.en.md);
+- Пример rc.d скрипта: [contrib/openbsd/telemt.rcd](contrib/openbsd/telemt.rcd);
+- Поддержка sandbox с `pledge(2)` и `unveil(2)` пока не реализована.
+
+## Почему Rust?
+- Надёжность для долгоживущих процессов;
+- Детерминированное управление ресурсами (RAII);
+- Отсутствие сборщика мусора;
+- Безопасность памяти;
+- Асинхронная архитектура Tokio.
+
+## Поддержать Telemt
+
+Telemt — это бесплатное программное обеспечение с открытым исходным кодом, разработанное в свободное время.
+Если оно оказалось вам полезным, вы можете поддержать дальнейшую разработку.
+
+Принимаемые криптовалюты (BTC, ETH, USDT, 350+ и другие):
+
+<p align="center">
+  <a href="https://nowpayments.io/donation?api_key=2bf1afd2-abc2-49f9-a012-f1e715b37223" target="_blank" rel="noreferrer noopener">
+    <img src="https://nowpayments.io/images/embeds/donation-button-white.svg" alt="Cryptocurrency & Bitcoin donation button by NOWPayments" height="80">
+  </a>
+</p>
+
+Monero (XMR) напрямую:
+
+```
+8Bk4tZEYPQWSypeD2hrUXG2rKbAKF16GqEN942ZdAP5cFdSqW6h4DwkP5cJMAdszzuPeHeHZPTyjWWFwzeFdjuci3ktfMoB
+```
+
+Все пожертвования пойдут на инфраструктуру, разработку и исследования.
+
+![telemt_scheme](docs/assets/telemt.png)

config.toml

@@ -32,13 +32,13 @@ show = "*"
 port = 443
 # proxy_protocol = false           # Enable if behind HAProxy/nginx with PROXY protocol
 # metrics_port = 9090
-# metrics_listen = "0.0.0.0:9090"  # Listen address for metrics (overrides metrics_port)
-# metrics_whitelist = ["127.0.0.1", "::1", "0.0.0.0/0"]
+# metrics_listen = "127.0.0.1:9090" # Listen address for metrics (overrides metrics_port)
+# metrics_whitelist = ["127.0.0.1/32", "::1/128"]
 
 [server.api]
 enabled = true
-listen = "0.0.0.0:9091"
-whitelist = ["127.0.0.0/8"]
+listen = "127.0.0.1:9091"
+whitelist = ["127.0.0.1/32", "::1/128"]
 minimal_runtime_enabled = false
 minimal_runtime_cache_ttl_ms = 1000
 
@@ -48,9 +48,12 @@ ip = "0.0.0.0"
 
 # === Anti-Censorship & Masking ===
 [censorship]
+# Fake-TLS / SNI masking domain used in generated ee-links.
+# Changing tls_domain invalidates previously generated TLS links.
 tls_domain = "petrovich.ru"
+
 mask = true
-tls_emulation = true        # Fetch real cert lengths and emulate TLS records
+tls_emulation = true         # Fetch real cert lengths and emulate TLS records
 tls_front_dir = "tlsfront"   # Cache directory for TLS emulation
 
 [access.users]

docker-compose.host-netfilter.yml

@@ -0,0 +1,10 @@
+services:
+  telemt:
+    build:
+      context: .
+      target: prod-netfilter
+    network_mode: host
+    ports: []
+    cap_add:
+      - NET_BIND_SERVICE
+      - NET_ADMIN

docker-compose.netfilter.yml

@@ -0,0 +1,8 @@
+services:
+  telemt:
+    build:
+      context: .
+      target: prod-netfilter
+    cap_add:
+      - NET_BIND_SERVICE
+      - NET_ADMIN

docker-compose.yml

@@ -1,7 +1,9 @@
 services:
   telemt:
     image: ghcr.io/telemt/telemt:latest
-    build: .
+    build:
+      context: .
+      target: prod
     container_name: telemt
     restart: unless-stopped
     ports:
@@ -9,23 +11,29 @@ services:
       - "127.0.0.1:9090:9090"
       - "127.0.0.1:9091:9091"
     # Allow caching 'proxy-secret' in read-only container
-    working_dir: /run/telemt
+    working_dir: /etc/telemt
     volumes:
-      - ./config.toml:/run/telemt/config.toml:ro
+      - ./config.toml:/etc/telemt/config.toml:ro
     tmpfs:
-      - /run/telemt:rw,mode=1777,size=1m
+      - /etc/telemt:rw,mode=1777,size=4m
     environment:
       - RUST_LOG=info
+    healthcheck:
+      test: [ "CMD", "/app/telemt", "healthcheck", "/etc/telemt/config.toml", "--mode", "liveness" ]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 20s
     # Uncomment this line if you want to use host network for IPv6, but bridge is default and usually better
     # network_mode: host
     cap_drop:
       - ALL
     cap_add:
-      - NET_BIND_SERVICE   # allow binding to port 443
+      - NET_BIND_SERVICE
     read_only: true
     security_opt:
       - no-new-privileges:true
     ulimits:
       nofile:
         soft: 65536
-        hard: 65536
+        hard: 262144

docs/Advanced_settings/HIGH_LOAD.en.md

@@ -0,0 +1,141 @@
+# High-Load Configuration & Tuning Guide
+When deploying Telemt under high-traffic load (tens or hundreds of thousands of concurrent connections), the standard OS network stack limits can lead to packet drops, high CPU context switching, and connection failures. This guide covers Linux kernel tuning, hardware configuration, and architecture optimizations required to prepare the server for high-load scenarios.
+
+---
+## 1. System Limits & File Descriptors
+Every TCP connection requires a file descriptor. At 100k connections, standard Linux limits (often 1024 or 65535) will be exhausted immediately.
+### System-Wide Limits (`sysctl`)
+Increase the global file descriptor limit in `/etc/sysctl.conf`:
+```ini
+fs.file-max = 2097152
+fs.nr_open = 2097152
+```
+### User-Level Limits (`limits.conf`)
+Edit `/etc/security/limits.conf` to allow the telemt (or proxy) user to allocate them:
+```conf
+* soft nofile 1048576
+* hard nofile 1048576
+root soft nofile 1048576
+root hard nofile 1048576
+```
+### Systemd / Docker Overrides
+If using **Systemd**, add to your `telemt.service`:
+```ini
+[Service]
+LimitNOFILE=1048576
+LimitNPROC=65535
+TasksMax=infinity
+```
+If using **Docker**, configure `ulimits` in `docker-compose.yaml`:
+```yaml
+services:
+  telemt:
+    ulimits:
+      nofile:
+        soft: 1048576
+        hard: 1048576
+```
+
+---
+## 2. Kernel Network Stack Tuning (`sysctl`)
+Create a dedicated file `/etc/sysctl.d/99-telemt-highload.conf` and apply it via `sysctl -p /etc/sysctl.d/99-telemt-highload.conf`.
+### 2.1 Connection Queues & SYN Flood Protection
+Increase the size of accept queues to absorb sudden connection spikes (bursts) and mitigate SYN floods:
+```ini
+net.core.somaxconn = 65535
+net.core.netdev_max_backlog = 65535
+net.ipv4.tcp_max_syn_backlog = 65535
+net.ipv4.tcp_syncookies = 1
+```
+### 2.2 Port Exhaustion & TIME-WAIT Sockets
+High churn rates lead to ephemeral port exhaustion. Expand the range and rapidly recycle closed sockets:
+```ini
+net.ipv4.ip_local_port_range = 10000 65535
+net.ipv4.tcp_fin_timeout = 15
+net.ipv4.tcp_tw_reuse = 1
+net.ipv4.tcp_max_tw_buckets = 2000000
+```
+### 2.3 TCP Keepalive (Aggressive Dead Connection Culling)
+By default, Linux keeps silent, dropped connections open for over 2 hours. This consumes memory at scale. Configure the system to detect and drop them in < 5 minutes:
+```ini
+net.ipv4.tcp_keepalive_time = 300
+net.ipv4.tcp_keepalive_intvl = 30
+net.ipv4.tcp_keepalive_probes = 5
+```
+### 2.4 TCP Buffers & Congestion Control
+Optimize memory usage per socket and switch to BBR (Bottleneck Bandwidth and Round-trip propagation time) to improve latency on lossy networks:
+```ini
+# Core buffer sizes
+net.core.rmem_default = 262144
+net.core.wmem_default = 262144
+net.core.rmem_max = 16777216
+net.core.wmem_max = 16777216
+# TCP specific buffers (min, default, max)
+net.ipv4.tcp_rmem = 4096 87380 16777216
+net.ipv4.tcp_wmem = 4096 65536 16777216
+# Enable BBR
+net.core.default_qdisc = fq
+net.ipv4.tcp_congestion_control = bbr
+```
+
+---
+## 3. Conntrack (Netfilter) Tuning
+If your server uses `iptables`, `ufw`, or `firewalld`, the Linux kernel tracks every connection state in a table (`nf_conntrack`). When this table fills up, Linux drops new packets.
+Check your current limit and usage:
+```bash
+sysctl net.netfilter.nf_conntrack_max
+sysctl net.netfilter.nf_conntrack_count
+```
+If it gets close to the limit, tune it up, and reduce the time established connections linger in the tracker:
+```ini
+# In /etc/sysctl.d/99-telemt-highload.conf
+net.netfilter.nf_conntrack_max = 2097152
+# Reduce timeout from default 5 days to 1 hour
+net.netfilter.nf_conntrack_tcp_timeout_established = 3600
+net.netfilter.nf_conntrack_tcp_timeout_time_wait = 12
+```
+*Note: Depending on your OS, you may need to run `modprobe nf_conntrack` before setting these parameters.*
+
+---
+## 4. Multi-Tier Architecture: HAProxy Setup
+For massive traffic loads, buffering Telemt behind a reverse proxy like HAProxy can help absorb connection spikes and handle basic TCP connections before handing them off.
+### HAProxy High-Load `haproxy.cfg`
+```haproxy
+global
+    # Disable detailed logging under load
+    log stdout format raw local0 err
+    # maxconn 250000
+    
+    # Buffer tuning
+    tune.bufsize 16384
+    tune.maxaccept 64
+defaults
+    log     global
+    mode    tcp
+    option  clitcpka
+    option  srvtcpka
+    timeout connect 5s
+    timeout client  1h
+    timeout server  1h
+    # Quick purge for dead peers
+    timeout client-fin 10s
+    timeout server-fin 10s
+frontend proxy_in
+    bind *:443
+    maxconn 250000
+    option tcp-smart-accept
+    default_backend telemt_backend
+backend telemt_backend
+    option tcp-smart-connect
+    # Send-Proxy-V2 to preserve Client IP for Telemt's internal logic
+    server telemt_core 10.10.10.1:443 maxconn 250000 send-proxy-v2 check inter 5s
+```
+**Important**: Telemt must be configured to process the `PROXY` protocol on port `443` for this chain to work and preserve client IPs.
+
+---
+## 5. Diagnostics & Monitoring
+When operating under load, these commands are useful for diagnostics:
+* **Checking dropped connections (Queues full)**: `netstat -s | grep "times the listen queue of a socket overflowed"`
+* **Checking Conntrack drops**: `dmesg | grep conntrack`
+* **Checking File Descriptor usage**: `cat /proc/sys/fs/file-nr`
+* **Real-time connection states**: `ss -s` (Avoid using `netstat` on heavy loads).

docs/Advanced_settings/HIGH_LOAD.ru.md

@@ -0,0 +1,139 @@
+# Руководство по High-Load конфигурации и тюнингу
+При развертывании Telemt под высокой нагрузкой (десятки и сотни тысяч одновременных подключений), стандартные ограничения сетевого стека ОС могут приводить к потерям пакетов, переключениям контекста CPU и отказам в соединениях. В данном руководстве описана настройка ядра Linux, системных лимитов и аппаратной конфигурации для работы в подобных сценариях.
+
+---
+## 1. Системные лимиты и файловые дескрипторы
+Каждое TCP-сосоединение требует файлового дескриптора. При 100 тысячах соединений стандартные лимиты Linux (зачастую 1024 или 65535) будут исчерпаны немедленно.
+### Общесистемные лимиты (`sysctl`)
+Увеличьте глобальный лимит файловых дескрипторов в `/etc/sysctl.conf`:
+```ini
+fs.file-max = 2097152
+fs.nr_open = 2097152
+```
+### На уровне пользователя (`limits.conf`)
+Отредактируйте `/etc/security/limits.conf`, чтобы разрешить пользователю (от которого запущен telemt) резервировать дескрипторы:
+```conf
+* soft nofile 1048576
+* hard nofile 1048576
+root soft nofile 1048576
+root hard nofile 1048576
+```
+### Переопределения для Systemd / Docker
+Если используется **Systemd**, добавьте в ваш `telemt.service`:
+```ini
+[Service]
+LimitNOFILE=1048576
+LimitNPROC=65535
+TasksMax=infinity
+```
+Если используется **Docker**, задайте `ulimits` в `docker-compose.yaml`:
+```yaml
+services:
+  telemt:
+    ulimits:
+      nofile:
+        soft: 1048576
+        hard: 1048576
+```
+
+---
+## 2. Тонкая настройка сетевого стека ядра (`sysctl`)
+Создайте выделенный файл `/etc/sysctl.d/99-telemt-highload.conf` и примените его через `sysctl -p /etc/sysctl.d/99-telemt-highload.conf`.
+### 2.1 Очереди соединений и защита от SYN-флуда
+Увеличьте размеры очередей, чтобы поглощать внезапные всплески соединений и смягчить атаки типа SYN flood:
+```ini
+net.core.somaxconn = 65535
+net.core.netdev_max_backlog = 65535
+net.ipv4.tcp_max_syn_backlog = 65535
+net.ipv4.tcp_syncookies = 1
+```
+### 2.2 Исчерпание портов и TIME-WAIT сокеты
+Высокая текучесть приводит к нехватке временных (ephemeral) портов. Расширьте диапазон портов и позвольте ядру быстро переиспользовать закрытые сокеты:
+```ini
+net.ipv4.ip_local_port_range = 10000 65535
+net.ipv4.tcp_fin_timeout = 15
+net.ipv4.tcp_tw_reuse = 1
+net.ipv4.tcp_max_tw_buckets = 2000000
+```
+### 2.3 TCP Keepalive (Агрессивная очистка мертвых соединений)
+По умолчанию Linux держит "оборванные" TCP-сессии более 2 часов. Задайте параметры для обнаружения и сброса мертвых соединений за менее чем 5 минут:
+```ini
+net.ipv4.tcp_keepalive_time = 300
+net.ipv4.tcp_keepalive_intvl = 30
+net.ipv4.tcp_keepalive_probes = 5
+```
+### 2.4 Буферы TCP и управление перегрузками (Congestion Control)
+Оптимизируйте использование памяти на сокет и переключитесь на алгоритм BBR (Bottleneck Bandwidth and Round-trip propagation time) для улучшения задержки на плохих сетях:
+```ini
+# Размеры буферов ядра (по умолчанию и макс)
+net.core.rmem_default = 262144
+net.core.wmem_default = 262144
+net.core.rmem_max = 16777216
+net.core.wmem_max = 16777216
+# Специфичные TCP буферы (min, default, max)
+net.ipv4.tcp_rmem = 4096 87380 16777216
+net.ipv4.tcp_wmem = 4096 65536 16777216
+# Включение BBR
+net.core.default_qdisc = fq
+net.ipv4.tcp_congestion_control = bbr
+```
+
+---
+## 3. Тюнинг Conntrack (Netfilter)
+Если ваш сервер использует `iptables`, `ufw` или `firewalld`, ядро вынуждено отслеживать каждое соединение в таблице состояний (`nf_conntrack`). Когда эта таблица переполняется, Linux отбрасывает новые пакеты без уведомления приложения.
+Проверьте текущие лимиты и использование:
+```bash
+sysctl net.netfilter.nf_conntrack_max
+sysctl net.netfilter.nf_conntrack_count
+```
+Если вы близки к пределу, увеличьте таблицу и заставьте ядро быстрее удалять установленные соединения. Добавьте в `/etc/sysctl.d/99-telemt-highload.conf`:
+```ini
+net.netfilter.nf_conntrack_max = 2097152
+# Снижаем таймаут с дефолтных 5 дней до 1 часа
+net.netfilter.nf_conntrack_tcp_timeout_established = 3600
+net.netfilter.nf_conntrack_tcp_timeout_time_wait = 12
+```
+*Внимание: в зависимости от ОС, вам может потребоваться выполнить `modprobe nf_conntrack` перед установкой этих параметров.*
+
+---
+## 4. Архитектура: Развертывание за HAProxy
+Для максимальных нагрузок выставление Telemt напрямую в интернет менее эффективно, чем использование оптимизированного L4-балансировщика. HAProxy эффективен в поглощении TCP атак, обработке рукопожатий и сглаживании всплесков подключений.
+### Оптимизация `haproxy.cfg` для High-Load
+```haproxy
+global
+    # Отключить детальные логи соединений под нагрузкой
+    log stdout format raw local0 err
+    maxconn 250000
+    # Тюнинг буферов и приема сокетов
+    tune.bufsize 16384
+    tune.maxaccept 64
+defaults
+    log     global
+    mode    tcp
+    option  clitcpka
+    option  srvtcpka
+    timeout connect 5s
+    timeout client  1h
+    timeout server  1h
+    # Быстрая очистка мертвых пиров
+    timeout client-fin 10s
+    timeout server-fin 10s
+frontend proxy_in
+    bind *:443
+    maxconn 250000
+    option tcp-smart-accept
+    default_backend telemt_backend
+backend telemt_backend
+    option tcp-smart-connect
+    # Send-Proxy-V2 обязателен для сохранения IP клиента внутри внутренней логики Telemt
+    server telemt_core 10.10.10.1:443 maxconn 250000 send-proxy-v2 check inter 5s
+```
+**Важно**: Telemt должен быть настроен на обработку протокола `PROXY` на порту `443`, чтобы получать оригинальные IP-адреса клиентов.
+
+---
+## 5. Диагностика
+Команды для выявления узких мест:
+* **Проверка дропов TCP (переполнение очередей)**: `netstat -s | grep "times the listen queue of a socket overflowed"`
+* **Контроль отбрасывания пакетов Conntrack**: `dmesg | grep conntrack`
+* **Проверка использования файловых дескрипторов**: `cat /proc/sys/fs/file-nr`
+* **Отображение состояния сокетов**: `ss -s` (Избегайте использования `netstat` под высокой нагрузкой).

docs/Architecture/API/API.md

@@ -9,12 +9,12 @@ API runtime is configured in `[server.api]`.
 
 | Field | Type | Default | Description |
 | --- | --- | --- | --- |
-| `enabled` | `bool` | `false` | Enables REST API listener. |
-| `listen` | `string` (`IP:PORT`) | `127.0.0.1:9091` | API bind address. |
-| `whitelist` | `CIDR[]` | `127.0.0.1/32, ::1/128` | Source IP allowlist. Empty list means allow all. |
+| `enabled` | `bool` | `true` | Enables REST API listener. |
+| `listen` | `string` (`IP:PORT`) | `0.0.0.0:9091` | API bind address. |
+| `whitelist` | `CIDR[]` | `127.0.0.0/8` | Source IP allowlist. Empty list means allow all. |
 | `auth_header` | `string` | `""` | Exact value for `Authorization` header. Empty disables header auth. |
-| `request_body_limit_bytes` | `usize` | `65536` | Maximum request body size. Must be `> 0`. |
-| `minimal_runtime_enabled` | `bool` | `false` | Enables runtime snapshot endpoints requiring ME pool read-lock aggregation. |
+| `request_body_limit_bytes` | `usize` | `65536` | Maximum request body size. Must be within `[1, 1048576]`. |
+| `minimal_runtime_enabled` | `bool` | `true` | Enables runtime snapshot endpoints requiring ME pool read-lock aggregation. |
 | `minimal_runtime_cache_ttl_ms` | `u64` | `1000` | Cache TTL for minimal snapshots. `0` disables cache; valid range is `[0, 60000]`. |
 | `runtime_edge_enabled` | `bool` | `false` | Enables runtime edge endpoints with cached aggregation payloads. |
 | `runtime_edge_cache_ttl_ms` | `u64` | `1000` | Cache TTL for runtime edge summary payloads. `0` disables cache. |
@@ -26,7 +26,7 @@ API runtime is configured in `[server.api]`.
 
 Runtime validation for API config:
 - `server.api.listen` must be a valid `IP:PORT`.
-- `server.api.request_body_limit_bytes` must be `> 0`.
+- `server.api.request_body_limit_bytes` must be within `[1, 1048576]`.
 - `server.api.minimal_runtime_cache_ttl_ms` must be within `[0, 60000]`.
 - `server.api.runtime_edge_cache_ttl_ms` must be within `[0, 60000]`.
 - `server.api.runtime_edge_top_n` must be within `[1, 1000]`.
@@ -76,13 +76,14 @@ Requests are processed in this order:
 
 Notes:
 - Whitelist is evaluated against the direct TCP peer IP (`SocketAddr::ip`), without `X-Forwarded-For` support.
-- `Authorization` check is exact string equality against configured `auth_header`.
+- `Authorization` check is exact constant-time byte equality against configured `auth_header`.
 
 ## Endpoint Matrix
 
 | Method | Path | Body | Success | `data` contract |
 | --- | --- | --- | --- | --- |
 | `GET` | `/v1/health` | none | `200` | `HealthData` |
+| `GET` | `/v1/health/ready` | none | `200` or `503` | `HealthReadyData` |
 | `GET` | `/v1/system/info` | none | `200` | `SystemInfoData` |
 | `GET` | `/v1/runtime/gates` | none | `200` | `RuntimeGatesData` |
 | `GET` | `/v1/runtime/initialization` | none | `200` | `RuntimeInitializationData` |
@@ -102,13 +103,50 @@ Notes:
 | `GET` | `/v1/runtime/me-selftest` | none | `200` | `RuntimeMeSelftestData` |
 | `GET` | `/v1/runtime/connections/summary` | none | `200` | `RuntimeEdgeConnectionsSummaryData` |
 | `GET` | `/v1/runtime/events/recent` | none | `200` | `RuntimeEdgeEventsData` |
+| `GET` | `/v1/stats/users/active-ips` | none | `200` | `UserActiveIps[]` |
 | `GET` | `/v1/stats/users` | none | `200` | `UserInfo[]` |
 | `GET` | `/v1/users` | none | `200` | `UserInfo[]` |
-| `POST` | `/v1/users` | `CreateUserRequest` | `201` | `CreateUserResponse` |
+| `POST` | `/v1/users` | `CreateUserRequest` | `201` or `202` | `CreateUserResponse` |
 | `GET` | `/v1/users/{username}` | none | `200` | `UserInfo` |
-| `PATCH` | `/v1/users/{username}` | `PatchUserRequest` | `200` | `UserInfo` |
-| `DELETE` | `/v1/users/{username}` | none | `200` | `string` (deleted username) |
-| `POST` | `/v1/users/{username}/rotate-secret` | `RotateSecretRequest` or empty body | `404` | `ErrorResponse` (`not_found`, current runtime behavior) |
+| `PATCH` | `/v1/users/{username}` | `PatchUserRequest` | `200` or `202` | `UserInfo` |
+| `DELETE` | `/v1/users/{username}` | none | `200` or `202` | `DeleteUserResponse` |
+| `POST` | `/v1/users/{username}/rotate-secret` | `RotateSecretRequest` or empty body | `200` or `202` | `CreateUserResponse` |
+| `POST` | `/v1/users/{username}/reset-quota` | empty body | `200` | `ResetUserQuotaResponse` |
+
+## Endpoint Behavior
+
+| Endpoint | Function |
+| --- | --- |
+| `GET /v1/health` | Returns basic API liveness and current `read_only` flag. |
+| `GET /v1/health/ready` | Returns readiness based on admission state and upstream health; returns `503` when not ready. |
+| `GET /v1/system/info` | Returns binary/build metadata, process uptime, config path/hash, and reload counters. |
+| `GET /v1/runtime/gates` | Returns admission, ME readiness, fallback/reroute, and startup gate state. |
+| `GET /v1/runtime/initialization` | Returns startup progress, ME initialization status, and per-component timeline. |
+| `GET /v1/limits/effective` | Returns effective timeout, upstream, ME, unique-IP, and TCP policy values after config defaults/resolution. |
+| `GET /v1/security/posture` | Returns current API/security/telemetry posture flags. |
+| `GET /v1/security/whitelist` | Returns configured API whitelist CIDRs. |
+| `GET /v1/stats/summary` | Returns compact core counters and classed failure counters. |
+| `GET /v1/stats/zero/all` | Returns zero-cost core, upstream, ME, pool, and desync counters. |
+| `GET /v1/stats/upstreams` | Returns upstream zero counters and, when enabled/available, runtime upstream health rows. |
+| `GET /v1/stats/minimal/all` | Returns cached minimal ME writer/DC/runtime/network-path snapshot. |
+| `GET /v1/stats/me-writers` | Returns cached ME writer coverage and per-writer status rows. |
+| `GET /v1/stats/dcs` | Returns cached per-DC endpoint/writer/load status rows. |
+| `GET /v1/runtime/me_pool_state` | Returns active/warm/pending/draining generation state, writer contour/health, and refill state. |
+| `GET /v1/runtime/me_quality` | Returns ME lifecycle counters, route-drop counters, family states, drain gate, and per-DC RTT/coverage. |
+| `GET /v1/runtime/upstream_quality` | Returns upstream policy/counters plus runtime upstream health rows when available. |
+| `GET /v1/runtime/nat_stun` | Returns NAT/STUN runtime flags, configured/live STUN servers, reflection cache, and backoff. |
+| `GET /v1/runtime/me-selftest` | Returns ME self-test state for KDF, time skew, IP family, PID, and SOCKS BND observations. |
+| `GET /v1/runtime/connections/summary` | Returns runtime-edge connection totals and top-N users by connections/throughput. |
+| `GET /v1/runtime/events/recent` | Returns recent API/runtime event records with optional `limit` query. |
+| `GET /v1/stats/users/active-ips` | Returns users that currently have non-empty active source-IP lists. |
+| `GET /v1/stats/users` | Alias of `GET /v1/users`; returns disk-first user views with runtime lag flag. |
+| `GET /v1/users` | Returns disk-first user views sorted by username. |
+| `POST /v1/users` | Creates a user and returns the effective user view plus secret. |
+| `GET /v1/users/{username}` | Returns one disk-first user view or `404` when absent. |
+| `PATCH /v1/users/{username}` | Updates selected per-user fields with JSON Merge Patch semantics. |
+| `DELETE /v1/users/{username}` | Deletes one user and related per-user access-map entries. |
+| `POST /v1/users/{username}/rotate-secret` | Rotates one user's secret and returns the effective secret. |
+| `POST /v1/users/{username}/reset-quota` | Resets one user's runtime quota counter and persists quota state. |
 
 ## Common Error Codes
 
@@ -118,7 +156,7 @@ Notes:
 | `401` | `unauthorized` | Missing/invalid `Authorization` when `auth_header` is configured. |
 | `403` | `forbidden` | Source IP is not allowed by whitelist. |
 | `403` | `read_only` | Mutating endpoint called while `read_only=true`. |
-| `404` | `not_found` | Unknown route, unknown user, or unsupported sub-route (including current `rotate-secret` route). |
+| `404` | `not_found` | Unknown route, unknown user, or unsupported sub-route. |
 | `405` | `method_not_allowed` | Unsupported method for `/v1/users/{username}` route shape. |
 | `409` | `revision_conflict` | `If-Match` revision mismatch. |
 | `409` | `user_exists` | User already exists on create. |
@@ -132,11 +170,12 @@ Notes:
 | Case | Behavior |
 | --- | --- |
 | Path matching | Exact match on `req.uri().path()`. Query string does not affect route matching. |
-| Trailing slash | Not normalized. Example: `/v1/users/` is `404`. |
+| Trailing slash | Trimmed for route matching when path length is greater than 1. Example: `/v1/users/` matches `/v1/users`. |
 | Username route with extra slash | `/v1/users/{username}/...` is not treated as user route and returns `404`. |
 | `PUT /v1/users/{username}` | `405 method_not_allowed`. |
 | `POST /v1/users/{username}` | `404 not_found`. |
-| `POST /v1/users/{username}/rotate-secret` | `404 not_found` in current release due route matcher limitation. |
+| `POST /v1/users/{username}/rotate-secret/` | Trailing slash is trimmed and the route matches `rotate-secret`. |
+| `POST /v1/users/{username}/reset-quota/` | Trailing slash is trimmed and the route matches `reset-quota`. |
 
 ## Body and JSON Semantics
 
@@ -146,7 +185,7 @@ Notes:
 - Invalid JSON returns `400 bad_request` (`Invalid JSON body`).
 - `Content-Type` is not required for JSON parsing.
 - Unknown JSON fields are ignored by deserialization.
-- `PATCH` updates only provided fields and does not support explicit clearing of optional fields.
+- `PATCH` uses JSON Merge Patch semantics for optional per-user fields: omitted means unchanged, explicit `null` removes the config entry, and a non-null value sets it.
 - `If-Match` supports both quoted and unquoted values; surrounding whitespace is trimmed.
 
 ## Query Parameters
@@ -172,18 +211,33 @@ Notes:
 | Field | Type | Required | Description |
 | --- | --- | --- | --- |
 | `secret` | `string` | no | Exactly 32 hex chars. |
-| `user_ad_tag` | `string` | no | Exactly 32 hex chars. |
-| `max_tcp_conns` | `usize` | no | Per-user concurrent TCP limit. |
-| `expiration_rfc3339` | `string` | no | RFC3339 expiration timestamp. |
-| `data_quota_bytes` | `u64` | no | Per-user traffic quota. |
-| `max_unique_ips` | `usize` | no | Per-user unique source IP limit. |
+| `user_ad_tag` | `string|null` | no | Exactly 32 hex chars; `null` removes the per-user ad tag. |
+| `max_tcp_conns` | `usize|null` | no | Per-user concurrent TCP limit; `null` removes the per-user override. |
+| `expiration_rfc3339` | `string|null` | no | RFC3339 expiration timestamp; `null` removes the expiration. |
+| `data_quota_bytes` | `u64|null` | no | Per-user traffic quota; `null` removes the per-user quota. |
+| `max_unique_ips` | `usize|null` | no | Per-user unique source IP limit; `null` removes the per-user override. |
+
+### `access.user_source_deny` via API
+- In current API surface, per-user deny-list is **not** exposed as a dedicated field in `CreateUserRequest` / `PatchUserRequest`.
+- Configure it in `config.toml` under `[access.user_source_deny]` and apply via normal config reload path.
+- Runtime behavior after apply:
+  - auth succeeds for username/secret
+  - source IP is checked against `access.user_source_deny[username]`
+  - on match, handshake is rejected with the same fail-closed outcome as invalid auth
+
+Example config:
+```toml
+[access.user_source_deny]
+alice = ["203.0.113.0/24", "2001:db8:abcd::/48"]
+bob = ["198.51.100.42/32"]
+```
 
 ### `RotateSecretRequest`
 | Field | Type | Required | Description |
 | --- | --- | --- | --- |
 | `secret` | `string` | no | Exactly 32 hex chars. If missing, generated automatically. |
 
-Note: the request contract is defined, but the corresponding route currently returns `404` (see routing edge cases).
+An empty request body is accepted and generates a new secret automatically.
 
 ## Response Data Contracts
 
@@ -193,15 +247,33 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `status` | `string` | Always `"ok"`. |
 | `read_only` | `bool` | Mirrors current API `read_only` mode. |
 
+### `HealthReadyData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `ready` | `bool` | `true` when admission is open and at least one upstream is healthy. |
+| `status` | `string` | `"ready"` or `"not_ready"`. |
+| `reason` | `string?` | `admission_closed` or `no_healthy_upstreams` when not ready. |
+| `admission_open` | `bool` | Current admission-gate state. |
+| `healthy_upstreams` | `usize` | Number of healthy upstream entries. |
+| `total_upstreams` | `usize` | Number of configured upstream entries. |
+
 ### `SummaryData`
 | Field | Type | Description |
 | --- | --- | --- |
 | `uptime_seconds` | `f64` | Process uptime in seconds. |
 | `connections_total` | `u64` | Total accepted client connections. |
 | `connections_bad_total` | `u64` | Failed/invalid client connections. |
+| `connections_bad_by_class` | `ClassCount[]` | Failed/invalid connections grouped by class. |
+| `handshake_failures_by_class` | `ClassCount[]` | Handshake failures grouped by class. |
 | `handshake_timeouts_total` | `u64` | Handshake timeout count. |
 | `configured_users` | `usize` | Number of configured users in config. |
 
+#### `ClassCount`
+| Field | Type | Description |
+| --- | --- | --- |
+| `class` | `string` | Failure class label. |
+| `total` | `u64` | Counter value for this class. |
+
 ### `SystemInfoData`
 | Field | Type | Description |
 | --- | --- | --- |
@@ -226,7 +298,12 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `conditional_cast_enabled` | `bool` | Whether conditional ME admission logic is enabled (`general.use_middle_proxy`). |
 | `me_runtime_ready` | `bool` | Current ME runtime readiness status used for conditional gate decisions. |
 | `me2dc_fallback_enabled` | `bool` | Whether ME -> direct fallback is enabled. |
+| `me2dc_fast_enabled` | `bool` | Whether fast ME -> direct fallback is enabled. |
 | `use_middle_proxy` | `bool` | Current transport mode preference. |
+| `route_mode` | `string` | Current route mode label from route runtime controller. |
+| `reroute_active` | `bool` | `true` when ME fallback currently routes new sessions to Direct-DC. |
+| `reroute_to_direct_at_epoch_secs` | `u64?` | Unix timestamp when current direct reroute began. |
+| `reroute_reason` | `string?` | `fast_not_ready_fallback` or `strict_grace_fallback` while reroute is active. |
 | `startup_status` | `string` | Startup status (`pending`, `initializing`, `ready`, `failed`, `skipped`). |
 | `startup_stage` | `string` | Current startup stage identifier. |
 | `startup_progress_pct` | `f64` | Startup progress percentage (`0..100`). |
@@ -277,11 +354,13 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `upstream` | `EffectiveUpstreamLimits` | Effective upstream connect/retry limits. |
 | `middle_proxy` | `EffectiveMiddleProxyLimits` | Effective ME pool/floor/reconnect limits. |
 | `user_ip_policy` | `EffectiveUserIpPolicyLimits` | Effective unique-IP policy mode/window. |
+| `user_tcp_policy` | `EffectiveUserTcpPolicyLimits` | Effective per-user TCP connection policy. |
 
 #### `EffectiveTimeoutLimits`
 | Field | Type | Description |
 | --- | --- | --- |
 | `client_handshake_secs` | `u64` | Client handshake timeout. |
+| `client_first_byte_idle_secs` | `u64` | First-byte idle timeout before protocol classification. |
 | `tg_connect_secs` | `u64` | Upstream Telegram connect timeout. |
 | `client_keepalive_secs` | `u64` | Client keepalive interval. |
 | `client_ack_secs` | `u64` | ACK timeout. |
@@ -320,13 +399,20 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `writer_pick_mode` | `string` | Writer picker mode (`sorted_rr`, `p2c`). |
 | `writer_pick_sample_size` | `u8` | Candidate sample size for `p2c` picker mode. |
 | `me2dc_fallback` | `bool` | Effective ME -> direct fallback flag. |
+| `me2dc_fast` | `bool` | Effective fast fallback flag. |
 
 #### `EffectiveUserIpPolicyLimits`
 | Field | Type | Description |
 | --- | --- | --- |
+| `global_each` | `usize` | Global per-user unique-IP limit applied when no per-user override exists. |
 | `mode` | `string` | Unique-IP policy mode (`active_window`, `time_window`, `combined`). |
 | `window_secs` | `u64` | Time window length used by unique-IP policy. |
 
+#### `EffectiveUserTcpPolicyLimits`
+| Field | Type | Description |
+| --- | --- | --- |
+| `global_each` | `usize` | Global per-user concurrent TCP limit applied when no per-user override exists. |
+
 ### `SecurityPostureData`
 | Field | Type | Description |
 | --- | --- | --- |
@@ -430,6 +516,8 @@ Note: the request contract is defined, but the corresponding route currently ret
 | --- | --- | --- |
 | `counters` | `RuntimeMeQualityCountersData` | Key ME lifecycle/error counters. |
 | `route_drops` | `RuntimeMeQualityRouteDropData` | Route drop counters by reason. |
+| `family_states` | `RuntimeMeQualityFamilyStateData[]` | Per-family ME route/recovery state rows. |
+| `drain_gate` | `RuntimeMeQualityDrainGateData` | Current ME drain-gate decision state. |
 | `dc_rtt` | `RuntimeMeQualityDcRttData[]` | Per-DC RTT and writer coverage rows. |
 
 #### `RuntimeMeQualityCountersData`
@@ -451,6 +539,24 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `queue_full_base_total` | `u64` | Route drops in base-queue path. |
 | `queue_full_high_total` | `u64` | Route drops in high-priority queue path. |
 
+#### `RuntimeMeQualityFamilyStateData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `family` | `string` | Address family label. |
+| `state` | `string` | Current family state label. |
+| `state_since_epoch_secs` | `u64` | Unix timestamp when current state began. |
+| `suppressed_until_epoch_secs` | `u64?` | Unix timestamp until suppression remains active. |
+| `fail_streak` | `u32` | Consecutive failure count. |
+| `recover_success_streak` | `u32` | Consecutive recovery success count. |
+
+#### `RuntimeMeQualityDrainGateData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `route_quorum_ok` | `bool` | Whether route quorum condition allows drain. |
+| `redundancy_ok` | `bool` | Whether redundancy condition allows drain. |
+| `block_reason` | `string` | Current drain block reason label. |
+| `updated_at_epoch_secs` | `u64` | Unix timestamp of the latest gate update. |
+
 #### `RuntimeMeQualityDcRttData`
 | Field | Type | Description |
 | --- | --- | --- |
@@ -713,11 +819,24 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `uptime_seconds` | `f64` | Process uptime. |
 | `connections_total` | `u64` | Total accepted connections. |
 | `connections_bad_total` | `u64` | Failed/invalid connections. |
+| `connections_bad_by_class` | `ClassCount[]` | Failed/invalid connections grouped by class. |
+| `handshake_failures_by_class` | `ClassCount[]` | Handshake failures grouped by class. |
 | `handshake_timeouts_total` | `u64` | Handshake timeouts. |
+| `accept_permit_timeout_total` | `u64` | Listener admission permit acquisition timeouts. |
 | `configured_users` | `usize` | Configured user count. |
 | `telemetry_core_enabled` | `bool` | Core telemetry toggle. |
 | `telemetry_user_enabled` | `bool` | User telemetry toggle. |
 | `telemetry_me_level` | `string` | ME telemetry level (`off|normal|verbose`). |
+| `conntrack_control_enabled` | `bool` | Whether conntrack control is enabled by policy. |
+| `conntrack_control_available` | `bool` | Whether conntrack control backend is currently available. |
+| `conntrack_pressure_active` | `bool` | Current conntrack pressure flag. |
+| `conntrack_event_queue_depth` | `u64` | Current conntrack close-event queue depth. |
+| `conntrack_rule_apply_ok` | `bool` | Last conntrack rule application state. |
+| `conntrack_delete_attempt_total` | `u64` | Conntrack delete attempts. |
+| `conntrack_delete_success_total` | `u64` | Successful conntrack deletes. |
+| `conntrack_delete_not_found_total` | `u64` | Conntrack delete misses. |
+| `conntrack_delete_error_total` | `u64` | Conntrack delete errors. |
+| `conntrack_close_event_drop_total` | `u64` | Dropped conntrack close events. |
 
 #### `ZeroUpstreamData`
 | Field | Type | Description |
@@ -804,6 +923,24 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `route_drop_queue_full_total` | `u64` | Route drops due to full queue (total). |
 | `route_drop_queue_full_base_total` | `u64` | Route drops in base queue mode. |
 | `route_drop_queue_full_high_total` | `u64` | Route drops in high queue mode. |
+| `d2c_batches_total` | `u64` | ME D->C batch flushes. |
+| `d2c_batch_frames_total` | `u64` | ME D->C frames included in batches. |
+| `d2c_batch_bytes_total` | `u64` | ME D->C payload bytes included in batches. |
+| `d2c_flush_reason_queue_drain_total` | `u64` | Flushes caused by queue drain. |
+| `d2c_flush_reason_batch_frames_total` | `u64` | Flushes caused by frame-count batch limit. |
+| `d2c_flush_reason_batch_bytes_total` | `u64` | Flushes caused by byte-count batch limit. |
+| `d2c_flush_reason_max_delay_total` | `u64` | Flushes caused by max-delay budget. |
+| `d2c_flush_reason_ack_immediate_total` | `u64` | Flushes caused by immediate ACK policy. |
+| `d2c_flush_reason_close_total` | `u64` | Flushes caused by close path. |
+| `d2c_data_frames_total` | `u64` | ME D->C data frames. |
+| `d2c_ack_frames_total` | `u64` | ME D->C ACK frames. |
+| `d2c_payload_bytes_total` | `u64` | ME D->C payload bytes. |
+| `d2c_write_mode_coalesced_total` | `u64` | Coalesced D->C writes. |
+| `d2c_write_mode_split_total` | `u64` | Split D->C writes. |
+| `d2c_quota_reject_pre_write_total` | `u64` | D->C quota rejects before write. |
+| `d2c_quota_reject_post_write_total` | `u64` | D->C quota rejects after write. |
+| `d2c_frame_buf_shrink_total` | `u64` | D->C frame-buffer shrink operations. |
+| `d2c_frame_buf_shrink_bytes_total` | `u64` | Bytes released by D->C frame-buffer shrink operations. |
 | `socks_kdf_strict_reject_total` | `u64` | SOCKS KDF strict rejects. |
 | `socks_kdf_compat_fallback_total` | `u64` | SOCKS KDF compat fallbacks. |
 | `endpoint_quarantine_total` | `u64` | Endpoint quarantine activations. |
@@ -963,6 +1100,8 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `required_writers` | `usize` | Required writers based on current floor policy. |
 | `alive_writers` | `usize` | Writers currently alive. |
 | `coverage_pct` | `f64` | `alive_writers / required_writers * 100`. |
+| `fresh_alive_writers` | `usize` | Alive writers that match freshness requirements. |
+| `fresh_coverage_pct` | `f64` | `fresh_alive_writers / required_writers * 100`. |
 
 #### `MeWriterStatus`
 | Field | Type | Description |
@@ -977,6 +1116,12 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `bound_clients` | `usize` | Number of currently bound clients. |
 | `idle_for_secs` | `u64?` | Idle age in seconds if idle. |
 | `rtt_ema_ms` | `f64?` | RTT exponential moving average. |
+| `matches_active_generation` | `bool` | Whether this writer belongs to the active pool generation. |
+| `in_desired_map` | `bool` | Whether this writer's endpoint remains in desired topology. |
+| `allow_drain_fallback` | `bool` | Whether drain fallback is allowed for this writer. |
+| `drain_started_at_epoch_secs` | `u64?` | Unix timestamp when drain started. |
+| `drain_deadline_epoch_secs` | `u64?` | Unix timestamp of drain deadline. |
+| `drain_over_ttl` | `bool` | Whether drain has exceeded its TTL. |
 
 ### `DcStatusData`
 | Field | Type | Description |
@@ -1001,6 +1146,8 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `floor_capped` | `bool` | `true` when computed floor target was capped by active limits. |
 | `alive_writers` | `usize` | Alive writers in this DC. |
 | `coverage_pct` | `f64` | `alive_writers / required_writers * 100`. |
+| `fresh_alive_writers` | `usize` | Fresh alive writers in this DC. |
+| `fresh_coverage_pct` | `f64` | `fresh_alive_writers / required_writers * 100`. |
 | `rtt_ms` | `f64?` | Aggregated RTT for DC. |
 | `load` | `usize` | Active client sessions bound to this DC. |
 
@@ -1014,6 +1161,7 @@ Note: the request contract is defined, but the corresponding route currently ret
 | Field | Type | Description |
 | --- | --- | --- |
 | `username` | `string` | Username. |
+| `in_runtime` | `bool` | Whether current runtime config already contains this user. |
 | `user_ad_tag` | `string?` | Optional ad tag (32 hex chars). |
 | `max_tcp_conns` | `usize?` | Optional max concurrent TCP limit. |
 | `expiration_rfc3339` | `string?` | Optional expiration timestamp. |
@@ -1027,12 +1175,25 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `total_octets` | `u64` | Total traffic octets for this user. |
 | `links` | `UserLinks` | Active connection links derived from current config. |
 
+### `UserActiveIps`
+| Field | Type | Description |
+| --- | --- | --- |
+| `username` | `string` | Username with at least one active tracked source IP. |
+| `active_ips` | `ip[]` | Active source IPs for this user. |
+
 #### `UserLinks`
 | Field | Type | Description |
 | --- | --- | --- |
 | `classic` | `string[]` | Active `tg://proxy` links for classic mode. |
 | `secure` | `string[]` | Active `tg://proxy` links for secure/DD mode. |
 | `tls` | `string[]` | Active `tg://proxy` links for EE-TLS mode (for each host+TLS domain). |
+| `tls_domains` | `TlsDomainLink[]` | Extra TLS-domain links as explicit domain/link pairs for `censorship.tls_domains`. |
+
+#### `TlsDomainLink`
+| Field | Type | Description |
+| --- | --- | --- |
+| `domain` | `string` | TLS domain represented by the link. |
+| `link` | `string` | `tg://proxy` link for this domain. |
 
 Link generation uses active config and enabled modes:
 - Link port is `general.links.public_port` when configured; otherwise `server.port`.
@@ -1052,13 +1213,27 @@ Link generation uses active config and enabled modes:
 | `user` | `UserInfo` | Created or updated user view. |
 | `secret` | `string` | Effective user secret. |
 
+### `DeleteUserResponse`
+| Field | Type | Description |
+| --- | --- | --- |
+| `username` | `string` | Deleted username. |
+| `in_runtime` | `bool` | `true` when runtime config still contains the user and hot-reload has not applied deletion yet. |
+
+### `ResetUserQuotaResponse`
+| Field | Type | Description |
+| --- | --- | --- |
+| `username` | `string` | User whose runtime quota counter was reset. |
+| `used_bytes` | `u64` | Current used bytes after reset; always `0` on success. |
+| `last_reset_epoch_secs` | `u64` | Unix timestamp of the reset operation. |
+
 ## Mutation Semantics
 
 | Endpoint | Notes |
 | --- | --- |
 | `POST /v1/users` | Creates user, validates config, then atomically updates only affected `access.*` TOML tables (`access.users` always, plus optional per-user tables present in request). |
-| `PATCH /v1/users/{username}` | Partial update of provided fields only. Missing fields remain unchanged. Current implementation persists full config document on success. |
-| `POST /v1/users/{username}/rotate-secret` | Currently returns `404` in runtime route matcher; request schema is reserved for intended behavior. |
+| `PATCH /v1/users/{username}` | Partial update of provided fields only. Missing fields remain unchanged; explicit `null` removes optional per-user entries. The write path updates only affected `access.*` TOML tables. |
+| `POST /v1/users/{username}/rotate-secret` | Replaces the user's secret with a provided valid 32-hex value or a generated value, then returns the effective secret in `CreateUserResponse`. |
+| `POST /v1/users/{username}/reset-quota` | Resets the runtime quota counter for the route username, persists quota state to `general.quota_state_path`, and does not modify user config. |
 | `DELETE /v1/users/{username}` | Deletes only specified user, removes this user from related optional `access.user_*` maps, blocks last-user deletion, and atomically updates only related `access.*` TOML tables. |
 
 All mutating endpoints:
@@ -1133,5 +1308,4 @@ When `general.use_middle_proxy=true` and `general.me2dc_fallback=true`:
 
 ## Known Limitations (Current Release)
 
-- `POST /v1/users/{username}/rotate-secret` is currently unreachable in route matcher and returns `404`.
 - API runtime controls under `server.api` are documented as restart-required; hot-reload behavior for these fields is not strictly uniform in all change combinations.

docs/Architecture/Fronting-splitting/TLS_FRONT_PROFILE_FIDELITY.en.md

@@ -0,0 +1,266 @@
+# TLS Front Profile Fidelity
+
+## Overview
+
+This document describes how Telemt reuses captured TLS behavior in the FakeTLS server flight and how to validate the result on a real deployment.
+
+When TLS front emulation is enabled, Telemt can capture useful server-side TLS behavior from the selected origin and reuse that behavior in the emulated success path. The goal is not to reproduce the origin byte-for-byte, but to reduce stable synthetic traits and make the emitted server flight structurally closer to the captured profile.
+
+## Why this change exists
+
+The project already captures useful server-side TLS behavior in the TLS front fetch path:
+
+- `change_cipher_spec_count`
+- `app_data_record_sizes`
+- `ticket_record_sizes`
+
+Before this change, the emulator used only part of that information. This left a gap between captured origin behavior and emitted FakeTLS server flight.
+
+## What is implemented
+
+- The emulator now replays the observed `ChangeCipherSpec` count from the fetched behavior profile.
+- The emulator now replays observed ticket-like tail ApplicationData record sizes when raw or merged TLS profile data is available.
+- The emulator now preserves more of the profiled encrypted-flight structure instead of collapsing it into a smaller synthetic shape.
+- The emulator still falls back to the previous synthetic behavior when the cached profile does not contain raw TLS behavior information.
+- Operator-configured `tls_new_session_tickets` still works as an additive fallback when the profile does not provide enough tail records.
+
+## Practical benefit
+
+- Reduced distinguishability between profiled origin TLS behavior and emulated TLS behavior.
+- Lower chance of stable server-flight fingerprints caused by fixed CCS count or synthetic-only tail record sizes.
+- Better reuse of already captured TLS profile data without changing MTProto logic, KDF routing, or transport architecture.
+
+## Limitations
+
+This mechanism does not aim to make Telemt byte-identical to the origin server.
+
+It also does not change:
+
+- MTProto business logic;
+- KDF routing behavior;
+- the overall transport architecture.
+
+The practical goal is narrower:
+
+- reuse more captured profile data;
+- reduce fixed synthetic behavior in the server flight;
+- preserve a valid FakeTLS success path while changing the emitted shape on the wire.
+
+## Validation targets
+
+- Correct count of emulated `ChangeCipherSpec` records.
+- Correct replay of observed ticket-tail record sizes.
+- No regression in existing ALPN and payload-placement behavior.
+
+## How to validate the result
+
+Recommended validation consists of two layers:
+
+- focused unit and security tests for CCS-count replay and ticket-tail replay;
+- real packet-capture comparison for a selected origin and a successful FakeTLS session.
+
+When testing on the network, the expected result is:
+
+- a valid FakeTLS and MTProto success path is preserved;
+- the early encrypted server flight changes shape when richer profile data is available;
+- the change is visible on the wire without changing MTProto logic or transport architecture.
+
+This validation is intended to show better reuse of captured TLS profile data.
+It is not intended to prove byte-level equivalence with the real origin server.
+
+## How to test on a real deployment
+
+The strongest practical validation is a side-by-side trace comparison between:
+
+- a real TLS origin server used as `mask_host`;
+- a Telemt FakeTLS success-path connection for the same SNI;
+- optional captures from different Telemt builds or configurations.
+
+The purpose of the comparison is to inspect the shape of the server flight:
+
+- record order;
+- count of `ChangeCipherSpec` records;
+- count and grouping of early encrypted `ApplicationData` records;
+- lengths of tail or continuation `ApplicationData` records.
+
+## Recommended environment
+
+Use a Linux host or Docker container for the cleanest reproduction.
+
+Recommended setup:
+
+1. One Telemt instance.
+2. One real HTTPS origin as `mask_host`.
+3. One Telegram client configured with an `ee` proxy link for the Telemt instance.
+4. `tcpdump` or Wireshark available for capture analysis.
+
+## Step-by-step test procedure
+
+### 1. Prepare the origin
+
+1. Choose a real HTTPS origin.
+2. Set both `censorship.tls_domain` and `censorship.mask_host` to that hostname.
+3. Confirm that a direct TLS request works:
+
+```bash
+openssl s_client -connect ORIGIN_IP:443 -servername YOUR_DOMAIN </dev/null
+```
+
+### 2. Configure Telemt
+
+Use a configuration that enables:
+
+- `censorship.mask = true`
+- `censorship.tls_emulation = true`
+- `censorship.mask_host`
+- `censorship.mask_port`
+
+Recommended for cleaner testing:
+
+- keep `censorship.tls_new_session_tickets = 0`, so the result depends primarily on fetched profile data rather than operator-forced synthetic tail records;
+- keep `censorship.tls_fetch.strict_route = true`, if cleaner provenance for captured profile data is important.
+
+### 3. Refresh TLS profile data
+
+1. Start Telemt.
+2. Let it fetch TLS front profile data for the configured domain.
+3. If `tls_front_dir` is persisted, confirm that the TLS front cache is populated.
+
+Persisted cache artifacts are useful, but they are not required if packet captures already demonstrate the runtime result.
+
+### 4. Check TLS-front profile health metrics
+
+If the metrics endpoint is enabled, check the TLS-front profile health before packet-capture validation:
+
+```bash
+curl -s http://127.0.0.1:9999/metrics | grep -E 'telemt_tls_front_profile|telemt_tls_fetch_profile_cache|telemt_tls_front_full_cert'
+```
+
+The profile-health metrics expose the runtime state of configured TLS front domains:
+
+- `telemt_tls_front_profile_domains` shows configured, emitted, and suppressed domain series.
+- `telemt_tls_front_profile_info` shows profile source and feature flags per domain.
+- `telemt_tls_front_profile_age_seconds` shows cached profile age.
+- `telemt_tls_front_profile_app_data_records` shows cached AppData record count.
+- `telemt_tls_front_profile_ticket_records` shows cached ticket-like tail record count.
+- `telemt_tls_front_profile_change_cipher_spec_records` shows cached ChangeCipherSpec count.
+- `telemt_tls_front_profile_app_data_bytes` shows total cached AppData bytes.
+
+Interpretation:
+
+- `source="merged"` or `source="raw"` means real TLS profile data is being used.
+- `source="default"` or `is_default="true"` means the domain currently uses the synthetic default fallback.
+- `has_cert_payload="true"` means certificate payload data is available for TLS emulation.
+- Non-zero AppData/ticket/CCS counters show captured server-flight shape.
+
+Example healthy output:
+
+```text
+telemt_tls_front_profile_domains{status="configured"} 1
+telemt_tls_front_profile_domains{status="emitted"} 1
+telemt_tls_front_profile_domains{status="suppressed"} 0
+telemt_tls_front_profile_info{domain="itunes.apple.com",source="merged",is_default="false",has_cert_info="true",has_cert_payload="true"} 1
+telemt_tls_front_profile_age_seconds{domain="itunes.apple.com"} 20
+telemt_tls_front_profile_app_data_records{domain="itunes.apple.com"} 3
+telemt_tls_front_profile_ticket_records{domain="itunes.apple.com"} 1
+telemt_tls_front_profile_change_cipher_spec_records{domain="itunes.apple.com"} 1
+telemt_tls_front_profile_app_data_bytes{domain="itunes.apple.com"} 5240
+```
+
+These metrics do not prove byte-level origin equivalence. They are an operational health signal that the configured domain is backed by real cached profile data instead of default fallback data.
+
+### 5. Capture a direct-origin trace
+
+From a separate client host, connect directly to the origin:
+
+```bash
+openssl s_client -connect ORIGIN_IP:443 -servername YOUR_DOMAIN </dev/null
+```
+
+Capture with:
+
+```bash
+sudo tcpdump -i any -w origin-direct.pcap host ORIGIN_IP and port 443
+```
+
+### 6. Capture a Telemt FakeTLS success-path trace
+
+Now connect to Telemt with a real Telegram client through an `ee` proxy link that targets the Telemt instance.
+
+`openssl s_client` is useful for direct-origin capture and fallback sanity checks, but it does not exercise the successful FakeTLS and MTProto path.
+
+Capture with:
+
+```bash
+sudo tcpdump -i any -w telemt-emulated.pcap host TELEMT_IP and port 443
+```
+
+### 7. Decode TLS record structure
+
+Use `tshark` to print record-level structure:
+
+```bash
+tshark -r origin-direct.pcap -Y "tls.record" -T fields \
+  -e frame.number \
+  -e ip.src \
+  -e ip.dst \
+  -e tls.record.content_type \
+  -e tls.record.length
+```
+
+```bash
+tshark -r telemt-emulated.pcap -Y "tls.record" -T fields \
+  -e frame.number \
+  -e ip.src \
+  -e ip.dst \
+  -e tls.record.content_type \
+  -e tls.record.length
+```
+
+Focus on the server flight after ClientHello:
+
+- `22` = Handshake
+- `20` = ChangeCipherSpec
+- `23` = ApplicationData
+
+### 8. Build a comparison table
+
+A compact table like the following is usually enough:
+
+| Path | CCS count | AppData count in first encrypted flight | Tail AppData lengths |
+| --- | --- | --- | --- |
+| Origin | `N` | `M` | `[a, b, ...]` |
+| Telemt build A | `...` | `...` | `...` |
+| Telemt build B | `...` | `...` | `...` |
+
+The comparison should make it easy to see that:
+
+- the FakeTLS success path remains valid;
+- the early encrypted server flight changes when richer profile data is reused;
+- the result is backed by packet evidence.
+
+## Example capture set
+
+One practical example of this workflow uses:
+
+- `origin-direct-nginx.pcap`
+- `telemt-ee-before-nginx.pcap`
+- `telemt-ee-after-nginx.pcap`
+
+Practical notes:
+
+- `origin` was captured as a direct TLS 1.2 connection to `nginx.org`;
+- `before` and `after` were captured on the Telemt FakeTLS success path with a real Telegram client;
+- the first server-side FakeTLS response remains valid in both cases;
+- the early encrypted server-flight segmentation differs between `before` and `after`, which is consistent with better reuse of captured profile data;
+- this kind of result shows a wire-visible effect without breaking the success path, but it does not claim full indistinguishability from the origin.
+
+## Stronger validation
+
+For broader confidence, repeat the same comparison on:
+
+1. one CDN-backed origin;
+2. one regular nginx origin;
+3. one origin with a multi-record encrypted flight and visible ticket-like tails.
+
+If the same directional improvement appears across all three, confidence in the result will be much higher than for a single-origin example.

docs/Architecture/Fronting-splitting/TLS_FRONT_PROFILE_FIDELITY.ru.md

@@ -0,0 +1,266 @@
+# Fidelity TLS Front Profile
+
+## Обзор
+
+Этот документ описывает, как Telemt переиспользует захваченное TLS-поведение в FakeTLS server flight и как проверять результат на реальной инсталляции.
+
+Когда включена TLS front emulation, Telemt может собирать полезное серверное TLS-поведение выбранного origin и использовать его в emulated success path. Цель здесь не в побайтном копировании origin, а в уменьшении устойчивых synthetic признаков и в том, чтобы emitted server flight был структурно ближе к захваченному profile.
+
+## Зачем нужно это изменение
+
+Проект уже умеет собирать полезное серверное TLS-поведение в пути TLS front fetch:
+
+- `change_cipher_spec_count`
+- `app_data_record_sizes`
+- `ticket_record_sizes`
+
+До этого изменения эмулятор использовал только часть этой информации. Из-за этого оставался разрыв между захваченным поведением origin и тем FakeTLS server flight, который реально уходил на провод.
+
+## Что реализовано
+
+- Эмулятор теперь воспроизводит наблюдаемое значение `ChangeCipherSpec` из полученного `behavior_profile`.
+- Эмулятор теперь воспроизводит наблюдаемые размеры ticket-like tail ApplicationData records, когда доступны raw или merged TLS profile data.
+- Эмулятор теперь сохраняет больше структуры профилированного encrypted flight, а не схлопывает его в более маленькую synthetic форму.
+- Для профилей без raw TLS behavior по-прежнему сохраняется прежний synthetic fallback.
+- Операторский `tls_new_session_tickets` по-прежнему работает как дополнительный fallback, если профиль не даёт достаточного количества tail records.
+
+## Практическая польза
+
+- Снижается различимость между профилированным origin TLS-поведением и эмулируемым TLS-поведением.
+- Уменьшается шанс устойчивых server-flight fingerprint, вызванных фиксированным CCS count или полностью synthetic tail record sizes.
+- Уже собранные TLS profile data используются лучше, без изменения MTProto logic, KDF routing или transport architecture.
+
+## Ограничения
+
+Этот механизм не ставит целью сделать Telemt побайтно идентичным origin server.
+
+Он также не меняет:
+
+- MTProto business logic;
+- поведение KDF routing;
+- общую transport architecture.
+
+Практическая цель уже:
+
+- использовать больше уже собранных profile data;
+- уменьшить fixed synthetic behavior в server flight;
+- сохранить валидный FakeTLS success path, одновременно меняя форму emitted traffic на проводе.
+
+## Цели валидации
+
+- Корректное количество эмулируемых `ChangeCipherSpec` records.
+- Корректное воспроизведение наблюдаемых ticket-tail record sizes.
+- Отсутствие регрессии в существующем ALPN и payload-placement behavior.
+
+## Как проверять результат
+
+Рекомендуемая валидация состоит из двух слоёв:
+
+- focused unit и security tests для CCS-count replay и ticket-tail replay;
+- сравнение реальных packet capture для выбранного origin и успешной FakeTLS session.
+
+При проверке на сети ожидаемый результат такой:
+
+- валидный FakeTLS и MTProto success path сохраняется;
+- форма раннего encrypted server flight меняется, когда доступно более богатое profile data;
+- изменение видно на проводе без изменения MTProto logic и transport architecture.
+
+Такая проверка нужна для подтверждения того, что уже собранные TLS profile data используются лучше.
+Она не предназначена для доказательства побайтной эквивалентности с реальным origin server.
+
+## Как проверить на реальной инсталляции
+
+Самая сильная практическая проверка — side-by-side trace comparison между:
+
+- реальным TLS origin server, используемым как `mask_host`;
+- Telemt FakeTLS success-path connection для того же SNI;
+- при необходимости capture от разных Telemt builds или configurations.
+
+Смысл сравнения состоит в том, чтобы посмотреть на форму server flight:
+
+- порядок records;
+- количество `ChangeCipherSpec` records;
+- количество и группировку ранних encrypted `ApplicationData` records;
+- размеры tail или continuation `ApplicationData` records.
+
+## Рекомендуемое окружение
+
+Для самой чистой проверки лучше использовать Linux host или Docker container.
+
+Рекомендуемый setup:
+
+1. Один экземпляр Telemt.
+2. Один реальный HTTPS origin как `mask_host`.
+3. Один Telegram client, настроенный на `ee` proxy link для Telemt instance.
+4. `tcpdump` или Wireshark для анализа capture.
+
+## Пошаговая процедура проверки
+
+### 1. Подготовить origin
+
+1. Выберите реальный HTTPS origin.
+2. Установите и `censorship.tls_domain`, и `censorship.mask_host` в hostname этого origin.
+3. Убедитесь, что прямой TLS request работает:
+
+```bash
+openssl s_client -connect ORIGIN_IP:443 -servername YOUR_DOMAIN </dev/null
+```
+
+### 2. Настроить Telemt
+
+Используйте config, где включены:
+
+- `censorship.mask = true`
+- `censorship.tls_emulation = true`
+- `censorship.mask_host`
+- `censorship.mask_port`
+
+Для более чистой проверки рекомендуется:
+
+- держать `censorship.tls_new_session_tickets = 0`, чтобы результат в первую очередь зависел от fetched profile data, а не от операторских synthetic tail records;
+- держать `censorship.tls_fetch.strict_route = true`, если важна более чистая provenance для captured profile data.
+
+### 3. Обновить TLS profile data
+
+1. Запустите Telemt.
+2. Дайте ему получить TLS front profile data для выбранного домена.
+3. Если `tls_front_dir` хранится persistently, убедитесь, что TLS front cache заполнен.
+
+Сохранённые артефакты кэша полезны, но не обязательны, если packet capture уже показывает результат в runtime.
+
+### 4. Проверить метрики состояния TLS-front profile
+
+Если endpoint метрик включён, перед проверкой через packet capture можно быстро проверить состояние TLS-front profile:
+
+```bash
+curl -s http://127.0.0.1:9999/metrics | grep -E 'telemt_tls_front_profile|telemt_tls_fetch_profile_cache|telemt_tls_front_full_cert'
+```
+
+Метрики состояния профиля показывают runtime-состояние настроенных TLS-front доменов:
+
+- `telemt_tls_front_profile_domains` показывает количество настроенных, экспортируемых и скрытых из-за лимита доменов.
+- `telemt_tls_front_profile_info` показывает источник профиля и флаги доступных данных по каждому домену.
+- `telemt_tls_front_profile_age_seconds` показывает возраст закешированного профиля.
+- `telemt_tls_front_profile_app_data_records` показывает количество закешированных AppData records.
+- `telemt_tls_front_profile_ticket_records` показывает количество закешированных ticket-like tail records.
+- `telemt_tls_front_profile_change_cipher_spec_records` показывает закешированное количество ChangeCipherSpec records.
+- `telemt_tls_front_profile_app_data_bytes` показывает общий размер закешированных AppData bytes.
+
+Интерпретация:
+
+- `source="merged"` или `source="raw"` означает, что используются реальные данные TLS-профиля.
+- `source="default"` или `is_default="true"` означает, что домен сейчас работает на synthetic default fallback.
+- `has_cert_payload="true"` означает, что certificate payload доступен для TLS emulation.
+- Ненулевые AppData/ticket/CCS counters показывают захваченную форму server flight.
+
+Пример здорового состояния:
+
+```text
+telemt_tls_front_profile_domains{status="configured"} 1
+telemt_tls_front_profile_domains{status="emitted"} 1
+telemt_tls_front_profile_domains{status="suppressed"} 0
+telemt_tls_front_profile_info{domain="itunes.apple.com",source="merged",is_default="false",has_cert_info="true",has_cert_payload="true"} 1
+telemt_tls_front_profile_age_seconds{domain="itunes.apple.com"} 20
+telemt_tls_front_profile_app_data_records{domain="itunes.apple.com"} 3
+telemt_tls_front_profile_ticket_records{domain="itunes.apple.com"} 1
+telemt_tls_front_profile_change_cipher_spec_records{domain="itunes.apple.com"} 1
+telemt_tls_front_profile_app_data_bytes{domain="itunes.apple.com"} 5240
+```
+
+Эти метрики не доказывают побайтную эквивалентность с origin. Это эксплуатационный сигнал состояния: настроенный домен действительно основан на реальных закешированных данных профиля, а не на default fallback.
+
+### 5. Снять direct-origin trace
+
+С отдельной клиентской машины подключитесь напрямую к origin:
+
+```bash
+openssl s_client -connect ORIGIN_IP:443 -servername YOUR_DOMAIN </dev/null
+```
+
+Capture:
+
+```bash
+sudo tcpdump -i any -w origin-direct.pcap host ORIGIN_IP and port 443
+```
+
+### 6. Снять Telemt FakeTLS success-path trace
+
+Теперь подключитесь к Telemt через реальный Telegram client с `ee` proxy link, который указывает на Telemt instance.
+
+`openssl s_client` полезен для direct-origin capture и для fallback sanity checks, но он не проходит успешный FakeTLS и MTProto path.
+
+Capture:
+
+```bash
+sudo tcpdump -i any -w telemt-emulated.pcap host TELEMT_IP and port 443
+```
+
+### 7. Декодировать структуру TLS records
+
+Используйте `tshark`, чтобы вывести record-level structure:
+
+```bash
+tshark -r origin-direct.pcap -Y "tls.record" -T fields \
+  -e frame.number \
+  -e ip.src \
+  -e ip.dst \
+  -e tls.record.content_type \
+  -e tls.record.length
+```
+
+```bash
+tshark -r telemt-emulated.pcap -Y "tls.record" -T fields \
+  -e frame.number \
+  -e ip.src \
+  -e ip.dst \
+  -e tls.record.content_type \
+  -e tls.record.length
+```
+
+Смотрите на server flight после ClientHello:
+
+- `22` = Handshake
+- `20` = ChangeCipherSpec
+- `23` = ApplicationData
+
+### 8. Собрать сравнительную таблицу
+
+Обычно достаточно короткой таблицы такого вида:
+
+| Path | CCS count | AppData count in first encrypted flight | Tail AppData lengths |
+| --- | --- | --- | --- |
+| Origin | `N` | `M` | `[a, b, ...]` |
+| Telemt build A | `...` | `...` | `...` |
+| Telemt build B | `...` | `...` | `...` |
+
+По такой таблице должно быть легко увидеть, что:
+
+- FakeTLS success path остаётся валидным;
+- ранний encrypted server flight меняется, когда переиспользуется более богатое profile data;
+- результат подтверждён packet evidence.
+
+## Пример набора capture
+
+Один практический пример такой проверки использует:
+
+- `origin-direct-nginx.pcap`
+- `telemt-ee-before-nginx.pcap`
+- `telemt-ee-after-nginx.pcap`
+
+Практические замечания:
+
+- `origin` снимался как прямое TLS 1.2 connection к `nginx.org`;
+- `before` и `after` снимались на Telemt FakeTLS success path с реальным Telegram client;
+- первый server-side FakeTLS response остаётся валидным в обоих случаях;
+- сегментация раннего encrypted server flight отличается между `before` и `after`, что согласуется с лучшим использованием captured profile data;
+- такой результат показывает заметный эффект на проводе без поломки success path, но не заявляет полной неотличимости от origin.
+
+## Более сильная валидация
+
+Для более широкой проверки повторите ту же процедуру ещё на:
+
+1. одном CDN-backed origin;
+2. одном regular nginx origin;
+3. одном origin с multi-record encrypted flight и заметными ticket-like tails.
+
+Если одно и то же направление улучшения повторится на всех трёх, уверенность в результате будет значительно выше, чем для одного origin example.

docs/CONFIG_PARAMS.en.md

@@ -1,448 +0,0 @@
-# Telemt Config Parameters Reference
-
-This document lists all configuration keys accepted by `config.toml`.
-
-> [!WARNING]
-> 
-> The configuration parameters detailed in this document are intended for advanced users and fine-tuning purposes. Modifying these settings without a clear understanding of their function may lead to application instability or other unexpected behavior. Please proceed with caution and at your own risk.
-
-## Top-level keys
-
-| Parameter | Type | Default | Constraints / validation | Description |
-|---|---|---|---|---|
-| include | `String` (special directive) | `null` | — | Includes another TOML file with `include = "relative/or/absolute/path.toml"`; includes are processed recursively before parsing. |
-| show_link | `"*" \| String[]` | `[]` (`ShowLink::None`) | — | Legacy top-level link visibility selector (`"*"` for all users or explicit usernames list). |
-| dc_overrides | `Map<String, String[]>` | `{}` | — | Overrides DC endpoints for non-standard DCs; key is DC id string, value is `ip:port` list. |
-| default_dc | `u8 \| null` | `null` (effective fallback: `2` in ME routing) | — | Default DC index used for unmapped non-standard DCs. |
-
-## [general]
-
-| Parameter | Type | Default | Constraints / validation | Description |
-|---|---|---|---|---|
-| data_path | `String \| null` | `null` | — | Optional runtime data directory path. |
-| prefer_ipv6 | `bool` | `false` | Deprecated. Use `network.prefer`. | Deprecated legacy IPv6 preference flag migrated to `network.prefer`. |
-| fast_mode | `bool` | `true` | — | Enables fast-path optimizations for traffic processing. |
-| use_middle_proxy | `bool` | `true` | none | Enables ME transport mode; if `false`, runtime falls back to direct DC routing. |
-| proxy_secret_path | `String \| null` | `"proxy-secret"` | Path may be `null`. | Path to Telegram infrastructure proxy-secret file used by ME handshake logic. |
-| proxy_config_v4_cache_path | `String \| null` | `"cache/proxy-config-v4.txt"` | — | Optional cache path for raw `getProxyConfig` (IPv4) snapshot. |
-| proxy_config_v6_cache_path | `String \| null` | `"cache/proxy-config-v6.txt"` | — | Optional cache path for raw `getProxyConfigV6` (IPv6) snapshot. |
-| ad_tag | `String \| null` | `null` | — | Global fallback ad tag (32 hex characters). |
-| middle_proxy_nat_ip | `IpAddr \| null` | `null` | Must be a valid IP when set. | Manual public NAT IP override used as ME address material when set. |
-| middle_proxy_nat_probe | `bool` | `true` | Auto-forced to `true` when `use_middle_proxy = true`. | Enables ME NAT probing; runtime may force it on when ME mode is active. |
-| middle_proxy_nat_stun | `String \| null` | `null` | Deprecated. Use `network.stun_servers`. | Deprecated legacy single STUN server for NAT probing. |
-| middle_proxy_nat_stun_servers | `String[]` | `[]` | Deprecated. Use `network.stun_servers`. | Deprecated legacy STUN list for NAT probing fallback. |
-| stun_nat_probe_concurrency | `usize` | `8` | Must be `> 0`. | Maximum number of parallel STUN probes during NAT/public endpoint discovery. |
-| middle_proxy_pool_size | `usize` | `8` | none | Target size of active ME writer pool. |
-| middle_proxy_warm_standby | `usize` | `16` | none | Reserved compatibility field in current runtime revision. |
-| me_init_retry_attempts | `u32` | `0` | `0..=1_000_000`. | Startup retries for ME pool initialization (`0` means unlimited). |
-| me2dc_fallback | `bool` | `true` | — | Allows fallback from ME mode to direct DC when ME startup fails. |
-| me_keepalive_enabled | `bool` | `true` | none | Enables periodic ME keepalive/ping traffic. |
-| me_keepalive_interval_secs | `u64` | `8` | none | Base ME keepalive interval in seconds. |
-| me_keepalive_jitter_secs | `u64` | `2` | none | Keepalive jitter in seconds to reduce synchronized bursts. |
-| me_keepalive_payload_random | `bool` | `true` | none | Randomizes keepalive payload bytes instead of fixed zero payload. |
-| rpc_proxy_req_every | `u64` | `0` | `0` or `10..=300`. | Interval for service `RPC_PROXY_REQ` activity signals (`0` disables). |
-| me_writer_cmd_channel_capacity | `usize` | `4096` | Must be `> 0`. | Capacity of per-writer command channel. |
-| me_route_channel_capacity | `usize` | `768` | Must be `> 0`. | Capacity of per-connection ME response route channel. |
-| me_c2me_channel_capacity | `usize` | `1024` | Must be `> 0`. | Capacity of per-client command queue (client reader -> ME sender). |
-| me_c2me_send_timeout_ms | `u64` | `4000` | `0..=60000`. | Maximum wait for enqueueing client->ME commands when the per-client queue is full (`0` keeps legacy unbounded wait). |
-| me_reader_route_data_wait_ms | `u64` | `2` | `0..=20`. | Bounded wait for routing ME DATA to per-connection queue (`0` = no wait). |
-| me_d2c_flush_batch_max_frames | `usize` | `32` | `1..=512`. | Max ME->client frames coalesced before flush. |
-| me_d2c_flush_batch_max_bytes | `usize` | `131072` | `4096..=2_097_152`. | Max ME->client payload bytes coalesced before flush. |
-| me_d2c_flush_batch_max_delay_us | `u64` | `500` | `0..=5000`. | Max microsecond wait for coalescing more ME->client frames (`0` disables timed coalescing). |
-| me_d2c_ack_flush_immediate | `bool` | `true` | — | Flushes client writer immediately after quick-ack write. |
-| me_quota_soft_overshoot_bytes | `u64` | `65536` | `0..=16_777_216`. | Extra per-route quota allowance (bytes) tolerated before writer-side quota enforcement drops route data. |
-| me_d2c_frame_buf_shrink_threshold_bytes | `usize` | `262144` | `4096..=16_777_216`. | Threshold for shrinking oversized ME->client frame-aggregation buffers after flush. |
-| direct_relay_copy_buf_c2s_bytes | `usize` | `65536` | `4096..=1_048_576`. | Copy buffer size for client->DC direction in direct relay. |
-| direct_relay_copy_buf_s2c_bytes | `usize` | `262144` | `8192..=2_097_152`. | Copy buffer size for DC->client direction in direct relay. |
-| crypto_pending_buffer | `usize` | `262144` | — | Max pending ciphertext buffer per client writer (bytes). |
-| max_client_frame | `usize` | `16777216` | — | Maximum allowed client MTProto frame size (bytes). |
-| desync_all_full | `bool` | `false` | — | Emits full crypto-desync forensic logs for every event. |
-| beobachten | `bool` | `true` | — | Enables per-IP forensic observation buckets. |
-| beobachten_minutes | `u64` | `10` | Must be `> 0`. | Retention window (minutes) for per-IP observation buckets. |
-| beobachten_flush_secs | `u64` | `15` | Must be `> 0`. | Snapshot flush interval (seconds) for observation output file. |
-| beobachten_file | `String` | `"cache/beobachten.txt"` | — | Observation snapshot output file path. |
-| hardswap | `bool` | `true` | none | Enables generation-based ME hardswap strategy. |
-| me_warmup_stagger_enabled | `bool` | `true` | none | Staggers extra ME warmup dials to avoid connection spikes. |
-| me_warmup_step_delay_ms | `u64` | `500` | none | Base delay in milliseconds between warmup dial steps. |
-| me_warmup_step_jitter_ms | `u64` | `300` | none | Additional random delay in milliseconds for warmup steps. |
-| me_reconnect_max_concurrent_per_dc | `u32` | `8` | none | Limits concurrent reconnect workers per DC during health recovery. |
-| me_reconnect_backoff_base_ms | `u64` | `500` | none | Initial reconnect backoff in milliseconds. |
-| me_reconnect_backoff_cap_ms | `u64` | `30000` | none | Maximum reconnect backoff cap in milliseconds. |
-| me_reconnect_fast_retry_count | `u32` | `16` | none | Immediate retry budget before long backoff behavior applies. |
-| me_single_endpoint_shadow_writers | `u8` | `2` | `0..=32`. | Additional reserve writers for one-endpoint DC groups. |
-| me_single_endpoint_outage_mode_enabled | `bool` | `true` | — | Enables aggressive outage recovery for one-endpoint DC groups. |
-| me_single_endpoint_outage_disable_quarantine | `bool` | `true` | — | Ignores endpoint quarantine in one-endpoint outage mode. |
-| me_single_endpoint_outage_backoff_min_ms | `u64` | `250` | Must be `> 0`; also `<= me_single_endpoint_outage_backoff_max_ms`. | Minimum reconnect backoff in outage mode (ms). |
-| me_single_endpoint_outage_backoff_max_ms | `u64` | `3000` | Must be `> 0`; also `>= me_single_endpoint_outage_backoff_min_ms`. | Maximum reconnect backoff in outage mode (ms). |
-| me_single_endpoint_shadow_rotate_every_secs | `u64` | `900` | — | Periodic shadow writer rotation interval (`0` disables). |
-| me_floor_mode | `"static" \| "adaptive"` | `"adaptive"` | — | Writer floor policy mode. |
-| me_adaptive_floor_idle_secs | `u64` | `90` | — | Idle time before adaptive floor may reduce one-endpoint target. |
-| me_adaptive_floor_min_writers_single_endpoint | `u8` | `1` | `1..=32`. | Minimum adaptive writer target for one-endpoint DC groups. |
-| me_adaptive_floor_min_writers_multi_endpoint | `u8` | `1` | `1..=32`. | Minimum adaptive writer target for multi-endpoint DC groups. |
-| me_adaptive_floor_recover_grace_secs | `u64` | `180` | — | Grace period to hold static floor after activity. |
-| me_adaptive_floor_writers_per_core_total | `u16` | `48` | Must be `> 0`. | Global writer budget per logical CPU core in adaptive mode. |
-| me_adaptive_floor_cpu_cores_override | `u16` | `0` | — | Manual CPU core count override (`0` uses auto-detection). |
-| me_adaptive_floor_max_extra_writers_single_per_core | `u16` | `1` | — | Per-core max extra writers above base floor for one-endpoint DCs. |
-| me_adaptive_floor_max_extra_writers_multi_per_core | `u16` | `2` | — | Per-core max extra writers above base floor for multi-endpoint DCs. |
-| me_adaptive_floor_max_active_writers_per_core | `u16` | `64` | Must be `> 0`. | Hard cap for active ME writers per logical CPU core. |
-| me_adaptive_floor_max_warm_writers_per_core | `u16` | `64` | Must be `> 0`. | Hard cap for warm ME writers per logical CPU core. |
-| me_adaptive_floor_max_active_writers_global | `u32` | `256` | Must be `> 0`. | Hard global cap for active ME writers. |
-| me_adaptive_floor_max_warm_writers_global | `u32` | `256` | Must be `> 0`. | Hard global cap for warm ME writers. |
-| upstream_connect_retry_attempts | `u32` | `2` | Must be `> 0`. | Connect attempts for selected upstream before error/fallback. |
-| upstream_connect_retry_backoff_ms | `u64` | `100` | — | Delay between upstream connect attempts (ms). |
-| upstream_connect_budget_ms | `u64` | `3000` | Must be `> 0`. | Total wall-clock budget for one upstream connect request (ms). |
-| tg_connect | `u64` | `10` | Must be `> 0`. | Per-attempt upstream TCP connect timeout to Telegram DC (seconds). |
-| upstream_unhealthy_fail_threshold | `u32` | `5` | Must be `> 0`. | Consecutive failed requests before upstream is marked unhealthy. |
-| upstream_connect_failfast_hard_errors | `bool` | `false` | — | Skips additional retries for hard non-transient connect errors. |
-| stun_iface_mismatch_ignore | `bool` | `false` | none | Reserved compatibility flag in current runtime revision. |
-| unknown_dc_log_path | `String \| null` | `"unknown-dc.txt"` | — | File path for unknown-DC request logging (`null` disables file path). |
-| unknown_dc_file_log_enabled | `bool` | `false` | — | Enables unknown-DC file logging. |
-| log_level | `"debug" \| "verbose" \| "normal" \| "silent"` | `"normal"` | — | Runtime logging verbosity. |
-| disable_colors | `bool` | `false` | — | Disables ANSI colors in logs. |
-| me_socks_kdf_policy | `"strict" \| "compat"` | `"strict"` | — | SOCKS-bound KDF fallback policy for ME handshake. |
-| me_route_backpressure_base_timeout_ms | `u64` | `25` | Must be `> 0`. | Base backpressure timeout for route-channel send (ms). |
-| me_route_backpressure_high_timeout_ms | `u64` | `120` | Must be `>= me_route_backpressure_base_timeout_ms`. | High backpressure timeout when queue occupancy exceeds watermark (ms). |
-| me_route_backpressure_high_watermark_pct | `u8` | `80` | `1..=100`. | Queue occupancy threshold (%) for high timeout mode. |
-| me_health_interval_ms_unhealthy | `u64` | `1000` | Must be `> 0`. | Health monitor interval while writer coverage is degraded (ms). |
-| me_health_interval_ms_healthy | `u64` | `3000` | Must be `> 0`. | Health monitor interval while writer coverage is healthy (ms). |
-| me_admission_poll_ms | `u64` | `1000` | Must be `> 0`. | Poll interval for conditional-admission checks (ms). |
-| me_warn_rate_limit_ms | `u64` | `5000` | Must be `> 0`. | Cooldown for repetitive ME warning logs (ms). |
-| me_route_no_writer_mode | `"async_recovery_failfast" \| "inline_recovery_legacy" \| "hybrid_async_persistent"` | `"hybrid_async_persistent"` | — | Route behavior when no writer is immediately available. |
-| me_route_no_writer_wait_ms | `u64` | `250` | `10..=5000`. | Max wait in async-recovery failfast mode (ms). |
-| me_route_hybrid_max_wait_ms | `u64` | `3000` | `50..=60000`. | Maximum cumulative wait in hybrid no-writer mode before failfast fallback (ms). |
-| me_route_blocking_send_timeout_ms | `u64` | `250` | `0..=5000`. | Maximum wait for blocking route-channel send fallback (`0` keeps legacy unbounded wait). |
-| me_route_inline_recovery_attempts | `u32` | `3` | Must be `> 0`. | Inline recovery attempts in legacy mode. |
-| me_route_inline_recovery_wait_ms | `u64` | `3000` | `10..=30000`. | Max inline recovery wait in legacy mode (ms). |
-| fast_mode_min_tls_record | `usize` | `0` | — | Minimum TLS record size when fast-mode coalescing is enabled (`0` disables). |
-| update_every | `u64 \| null` | `300` | If set: must be `> 0`; if `null`: legacy fallback path is used. | Unified refresh interval for ME config and proxy-secret updater tasks. |
-| me_reinit_every_secs | `u64` | `900` | Must be `> 0`. | Periodic interval for zero-downtime ME reinit cycle. |
-| me_hardswap_warmup_delay_min_ms | `u64` | `1000` | Must be `<= me_hardswap_warmup_delay_max_ms`. | Lower bound for hardswap warmup dial spacing. |
-| me_hardswap_warmup_delay_max_ms | `u64` | `2000` | Must be `> 0`. | Upper bound for hardswap warmup dial spacing. |
-| me_hardswap_warmup_extra_passes | `u8` | `3` | Must be within `[0, 10]`. | Additional warmup passes after the base pass in one hardswap cycle. |
-| me_hardswap_warmup_pass_backoff_base_ms | `u64` | `500` | Must be `> 0`. | Base backoff between extra hardswap warmup passes. |
-| me_config_stable_snapshots | `u8` | `2` | Must be `> 0`. | Number of identical ME config snapshots required before apply. |
-| me_config_apply_cooldown_secs | `u64` | `300` | none | Cooldown between applied ME endpoint-map updates. |
-| me_snapshot_require_http_2xx | `bool` | `true` | — | Requires 2xx HTTP responses for applying config snapshots. |
-| me_snapshot_reject_empty_map | `bool` | `true` | — | Rejects empty config snapshots. |
-| me_snapshot_min_proxy_for_lines | `u32` | `1` | Must be `> 0`. | Minimum parsed `proxy_for` rows required to accept snapshot. |
-| proxy_secret_stable_snapshots | `u8` | `2` | Must be `> 0`. | Number of identical proxy-secret snapshots required before rotation. |
-| proxy_secret_rotate_runtime | `bool` | `true` | none | Enables runtime proxy-secret rotation from updater snapshots. |
-| me_secret_atomic_snapshot | `bool` | `true` | — | Keeps selector and secret bytes from the same snapshot atomically. |
-| proxy_secret_len_max | `usize` | `256` | Must be within `[32, 4096]`. | Upper length limit for accepted proxy-secret bytes. |
-| me_pool_drain_ttl_secs | `u64` | `90` | none | Time window where stale writers remain fallback-eligible after map change. |
-| me_instadrain | `bool` | `false` | — | Forces draining stale writers to be removed on the next cleanup tick, bypassing TTL/deadline waiting. |
-| me_pool_drain_threshold | `u64` | `128` | — | Max draining stale writers before batch force-close (`0` disables threshold cleanup). |
-| me_pool_drain_soft_evict_enabled | `bool` | `true` | — | Enables gradual soft-eviction of stale writers during drain/reinit instead of immediate hard close. |
-| me_pool_drain_soft_evict_grace_secs | `u64` | `30` | `0..=3600`. | Grace period before stale writers become soft-evict candidates. |
-| me_pool_drain_soft_evict_per_writer | `u8` | `1` | `1..=16`. | Maximum stale routes soft-evicted per writer in one eviction pass. |
-| me_pool_drain_soft_evict_budget_per_core | `u16` | `8` | `1..=64`. | Per-core budget limiting aggregate soft-eviction work per pass. |
-| me_pool_drain_soft_evict_cooldown_ms | `u64` | `5000` | Must be `> 0`. | Cooldown between consecutive soft-eviction passes (ms). |
-| me_bind_stale_mode | `"never" \| "ttl" \| "always"` | `"ttl"` | — | Policy for new binds on stale draining writers. |
-| me_bind_stale_ttl_secs | `u64` | `90` | — | TTL for stale bind allowance when stale mode is `ttl`. |
-| me_pool_min_fresh_ratio | `f32` | `0.8` | Must be within `[0.0, 1.0]`. | Minimum fresh desired-DC coverage ratio before stale writers are drained. |
-| me_reinit_drain_timeout_secs | `u64` | `120` | `0` disables force-close; if `> 0` and `< me_pool_drain_ttl_secs`, runtime bumps it to TTL. | Force-close timeout for draining stale writers (`0` keeps indefinite draining). |
-| proxy_secret_auto_reload_secs | `u64` | `3600` | Deprecated. Use `general.update_every`. | Deprecated legacy secret reload interval (fallback when `update_every` is not set). |
-| proxy_config_auto_reload_secs | `u64` | `3600` | Deprecated. Use `general.update_every`. | Deprecated legacy config reload interval (fallback when `update_every` is not set). |
-| me_reinit_singleflight | `bool` | `true` | — | Serializes ME reinit cycles across trigger sources. |
-| me_reinit_trigger_channel | `usize` | `64` | Must be `> 0`. | Trigger queue capacity for reinit scheduler. |
-| me_reinit_coalesce_window_ms | `u64` | `200` | — | Trigger coalescing window before starting reinit (ms). |
-| me_deterministic_writer_sort | `bool` | `true` | — | Enables deterministic candidate sort for writer binding path. |
-| me_writer_pick_mode | `"sorted_rr" \| "p2c"` | `"p2c"` | — | Writer selection mode for route bind path. |
-| me_writer_pick_sample_size | `u8` | `3` | `2..=4`. | Number of candidates sampled by picker in `p2c` mode. |
-| ntp_check | `bool` | `true` | — | Enables NTP drift check at startup. |
-| ntp_servers | `String[]` | `["pool.ntp.org"]` | — | NTP servers used for drift check. |
-| auto_degradation_enabled | `bool` | `true` | none | Reserved compatibility flag in current runtime revision. |
-| degradation_min_unavailable_dc_groups | `u8` | `2` | none | Reserved compatibility threshold in current runtime revision. |
-
-## [general.modes]
-
-| Parameter | Type | Default | Constraints / validation | Description |
-|---|---|---|---|---|
-| classic | `bool` | `false` | — | Enables classic MTProxy mode. |
-| secure | `bool` | `false` | — | Enables secure mode. |
-| tls | `bool` | `true` | — | Enables TLS mode. |
-
-## [general.links]
-
-| Parameter | Type | Default | Constraints / validation | Description |
-|---|---|---|---|---|
-| show | `"*" \| String[]` | `"*"` | — | Selects users whose tg:// links are shown at startup. |
-| public_host | `String \| null` | `null` | — | Public hostname/IP override for generated tg:// links. |
-| public_port | `u16 \| null` | `null` | — | Public port override for generated tg:// links. |
-
-## [general.telemetry]
-
-| Parameter | Type | Default | Constraints / validation | Description |
-|---|---|---|---|---|
-| core_enabled | `bool` | `true` | — | Enables core hot-path telemetry counters. |
-| user_enabled | `bool` | `true` | — | Enables per-user telemetry counters. |
-| me_level | `"silent" \| "normal" \| "debug"` | `"normal"` | — | Middle-End telemetry verbosity level. |
-
-## [network]
-
-| Parameter | Type | Default | Constraints / validation | Description |
-|---|---|---|---|---|
-| ipv4 | `bool` | `true` | — | Enables IPv4 networking. |
-| ipv6 | `bool` | `false` | — | Enables/disables IPv6 when set |
-| prefer | `u8` | `4` | Must be `4` or `6`. | Preferred IP family for selection (`4` or `6`). |
-| multipath | `bool` | `false` | — | Enables multipath behavior where supported. |
-| stun_use | `bool` | `true` | none | Global STUN switch; when `false`, STUN probing path is disabled. |
-| stun_servers | `String[]` | Built-in STUN list (13 hosts) | Deduplicated; empty values are removed. | Primary STUN server list for NAT/public endpoint discovery. |
-| stun_tcp_fallback | `bool` | `true` | none | Enables TCP fallback for STUN when UDP path is blocked. |
-| http_ip_detect_urls | `String[]` | `["https://ifconfig.me/ip", "https://api.ipify.org"]` | none | HTTP fallback endpoints for public IP detection when STUN is unavailable. |
-| cache_public_ip_path | `String` | `"cache/public_ip.txt"` | — | File path for caching detected public IP. |
-| dns_overrides | `String[]` | `[]` | Must match `host:port:ip`; IPv6 must be bracketed. | Runtime DNS overrides in `host:port:ip` format. |
-
-## [server]
-
-| Parameter | Type | Default | Constraints / validation | Description |
-|---|---|---|---|---|
-| port | `u16` | `443` | — | Main proxy listen port. |
-| listen_addr_ipv4 | `String \| null` | `"0.0.0.0"` | — | IPv4 bind address for TCP listener. |
-| listen_addr_ipv6 | `String \| null` | `"::"` | — | IPv6 bind address for TCP listener. |
-| listen_unix_sock | `String \| null` | `null` | — | Unix socket path for listener. |
-| listen_unix_sock_perm | `String \| null` | `null` | — | Unix socket permissions in octal string (e.g., `"0666"`). |
-| listen_tcp | `bool \| null` | `null` (auto) | — | Explicit TCP listener enable/disable override. |
-| proxy_protocol | `bool` | `false` | — | Enables HAProxy PROXY protocol parsing on incoming client connections. |
-| proxy_protocol_header_timeout_ms | `u64` | `500` | Must be `> 0`. | Timeout for PROXY protocol header read/parse (ms). |
-| proxy_protocol_trusted_cidrs | `IpNetwork[]` | `[]` | — | When non-empty, only connections from these proxy source CIDRs are allowed to provide PROXY protocol headers. If empty, PROXY headers are rejected by default (security hardening). |
-| metrics_port | `u16 \| null` | `null` | — | Metrics endpoint port (enables metrics listener). |
-| metrics_listen | `String \| null` | `null` | — | Full metrics bind address (`IP:PORT`), overrides `metrics_port`. |
-| metrics_whitelist | `IpNetwork[]` | `["127.0.0.1/32", "::1/128"]` | — | CIDR whitelist for metrics endpoint access. |
-| max_connections | `u32` | `10000` | — | Max concurrent client connections (`0` = unlimited). |
-| accept_permit_timeout_ms | `u64` | `250` | `0..=60000`. | Maximum wait for acquiring a connection-slot permit before the accepted connection is dropped (`0` keeps legacy unbounded wait). |
-
-Note: When `server.proxy_protocol` is enabled, incoming PROXY protocol headers are parsed from the first bytes of the connection and the client source address is replaced with `src_addr` from the header. For security, the peer source IP (the direct connection address) is verified against `server.proxy_protocol_trusted_cidrs`; if this list is empty, PROXY headers are rejected and the connection is considered untrusted. 
-
-## [server.api]
-
-| Parameter | Type | Default | Constraints / validation | Description |
-|---|---|---|---|---|
-| enabled | `bool` | `true` | — | Enables control-plane REST API. |
-| listen | `String` | `"0.0.0.0:9091"` | Must be valid `IP:PORT`. | API bind address in `IP:PORT` format. |
-| whitelist | `IpNetwork[]` | `["127.0.0.0/8"]` | — | CIDR whitelist allowed to access API. |
-| auth_header | `String` | `""` | — | Exact expected `Authorization` header value (empty = disabled). |
-| request_body_limit_bytes | `usize` | `65536` | Must be `> 0`. | Maximum accepted HTTP request body size. |
-| minimal_runtime_enabled | `bool` | `true` | — | Enables minimal runtime snapshots endpoint logic. |
-| minimal_runtime_cache_ttl_ms | `u64` | `1000` | `0..=60000`. | Cache TTL for minimal runtime snapshots (ms; `0` disables cache). |
-| runtime_edge_enabled | `bool` | `false` | — | Enables runtime edge endpoints. |
-| runtime_edge_cache_ttl_ms | `u64` | `1000` | `0..=60000`. | Cache TTL for runtime edge aggregation payloads (ms). |
-| runtime_edge_top_n | `usize` | `10` | `1..=1000`. | Top-N size for edge connection leaderboard. |
-| runtime_edge_events_capacity | `usize` | `256` | `16..=4096`. | Ring-buffer capacity for runtime edge events. |
-| read_only | `bool` | `false` | — | Rejects mutating API endpoints when enabled. |
-
-## [[server.listeners]]
-
-| Parameter | Type | Default | Constraints / validation | Description |
-|---|---|---|---|---|
-| ip | `IpAddr` | — | — | Listener bind IP. |
-| announce | `String \| null` | — | — | Public IP/domain announced in proxy links (priority over `announce_ip`). |
-| announce_ip | `IpAddr \| null` | — | Deprecated. Use `announce`. | Deprecated legacy announce IP (migrated to `announce` if needed). |
-| proxy_protocol | `bool \| null` | `null` | — | Per-listener override for PROXY protocol enable flag. |
-| reuse_allow | `bool` | `false` | — | Enables `SO_REUSEPORT` for multi-instance bind sharing. |
-
-## [timeouts]
-
-| Parameter | Type | Default | Constraints / validation | Description |
-|---|---|---|---|---|
-| client_handshake | `u64` | `30` | — | Client handshake timeout. |
-| relay_idle_policy_v2_enabled | `bool` | `true` | — | Enables soft/hard middle-relay client idle policy. |
-| relay_client_idle_soft_secs | `u64` | `120` | Must be `> 0`; must be `<= relay_client_idle_hard_secs`. | Soft idle threshold for middle-relay client uplink inactivity (seconds). |
-| relay_client_idle_hard_secs | `u64` | `360` | Must be `> 0`; must be `>= relay_client_idle_soft_secs`. | Hard idle threshold for middle-relay client uplink inactivity (seconds). |
-| relay_idle_grace_after_downstream_activity_secs | `u64` | `30` | Must be `<= relay_client_idle_hard_secs`. | Extra hard-idle grace after recent downstream activity (seconds). |
-| client_keepalive | `u64` | `15` | — | Client keepalive timeout. |
-| client_ack | `u64` | `90` | — | Client ACK timeout. |
-| me_one_retry | `u8` | `12` | none | Fast reconnect attempts budget for single-endpoint DC scenarios. |
-| me_one_timeout_ms | `u64` | `1200` | none | Timeout in milliseconds for each quick single-endpoint reconnect attempt. |
-
-## [censorship]
-
-| Parameter | Type | Default | Constraints / validation | Description |
-|---|---|---|---|---|
-| tls_domain | `String` | `"petrovich.ru"` | — | Primary TLS domain used in fake TLS handshake profile. |
-| tls_domains | `String[]` | `[]` | — | Additional TLS domains for generating multiple links. |
-| unknown_sni_action | `"drop" \| "mask"` | `"drop"` | — | Action for TLS ClientHello with unknown/non-configured SNI. |
-| tls_fetch_scope | `String` | `""` | Value is trimmed during load; empty keeps default upstream routing behavior. | Upstream scope tag used for TLS-front metadata fetches. |
-| tls_fetch | `Table` | built-in defaults | See `[censorship.tls_fetch]` section below. | TLS-front metadata fetch strategy settings. |
-| mask | `bool` | `true` | — | Enables masking/fronting relay mode. |
-| mask_host | `String \| null` | `null` | — | Upstream mask host for TLS fronting relay. |
-| mask_port | `u16` | `443` | — | Upstream mask port for TLS fronting relay. |
-| mask_unix_sock | `String \| null` | `null` | — | Unix socket path for mask backend instead of TCP host/port. |
-| fake_cert_len | `usize` | `2048` | — | Length of synthetic certificate payload when emulation data is unavailable. |
-| tls_emulation | `bool` | `true` | — | Enables certificate/TLS behavior emulation from cached real fronts. |
-| tls_front_dir | `String` | `"tlsfront"` | — | Directory path for TLS front cache storage. |
-| server_hello_delay_min_ms | `u64` | `0` | — | Minimum server_hello delay for anti-fingerprint behavior (ms). |
-| server_hello_delay_max_ms | `u64` | `0` | — | Maximum server_hello delay for anti-fingerprint behavior (ms). |
-| tls_new_session_tickets | `u8` | `0` | — | Number of `NewSessionTicket` messages to emit after handshake. |
-| tls_full_cert_ttl_secs | `u64` | `90` | — | TTL for sending full cert payload per (domain, client IP) tuple. |
-| alpn_enforce | `bool` | `true` | — | Enforces ALPN echo behavior based on client preference. |
-| mask_proxy_protocol | `u8` | `0` | — | PROXY protocol mode for mask backend (`0` disabled, `1` v1, `2` v2). |
-| mask_shape_hardening | `bool` | `true` | — | Enables client->mask shape-channel hardening by applying controlled tail padding to bucket boundaries on mask relay shutdown. |
-| mask_shape_hardening_aggressive_mode | `bool` | `false` | Requires `mask_shape_hardening = true`. | Opt-in aggressive shaping profile: allows shaping on backend-silent non-EOF paths and switches above-cap blur to strictly positive random tail. |
-| mask_shape_bucket_floor_bytes | `usize` | `512` | Must be `> 0`; should be `<= mask_shape_bucket_cap_bytes`. | Minimum bucket size used by shape-channel hardening. |
-| mask_shape_bucket_cap_bytes | `usize` | `4096` | Must be `>= mask_shape_bucket_floor_bytes`. | Maximum bucket size used by shape-channel hardening; traffic above cap is not padded further. |
-| mask_shape_above_cap_blur | `bool` | `false` | Requires `mask_shape_hardening = true`; requires `mask_shape_above_cap_blur_max_bytes > 0`. | Adds bounded randomized tail bytes even when forwarded size already exceeds cap. |
-| mask_shape_above_cap_blur_max_bytes | `usize` | `512` | Must be `<= 1048576`; must be `> 0` when `mask_shape_above_cap_blur = true`. | Maximum randomized extra bytes appended above cap. |
-| mask_relay_max_bytes | `usize` | `5242880` | Must be `> 0`; must be `<= 67108864`. | Maximum relayed bytes per direction on unauthenticated masking fallback path. |
-| mask_classifier_prefetch_timeout_ms | `u64` | `5` | Must be within `[5, 50]`. | Timeout budget (ms) for extending fragmented initial classifier window on masking fallback. |
-| mask_timing_normalization_enabled | `bool` | `false` | Requires `mask_timing_normalization_floor_ms > 0`; requires `ceiling >= floor`. | Enables timing envelope normalization on masking outcomes. |
-| mask_timing_normalization_floor_ms | `u64` | `0` | Must be `> 0` when timing normalization is enabled; must be `<= ceiling`. | Lower bound (ms) for masking outcome normalization target. |
-| mask_timing_normalization_ceiling_ms | `u64` | `0` | Must be `>= floor`; must be `<= 60000`. | Upper bound (ms) for masking outcome normalization target. |
-
-## [censorship.tls_fetch]
-
-| Parameter | Type | Default | Constraints / validation | Description |
-|---|---|---|---|---|
-| profiles | `("modern_chrome_like" \| "modern_firefox_like" \| "compat_tls12" \| "legacy_minimal")[]` | `["modern_chrome_like", "modern_firefox_like", "compat_tls12", "legacy_minimal"]` | Empty list falls back to defaults; values are deduplicated preserving order. | Ordered ClientHello profile fallback chain for TLS-front metadata fetch. |
-| strict_route | `bool` | `true` | — | Fails closed on upstream-route connect errors instead of falling back to direct TCP when route is configured. |
-| attempt_timeout_ms | `u64` | `5000` | Must be `> 0`. | Timeout budget per one TLS-fetch profile attempt (ms). |
-| total_budget_ms | `u64` | `15000` | Must be `> 0`. | Total wall-clock budget across all TLS-fetch attempts (ms). |
-| grease_enabled | `bool` | `false` | — | Enables GREASE-style random values in selected ClientHello extensions for fetch traffic. |
-| deterministic | `bool` | `false` | — | Enables deterministic ClientHello randomness for debugging/tests. |
-| profile_cache_ttl_secs | `u64` | `600` | `0` disables cache. | TTL for winner-profile cache entries used by TLS fetch path. |
-
-### Shape-channel hardening notes (`[censorship]`)
-
-These parameters are designed to reduce one specific fingerprint source during masking: the exact number of bytes sent from proxy to `mask_host` for invalid or probing traffic.
-
-Without hardening, a censor can often correlate probe input length with backend-observed length very precisely (for example: `5 + body_sent` on early TLS reject paths). That creates a length-based classifier signal.
-
-When `mask_shape_hardening = true`, Telemt pads the **client->mask** stream tail to a bucket boundary at relay shutdown:
-
-- Total bytes sent to mask are first measured.
-- A bucket is selected using powers of two starting from `mask_shape_bucket_floor_bytes`.
-- Padding is added only if total bytes are below `mask_shape_bucket_cap_bytes`.
-- If bytes already exceed cap, no extra padding is added.
-
-This means multiple nearby probe sizes collapse into the same backend-observed size class, making active classification harder.
-
-What each parameter changes in practice:
-
-- `mask_shape_hardening`
-	Enables or disables this entire length-shaping stage on the fallback path.
-	When `false`, backend-observed length stays close to the real forwarded probe length.
-	When `true`, clean relay shutdown can append random padding bytes to move the total into a bucket.
-
-- `mask_shape_bucket_floor_bytes`
-	Sets the first bucket boundary used for small probes.
-	Example: with floor `512`, a malformed probe that would otherwise forward `37` bytes can be expanded to `512` bytes on clean EOF.
-	Larger floor values hide very small probes better, but increase egress cost.
-
-- `mask_shape_bucket_cap_bytes`
-	Sets the largest bucket Telemt will pad up to with bucket logic.
-	Example: with cap `4096`, a forwarded total of `1800` bytes may be padded to `2048` or `4096` depending on the bucket ladder, but a total already above `4096` will not be bucket-padded further.
-	Larger cap values increase the range over which size classes are collapsed, but also increase worst-case overhead.
-
-- Clean EOF matters in conservative mode
-	In the default profile, shape padding is intentionally conservative: it is applied on clean relay shutdown, not on every timeout/drip path.
-	This avoids introducing new timeout-tail artifacts that some backends or tests interpret as a separate fingerprint.
-
-Practical trade-offs:
-
-- Better anti-fingerprinting on size/shape channel.
-- Slightly higher egress overhead for small probes due to padding.
-- Behavior is intentionally conservative and enabled by default.
-
-Recommended starting profile:
-
-- `mask_shape_hardening = true` (default)
-- `mask_shape_bucket_floor_bytes = 512`
-- `mask_shape_bucket_cap_bytes = 4096`
-
-### Aggressive mode notes (`[censorship]`)
-
-`mask_shape_hardening_aggressive_mode` is an opt-in profile for higher anti-classifier pressure.
-
-- Default is `false` to preserve conservative timeout/no-tail behavior.
-- Requires `mask_shape_hardening = true`.
-- When enabled, backend-silent non-EOF masking paths may be shaped.
-- When enabled together with above-cap blur, the random extra tail uses `[1, max]` instead of `[0, max]`.
-
-What changes when aggressive mode is enabled:
-
-- Backend-silent timeout paths can be shaped
-	In default mode, a client that keeps the socket half-open and times out will usually not receive shape padding on that path.
-	In aggressive mode, Telemt may still shape that backend-silent session if no backend bytes were returned.
-	This is specifically aimed at active probes that try to avoid EOF in order to preserve an exact backend-observed length.
-
-- Above-cap blur always adds at least one byte
-	In default mode, above-cap blur may choose `0`, so some oversized probes still land on their exact base forwarded length.
-	In aggressive mode, that exact-base sample is removed by construction.
-
-- Tradeoff
-	Aggressive mode improves resistance to active length classifiers, but it is more opinionated and less conservative.
-	If your deployment prioritizes strict compatibility with timeout/no-tail semantics, leave it disabled.
-	If your threat model includes repeated active probing by a censor, this mode is the stronger profile.
-
-Use this mode only when your threat model prioritizes classifier resistance over strict compatibility with conservative masking semantics.
-
-### Above-cap blur notes (`[censorship]`)
-
-`mask_shape_above_cap_blur` adds a second-stage blur for very large probes that are already above `mask_shape_bucket_cap_bytes`.
-
-- A random tail in `[0, mask_shape_above_cap_blur_max_bytes]` is appended in default mode.
-- In aggressive mode, the random tail becomes strictly positive: `[1, mask_shape_above_cap_blur_max_bytes]`.
-- This reduces exact-size leakage above cap at bounded overhead.
-- Keep `mask_shape_above_cap_blur_max_bytes` conservative to avoid unnecessary egress growth.
-
-Operational meaning:
-
-- Without above-cap blur
-	A probe that forwards `5005` bytes will still look like `5005` bytes to the backend if it is already above cap.
-
-- With above-cap blur enabled
-	That same probe may look like any value in a bounded window above its base length.
-	Example with `mask_shape_above_cap_blur_max_bytes = 64`:
-	backend-observed size becomes `5005..5069` in default mode, or `5006..5069` in aggressive mode.
-
-- Choosing `mask_shape_above_cap_blur_max_bytes`
-	Small values reduce cost but preserve more separability between far-apart oversized classes.
-	Larger values blur oversized classes more aggressively, but add more egress overhead and more output variance.
-
-### Timing normalization envelope notes (`[censorship]`)
-
-`mask_timing_normalization_enabled` smooths timing differences between masking outcomes by applying a target duration envelope.
-
-- A random target is selected in `[mask_timing_normalization_floor_ms, mask_timing_normalization_ceiling_ms]`.
-- Fast paths are delayed up to the selected target.
-- Slow paths are not forced to finish by the ceiling (the envelope is best-effort shaping, not truncation).
-
-Recommended starting profile for timing shaping:
-
-- `mask_timing_normalization_enabled = true`
-- `mask_timing_normalization_floor_ms = 180`
-- `mask_timing_normalization_ceiling_ms = 320`
-
-If your backend or network is very bandwidth-constrained, reduce cap first. If probes are still too distinguishable in your environment, increase floor gradually.
-
-## [access]
-
-| Parameter | Type | Default | Constraints / validation | TOML shape example | Description |
-|---|---|---|---|---|---|
-| users | `Map<String, String>` | `{"default": "000…000"}` | Secret must be 32 hex characters. | `[access.users]`<br>`user = "32-hex secret"`<br>`user2 = "32-hex secret"` | User credentials map used for client authentication. |
-| user_ad_tags | `Map<String, String>` | `{}` | Every value must be exactly 32 hex characters. | `[access.user_ad_tags]`<br>`user = "32-hex ad_tag"` | Per-user ad tags used as override over `general.ad_tag`. |
-| user_max_tcp_conns | `Map<String, usize>` | `{}` | — | `[access.user_max_tcp_conns]`<br>`user = 500` | Per-user maximum concurrent TCP connections. |
-| user_expirations | `Map<String, DateTime<Utc>>` | `{}` | Timestamp must be valid RFC3339/ISO-8601 datetime. | `[access.user_expirations]`<br>`user = "2026-12-31T23:59:59Z"` | Per-user account expiration timestamps. |
-| user_data_quota | `Map<String, u64>` | `{}` | — | `[access.user_data_quota]`<br>`user = 1073741824` | Per-user traffic quota in bytes. |
-| user_max_unique_ips | `Map<String, usize>` | `{}` | — | `[access.user_max_unique_ips]`<br>`user = 16` | Per-user unique source IP limits. |
-| user_max_unique_ips_global_each | `usize` | `0` | — | `user_max_unique_ips_global_each = 0` | Global fallback used when `[access.user_max_unique_ips]` has no per-user override. |
-| user_max_unique_ips_mode | `"active_window" \| "time_window" \| "combined"` | `"active_window"` | — | `user_max_unique_ips_mode = "active_window"` | Unique source IP limit accounting mode. |
-| user_max_unique_ips_window_secs | `u64` | `30` | Must be `> 0`. | `user_max_unique_ips_window_secs = 30` | Window size (seconds) used by unique-IP accounting modes that use time windows. |
-| replay_check_len | `usize` | `65536` | — | `replay_check_len = 65536` | Replay-protection storage length. |
-| replay_window_secs | `u64` | `1800` | — | `replay_window_secs = 1800` | Replay-protection window in seconds. |
-| ignore_time_skew | `bool` | `false` | — | `ignore_time_skew = false` | Disables client/server timestamp skew checks in replay validation when enabled. |
-
-## [[upstreams]]
-
-| Parameter | Type | Default | Constraints / validation | Description |
-|---|---|---|---|---|
-| type | `"direct" \| "socks4" \| "socks5"` | — | Required field. | Upstream transport type selector. |
-| weight | `u16` | `1` | none | Base weight used by weighted-random upstream selection. |
-| enabled | `bool` | `true` | none | Disabled entries are excluded from upstream selection at runtime. |
-| scopes | `String` | `""` | none | Comma-separated scope tags used for request-level upstream filtering. |
-| interface | `String \| null` | `null` | Optional; type-specific runtime rules apply. | Optional outbound interface/local bind hint (supported with type-specific rules). |
-| bind_addresses | `String[] \| null` | `null` | Applies to `type = "direct"`. | Optional explicit local source bind addresses for `type = "direct"`. |
-| address | `String` | — | Required for `type = "socks4"` and `type = "socks5"`. | SOCKS server endpoint (`host:port` or `ip:port`) for SOCKS upstream types. |
-| user_id | `String \| null` | `null` | Only for `type = "socks4"`. | SOCKS4 CONNECT user ID (`type = "socks4"` only). |
-| username | `String \| null` | `null` | Only for `type = "socks5"`. | SOCKS5 username (`type = "socks5"` only). |
-| password | `String \| null` | `null` | Only for `type = "socks5"`. | SOCKS5 password (`type = "socks5"` only). |

docs/FAQ.en.md

@@ -1,5 +1,4 @@
 ## How to set up a "proxy sponsor" channel and statistics via the @MTProxybot
-
 1. Go to the @MTProxybot.
 2. Enter the `/newproxy` command.
 3. Send your server's IP address and port. For example: `1.2.3.4:443`.
@@ -32,23 +31,161 @@ use_middle_proxy = true
 hello = "ad_tag"
 hello2 = "ad_tag2"
 ```
+## Recognizability for DPI and crawler
 
-## Why do you need a middle proxy (ME)
+On April 1, 2026, we became aware of a method for detecting MTProxy Fake-TLS, 
+based on the ECH extension and the ordering of cipher suites, 
+as well as an overall unique JA3/JA4 fingerprint 
+that does not occur in modern browsers.
+
+> [!IMPORTANT]
+> TLS fingerprint has been fixed in latest version of clients for Desktop / Android / iOS.  
+> Please update your client for MTProxy Fake-TLS to work correctly.
+
+- We consider this a breakthrough aspect, which has no stable analogues today
+- Based on this: if `telemt` configured correctly, **TLS mode is completely identical to real-life handshake + communication** with a specified host
+- Here is our evidence:
+    - 212.220.88.77 - "dummy" host, running `telemt`
+    - `petrovich.ru` - `tls` + `masking` host, in HEX: `706574726f766963682e7275`
+    - **No MITM + No Fake Certificates/Crypto** = pure transparent *TCP Splice* to "best" upstream: MTProxy or tls/mask-host:
+      - DPI see legitimate HTTPS to `tls_host`, including *valid chain-of-trust* and entropy
+      - Crawlers completely satisfied receiving responses from `mask_host`
+  ### Client WITH secret-key accesses the MTProxy resource:
+  
+  <img width="360" height="439" alt="telemt" src="https://github.com/user-attachments/assets/39352afb-4a11-4ecc-9d91-9e8cfb20607d" />
+  
+  ### Client WITHOUT secret-key gets transparent access to the specified resource:
+    - with trusted certificate
+    - with original handshake
+    - with full request-response way
+    - with low-latency overhead
+```bash
+root@debian:~/telemt# curl -v -I --resolve petrovich.ru:443:212.220.88.77 https://petrovich.ru/
+* Added petrovich.ru:443:212.220.88.77 to DNS cache
+* Hostname petrovich.ru was found in DNS cache
+*   Trying 212.220.88.77:443...
+* Connected to petrovich.ru (212.220.88.77) port 443 (#0)
+* ALPN: offers h2,http/1.1
+* TLSv1.3 (OUT), TLS handshake, Client hello (1):
+*  CAfile: /etc/ssl/certs/ca-certificates.crt
+*  CApath: /etc/ssl/certs
+* TLSv1.3 (IN), TLS handshake, Server hello (2):
+* TLSv1.3 (IN), TLS handshake, Encrypted Extensions (8):
+* TLSv1.3 (IN), TLS handshake, Certificate (11):
+* TLSv1.3 (IN), TLS handshake, CERT verify (15):
+* TLSv1.3 (IN), TLS handshake, Finished (20):
+* TLSv1.3 (OUT), TLS change cipher, Change cipher spec (1):
+* TLSv1.3 (OUT), TLS handshake, Finished (20):
+* SSL connection using TLSv1.3 / TLS_AES_256_GCM_SHA384
+* ALPN: server did not agree on a protocol. Uses default.
+* Server certificate:
+*  subject: C=RU; ST=Saint Petersburg; L=Saint Petersburg; O=STD Petrovich; CN=*.petrovich.ru
+*  start date: Jan 28 11:21:01 2025 GMT
+*  expire date: Mar  1 11:21:00 2026 GMT
+*  subjectAltName: host "petrovich.ru" matched cert's "petrovich.ru"
+*  issuer: C=BE; O=GlobalSign nv-sa; CN=GlobalSign RSA OV SSL CA 2018
+*  SSL certificate verify ok.
+* using HTTP/1.x
+> HEAD / HTTP/1.1
+> Host: petrovich.ru
+> User-Agent: curl/7.88.1
+> Accept: */*
+> 
+* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
+* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
+* old SSL session ID is stale, removing
+< HTTP/1.1 200 OK
+HTTP/1.1 200 OK
+< Server: Variti/0.9.3a
+Server: Variti/0.9.3a
+< Date: Thu, 01 Jan 2026 00:0000 GMT
+Date: Thu, 01 Jan 2026 00:0000 GMT
+< Access-Control-Allow-Origin: *
+Access-Control-Allow-Origin: *
+< Content-Type: text/html
+Content-Type: text/html
+< Cache-Control: no-store
+Cache-Control: no-store
+< Expires: Thu, 01 Jan 2026 00:0000 GMT
+Expires: Thu, 01 Jan 2026 00:0000 GMT
+< Pragma: no-cache
+Pragma: no-cache
+< Set-Cookie: ipp_uid=XXXXX/XXXXX/XXXXX==; Expires=Tue, 31 Dec 2040 23:59:59 GMT; Domain=.petrovich.ru; Path=/
+Set-Cookie: ipp_uid=XXXXX/XXXXX/XXXXX==; Expires=Tue, 31 Dec 2040 23:59:59 GMT; Domain=.petrovich.ru; Path=/
+< Content-Type: text/html
+Content-Type: text/html
+< Content-Length: 31253
+Content-Length: 31253
+< Connection: keep-alive
+Connection: keep-alive
+< Keep-Alive: timeout=60
+Keep-Alive: timeout=60
+
+< 
+* Connection #0 to host petrovich.ru left intact
+
+```
+- We challenged ourselves, we kept trying and we didn't only *beat the air*: now, we have something to show you
+  - Do not just take our word for it? - This is great and we respect that: you can build your own `telemt` or download a build and check it right now
+
+
+## F.A.Q.
+
+### Telegram Calls via MTProxy
+- Telegram architecture **does NOT allow calls via MTProxy**, but only via SOCKS5, which cannot be obfuscated
+
+### How does DPI see MTProxy TLS?
+- DPI sees MTProxy in Fake TLS (ee) mode as TLS 1.3
+- the SNI you specify sends both the client and the server;
+- ALPN is similar to HTTP 1.1/2;
+- high entropy, which is normal for AES-encrypted traffic;
+
+### Whitelist on IP
+- MTProxy cannot work when there is: 
+  - no IP connectivity to the target host: Russian Whitelist on Mobile Networks - "Белый список"
+  - OR all TCP traffic is blocked
+  - OR high entropy/encrypted traffic is blocked: content filters at universities and critical infrastructure
+  - OR all TLS traffic is blocked
+  - OR specified port is blocked: use 443 to make it "like real"
+  - OR provided SNI is blocked: use "officially approved"/innocuous name
+- like most protocols on the Internet; 
+- these situations are observed:
+  - in China behind the Great Firewall
+  - in Russia on mobile networks, less in wired networks
+  - in Iran during "activity"
+
+### Why do you need a middle proxy (ME)
 https://github.com/telemt/telemt/discussions/167
 
+## How clients interact with Telegram DCs
+When you register a Telegram account, it gets permanently bound to one of Telegram's data centers (DCs).  
+It is deciced beforehand by Telegram based on the phone number's region.  
+This DC becomes your **home DC**: all content you upload (photos, videos, files, messages) is stored there.  
+Your client authenticates on it with every connection.  
 
-## How many people can use one link
+For example, if your account is registered on **DC2**, your client will always connect to DC2 first.  
+When you open a chat with another user whose home DC is **DC5**, your client opens an additional connection to DC5 to download their media.  
+Those cross-DC requests are normal and happen constantly.  
 
+> [!WARNING]
+> Because every session is anchored to your home DC, an outage there causes other DCs to be unavaliable.  
+> If your home DC is DC2 and DC2 goes down, you **cannot** reach DC5 even though DC5 itself is perfectly healthy.  
+> The client has no valid session to route the request through.  
+
+This is also why an MTProxy only needs to reach Telegram's DC infrastructure as a whole.  
+The proxy itself doesn't care which DC your account lives on. The client negotiates the correct DC through the proxy after connecting.
+
+### How many people can use one link
 By default, an unlimited number of people can use a single link.  
 However, you can limit the number of unique IP addresses for each user:
 ```toml
 [access.user_max_unique_ips]
 hello = 1
 ```
-This parameter sets the maximum number of unique IP addresses from which a single link can be used simultaneously. If the first user disconnects, a second one can connect. At the same time, multiple users can connect from a single IP address simultaneously (for example, devices on the same Wi-Fi network).
-
-## How to create multiple different links
+This parameter sets the maximum number of unique IP addresses from which a single link can be used simultaneously. If the first user disconnects, a second one can connect.
+At the same time, multiple users can connect from a single IP address simultaneously (for example, devices on the same Wi-Fi network).
 
+### How to create multiple different links
 1. Generate the required number of secrets using the command: `openssl rand -hex 16`.
 2. Open the configuration file: `nano /etc/telemt/telemt.toml`.
 3. Add new users to the `[access.users]` section:
@@ -64,7 +201,7 @@ user3 = "00000000000000000000000000000003"
 curl -s http://127.0.0.1:9091/v1/users | jq
 ```
 
-## "Unknown TLS SNI" error
+### "Unknown TLS SNI" error
 Usually, this error occurs if you have changed the `tls_domain` parameter, but users continue to connect using old links with the previous domain.
 
 If you need to allow connections with any domains (ignoring SNI mismatches), add the following parameters:
@@ -73,7 +210,14 @@ If you need to allow connections with any domains (ignoring SNI mismatches), add
 unknown_sni_action = "mask"
 ```
 
-## How to view metrics
+Alternatively, if you want telemt to behave like a vanilla nginx with `ssl_reject_handshake on;` on unknown SNI (emit a TLS `unrecognized_name` alert and close the connection), use:
+```toml
+[censorship]
+unknown_sni_action = "reject_handshake"
+```
+This does not recover stale clients, but it makes port 443 wire-indistinguishable from a stock web server that simply does not host the requested vhost.
+
+### How to view metrics
 
 1. Open the configuration file: `nano /etc/telemt/telemt.toml`.
 2. Add the following parameters:
@@ -87,6 +231,25 @@ metrics_whitelist = ["127.0.0.1/32", "::1/128", "0.0.0.0/0"]
 > [!WARNING]
 > The value `"0.0.0.0/0"` in `metrics_whitelist` opens access to metrics from any IP address. It is recommended to replace it with your personal IP, for example: `"1.2.3.4/32"`.
 
+### Too many open files
+- On a fresh Linux install the default open file limit is low; under load `telemt` may fail with `Accept error: Too many open files`
+- **Systemd**: add `LimitNOFILE=65536` to the `[Service]` section (already included in the example above)
+- **Docker**: add `--ulimit nofile=65536:65536` to your `docker run` command, or in `docker-compose.yml`:
+```yaml
+ulimits:
+  nofile:
+    soft: 65536
+    hard: 65536
+```
+- **System-wide** (optional): add to `/etc/security/limits.conf`:
+```
+*       soft    nofile  1048576
+*       hard    nofile  1048576
+root    soft    nofile  1048576
+root    hard    nofile  1048576
+```
+
+
 ## Additional parameters
 
 ### Domain in the link instead of IP

docs/FAQ.ru.md

@@ -32,10 +32,164 @@ use_middle_proxy = true
 hello = "ad_tag"
 hello2 = "ad_tag2"
 ```
+## Распознаваемость для DPI и сканеров
+1 апреля 2026 года нам стало известно о методе обнаружения MTProxy Fake-TLS, основанном на расширении ECH и порядке набора шифров,
+а также об общем уникальном отпечатке JA3/JA4, который не встречается в современных браузерах.
+
+> [!IMPORTANT]
+> Проблема с TLS отпечатком исправлена в последних версиях клиентов Telegram для Desktop / Android / iOS.  
+> Обновите свой клиент для корректной работы с MTProxy Fake-TLS!
+
+- Мы считаем это прорывом, которому на сегодняшний день нет стабильных аналогов;
+- Исходя из этого: если `telemt` настроен правильно, **режим TLS полностью идентичен реальному «рукопожатию» + обмену данными** с указанным хостом;
+- Вот наши доказательства:
+    - 212.220.88.77 — «фиктивный» хост, на котором запущен `telemt`;
+    - `petrovich.ru` — хост с `tls` + `masking`, в HEX: `706574726f766963682e7275`;
+    - **Без MITM + без поддельных сертификатов/шифрования** = чистое прозрачное *TCP Splice* к «лучшему» исходному серверу: MTProxy или tls/mask-host:
+      - DPI видит легитимный HTTPS к `tls_host`, включая *достоверную цепочку доверия* и энтропию;
+      - Краулеры полностью удовлетворены получением ответов от `mask_host`.
+ 
+  ### Клиент С секретным ключом получает доступ к ресурсу MTProxy:
+  
+  <img width="360" height="439" alt="telemt" src="https://github.com/user-attachments/assets/39352afb-4a11-4ecc-9d91-9e8cfb20607d" />
+  
+  ### Клиент БЕЗ секретного ключа получает прозрачный доступ к указанному ресурсу:
+    - с доверенным сертификатом;
+    - с исходным «рукопожатием»;
+    - с полным циклом запрос-ответ;
+    - с низкой задержкой.
+
+```bash
+root@debian:~/telemt# curl -v -I --resolve petrovich.ru:443:212.220.88.77 https://petrovich.ru/
+* Added petrovich.ru:443:212.220.88.77 to DNS cache
+* Hostname petrovich.ru was found in DNS cache
+*   Trying 212.220.88.77:443...
+* Connected to petrovich.ru (212.220.88.77) port 443 (#0)
+* ALPN: offers h2,http/1.1
+* TLSv1.3 (OUT), TLS handshake, Client hello (1):
+*  CAfile: /etc/ssl/certs/ca-certificates.crt
+*  CApath: /etc/ssl/certs
+* TLSv1.3 (IN), TLS handshake, Server hello (2):
+* TLSv1.3 (IN), TLS handshake, Encrypted Extensions (8):
+* TLSv1.3 (IN), TLS handshake, Certificate (11):
+* TLSv1.3 (IN), TLS handshake, CERT verify (15):
+* TLSv1.3 (IN), TLS handshake, Finished (20):
+* TLSv1.3 (OUT), TLS change cipher, Change cipher spec (1):
+* TLSv1.3 (OUT), TLS handshake, Finished (20):
+* SSL connection using TLSv1.3 / TLS_AES_256_GCM_SHA384
+* ALPN: server did not agree on a protocol. Uses default.
+* Server certificate:
+*  subject: C=RU; ST=Saint Petersburg; L=Saint Petersburg; O=STD Petrovich; CN=*.petrovich.ru
+*  start date: Jan 28 11:21:01 2025 GMT
+*  expire date: Mar  1 11:21:00 2026 GMT
+*  subjectAltName: host "petrovich.ru" matched cert's "petrovich.ru"
+*  issuer: C=BE; O=GlobalSign nv-sa; CN=GlobalSign RSA OV SSL CA 2018
+*  SSL certificate verify ok.
+* using HTTP/1.x
+> HEAD / HTTP/1.1
+> Host: petrovich.ru
+> User-Agent: curl/7.88.1
+> Accept: */*
+> 
+* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
+* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
+* old SSL session ID is stale, removing
+< HTTP/1.1 200 OK
+HTTP/1.1 200 OK
+< Server: Variti/0.9.3a
+Server: Variti/0.9.3a
+< Date: Thu, 01 Jan 2026 00:0000 GMT
+Date: Thu, 01 Jan 2026 00:0000 GMT
+< Access-Control-Allow-Origin: *
+Access-Control-Allow-Origin: *
+< Content-Type: text/html
+Content-Type: text/html
+< Cache-Control: no-store
+Cache-Control: no-store
+< Expires: Thu, 01 Jan 2026 00:0000 GMT
+Expires: Thu, 01 Jan 2026 00:0000 GMT
+< Pragma: no-cache
+Pragma: no-cache
+< Set-Cookie: ipp_uid=XXXXX/XXXXX/XXXXX==; Expires=Tue, 31 Dec 2040 23:59:59 GMT; Domain=.petrovich.ru; Path=/
+Set-Cookie: ipp_uid=XXXXX/XXXXX/XXXXX==; Expires=Tue, 31 Dec 2040 23:59:59 GMT; Domain=.petrovich.ru; Path=/
+< Content-Type: text/html
+Content-Type: text/html
+< Content-Length: 31253
+Content-Length: 31253
+< Connection: keep-alive
+Connection: keep-alive
+< Keep-Alive: timeout=60
+Keep-Alive: timeout=60
+
+< 
+* Connection #0 to host petrovich.ru left intact
+
+```
+- Мы поставили перед собой задачу, не сдавались и не просто «бились в пустоту»: теперь у нас есть что вам показать.
+- Не верите нам на слово? — Это прекрасно, и мы уважаем ваше решение: вы можете собрать свой собственный `telemt` или скачать готовую сборку и проверить её прямо сейчас.
+
+### Звонки в Telegram через MTProxy
+- Архитектура Telegram **НЕ поддерживает звонки через MTProxy**, а только через SOCKS5, который невозможно замаскировать
+
+### Как DPI распознает TLS-соединение MTProxy?
+- DPI распознает MTProxy в режиме Fake TLS (ee) как TLS 1.3
+- указанный вами SNI отправляется как клиентом, так и сервером;
+- ALPN аналогичен HTTP 1.1/2;
+- высокая энтропия, что нормально для трафика, зашифрованного AES;
+
+### Белый список по IP
+- MTProxy не может работать, если: 
+  - отсутствует IP-связь с целевым хостом: российский белый список в мобильных сетях — «Белый список»;
+  - ИЛИ весь TCP-трафик заблокирован;
+  - ИЛИ трафик с высокой энтропией/зашифрованный трафик заблокирован: контент-фильтры в университетах и критически важной инфраструктуре;
+  - ИЛИ весь TLS-трафик заблокирован;
+  - ИЛИ заблокирован указанный порт: используйте 443, чтобы сделать его «как настоящий»;
+  - ИЛИ заблокирован предоставленный SNI: используйте «официально одобренное»/безобидное имя;
+- как и большинство протоколов в Интернете; 
+- такие ситуации наблюдаются:
+  - в Китае за Великим файрволом;
+  - в России в мобильных сетях, реже в проводных сетях;
+  - в Иране во время «активности».
+
 
 ## Зачем нужен middle proxy (ME)
 https://github.com/telemt/telemt/discussions/167
 
+## Как клиенты взаимодействуют с дата-центрами Telegram
+При регистрации аккаунта Telegram он навсегда привязывается к одному из дата-центров (DC).  
+Telegram заранее определяет к какому DC привязать аккаунт исходя из региона, к которому относиться номер телефона.  
+Этот DC становится вашим **домашним**: именно там хранится весь контент, который вы загружаете (фото, видео, файлы, сообщения).  
+И именно на нем клиент авторизуется при каждом подключении.  
+
+Например, если ваш аккаунт зарегистрирован на **DC2**, клиент всегда будет подключаться в первую очередь к DC2.  
+Когда вы открываете переписку с пользователем, чей домашний DC — **DC5**, клиент устанавливает доп. соединение с DC5, чтобы загрузить его контент.  
+Такие кросс-запросы к DC — это нормальная часть работы Telegram.  
+
+> [!WARNING]
+> Поскольку аккаунт всегда привязан к домашнему DC, при его падении контент с других DC будет недоступен.  
+> Если ваш домашний DC — DC2, и DC2 лежит, вы **не сможете** достучаться  и до DC5, даже если сам DC5 полностью исправен.  
+> У клиента просто нет валидной сессии, через которую можно было бы направить запрос.  
+
+По той же причине MTProxy достаточно иметь доступ к инфраструктуре Telegram в целом.  
+Cамому MTProxy всё равно, на каком DC живёт ваш аккаунт. Клиент cам договаривается о нужном DC через прокси уже после подключения.  
+
+## Что такое dd и ee в контексте MTProxy?
+
+Это два разных режима работы прокси. Понять, какой режим используется, можно взглянув на начало секрета — там будет dd или ee, вот пример:
+tg://proxy?server=s1.dimasssss.space&port=443&secret=eebe3007e927acd147dde12bee8b1a7c9364726976652e676f6f676c652e636f6d
+
+dd — режим с мусорным трафиком, обфускацией данных, похожий на shadowsocks. У такого трафика есть заметный паттерн, который DPI умеют распознавать и впоследствии блокировать. Использовать этот режим на текущий момент не рекомендуется.
+
+ee — режим маскировки под существующий домен (FakeTLS), словно вы сёрфите в интернете через браузер. На текущий момент не попадает под блокировку.
+
+### Где эти режимы настраиваются?
+
+```toml
+В конфиге telemt.toml в разделе [general.modes]:
+classic = false # классический режим, давно стал бесполезным
+secure = false # переменная dd-режима
+tls = true # переменная ee-режима
+```
 
 ## Сколько человек может пользоваться одной ссылкой
 
@@ -73,6 +227,13 @@ curl -s http://127.0.0.1:9091/v1/users | jq
 unknown_sni_action = "mask"
 ```
 
+Альтернатива: если вы хотите, чтобы telemt на неизвестный SNI вёл себя как обычный nginx с `ssl_reject_handshake on;` (отдавал TLS-alert `unrecognized_name` и закрывал соединение), используйте:
+```toml
+[censorship]
+unknown_sni_action = "reject_handshake"
+```
+Это не пропускает старых клиентов, но делает поведение на 443-м порту неотличимым от стокового веб-сервера, у которого просто нет такого виртуального хоста.
+
 ## Как посмотреть метрики
 
 1. Откройте файл конфигурации: `nano /etc/telemt/telemt.toml`.
@@ -104,7 +265,7 @@ max_connections = 10000    # 0 - без ограничений, 10000 - по у
 ```
 
 ### Upstream Manager
-Для настройки исходящих подключений (апстримов) добавьте соответствующие параметры в секцию `[[upstreams]]` файла конфигурации:
+Для настройки исходящих подключений (Upstreams) добавьте соответствующие параметры в секцию `[[upstreams]]` файла конфигурации:
 
 #### Привязка к исходящему IP-адресу
 ```toml
@@ -119,20 +280,20 @@ interface = "192.168.1.100" # Замените на ваш исходящий IP
 - Без авторизации:
 ```toml
 [[upstreams]]
-type = "socks5"            # Specify SOCKS4 or SOCKS5
-address = "1.2.3.4:1234"   # SOCKS-server Address
-weight = 1                 # Set Weight for Scenarios
+type = "socks5"            # выбор типа SOCKS4 или SOCKS5
+address = "1.2.3.4:1234"   # адрес сервера SOCKS
+weight = 1                 # вес
 enabled = true
 ```
 
 - С авторизацией:
 ```toml
 [[upstreams]]
-type = "socks5"            # Specify SOCKS4 or SOCKS5
-address = "1.2.3.4:1234"   # SOCKS-server Address
-username = "user"          # Username for Auth on SOCKS-server
-password = "pass"          # Password for Auth on SOCKS-server
-weight = 1                 # Set Weight for Scenarios
+type = "socks5"            # выбор типа SOCKS4 или SOCKS5
+address = "1.2.3.4:1234"   # адрес сервера SOCKS
+username = "user"          # имя пользователя
+password = "pass"          # пароль
+weight = 1                 # вес
 enabled = true
 ```
 

docs/LICENSE/LICENSE.de.md

@@ -1,92 +0,0 @@
-# Öffentliche TELEMT-Lizenz 3
-
-***Alle Rechte vorbehalten (c) 2026 Telemt***
-
-Hiermit wird jeder Person, die eine Kopie dieser Software und der dazugehörigen Dokumentation (nachfolgend "Software") erhält, unentgeltlich die Erlaubnis erteilt, die Software ohne Einschränkungen zu nutzen, einschließlich des Rechts, die Software zu verwenden, zu vervielfältigen, zu ändern, abgeleitete Werke zu erstellen, zu verbinden, zu veröffentlichen, zu verbreiten, zu unterlizenzieren und/oder Kopien der Software zu verkaufen sowie diese Rechte auch denjenigen einzuräumen, denen die Software zur Verfügung gestellt wird, vorausgesetzt, dass sämtliche Urheberrechtshinweise sowie die Bedingungen und Bestimmungen dieser Lizenz eingehalten werden.
-
-### Begriffsbestimmungen
-
-Für die Zwecke dieser Lizenz gelten die folgenden Definitionen:
-
-**"Software" (Software)** — die Telemt-Software einschließlich Quellcode, Dokumentation und sämtlicher zugehöriger Dateien, die unter den Bedingungen dieser Lizenz verbreitet werden.
-
-**"Contributor" (Contributor)** — jede natürliche oder juristische Person, die Code, Patches, Dokumentation oder andere Materialien eingereicht hat, die von den Maintainers des Projekts angenommen und in die Software aufgenommen wurden.
-
-**"Beitrag" (Contribution)** — jedes urheberrechtlich geschützte Werk, das bewusst zur Aufnahme in die Software eingereicht wurde.
-
-**"Modifizierte Version" (Modified Version)** — jede Version der Software, die gegenüber der ursprünglichen Software geändert, angepasst, erweitert oder anderweitig modifiziert wurde.
-
-**"Maintainers" (Maintainers)** — natürliche oder juristische Personen, die für das offizielle Telemt-Projekt und dessen offizielle Veröffentlichungen verantwortlich sind.
-
-### 1 Urheberrechtshinweis (Attribution)
-
-Bei der Weitergabe der Software, sowohl in Form des Quellcodes als auch in binärer Form, MÜSSEN folgende Elemente erhalten bleiben:
-
-- der oben genannte Urheberrechtshinweis;
-- der vollständige Text dieser Lizenz;
-- sämtliche bestehenden Hinweise auf Urheberschaft.
-
-### 2 Hinweis auf Modifikationen
-
-Wenn Änderungen an der Software vorgenommen werden, MUSS die Person, die diese Änderungen vorgenommen hat, eindeutig darauf hinweisen, dass die Software modifiziert wurde, und eine kurze Beschreibung der vorgenommenen Änderungen beifügen.
-
-Modifizierte Versionen der Software DÜRFEN NICHT als die originale Version von Telemt dargestellt werden.
-
-### 3 Marken und Bezeichnungen
-
-Diese Lizenz GEWÄHRT KEINE Rechte zur Nutzung der Bezeichnung **"Telemt"**, des Telemt-Logos oder sonstiger Marken, Kennzeichen oder Branding-Elemente von Telemt.
-
-Weiterverbreitete oder modifizierte Versionen der Software DÜRFEN die Bezeichnung Telemt nicht in einer Weise verwenden, die bei Nutzern den Eindruck eines offiziellen Ursprungs oder einer Billigung durch das Telemt-Projekt erwecken könnte, sofern hierfür keine ausdrückliche Genehmigung der Maintainers vorliegt.
-
-Die Verwendung der Bezeichnung **Telemt** zur Beschreibung einer modifizierten Version der Software ist nur zulässig, wenn diese Version eindeutig als modifiziert oder inoffiziell gekennzeichnet ist.
-
-Jegliche Verbreitung, die Nutzer vernünftigerweise darüber täuschen könnte, dass es sich um eine offizielle Veröffentlichung von Telemt handelt, ist untersagt.
-
-### 4 Transparenz bei der Verbreitung von Binärversionen
-
-Im Falle der Verbreitung kompilierter Binärversionen der Software wird der Verbreiter HIERMIT ERMUTIGT (encouraged), soweit dies vernünftigerweise möglich ist, Zugang zum entsprechenden Quellcode sowie zu den Build-Anweisungen bereitzustellen.
-
-Diese Praxis trägt zur Transparenz bei und ermöglicht es Empfängern, die Integrität und Reproduzierbarkeit der verbreiteten Builds zu überprüfen.
-
-## 5 Gewährung einer Patentlizenz und Beendigung von Rechten
-
-Jeder Contributor gewährt den Empfängern der Software eine unbefristete, weltweite, nicht-exklusive, unentgeltliche, lizenzgebührenfreie und unwiderrufliche Patentlizenz für:
-
-- die Herstellung,
-- die Beauftragung der Herstellung,
-- die Nutzung,
-- das Anbieten zum Verkauf,
-- den Verkauf,
-- den Import,
-- sowie jede sonstige Verbreitung der Software.
-
-Diese Patentlizenz erstreckt sich ausschließlich auf solche Patentansprüche, die notwendigerweise durch den jeweiligen Beitrag des Contributors allein oder in Kombination mit der Software verletzt würden.
-
-Leitet eine Person ein Patentverfahren ein oder beteiligt sich daran, einschließlich Gegenklagen oder Kreuzklagen, mit der Behauptung, dass die Software oder ein darin enthaltener Beitrag ein Patent verletzt, **erlöschen sämtliche durch diese Lizenz gewährten Rechte für diese Person unmittelbar mit Einreichung der Klage**.
-
-Darüber hinaus erlöschen alle durch diese Lizenz gewährten Rechte **automatisch**, wenn eine Person ein gerichtliches Verfahren einleitet, in dem behauptet wird, dass die Software selbst ein Patent oder andere Rechte des geistigen Eigentums verletzt.
-
-### 6 Beteiligung und Beiträge zur Entwicklung
-
-Sofern ein Contributor nicht ausdrücklich etwas anderes erklärt, gilt jeder Beitrag, der bewusst zur Aufnahme in die Software eingereicht wird, als unter den Bedingungen dieser Lizenz lizenziert.
-
-Durch die Einreichung eines Beitrags gewährt der Contributor den Maintainers des Telemt-Projekts sowie allen Empfängern der Software die in dieser Lizenz beschriebenen Rechte in Bezug auf diesen Beitrag.
-
-### 7 Urheberhinweis bei Netzwerk- und Servicenutzung
-
-Wird die Software zur Bereitstellung eines öffentlich zugänglichen Netzwerkdienstes verwendet, MUSS der Betreiber dieses Dienstes einen Hinweis auf die Urheberschaft von Telemt an mindestens einer der folgenden Stellen anbringen:
-
-* in der Servicedokumentation;
-* in der Dienstbeschreibung;
-* auf einer Seite "Über" oder einer vergleichbaren Informationsseite;
-* in anderen für Nutzer zugänglichen Materialien, die in angemessenem Zusammenhang mit dem Dienst stehen.
-
-Ein solcher Hinweis DARF NICHT den Eindruck erwecken, dass der Dienst vom Telemt-Projekt oder dessen Maintainers unterstützt oder offiziell gebilligt wird.
-
-### 8 Haftungsausschluss und salvatorische Klausel
-
-DIE SOFTWARE WIRD "WIE BESEHEN" BEREITGESTELLT, OHNE JEGLICHE AUSDRÜCKLICHE ODER STILLSCHWEIGENDE GEWÄHRLEISTUNG, EINSCHLIESSLICH, ABER NICHT BESCHRÄNKT AUF GEWÄHRLEISTUNGEN DER MARKTGÄNGIGKEIT, DER EIGNUNG FÜR EINEN BESTIMMTEN ZWECK UND DER NICHTVERLETZUNG VON RECHTEN.
-
-IN KEINEM FALL HAFTEN DIE AUTOREN ODER RECHTEINHABER FÜR IRGENDWELCHE ANSPRÜCHE, SCHÄDEN ODER SONSTIGE HAFTUNG, DIE AUS VERTRAG, UNERLAUBTER HANDLUNG ODER AUF ANDERE WEISE AUS DER SOFTWARE ODER DER NUTZUNG DER SOFTWARE ENTSTEHEN.
-
-SOLLTE EINE BESTIMMUNG DIESER LIZENZ ALS UNWIRKSAM ODER NICHT DURCHSETZBAR ANGESEHEN WERDEN, IST DIESE BESTIMMUNG SO AUSZULEGEN, DASS SIE DEM URSPRÜNGLICHEN WILLEN DER PARTEIEN MÖGLICHST NAHEKOMMT; DIE ÜBRIGEN BESTIMMUNGEN BLEIBEN DAVON UNBERÜHRT UND IN VOLLER WIRKUNG.

docs/LICENSE/LICENSE.en.md

@@ -1,143 +0,0 @@
-###### TELEMT Public License 3 ######
-##### Copyright (c) 2026 Telemt #####
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this Software and associated documentation files (the "Software"),
-to use, reproduce, modify, prepare derivative works of, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to permit
-persons to whom the Software is furnished to do so, provided that all
-copyright notices, license terms, and conditions set forth in this License
-are preserved and complied with.
-
-### Official Translations
-
-The canonical version of this License is the English version.
-
-Official translations are provided for informational purposes only
-and for convenience, and do not have legal force. In case of any
-discrepancy, the English version of this License shall prevail.
-
-Available versions:
-- English in Markdown: docs/LICENSE/LICENSE.md
-- German: docs/LICENSE/LICENSE.de.md
-- Russian: docs/LICENSE/LICENSE.ru.md
-
-### Definitions
-
-For the purposes of this License:
-
-"Software" means the Telemt software, including source code, documentation,
-and any associated files distributed under this License.
-
-"Contributor" means any person or entity that submits code, patches,
-documentation, or other contributions to the Software that are accepted
-into the Software by the maintainers.
-
-"Contribution" means any work of authorship intentionally submitted
-to the Software for inclusion in the Software.
-
-"Modified Version" means any version of the Software that has been
-changed, adapted, extended, or otherwise modified from the original
-Software.
-
-"Maintainers" means the individuals or entities responsible for
-the official Telemt project and its releases.
-
-#### 1 Attribution
-
-Redistributions of the Software, in source or binary form, MUST RETAIN the
-above copyright notice, this license text, and any existing attribution
-notices.
-
-#### 2 Modification Notice
-
-If you modify the Software, you MUST clearly state that the Software has been
-modified and include a brief description of the changes made.
-
-Modified versions MUST NOT be presented as the original Telemt.
-
-#### 3 Trademark and Branding
-
-This license DOES NOT grant permission to use the name "Telemt", 
-the Telemt logo, or any Telemt trademarks or branding.
-
-Redistributed or modified versions of the Software MAY NOT use the Telemt
-name in a way that suggests endorsement or official origin without explicit
-permission from the Telemt maintainers.
-
-Use of the name "Telemt" to describe a modified version of the Software
-is permitted only if the modified version is clearly identified as a
-modified or unofficial version.
-
-Any distribution that could reasonably confuse users into believing that
-the software is an official Telemt release is prohibited.
-
-#### 4 Binary Distribution Transparency
-
-If you distribute compiled binaries of the Software,
-you are ENCOURAGED to provide access to the corresponding
-source code and build instructions where reasonably possible.
-
-This helps preserve transparency and allows recipients to verify the
-integrity and reproducibility of distributed builds.
-
-#### 5 Patent Grant and Defensive Termination Clause
-
-Each contributor grants you a perpetual, worldwide, non-exclusive,
-no-charge, royalty-free, irrevocable patent license to make, have made,
-use, offer to sell, sell, import, and otherwise transfer the Software.
-
-This patent license applies only to those patent claims necessarily
-infringed by the contributor’s contribution alone or by combination of
-their contribution with the Software.
-
-If you initiate or participate in any patent litigation, including
-cross-claims or counterclaims, alleging that the Software or any
-contribution incorporated within the Software constitutes patent
-infringement, then **all rights granted to you under this license shall
-terminate immediately** as of the date such litigation is filed.
-
-Additionally, if you initiate legal action alleging that the
-Software itself infringes your patent or other intellectual
-property rights, then all rights granted to you under this
-license SHALL TERMINATE automatically.
-
-#### 6 Contributions
-
-Unless you explicitly state otherwise, any Contribution intentionally
-submitted for inclusion in the Software shall be licensed under the terms
-of this License.
-
-By submitting a Contribution, you grant the Telemt maintainers and all
-recipients of the Software the rights described in this License with
-respect to that Contribution.
-
-#### 7 Network Use Attribution
-
-If the Software is used to provide a publicly accessible network service,
-the operator of such service MUST provide attribution to Telemt in at least
-one of the following locations:
-
-- service documentation
-- service description
-- an "About" or similar informational page
-- other user-visible materials reasonably associated with the service
-
-Such attribution MUST NOT imply endorsement by the Telemt project or its
-maintainers.
-
-#### 8 Disclaimer of Warranty and Severability Clause
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-
-IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
-DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
-OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
-USE OR OTHER DEALINGS IN THE SOFTWARE
-
-IF ANY PROVISION OF THIS LICENSE IS HELD TO BE INVALID OR UNENFORCEABLE,
-SUCH PROVISION SHALL BE INTERPRETED TO REFLECT THE ORIGINAL INTENT
-OF THE PARTIES AS CLOSELY AS POSSIBLE, AND THE REMAINING PROVISIONS
-SHALL REMAIN IN FULL FORCE AND EFFECT

docs/LICENSE/LICENSE.ru.md

@@ -1,90 +0,0 @@
-# Публичная лицензия TELEMT 3
-
-***Все права защищёны (c) 2026 Telemt***
-
-Настоящим любому лицу, получившему копию данного программного обеспечения и сопутствующей документации (далее — "Программное обеспечение"), безвозмездно предоставляется разрешение использовать Программное обеспечение без ограничений, включая право использовать, воспроизводить, изменять, создавать производные произведения, объединять, публиковать, распространять, сублицензировать и (или) продавать копии Программного обеспечения, а также предоставлять такие права лицам, которым предоставляется Программное обеспечение, при условии соблюдения всех уведомлений об авторских правах, условий и положений настоящей Лицензии.
-
-### Определения
-
-Для целей настоящей Лицензии применяются следующие определения:
-
-**"Программное обеспечение" (Software)** — программное обеспечение Telemt, включая исходный код, документацию и любые связанные файлы, распространяемые на условиях настоящей Лицензии.
-
-**"Контрибьютор" (Contributor)** — любое физическое или юридическое лицо, направившее код, исправления (патчи), документацию или иные материалы, которые были приняты мейнтейнерами проекта и включены в состав Программного обеспечения.
-
-**"Вклад" (Contribution)** — любое произведение авторского права, намеренно представленное для включения в состав Программного обеспечения.
-
-**"Модифицированная версия" (Modified Version)** — любая версия Программного обеспечения, которая была изменена, адаптирована, расширена или иным образом модифицирована по сравнению с исходным Программным обеспечением.
-
-**"Мейнтейнеры" (Maintainers)** — физические или юридические лица, ответственные за официальный проект Telemt и его официальные релизы.
-
-### 1 Указание авторства
-
-При распространении Программного обеспечения, как в форме исходного кода, так и в бинарной форме, ДОЛЖНЫ СОХРАНЯТЬСЯ:
-
-- указанное выше уведомление об авторских правах;
-- текст настоящей Лицензии;
-- любые существующие уведомления об авторстве.
-
-### 2 Уведомление о модификации
-
-В случае внесения изменений в Программное обеспечение лицо, осуществившее такие изменения, ОБЯЗАНО явно указать, что Программное обеспечение было модифицировано, а также включить краткое описание внесённых изменений.
-
-Модифицированные версии Программного обеспечения НЕ ДОЛЖНЫ представляться как оригинальная версия Telemt.
-
-### 3 Товарные знаки и обозначения
-
-Настоящая Лицензия НЕ ПРЕДОСТАВЛЯЕТ права использовать наименование **"Telemt"**, логотип Telemt, а также любые товарные знаки, фирменные обозначения или элементы бренда Telemt.
-
-Распространяемые или модифицированные версии Программного обеспечения НЕ ДОЛЖНЫ использовать наименование Telemt таким образом, который может создавать у пользователей впечатление официального происхождения либо одобрения со стороны проекта Telemt без явного разрешения мейнтейнеров проекта.
-
-Использование наименования **Telemt** для описания модифицированной версии Программного обеспечения допускается только при условии, что такая версия ясно обозначена как модифицированная или неофициальная.
-
-Запрещается любое распространение, которое может разумно вводить пользователей в заблуждение относительно того, что программное обеспечение является официальным релизом Telemt.
-
-### 4 Прозрачность распространения бинарных версий
-
-В случае распространения скомпилированных бинарных версий Программного обеспечения распространитель НАСТОЯЩИМ ПОБУЖДАЕТСЯ предоставлять доступ к соответствующему исходному коду и инструкциям по сборке, если это разумно возможно.
-
-Такая практика способствует прозрачности распространения и позволяет получателям проверять целостность и воспроизводимость распространяемых сборок.
-
-### 5 Предоставление патентной лицензии и прекращение прав
-
-Каждый контрибьютор предоставляет получателям Программного обеспечения бессрочную, всемирную, неисключительную, безвозмездную, не требующую выплаты роялти и безотзывную патентную лицензию на:
-
-- изготовление,
-- поручение изготовления,
-- использование,
-- предложение к продаже,
-- продажу,
-- импорт,
-- и иное распространение Программного обеспечения.
-
-Такая патентная лицензия распространяется исключительно на те патентные требования, которые неизбежно нарушаются соответствующим вкладом контрибьютора как таковым либо его сочетанием с Программным обеспечением.
-
-Если лицо инициирует либо участвует в каком-либо судебном разбирательстве по патентному спору, включая встречные или перекрёстные иски, утверждая, что Программное обеспечение либо любой вклад, включённый в него, нарушает патент, **все права, предоставленные такому лицу настоящей Лицензией, немедленно прекращаются** с даты подачи соответствующего иска.
-
-Кроме того, если лицо инициирует судебное разбирательство, утверждая, что само Программное обеспечение нарушает его патентные либо иные права интеллектуальной собственности, все права, предоставленные настоящей Лицензией, **автоматически прекращаются**.
-
-### 6 Участие и вклад в разработку
-
-Если контрибьютор явно не указал иное, любой Вклад, намеренно представленный для включения в Программное обеспечение, считается лицензированным на условиях настоящей Лицензии.
-Путём предоставления Вклада контрибьютор предоставляет мейнтейнером проекта Telemt и всем получателям Программного обеспечения права, предусмотренные настоящей Лицензией, в отношении такого Вклада.
-
-### 7 Указание авторства при сетевом и сервисном использовании
-
-В случае использования Программного обеспечения для предоставления публично доступного сетевого сервиса оператор такого сервиса ОБЯЗАН обеспечить указание авторства Telemt как минимум в одном из следующих мест:
-- документация сервиса;
-- описание сервиса;
-- страница "О программе" или аналогичная информационная страница;
-- иные материалы, доступные пользователям и разумно связанные с данным сервисом.
-
-Такое указание авторства НЕ ДОЛЖНО создавать впечатление одобрения или официальной поддержки со стороны проекта Telemt либо его мейнтейнеров.
-
-### 8 Отказ от гарантий и делимость положений
-
-ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ "КАК ЕСТЬ", БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ, ЯВНЫХ ИЛИ ПОДРАЗУМЕВАЕМЫХ, ВКЛЮЧАЯ, НО НЕ ОГРАНИЧИВАЯСЬ ГАРАНТИЯМИ КОММЕРЧЕСКОЙ ПРИГОДНОСТИ, ПРИГОДНОСТИ ДЛЯ КОНКРЕТНОЙ ЦЕЛИ И НЕНАРУШЕНИЯ ПРАВ.
-
-НИ ПРИ КАКИХ ОБСТОЯТЕЛЬСТВАХ АВТОРЫ ИЛИ ПРАВООБЛАДАТЕЛИ НЕ НЕСУТ ОТВЕТСТВЕННОСТИ ПО КАКИМ-ЛИБО ТРЕБОВАНИЯМ, УБЫТКАМ ИЛИ ИНОЙ ОТВЕТСТВЕННОСТИ, ВОЗНИКАЮЩЕЙ В РЕЗУЛЬТАТЕ ДОГОВОРА, ДЕЛИКТА ИЛИ ИНЫМ ОБРАЗОМ, СВЯЗАННЫМ С ПРОГРАММНЫМ ОБЕСПЕЧЕНИЕМ ИЛИ ЕГО ИСПОЛЬЗОВАНИЕМ.
-
-В СЛУЧАЕ ЕСЛИ КАКОЕ-ЛИБО ПОЛОЖЕНИЕ НАСТОЯЩЕЙ ЛИЦЕНЗИИ ПРИЗНАЁТСЯ НЕДЕЙСТВИТЕЛЬНЫМ ИЛИ НЕПРИМЕНИМЫМ, ТАКОЕ ПОЛОЖЕНИЕ ПОДЛЕЖИТ ТОЛКОВАНИЮ МАКСИМАЛЬНО БЛИЗКО К ИСХОДНОМУ НАМЕРЕНИЮ СТОРОН, ПРИ ЭТОМ ОСТАЛЬНЫЕ ПОЛОЖЕНИЯ СОХРАНЯЮТ ПОЛНУЮ ЮРИДИЧЕСКУЮ СИЛУ.

docs/LICENSE/TELEMT-LICENSE.en.md

@@ -0,0 +1,120 @@
+# TELEMT License 3.3
+
+***Copyright (c) 2026 Telemt***
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this Software and associated documentation files (the "Software"), to use, reproduce, modify, prepare derivative works of, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, provided that all copyright notices, license terms, and conditions set forth in this License are preserved and complied with.
+
+### Official Translations
+
+The canonical version of this License is the English version.
+Official translations are provided for informational purposes only and for convenience, and do not have legal force. In case of any discrepancy, the English version of this License shall prevail.
+
+| Language    | Location |
+|-------------|----------|
+| English     | [docs/LICENSE/TELEMT-LICENSE.en.md](https://github.com/telemt/telemt/tree/main/docs/LICENSE/TELEMT-LICENSE.en.md)|
+| German      | [docs/LICENSE/TELEMT-LICENSE.de.md](https://github.com/telemt/telemt/tree/main/docs/LICENSE/TELEMT-LICENSE.de.md)|
+| Russian     | [docs/LICENSE/TELEMT-LICENSE.ru.md](https://github.com/telemt/telemt/tree/main/docs/LICENSE/TELEMT-LICENSE.ru.md)|
+
+### License Versioning Policy
+
+This License is version 3.3 of the TELEMT License.
+Each version of the Software is licensed under the License that accompanies its corresponding source code distribution.
+
+Future versions of the Software may be distributed under a different version of the TELEMT Public License or under a different license, as determined by the Telemt maintainers.
+
+Any such change of license applies only to the versions of the Software distributed with the new license and SHALL NOT retroactively affect any previously released versions of the Software.
+
+Recipients of the Software are granted rights only under the License provided with the version of the Software they received.
+
+Redistributions of the Software, including Modified Versions, MUST preserve the copyright notices, license text, and conditions of this License for all portions of the Software derived from Telemt.
+
+Additional terms or licenses may be applied to modifications or additional code added by a redistributor, provided that such terms do not restrict or alter the rights granted under this License for the original Telemt Software.
+
+Nothing in this section limits the rights granted under this License for versions of the Software already released.
+
+### Definitions
+
+For the purposes of this License:
+
+**"Software"** means the Telemt software, including source code, documentation, and any associated files distributed under this License.
+
+**"Contributor"** means any person or entity that submits code, patches, documentation, or other contributions to the Software that are accepted into the Software by the maintainers.
+
+**"Contribution"** means any work of authorship intentionally submitted to the Software for inclusion in the Software.
+
+**"Modified Version"** means any version of the Software that has been changed, adapted, extended, or otherwise modified from the original Software.
+
+**"Maintainers"** means the individuals or entities responsible for the official Telemt project and its releases.
+
+### 1 Attribution
+
+Redistributions of the Software, in source or binary form, MUST RETAIN:
+
+- the above copyright notice;
+- this license text;
+- any existing attribution notices.
+
+### 2 Modification Notice
+
+If you modify the Software, you MUST clearly state that the Software has been modified and include a brief description of the changes made.
+
+Modified versions MUST NOT be presented as the original Telemt.
+
+### 3 Trademark and Branding
+
+This license DOES NOT grant permission to use the name "Telemt", the Telemt logo, or any Telemt trademarks or branding.
+
+Redistributed or modified versions of the Software MAY NOT use the Telemt name in a way that suggests endorsement or official origin without explicit permission from the Telemt maintainers.
+
+Use of the name "Telemt" to describe a modified version of the Software is permitted only if the modified version is clearly identified as a modified or unofficial version.
+
+Any distribution that could reasonably confuse users into believing that the software is an official Telemt release is prohibited.
+
+### 4 Binary Distribution Transparency
+
+If you distribute compiled binaries of the Software, you are ENCOURAGED to provide access to the corresponding source code and build instructions where reasonably possible.
+
+This helps preserve transparency and allows recipients to verify the integrity and reproducibility of distributed builds.
+
+### 5 Patent Grant and Defensive Termination Clause
+
+Each contributor grants you a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable patent license to:
+
+- make,
+- have made,
+- use,
+- offer to sell,
+- sell,
+- import,
+- and otherwise transfer the Software.
+
+This patent license applies only to those patent claims necessarily infringed by the contributor’s contribution alone or by combination of their contribution with the Software.
+
+If you initiate or participate in any patent litigation, including cross-claims or counterclaims, alleging that the Software or any contribution incorporated within the Software constitutes patent infringement, then **all rights granted to you under this license shall terminate immediately** as of the date such litigation is filed.
+
+Additionally, if you initiate legal action alleging that the Software itself infringes your patent or other intellectual property rights, then all rights granted to you under this license SHALL TERMINATE automatically.
+
+### 6 Contributions
+
+Unless you explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Software shall be licensed under the terms of this License.
+
+By submitting a Contribution, you grant the Telemt maintainers and all recipients of the Software the rights described in this License with respect to that Contribution.
+
+### 7 Network Use Attribution
+
+If the Software is used to provide a publicly accessible network service, the operator of such service SHOULD provide attribution to Telemt in at least one of the following locations:
+
+- service documentation;
+- service description;
+- an "About" or similar informational page;
+- other user-visible materials reasonably associated with the service.
+
+Such attribution MUST NOT imply endorsement by the Telemt project or its maintainers.
+
+### 8 Disclaimer of Warranty and Severability Clause
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+IF ANY PROVISION OF THIS LICENSE IS HELD TO BE INVALID OR UNENFORCEABLE, SUCH PROVISION SHALL BE INTERPRETED TO REFLECT THE ORIGINAL INTENT OF THE PARTIES AS CLOSELY AS POSSIBLE, AND THE REMAINING PROVISIONS SHALL REMAIN IN FULL FORCE AND EFFECT.

docs/LICENSE/TELEMT-LICENSE.ru.md

@@ -0,0 +1,120 @@
+# TELEMT Лицензия 3.3
+
+***Copyright (c) 2026 Telemt***
+
+Настоящим безвозмездно предоставляется разрешение любому лицу, получившему копию данного программного обеспечения и сопутствующей документации (далее — "Программное обеспечение"), использовать, воспроизводить, изменять, создавать производные произведения, объединять, публиковать, распространять, сублицензировать и/или продавать копии Программного обеспечения, а также разрешать лицам, которым предоставляется Программное обеспечение, осуществлять указанные действия при условии соблюдения и сохранения всех уведомлений об авторском праве, условий и положений настоящей Лицензии.
+
+### Официальные переводы
+
+Канонической версией настоящей Лицензии является версия на английском языке.  
+Официальные переводы предоставляются исключительно в информационных целях и для удобства и не имеют юридической силы. В случае любых расхождений приоритет имеет английская версия.
+
+| Язык       | Расположение |
+|------------|--------------|
+| Русский    | [docs/LICENSE/TELEMT-LICENSE.ru.md](https://github.com/telemt/telemt/tree/main/docs/LICENSE/TELEMT-LICENSE.ru.md)|
+| Английский | [docs/LICENSE/TELEMT-LICENSE.en.md](https://github.com/telemt/telemt/tree/main/docs/LICENSE/TELEMT-LICENSE.en.md)|
+| Немецкий   | [docs/LICENSE/TELEMT-LICENSE.de.md](https://github.com/telemt/telemt/tree/main/docs/LICENSE/TELEMT-LICENSE.de.md)|
+
+### Политика версионирования лицензии
+
+Настоящая Лицензия является версией 3.3 Лицензии TELEMT.  
+Каждая версия Программного обеспечения лицензируется в соответствии с Лицензией, сопровождающей соответствующее распространение исходного кода.
+
+Будущие версии Программного обеспечения могут распространяться в соответствии с иной версией Лицензии TELEMT Public License либо под иной лицензией, определяемой мейнтейнерами Telemt.
+
+Любое такое изменение лицензии применяется исключительно к версиям Программного обеспечения, распространяемым с новой лицензией, и НЕ распространяется ретроактивно на ранее выпущенные версии Программного обеспечения.
+
+Получатели Программного обеспечения приобретают права исключительно в соответствии с Лицензией, предоставленной вместе с полученной ими версией Программного обеспечения.
+
+При распространении Программного обеспечения, включая Модифицированные версии, ОБЯЗАТЕЛЬНО сохранение уведомлений об авторском праве, текста лицензии и условий настоящей Лицензии в отношении всех частей Программного обеспечения, производных от Telemt.
+
+Дополнительные условия или лицензии могут применяться к модификациям или дополнительному коду, добавленному распространителем, при условии, что такие условия не ограничивают и не изменяют права, предоставленные настоящей Лицензией в отношении оригинального Программного обеспечения Telemt.
+
+Ничто в настоящем разделе не ограничивает права, предоставленные настоящей Лицензией в отношении уже выпущенных версий Программного обеспечения.
+
+### Определения
+
+Для целей настоящей Лицензии:
+
+**"Программное обеспечение"** означает программное обеспечение Telemt, включая исходный код, документацию и любые сопутствующие файлы, распространяемые в соответствии с настоящей Лицензией.
+
+**"Контрибьютор"** означает любое физическое или юридическое лицо, которое предоставляет код, исправления, документацию или иные материалы в качестве вклада в Программное обеспечение, принятые мейнтейнерами для включения в Программное обеспечение.
+
+**"Вклад"** означает любое произведение, сознательно представленное для включения в Программное обеспечение.
+
+**"Модифицированная версия"** означает любую версию Программного обеспечения, которая была изменена, адаптирована, расширена или иным образом модифицирована по сравнению с оригинальным Программным обеспечением.
+
+**"Мейнтейнеры"** означает физических или юридических лиц, ответственных за официальный проект Telemt и его релизы.
+
+### 1. Атрибуция
+
+При распространении Программного обеспечения, как в виде исходного кода, так и в бинарной форме, ОБЯЗАТЕЛЬНО СОХРАНЕНИЕ:
+
+- указанного выше уведомления об авторском праве;
+- текста настоящей Лицензии;
+- всех существующих уведомлений об атрибуции.
+
+### 2. Уведомление о модификациях
+
+В случае внесения изменений в Программное обеспечение вы ОБЯЗАНЫ явно указать факт модификации Программного обеспечения и включить краткое описание внесённых изменений.
+
+Модифицированные версии НЕ ДОЛЖНЫ представляться как оригинальное Программное обеспечение Telemt.
+
+### 3. Товарные знаки и брендинг
+
+Настоящая Лицензия НЕ предоставляет право на использование наименования "Telemt", логотипа Telemt или любых товарных знаков и элементов брендинга Telemt.
+
+Распространяемые или модифицированные версии Программного обеспечения НЕ МОГУТ использовать наименование Telemt таким образом, который может создавать впечатление одобрения или официального происхождения без явного разрешения мейнтейнеров Telemt.
+
+Использование наименования "Telemt" для описания модифицированной версии Программного обеспечения допускается только при условии, что такая версия чётко обозначена как модифицированная или неофициальная.
+
+Запрещается любое распространение, способное разумно ввести пользователей в заблуждение относительно того, что программное обеспечение является официальным релизом Telemt.
+
+### 4. Прозрачность распространения бинарных файлов
+
+В случае распространения скомпилированных бинарных файлов Программного обеспечения рекомендуется (ENCOURAGED) предоставлять доступ к соответствующему исходному коду и инструкциям по сборке, если это разумно возможно.
+
+Это способствует обеспечению прозрачности и позволяет получателям проверять целостность и воспроизводимость распространяемых сборок.
+
+### 5. Патентная лицензия и условие защитного прекращения
+
+Каждый контрибьютор предоставляет вам бессрочную, всемирную, неисключительную, безвозмездную, без лицензионных отчислений, безотзывную патентную лицензию на:
+
+- изготовление,
+- поручение изготовления,
+- использование,
+- предложение к продаже,
+- продажу,
+- импорт,
+- а также иные формы передачи Программного обеспечения.
+
+Данная патентная лицензия распространяется исключительно на те патентные притязания, которые неизбежно нарушаются вкладом контрибьютора отдельно либо в сочетании его вклада с Программным обеспечением.
+
+Если вы инициируете или участвуете в любом патентном судебном разбирательстве, включая встречные иски или требования, утверждая, что Программное обеспечение или любой Вклад, включённый в Программное обеспечение, нарушает патент, то **все предоставленные вам настоящей Лицензией права немедленно прекращаются** с даты подачи такого иска.
+
+Дополнительно, если вы инициируете судебное разбирательство, утверждая, что само Программное обеспечение нарушает ваш патент или иные права интеллектуальной собственности, все права, предоставленные вам настоящей Лицензией, ПРЕКРАЩАЮТСЯ автоматически.
+
+### 6. Вклады
+
+Если вы прямо не указали иное, любой Вклад, сознательно представленный для включения в Программное обеспечение, лицензируется на условиях настоящей Лицензии.
+
+Предоставляя Вклад, вы предоставляете мейнтейнерам Telemt и всем получателям Программного обеспечения права, предусмотренные настоящей Лицензией, в отношении такого Вклада.
+
+### 7. Атрибуция при сетевом использовании
+
+Если Программное обеспечение используется для предоставления общедоступного сетевого сервиса, оператор такого сервиса ДОЛЖЕН (SHOULD) обеспечить указание атрибуции Telemt как минимум в одном из следующих мест:
+
+- документация сервиса;
+- описание сервиса;
+- раздел "О программе" или аналогичная информационная страница;
+- иные материалы, доступные пользователю и разумно связанные с сервисом.
+
+Такая атрибуция НЕ ДОЛЖНА подразумевать одобрение со стороны проекта Telemt или его мейнтейнеров.
+
+### 8. Отказ от гарантий и оговорка о делимости
+
+ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ "КАК ЕСТЬ", БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ, ЯВНЫХ ИЛИ ПОДРАЗУМЕВАЕМЫХ, ВКЛЮЧАЯ, В ЧАСТНОСТИ, ГАРАНТИИ ТОВАРНОЙ ПРИГОДНОСТИ, СООТВЕТСТВИЯ ОПРЕДЕЛЁННОЙ ЦЕЛИ И ОТСУТСТВИЯ НАРУШЕНИЙ ПРАВ.
+
+НИ ПРИ КАКИХ ОБСТОЯТЕЛЬСТВАХ АВТОРЫ ИЛИ ПРАВООБЛАДАТЕЛИ НЕ НЕСУТ ОТВЕТСТВЕННОСТИ ПО КАКИМ-ЛИБО ТРЕБОВАНИЯМ, УБЫТКАМ ИЛИ ИНОЙ ОТВЕТСТВЕННОСТИ, ВОЗНИКАЮЩИМ В РАМКАХ ДОГОВОРА, ДЕЛИКТА ИЛИ ИНЫМ ОБРАЗОМ, ИЗ, В СВЯЗИ С ИЛИ В РЕЗУЛЬТАТЕ ИСПОЛЬЗОВАНИЯ ПРОГРАММНОГО ОБЕСПЕЧЕНИЯ ИЛИ ИНЫХ ДЕЙСТВИЙ С НИМ.
+
+ЕСЛИ ЛЮБОЕ ПОЛОЖЕНИЕ НАСТОЯЩЕЙ ЛИЦЕНЗИИ ПРИЗНАЁТСЯ НЕДЕЙСТВИТЕЛЬНЫМ ИЛИ НЕПРИМЕНИМЫМ, ТАКОЕ ПОЛОЖЕНИЕ ПОДЛЕЖИТ ТОЛКОВАНИЮ МАКСИМАЛЬНО БЛИЗКО К ИСХОДНОМУ НАМЕРЕНИЮ СТОРОН, А ОСТАЛЬНЫЕ ПОЛОЖЕНИЯ СОХРАНЯЮТ ПОЛНУЮ СИЛУ И ДЕЙСТВИЕ.

docs/QUICK_START_GUIDE.ru.md

@@ -1,195 +0,0 @@
-# Telemt через Systemd
-
-## Установка
-
-Это программное обеспечение разработано для ОС на базе Debian: помимо Debian, это Ubuntu, Mint, Kali, MX и многие другие Linux
-
-**1. Скачать**
-```bash
-wget -qO- "https://github.com/telemt/telemt/releases/latest/download/telemt-$(uname -m)-linux-$(ldd --version 2>&1 | grep -iq musl && echo musl || echo gnu).tar.gz" | tar -xz
-```
-**2. Переместить в папку Bin**
-```bash
-mv telemt /bin
-```
-**3. Сделать файл исполняемым**
-```bash
-chmod +x /bin/telemt
-```
-
-## Как правильно использовать?
-
-**Эта инструкция "предполагает", что вы:**
-- Авторизовались как пользователь root или выполнил `su -` / `sudo su`
-- У вас уже есть исполняемый файл "telemt" в папке /bin. Читайте раздел **[Установка](#установка)**
-
----
-
-**0. Проверьте порт и сгенерируйте секреты**
-
-Порт, который вы выбрали для использования, должен отсутствовать в списке:
-```bash
-netstat -lnp
-```
-
-Сгенерируйте 16 bytes/32 символа в шестнадцатеричном формате с помощью OpenSSL или другим способом:
-```bash
-openssl rand -hex 16
-```
-ИЛИ
-```bash
-xxd -l 16 -p /dev/urandom
-```
-ИЛИ
-```bash
-python3 -c 'import os; print(os.urandom(16).hex())'
-```
-Полученный результат сохраняем где-нибудь. Он понадобиться вам дальше!
-
----
-
-**1. Поместите свою конфигурацию в файл /etc/telemt/telemt.toml**
-
-Создаём директорию для конфига:
-```bash
-mkdir /etc/telemt
-```
-
-Открываем nano
-```bash
-nano /etc/telemt/telemt.toml
-```
-Вставьте свою конфигурацию
-
-```toml
-# === General Settings ===
-[general]
-# ad_tag = "00000000000000000000000000000000"
-use_middle_proxy = false
-
-[general.modes]
-classic = false
-secure = false
-tls = true
-
-[server]
-port = 443
-
-[server.api]
-enabled = true
-# listen = "127.0.0.1:9091"
-# whitelist = ["127.0.0.1/32"]
-# read_only = true
-
-# === Anti-Censorship & Masking ===
-[censorship]
-tls_domain = "petrovich.ru"
-
-[access.users]
-# format: "username" = "32_hex_chars_secret"
-hello = "00000000000000000000000000000000"
-```
-
-Затем нажмите Ctrl+S -> Ctrl+X, чтобы сохранить
-
-> [!WARNING]
-> Замените значение параметра hello на значение, которое вы получили в пункте 0.  
-> Так же замените значение параметра tls_domain на другой сайт.
-> Изменение параметра tls_domain сделает нерабочими все ссылки, использующие старый домен!
-
----
-
-**2. Создайте пользователя для telemt**
-
-```bash
-useradd -d /opt/telemt -m -r -U telemt
-chown -R telemt:telemt /etc/telemt
-```
-
-**3. Создайте службу в /etc/systemd/system/telemt.service**
-
-Открываем nano
-```bash
-nano /etc/systemd/system/telemt.service
-```
-
-Вставьте этот модуль Systemd
-```bash
-[Unit]
-Description=Telemt
-After=network-online.target
-Wants=network-online.target
-
-[Service]
-Type=simple
-User=telemt
-Group=telemt
-WorkingDirectory=/opt/telemt
-ExecStart=/bin/telemt /etc/telemt/telemt.toml
-Restart=on-failure
-LimitNOFILE=65536
-AmbientCapabilities=CAP_NET_BIND_SERVICE
-CapabilityBoundingSet=CAP_NET_BIND_SERVICE
-NoNewPrivileges=true
-
-[Install]
-WantedBy=multi-user.target
-```
-Затем нажмите Ctrl+S -> Ctrl+X, чтобы сохранить
-
-перезагрузите конфигурацию systemd
-```bash
-systemctl daemon-reload
-```
-
-**4.** Для запуска введите команду `systemctl start telemt`
-
-**5.** Для получения информации о статусе введите `systemctl status telemt`
-
-**6.** Для автоматического запуска при запуске системы в введите `systemctl enable telemt`
-
-**7.** Для получения ссылки/ссылок введите 
-```bash
-curl -s http://127.0.0.1:9091/v1/users | jq
-```
-> Одной ссылкой может пользоваться сколько угодно человек.
-
-> [!WARNING]
-> Рабочую ссылку может выдать только команда из 7 пункта. Не пытайтесь делать ее самостоятельно или копировать откуда-либо если вы не уверены в том, что делаете!
-
----
-
-# Telemt через Docker Compose
-
-**1. Отредактируйте `config.toml` в корневом каталоге репозитория (как минимум: порт, пользовательские секреты, tls_domain)**  
-**2. Запустите контейнер:**
-```bash
-docker compose up -d --build
-```
-**3. Проверьте логи:**
-```bash
-docker compose logs -f telemt
-```
-**4. Остановите контейнер:**
-```bash
-docker compose down
-```
-> [!NOTE]
-> - В `docker-compose.yml` файл `./config.toml` монтируется в `/app/config.toml` (доступно только для чтения)  
-> - По умолчанию публикуются порты 443:443, а контейнер запускается со сброшенными привилегиями (добавлена только `NET_BIND_SERVICE`)  
-> - Если вам действительно нужна сеть хоста (обычно это требуется только для некоторых конфигураций IPv6), раскомментируйте `network_mode: host`
-
-**Запуск без Docker Compose**
-```bash
-docker build -t telemt:local .
-docker run --name telemt --restart unless-stopped \
-  -p 443:443 \
-  -p 9090:9090 \
-  -p 9091:9091 \
-  -e RUST_LOG=info \
-  -v "$PWD/config.toml:/app/config.toml:ro" \
-  --read-only \
-  --cap-drop ALL --cap-add NET_BIND_SERVICE \
-  --ulimit nofile=65536:65536 \
-  telemt:local
-```

docs/Quick_start/OPENBSD_QUICK_START_GUIDE.en.md

@@ -27,7 +27,8 @@ cargo build --release
 ./target/release/telemt --version
 ```
 
-For low-RAM systems, this repository already uses `lto = "thin"` in release profile.
+For low-RAM systems, note that this repository currently uses `lto = "fat"` in release profile.  
+On constrained builders, a local override to `lto = "thin"` may be more practical.
 
 ## 3. Install binary and config
 

docs/Quick_start/QUICK_START_GUIDE.en.md

@@ -1,3 +1,46 @@
+# Installation Options 
+There are three options for installing Telemt:
+ - [Automated installation using a script](#very-quick-start).
+ - [Manual installation of Telemt as a service](#telemt-via-systemd).
+ - [Installation using Docker Compose](#telemt-via-docker-compose).
+
+# Very quick start
+
+### One-command installation / update on re-run
+```bash
+curl -fsSL https://raw.githubusercontent.com/telemt/telemt/main/install.sh | sh
+```
+
+After starting, the script will prompt for:
+ - Your language (1 - English, 2 - Russian);
+ - Your TLS domain (press Enter for petrovich.ru).
+
+The script checks if the port (default **443**) is free. If the port is already in use, installation will fail. You need to free up the port or use the **-p** flag with a different port to retry the installation.
+
+To modify the script’s startup parameters, you can use the following flags:
+ - **-d, --domain** - TLS domain;
+ - **-p, --port** - server port (1–65535);
+ - **-s, --secret** - 32 hex secret;
+ - **-a, --ad-tag** - ad_tag;
+ - **-l, --lan**g - language (1/en or 2/ru);
+
+Providing all options skips interactive prompts.
+
+After completion, the script will provide a link for client connections:
+```bash
+tg://proxy?server=IP&port=PORT&secret=SECRET
+```
+
+### Installing a specific version
+```bash
+curl -fsSL https://raw.githubusercontent.com/telemt/telemt/main/install.sh | sh -s -- 3.3.39
+```
+
+### Uninstall with full cleanup
+```bash
+curl -fsSL https://raw.githubusercontent.com/telemt/telemt/main/install.sh | sh -s -- purge
+```
+
 # Telemt via Systemd
 
 ## Installation
@@ -62,28 +105,60 @@ nano /etc/telemt/telemt.toml
 Insert your configuration:
 
 ```toml
+### Telemt Based Config.toml
+# We believe that these settings are sufficient for most scenarios 
+# where cutting-egde methods and parameters or special solutions are not needed
+
 # === General Settings ===
 [general]
+use_middle_proxy = true
+# Global ad_tag fallback when user has no per-user tag in [access.user_ad_tags]
 # ad_tag = "00000000000000000000000000000000"
-use_middle_proxy = false
+# Per-user ad_tag in [access.user_ad_tags] (32 hex from @MTProxybot)
+
+# === Log Level ===
+# Log level: debug | verbose | normal | silent
+# Can be overridden with --silent or --log-level CLI flags
+# RUST_LOG env var takes absolute priority over all of these
+log_level = "normal"
 
 [general.modes]
 classic = false
 secure = false
 tls = true
 
+[general.links]
+show = "*"
+# show = ["alice", "bob"] # Only show links for alice and bob
+# show = "*"              # Show links for all users
+# public_host = "proxy.example.com"  # Host (IP or domain) for tg:// links
+# public_port = 443                  # Port for tg:// links (default: server.port)
+
+# === Server Binding ===
 [server]
 port = 443
+# proxy_protocol = false            # Enable if behind HAProxy/nginx with PROXY protocol
+# metrics_port = 9090
+# metrics_listen = "127.0.0.1:9090" # Listen address for metrics (overrides metrics_port)
+# metrics_whitelist = ["127.0.0.1/32", "::1/128"]
 
 [server.api]
 enabled = true
-# listen = "127.0.0.1:9091"
-# whitelist = ["127.0.0.1/32"]
-# read_only = true
+listen = "127.0.0.1:9091"
+whitelist = ["127.0.0.1/32", "::1/128"]
+minimal_runtime_enabled = false
+minimal_runtime_cache_ttl_ms = 1000
+
+# Listen on multiple interfaces/IPs - IPv4
+[[server.listeners]]
+ip = "0.0.0.0"
 
 # === Anti-Censorship & Masking ===
 [censorship]
-tls_domain = "petrovich.ru"
+tls_domain = "petrovich.ru"  # Fake-TLS / SNI masking domain used in generated ee-links
+mask = true
+tls_emulation = true         # Fetch real cert lengths and emulate TLS records
+tls_front_dir = "tlsfront"   # Cache directory for TLS emulation
 
 [access.users]
 # format: "username" = "32_hex_chars_secret"
@@ -93,9 +168,9 @@ hello = "00000000000000000000000000000000"
 then Ctrl+S -> Ctrl+X to save
 
 > [!WARNING]
-> Replace the value of the hello parameter with the value you obtained in step 0.  
-> Additionally, change the value of the tls_domain parameter to a different website.
-> Changing the tls_domain parameter will break all links that use the old domain!
+> Replace the value of the `hello` parameter with the value you obtained in step 0.  
+> Additionally, change the value of the `tls_domain` parameter to a different website.
+> Changing the `tls_domain` parameter will break all links that use the old domain!
 
 ---
 
@@ -128,8 +203,8 @@ WorkingDirectory=/opt/telemt
 ExecStart=/bin/telemt /etc/telemt/telemt.toml
 Restart=on-failure
 LimitNOFILE=65536
-AmbientCapabilities=CAP_NET_BIND_SERVICE
-CapabilityBoundingSet=CAP_NET_BIND_SERVICE
+AmbientCapabilities=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
+CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
 NoNewPrivileges=true
 
 [Install]
@@ -150,7 +225,7 @@ systemctl daemon-reload
 
 **7.** To get the link(s), enter:
 ```bash
-curl -s http://127.0.0.1:9091/v1/users | jq
+curl -s http://127.0.0.1:9091/v1/users | jq -r '.data[] | "[\(.username)]", (.links.classic[]? | "classic: \(.)"), (.links.secure[]? | "secure: \(.)"), (.links.tls[]? | "tls: \(.)"), ""'
 ```
 
 > Any number of people can use one link.

docs/Quick_start/QUICK_START_GUIDE.ru.md

@@ -0,0 +1,269 @@
+# Варианты установки
+Имеется три варианта установки Telemt:
+ - [Автоматизированная установка с помощью скрипта](#очень-быстрый-старт).
+ - [Ручная установка Telemt в качестве службы](#telemt-через-systemd-вручную).
+ - [Установка через Docker Compose](#telemt-через-docker-compose).
+
+# Очень быстрый старт
+
+### Установка одной командой / обновление при повторном запуске
+```bash
+curl -fsSL https://raw.githubusercontent.com/telemt/telemt/main/install.sh | sh
+```
+После запуска скрипт запросит:
+ - ваш язык (1 - English, 2 - Русский);
+ - ваш TLS-домен (нажмите Enter для petrovich.ru).
+
+Во время установки скрипт проверяет, свободен ли порт (по умолчанию **443**). Если порт занят другим процессом - установка завершится с ошибкой. Для повторной установки необходимо освободить порт или указать другой через флаг **-p**.
+
+Для изменения параметров запуска скрипта можно использовать следующие флаги:
+ - **-d, --domain** - TLS-домен;
+ - **-p, --port** - порт (1–65535);
+ - **-s, --secret** - секрет (32 hex символа);
+ - **-a, --ad-tag** - ad_tag;
+ - **-l, --lang** - язык (1/en или 2/ru).
+
+Если заданы флаги для языка и домена, интерактивных вопросов не будет.
+
+После завершения установки скрипт выдаст ссылку для подключения клиентов:
+```bash
+tg://proxy?server=IP&port=PORT&secret=SECRET
+```
+
+### Установка нужной версии
+```bash
+curl -fsSL https://raw.githubusercontent.com/telemt/telemt/main/install.sh | sh -s -- 3.3.39
+```
+
+### Удаление с полной очисткой
+```bash
+curl -fsSL https://raw.githubusercontent.com/telemt/telemt/main/install.sh | sh -s -- purge
+```
+
+# Telemt через Systemd вручную
+
+## Установка
+
+Это программное обеспечение разработано для ОС на базе Debian: помимо Debian, это Ubuntu, Mint, Kali, MX и многие другие Linux
+
+**1. Скачать**
+```bash
+wget -qO- "https://github.com/telemt/telemt/releases/latest/download/telemt-$(uname -m)-linux-$(ldd --version 2>&1 | grep -iq musl && echo musl || echo gnu).tar.gz" | tar -xz
+```
+**2. Переместить в папку Bin**
+```bash
+mv telemt /bin
+```
+**3. Сделать файл исполняемым**
+```bash
+chmod +x /bin/telemt
+```
+
+## Как правильно использовать?
+
+**Эта инструкция "предполагает", что вы:**
+- Авторизовались как пользователь root или выполнил `su -` / `sudo su`
+- У вас уже есть исполняемый файл "telemt" в папке /bin. Читайте раздел **[Установка](#установка)**
+
+---
+
+**0. Проверьте порт и сгенерируйте секреты**
+
+Порт, который вы выбрали для использования, должен отсутствовать в списке:
+```bash
+netstat -lnp
+```
+
+Сгенерируйте 16 bytes/32 символа в шестнадцатеричном формате с помощью OpenSSL или другим способом:
+```bash
+openssl rand -hex 16
+```
+ИЛИ
+```bash
+xxd -l 16 -p /dev/urandom
+```
+ИЛИ
+```bash
+python3 -c 'import os; print(os.urandom(16).hex())'
+```
+Полученный результат сохраняем где-нибудь. Он понадобиться вам дальше!
+
+---
+
+**1. Поместите свою конфигурацию в файл /etc/telemt/telemt.toml**
+
+Создаём директорию для конфига:
+```bash
+mkdir /etc/telemt
+```
+
+Открываем nano
+```bash
+nano /etc/telemt/telemt.toml
+```
+Вставьте свою конфигурацию
+
+```toml
+### Конфигурационный файл на основе Telemt
+# Мы полагаем, что этих настроек достаточно для большинства сценариев, 
+# где не требуются передовые методы, параметры или специальные решения
+
+# === Общие настройки ===
+[general]
+use_middle_proxy = true
+# Глобальный ad_tag, если у пользователя нет индивидуального тега в [access.user_ad_tags]
+# ad_tag = "00000000000000000000000000000000"
+# Индивидуальный ad_tag в [access.user_ad_tags] (32 шестнадцатеричных символа от @MTProxybot)
+
+# === Уровень логирования ===
+# Уровень логирования: debug | verbose | normal | silent
+# Можно переопределить с помощью флагов командной строки --silent или --log-level
+# Переменная окружения RUST_LOG имеет абсолютный приоритет над всеми этими настройками
+log_level = "normal"
+
+[general.modes]
+classic = false
+secure = false
+tls = true
+
+[general.links]
+show = "*"
+# show = ["alice", "bob"] # Показывать ссылки только для alice и bob
+# show = "*"              # Показывать ссылки для всех пользователей
+# public_host = "proxy.example.com"  # Хост (IP-адрес или домен) для ссылок tg://
+# public_port = 443                  # Порт для ссылок tg:// (по умолчанию: server.port)
+
+# === Привязка сервера ===
+[server]
+port = 443
+# proxy_protocol = false           # Включите, если сервер находится за HAProxy/nginx с протоколом PROXY
+# metrics_port = 9090
+# metrics_listen = "127.0.0.1:9090"  # Адрес прослушивания для метрик (переопределяет metrics_port)
+# metrics_whitelist = ["127.0.0.1/32", "::1/128"]
+
+[server.api]
+enabled = true
+listen = "127.0.0.1:9091"
+whitelist = ["127.0.0.1/32", "::1/128"]
+minimal_runtime_enabled = false
+minimal_runtime_cache_ttl_ms = 1000
+
+# Прослушивание на нескольких интерфейсах/IP-адресах - IPv4
+[[server.listeners]]
+ip = "0.0.0.0"
+
+# === Обход блокировок и маскировка ===
+[censorship]
+tls_domain = "petrovich.ru"  # Домен Fake-TLS / SNI, который будет использоваться в сгенерированных ee-ссылках
+mask = true
+tls_emulation = true         # Получить реальную длину сертификата и эмулировать запись TLS
+tls_front_dir = "tlsfront"   # Директория кэша для эмуляции TLS
+
+[access.users]
+# формат: "имя_пользователя" = "секрет_из_32_шестнадцатеричных_символов"
+hello = "00000000000000000000000000000000"
+```
+
+Затем нажмите Ctrl+O -> Ctrl+X, чтобы сохранить
+
+> [!WARNING]
+> Замените значение параметра `hello` на значение, которое вы получили в пункте 0.  
+> Так же замените значение параметра `tls_domain` на другой сайт.
+> Изменение параметра `tls_domain` сделает нерабочими все ссылки, использующие старый домен!
+
+---
+
+**2. Создайте пользователя для telemt**
+
+```bash
+useradd -d /opt/telemt -m -r -U telemt
+chown -R telemt:telemt /etc/telemt
+```
+
+**3. Создайте службу в /etc/systemd/system/telemt.service**
+
+Открываем nano
+```bash
+nano /etc/systemd/system/telemt.service
+```
+
+Вставьте этот модуль Systemd
+```bash
+[Unit]
+Description=Telemt
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=telemt
+Group=telemt
+WorkingDirectory=/opt/telemt
+ExecStart=/bin/telemt /etc/telemt/telemt.toml
+Restart=on-failure
+LimitNOFILE=65536
+AmbientCapabilities=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
+CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
+NoNewPrivileges=true
+
+[Install]
+WantedBy=multi-user.target
+```
+Затем нажмите Ctrl+S -> Ctrl+X, чтобы сохранить
+
+перезагрузите конфигурацию systemd
+```bash
+systemctl daemon-reload
+```
+
+**4.** Для запуска введите команду `systemctl start telemt`
+
+**5.** Для получения информации о статусе введите `systemctl status telemt`
+
+**6.** Для автоматического запуска при запуске системы в введите `systemctl enable telemt`
+
+**7.** Для получения ссылки/ссылок введите 
+```bash
+curl -s http://127.0.0.1:9091/v1/users | jq -r '.data[] | "[\(.username)]", (.links.classic[]? | "classic: \(.)"), (.links.secure[]? | "secure: \(.)"), (.links.tls[]? | "tls: \(.)"), ""'
+```
+> Одной ссылкой может пользоваться сколько угодно человек.
+
+> [!WARNING]
+> Рабочую ссылку может выдать только команда из 7 пункта. Не пытайтесь делать ее самостоятельно или копировать откуда-либо если вы не уверены в том, что делаете!
+
+---
+
+# Telemt через Docker Compose
+
+**1. Отредактируйте `config.toml` в корневом каталоге репозитория (как минимум: порт, пользовательские секреты, tls_domain)**  
+**2. Запустите контейнер:**
+```bash
+docker compose up -d --build
+```
+**3. Проверьте логи:**
+```bash
+docker compose logs -f telemt
+```
+**4. Остановите контейнер:**
+```bash
+docker compose down
+```
+> [!NOTE]
+> - В `docker-compose.yml` файл `./config.toml` монтируется в `/app/config.toml` (доступно только для чтения)  
+> - По умолчанию публикуются порты 443:443, а контейнер запускается со сброшенными привилегиями (добавлена только `NET_BIND_SERVICE`)  
+> - Если вам действительно нужна сеть хоста (обычно это требуется только для некоторых конфигураций IPv6), раскомментируйте `network_mode: host`
+
+**Запуск без Docker Compose**
+```bash
+docker build -t telemt:local .
+docker run --name telemt --restart unless-stopped \
+  -p 443:443 \
+  -p 9090:9090 \
+  -p 9091:9091 \
+  -e RUST_LOG=info \
+  -v "$PWD/config.toml:/app/config.toml:ro" \
+  --read-only \
+  --cap-drop ALL --cap-add NET_BIND_SERVICE \
+  --ulimit nofile=65536:65536 \
+  telemt:local
+```

docs/Setup_examples/VPS_DOUBLE_HOP.en.md

@@ -163,7 +163,7 @@ PING 10.10.10.1 (10.10.10.1) 56(84) bytes of data.
 ---
 
 ## Step 2. Installing telemt on Server B (conditionally Netherlands)
-Installation and configuration are described [here](https://github.com/telemt/telemt/blob/main/docs/QUICK_START_GUIDE.ru.md) or [here](https://gitlab.com/An0nX/telemt-docker#-quick-start-docker-compose).\
+Installation and configuration are described [here](https://github.com/telemt/telemt/blob/main/docs/Quick_start/QUICK_START_GUIDE.en.md) or [here](https://gitlab.com/An0nX/telemt-docker#-quick-start-docker-compose).\
 It is assumed that telemt expects connections on port `443\tcp`.
 
 In the telemt config, you must enable the `Proxy` protocol and restrict connections to it only through the tunnel.

docs/Setup_examples/VPS_DOUBLE_HOP.ru.md

@@ -166,7 +166,7 @@ PING 10.10.10.1 (10.10.10.1) 56(84) bytes of data.
 
 ## Шаг 2. Установка telemt на Сервере B (_условно Нидерланды_)
 
-Установка и настройка описаны [здесь](https://github.com/telemt/telemt/blob/main/docs/QUICK_START_GUIDE.ru.md) или [здесь](https://gitlab.com/An0nX/telemt-docker#-quick-start-docker-compose).\
+Установка и настройка описаны [здесь](https://github.com/telemt/telemt/blob/main/docs/Quick_start/QUICK_START_GUIDE.ru.md) или [здесь](https://gitlab.com/An0nX/telemt-docker#-quick-start-docker-compose).\
 Подразумевается что telemt ожидает подключения на порту `443\tcp`.
 
 В конфиге telemt необходимо включить протокол `Proxy` и ограничить подключения к нему только через туннель.

docs/Setup_examples/XRAY_DOUBLE_HOP.en.md

@@ -0,0 +1,273 @@
+<img src="https://gist.githubusercontent.com/avbor/1f8a128e628f47249aae6e058a57610b/raw/19013276c035e91058e0a9799ab145f8e70e3ff5/scheme.svg">
+
+## Concept
+- **Server A** (_e.g., RU_):\
+  Entry point, accepts Telegram proxy user traffic via **Xray** (port `443\tcp`)\
+  and sends it through the tunnel to Server **B**.\
+  Public port for Telegram clients — `443\tcp`
+- **Server B** (_e.g., NL_):\
+  Exit point, runs the **Xray server** (to terminate the tunnel entry point) and **telemt**.\
+  The server must have unrestricted access to Telegram Data Centers.\
+  Public port for VLESS/REALITY (incoming) — `443\tcp`\
+  Internal telemt port (where decrypted Xray traffic ends up) — `8443\tcp`
+
+The tunnel works over the `VLESS-XTLS-Reality` (or `VLESS/xhttp/reality`) protocol. The original client IP address is preserved thanks to the PROXYv2 protocol, which Xray on Server A dynamically injects via a local loopback before wrapping the traffic into Reality, transparently delivering the real IPs to telemt on Server B.
+
+---
+
+## Step 1. Setup Xray Tunnel (A <-> B)
+
+You must install **Xray-core** (version 1.8.4 or newer recommended) on both servers.
+Official installation script (run on both servers):
+```bash
+bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ install
+```
+
+### Key and Parameter Generation (Run Once)
+For configuration, you need a unique UUID and Xray Reality keys. Run on any server with Xray installed:
+1. **Client UUID:**
+```bash
+xray uuid
+# Save the output (e.g.: 12345678-abcd-1234-abcd-1234567890ab) — this is <XRAY_UUID>
+```
+2. **X25519 Keypair (Private & Public) for Reality:**
+```bash
+xray x25519
+# Save the Private key (<SERVER_B_PRIVATE_KEY>) and Public key (<SERVER_B_PUBLIC_KEY>)
+```
+3. **Short ID (Reality identifier):**
+```bash
+openssl rand -hex 8
+# Save the output (e.g.: abc123def456) — this is <SHORT_ID>
+```
+4. **Random Path (for xhttp):**
+```bash
+openssl rand -hex 16
+# Save the output (e.g., 0123456789abcdef0123456789abcdef) to replace <YOUR_RANDOM_PATH> in configs
+```
+
+---
+
+### Configuration for Server B (_EU_):
+
+Create or edit the file `/usr/local/etc/xray/config.json`.
+This Xray instance will listen on the public `443` port and proxy valid Reality traffic, while routing "disguised" traffic (e.g., direct web browser scans) to `yahoo.com`.
+
+```bash
+nano /usr/local/etc/xray/config.json
+```
+
+File content:
+```json
+{
+  "log": {
+    "loglevel": "error",
+    "access": "none"
+  },
+  "inbounds": [
+    {
+      "tag": "vless-in",
+      "port": 443,
+      "protocol": "vless",
+      "settings": {
+        "clients": [
+          {
+            "id": "<XRAY_UUID>"
+          }
+        ],
+        "decryption": "none"
+      },
+      "streamSettings": {
+        "network": "xhttp",
+        "security": "reality",
+        "realitySettings": {
+          "dest": "yahoo.com:443",
+          "serverNames": [
+            "yahoo.com"
+          ],
+          "privateKey": "<SERVER_B_PRIVATE_KEY>",
+          "shortIds": [
+            "<SHORT_ID>"
+          ]
+        },
+        "xhttpSettings": {
+          "path": "/<YOUR_RANDOM_PATH>",
+          "mode": "auto"
+        }
+      }
+    }
+  ],
+  "outbounds": [
+    {
+      "tag": "tunnel-to-telemt",
+      "protocol": "freedom",
+      "settings": {
+        "destination": "127.0.0.1:8443"
+      }
+    }
+  ],
+  "routing": {
+    "domainStrategy": "AsIs",
+    "rules": [
+      {
+        "type": "field",
+        "inboundTag": [
+          "vless-in"
+        ],
+        "outboundTag": "tunnel-to-telemt"
+      }
+    ]
+  }
+}
+```
+
+Open the firewall port (if enabled):
+```bash
+sudo ufw allow 443/tcp
+```
+Restart and setup Xray to run at boot:
+```bash
+sudo systemctl restart xray
+sudo systemctl enable xray
+```
+
+---
+
+### Configuration for Server A (_RU_):
+
+Similarly, edit `/usr/local/etc/xray/config.json`.
+Here Xray acts as the public entry point: it listens on `443\tcp`, uses a local loopback (via internal port `10444`) to prepend the `PROXYv2` header, and encapsulates the payload via Reality to Server B, instructing Server B to deliver it to its *local* `127.0.0.1:8443` port (where telemt will listen).
+
+```bash
+nano /usr/local/etc/xray/config.json
+```
+
+File content:
+```json
+{
+  "log": {
+    "loglevel": "error",
+    "access": "none"
+  },
+  "inbounds": [
+    {
+      "tag": "public-in",
+      "port": 443,
+      "listen": "0.0.0.0",
+      "protocol": "dokodemo-door",
+      "settings": {
+        "address": "127.0.0.1",
+        "port": 10444,
+        "network": "tcp"
+      }
+    },
+    {
+      "tag": "tunnel-in",
+      "port": 10444,
+      "listen": "127.0.0.1",
+      "protocol": "dokodemo-door",
+      "settings": {
+        "address": "127.0.0.1",
+        "port": 8443,
+        "network": "tcp"
+      }
+    }
+  ],
+  "outbounds": [
+    {
+      "tag": "local-injector",
+      "protocol": "freedom",
+      "settings": {
+        "proxyProtocol": 2
+      }
+    },
+    {
+      "tag": "vless-out",
+      "protocol": "vless",
+      "settings": {
+        "vnext": [
+          {
+            "address": "<PUBLIC_IP_SERVER_B>",
+            "port": 443,
+            "users": [
+              {
+                "id": "<XRAY_UUID>",
+                "encryption": "none"
+              }
+            ]
+          }
+        ]
+      },
+      "streamSettings": {
+        "network": "xhttp",
+        "security": "reality",
+        "realitySettings": {
+          "serverName": "yahoo.com",
+          "publicKey": "<SERVER_B_PUBLIC_KEY>",
+          "shortId": "<SHORT_ID>",
+          "spiderX": "/",
+          "fingerprint": "chrome"
+        },
+        "xhttpSettings": {
+          "path": "/<YOUR_RANDOM_PATH>"
+        }
+      }
+    }
+  ],
+  "routing": {
+    "domainStrategy": "AsIs",
+    "rules": [
+      {
+        "type": "field",
+        "inboundTag": ["public-in"],
+        "outboundTag": "local-injector"
+      },
+      {
+        "type": "field",
+        "inboundTag": ["tunnel-in"],
+        "outboundTag": "vless-out"
+      }
+    ]
+  }
+}
+```
+*Replace `<PUBLIC_IP_SERVER_B>` with the public IP address of Server B.*
+
+Open the firewall port for clients (if enabled):
+```bash
+sudo ufw allow 443/tcp
+```
+
+Restart and setup Xray to run at boot:
+```bash
+sudo systemctl restart xray
+sudo systemctl enable xray
+```
+
+---
+
+## Step 2. Install telemt on Server B (_EU_)
+
+telemt installation is heavily covered in the [Quick Start Guide](../Quick_start/QUICK_START_GUIDE.en.md).
+By contrast to standard setups, telemt must listen strictly _locally_ (since Xray occupies the public `443` interface) and must expect `PROXYv2` packets.
+
+Edit the configuration file (`config.toml`) on Server B accordingly:
+
+```toml
+[server]
+port = 8443
+listen_addr_ipv4 = "127.0.0.1"
+proxy_protocol = true
+
+[general.links]
+show = "*"
+public_host = "<FQDN_OR_IP_SERVER_A>"
+public_port = 443
+```
+
+- Address `127.0.0.1` and `port = 8443` instructs the core proxy router to process connections unpacked locally via Xray-server.
+- `proxy_protocol = true` commands telemt to parse the injected PROXY header (from Server A's Xray local loopback) and log genuine end-user IPs.
+- Under `public_host`, place Server A's public IP address or FQDN to ensure working links are generated for Telegram users.
+
+Restart `telemt`. Your server is now robust against DPI scanners, passing traffic optimally.
+

docs/Setup_examples/XRAY_DOUBLE_HOP.ru.md

@@ -0,0 +1,272 @@
+<img src="https://gist.githubusercontent.com/avbor/1f8a128e628f47249aae6e058a57610b/raw/19013276c035e91058e0a9799ab145f8e70e3ff5/scheme.svg">
+
+## Концепция
+- **Сервер A** (_РФ_):\
+  Точка входа, принимает трафик пользователей Telegram-прокси напрямую через **Xray** (порт `443\tcp`)\
+  и отправляет его в туннель на Сервер **B**.\
+  Порт для клиентов Telegram — `443\tcp`
+- **Сервер B** (_условно Нидерланды_):\
+  Точка выхода, на нем работает **Xray-сервер** (принимает подключения точки входа) и **telemt**.\
+  На сервере должен быть неограниченный доступ до серверов Telegram.\
+  Порт для VLESS/REALITY (вход) — `443\tcp`\
+  Внутренний порт telemt (куда пробрасывается трафик) — `8443\tcp`
+
+Туннель работает по протоколу VLESS-XTLS-Reality (или VLESS/xhttp/reality). Оригинальный IP-адрес клиента сохраняется благодаря протоколу PROXYv2, который Xray на Сервере А добавляет через локальный loopback перед упаковкой в туннель, благодаря чему прозрачно доходит до telemt.
+
+---
+
+## Шаг 1. Настройка туннеля Xray (A <-> B)
+
+На обоих серверах необходимо установить **Xray-core** (рекомендуется версия 1.8.4 или новее).
+Официальный скрипт установки (выполнить на обоих серверах):
+```bash
+bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ install
+```
+
+### Генерация ключей и параметров (выполнить один раз)
+Для конфигурации потребуются уникальные ID и ключи Xray Reality. Выполните на любом сервере с установленным Xray:
+1. **UUID клиента:**
+```bash
+xray uuid
+# Сохраните вывод (например: 12345678-abcd-1234-abcd-1234567890ab) — это <XRAY_UUID>
+```
+2. **Пара ключей X25519 (Private & Public) для Reality:**
+```bash
+xray x25519
+# Сохраните Private key (<SERVER_B_PRIVATE_KEY>) и Public key (<SERVER_B_PUBLIC_KEY>)
+```
+3. **Short ID (идентификатор Reality):**
+```bash
+openssl rand -hex 8
+# Сохраните вывод (например: abc123def456) — это <SHORT_ID>
+```
+4. **Random Path (путь для xhttp):**
+```bash
+openssl rand -hex 16
+# Сохраните вывод (например, 0123456789abcdef0123456789abcdef), чтобы заменить <YOUR_RANDOM_PATH> в конфигах
+```
+
+---
+
+### Конфигурация Сервера B (_Нидерланды_):
+
+Создаем или редактируем файл `/usr/local/etc/xray/config.json`.
+Этот Xray-сервер будет слушать порт `443` и прозрачно пропускать валидный Reality трафик дальше, а "замаскированный" трафик (например, если кто-то стучится в лоб веб-браузером) пойдет на `yahoo.com`.
+
+```bash
+nano /usr/local/etc/xray/config.json
+```
+
+Содержимое файла:
+```json
+{
+  "log": {
+    "loglevel": "error",
+    "access": "none"
+  },
+  "inbounds": [
+    {
+      "tag": "vless-in",
+      "port": 443,
+      "protocol": "vless",
+      "settings": {
+        "clients": [
+          {
+            "id": "<XRAY_UUID>"
+          }
+        ],
+        "decryption": "none"
+      },
+      "streamSettings": {
+        "network": "xhttp",
+        "security": "reality",
+        "realitySettings": {
+          "dest": "yahoo.com:443",
+          "serverNames": [
+            "yahoo.com"
+          ],
+          "privateKey": "<SERVER_B_PRIVATE_KEY>",
+          "shortIds": [
+            "<SHORT_ID>"
+          ]
+        },
+        "xhttpSettings": {
+          "path": "/<YOUR_RANDOM_PATH>",
+          "mode": "auto"
+        }
+      }
+    }
+  ],
+  "outbounds": [
+    {
+      "tag": "tunnel-to-telemt",
+      "protocol": "freedom",
+      "settings": {
+        "destination": "127.0.0.1:8443"
+      }
+    }
+  ],
+  "routing": {
+    "domainStrategy": "AsIs",
+    "rules": [
+      {
+        "type": "field",
+        "inboundTag": [
+          "vless-in"
+        ],
+        "outboundTag": "tunnel-to-telemt"
+      }
+    ]
+  }
+}
+```
+
+Открываем порт на фаерволе (если включен):
+```bash
+sudo ufw allow 443/tcp
+```
+Перезапускаем Xray:
+```bash
+sudo systemctl restart xray
+sudo systemctl enable xray
+```
+
+---
+
+### Конфигурация Сервера A (_РФ_):
+
+Аналогично, редактируем `/usr/local/etc/xray/config.json`.
+Здесь Xray выступает публичной точкой: он принимает трафик на внешний порт `443\tcp`, пропускает через локальный loopback (порт `10444`) для добавления PROXYv2-заголовка, и упаковывает в Reality до Сервера B, прося тот доставить данные на *свой локальный* порт `127.0.0.1:8443` (именно там будет слушать telemt).
+
+```bash
+nano /usr/local/etc/xray/config.json
+```
+
+Содержимое файла:
+```json
+{
+  "log": {
+    "loglevel": "error",
+    "access": "none"
+  },
+  "inbounds": [
+    {
+      "tag": "public-in",
+      "port": 443,
+      "listen": "0.0.0.0",
+      "protocol": "dokodemo-door",
+      "settings": {
+        "address": "127.0.0.1",
+        "port": 10444,
+        "network": "tcp"
+      }
+    },
+    {
+      "tag": "tunnel-in",
+      "port": 10444,
+      "listen": "127.0.0.1",
+      "protocol": "dokodemo-door",
+      "settings": {
+        "address": "127.0.0.1",
+        "port": 8443,
+        "network": "tcp"
+      }
+    }
+  ],
+  "outbounds": [
+    {
+      "tag": "local-injector",
+      "protocol": "freedom",
+      "settings": {
+        "proxyProtocol": 2
+      }
+    },
+    {
+      "tag": "vless-out",
+      "protocol": "vless",
+      "settings": {
+        "vnext": [
+          {
+            "address": "<PUBLIC_IP_SERVER_B>",
+            "port": 443,
+            "users": [
+              {
+                "id": "<XRAY_UUID>",
+                "encryption": "none"
+              }
+            ]
+          }
+        ]
+      },
+      "streamSettings": {
+        "network": "xhttp",
+        "security": "reality",
+        "realitySettings": {
+          "serverName": "yahoo.com",
+          "publicKey": "<SERVER_B_PUBLIC_KEY>",
+          "shortId": "<SHORT_ID>",
+          "spiderX": "/",
+          "fingerprint": "chrome"
+        },
+        "xhttpSettings": {
+          "path": "/<YOUR_RANDOM_PATH>"
+        }
+      }
+    }
+  ],
+  "routing": {
+    "domainStrategy": "AsIs",
+    "rules": [
+      {
+        "type": "field",
+        "inboundTag": ["public-in"],
+        "outboundTag": "local-injector"
+      },
+      {
+        "type": "field",
+        "inboundTag": ["tunnel-in"],
+        "outboundTag": "vless-out"
+      }
+    ]
+  }
+}
+```
+*Замените `<PUBLIC_IP_SERVER_B>` на внешний IP-адрес Сервера B.*
+
+Открываем порт на фаерволе для клиентов:
+```bash
+sudo ufw allow 443/tcp
+```
+
+Перезапускаем Xray:
+```bash
+sudo systemctl restart xray
+sudo systemctl enable xray
+```
+
+---
+
+## Шаг 2. Установка и настройка telemt на Сервере B (_Нидерланды_)
+
+Установка telemt описана [в основной инструкции](../Quick_start/QUICK_START_GUIDE.ru.md).
+Отличие в том, что telemt должен слушать *внутренний* порт (так как 443 занят Xray-сервером), а также ожидать `PROXY` протокол из Xray туннеля.
+
+В конфиге `config.toml` прокси (на Сервере B) укажите:
+```toml
+[server]
+port = 8443
+listen_addr_ipv4 = "127.0.0.1"
+proxy_protocol = true
+
+[general.links]
+show = "*"
+public_host = "<FQDN_OR_IP_SERVER_A>"
+public_port = 443
+```
+
+- `port = 8443` и `listen_addr_ipv4 = "127.0.0.1"` означают, что telemt принимает подключения только изнутри (приходящие от локального Xray-процесса).
+- `proxy_protocol = true` заставляет telemt парсить PROXYv2-заголовок (который добавил Xray на Сервере A через loopback), восстанавливая IP-адрес конечного пользователя (РФ).
+- В `public_host` укажите публичный IP-адрес или домен Сервера A, чтобы ссылки на подключение генерировались корректно.
+
+Перезапустите `telemt`, и клиенты смогут подключаться по выданным ссылкам.
+

docs/assets/telegram_button.svg

@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?><!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"><svg width="100%" height="100%" viewBox="0 0 150 30" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;"><path d="M150,15c0,8.279 -6.721,15 -15,15l-120,0c-8.279,0 -15,-6.721 -15,-15c0,-8.279 6.721,-15 15,-15l120,0c8.279,0 15,6.721 15,15Z" style="fill:#24a1ed;"/><g transform="matrix(20.833333,0,0,20.833333,111.464184,22.329305)"></g><text x="39.666px" y="22.329px" style="font-family:'ArialMT', 'Arial', sans-serif;font-size:20.833px;fill:#fff;">Join us!</text></svg>

install.sh

@@ -8,31 +8,263 @@ CONFIG_DIR="${CONFIG_DIR:-/etc/telemt}"
 CONFIG_FILE="${CONFIG_FILE:-${CONFIG_DIR}/telemt.toml}"
 WORK_DIR="${WORK_DIR:-/opt/telemt}"
 TLS_DOMAIN="${TLS_DOMAIN:-petrovich.ru}"
+SERVER_PORT="${SERVER_PORT:-443}"
+USER_SECRET=""
+AD_TAG=""
 SERVICE_NAME="telemt"
 TEMP_DIR=""
 SUDO=""
 CONFIG_PARENT_DIR=""
 SERVICE_START_FAILED=0
 
+PORT_PROVIDED=0
+SECRET_PROVIDED=0
+AD_TAG_PROVIDED=0
+DOMAIN_PROVIDED=0
+LANG_PROVIDED=0
+
 ACTION="install"
 TARGET_VERSION="${VERSION:-latest}"
+LANG_CHOICE="en"
+
+PATH="${PATH}:/usr/sbin:/sbin"
+
+set_language() {
+    case "$1" in
+        ru)
+            L_ERR_DOMAIN_REQ="требует аргумент (домен)."
+            L_ERR_PORT_REQ="требует аргумент (порт)."
+            L_ERR_PORT_NUM="Порт должен быть числом."
+            L_ERR_PORT_RANGE="Порт должен быть от 1 до 65535."
+            L_ERR_SECRET_REQ="требует аргумент (секрет)."
+            L_ERR_SECRET_HEX="Секрет должен содержать только HEX символы."
+            L_ERR_SECRET_LEN="Секрет должен состоять ровно из 32 символов."
+            L_ERR_ADTAG_REQ="требует аргумент (ad_tag)."
+            L_ERR_UNKNOWN_OPT="Неизвестная опция:"
+            L_WARN_EXTRA_ARG="Игнорируется лишний аргумент:"
+            L_ERR_REQ_ARG="требует аргумент (1, 2, en или ru)."
+            L_ERR_EMPTY_VAR="не может быть пустым."
+            L_ERR_INV_VER="Недопустимые символы в версии."
+            L_ERR_INV_BIN="Недопустимые символы в BIN_NAME."
+            L_ERR_ROOT="Для работы скрипта требуются права root или sudo."
+            L_ERR_SUDO_TTY="sudo требует пароль, но терминал (TTY) не обнаружен."
+            L_ERR_DIR_CHECK="Ошибка: конфиг является директорией."
+            L_ERR_CMD_NOT_FOUND="Необходимая команда не найдена:"
+            L_ERR_NO_DL_TOOL="Не установлен curl или wget."
+            L_ERR_NO_CP_TOOL="Необходима утилита cp или install."
+            L_WARN_NO_NET_TOOL="Утилиты сети не найдены. Проверка порта пропущена."
+            L_INFO_PORT_IGNORE="Порт занят текущим процессом телеметрии. Игнорируем."
+            L_ERR_PORT_IN_USE="Порт уже занят другим процессом:"
+            L_ERR_PORT_FREE="Освободите порт или укажите другой и попробуйте снова."
+            L_ERR_UNSUP_ARCH="Неподдерживаемая архитектура:"
+            L_ERR_CREATE_GRP="Не удалось создать группу"
+            L_ERR_CREATE_USR="Не удалось создать пользователя"
+            L_ERR_MKDIR="Не удалось создать директории"
+            L_ERR_INSTALL_DIR="не является директорией."
+            L_ERR_BIN_INSTALL="Не удалось установить бинарный файл"
+            L_ERR_BIN_COPY="Не удалось скопировать бинарный файл"
+            L_ERR_BIN_EXEC="Бинарный файл не исполняемый."
+            L_ERR_GEN_SEC="Не удалось сгенерировать секрет."
+            L_INFO_CONF_EXISTS="Конфиг уже существует. Обновление параметров..."
+            L_INFO_UPD_PORT="Обновлен порт:"
+            L_INFO_UPD_SEC="Обновлен секрет для пользователя 'hello'"
+            L_INFO_UPD_DOM="Обновлен tls_domain:"
+            L_INFO_UPD_TAG="Обновлен ad_tag"
+            L_ERR_CONF_INST="Не удалось установить конфиг"
+            L_INFO_CONF_OK="Конфиг успешно создан."
+            L_INFO_CONF_SEC="Настроен секрет для пользователя 'hello':"
+            L_WARN_SVC_FAIL="Не удалось запустить службу"
+            L_INFO_MANUAL_START="Менеджер служб не найден. Запустите вручную:"
+            L_INFO_UNINST_START="Начинается удаление"
+            L_U_STAGE_1=">>> Этап 1: Остановка служб"
+            L_U_STAGE_2=">>> Этап 2: Удаление конфигурации службы"
+            L_U_STAGE_3=">>> Этап 3: Завершение процессов пользователя"
+            L_U_STAGE_4=">>> Этап 4: Удаление бинарного файла"
+            L_U_STAGE_5=">>> Этап 5: Полная очистка (конфиг, данные, пользователь)"
+            L_INFO_KEEP_CONF="Примечание: Конфигурация сохранена. Используйте 'purge' для очистки."
+            L_INFO_I_START="Начинается установка"
+            L_I_STAGE_1=">>> Этап 1: Проверка окружения и зависимостей"
+            L_I_STAGE_1_5=">>> Этап 1.5: Интерактивная настройка"
+            L_I_PROMPT_DOM="\nПожалуйста, укажите домен TLS\nНажмите Enter, чтобы оставить по умолчанию [%s]: "
+            L_WARN_NO_TTY="Интерактивный режим недоступен (нет TTY). Используется:"
+            L_I_STAGE_2=">>> Этап 2: Загрузка архива"
+            L_ERR_TMP_DIR="Не удалось создать временную директорию"
+            L_ERR_TMP_INV="Временная директория недействительна"
+            L_INFO_FALLBACK="Сборка x86_64-v3 не найдена, откат к стандартной x86_64..."
+            L_ERR_DL_FAIL="Ошибка загрузки архива"
+            L_I_STAGE_3=">>> Этап 3: Распаковка архива"
+            L_ERR_EXTRACT="Ошибка распаковки архива."
+            L_ERR_BIN_NOT_FOUND="Бинарный файл не найден в архиве"
+            L_I_STAGE_4=">>> Этап 4: Настройка окружения (Юзер, Группа, Папки)"
+            L_I_STAGE_5=">>> Этап 5: Установка бинарного файла"
+            L_I_STAGE_6=">>> Этап 6: Генерация/Обновление конфигурации"
+            L_I_STAGE_7=">>> Этап 7: Установка и запуск службы"
+            L_OUT_WARN_H="УСТАНОВКА ЗАВЕРШЕНА С ПРЕДУПРЕЖДЕНИЯМИ"
+            L_OUT_WARN_D="Служба установлена, но не запустилась.\nПожалуйста, проверьте логи.\n"
+            L_OUT_SUCC_H="УСТАНОВКА УСПЕШНО ЗАВЕРШЕНА"
+            L_OUT_UNINST_H="УДАЛЕНИЕ ЗАВЕРШЕНО"
+            L_OUT_LINK="Ваша ссылка для подключения к Telegram Proxy:\n"
+            L_ERR_INCORR_ROOT_LOGIN="Используйте 'su -' или 'sudo -i' для входа под пользователем root"
+            L_OUT_LOGS="Чтобы посмотреть логи (в случае проблем), используйте команду:"
+            ;;
+        *)
+            L_ERR_DOMAIN_REQ="requires a domain argument."
+            L_ERR_PORT_REQ="requires a port argument."
+            L_ERR_PORT_NUM="Port must be a valid number."
+            L_ERR_PORT_RANGE="Port must be between 1 and 65535."
+            L_ERR_SECRET_REQ="requires a secret argument."
+            L_ERR_SECRET_HEX="Secret must contain only hex characters."
+            L_ERR_SECRET_LEN="Secret must be exactly 32 chars."
+            L_ERR_ADTAG_REQ="requires an ad_tag argument."
+            L_ERR_UNKNOWN_OPT="Unknown option:"
+            L_WARN_EXTRA_ARG="Ignoring extra argument:"
+            L_ERR_REQ_ARG="requires an argument (1, 2, en, ru)."
+            L_ERR_EMPTY_VAR="cannot be empty."
+            L_ERR_INV_VER="Invalid characters in version."
+            L_ERR_INV_BIN="Invalid characters in BIN_NAME."
+            L_ERR_ROOT="This script requires root or sudo."
+            L_ERR_SUDO_TTY="sudo requires a password, but no TTY detected."
+            L_ERR_DIR_CHECK="Safety check failed: Config is a directory."
+            L_ERR_CMD_NOT_FOUND="Required command not found:"
+            L_ERR_NO_DL_TOOL="Neither curl nor wget is installed."
+            L_ERR_NO_CP_TOOL="Need cp or install."
+            L_WARN_NO_NET_TOOL="Network tools not found. Skipping port check."
+            L_INFO_PORT_IGNORE="Port is in use by telemt. Ignoring as it will be restarted."
+            L_ERR_PORT_IN_USE="Port is already in use by another process:"
+            L_ERR_PORT_FREE="Please free the port or change it and try again."
+            L_ERR_UNSUP_ARCH="Unsupported architecture:"
+            L_ERR_CREATE_GRP="Cannot create group"
+            L_ERR_CREATE_USR="Cannot create user"
+            L_ERR_MKDIR="Failed to create directories"
+            L_ERR_INSTALL_DIR="is not a directory."
+            L_ERR_BIN_INSTALL="Failed to install binary"
+            L_ERR_BIN_COPY="Failed to copy binary"
+            L_ERR_BIN_EXEC="Binary not executable."
+            L_ERR_GEN_SEC="Failed to generate secret."
+            L_INFO_CONF_EXISTS="Config already exists. Updating parameters..."
+            L_INFO_UPD_PORT="Updated port:"
+            L_INFO_UPD_SEC="Updated secret for user 'hello'"
+            L_INFO_UPD_DOM="Updated tls_domain:"
+            L_INFO_UPD_TAG="Updated ad_tag"
+            L_ERR_CONF_INST="Failed to install config"
+            L_INFO_CONF_OK="Config created successfully."
+            L_INFO_CONF_SEC="Configured secret for user 'hello':"
+            L_WARN_SVC_FAIL="Failed to start service"
+            L_INFO_MANUAL_START="Service manager not found. Start manually:"
+            L_INFO_UNINST_START="Starting uninstallation of"
+            L_U_STAGE_1=">>> Stage 1: Stopping services"
+            L_U_STAGE_2=">>> Stage 2: Removing service configuration"
+            L_U_STAGE_3=">>> Stage 3: Terminating user processes"
+            L_U_STAGE_4=">>> Stage 4: Removing binary"
+            L_U_STAGE_5=">>> Stage 5: Purging configuration, data, and user"
+            L_INFO_KEEP_CONF="Note: Configuration kept. Run with 'purge' to remove completely."
+            L_INFO_I_START="Starting installation of"
+            L_I_STAGE_1=">>> Stage 1: Verifying environment and dependencies"
+            L_I_STAGE_1_5=">>> Stage 1.5: Interactive Setup"
+            L_I_PROMPT_DOM="\nPlease specify the TLS Domain\nPress Enter to keep default [%s]: "
+            L_WARN_NO_TTY="Interactive mode unavailable (no TTY). Using:"
+            L_I_STAGE_2=">>> Stage 2: Downloading archive"
+            L_ERR_TMP_DIR="Temp directory creation failed"
+            L_ERR_TMP_INV="Temp directory is invalid or was not created"
+            L_INFO_FALLBACK="x86_64-v3 build not found, falling back to standard x86_64..."
+            L_ERR_DL_FAIL="Download failed"
+            L_I_STAGE_3=">>> Stage 3: Extracting archive"
+            L_ERR_EXTRACT="Extraction failed."
+            L_ERR_BIN_NOT_FOUND="Binary not found in archive"
+            L_I_STAGE_4=">>> Stage 4: Setting up environment (User, Group, Directories)"
+            L_I_STAGE_5=">>> Stage 5: Installing binary"
+            L_I_STAGE_6=">>> Stage 6: Generating/Updating configuration"
+            L_I_STAGE_7=">>> Stage 7: Installing and starting service"
+            L_OUT_WARN_H="INSTALLATION COMPLETED WITH WARNINGS"
+            L_OUT_WARN_D="The service was installed but failed to start.\nPlease check the logs to determine the issue.\n"
+            L_OUT_SUCC_H="INSTALLATION SUCCESS"
+            L_OUT_UNINST_H="UNINSTALLATION COMPLETE"
+            L_OUT_LINK="Your Telegram Proxy connection link:\n"
+            L_ERR_INCORR_ROOT_LOGIN="Use 'su -' or 'sudo -i' to login under root"
+            L_OUT_LOGS="To view logs (in case of issues), use the following command:"
+            ;;
+    esac
+}
+
+set_language "$LANG_CHOICE"
 
 while [ $# -gt 0 ]; do
     case "$1" in
         -h|--help) ACTION="help"; shift ;;
+        -l|--lang)
+            if [ "$#" -lt 2 ] || [ -z "$2" ]; then
+                printf '[ERROR] %s %s\n' "$1" "$L_ERR_REQ_ARG" >&2; exit 1
+            fi
+            case "$2" in
+                ru|2) LANG_CHOICE="ru"; set_language "$LANG_CHOICE"; LANG_PROVIDED=1 ;;
+                en|1) LANG_CHOICE="en"; set_language "$LANG_CHOICE"; LANG_PROVIDED=1 ;;
+                *) printf '[ERROR] %s %s\n' "$1" "$L_ERR_REQ_ARG" >&2; exit 1 ;;
+            esac
+            shift 2 ;;
+        -d|--domain)
+            if [ "$#" -lt 2 ] || [ -z "$2" ]; then
+                printf '[ERROR] %s %s\n' "$1" "$L_ERR_DOMAIN_REQ" >&2; exit 1
+            fi
+            TLS_DOMAIN="$2"; DOMAIN_PROVIDED=1; shift 2 ;;
+        -p|--port)
+            if [ "$#" -lt 2 ] || [ -z "$2" ]; then
+                printf '[ERROR] %s %s\n' "$1" "$L_ERR_PORT_REQ" >&2; exit 1
+            fi
+            case "$2" in
+                *[!0-9]*) printf '[ERROR] %s\n' "$L_ERR_PORT_NUM" >&2; exit 1 ;;
+            esac
+            port_num="$(printf '%s\n' "$2" | sed 's/^0*//')"
+            [ -z "$port_num" ] && port_num="0"
+            if [ "${#port_num}" -gt 5 ] || [ "$port_num" -lt 1 ] || [ "$port_num" -gt 65535 ]; then
+                printf '[ERROR] %s\n' "$L_ERR_PORT_RANGE" >&2; exit 1
+            fi
+            SERVER_PORT="$port_num"; PORT_PROVIDED=1; shift 2 ;;
+        -s|--secret)
+            if [ "$#" -lt 2 ] || [ -z "$2" ]; then
+                printf '[ERROR] %s %s\n' "$1" "$L_ERR_SECRET_REQ" >&2; exit 1
+            fi
+            case "$2" in
+                *[!0-9a-fA-F]*) printf '[ERROR] %s\n' "$L_ERR_SECRET_HEX" >&2; exit 1 ;;
+            esac
+            if [ "${#2}" -ne 32 ]; then
+                printf '[ERROR] %s\n' "$L_ERR_SECRET_LEN" >&2; exit 1
+            fi
+            USER_SECRET="$2"; SECRET_PROVIDED=1; shift 2 ;;
+        -a|--ad-tag|--ad_tag)
+            if [ "$#" -lt 2 ] || [ -z "$2" ]; then
+                printf '[ERROR] %s %s\n' "$1" "$L_ERR_ADTAG_REQ" >&2; exit 1
+            fi
+            AD_TAG="$2"; AD_TAG_PROVIDED=1; shift 2 ;;
         uninstall|--uninstall)
             if [ "$ACTION" != "purge" ]; then ACTION="uninstall"; fi
             shift ;;
         purge|--purge) ACTION="purge"; shift ;;
         install|--install) ACTION="install"; shift ;;
-        -*) printf '[ERROR] Unknown option: %s\n' "$1" >&2; exit 1 ;;
+        -*) printf '[ERROR] %s %s\n' "$L_ERR_UNKNOWN_OPT" "$1" >&2; exit 1 ;;
         *)
             if [ "$ACTION" = "install" ]; then TARGET_VERSION="$1"
-            else printf '[WARNING] Ignoring extra argument: %s\n' "$1" >&2; fi
+            else printf '[WARNING] %s %s\n' "$L_WARN_EXTRA_ARG" "$1" >&2; fi
             shift ;;
     esac
 done
 
+if [ "$ACTION" != "help" ] && [ "$LANG_PROVIDED" -eq 0 ]; then
+    if [ -t 0 ] || [ -c /dev/tty ]; then
+        printf "\nSelect language / Выберите язык:\n"
+        printf "  1) English (default)\n"
+        printf "  2) Русский\n"
+        printf "Your choice / Ваш выбор [1/2]: "
+        read -r input_lang </dev/tty || input_lang=""
+        case "$input_lang" in
+            2) LANG_CHOICE="ru" ;;
+            *) LANG_CHOICE="en" ;;
+        esac
+    else
+        LANG_CHOICE="en"
+    fi
+    set_language "$LANG_CHOICE"
+fi
+
 say() {
     if [ "$#" -eq 0 ] || [ -z "${1:-}" ]; then
         printf '\n'
@@ -52,11 +284,33 @@ cleanup() {
 trap cleanup EXIT INT TERM
 
 show_help() {
-    say "Usage: $0 [ <version> | install | uninstall | purge | --help ]"
-    say "  <version>    Install specific version (e.g. 3.3.15, default: latest)"
-    say "  install      Install the latest version"
-    say "  uninstall    Remove the binary and service (keeps config and user)"
-    say "  purge        Remove everything including configuration, data, and user"
+    if [ "$LANG_CHOICE" = "ru" ]; then
+        say "Использование: $0 [ <версия> | install | uninstall | purge ] [ опции ]"
+        say "  <версия>     Установить конкретную версию (например, 3.3.15, по умолчанию: latest)"
+        say "  install      Установить последнюю версию"
+        say "  uninstall    Удалить бинарный файл и службу"
+        say "  purge        Полностью удалить вместе с конфигурацией, данными и пользователем"
+        say ""
+        say "Опции:"
+        say "  -d, --domain Указать домен TLS (по умолчанию: petrovich.ru)"
+        say "  -p, --port   Указать порт сервера (по умолчанию: 443)"
+        say "  -s, --secret Указать секрет пользователя (32 hex символа)"
+        say "  -a, --ad-tag Указать ad_tag"
+        say "  -l, --lang   Выбрать язык вывода (1/en или 2/ru)"
+    else
+        say "Usage: $0 [ <version> | install | uninstall | purge ] [ options ]"
+        say "  <version>    Install specific version (e.g. 3.3.15, default: latest)"
+        say "  install      Install the latest version"
+        say "  uninstall    Remove the binary and service"
+        say "  purge        Remove everything including configuration, data, and user"
+        say ""
+        say "Options:"
+        say "  -d, --domain Set TLS domain (default: petrovich.ru)"
+        say "  -p, --port   Set server port (default: 443)"
+        say "  -s, --secret Set specific user secret (32 hex characters)"
+        say "  -a, --ad-tag Set ad_tag"
+        say "  -l, --lang   Set output language (1/en or 2/ru)"
+    fi
     exit 0
 }
 
@@ -73,13 +327,13 @@ get_realpath() {
     path_in="$1"
     case "$path_in" in /*) ;; *) path_in="$(pwd)/$path_in" ;; esac
 
-    if command -v realpath >/dev/null 2>&1; then 
+    if command -v realpath >/dev/null 2>&1; then
         if realpath_out="$(realpath -m "$path_in" 2>/dev/null)"; then
             printf '%s\n' "$realpath_out"
             return
         fi
     fi
-    
+
     if command -v readlink >/dev/null 2>&1; then
         resolved_path="$(readlink -f "$path_in" 2>/dev/null || true)"
         if [ -n "$resolved_path" ]; then
@@ -112,18 +366,22 @@ get_svc_mgr() {
     else echo "none"; fi
 }
 
+is_config_exists() {
+    if [ -n "$SUDO" ]; then
+        $SUDO sh -c '[ -f "$1" ]' _ "$CONFIG_FILE"
+    else
+        [ -f "$CONFIG_FILE" ]
+    fi
+}
+
 verify_common() {
-    [ -n "$BIN_NAME" ] || die "BIN_NAME cannot be empty."
-    [ -n "$INSTALL_DIR" ] || die "INSTALL_DIR cannot be empty."
-    [ -n "$CONFIG_DIR" ] || die "CONFIG_DIR cannot be empty."
-    [ -n "$CONFIG_FILE" ] || die "CONFIG_FILE cannot be empty."
+    [ -n "$BIN_NAME" ] || die "BIN_NAME $L_ERR_EMPTY_VAR"
+    [ -n "$INSTALL_DIR" ] || die "INSTALL_DIR $L_ERR_EMPTY_VAR"
+    [ -n "$CONFIG_DIR" ] || die "CONFIG_DIR $L_ERR_EMPTY_VAR"
+    [ -n "$CONFIG_FILE" ] || die "CONFIG_FILE $L_ERR_EMPTY_VAR"
 
-    case "${INSTALL_DIR}${CONFIG_DIR}${WORK_DIR}${CONFIG_FILE}" in
-        *[!a-zA-Z0-9_./-]*) die "Invalid characters in paths. Only alphanumeric, _, ., -, and / allowed." ;;
-    esac
-
-    case "$TARGET_VERSION" in *[!a-zA-Z0-9_.-]*) die "Invalid characters in version." ;; esac
-    case "$BIN_NAME" in *[!a-zA-Z0-9_-]*) die "Invalid characters in BIN_NAME." ;; esac
+    case "$TARGET_VERSION" in *[!a-zA-Z0-9_.-]*) die "$L_ERR_INV_VER" ;; esac
+    case "$BIN_NAME" in *[!a-zA-Z0-9_-]*) die "$L_ERR_INV_BIN" ;; esac
 
     INSTALL_DIR="$(get_realpath "$INSTALL_DIR")"
     CONFIG_DIR="$(get_realpath "$CONFIG_DIR")"
@@ -136,65 +394,87 @@ verify_common() {
 
     if [ "$(id -u)" -eq 0 ]; then
         SUDO=""
+        if [ "${USER:-}" != "root" ] && [ "${LOGNAME:-}" != "root" ]; then
+            die "$L_ERR_INCORR_ROOT_LOGIN"
+        fi
     else
-        command -v sudo >/dev/null 2>&1 || die "This script requires root or sudo. Neither found."
+        command -v sudo >/dev/null 2>&1 || die "$L_ERR_ROOT"
         SUDO="sudo"
         if ! sudo -n true 2>/dev/null; then
             if ! [ -t 0 ]; then
-                die "sudo requires a password, but no TTY detected. Aborting to prevent hang."
+                die "$L_ERR_SUDO_TTY"
             fi
         fi
     fi
 
     if [ -n "$SUDO" ]; then
         if $SUDO sh -c '[ -d "$1" ]' _ "$CONFIG_FILE"; then
-            die "Safety check failed: CONFIG_FILE '$CONFIG_FILE' is a directory."
+            die "$L_ERR_DIR_CHECK"
         fi
     elif [ -d "$CONFIG_FILE" ]; then
-        die "Safety check failed: CONFIG_FILE '$CONFIG_FILE' is a directory."
+        die "$L_ERR_DIR_CHECK"
     fi
 
-    for path in "$CONFIG_DIR" "$CONFIG_PARENT_DIR" "$WORK_DIR"; do
-        check_path="$(get_realpath "$path")"
-        case "$check_path" in
-            /|/bin|/sbin|/usr|/usr/bin|/usr/sbin|/usr/local|/usr/local/bin|/usr/local/sbin|/usr/local/etc|/usr/local/share|/etc|/var|/var/lib|/var/log|/var/run|/home|/root|/tmp|/lib|/lib64|/opt|/run|/boot|/dev|/sys|/proc)
-                die "Safety check failed: '$path' (resolved to '$check_path') is a critical system directory." ;;
-        esac
-    done
-
-    check_install_dir="$(get_realpath "$INSTALL_DIR")"
-    case "$check_install_dir" in
-        /|/etc|/var|/home|/root|/tmp|/usr|/usr/local|/opt|/boot|/dev|/sys|/proc|/run)
-            die "Safety check failed: INSTALL_DIR '$INSTALL_DIR' is a critical system directory." ;;
-    esac
-
-    for cmd in id uname grep find rm chown chmod mv mktemp mkdir tr dd sed ps head sleep cat tar gzip rmdir; do
-        command -v "$cmd" >/dev/null 2>&1 || die "Required command not found: $cmd"
+    for cmd in id uname awk grep find rm chown chmod mv mktemp mkdir tr dd sed ps head sleep cat tar gzip; do
+        command -v "$cmd" >/dev/null 2>&1 || die "$L_ERR_CMD_NOT_FOUND $cmd"
     done
 }
 
 verify_install_deps() {
-    command -v curl >/dev/null 2>&1 || command -v wget >/dev/null 2>&1 || die "Neither curl nor wget is installed."
-    command -v cp >/dev/null 2>&1 || command -v install >/dev/null 2>&1 || die "Need cp or install"
+    command -v curl >/dev/null 2>&1 || command -v wget >/dev/null 2>&1 || die "$L_ERR_NO_DL_TOOL"
+    command -v cp >/dev/null 2>&1 || command -v install >/dev/null 2>&1 || die "$L_ERR_NO_CP_TOOL"
 
     if ! command -v setcap >/dev/null 2>&1; then
         if command -v apk >/dev/null 2>&1; then
-            $SUDO apk add --no-cache libcap-utils >/dev/null 2>&1 || $SUDO apk add --no-cache libcap >/dev/null 2>&1 || true
+            $SUDO apk add --no-cache libcap-utils libcap >/dev/null 2>&1 || true
         elif command -v apt-get >/dev/null 2>&1; then
-            $SUDO apt-get update -q >/dev/null 2>&1 || true
-            $SUDO apt-get install -y -q libcap2-bin >/dev/null 2>&1 || true
+            $SUDO env DEBIAN_FRONTEND=noninteractive apt-get install -y -q libcap2-bin >/dev/null 2>&1 || {
+                $SUDO env DEBIAN_FRONTEND=noninteractive apt-get update -q >/dev/null 2>&1 || true
+                $SUDO env DEBIAN_FRONTEND=noninteractive apt-get install -y -q libcap2-bin >/dev/null 2>&1 || true
+            }
         elif command -v dnf >/dev/null 2>&1; then $SUDO dnf install -y -q libcap >/dev/null 2>&1 || true
         elif command -v yum >/dev/null 2>&1; then $SUDO yum install -y -q libcap >/dev/null 2>&1 || true
         fi
     fi
 }
 
+check_port_availability() {
+    port_info=""
+
+    if command -v ss >/dev/null 2>&1; then
+        port_info=$($SUDO ss -tulnp 2>/dev/null | grep -E ":${SERVER_PORT}([[:space:]]|$)" || true)
+    elif command -v netstat >/dev/null 2>&1; then
+        port_info=$($SUDO netstat -tulnp 2>/dev/null | grep -E ":${SERVER_PORT}([[:space:]]|$)" || true)
+    elif command -v lsof >/dev/null 2>&1; then
+        port_info=$($SUDO lsof -i :${SERVER_PORT} 2>/dev/null | grep LISTEN || true)
+    else
+        say "[WARNING] $L_WARN_NO_NET_TOOL"
+        return 0
+    fi
+
+    if [ -n "$port_info" ]; then
+        if printf '%s\n' "$port_info" | grep -q "${BIN_NAME}"; then
+            say "  -> $L_INFO_PORT_IGNORE"
+        else
+            say "[ERROR] $L_ERR_PORT_IN_USE $SERVER_PORT:"
+            printf '  %s\n' "$port_info"
+            die "$L_ERR_PORT_FREE"
+        fi
+    fi
+}
+
 detect_arch() {
     sys_arch="$(uname -m)"
     case "$sys_arch" in
-        x86_64|amd64) echo "x86_64" ;;
+        x86_64|amd64)
+            if [ -r /proc/cpuinfo ] && grep -q "avx2" /proc/cpuinfo 2>/dev/null && grep -q "bmi2" /proc/cpuinfo 2>/dev/null; then
+                echo "x86_64-v3"
+            else
+                echo "x86_64"
+            fi
+            ;;
         aarch64|arm64) echo "aarch64" ;;
-        *) die "Unsupported architecture: $sys_arch" ;;
+        *) die "$L_ERR_UNSUP_ARCH $sys_arch" ;;
     esac
 }
 
@@ -218,7 +498,7 @@ ensure_user_group() {
     if ! check_os_entity group telemt; then
         if command -v groupadd >/dev/null 2>&1; then $SUDO groupadd -r telemt
         elif command -v addgroup >/dev/null 2>&1; then $SUDO addgroup -S telemt
-        else die "Cannot create group"; fi
+        else die "$L_ERR_CREATE_GRP" ; fi
     fi
 
     if ! check_os_entity passwd telemt; then
@@ -230,16 +510,16 @@ ensure_user_group() {
             else
                 $SUDO adduser --system --home "$WORK_DIR" --shell "$nologin_bin" --no-create-home --ingroup telemt --disabled-password telemt
             fi
-        else die "Cannot create user"; fi
+        else die "$L_ERR_CREATE_USR"; fi
     fi
 }
 
 setup_dirs() {
-    $SUDO mkdir -p "$WORK_DIR" "$CONFIG_DIR" "$CONFIG_PARENT_DIR" || die "Failed to create directories"
-    
+    $SUDO mkdir -p "$WORK_DIR" "$CONFIG_DIR" "$CONFIG_PARENT_DIR" || die "$L_ERR_MKDIR"
+
     $SUDO chown telemt:telemt "$WORK_DIR" && $SUDO chmod 750 "$WORK_DIR"
-    $SUDO chown root:telemt "$CONFIG_DIR" && $SUDO chmod 750 "$CONFIG_DIR"
-    
+    $SUDO chown telemt:telemt "$CONFIG_DIR" && $SUDO chmod 750 "$CONFIG_DIR"
+
     if [ "$CONFIG_PARENT_DIR" != "$CONFIG_DIR" ] && [ "$CONFIG_PARENT_DIR" != "." ] && [ "$CONFIG_PARENT_DIR" != "/" ]; then
         $SUDO chown root:telemt "$CONFIG_PARENT_DIR" && $SUDO chmod 750 "$CONFIG_PARENT_DIR"
     fi
@@ -257,21 +537,23 @@ stop_service() {
 install_binary() {
     bin_src="$1"; bin_dst="$2"
     if [ -e "$INSTALL_DIR" ] && [ ! -d "$INSTALL_DIR" ]; then
-        die "'$INSTALL_DIR' is not a directory."
+        die "'$INSTALL_DIR' $L_ERR_INSTALL_DIR"
     fi
 
-    $SUDO mkdir -p "$INSTALL_DIR" || die "Failed to create install directory"
+    $SUDO mkdir -p "$INSTALL_DIR" || die "$L_ERR_MKDIR"
+
+    $SUDO rm -f "$bin_dst" 2>/dev/null || true
+
     if command -v install >/dev/null 2>&1; then
-        $SUDO install -m 0755 "$bin_src" "$bin_dst" || die "Failed to install binary"
+        $SUDO install -m 0755 "$bin_src" "$bin_dst" || die "$L_ERR_BIN_INSTALL"
     else
-        $SUDO rm -f "$bin_dst" 2>/dev/null || true
-        $SUDO cp "$bin_src" "$bin_dst" && $SUDO chmod 0755 "$bin_dst" || die "Failed to copy binary"
+        $SUDO cp "$bin_src" "$bin_dst" && $SUDO chmod 0755 "$bin_dst" || die "$L_ERR_BIN_COPY"
     fi
 
-    $SUDO sh -c '[ -x "$1" ]' _ "$bin_dst" || die "Binary not executable: $bin_dst"
+    $SUDO sh -c '[ -x "$1" ]' _ "$bin_dst" || die "$L_ERR_BIN_EXEC $bin_dst"
 
     if command -v setcap >/dev/null 2>&1; then
-        $SUDO setcap cap_net_bind_service=+ep "$bin_dst" 2>/dev/null || true
+        $SUDO setcap cap_net_bind_service,cap_net_admin=+ep "$bin_dst" 2>/dev/null || true
     fi
 }
 
@@ -287,11 +569,20 @@ generate_secret() {
 }
 
 generate_config_content() {
+    conf_secret="$1"
+    conf_tag="$2"
     escaped_tls_domain="$(printf '%s\n' "$TLS_DOMAIN" | tr -d '[:cntrl:]' | sed 's/\\/\\\\/g; s/"/\\"/g')"
 
     cat <<EOF
 [general]
-use_middle_proxy = false
+use_middle_proxy = true
+EOF
+
+    if [ -n "$conf_tag" ]; then
+        echo "ad_tag = \"${conf_tag}\""
+    fi
+
+    cat <<EOF
 
 [general.modes]
 classic = false
@@ -299,7 +590,7 @@ secure = false
 tls = true
 
 [server]
-port = 443
+port = ${SERVER_PORT}
 
 [server.api]
 enabled = true
@@ -310,28 +601,65 @@ whitelist = ["127.0.0.1/32"]
 tls_domain = "${escaped_tls_domain}"
 
 [access.users]
-hello = "$1"
+hello = "${conf_secret}"
 EOF
 }
 
 install_config() {
-    if [ -n "$SUDO" ]; then
-        if $SUDO sh -c '[ -f "$1" ]' _ "$CONFIG_FILE"; then
-            say "  -> Config already exists at $CONFIG_FILE. Skipping creation."
-            return 0
-        fi
-    elif [ -f "$CONFIG_FILE" ]; then
-        say "  -> Config already exists at $CONFIG_FILE. Skipping creation."
+    if is_config_exists; then
+        say "  -> $L_INFO_CONF_EXISTS"
+
+        tmp_conf="${TEMP_DIR}/config.tmp"
+        $SUDO cat "$CONFIG_FILE" > "$tmp_conf"
+
+        escaped_domain="$(printf '%s\n' "$TLS_DOMAIN" | tr -d '[:cntrl:]' | sed 's/\\/\\\\/g; s/"/\\"/g')"
+
+        awk -v port="$SERVER_PORT" -v secret="$USER_SECRET" -v domain="$escaped_domain" -v ad_tag="$AD_TAG" \
+            -v flag_p="$PORT_PROVIDED" -v flag_s="$SECRET_PROVIDED" -v flag_d="$DOMAIN_PROVIDED" -v flag_a="$AD_TAG_PROVIDED" '
+        BEGIN { ad_tag_handled = 0 }
+
+        flag_p == "1" && /^[ \t]*port[ \t]*=/ { print "port = " port; next }
+        flag_s == "1" && /^[ \t]*hello[ \t]*=/ { print "hello = \"" secret "\""; next }
+        flag_d == "1" && /^[ \t]*tls_domain[ \t]*=/ { print "tls_domain = \"" domain "\""; next }
+
+        flag_a == "1" && /^[ \t]*ad_tag[ \t]*=/ {
+            if (!ad_tag_handled) {
+                print "ad_tag = \"" ad_tag "\"";
+                ad_tag_handled = 1;
+            }
+            next
+        }
+        flag_a == "1" && /^\[general\]/ {
+            print;
+            if (!ad_tag_handled) {
+                print "ad_tag = \"" ad_tag "\"";
+                ad_tag_handled = 1;
+            }
+            next
+        }
+
+        { print }
+        ' "$tmp_conf" > "${tmp_conf}.new" && mv "${tmp_conf}.new" "$tmp_conf"
+
+        [ "$PORT_PROVIDED" -eq 1 ] && say "  -> $L_INFO_UPD_PORT $SERVER_PORT"
+        [ "$SECRET_PROVIDED" -eq 1 ] && say "  -> $L_INFO_UPD_SEC"
+        [ "$DOMAIN_PROVIDED" -eq 1 ] && say "  -> $L_INFO_UPD_DOM $TLS_DOMAIN"
+        [ "$AD_TAG_PROVIDED" -eq 1 ] && say "  -> $L_INFO_UPD_TAG"
+
+        write_root "$CONFIG_FILE" < "$tmp_conf"
+        rm -f "$tmp_conf"
         return 0
     fi
 
-    toml_secret="$(generate_secret)" || die "Failed to generate secret."
+    if [ -z "$USER_SECRET" ]; then
+        USER_SECRET="$(generate_secret)" || die "$L_ERR_GEN_SEC"
+    fi
 
-    generate_config_content "$toml_secret" | write_root "$CONFIG_FILE" || die "Failed to install config"
+    generate_config_content "$USER_SECRET" "$AD_TAG" | write_root "$CONFIG_FILE" || die "$L_ERR_CONF_INST"
     $SUDO chown root:telemt "$CONFIG_FILE" && $SUDO chmod 640 "$CONFIG_FILE"
 
-    say "  -> Config created successfully."
-    say "  -> Generated secret for default user 'hello': $toml_secret"
+    say "  -> $L_INFO_CONF_OK"
+    say "  -> $L_INFO_CONF_SEC $USER_SECRET"
 }
 
 generate_systemd_content() {
@@ -348,9 +676,10 @@ Group=telemt
 WorkingDirectory=$WORK_DIR
 ExecStart="${INSTALL_DIR}/${BIN_NAME}" "${CONFIG_FILE}"
 Restart=on-failure
+RestartSec=5
 LimitNOFILE=65536
-AmbientCapabilities=CAP_NET_BIND_SERVICE
-CapabilityBoundingSet=CAP_NET_BIND_SERVICE
+AmbientCapabilities=CAP_NET_BIND_SERVICE CAP_NET_ADMIN
+CapabilityBoundingSet=CAP_NET_BIND_SERVICE CAP_NET_ADMIN
 
 [Install]
 WantedBy=multi-user.target
@@ -381,9 +710,9 @@ install_service() {
 
         $SUDO systemctl daemon-reload || true
         $SUDO systemctl enable "$SERVICE_NAME" || true
-        
+
         if ! $SUDO systemctl start "$SERVICE_NAME"; then
-            say "[WARNING] Failed to start service"
+            say "[WARNING] $L_WARN_SVC_FAIL"
             SERVICE_START_FAILED=1
         fi
     elif [ "$svc" = "openrc" ]; then
@@ -391,17 +720,17 @@ install_service() {
         $SUDO chown root:root "/etc/init.d/${SERVICE_NAME}" && $SUDO chmod 0755 "/etc/init.d/${SERVICE_NAME}"
 
         $SUDO rc-update add "$SERVICE_NAME" default 2>/dev/null || true
-        
+
         if ! $SUDO rc-service "$SERVICE_NAME" start 2>/dev/null; then
-            say "[WARNING] Failed to start service"
+            say "[WARNING] $L_WARN_SVC_FAIL"
             SERVICE_START_FAILED=1
         fi
     else
         cmd="\"${INSTALL_DIR}/${BIN_NAME}\" \"${CONFIG_FILE}\""
-        if [ -n "$SUDO" ]; then 
-            say "  -> Service manager not found. Start manually: sudo -u telemt $cmd"
-        else 
-            say "  -> Service manager not found. Start manually: su -s /bin/sh telemt -c '$cmd'"
+        if [ -n "$SUDO" ]; then
+            say "  -> $L_INFO_MANUAL_START sudo -u telemt $cmd"
+        else
+            say "  -> $L_INFO_MANUAL_START su -s /bin/sh telemt -c '$cmd'"
         fi
     fi
 }
@@ -415,9 +744,10 @@ kill_user_procs() {
         if command -v pgrep >/dev/null 2>&1; then
             pids="$(pgrep -u telemt 2>/dev/null || true)"
         else
-            pids="$(ps -u telemt -o pid= 2>/dev/null || true)"
+            pids="$(ps -ef 2>/dev/null | awk '$1=="telemt"{print $2}' || true)"
+            [ -z "$pids" ] && pids="$(ps 2>/dev/null | awk '$2=="telemt"{print $1}' || true)"
         fi
-        
+
         if [ -n "$pids" ]; then
             for pid in $pids; do
                 case "$pid" in ''|*[!0-9]*) continue ;; *) $SUDO kill "$pid" 2>/dev/null || true ;; esac
@@ -431,12 +761,12 @@ kill_user_procs() {
 }
 
 uninstall() {
-    say "Starting uninstallation of $BIN_NAME..."
+    say "$L_INFO_UNINST_START $BIN_NAME..."
 
-    say ">>> Stage 1: Stopping services"
+    say "$L_U_STAGE_1"
     stop_service
 
-    say ">>> Stage 2: Removing service configuration"
+    say "$L_U_STAGE_2"
     svc="$(get_svc_mgr)"
     if [ "$svc" = "systemd" ]; then
         $SUDO systemctl disable "$SERVICE_NAME" 2>/dev/null || true
@@ -447,27 +777,30 @@ uninstall() {
         $SUDO rm -f "/etc/init.d/${SERVICE_NAME}"
     fi
 
-    say ">>> Stage 3: Terminating user processes"
+    say "$L_U_STAGE_3"
     kill_user_procs
 
-    say ">>> Stage 4: Removing binary"
+    say "$L_U_STAGE_4"
     $SUDO rm -f "${INSTALL_DIR}/${BIN_NAME}"
 
     if [ "$ACTION" = "purge" ]; then
-        say ">>> Stage 5: Purging configuration, data, and user"
+        say "$L_U_STAGE_5"
         $SUDO rm -rf "$CONFIG_DIR" "$WORK_DIR"
         $SUDO rm -f "$CONFIG_FILE"
-        if [ "$CONFIG_PARENT_DIR" != "$CONFIG_DIR" ] && [ "$CONFIG_PARENT_DIR" != "." ] && [ "$CONFIG_PARENT_DIR" != "/" ]; then
-            $SUDO rmdir "$CONFIG_PARENT_DIR" 2>/dev/null || true
+
+        if check_os_entity passwd telemt; then
+            $SUDO userdel telemt 2>/dev/null || $SUDO deluser telemt 2>/dev/null || true
+        fi
+
+        if check_os_entity group telemt; then
+            $SUDO groupdel telemt 2>/dev/null || $SUDO delgroup telemt 2>/dev/null || true
         fi
-        $SUDO userdel telemt 2>/dev/null || $SUDO deluser telemt 2>/dev/null || true
-        $SUDO groupdel telemt 2>/dev/null || $SUDO delgroup telemt 2>/dev/null || true
     else
-        say "Note: Configuration and user kept. Run with 'purge' to remove completely."
+        say "$L_INFO_KEEP_CONF"
     fi
-    
+
     printf '\n====================================================================\n'
-    printf '                    UNINSTALLATION COMPLETE\n'
+    printf '                    %s\n' "$L_OUT_UNINST_H"
     printf '====================================================================\n\n'
     exit 0
 }
@@ -476,81 +809,135 @@ case "$ACTION" in
     help) show_help ;;
     uninstall|purge) verify_common; uninstall ;;
     install)
-        say "Starting installation of $BIN_NAME (Version: $TARGET_VERSION)"
+        say "$L_INFO_I_START $BIN_NAME (Version: $TARGET_VERSION)"
 
-        say ">>> Stage 1: Verifying environment and dependencies"
-        verify_common; verify_install_deps
+        say "$L_I_STAGE_1"
+        verify_common
+        verify_install_deps
 
-        if [ "$TARGET_VERSION" != "latest" ]; then 
+        if is_config_exists; then
+            ext_port="$($SUDO awk -F'=' '/^[ \t]*port[ \t]*=/ {gsub(/[^0-9]/, "", $2); print $2; exit}' "$CONFIG_FILE" 2>/dev/null || true)"
+            if [ -n "$ext_port" ] && [ "$PORT_PROVIDED" -eq 0 ]; then
+                SERVER_PORT="$ext_port"
+            fi
+
+            ext_secret="$($SUDO awk -F'"' '/^[ \t]*hello[ \t]*=/ {print $2; exit}' "$CONFIG_FILE" 2>/dev/null || true)"
+            if [ -n "$ext_secret" ] && [ "$SECRET_PROVIDED" -eq 0 ]; then
+                USER_SECRET="$ext_secret"
+            fi
+
+            ext_domain="$($SUDO awk -F'"' '/^[ \t]*tls_domain[ \t]*=/ {print $2; exit}' "$CONFIG_FILE" 2>/dev/null || true)"
+            if [ -n "$ext_domain" ] && [ "$DOMAIN_PROVIDED" -eq 0 ]; then
+                TLS_DOMAIN="$ext_domain"
+            fi
+        fi
+
+        check_port_availability
+
+        if [ "$DOMAIN_PROVIDED" -eq 0 ]; then
+            say "$L_I_STAGE_1_5"
+            if [ -t 0 ] || [ -c /dev/tty ]; then
+                printf "$L_I_PROMPT_DOM" "$TLS_DOMAIN"
+                read -r input_domain </dev/tty || input_domain=""
+                if [ -n "$input_domain" ]; then
+                    TLS_DOMAIN="$input_domain"
+                fi
+            else
+                say "[WARNING] $L_WARN_NO_TTY $TLS_DOMAIN"
+            fi
+            DOMAIN_PROVIDED=1
+        fi
+
+        if [ "$TARGET_VERSION" != "latest" ]; then
             TARGET_VERSION="${TARGET_VERSION#v}"
         fi
-        
+
         ARCH="$(detect_arch)"; LIBC="$(detect_libc)"
         FILE_NAME="${BIN_NAME}-${ARCH}-linux-${LIBC}.tar.gz"
-        
+
         if [ "$TARGET_VERSION" = "latest" ]; then
             DL_URL="https://github.com/${REPO}/releases/latest/download/${FILE_NAME}"
-        else 
+        else
             DL_URL="https://github.com/${REPO}/releases/download/${TARGET_VERSION}/${FILE_NAME}"
         fi
 
-        say ">>> Stage 2: Downloading archive"
-        TEMP_DIR="$(mktemp -d)" || die "Temp directory creation failed"
+        say "$L_I_STAGE_2"
+        TEMP_DIR="$(mktemp -d)" || die "$L_ERR_TMP_DIR"
         if [ -z "$TEMP_DIR" ] || [ ! -d "$TEMP_DIR" ]; then
-            die "Temp directory is invalid or was not created"
+            die "$L_ERR_TMP_INV"
         fi
 
-        fetch_file "$DL_URL" "${TEMP_DIR}/${FILE_NAME}" || die "Download failed"
+        if ! fetch_file "$DL_URL" "${TEMP_DIR}/${FILE_NAME}"; then
+            if [ "$ARCH" = "x86_64-v3" ]; then
+                say "  -> $L_INFO_FALLBACK"
+                ARCH="x86_64"
+                FILE_NAME="${BIN_NAME}-${ARCH}-linux-${LIBC}.tar.gz"
+                if [ "$TARGET_VERSION" = "latest" ]; then
+                    DL_URL="https://github.com/${REPO}/releases/latest/download/${FILE_NAME}"
+                else
+                    DL_URL="https://github.com/${REPO}/releases/download/${TARGET_VERSION}/${FILE_NAME}"
+                fi
+                fetch_file "$DL_URL" "${TEMP_DIR}/${FILE_NAME}" || die "$L_ERR_DL_FAIL"
+            else
+                die "$L_ERR_DL_FAIL"
+            fi
+        fi
 
-        say ">>> Stage 3: Extracting archive"
+        say "$L_I_STAGE_3"
         if ! gzip -dc "${TEMP_DIR}/${FILE_NAME}" | tar -xf - -C "$TEMP_DIR" 2>/dev/null; then
-            die "Extraction failed (downloaded archive might be invalid or 404)."
+            die "$L_ERR_EXTRACT"
         fi
 
         EXTRACTED_BIN="$(find "$TEMP_DIR" -type f -name "$BIN_NAME" -print 2>/dev/null | head -n 1 || true)"
-        [ -n "$EXTRACTED_BIN" ] || die "Binary '$BIN_NAME' not found in archive"
+        [ -n "$EXTRACTED_BIN" ] || die "$L_ERR_BIN_NOT_FOUND"
 
-        say ">>> Stage 4: Setting up environment (User, Group, Directories)"
+        say "$L_I_STAGE_4"
         ensure_user_group; setup_dirs; stop_service
-        
-        say ">>> Stage 5: Installing binary"
+
+        say "$L_I_STAGE_5"
         install_binary "$EXTRACTED_BIN" "${INSTALL_DIR}/${BIN_NAME}"
-        
-        say ">>> Stage 6: Generating configuration"
+
+        say "$L_I_STAGE_6"
         install_config
-        
-        say ">>> Stage 7: Installing and starting service"
+
+        say "$L_I_STAGE_7"
         install_service
 
         if [ "${SERVICE_START_FAILED:-0}" -eq 1 ]; then
             printf '\n====================================================================\n'
-            printf '               INSTALLATION COMPLETED WITH WARNINGS\n'
+            printf '               %s\n' "$L_OUT_WARN_H"
             printf '====================================================================\n\n'
-            printf 'The service was installed but failed to start automatically.\n'
-            printf 'Please check the logs to determine the issue.\n\n'
+            printf '%b' "$L_OUT_WARN_D"
         else
             printf '\n====================================================================\n'
-            printf '                      INSTALLATION SUCCESS\n'
+            printf '                      %s\n' "$L_OUT_SUCC_H"
             printf '====================================================================\n\n'
         fi
-        
+
+        SERVER_IP=""
+        if command -v curl >/dev/null 2>&1; then SERVER_IP="$(curl -s4 -m 3 ifconfig.me 2>/dev/null || curl -s4 -m 3 api.ipify.org 2>/dev/null || true)"
+        elif command -v wget >/dev/null 2>&1; then SERVER_IP="$(wget -qO- -T 3 ifconfig.me 2>/dev/null || wget -qO- -T 3 api.ipify.org 2>/dev/null || true)"; fi
+        [ -z "$SERVER_IP" ] && SERVER_IP="<YOUR_SERVER_IP>"
+
+        if command -v xxd >/dev/null 2>&1; then HEX_DOMAIN="$(printf '%s' "$TLS_DOMAIN" | xxd -p | tr -d '\n')"
+        elif command -v hexdump >/dev/null 2>&1; then HEX_DOMAIN="$(printf '%s' "$TLS_DOMAIN" | hexdump -v -e '/1 "%02x"')"
+        elif command -v od >/dev/null 2>&1; then HEX_DOMAIN="$(printf '%s' "$TLS_DOMAIN" | od -A n -t x1 | tr -d ' \n')"
+        else HEX_DOMAIN=""; fi
+
+        CLIENT_SECRET="ee${USER_SECRET}${HEX_DOMAIN}"
+
+        printf '%b\n' "$L_OUT_LINK"
+        printf '  tg://proxy?server=%s&port=%s&secret=%s\n\n' "$SERVER_IP" "$SERVER_PORT" "$CLIENT_SECRET"
+
         svc="$(get_svc_mgr)"
         if [ "$svc" = "systemd" ]; then
-            printf 'To check the status of your proxy service, run:\n'
-            printf '  systemctl status %s\n\n' "$SERVICE_NAME"
+            printf '%s\n' "$L_OUT_LOGS"
+            printf '  sudo journalctl -u %s -f\n\n' "$SERVICE_NAME"
         elif [ "$svc" = "openrc" ]; then
-            printf 'To check the status of your proxy service, run:\n'
-            printf '  rc-service %s status\n\n' "$SERVICE_NAME"
+            printf '%s\n' "$L_OUT_LOGS"
+            printf '  sudo tail -f /var/log/messages /var/log/syslog 2>/dev/null | grep -i %s\n\n' "$SERVICE_NAME"
         fi
-        
-        printf 'To get your user connection links (for Telegram), run:\n'
-        if command -v jq >/dev/null 2>&1; then
-            printf '  curl -s http://127.0.0.1:9091/v1/users | jq -r '\''.data[] | "User: \\(.username)\\n\\(.links.tls[0] // empty)\\n"'\''\n'
-        else
-            printf '  curl -s http://127.0.0.1:9091/v1/users\n'
-            printf '  (Tip: Install '\''jq'\'' for a much cleaner output)\n'
-        fi
-        
-        printf '\n====================================================================\n'
+
+        printf '====================================================================\n'
         ;;
 esac

src/api/config_store.rs

@@ -82,6 +82,7 @@ pub(super) async fn load_config_from_disk(config_path: &Path) -> Result<ProxyCon
         .map_err(|e| ApiFailure::internal(format!("failed to load config: {}", e)))
 }
 
+#[allow(dead_code)]
 pub(super) async fn save_config_to_disk(
     config_path: &Path,
     cfg: &ProxyConfig,
@@ -106,6 +107,12 @@ pub(super) async fn save_access_sections_to_disk(
         if applied.contains(section) {
             continue;
         }
+        if find_toml_table_bounds(&content, section.table_name()).is_none()
+            && access_section_is_empty(cfg, *section)
+        {
+            applied.push(*section);
+            continue;
+        }
         let rendered = render_access_section(cfg, *section)?;
         content = upsert_toml_table(&content, section.table_name(), &rendered);
         applied.push(*section);
@@ -183,6 +190,17 @@ fn render_access_section(cfg: &ProxyConfig, section: AccessSection) -> Result<St
     Ok(out)
 }
 
+fn access_section_is_empty(cfg: &ProxyConfig, section: AccessSection) -> bool {
+    match section {
+        AccessSection::Users => cfg.access.users.is_empty(),
+        AccessSection::UserAdTags => cfg.access.user_ad_tags.is_empty(),
+        AccessSection::UserMaxTcpConns => cfg.access.user_max_tcp_conns.is_empty(),
+        AccessSection::UserExpirations => cfg.access.user_expirations.is_empty(),
+        AccessSection::UserDataQuota => cfg.access.user_data_quota.is_empty(),
+        AccessSection::UserMaxUniqueIps => cfg.access.user_max_unique_ips.is_empty(),
+    }
+}
+
 fn serialize_table_body<T: Serialize>(value: &T) -> Result<String, ApiFailure> {
     toml::to_string(value)
         .map_err(|e| ApiFailure::internal(format!("failed to serialize access section: {}", e)))

src/api/mod.rs

@@ -1,10 +1,11 @@
 #![allow(clippy::too_many_arguments)]
 
-use std::convert::Infallible;
+use std::io::{Error as IoError, ErrorKind};
 use std::net::{IpAddr, SocketAddr};
 use std::path::PathBuf;
 use std::sync::Arc;
 use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::time::Duration;
 
 use http_body_util::Full;
 use hyper::body::{Bytes, Incoming};
@@ -12,11 +13,13 @@ use hyper::header::AUTHORIZATION;
 use hyper::server::conn::http1;
 use hyper::service::service_fn;
 use hyper::{Method, Request, Response, StatusCode};
+use subtle::ConstantTimeEq;
 use tokio::net::TcpListener;
-use tokio::sync::{Mutex, RwLock, watch};
+use tokio::sync::{Mutex, RwLock, Semaphore, watch};
+use tokio::time::timeout;
 use tracing::{debug, info, warn};
 
-use crate::config::ProxyConfig;
+use crate::config::{ApiGrayAction, ProxyConfig};
 use crate::ip_tracker::UserIpTracker;
 use crate::proxy::route_mode::RouteRuntimeController;
 use crate::startup::StartupTracker;
@@ -28,6 +31,7 @@ mod config_store;
 mod events;
 mod http_utils;
 mod model;
+mod patch;
 mod runtime_edge;
 mod runtime_init;
 mod runtime_min;
@@ -41,8 +45,9 @@ use config_store::{current_revision, load_config_from_disk, parse_if_match};
 use events::ApiEventStore;
 use http_utils::{error_response, read_json, read_optional_json, success_response};
 use model::{
-    ApiFailure, CreateUserRequest, DeleteUserResponse, HealthData, PatchUserRequest,
-    RotateSecretRequest, SummaryData, UserActiveIps,
+    ApiFailure, ClassCount, CreateUserRequest, DeleteUserResponse, HealthData, HealthReadyData,
+    PatchUserRequest, ResetUserQuotaResponse, RotateSecretRequest, SummaryData, UserActiveIps,
+    is_valid_username,
 };
 use runtime_edge::{
     EdgeConnectionsCacheEntry, build_runtime_connections_summary_data,
@@ -65,6 +70,10 @@ use runtime_zero::{
 };
 use users::{create_user, delete_user, patch_user, rotate_secret, users_from_config};
 
+const API_MAX_CONTROL_CONNECTIONS: usize = 1024;
+const API_HTTP_CONNECTION_TIMEOUT: Duration = Duration::from_secs(15);
+const ROUTE_USERNAME_ERROR: &str = "username must match [A-Za-z0-9_.-] and be 1..64 chars";
+
 pub(super) struct ApiRuntimeState {
     pub(super) process_started_at_epoch_secs: u64,
     pub(super) config_reload_count: AtomicU64,
@@ -79,6 +88,7 @@ pub(super) struct ApiShared {
     pub(super) me_pool: Arc<RwLock<Option<Arc<MePool>>>>,
     pub(super) upstream_manager: Arc<UpstreamManager>,
     pub(super) config_path: PathBuf,
+    pub(super) quota_state_path: PathBuf,
     pub(super) detected_ips_rx: watch::Receiver<(Option<IpAddr>, Option<IpAddr>)>,
     pub(super) mutation_lock: Arc<Mutex<()>>,
     pub(super) minimal_cache: Arc<Mutex<Option<MinimalCacheEntry>>>,
@@ -101,6 +111,18 @@ impl ApiShared {
     }
 }
 
+fn auth_header_matches(actual: &str, expected: &str) -> bool {
+    actual.as_bytes().ct_eq(expected.as_bytes()).into()
+}
+
+fn parse_route_username(user: &str) -> Result<&str, ApiFailure> {
+    if is_valid_username(user) {
+        Ok(user)
+    } else {
+        Err(ApiFailure::bad_request(ROUTE_USERNAME_ERROR))
+    }
+}
+
 pub async fn serve(
     listen: SocketAddr,
     stats: Arc<Stats>,
@@ -111,6 +133,7 @@ pub async fn serve(
     config_rx: watch::Receiver<Arc<ProxyConfig>>,
     admission_rx: watch::Receiver<bool>,
     config_path: PathBuf,
+    quota_state_path: PathBuf,
     detected_ips_rx: watch::Receiver<(Option<IpAddr>, Option<IpAddr>)>,
     process_started_at_epoch_secs: u64,
     startup_tracker: Arc<StartupTracker>,
@@ -142,6 +165,7 @@ pub async fn serve(
         me_pool,
         upstream_manager,
         config_path,
+        quota_state_path,
         detected_ips_rx,
         mutation_lock: Arc::new(Mutex::new(())),
         minimal_cache: Arc::new(Mutex::new(None)),
@@ -163,6 +187,8 @@ pub async fn serve(
         shared.runtime_events.clone(),
     );
 
+    let connection_permits = Arc::new(Semaphore::new(API_MAX_CONTROL_CONNECTIONS));
+
     loop {
         let (stream, peer) = match listener.accept().await {
             Ok(v) => v,
@@ -172,19 +198,46 @@ pub async fn serve(
             }
         };
 
+        let connection_permit = match connection_permits.clone().try_acquire_owned() {
+            Ok(permit) => permit,
+            Err(_) => {
+                debug!(
+                    peer = %peer,
+                    max_connections = API_MAX_CONTROL_CONNECTIONS,
+                    "Dropping API connection: control-plane connection budget exhausted"
+                );
+                continue;
+            }
+        };
+
         let shared_conn = shared.clone();
         let config_rx_conn = config_rx.clone();
         tokio::spawn(async move {
+            let _connection_permit = connection_permit;
             let svc = service_fn(move |req: Request<Incoming>| {
                 let shared_req = shared_conn.clone();
                 let config_rx_req = config_rx_conn.clone();
                 async move { handle(req, peer, shared_req, config_rx_req).await }
             });
-            if let Err(error) = http1::Builder::new()
-                .serve_connection(hyper_util::rt::TokioIo::new(stream), svc)
-                .await
+            match timeout(
+                API_HTTP_CONNECTION_TIMEOUT,
+                http1::Builder::new().serve_connection(hyper_util::rt::TokioIo::new(stream), svc),
+            )
+            .await
             {
-                debug!(error = %error, "API connection error");
+                Ok(Ok(())) => {}
+                Ok(Err(error)) => {
+                    if !error.is_user() {
+                        debug!(error = %error, "API connection error");
+                    }
+                }
+                Err(_) => {
+                    debug!(
+                        peer = %peer,
+                        timeout_ms = API_HTTP_CONNECTION_TIMEOUT.as_millis() as u64,
+                        "API connection timed out"
+                    );
+                }
             }
         });
     }
@@ -195,7 +248,7 @@ async fn handle(
     peer: SocketAddr,
     shared: Arc<ApiShared>,
     config_rx: watch::Receiver<Arc<ProxyConfig>>,
-) -> Result<Response<Full<Bytes>>, Infallible> {
+) -> Result<Response<Full<Bytes>>, IoError> {
     let request_id = shared.next_request_id();
     let cfg = config_rx.borrow().clone();
     let api_cfg = &cfg.server.api;
@@ -213,14 +266,25 @@ async fn handle(
 
     if !api_cfg.whitelist.is_empty() && !api_cfg.whitelist.iter().any(|net| net.contains(peer.ip()))
     {
-        return Ok(error_response(
-            request_id,
-            ApiFailure::new(
-                StatusCode::FORBIDDEN,
-                "forbidden",
-                "Source IP is not allowed",
-            ),
-        ));
+        return match api_cfg.gray_action {
+            ApiGrayAction::Api => Ok(error_response(
+                request_id,
+                ApiFailure::new(
+                    StatusCode::FORBIDDEN,
+                    "forbidden",
+                    "Source IP is not allowed",
+                ),
+            )),
+            ApiGrayAction::Ok200 => Ok(Response::builder()
+                .status(StatusCode::OK)
+                .header("content-type", "text/html; charset=utf-8")
+                .body(Full::new(Bytes::new()))
+                .unwrap()),
+            ApiGrayAction::Drop => Err(IoError::new(
+                ErrorKind::ConnectionAborted,
+                "api request dropped by gray_action=drop",
+            )),
+        };
     }
 
     if !api_cfg.auth_header.is_empty() {
@@ -228,7 +292,7 @@ async fn handle(
             .headers()
             .get(AUTHORIZATION)
             .and_then(|v| v.to_str().ok())
-            .map(|v| v == api_cfg.auth_header)
+            .map(|v| auth_header_matches(v, &api_cfg.auth_header))
             .unwrap_or(false);
         if !auth_ok {
             return Ok(error_response(
@@ -244,11 +308,16 @@ async fn handle(
 
     let method = req.method().clone();
     let path = req.uri().path().to_string();
+    let normalized_path = if path.len() > 1 {
+        path.trim_end_matches('/')
+    } else {
+        path.as_str()
+    };
     let query = req.uri().query().map(str::to_string);
     let body_limit = api_cfg.request_body_limit_bytes;
 
     let result: Result<Response<Full<Bytes>>, ApiFailure> = async {
-        match (method.as_str(), path.as_str()) {
+        match (method.as_str(), normalized_path) {
             ("GET", "/v1/health") => {
                 let revision = current_revision(&shared.config_path).await?;
                 let data = HealthData {
@@ -257,6 +326,33 @@ async fn handle(
                 };
                 Ok(success_response(StatusCode::OK, data, revision))
             }
+            ("GET", "/v1/health/ready") => {
+                let revision = current_revision(&shared.config_path).await?;
+                let admission_open = shared.runtime_state.admission_open.load(Ordering::Relaxed);
+                let upstream_health = shared.upstream_manager.api_health_summary().await;
+                let ready = admission_open && upstream_health.healthy_total > 0;
+                let reason = if ready {
+                    None
+                } else if !admission_open {
+                    Some("admission_closed")
+                } else {
+                    Some("no_healthy_upstreams")
+                };
+                let data = HealthReadyData {
+                    ready,
+                    status: if ready { "ready" } else { "not_ready" },
+                    reason,
+                    admission_open,
+                    healthy_upstreams: upstream_health.healthy_total,
+                    total_upstreams: upstream_health.configured_total,
+                };
+                let status_code = if ready {
+                    StatusCode::OK
+                } else {
+                    StatusCode::SERVICE_UNAVAILABLE
+                };
+                Ok(success_response(status_code, data, revision))
+            }
             ("GET", "/v1/system/info") => {
                 let revision = current_revision(&shared.config_path).await?;
                 let data = build_system_info_data(shared.as_ref(), cfg.as_ref(), &revision);
@@ -289,10 +385,24 @@ async fn handle(
             }
             ("GET", "/v1/stats/summary") => {
                 let revision = current_revision(&shared.config_path).await?;
+                let connections_bad_by_class = shared
+                    .stats
+                    .get_connects_bad_class_counts()
+                    .into_iter()
+                    .map(|(class, total)| ClassCount { class, total })
+                    .collect();
+                let handshake_failures_by_class = shared
+                    .stats
+                    .get_handshake_failure_class_counts()
+                    .into_iter()
+                    .map(|(class, total)| ClassCount { class, total })
+                    .collect();
                 let data = SummaryData {
                     uptime_seconds: shared.stats.uptime_secs(),
                     connections_total: shared.stats.get_connects_all(),
                     connections_bad_total: shared.stats.get_connects_bad(),
+                    connections_bad_by_class,
+                    handshake_failures_by_class,
                     handshake_timeouts_total: shared.stats.get_handshake_timeouts(),
                     configured_users: cfg.access.users.len(),
                 };
@@ -431,10 +541,115 @@ async fn handle(
                 Ok(success_response(status, data, revision))
             }
             _ => {
-                if let Some(user) = path.strip_prefix("/v1/users/")
+                if method == Method::POST
+                    && let Some(user) = normalized_path
+                        .strip_prefix("/v1/users/")
+                        .and_then(|path| path.strip_suffix("/reset-quota"))
                     && !user.is_empty()
                     && !user.contains('/')
                 {
+                    let user = parse_route_username(user)?;
+                    if api_cfg.read_only {
+                        return Ok(error_response(
+                            request_id,
+                            ApiFailure::new(
+                                StatusCode::FORBIDDEN,
+                                "read_only",
+                                "API runs in read-only mode",
+                            ),
+                        ));
+                    }
+                    let snapshot = match crate::quota_state::reset_user_quota(
+                        &shared.quota_state_path,
+                        shared.stats.as_ref(),
+                        user,
+                    )
+                    .await
+                    {
+                        Ok(snapshot) => snapshot,
+                        Err(error) => {
+                            shared.runtime_events.record(
+                                "api.user.reset_quota.failed",
+                                format!("username={} error={}", user, error),
+                            );
+                            return Err(ApiFailure::internal(format!(
+                                "Failed to reset user quota: {}",
+                                error
+                            )));
+                        }
+                    };
+                    shared
+                        .runtime_events
+                        .record("api.user.reset_quota.ok", format!("username={}", user));
+                    let revision = current_revision(&shared.config_path).await?;
+                    return Ok(success_response(
+                        StatusCode::OK,
+                        ResetUserQuotaResponse {
+                            username: user.to_string(),
+                            used_bytes: snapshot.used_bytes,
+                            last_reset_epoch_secs: snapshot.last_reset_epoch_secs,
+                        },
+                        revision,
+                    ));
+                }
+                if method == Method::POST
+                    && let Some(base_user) = normalized_path
+                        .strip_prefix("/v1/users/")
+                        .and_then(|path| path.strip_suffix("/rotate-secret"))
+                    && !base_user.is_empty()
+                    && !base_user.contains('/')
+                {
+                    let base_user = parse_route_username(base_user)?;
+                    if api_cfg.read_only {
+                        return Ok(error_response(
+                            request_id,
+                            ApiFailure::new(
+                                StatusCode::FORBIDDEN,
+                                "read_only",
+                                "API runs in read-only mode",
+                            ),
+                        ));
+                    }
+                    let expected_revision = parse_if_match(req.headers());
+                    let body =
+                        read_optional_json::<RotateSecretRequest>(req.into_body(), body_limit)
+                            .await?;
+                    let result = rotate_secret(
+                        base_user,
+                        body.unwrap_or_default(),
+                        expected_revision,
+                        &shared,
+                    )
+                    .await;
+                    let (mut data, revision) = match result {
+                        Ok(ok) => ok,
+                        Err(error) => {
+                            shared.runtime_events.record(
+                                "api.user.rotate_secret.failed",
+                                format!("username={} code={}", base_user, error.code),
+                            );
+                            return Err(error);
+                        }
+                    };
+                    let runtime_cfg = config_rx.borrow().clone();
+                    data.user.in_runtime =
+                        runtime_cfg.access.users.contains_key(&data.user.username);
+                    shared.runtime_events.record(
+                        "api.user.rotate_secret.ok",
+                        format!("username={}", base_user),
+                    );
+                    let status = if data.user.in_runtime {
+                        StatusCode::OK
+                    } else {
+                        StatusCode::ACCEPTED
+                    };
+                    return Ok(success_response(status, data, revision));
+                }
+                if let Some(user) = normalized_path.strip_prefix("/v1/users/")
+                    && !user.is_empty()
+                    && !user.contains('/')
+                {
+                    let user = parse_route_username(user)?;
                     if method == Method::GET {
                         let revision = current_revision(&shared.config_path).await?;
                         let disk_cfg = load_config_from_disk(&shared.config_path).await?;
@@ -535,56 +750,6 @@ async fn handle(
                         };
                         return Ok(success_response(status, response, revision));
                     }
-                    if method == Method::POST
-                        && let Some(base_user) = user.strip_suffix("/rotate-secret")
-                        && !base_user.is_empty()
-                        && !base_user.contains('/')
-                    {
-                        if api_cfg.read_only {
-                            return Ok(error_response(
-                                request_id,
-                                ApiFailure::new(
-                                    StatusCode::FORBIDDEN,
-                                    "read_only",
-                                    "API runs in read-only mode",
-                                ),
-                            ));
-                        }
-                        let expected_revision = parse_if_match(req.headers());
-                        let body =
-                            read_optional_json::<RotateSecretRequest>(req.into_body(), body_limit)
-                                .await?;
-                        let result = rotate_secret(
-                            base_user,
-                            body.unwrap_or_default(),
-                            expected_revision,
-                            &shared,
-                        )
-                        .await;
-                        let (mut data, revision) = match result {
-                            Ok(ok) => ok,
-                            Err(error) => {
-                                shared.runtime_events.record(
-                                    "api.user.rotate_secret.failed",
-                                    format!("username={} code={}", base_user, error.code),
-                                );
-                                return Err(error);
-                            }
-                        };
-                        let runtime_cfg = config_rx.borrow().clone();
-                        data.user.in_runtime =
-                            runtime_cfg.access.users.contains_key(&data.user.username);
-                        shared.runtime_events.record(
-                            "api.user.rotate_secret.ok",
-                            format!("username={}", base_user),
-                        );
-                        let status = if data.user.in_runtime {
-                            StatusCode::OK
-                        } else {
-                            StatusCode::ACCEPTED
-                        };
-                        return Ok(success_response(status, data, revision));
-                    }
                     if method == Method::POST {
                         return Ok(error_response(
                             request_id,
@@ -600,6 +765,12 @@ async fn handle(
                         ),
                     ));
                 }
+                debug!(
+                    method = method.as_str(),
+                    path = %path,
+                    normalized_path = %normalized_path,
+                    "API route not found"
+                );
                 Ok(error_response(
                     request_id,
                     ApiFailure::new(StatusCode::NOT_FOUND, "not_found", "Route not found"),

src/api/model.rs

@@ -5,6 +5,7 @@ use chrono::{DateTime, Utc};
 use hyper::StatusCode;
 use serde::{Deserialize, Serialize};
 
+use super::patch::{Patch, patch_field};
 use crate::crypto::SecureRandom;
 
 const MAX_USERNAME_LEN: usize = 64;
@@ -60,11 +61,30 @@ pub(super) struct HealthData {
     pub(super) read_only: bool,
 }
 
+#[derive(Serialize)]
+pub(super) struct HealthReadyData {
+    pub(super) ready: bool,
+    pub(super) status: &'static str,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) reason: Option<&'static str>,
+    pub(super) admission_open: bool,
+    pub(super) healthy_upstreams: usize,
+    pub(super) total_upstreams: usize,
+}
+
+#[derive(Serialize, Clone)]
+pub(super) struct ClassCount {
+    pub(super) class: String,
+    pub(super) total: u64,
+}
+
 #[derive(Serialize)]
 pub(super) struct SummaryData {
     pub(super) uptime_seconds: f64,
     pub(super) connections_total: u64,
     pub(super) connections_bad_total: u64,
+    pub(super) connections_bad_by_class: Vec<ClassCount>,
+    pub(super) handshake_failures_by_class: Vec<ClassCount>,
     pub(super) handshake_timeouts_total: u64,
     pub(super) configured_users: usize,
 }
@@ -80,6 +100,8 @@ pub(super) struct ZeroCoreData {
     pub(super) uptime_seconds: f64,
     pub(super) connections_total: u64,
     pub(super) connections_bad_total: u64,
+    pub(super) connections_bad_by_class: Vec<ClassCount>,
+    pub(super) handshake_failures_by_class: Vec<ClassCount>,
     pub(super) handshake_timeouts_total: u64,
     pub(super) accept_permit_timeout_total: u64,
     pub(super) configured_users: usize,
@@ -434,6 +456,13 @@ pub(super) struct UserLinks {
     pub(super) classic: Vec<String>,
     pub(super) secure: Vec<String>,
     pub(super) tls: Vec<String>,
+    pub(super) tls_domains: Vec<TlsDomainLink>,
+}
+
+#[derive(Serialize)]
+pub(super) struct TlsDomainLink {
+    pub(super) domain: String,
+    pub(super) link: String,
 }
 
 #[derive(Serialize)]
@@ -472,6 +501,13 @@ pub(super) struct DeleteUserResponse {
     pub(super) in_runtime: bool,
 }
 
+#[derive(Serialize)]
+pub(super) struct ResetUserQuotaResponse {
+    pub(super) username: String,
+    pub(super) used_bytes: u64,
+    pub(super) last_reset_epoch_secs: u64,
+}
+
 #[derive(Deserialize)]
 pub(super) struct CreateUserRequest {
     pub(super) username: String,
@@ -486,11 +522,16 @@ pub(super) struct CreateUserRequest {
 #[derive(Deserialize)]
 pub(super) struct PatchUserRequest {
     pub(super) secret: Option<String>,
-    pub(super) user_ad_tag: Option<String>,
-    pub(super) max_tcp_conns: Option<usize>,
-    pub(super) expiration_rfc3339: Option<String>,
-    pub(super) data_quota_bytes: Option<u64>,
-    pub(super) max_unique_ips: Option<usize>,
+    #[serde(default, deserialize_with = "patch_field")]
+    pub(super) user_ad_tag: Patch<String>,
+    #[serde(default, deserialize_with = "patch_field")]
+    pub(super) max_tcp_conns: Patch<usize>,
+    #[serde(default, deserialize_with = "patch_field")]
+    pub(super) expiration_rfc3339: Patch<String>,
+    #[serde(default, deserialize_with = "patch_field")]
+    pub(super) data_quota_bytes: Patch<u64>,
+    #[serde(default, deserialize_with = "patch_field")]
+    pub(super) max_unique_ips: Patch<usize>,
 }
 
 #[derive(Default, Deserialize)]
@@ -509,6 +550,20 @@ pub(super) fn parse_optional_expiration(
     Ok(Some(parsed.with_timezone(&Utc)))
 }
 
+pub(super) fn parse_patch_expiration(
+    value: &Patch<String>,
+) -> Result<Patch<DateTime<Utc>>, ApiFailure> {
+    match value {
+        Patch::Unchanged => Ok(Patch::Unchanged),
+        Patch::Remove => Ok(Patch::Remove),
+        Patch::Set(raw) => {
+            let parsed = DateTime::parse_from_rfc3339(raw)
+                .map_err(|_| ApiFailure::bad_request("expiration_rfc3339 must be valid RFC3339"))?;
+            Ok(Patch::Set(parsed.with_timezone(&Utc)))
+        }
+    }
+}
+
 pub(super) fn is_valid_user_secret(secret: &str) -> bool {
     secret.len() == 32 && secret.chars().all(|c| c.is_ascii_hexdigit())
 }

src/api/patch.rs

@@ -0,0 +1,130 @@
+use serde::Deserialize;
+
+/// Three-state field for JSON Merge Patch semantics on the `PATCH /v1/users/{user}`
+/// endpoint.
+///
+/// `Unchanged` is produced when the JSON body omits the field entirely and tells the
+/// handler to leave the corresponding configuration entry untouched. `Remove` is
+/// produced when the JSON body sets the field to `null` and instructs the handler to
+/// drop the entry from the corresponding access HashMap. `Set` carries an explicit
+/// new value, including zero, which is preserved verbatim in the configuration.
+#[derive(Debug)]
+pub(super) enum Patch<T> {
+    Unchanged,
+    Remove,
+    Set(T),
+}
+
+impl<T> Default for Patch<T> {
+    fn default() -> Self {
+        Self::Unchanged
+    }
+}
+
+/// Serde deserializer adapter for fields that follow JSON Merge Patch semantics.
+///
+/// Pair this with `#[serde(default, deserialize_with = "patch_field")]` on a
+/// `Patch<T>` field. An omitted field falls back to `Patch::Unchanged` via
+/// `Default`; an explicit JSON `null` becomes `Patch::Remove`; any other value
+/// becomes `Patch::Set(v)`.
+pub(super) fn patch_field<'de, D, T>(deserializer: D) -> Result<Patch<T>, D::Error>
+where
+    D: serde::Deserializer<'de>,
+    T: serde::Deserialize<'de>,
+{
+    Option::<T>::deserialize(deserializer).map(|opt| match opt {
+        Some(value) => Patch::Set(value),
+        None => Patch::Remove,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::api::model::{PatchUserRequest, parse_patch_expiration};
+    use chrono::{TimeZone, Utc};
+    use serde::Deserialize;
+
+    #[derive(Deserialize)]
+    struct Holder {
+        #[serde(default, deserialize_with = "patch_field")]
+        value: Patch<u64>,
+    }
+
+    fn parse(json: &str) -> Holder {
+        serde_json::from_str(json).expect("valid json")
+    }
+
+    #[test]
+    fn omitted_field_yields_unchanged() {
+        let h = parse("{}");
+        assert!(matches!(h.value, Patch::Unchanged));
+    }
+
+    #[test]
+    fn explicit_null_yields_remove() {
+        let h = parse(r#"{"value": null}"#);
+        assert!(matches!(h.value, Patch::Remove));
+    }
+
+    #[test]
+    fn explicit_value_yields_set() {
+        let h = parse(r#"{"value": 42}"#);
+        assert!(matches!(h.value, Patch::Set(42)));
+    }
+
+    #[test]
+    fn explicit_zero_yields_set_zero() {
+        let h = parse(r#"{"value": 0}"#);
+        assert!(matches!(h.value, Patch::Set(0)));
+    }
+
+    #[test]
+    fn parse_patch_expiration_passes_unchanged_and_remove_through() {
+        assert!(matches!(
+            parse_patch_expiration(&Patch::Unchanged),
+            Ok(Patch::Unchanged)
+        ));
+        assert!(matches!(
+            parse_patch_expiration(&Patch::Remove),
+            Ok(Patch::Remove)
+        ));
+    }
+
+    #[test]
+    fn parse_patch_expiration_parses_set_value() {
+        let parsed =
+            parse_patch_expiration(&Patch::Set("2030-01-02T03:04:05Z".into())).expect("valid");
+        match parsed {
+            Patch::Set(dt) => {
+                assert_eq!(dt, Utc.with_ymd_and_hms(2030, 1, 2, 3, 4, 5).unwrap());
+            }
+            other => panic!("expected Patch::Set, got {:?}", other),
+        }
+    }
+
+    #[test]
+    fn parse_patch_expiration_rejects_invalid_set_value() {
+        assert!(parse_patch_expiration(&Patch::Set("not-a-date".into())).is_err());
+    }
+
+    #[test]
+    fn patch_user_request_deserializes_mixed_states() {
+        let raw = r#"{
+            "secret": "00112233445566778899aabbccddeeff",
+            "max_tcp_conns": 0,
+            "max_unique_ips": null,
+            "data_quota_bytes": 1024
+        }"#;
+        let req: PatchUserRequest = serde_json::from_str(raw).expect("valid json");
+        assert_eq!(
+            req.secret.as_deref(),
+            Some("00112233445566778899aabbccddeeff")
+        );
+        assert!(matches!(req.max_tcp_conns, Patch::Set(0)));
+        assert!(matches!(req.max_unique_ips, Patch::Remove));
+        assert!(matches!(req.data_quota_bytes, Patch::Set(1024)));
+        assert!(matches!(req.expiration_rfc3339, Patch::Unchanged));
+        assert!(matches!(req.user_ad_tag, Patch::Unchanged));
+    }
+}

src/api/runtime_stats.rs

@@ -7,8 +7,8 @@ use crate::transport::upstream::IpPreference;
 
 use super::ApiShared;
 use super::model::{
-    DcEndpointWriters, DcStatus, DcStatusData, MeWriterStatus, MeWritersData, MeWritersSummary,
-    MinimalAllData, MinimalAllPayload, MinimalDcPathData, MinimalMeRuntimeData,
+    ClassCount, DcEndpointWriters, DcStatus, DcStatusData, MeWriterStatus, MeWritersData,
+    MeWritersSummary, MinimalAllData, MinimalAllPayload, MinimalDcPathData, MinimalMeRuntimeData,
     MinimalQuarantineData, UpstreamDcStatus, UpstreamStatus, UpstreamSummaryData, UpstreamsData,
     ZeroAllData, ZeroCodeCount, ZeroCoreData, ZeroDesyncData, ZeroMiddleProxyData, ZeroPoolData,
     ZeroUpstreamData,
@@ -26,6 +26,16 @@ pub(crate) struct MinimalCacheEntry {
 
 pub(super) fn build_zero_all_data(stats: &Stats, configured_users: usize) -> ZeroAllData {
     let telemetry = stats.telemetry_policy();
+    let bad_connection_classes = stats
+        .get_connects_bad_class_counts()
+        .into_iter()
+        .map(|(class, total)| ClassCount { class, total })
+        .collect();
+    let handshake_failure_classes = stats
+        .get_handshake_failure_class_counts()
+        .into_iter()
+        .map(|(class, total)| ClassCount { class, total })
+        .collect();
     let handshake_error_codes = stats
         .get_me_handshake_error_code_counts()
         .into_iter()
@@ -38,6 +48,8 @@ pub(super) fn build_zero_all_data(stats: &Stats, configured_users: usize) -> Zer
             uptime_seconds: stats.uptime_secs(),
             connections_total: stats.get_connects_all(),
             connections_bad_total: stats.get_connects_bad(),
+            connections_bad_by_class: bad_connection_classes,
+            handshake_failures_by_class: handshake_failure_classes,
             handshake_timeouts_total: stats.get_handshake_timeouts(),
             accept_permit_timeout_total: stats.get_accept_permit_timeout_total(),
             configured_users,

src/api/users.rs

@@ -8,14 +8,15 @@ use crate::stats::Stats;
 
 use super::ApiShared;
 use super::config_store::{
-    AccessSection, ensure_expected_revision, load_config_from_disk, save_access_sections_to_disk,
-    save_config_to_disk,
+    AccessSection, current_revision, ensure_expected_revision, load_config_from_disk,
+    save_access_sections_to_disk,
 };
 use super::model::{
     ApiFailure, CreateUserRequest, CreateUserResponse, PatchUserRequest, RotateSecretRequest,
-    UserInfo, UserLinks, is_valid_ad_tag, is_valid_user_secret, is_valid_username,
-    parse_optional_expiration, random_user_secret,
+    TlsDomainLink, UserInfo, UserLinks, is_valid_ad_tag, is_valid_user_secret, is_valid_username,
+    parse_optional_expiration, parse_patch_expiration, random_user_secret,
 };
+use super::patch::Patch;
 
 pub(super) async fn create_user(
     body: CreateUserRequest,
@@ -175,6 +176,13 @@ pub(super) async fn patch_user(
     expected_revision: Option<String>,
     shared: &ApiShared,
 ) -> Result<(UserInfo, String), ApiFailure> {
+    let touches_users = body.secret.is_some();
+    let touches_user_ad_tags = !matches!(&body.user_ad_tag, Patch::Unchanged);
+    let touches_user_max_tcp_conns = !matches!(&body.max_tcp_conns, Patch::Unchanged);
+    let touches_user_expirations = !matches!(&body.expiration_rfc3339, Patch::Unchanged);
+    let touches_user_data_quota = !matches!(&body.data_quota_bytes, Patch::Unchanged);
+    let touches_user_max_unique_ips = !matches!(&body.max_unique_ips, Patch::Unchanged);
+
     if let Some(secret) = body.secret.as_ref()
         && !is_valid_user_secret(secret)
     {
@@ -182,14 +190,14 @@ pub(super) async fn patch_user(
             "secret must be exactly 32 hex characters",
         ));
     }
-    if let Some(ad_tag) = body.user_ad_tag.as_ref()
+    if let Patch::Set(ad_tag) = &body.user_ad_tag
         && !is_valid_ad_tag(ad_tag)
     {
         return Err(ApiFailure::bad_request(
             "user_ad_tag must be exactly 32 hex characters",
         ));
     }
-    let expiration = parse_optional_expiration(body.expiration_rfc3339.as_deref())?;
+    let expiration = parse_patch_expiration(&body.expiration_rfc3339)?;
     let _guard = shared.mutation_lock.lock().await;
     let mut cfg = load_config_from_disk(&shared.config_path).await?;
     ensure_expected_revision(&shared.config_path, expected_revision.as_deref()).await?;
@@ -205,38 +213,95 @@ pub(super) async fn patch_user(
     if let Some(secret) = body.secret {
         cfg.access.users.insert(user.to_string(), secret);
     }
-    if let Some(ad_tag) = body.user_ad_tag {
-        cfg.access.user_ad_tags.insert(user.to_string(), ad_tag);
+    match body.user_ad_tag {
+        Patch::Unchanged => {}
+        Patch::Remove => {
+            cfg.access.user_ad_tags.remove(user);
+        }
+        Patch::Set(ad_tag) => {
+            cfg.access.user_ad_tags.insert(user.to_string(), ad_tag);
+        }
     }
-    if let Some(limit) = body.max_tcp_conns {
-        cfg.access
-            .user_max_tcp_conns
-            .insert(user.to_string(), limit);
+    match body.max_tcp_conns {
+        Patch::Unchanged => {}
+        Patch::Remove => {
+            cfg.access.user_max_tcp_conns.remove(user);
+        }
+        Patch::Set(limit) => {
+            cfg.access
+                .user_max_tcp_conns
+                .insert(user.to_string(), limit);
+        }
     }
-    if let Some(expiration) = expiration {
-        cfg.access
-            .user_expirations
-            .insert(user.to_string(), expiration);
+    match expiration {
+        Patch::Unchanged => {}
+        Patch::Remove => {
+            cfg.access.user_expirations.remove(user);
+        }
+        Patch::Set(expiration) => {
+            cfg.access
+                .user_expirations
+                .insert(user.to_string(), expiration);
+        }
     }
-    if let Some(quota) = body.data_quota_bytes {
-        cfg.access.user_data_quota.insert(user.to_string(), quota);
-    }
-
-    let mut updated_limit = None;
-    if let Some(limit) = body.max_unique_ips {
-        cfg.access
-            .user_max_unique_ips
-            .insert(user.to_string(), limit);
-        updated_limit = Some(limit);
+    match body.data_quota_bytes {
+        Patch::Unchanged => {}
+        Patch::Remove => {
+            cfg.access.user_data_quota.remove(user);
+        }
+        Patch::Set(quota) => {
+            cfg.access.user_data_quota.insert(user.to_string(), quota);
+        }
     }
+    // Capture how the per-user IP limit changed, so the in-memory ip_tracker
+    // can be synced (set or removed) after the config is persisted.
+    let max_unique_ips_change = match body.max_unique_ips {
+        Patch::Unchanged => None,
+        Patch::Remove => {
+            cfg.access.user_max_unique_ips.remove(user);
+            Some(None)
+        }
+        Patch::Set(limit) => {
+            cfg.access
+                .user_max_unique_ips
+                .insert(user.to_string(), limit);
+            Some(Some(limit))
+        }
+    };
 
     cfg.validate()
         .map_err(|e| ApiFailure::bad_request(format!("config validation failed: {}", e)))?;
 
-    let revision = save_config_to_disk(&shared.config_path, &cfg).await?;
+    let mut touched_sections = Vec::new();
+    if touches_users {
+        touched_sections.push(AccessSection::Users);
+    }
+    if touches_user_ad_tags {
+        touched_sections.push(AccessSection::UserAdTags);
+    }
+    if touches_user_max_tcp_conns {
+        touched_sections.push(AccessSection::UserMaxTcpConns);
+    }
+    if touches_user_expirations {
+        touched_sections.push(AccessSection::UserExpirations);
+    }
+    if touches_user_data_quota {
+        touched_sections.push(AccessSection::UserDataQuota);
+    }
+    if touches_user_max_unique_ips {
+        touched_sections.push(AccessSection::UserMaxUniqueIps);
+    }
+
+    let revision = if touched_sections.is_empty() {
+        current_revision(&shared.config_path).await?
+    } else {
+        save_access_sections_to_disk(&shared.config_path, &cfg, &touched_sections).await?
+    };
     drop(_guard);
-    if let Some(limit) = updated_limit {
-        shared.ip_tracker.set_user_limit(user, limit).await;
+    match max_unique_ips_change {
+        Some(Some(limit)) => shared.ip_tracker.set_user_limit(user, limit).await,
+        Some(None) => shared.ip_tracker.remove_user_limit(user).await,
+        None => {}
     }
     let (detected_ip_v4, detected_ip_v6) = shared.detected_link_ips();
     let users = users_from_config(
@@ -400,11 +465,7 @@ pub(super) async fn users_from_config(
             .map(|secret| {
                 build_user_links(cfg, secret, startup_detected_ip_v4, startup_detected_ip_v6)
             })
-            .unwrap_or(UserLinks {
-                classic: Vec::new(),
-                secure: Vec::new(),
-                tls: Vec::new(),
-            });
+            .unwrap_or_else(empty_user_links);
         users.push(UserInfo {
             in_runtime: runtime_cfg
                 .map(|runtime| runtime.access.users.contains_key(&username))
@@ -445,6 +506,15 @@ pub(super) async fn users_from_config(
     users
 }
 
+fn empty_user_links() -> UserLinks {
+    UserLinks {
+        classic: Vec::new(),
+        secure: Vec::new(),
+        tls: Vec::new(),
+        tls_domains: Vec::new(),
+    }
+}
+
 fn build_user_links(
     cfg: &ProxyConfig,
     secret: &str,
@@ -452,12 +522,18 @@ fn build_user_links(
     startup_detected_ip_v6: Option<IpAddr>,
 ) -> UserLinks {
     let hosts = resolve_link_hosts(cfg, startup_detected_ip_v4, startup_detected_ip_v6);
-    let port = cfg.general.links.public_port.unwrap_or(cfg.server.port);
+    let port = cfg
+        .general
+        .links
+        .public_port
+        .unwrap_or(resolve_default_link_port(cfg));
     let tls_domains = resolve_tls_domains(cfg);
+    let extra_tls_domains = resolve_extra_tls_domains(cfg);
 
     let mut classic = Vec::new();
     let mut secure = Vec::new();
     let mut tls = Vec::new();
+    let mut tls_domain_links = Vec::new();
 
     for host in &hosts {
         if cfg.general.modes.classic {
@@ -480,6 +556,17 @@ fn build_user_links(
                     host, port, secret, domain_hex
                 ));
             }
+            for domain in &extra_tls_domains {
+                let domain_hex = hex::encode(domain);
+                let link = format!(
+                    "tg://proxy?server={}&port={}&secret=ee{}{}",
+                    host, port, secret, domain_hex
+                );
+                tls_domain_links.push(TlsDomainLink {
+                    domain: (*domain).to_string(),
+                    link,
+                });
+            }
         }
     }
 
@@ -487,9 +574,18 @@ fn build_user_links(
         classic,
         secure,
         tls,
+        tls_domains: tls_domain_links,
     }
 }
 
+fn resolve_default_link_port(cfg: &ProxyConfig) -> u16 {
+    cfg.server
+        .listeners
+        .first()
+        .and_then(|listener| listener.port)
+        .unwrap_or(cfg.server.port)
+}
+
 fn resolve_link_hosts(
     cfg: &ProxyConfig,
     startup_detected_ip_v4: Option<IpAddr>,
@@ -595,6 +691,19 @@ fn resolve_tls_domains(cfg: &ProxyConfig) -> Vec<&str> {
     domains
 }
 
+fn resolve_extra_tls_domains(cfg: &ProxyConfig) -> Vec<&str> {
+    let mut domains = Vec::with_capacity(cfg.censorship.tls_domains.len());
+    let primary = cfg.censorship.tls_domain.as_str();
+    for domain in &cfg.censorship.tls_domains {
+        let value = domain.as_str();
+        if value.is_empty() || value == primary || domains.contains(&value) {
+            continue;
+        }
+        domains.push(value);
+    }
+    domains
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -684,4 +793,80 @@ mod tests {
         assert!(alice.in_runtime);
         assert!(!bob.in_runtime);
     }
+
+    #[tokio::test]
+    async fn users_from_config_returns_tls_link_for_each_tls_domain() {
+        let mut cfg = ProxyConfig::default();
+        cfg.access.users.insert(
+            "alice".to_string(),
+            "0123456789abcdef0123456789abcdef".to_string(),
+        );
+        cfg.general.modes.classic = false;
+        cfg.general.modes.secure = false;
+        cfg.general.modes.tls = true;
+        cfg.general.links.public_host = Some("proxy.example.net".to_string());
+        cfg.general.links.public_port = Some(443);
+        cfg.censorship.tls_domain = "front-a.example.com".to_string();
+        cfg.censorship.tls_domains = vec![
+            "front-b.example.com".to_string(),
+            "front-c.example.com".to_string(),
+            "front-b.example.com".to_string(),
+            "front-a.example.com".to_string(),
+        ];
+
+        let stats = Stats::new();
+        let tracker = UserIpTracker::new();
+        let users = users_from_config(&cfg, &stats, &tracker, None, None, None).await;
+        let alice = users
+            .iter()
+            .find(|entry| entry.username == "alice")
+            .expect("alice must be present");
+
+        assert_eq!(alice.links.tls.len(), 3);
+        assert!(
+            alice
+                .links
+                .tls
+                .iter()
+                .any(|link| link.ends_with(&hex::encode("front-a.example.com")))
+        );
+        assert!(
+            alice
+                .links
+                .tls
+                .iter()
+                .any(|link| link.ends_with(&hex::encode("front-b.example.com")))
+        );
+        assert!(
+            alice
+                .links
+                .tls
+                .iter()
+                .any(|link| link.ends_with(&hex::encode("front-c.example.com")))
+        );
+        assert_eq!(alice.links.tls_domains.len(), 2);
+        assert!(
+            alice
+                .links
+                .tls_domains
+                .iter()
+                .any(|entry| entry.domain == "front-b.example.com"
+                    && entry.link.ends_with(&hex::encode("front-b.example.com")))
+        );
+        assert!(
+            alice
+                .links
+                .tls_domains
+                .iter()
+                .any(|entry| entry.domain == "front-c.example.com"
+                    && entry.link.ends_with(&hex::encode("front-c.example.com")))
+        );
+        assert!(
+            !alice
+                .links
+                .tls_domains
+                .iter()
+                .any(|entry| entry.domain == "front-a.example.com")
+        );
+    }
 }

src/cli.rs

@@ -6,12 +6,15 @@
 //! - `reload [--pid-file PATH]` - Reload configuration (SIGHUP)
 //! - `status [--pid-file PATH]` - Check daemon status
 //! - `run [OPTIONS] [config.toml]` - Run in foreground (default behavior)
+//! - `healthcheck [OPTIONS] [config.toml]` - Run control-plane health probe
 
 use rand::RngExt;
 use std::fs;
 use std::path::{Path, PathBuf};
 use std::process::Command;
 
+use crate::healthcheck::{self, HealthcheckMode};
+
 #[cfg(unix)]
 use crate::daemon::{self, DEFAULT_PID_FILE, DaemonOptions};
 
@@ -28,6 +31,8 @@ pub enum Subcommand {
     Reload,
     /// Check daemon status (`status` subcommand).
     Status,
+    /// Run health probe and exit with status code.
+    Healthcheck,
     /// Fire-and-forget setup (`--init`).
     Init,
 }
@@ -38,6 +43,8 @@ pub struct ParsedCommand {
     pub subcommand: Subcommand,
     pub pid_file: PathBuf,
     pub config_path: String,
+    pub healthcheck_mode: HealthcheckMode,
+    pub healthcheck_mode_invalid: Option<String>,
     #[cfg(unix)]
     pub daemon_opts: DaemonOptions,
     pub init_opts: Option<InitOptions>,
@@ -52,6 +59,8 @@ impl Default for ParsedCommand {
             #[cfg(not(unix))]
             pid_file: PathBuf::from("/var/run/telemt.pid"),
             config_path: "config.toml".to_string(),
+            healthcheck_mode: HealthcheckMode::Liveness,
+            healthcheck_mode_invalid: None,
             #[cfg(unix)]
             daemon_opts: DaemonOptions::default(),
             init_opts: None,
@@ -91,6 +100,9 @@ pub fn parse_command(args: &[String]) -> ParsedCommand {
             "status" => {
                 cmd.subcommand = Subcommand::Status;
             }
+            "healthcheck" => {
+                cmd.subcommand = Subcommand::Healthcheck;
+            }
             "run" => {
                 cmd.subcommand = Subcommand::Run;
                 #[cfg(unix)]
@@ -113,7 +125,35 @@ pub fn parse_command(args: &[String]) -> ParsedCommand {
     while i < args.len() {
         match args[i].as_str() {
             // Skip subcommand names
-            "start" | "stop" | "reload" | "status" | "run" => {}
+            "start" | "stop" | "reload" | "status" | "run" | "healthcheck" => {}
+            "--mode" => {
+                i += 1;
+                if i < args.len() {
+                    match HealthcheckMode::from_cli_arg(&args[i]) {
+                        Some(mode) => {
+                            cmd.healthcheck_mode = mode;
+                            cmd.healthcheck_mode_invalid = None;
+                        }
+                        None => {
+                            cmd.healthcheck_mode_invalid = Some(args[i].clone());
+                        }
+                    }
+                } else {
+                    cmd.healthcheck_mode_invalid = Some(String::new());
+                }
+            }
+            s if s.starts_with("--mode=") => {
+                let raw = s.trim_start_matches("--mode=");
+                match HealthcheckMode::from_cli_arg(raw) {
+                    Some(mode) => {
+                        cmd.healthcheck_mode = mode;
+                        cmd.healthcheck_mode_invalid = None;
+                    }
+                    None => {
+                        cmd.healthcheck_mode_invalid = Some(raw.to_string());
+                    }
+                }
+            }
             // PID file option (for stop/reload/status)
             "--pid-file" => {
                 i += 1;
@@ -152,6 +192,20 @@ pub fn execute_subcommand(cmd: &ParsedCommand) -> Option<i32> {
         Subcommand::Stop => Some(cmd_stop(&cmd.pid_file)),
         Subcommand::Reload => Some(cmd_reload(&cmd.pid_file)),
         Subcommand::Status => Some(cmd_status(&cmd.pid_file)),
+        Subcommand::Healthcheck => {
+            if let Some(invalid_mode) = cmd.healthcheck_mode_invalid.as_ref() {
+                if invalid_mode.is_empty() {
+                    eprintln!("[telemt] Missing value for --mode (supported: liveness, ready)");
+                } else {
+                    eprintln!(
+                        "[telemt] Invalid --mode value '{invalid_mode}' (supported: liveness, ready)"
+                    );
+                }
+                Some(2)
+            } else {
+                Some(healthcheck::run(&cmd.config_path, cmd.healthcheck_mode))
+            }
+        }
         Subcommand::Init => {
             if let Some(opts) = cmd.init_opts.clone() {
                 match run_init(opts) {
@@ -177,6 +231,20 @@ pub fn execute_subcommand(cmd: &ParsedCommand) -> Option<i32> {
             eprintln!("[telemt] Subcommand not supported on this platform");
             Some(1)
         }
+        Subcommand::Healthcheck => {
+            if let Some(invalid_mode) = cmd.healthcheck_mode_invalid.as_ref() {
+                if invalid_mode.is_empty() {
+                    eprintln!("[telemt] Missing value for --mode (supported: liveness, ready)");
+                } else {
+                    eprintln!(
+                        "[telemt] Invalid --mode value '{invalid_mode}' (supported: liveness, ready)"
+                    );
+                }
+                Some(2)
+            } else {
+                Some(healthcheck::run(&cmd.config_path, cmd.healthcheck_mode))
+            }
+        }
         Subcommand::Init => {
             if let Some(opts) = cmd.init_opts.clone() {
                 match run_init(opts) {
@@ -598,16 +666,17 @@ secure = false
 tls = true
 
 [server]
-port = {port}
 listen_addr_ipv4 = "0.0.0.0"
 listen_addr_ipv6 = "::"
 
 [[server.listeners]]
 ip = "0.0.0.0"
+port = {port}
 # reuse_allow = false # Set true only when intentionally running multiple telemt instances on same port
 
 [[server.listeners]]
 ip = "::"
+port = {port}
 
 [timeouts]
 client_first_byte_idle_secs = 300
@@ -620,6 +689,7 @@ tls_domain = "{domain}"
 mask = true
 mask_port = 443
 fake_cert_len = 2048
+serverhello_compact = false
 tls_full_cert_ttl_secs = 90
 
 [access]

src/config/defaults.rs

@@ -21,6 +21,8 @@ const DEFAULT_ME_ADAPTIVE_FLOOR_MAX_ACTIVE_WRITERS_PER_CORE: u16 = 64;
 const DEFAULT_ME_ADAPTIVE_FLOOR_MAX_WARM_WRITERS_PER_CORE: u16 = 64;
 const DEFAULT_ME_ADAPTIVE_FLOOR_MAX_ACTIVE_WRITERS_GLOBAL: u32 = 256;
 const DEFAULT_ME_ADAPTIVE_FLOOR_MAX_WARM_WRITERS_GLOBAL: u32 = 256;
+const DEFAULT_ME_ROUTE_BACKPRESSURE_ENABLED: bool = false;
+const DEFAULT_ME_ROUTE_FAIRSHARE_ENABLED: bool = false;
 const DEFAULT_ME_WRITER_CMD_CHANNEL_CAPACITY: usize = 4096;
 const DEFAULT_ME_ROUTE_CHANNEL_CAPACITY: usize = 768;
 const DEFAULT_ME_C2ME_CHANNEL_CAPACITY: usize = 1024;
@@ -302,7 +304,7 @@ pub(crate) fn default_me2dc_fallback() -> bool {
 }
 
 pub(crate) fn default_me2dc_fast() -> bool {
-    false
+    true
 }
 
 pub(crate) fn default_keepalive_interval() -> u64 {
@@ -529,6 +531,14 @@ pub(crate) fn default_me_route_backpressure_base_timeout_ms() -> u64 {
     25
 }
 
+pub(crate) fn default_me_route_backpressure_enabled() -> bool {
+    DEFAULT_ME_ROUTE_BACKPRESSURE_ENABLED
+}
+
+pub(crate) fn default_me_route_fairshare_enabled() -> bool {
+    DEFAULT_ME_ROUTE_FAIRSHARE_ENABLED
+}
+
 pub(crate) fn default_me_route_backpressure_high_timeout_ms() -> u64 {
     120
 }
@@ -558,13 +568,17 @@ pub(crate) fn default_beobachten_flush_secs() -> u64 {
 }
 
 pub(crate) fn default_beobachten_file() -> String {
-    "cache/beobachten.txt".to_string()
+    "beobachten.txt".to_string()
 }
 
 pub(crate) fn default_tls_new_session_tickets() -> u8 {
     0
 }
 
+pub(crate) fn default_serverhello_compact() -> bool {
+    false
+}
+
 pub(crate) fn default_tls_full_cert_ttl_secs() -> u64 {
     90
 }
@@ -615,6 +629,26 @@ pub(crate) fn default_mask_relay_max_bytes() -> usize {
     32 * 1024
 }
 
+#[cfg(not(test))]
+pub(crate) fn default_mask_relay_timeout_ms() -> u64 {
+    60_000
+}
+
+#[cfg(test)]
+pub(crate) fn default_mask_relay_timeout_ms() -> u64 {
+    200
+}
+
+#[cfg(not(test))]
+pub(crate) fn default_mask_relay_idle_timeout_ms() -> u64 {
+    5_000
+}
+
+#[cfg(test)]
+pub(crate) fn default_mask_relay_idle_timeout_ms() -> u64 {
+    100
+}
+
 pub(crate) fn default_mask_classifier_prefetch_timeout_ms() -> u64 {
     5
 }

src/config/hot_reload.rs

@@ -17,8 +17,9 @@
 //! | `network` | `dns_overrides`                | Applied immediately                            |
 //! | `access`  | All user/quota fields          | Effective immediately                          |
 //!
-//! Fields that require re-binding sockets (`server.port`, `censorship.*`,
-//! `network.*`, `use_middle_proxy`) are **not** applied; a warning is emitted.
+//! Fields that require re-binding sockets (`server.listeners`, legacy
+//! `server.port`, `censorship.*`, `network.*`, `use_middle_proxy`) are **not**
+//! applied; a warning is emitted.
 //! Non-hot changes are never mixed into the runtime config snapshot.
 
 use std::collections::BTreeSet;
@@ -85,6 +86,8 @@ pub struct HotFields {
     pub telemetry_user_enabled: bool,
     pub telemetry_me_level: MeTelemetryLevel,
     pub me_socks_kdf_policy: MeSocksKdfPolicy,
+    pub me_route_backpressure_enabled: bool,
+    pub me_route_fairshare_enabled: bool,
     pub me_floor_mode: MeFloorMode,
     pub me_adaptive_floor_idle_secs: u64,
     pub me_adaptive_floor_min_writers_single_endpoint: u8,
@@ -120,6 +123,9 @@ pub struct HotFields {
     pub user_max_tcp_conns_global_each: usize,
     pub user_expirations: std::collections::HashMap<String, chrono::DateTime<chrono::Utc>>,
     pub user_data_quota: std::collections::HashMap<String, u64>,
+    pub user_rate_limits: std::collections::HashMap<String, crate::config::RateLimitBps>,
+    pub cidr_rate_limits:
+        std::collections::HashMap<ipnetwork::IpNetwork, crate::config::RateLimitBps>,
     pub user_max_unique_ips: std::collections::HashMap<String, usize>,
     pub user_max_unique_ips_global_each: usize,
     pub user_max_unique_ips_mode: crate::config::UserMaxUniqueIpsMode,
@@ -183,6 +189,8 @@ impl HotFields {
             telemetry_user_enabled: cfg.general.telemetry.user_enabled,
             telemetry_me_level: cfg.general.telemetry.me_level,
             me_socks_kdf_policy: cfg.general.me_socks_kdf_policy,
+            me_route_backpressure_enabled: cfg.general.me_route_backpressure_enabled,
+            me_route_fairshare_enabled: cfg.general.me_route_fairshare_enabled,
             me_floor_mode: cfg.general.me_floor_mode,
             me_adaptive_floor_idle_secs: cfg.general.me_adaptive_floor_idle_secs,
             me_adaptive_floor_min_writers_single_endpoint: cfg
@@ -244,6 +252,8 @@ impl HotFields {
             user_max_tcp_conns_global_each: cfg.access.user_max_tcp_conns_global_each,
             user_expirations: cfg.access.user_expirations.clone(),
             user_data_quota: cfg.access.user_data_quota.clone(),
+            user_rate_limits: cfg.access.user_rate_limits.clone(),
+            cidr_rate_limits: cfg.access.cidr_rate_limits.clone(),
             user_max_unique_ips: cfg.access.user_max_unique_ips.clone(),
             user_max_unique_ips_global_each: cfg.access.user_max_unique_ips_global_each,
             user_max_unique_ips_mode: cfg.access.user_max_unique_ips_mode,
@@ -299,6 +309,7 @@ fn listeners_equal(
     }
     lhs.iter().zip(rhs.iter()).all(|(a, b)| {
         a.ip == b.ip
+            && a.port == b.port
             && a.announce == b.announce
             && a.announce_ip == b.announce_ip
             && a.proxy_protocol == b.proxy_protocol
@@ -306,6 +317,14 @@ fn listeners_equal(
     })
 }
 
+fn resolve_default_link_port(cfg: &ProxyConfig) -> u16 {
+    cfg.server
+        .listeners
+        .first()
+        .and_then(|listener| listener.port)
+        .unwrap_or(cfg.server.port)
+}
+
 #[derive(Debug, Clone, Default, PartialEq, Eq)]
 struct WatchManifest {
     files: BTreeSet<PathBuf>,
@@ -514,6 +533,8 @@ fn overlay_hot_fields(old: &ProxyConfig, new: &ProxyConfig) -> ProxyConfig {
         new.general.me_route_backpressure_high_timeout_ms;
     cfg.general.me_route_backpressure_high_watermark_pct =
         new.general.me_route_backpressure_high_watermark_pct;
+    cfg.general.me_route_backpressure_enabled = new.general.me_route_backpressure_enabled;
+    cfg.general.me_route_fairshare_enabled = new.general.me_route_fairshare_enabled;
     cfg.general.me_reader_route_data_wait_ms = new.general.me_reader_route_data_wait_ms;
     cfg.general.me_d2c_flush_batch_max_frames = new.general.me_d2c_flush_batch_max_frames;
     cfg.general.me_d2c_flush_batch_max_bytes = new.general.me_d2c_flush_batch_max_bytes;
@@ -535,11 +556,17 @@ fn overlay_hot_fields(old: &ProxyConfig, new: &ProxyConfig) -> ProxyConfig {
     cfg.access.user_max_tcp_conns_global_each = new.access.user_max_tcp_conns_global_each;
     cfg.access.user_expirations = new.access.user_expirations.clone();
     cfg.access.user_data_quota = new.access.user_data_quota.clone();
+    cfg.access.user_rate_limits = new.access.user_rate_limits.clone();
+    cfg.access.cidr_rate_limits = new.access.cidr_rate_limits.clone();
     cfg.access.user_max_unique_ips = new.access.user_max_unique_ips.clone();
     cfg.access.user_max_unique_ips_global_each = new.access.user_max_unique_ips_global_each;
     cfg.access.user_max_unique_ips_mode = new.access.user_max_unique_ips_mode;
     cfg.access.user_max_unique_ips_window_secs = new.access.user_max_unique_ips_window_secs;
 
+    if cfg.rebuild_runtime_user_auth().is_err() {
+        cfg.runtime_user_auth = None;
+    }
+
     cfg
 }
 
@@ -556,6 +583,7 @@ fn warn_non_hot_changes(old: &ProxyConfig, new: &ProxyConfig, non_hot_changed: b
     if old.server.api.enabled != new.server.api.enabled
         || old.server.api.listen != new.server.api.listen
         || old.server.api.whitelist != new.server.api.whitelist
+        || old.server.api.gray_action != new.server.api.gray_action
         || old.server.api.auth_header != new.server.api.auth_header
         || old.server.api.request_body_limit_bytes != new.server.api.request_body_limit_bytes
         || old.server.api.minimal_runtime_enabled != new.server.api.minimal_runtime_enabled
@@ -596,6 +624,7 @@ fn warn_non_hot_changes(old: &ProxyConfig, new: &ProxyConfig, non_hot_changed: b
         || old.censorship.server_hello_delay_min_ms != new.censorship.server_hello_delay_min_ms
         || old.censorship.server_hello_delay_max_ms != new.censorship.server_hello_delay_max_ms
         || old.censorship.tls_new_session_tickets != new.censorship.tls_new_session_tickets
+        || old.censorship.serverhello_compact != new.censorship.serverhello_compact
         || old.censorship.tls_full_cert_ttl_secs != new.censorship.tls_full_cert_ttl_secs
         || old.censorship.alpn_enforce != new.censorship.alpn_enforce
         || old.censorship.mask_proxy_protocol != new.censorship.mask_proxy_protocol
@@ -607,6 +636,8 @@ fn warn_non_hot_changes(old: &ProxyConfig, new: &ProxyConfig, non_hot_changed: b
         || old.censorship.mask_shape_above_cap_blur_max_bytes
             != new.censorship.mask_shape_above_cap_blur_max_bytes
         || old.censorship.mask_relay_max_bytes != new.censorship.mask_relay_max_bytes
+        || old.censorship.mask_relay_timeout_ms != new.censorship.mask_relay_timeout_ms
+        || old.censorship.mask_relay_idle_timeout_ms != new.censorship.mask_relay_idle_timeout_ms
         || old.censorship.mask_classifier_prefetch_timeout_ms
             != new.censorship.mask_classifier_prefetch_timeout_ms
         || old.censorship.mask_timing_normalization_enabled
@@ -1029,6 +1060,8 @@ fn log_changes(
             != new_hot.me_route_backpressure_high_timeout_ms
         || old_hot.me_route_backpressure_high_watermark_pct
             != new_hot.me_route_backpressure_high_watermark_pct
+        || old_hot.me_route_backpressure_enabled != new_hot.me_route_backpressure_enabled
+        || old_hot.me_route_fairshare_enabled != new_hot.me_route_fairshare_enabled
         || old_hot.me_reader_route_data_wait_ms != new_hot.me_reader_route_data_wait_ms
         || old_hot.me_health_interval_ms_unhealthy != new_hot.me_health_interval_ms_unhealthy
         || old_hot.me_health_interval_ms_healthy != new_hot.me_health_interval_ms_healthy
@@ -1036,10 +1069,12 @@ fn log_changes(
         || old_hot.me_warn_rate_limit_ms != new_hot.me_warn_rate_limit_ms
     {
         info!(
-            "config reload: me_route_backpressure: base={}ms high={}ms watermark={}%; me_reader_route_data_wait_ms={}; me_health_interval: unhealthy={}ms healthy={}ms; me_admission_poll={}ms; me_warn_rate_limit={}ms",
+            "config reload: me_route_backpressure: enabled={} base={}ms high={}ms watermark={}%; me_route_fairshare_enabled={}; me_reader_route_data_wait_ms={}; me_health_interval: unhealthy={}ms healthy={}ms; me_admission_poll={}ms; me_warn_rate_limit={}ms",
+            new_hot.me_route_backpressure_enabled,
             new_hot.me_route_backpressure_base_timeout_ms,
             new_hot.me_route_backpressure_high_timeout_ms,
             new_hot.me_route_backpressure_high_watermark_pct,
+            new_hot.me_route_fairshare_enabled,
             new_hot.me_reader_route_data_wait_ms,
             new_hot.me_health_interval_ms_unhealthy,
             new_hot.me_health_interval_ms_healthy,
@@ -1113,7 +1148,7 @@ fn log_changes(
                 .general
                 .links
                 .public_port
-                .unwrap_or(new_cfg.server.port);
+                .unwrap_or(resolve_default_link_port(new_cfg));
             for user in &added {
                 if let Some(secret) = new_hot.users.get(*user) {
                     print_user_links(user, secret, &host, port, new_cfg);
@@ -1166,6 +1201,18 @@ fn log_changes(
             new_hot.user_data_quota.len()
         );
     }
+    if old_hot.user_rate_limits != new_hot.user_rate_limits {
+        info!(
+            "config reload: user_rate_limits updated ({} entries)",
+            new_hot.user_rate_limits.len()
+        );
+    }
+    if old_hot.cidr_rate_limits != new_hot.cidr_rate_limits {
+        info!(
+            "config reload: cidr_rate_limits updated ({} entries)",
+            new_hot.cidr_rate_limits.len()
+        );
+    }
     if old_hot.user_max_unique_ips != new_hot.user_max_unique_ips {
         info!(
             "config reload: user_max_unique_ips updated ({} entries)",

src/config/tests/load_mask_shape_security_tests.rs

@@ -238,7 +238,7 @@ mask_shape_above_cap_blur_max_bytes = 8
 }
 
 #[test]
-fn load_rejects_zero_mask_relay_max_bytes() {
+fn load_accepts_zero_mask_relay_max_bytes_as_unlimited() {
     let path = write_temp_config(
         r#"
 [censorship]
@@ -246,12 +246,9 @@ mask_relay_max_bytes = 0
 "#,
     );
 
-    let err = ProxyConfig::load(&path).expect_err("mask_relay_max_bytes must be > 0");
-    let msg = err.to_string();
-    assert!(
-        msg.contains("censorship.mask_relay_max_bytes must be > 0"),
-        "error must explain non-zero relay cap invariant, got: {msg}"
-    );
+    let cfg = ProxyConfig::load(&path)
+        .expect("mask_relay_max_bytes=0 must be accepted as unlimited relay cap");
+    assert_eq!(cfg.censorship.mask_relay_max_bytes, 0);
 
     remove_temp_config(&path);
 }

src/config/tests/load_memory_envelope_tests.rs

@@ -0,0 +1,117 @@
+use super::*;
+use std::fs;
+use std::path::PathBuf;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+fn write_temp_config(contents: &str) -> PathBuf {
+    let nonce = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .expect("system time must be after unix epoch")
+        .as_nanos();
+    let path = std::env::temp_dir().join(format!("telemt-load-memory-envelope-{nonce}.toml"));
+    fs::write(&path, contents).expect("temp config write must succeed");
+    path
+}
+
+fn remove_temp_config(path: &PathBuf) {
+    let _ = fs::remove_file(path);
+}
+
+#[test]
+fn load_rejects_writer_cmd_capacity_above_upper_bound() {
+    let path = write_temp_config(
+        r#"
+[general]
+me_writer_cmd_channel_capacity = 16385
+"#,
+    );
+
+    let err =
+        ProxyConfig::load(&path).expect_err("writer command capacity above hard cap must fail");
+    let msg = err.to_string();
+    assert!(
+        msg.contains("general.me_writer_cmd_channel_capacity must be within [1, 16384]"),
+        "error must explain writer command capacity hard cap, got: {msg}"
+    );
+
+    remove_temp_config(&path);
+}
+
+#[test]
+fn load_rejects_route_channel_capacity_above_upper_bound() {
+    let path = write_temp_config(
+        r#"
+[general]
+me_route_channel_capacity = 8193
+"#,
+    );
+
+    let err =
+        ProxyConfig::load(&path).expect_err("route channel capacity above hard cap must fail");
+    let msg = err.to_string();
+    assert!(
+        msg.contains("general.me_route_channel_capacity must be within [1, 8192]"),
+        "error must explain route channel hard cap, got: {msg}"
+    );
+
+    remove_temp_config(&path);
+}
+
+#[test]
+fn load_rejects_c2me_channel_capacity_above_upper_bound() {
+    let path = write_temp_config(
+        r#"
+[general]
+me_c2me_channel_capacity = 8193
+"#,
+    );
+
+    let err = ProxyConfig::load(&path).expect_err("c2me channel capacity above hard cap must fail");
+    let msg = err.to_string();
+    assert!(
+        msg.contains("general.me_c2me_channel_capacity must be within [1, 8192]"),
+        "error must explain c2me channel hard cap, got: {msg}"
+    );
+
+    remove_temp_config(&path);
+}
+
+#[test]
+fn load_rejects_max_client_frame_above_upper_bound() {
+    let path = write_temp_config(
+        r#"
+[general]
+max_client_frame = 16777217
+"#,
+    );
+
+    let err = ProxyConfig::load(&path).expect_err("max_client_frame above hard cap must fail");
+    let msg = err.to_string();
+    assert!(
+        msg.contains("general.max_client_frame must be within [4096, 16777216]"),
+        "error must explain max_client_frame hard cap, got: {msg}"
+    );
+
+    remove_temp_config(&path);
+}
+
+#[test]
+fn load_accepts_memory_limits_at_hard_upper_bounds() {
+    let path = write_temp_config(
+        r#"
+[general]
+me_writer_cmd_channel_capacity = 16384
+me_route_channel_capacity = 8192
+me_c2me_channel_capacity = 8192
+max_client_frame = 16777216
+"#,
+    );
+
+    let cfg = ProxyConfig::load(&path).expect("hard upper bound values must be accepted");
+    assert_eq!(cfg.general.me_writer_cmd_channel_capacity, 16384);
+    assert_eq!(cfg.general.me_route_channel_capacity, 8192);
+    assert_eq!(cfg.general.me_c2me_channel_capacity, 8192);
+    assert_eq!(cfg.general.max_client_frame, 16 * 1024 * 1024);
+
+    remove_temp_config(&path);
+}

src/config/types.rs

@@ -26,6 +26,10 @@ pub enum LogLevel {
     Silent,
 }
 
+fn default_quota_state_path() -> PathBuf {
+    PathBuf::from("telemt.limit.json")
+}
+
 impl LogLevel {
     /// Convert to tracing EnvFilter directive string.
     pub fn to_filter_str(&self) -> &'static str {
@@ -159,6 +163,21 @@ impl MeBindStaleMode {
     }
 }
 
+/// RST-on-close mode for accepted client sockets.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[serde(rename_all = "lowercase")]
+pub enum RstOnCloseMode {
+    /// Normal FIN on all closes (default, no behaviour change).
+    #[default]
+    Off,
+    /// SO_LINGER(0) on accept; cleared after successful auth.
+    /// Pre-handshake failures (scanners, DPI, timeouts) send RST;
+    /// authenticated relay sessions close gracefully with FIN.
+    Errors,
+    /// SO_LINGER(0) on accept, never cleared — all closes send RST.
+    Always,
+}
+
 /// Middle-End writer floor policy mode.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
 #[serde(rename_all = "lowercase")]
@@ -360,6 +379,15 @@ pub struct GeneralConfig {
     #[serde(default)]
     pub data_path: Option<PathBuf>,
 
+    /// JSON state file for runtime per-user quota consumption.
+    #[serde(default = "default_quota_state_path")]
+    pub quota_state_path: PathBuf,
+
+    /// Reject unknown TOML config keys during load.
+    /// Startup fails fast; hot-reload rejects the new snapshot and keeps the current config.
+    #[serde(default)]
+    pub config_strict: bool,
+
     #[serde(default)]
     pub modes: ProxyModes,
 
@@ -377,14 +405,26 @@ pub struct GeneralConfig {
     #[serde(default = "default_proxy_secret_path")]
     pub proxy_secret_path: Option<String>,
 
+    /// Optional custom URL for infrastructure secret (https://core.telegram.org/getProxySecret if absent).
+    #[serde(default)]
+    pub proxy_secret_url: Option<String>,
+
     /// Optional path to cache raw getProxyConfig (IPv4) snapshot for startup fallback.
     #[serde(default = "default_proxy_config_v4_cache_path")]
     pub proxy_config_v4_cache_path: Option<String>,
 
+    /// Optional custom URL for getProxyConfig (https://core.telegram.org/getProxyConfig if absent).
+    #[serde(default)]
+    pub proxy_config_v4_url: Option<String>,
+
     /// Optional path to cache raw getProxyConfigV6 snapshot for startup fallback.
     #[serde(default = "default_proxy_config_v6_cache_path")]
     pub proxy_config_v6_cache_path: Option<String>,
 
+    /// Optional custom URL for getProxyConfigV6 (https://core.telegram.org/getProxyConfigV6 if absent).
+    #[serde(default)]
+    pub proxy_config_v6_url: Option<String>,
+
     /// Global ad_tag (32 hex chars from @MTProxybot). Fallback when user has no per-user tag in access.user_ad_tags.
     #[serde(default)]
     pub ad_tag: Option<String>,
@@ -503,10 +543,17 @@ pub struct GeneralConfig {
     pub me_d2c_frame_buf_shrink_threshold_bytes: usize,
 
     /// Copy buffer size for client->DC direction in direct relay.
+    ///
+    /// This is also the upper bound for one amortized upload rate-limit burst:
+    /// upload debt is settled before the next relay read instead of blocking
+    /// inside the completed read path.
     #[serde(default = "default_direct_relay_copy_buf_c2s_bytes")]
     pub direct_relay_copy_buf_c2s_bytes: usize,
 
     /// Copy buffer size for DC->client direction in direct relay.
+    ///
+    /// This bounds one direct download rate-limit grant because writes are
+    /// clipped to the currently available shaper budget.
     #[serde(default = "default_direct_relay_copy_buf_s2c_bytes")]
     pub direct_relay_copy_buf_s2c_bytes: usize,
 
@@ -702,6 +749,14 @@ pub struct GeneralConfig {
     #[serde(default)]
     pub me_socks_kdf_policy: MeSocksKdfPolicy,
 
+    /// Enable route-level ME backpressure controls in reader fairness path.
+    #[serde(default = "default_me_route_backpressure_enabled")]
+    pub me_route_backpressure_enabled: bool,
+
+    /// Enable worker-local fairshare scheduler for ME reader routing.
+    #[serde(default = "default_me_route_fairshare_enabled")]
+    pub me_route_fairshare_enabled: bool,
+
     /// Base backpressure timeout in milliseconds for ME route channel send.
     #[serde(default = "default_me_route_backpressure_base_timeout_ms")]
     pub me_route_backpressure_base_timeout_ms: u64,
@@ -743,7 +798,7 @@ pub struct GeneralConfig {
     pub me_route_hybrid_max_wait_ms: u64,
 
     /// Maximum wait in milliseconds for blocking ME writer channel send fallback.
-    /// `0` keeps legacy unbounded wait behavior.
+    /// Must be within [1, 5000].
     #[serde(default = "default_me_route_blocking_send_timeout_ms")]
     pub me_route_blocking_send_timeout_ms: u64,
 
@@ -925,20 +980,33 @@ pub struct GeneralConfig {
     /// Minimum unavailable ME DC groups before degrading.
     #[serde(default = "default_degradation_min_unavailable_dc_groups")]
     pub degradation_min_unavailable_dc_groups: u8,
+
+    /// RST-on-close mode for accepted client sockets.
+    /// `off`    — normal FIN on all closes (default).
+    /// `errors` — SO_LINGER(0) on accept, cleared after successful auth;
+    ///            pre-handshake failures send RST, relayed sessions close gracefully.
+    /// `always` — SO_LINGER(0) on accept, never cleared; all closes send RST.
+    #[serde(default)]
+    pub rst_on_close: RstOnCloseMode,
 }
 
 impl Default for GeneralConfig {
     fn default() -> Self {
         Self {
             data_path: None,
+            quota_state_path: default_quota_state_path(),
+            config_strict: false,
             modes: ProxyModes::default(),
             prefer_ipv6: false,
             fast_mode: default_true(),
             use_middle_proxy: default_true(),
             ad_tag: None,
             proxy_secret_path: default_proxy_secret_path(),
+            proxy_secret_url: None,
             proxy_config_v4_cache_path: default_proxy_config_v4_cache_path(),
+            proxy_config_v4_url: None,
             proxy_config_v6_cache_path: default_proxy_config_v6_cache_path(),
+            proxy_config_v6_url: None,
             middle_proxy_nat_ip: None,
             middle_proxy_nat_probe: default_true(),
             middle_proxy_nat_stun: default_middle_proxy_nat_stun(),
@@ -1021,6 +1089,8 @@ impl Default for GeneralConfig {
             disable_colors: false,
             telemetry: TelemetryConfig::default(),
             me_socks_kdf_policy: MeSocksKdfPolicy::Strict,
+            me_route_backpressure_enabled: default_me_route_backpressure_enabled(),
+            me_route_fairshare_enabled: default_me_route_fairshare_enabled(),
             me_route_backpressure_base_timeout_ms: default_me_route_backpressure_base_timeout_ms(),
             me_route_backpressure_high_timeout_ms: default_me_route_backpressure_high_timeout_ms(),
             me_route_backpressure_high_watermark_pct:
@@ -1086,6 +1156,7 @@ impl Default for GeneralConfig {
             ntp_servers: default_ntp_servers(),
             auto_degradation_enabled: default_true(),
             degradation_min_unavailable_dc_groups: default_degradation_min_unavailable_dc_groups(),
+            rst_on_close: RstOnCloseMode::default(),
         }
     }
 }
@@ -1129,7 +1200,8 @@ pub struct LinksConfig {
     #[serde(default)]
     pub public_host: Option<String>,
 
-    /// Public port for tg:// link generation (overrides server.port).
+    /// Public port for tg:// link generation.
+    /// Overrides listener ports and legacy `server.port`.
     #[serde(default)]
     pub public_port: Option<u16>,
 }
@@ -1159,6 +1231,13 @@ pub struct ApiConfig {
     #[serde(default = "default_api_whitelist")]
     pub whitelist: Vec<IpNetwork>,
 
+    /// Behavior for requests from source IPs outside `whitelist`.
+    /// - `api`: return structured API forbidden response.
+    /// - `200`: return `200 OK` with an empty body.
+    /// - `drop`: close the connection without HTTP response.
+    #[serde(default)]
+    pub gray_action: ApiGrayAction,
+
     /// Optional static value for `Authorization` header validation.
     /// Empty string disables header auth.
     #[serde(default)]
@@ -1203,6 +1282,7 @@ impl Default for ApiConfig {
             enabled: default_true(),
             listen: default_api_listen(),
             whitelist: default_api_whitelist(),
+            gray_action: ApiGrayAction::default(),
             auth_header: String::new(),
             request_body_limit_bytes: default_api_request_body_limit_bytes(),
             minimal_runtime_enabled: default_api_minimal_runtime_enabled(),
@@ -1216,6 +1296,19 @@ impl Default for ApiConfig {
     }
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[serde(rename_all = "lowercase")]
+pub enum ApiGrayAction {
+    /// Preserve current API behavior for denied source IPs.
+    Api,
+    /// Mimic a plain web endpoint by returning `200 OK` with an empty body.
+    #[serde(rename = "200")]
+    Ok200,
+    /// Drop connection without HTTP response for denied source IPs.
+    #[default]
+    Drop,
+}
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
 #[serde(rename_all = "lowercase")]
 pub enum ConntrackMode {
@@ -1283,6 +1376,10 @@ pub struct ConntrackControlConfig {
     #[serde(default = "default_conntrack_control_enabled")]
     pub inline_conntrack_control: bool,
 
+    /// Tracks whether inline_conntrack_control was explicitly set in config.
+    #[serde(skip)]
+    pub inline_conntrack_control_explicit: bool,
+
     /// Conntrack mode for listener ingress traffic.
     #[serde(default)]
     pub mode: ConntrackMode,
@@ -1317,6 +1414,7 @@ impl Default for ConntrackControlConfig {
     fn default() -> Self {
         Self {
             inline_conntrack_control: default_conntrack_control_enabled(),
+            inline_conntrack_control_explicit: false,
             mode: ConntrackMode::default(),
             backend: ConntrackBackend::default(),
             profile: ConntrackPressureProfile::default(),
@@ -1330,6 +1428,8 @@ impl Default for ConntrackControlConfig {
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ServerConfig {
+    /// Legacy listener port used for backward compatibility.
+    /// For new configs prefer `[[server.listeners]].port`.
     #[serde(default = "default_port")]
     pub port: u16,
 
@@ -1502,6 +1602,14 @@ pub enum UnknownSniAction {
     #[default]
     Drop,
     Mask,
+    Accept,
+    /// Reject the TLS handshake by sending a fatal `unrecognized_name` alert
+    /// (RFC 6066, AlertDescription = 112) before closing the connection.
+    /// Mimics nginx `ssl_reject_handshake on;` behavior on the default vhost —
+    /// the wire response indistinguishable from a stock modern web server
+    /// that simply does not host the requested name.
+    #[serde(rename = "reject_handshake")]
+    RejectHandshake,
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
@@ -1637,9 +1745,16 @@ pub struct AntiCensorshipConfig {
     #[serde(default = "default_tls_new_session_tickets")]
     pub tls_new_session_tickets: u8,
 
+    /// Enable compact ServerHello payload mode.
+    /// When false, FakeTLS always uses full ServerHello payload behavior.
+    /// When true, compact certificate payload mode can be used by TTL policy.
+    #[serde(default = "default_serverhello_compact")]
+    pub serverhello_compact: bool,
+
     /// TTL in seconds for sending full certificate payload per client IP.
     /// First client connection per (SNI domain, client IP) gets full cert payload.
     /// Subsequent handshakes within TTL use compact cert metadata payload.
+    /// Applied only when `serverhello_compact` is enabled.
     #[serde(default = "default_tls_full_cert_ttl_secs")]
     pub tls_full_cert_ttl_secs: u64,
 
@@ -1682,9 +1797,23 @@ pub struct AntiCensorshipConfig {
     pub mask_shape_above_cap_blur_max_bytes: usize,
 
     /// Maximum bytes relayed per direction on unauthenticated masking fallback paths.
+    /// Set to 0 to disable byte cap (unlimited within relay/idle timeouts).
     #[serde(default = "default_mask_relay_max_bytes")]
     pub mask_relay_max_bytes: usize,
 
+    /// Wall-clock cap for the full masking relay on non-MTProto fallback paths.
+    /// Raise when the mask target is a long-lived service (e.g. WebSocket).
+    /// Default: 60 000 ms (60 s).
+    #[serde(default = "default_mask_relay_timeout_ms")]
+    pub mask_relay_timeout_ms: u64,
+
+    /// Per-read idle timeout on masking relay and drain paths.
+    /// Limits resource consumption by slow-loris attacks and port scanners.
+    /// A read call stalling beyond this is treated as an abandoned connection.
+    /// Default: 5 000 ms (5 s).
+    #[serde(default = "default_mask_relay_idle_timeout_ms")]
+    pub mask_relay_idle_timeout_ms: u64,
+
     /// Prefetch timeout (ms) for extending fragmented masking classifier window.
     #[serde(default = "default_mask_classifier_prefetch_timeout_ms")]
     pub mask_classifier_prefetch_timeout_ms: u64,
@@ -1720,6 +1849,7 @@ impl Default for AntiCensorshipConfig {
             server_hello_delay_min_ms: default_server_hello_delay_min_ms(),
             server_hello_delay_max_ms: default_server_hello_delay_max_ms(),
             tls_new_session_tickets: default_tls_new_session_tickets(),
+            serverhello_compact: default_serverhello_compact(),
             tls_full_cert_ttl_secs: default_tls_full_cert_ttl_secs(),
             alpn_enforce: default_alpn_enforce(),
             mask_proxy_protocol: 0,
@@ -1730,6 +1860,8 @@ impl Default for AntiCensorshipConfig {
             mask_shape_above_cap_blur: default_mask_shape_above_cap_blur(),
             mask_shape_above_cap_blur_max_bytes: default_mask_shape_above_cap_blur_max_bytes(),
             mask_relay_max_bytes: default_mask_relay_max_bytes(),
+            mask_relay_timeout_ms: default_mask_relay_timeout_ms(),
+            mask_relay_idle_timeout_ms: default_mask_relay_idle_timeout_ms(),
             mask_classifier_prefetch_timeout_ms: default_mask_classifier_prefetch_timeout_ms(),
             mask_timing_normalization_enabled: default_mask_timing_normalization_enabled(),
             mask_timing_normalization_floor_ms: default_mask_timing_normalization_floor_ms(),
@@ -1762,6 +1894,30 @@ pub struct AccessConfig {
     #[serde(default)]
     pub user_data_quota: HashMap<String, u64>,
 
+    /// Per-user transport rate limits in bits-per-second.
+    ///
+    /// Each entry supports independent upload (`up_bps`) and download
+    /// (`down_bps`) ceilings. A value of `0` in one direction means
+    /// "unlimited" for that direction. Limits are amortized: a relay quantum
+    /// may pass as a bounded burst, and the limiter applies the resulting wait
+    /// before later traffic in the same direction proceeds.
+    #[serde(default)]
+    pub user_rate_limits: HashMap<String, RateLimitBps>,
+
+    /// Per-CIDR aggregate transport rate limits in bits-per-second.
+    ///
+    /// Matching uses longest-prefix-wins semantics. A value of `0` in one
+    /// direction means "unlimited" for that direction. Limits are amortized
+    /// with the same bounded-burst contract as per-user rate limits.
+    #[serde(default)]
+    pub cidr_rate_limits: HashMap<IpNetwork, RateLimitBps>,
+
+    /// Per-username client source IP/CIDR deny list. Checked after successful
+    /// authentication; matching IPs get the same rejection path as invalid auth
+    /// (handshake fails closed for that connection).
+    #[serde(default)]
+    pub user_source_deny: HashMap<String, Vec<IpNetwork>>,
+
     #[serde(default)]
     pub user_max_unique_ips: HashMap<String, usize>,
 
@@ -1795,6 +1951,9 @@ impl Default for AccessConfig {
             user_max_tcp_conns_global_each: default_user_max_tcp_conns_global_each(),
             user_expirations: HashMap::new(),
             user_data_quota: HashMap::new(),
+            user_rate_limits: HashMap::new(),
+            cidr_rate_limits: HashMap::new(),
+            user_source_deny: HashMap::new(),
             user_max_unique_ips: HashMap::new(),
             user_max_unique_ips_global_each: default_user_max_unique_ips_global_each(),
             user_max_unique_ips_mode: UserMaxUniqueIpsMode::default(),
@@ -1806,6 +1965,23 @@ impl Default for AccessConfig {
     }
 }
 
+impl AccessConfig {
+    /// Returns true if `ip` is contained in any CIDR listed for `username` under `user_source_deny`.
+    pub fn is_user_source_ip_denied(&self, username: &str, ip: IpAddr) -> bool {
+        self.user_source_deny
+            .get(username)
+            .is_some_and(|nets| nets.iter().any(|n| n.contains(ip)))
+    }
+}
+
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct RateLimitBps {
+    #[serde(default)]
+    pub up_bps: u64,
+    #[serde(default)]
+    pub down_bps: u64,
+}
+
 // ============= Aux Structures =============
 
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
@@ -1816,6 +1992,10 @@ pub enum UpstreamType {
         interface: Option<String>,
         #[serde(default)]
         bind_addresses: Option<Vec<String>>,
+        /// Linux-only hard interface pinning via `SO_BINDTODEVICE`.
+        /// Optional alias: `force_bind`.
+        #[serde(default, alias = "force_bind")]
+        bindtodevice: Option<String>,
     },
     Socks4 {
         address: String,
@@ -1852,11 +2032,22 @@ pub struct UpstreamConfig {
     pub scopes: String,
     #[serde(skip)]
     pub selected_scope: String,
+    /// Allow IPv4 DC targets for this upstream.
+    /// `None` means auto-detect from runtime connectivity state.
+    #[serde(default)]
+    pub ipv4: Option<bool>,
+    /// Allow IPv6 DC targets for this upstream.
+    /// `None` means auto-detect from runtime connectivity state.
+    #[serde(default)]
+    pub ipv6: Option<bool>,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ListenerConfig {
     pub ip: IpAddr,
+    /// Per-listener TCP port. If omitted, falls back to legacy `server.port`.
+    #[serde(default)]
+    pub port: Option<u16>,
     /// IP address or hostname to announce in proxy links.
     /// Takes precedence over `announce_ip` if both are set.
     #[serde(default)]

src/conntrack_control.rs

@@ -24,6 +24,13 @@ enum NetfilterBackend {
     Iptables,
 }
 
+#[derive(Clone, Copy)]
+struct ConntrackRuntimeSupport {
+    netfilter_backend: Option<NetfilterBackend>,
+    has_cap_net_admin: bool,
+    has_conntrack_binary: bool,
+}
+
 #[derive(Clone, Copy)]
 struct PressureSample {
     conn_pct: Option<u8>,
@@ -56,7 +63,8 @@ pub(crate) fn spawn_conntrack_controller(
     shared: Arc<ProxySharedState>,
 ) {
     if !cfg!(target_os = "linux") {
-        let enabled = config_rx.borrow().server.conntrack_control.inline_conntrack_control;
+        let cfg = config_rx.borrow();
+        let enabled = cfg.server.conntrack_control.inline_conntrack_control;
         stats.set_conntrack_control_enabled(enabled);
         stats.set_conntrack_control_available(false);
         stats.set_conntrack_pressure_active(false);
@@ -64,8 +72,15 @@ pub(crate) fn spawn_conntrack_controller(
         stats.set_conntrack_rule_apply_ok(false);
         shared.disable_conntrack_close_sender();
         shared.set_conntrack_pressure_active(false);
-        if enabled {
-            warn!("conntrack control is configured but unsupported on this OS; disabling runtime worker");
+        if enabled
+            && cfg
+                .server
+                .conntrack_control
+                .inline_conntrack_control_explicit
+        {
+            warn!(
+                "conntrack control explicitly enabled but unsupported on this OS; disabling runtime worker"
+            );
         }
         return;
     }
@@ -86,10 +101,17 @@ async fn run_conntrack_controller(
     let mut cfg = config_rx.borrow().clone();
     let mut pressure_state = PressureState::new(stats.as_ref());
     let mut delete_budget_tokens = cfg.server.conntrack_control.delete_budget_per_sec;
-    let mut backend = pick_backend(cfg.server.conntrack_control.backend);
+    let mut runtime_support = probe_runtime_support(cfg.server.conntrack_control.backend);
+    let mut effective_enabled = effective_conntrack_enabled(&cfg, runtime_support);
 
-    apply_runtime_state(stats.as_ref(), shared.as_ref(), &cfg, backend.is_some(), false);
-    reconcile_rules(&cfg, backend, stats.as_ref()).await;
+    apply_runtime_state(
+        stats.as_ref(),
+        shared.as_ref(),
+        &cfg,
+        runtime_support,
+        false,
+    );
+    reconcile_rules(&cfg, runtime_support, stats.as_ref()).await;
 
     loop {
         tokio::select! {
@@ -98,17 +120,18 @@ async fn run_conntrack_controller(
                     break;
                 }
                 cfg = config_rx.borrow_and_update().clone();
-                backend = pick_backend(cfg.server.conntrack_control.backend);
+                runtime_support = probe_runtime_support(cfg.server.conntrack_control.backend);
+                effective_enabled = effective_conntrack_enabled(&cfg, runtime_support);
                 delete_budget_tokens = cfg.server.conntrack_control.delete_budget_per_sec;
-                apply_runtime_state(stats.as_ref(), shared.as_ref(), &cfg, backend.is_some(), pressure_state.active);
-                reconcile_rules(&cfg, backend, stats.as_ref()).await;
+                apply_runtime_state(stats.as_ref(), shared.as_ref(), &cfg, runtime_support, pressure_state.active);
+                reconcile_rules(&cfg, runtime_support, stats.as_ref()).await;
             }
             event = close_rx.recv() => {
                 let Some(event) = event else {
                     break;
                 };
                 stats.set_conntrack_event_queue_depth(close_rx.len() as u64);
-                if !cfg.server.conntrack_control.inline_conntrack_control {
+                if !effective_enabled {
                     continue;
                 }
                 if !pressure_state.active {
@@ -144,6 +167,7 @@ async fn run_conntrack_controller(
                     stats.as_ref(),
                     shared.as_ref(),
                     &cfg,
+                    effective_enabled,
                     &sample,
                     &mut pressure_state,
                 );
@@ -163,20 +187,30 @@ fn apply_runtime_state(
     stats: &Stats,
     shared: &ProxySharedState,
     cfg: &ProxyConfig,
-    backend_available: bool,
+    runtime_support: ConntrackRuntimeSupport,
     pressure_active: bool,
 ) {
     let enabled = cfg.server.conntrack_control.inline_conntrack_control;
-    let available = enabled && backend_available && has_cap_net_admin();
-    if enabled && !available {
+    let available = effective_conntrack_enabled(cfg, runtime_support);
+    if enabled
+        && !available
+        && cfg
+            .server
+            .conntrack_control
+            .inline_conntrack_control_explicit
+    {
         warn!(
-            "conntrack control enabled but unavailable (missing CAP_NET_ADMIN or backend binaries)"
+            has_cap_net_admin = runtime_support.has_cap_net_admin,
+            backend_available = runtime_support.netfilter_backend.is_some(),
+            conntrack_binary_available = runtime_support.has_conntrack_binary,
+            configured_backend = ?cfg.server.conntrack_control.backend,
+            "conntrack control explicitly enabled but unavailable; disabling runtime features"
         );
     }
     stats.set_conntrack_control_enabled(enabled);
     stats.set_conntrack_control_available(available);
-    shared.set_conntrack_pressure_active(enabled && pressure_active);
-    stats.set_conntrack_pressure_active(enabled && pressure_active);
+    shared.set_conntrack_pressure_active(available && pressure_active);
+    stats.set_conntrack_pressure_active(available && pressure_active);
 }
 
 fn collect_pressure_sample(
@@ -216,10 +250,11 @@ fn update_pressure_state(
     stats: &Stats,
     shared: &ProxySharedState,
     cfg: &ProxyConfig,
+    effective_enabled: bool,
     sample: &PressureSample,
     state: &mut PressureState,
 ) {
-    if !cfg.server.conntrack_control.inline_conntrack_control {
+    if !effective_enabled {
         if state.active {
             state.active = false;
             state.low_streak = 0;
@@ -273,22 +308,26 @@ fn update_pressure_state(
     state.low_streak = 0;
 }
 
-async fn reconcile_rules(cfg: &ProxyConfig, backend: Option<NetfilterBackend>, stats: &Stats) {
+async fn reconcile_rules(
+    cfg: &ProxyConfig,
+    runtime_support: ConntrackRuntimeSupport,
+    stats: &Stats,
+) {
     if !cfg.server.conntrack_control.inline_conntrack_control {
         clear_notrack_rules_all_backends().await;
         stats.set_conntrack_rule_apply_ok(true);
         return;
     }
 
-    if !has_cap_net_admin() {
+    if !effective_conntrack_enabled(cfg, runtime_support) {
+        clear_notrack_rules_all_backends().await;
         stats.set_conntrack_rule_apply_ok(false);
         return;
     }
 
-    let Some(backend) = backend else {
-        stats.set_conntrack_rule_apply_ok(false);
-        return;
-    };
+    let backend = runtime_support
+        .netfilter_backend
+        .expect("netfilter backend must be available for effective conntrack control");
 
     let apply_result = match backend {
         NetfilterBackend::Nftables => apply_nft_rules(cfg).await,
@@ -303,6 +342,24 @@ async fn reconcile_rules(cfg: &ProxyConfig, backend: Option<NetfilterBackend>, s
     }
 }
 
+fn probe_runtime_support(configured_backend: ConntrackBackend) -> ConntrackRuntimeSupport {
+    ConntrackRuntimeSupport {
+        netfilter_backend: pick_backend(configured_backend),
+        has_cap_net_admin: has_cap_net_admin(),
+        has_conntrack_binary: command_exists("conntrack"),
+    }
+}
+
+fn effective_conntrack_enabled(
+    cfg: &ProxyConfig,
+    runtime_support: ConntrackRuntimeSupport,
+) -> bool {
+    cfg.server.conntrack_control.inline_conntrack_control
+        && runtime_support.has_cap_net_admin
+        && runtime_support.netfilter_backend.is_some()
+        && runtime_support.has_conntrack_binary
+}
+
 fn pick_backend(configured: ConntrackBackend) -> Option<NetfilterBackend> {
     match configured {
         ConntrackBackend::Auto => {
@@ -315,7 +372,9 @@ fn pick_backend(configured: ConntrackBackend) -> Option<NetfilterBackend> {
             }
         }
         ConntrackBackend::Nftables => command_exists("nft").then_some(NetfilterBackend::Nftables),
-        ConntrackBackend::Iptables => command_exists("iptables").then_some(NetfilterBackend::Iptables),
+        ConntrackBackend::Iptables => {
+            command_exists("iptables").then_some(NetfilterBackend::Iptables)
+        }
     }
 }
 
@@ -329,15 +388,28 @@ fn command_exists(binary: &str) -> bool {
     })
 }
 
-fn notrack_targets(cfg: &ProxyConfig) -> (Vec<Option<IpAddr>>, Vec<Option<IpAddr>>) {
+fn listener_port_set(cfg: &ProxyConfig) -> Vec<u16> {
+    let mut ports: BTreeSet<u16> = BTreeSet::new();
+    if cfg.server.listeners.is_empty() {
+        ports.insert(cfg.server.port);
+    } else {
+        for listener in &cfg.server.listeners {
+            ports.insert(listener.port.unwrap_or(cfg.server.port));
+        }
+    }
+    ports.into_iter().collect()
+}
+
+fn notrack_targets(cfg: &ProxyConfig) -> (Vec<(Option<IpAddr>, u16)>, Vec<(Option<IpAddr>, u16)>) {
     let mode = cfg.server.conntrack_control.mode;
-    let mut v4_targets: BTreeSet<Option<IpAddr>> = BTreeSet::new();
-    let mut v6_targets: BTreeSet<Option<IpAddr>> = BTreeSet::new();
+    let mut v4_targets: BTreeSet<(Option<IpAddr>, u16)> = BTreeSet::new();
+    let mut v6_targets: BTreeSet<(Option<IpAddr>, u16)> = BTreeSet::new();
 
     match mode {
         ConntrackMode::Tracked => {}
         ConntrackMode::Notrack => {
             if cfg.server.listeners.is_empty() {
+                let port = cfg.server.port;
                 if let Some(ipv4) = cfg
                     .server
                     .listen_addr_ipv4
@@ -345,9 +417,9 @@ fn notrack_targets(cfg: &ProxyConfig) -> (Vec<Option<IpAddr>>, Vec<Option<IpAddr
                     .and_then(|s| s.parse::<IpAddr>().ok())
                 {
                     if ipv4.is_unspecified() {
-                        v4_targets.insert(None);
+                        v4_targets.insert((None, port));
                     } else {
-                        v4_targets.insert(Some(ipv4));
+                        v4_targets.insert((Some(ipv4), port));
                     }
                 }
                 if let Some(ipv6) = cfg
@@ -357,33 +429,39 @@ fn notrack_targets(cfg: &ProxyConfig) -> (Vec<Option<IpAddr>>, Vec<Option<IpAddr
                     .and_then(|s| s.parse::<IpAddr>().ok())
                 {
                     if ipv6.is_unspecified() {
-                        v6_targets.insert(None);
+                        v6_targets.insert((None, port));
                     } else {
-                        v6_targets.insert(Some(ipv6));
+                        v6_targets.insert((Some(ipv6), port));
                     }
                 }
             } else {
                 for listener in &cfg.server.listeners {
+                    let port = listener.port.unwrap_or(cfg.server.port);
                     if listener.ip.is_ipv4() {
                         if listener.ip.is_unspecified() {
-                            v4_targets.insert(None);
+                            v4_targets.insert((None, port));
                         } else {
-                            v4_targets.insert(Some(listener.ip));
+                            v4_targets.insert((Some(listener.ip), port));
                         }
                     } else if listener.ip.is_unspecified() {
-                        v6_targets.insert(None);
+                        v6_targets.insert((None, port));
                     } else {
-                        v6_targets.insert(Some(listener.ip));
+                        v6_targets.insert((Some(listener.ip), port));
                     }
                 }
             }
         }
         ConntrackMode::Hybrid => {
+            let ports = listener_port_set(cfg);
             for ip in &cfg.server.conntrack_control.hybrid_listener_ips {
                 if ip.is_ipv4() {
-                    v4_targets.insert(Some(*ip));
+                    for port in &ports {
+                        v4_targets.insert((Some(*ip), *port));
+                    }
                 } else {
-                    v6_targets.insert(Some(*ip));
+                    for port in &ports {
+                        v6_targets.insert((Some(*ip), *port));
+                    }
                 }
             }
         }
@@ -396,26 +474,31 @@ fn notrack_targets(cfg: &ProxyConfig) -> (Vec<Option<IpAddr>>, Vec<Option<IpAddr
 }
 
 async fn apply_nft_rules(cfg: &ProxyConfig) -> Result<(), String> {
-    let _ = run_command("nft", &["delete", "table", "inet", "telemt_conntrack"], None).await;
+    let _ = run_command(
+        "nft",
+        &["delete", "table", "inet", "telemt_conntrack"],
+        None,
+    )
+    .await;
     if matches!(cfg.server.conntrack_control.mode, ConntrackMode::Tracked) {
         return Ok(());
     }
 
     let (v4_targets, v6_targets) = notrack_targets(cfg);
     let mut rules = Vec::new();
-    for ip in v4_targets {
+    for (ip, port) in v4_targets {
         let rule = if let Some(ip) = ip {
-            format!("tcp dport {} ip daddr {} notrack", cfg.server.port, ip)
+            format!("tcp dport {} ip daddr {} notrack", port, ip)
         } else {
-            format!("tcp dport {} notrack", cfg.server.port)
+            format!("tcp dport {} notrack", port)
         };
         rules.push(rule);
     }
-    for ip in v6_targets {
+    for (ip, port) in v6_targets {
         let rule = if let Some(ip) = ip {
-            format!("tcp dport {} ip6 daddr {} notrack", cfg.server.port, ip)
+            format!("tcp dport {} ip6 daddr {} notrack", port, ip)
         } else {
-            format!("tcp dport {} notrack", cfg.server.port)
+            format!("tcp dport {} notrack", port)
         };
         rules.push(rule);
     }
@@ -446,7 +529,12 @@ async fn apply_iptables_rules_for_binary(
         return Ok(());
     }
     let chain = "TELEMT_NOTRACK";
-    let _ = run_command(binary, &["-t", "raw", "-D", "PREROUTING", "-j", chain], None).await;
+    let _ = run_command(
+        binary,
+        &["-t", "raw", "-D", "PREROUTING", "-j", chain],
+        None,
+    )
+    .await;
     let _ = run_command(binary, &["-t", "raw", "-F", chain], None).await;
     let _ = run_command(binary, &["-t", "raw", "-X", chain], None).await;
 
@@ -456,13 +544,25 @@ async fn apply_iptables_rules_for_binary(
 
     run_command(binary, &["-t", "raw", "-N", chain], None).await?;
     run_command(binary, &["-t", "raw", "-F", chain], None).await?;
-    if run_command(binary, &["-t", "raw", "-C", "PREROUTING", "-j", chain], None).await.is_err() {
-        run_command(binary, &["-t", "raw", "-I", "PREROUTING", "1", "-j", chain], None).await?;
+    if run_command(
+        binary,
+        &["-t", "raw", "-C", "PREROUTING", "-j", chain],
+        None,
+    )
+    .await
+    .is_err()
+    {
+        run_command(
+            binary,
+            &["-t", "raw", "-I", "PREROUTING", "1", "-j", chain],
+            None,
+        )
+        .await?;
     }
 
     let (v4_targets, v6_targets) = notrack_targets(cfg);
     let selected = if ipv4 { v4_targets } else { v6_targets };
-    for ip in selected {
+    for (ip, port) in selected {
         let mut args = vec![
             "-t".to_string(),
             "raw".to_string(),
@@ -471,7 +571,7 @@ async fn apply_iptables_rules_for_binary(
             "-p".to_string(),
             "tcp".to_string(),
             "--dport".to_string(),
-            cfg.server.port.to_string(),
+            port.to_string(),
         ];
         if let Some(ip) = ip {
             args.push("-d".to_string());
@@ -487,11 +587,26 @@ async fn apply_iptables_rules_for_binary(
 }
 
 async fn clear_notrack_rules_all_backends() {
-    let _ = run_command("nft", &["delete", "table", "inet", "telemt_conntrack"], None).await;
-    let _ = run_command("iptables", &["-t", "raw", "-D", "PREROUTING", "-j", "TELEMT_NOTRACK"], None).await;
+    let _ = run_command(
+        "nft",
+        &["delete", "table", "inet", "telemt_conntrack"],
+        None,
+    )
+    .await;
+    let _ = run_command(
+        "iptables",
+        &["-t", "raw", "-D", "PREROUTING", "-j", "TELEMT_NOTRACK"],
+        None,
+    )
+    .await;
     let _ = run_command("iptables", &["-t", "raw", "-F", "TELEMT_NOTRACK"], None).await;
     let _ = run_command("iptables", &["-t", "raw", "-X", "TELEMT_NOTRACK"], None).await;
-    let _ = run_command("ip6tables", &["-t", "raw", "-D", "PREROUTING", "-j", "TELEMT_NOTRACK"], None).await;
+    let _ = run_command(
+        "ip6tables",
+        &["-t", "raw", "-D", "PREROUTING", "-j", "TELEMT_NOTRACK"],
+        None,
+    )
+    .await;
     let _ = run_command("ip6tables", &["-t", "raw", "-F", "TELEMT_NOTRACK"], None).await;
     let _ = run_command("ip6tables", &["-t", "raw", "-X", "TELEMT_NOTRACK"], None).await;
 }
@@ -640,7 +755,7 @@ mod tests {
             me_queue_pressure_delta: 0,
         };
 
-        update_pressure_state(&stats, shared.as_ref(), &cfg, &sample, &mut state);
+        update_pressure_state(&stats, shared.as_ref(), &cfg, true, &sample, &mut state);
 
         assert!(state.active);
         assert!(shared.conntrack_pressure_active());
@@ -661,7 +776,14 @@ mod tests {
             accept_timeout_delta: 0,
             me_queue_pressure_delta: 0,
         };
-        update_pressure_state(&stats, shared.as_ref(), &cfg, &high_sample, &mut state);
+        update_pressure_state(
+            &stats,
+            shared.as_ref(),
+            &cfg,
+            true,
+            &high_sample,
+            &mut state,
+        );
         assert!(state.active);
 
         let low_sample = PressureSample {
@@ -670,11 +792,11 @@ mod tests {
             accept_timeout_delta: 0,
             me_queue_pressure_delta: 0,
         };
-        update_pressure_state(&stats, shared.as_ref(), &cfg, &low_sample, &mut state);
+        update_pressure_state(&stats, shared.as_ref(), &cfg, true, &low_sample, &mut state);
         assert!(state.active);
-        update_pressure_state(&stats, shared.as_ref(), &cfg, &low_sample, &mut state);
+        update_pressure_state(&stats, shared.as_ref(), &cfg, true, &low_sample, &mut state);
         assert!(state.active);
-        update_pressure_state(&stats, shared.as_ref(), &cfg, &low_sample, &mut state);
+        update_pressure_state(&stats, shared.as_ref(), &cfg, true, &low_sample, &mut state);
 
         assert!(!state.active);
         assert!(!shared.conntrack_pressure_active());
@@ -695,7 +817,7 @@ mod tests {
             me_queue_pressure_delta: 10,
         };
 
-        update_pressure_state(&stats, shared.as_ref(), &cfg, &sample, &mut state);
+        update_pressure_state(&stats, shared.as_ref(), &cfg, false, &sample, &mut state);
 
         assert!(!state.active);
         assert!(!shared.conntrack_pressure_active());

src/daemon/mod.rs

@@ -8,6 +8,7 @@ use std::io::{self, Read, Write};
 use std::os::unix::fs::OpenOptionsExt;
 use std::path::{Path, PathBuf};
 
+use nix::errno::Errno;
 use nix::fcntl::{Flock, FlockArg};
 use nix::unistd::{self, ForkResult, Gid, Pid, Uid, chdir, close, fork, getpid, setsid};
 use tracing::{debug, info, warn};
@@ -157,15 +158,15 @@ fn redirect_stdio_to_devnull() -> Result<(), DaemonError> {
     unsafe {
         // Redirect stdin (fd 0)
         if libc::dup2(devnull_fd, 0) < 0 {
-            return Err(DaemonError::RedirectFailed(nix::errno::Errno::last()));
+            return Err(DaemonError::RedirectFailed(Errno::last()));
         }
         // Redirect stdout (fd 1)
         if libc::dup2(devnull_fd, 1) < 0 {
-            return Err(DaemonError::RedirectFailed(nix::errno::Errno::last()));
+            return Err(DaemonError::RedirectFailed(Errno::last()));
         }
         // Redirect stderr (fd 2)
         if libc::dup2(devnull_fd, 2) < 0 {
-            return Err(DaemonError::RedirectFailed(nix::errno::Errno::last()));
+            return Err(DaemonError::RedirectFailed(Errno::last()));
         }
     }
 
@@ -337,40 +338,97 @@ fn is_process_running(pid: i32) -> bool {
     nix::sys::signal::kill(Pid::from_raw(pid), None).is_ok()
 }
 
+// macOS gates nix::unistd::setgroups differently in the current dependency set,
+// so call libc directly there while preserving the original nix path elsewhere.
+fn set_supplementary_groups(gid: Gid) -> Result<(), nix::Error> {
+    #[cfg(target_os = "macos")]
+    {
+        let groups = [gid.as_raw()];
+        let rc = unsafe {
+            libc::setgroups(
+                i32::try_from(groups.len()).expect("single supplementary group must fit in c_int"),
+                groups.as_ptr(),
+            )
+        };
+        if rc == 0 { Ok(()) } else { Err(Errno::last()) }
+    }
+
+    #[cfg(not(target_os = "macos"))]
+    {
+        unistd::setgroups(&[gid])
+    }
+}
+
 /// Drops privileges to the specified user and group.
 ///
-/// This should be called after binding privileged ports but before
-/// entering the main event loop.
-pub fn drop_privileges(user: Option<&str>, group: Option<&str>) -> Result<(), DaemonError> {
-    // Look up group first (need to do this while still root)
+/// This should be called after binding privileged ports but before entering
+/// the main event loop.
+pub fn drop_privileges(
+    user: Option<&str>,
+    group: Option<&str>,
+    pid_file: Option<&PidFile>,
+) -> Result<(), DaemonError> {
     let target_gid = if let Some(group_name) = group {
         Some(lookup_group(group_name)?)
     } else if let Some(user_name) = user {
-        // If no group specified but user is, use user's primary group
         Some(lookup_user_primary_gid(user_name)?)
     } else {
         None
     };
 
-    // Look up user
     let target_uid = if let Some(user_name) = user {
         Some(lookup_user(user_name)?)
     } else {
         None
     };
 
-    // Drop privileges: set GID first, then UID
-    // (Setting UID first would prevent us from setting GID)
+    if (target_uid.is_some() || target_gid.is_some())
+        && let Some(file) = pid_file.and_then(|pid| pid.file.as_ref())
+    {
+        unistd::fchown(file, target_uid, target_gid).map_err(DaemonError::PrivilegeDrop)?;
+    }
+
     if let Some(gid) = target_gid {
         unistd::setgid(gid).map_err(DaemonError::PrivilegeDrop)?;
-        // Also set supplementary groups to just this one
-        unistd::setgroups(&[gid]).map_err(DaemonError::PrivilegeDrop)?;
+        set_supplementary_groups(gid).map_err(DaemonError::PrivilegeDrop)?;
         info!(gid = gid.as_raw(), "Dropped group privileges");
     }
 
     if let Some(uid) = target_uid {
         unistd::setuid(uid).map_err(DaemonError::PrivilegeDrop)?;
         info!(uid = uid.as_raw(), "Dropped user privileges");
+
+        if uid.as_raw() != 0
+            && let Some(pid) = pid_file
+        {
+            let parent = pid.path.parent().unwrap_or(Path::new("."));
+            let probe_path = parent.join(format!(
+                ".telemt_pid_probe_{}_{}",
+                std::process::id(),
+                getpid().as_raw()
+            ));
+            OpenOptions::new()
+                .write(true)
+                .create_new(true)
+                .mode(0o600)
+                .open(&probe_path)
+                .map_err(|e| {
+                    DaemonError::PidFile(format!(
+                        "cannot create probe in PID directory {} as uid {} (pid cleanup will fail): {}",
+                        parent.display(),
+                        uid.as_raw(),
+                        e
+                    ))
+                })?;
+            fs::remove_file(&probe_path).map_err(|e| {
+                DaemonError::PidFile(format!(
+                    "cannot remove probe in PID directory {} as uid {} (pid cleanup will fail): {}",
+                    parent.display(),
+                    uid.as_raw(),
+                    e
+                ))
+            })?;
+        }
     }
 
     Ok(())

src/error.rs

@@ -222,6 +222,21 @@ pub enum ProxyError {
     #[error("Proxy error: {0}")]
     Proxy(String),
 
+    #[error("ME connection lost")]
+    MiddleConnectionLost,
+
+    #[error("Session terminated")]
+    RouteSwitched,
+
+    #[error("Traffic budget wait cancelled")]
+    TrafficBudgetWaitCancelled,
+
+    #[error("Traffic budget wait deadline exceeded")]
+    TrafficBudgetWaitDeadlineExceeded,
+
+    #[error("ME client writer cancelled")]
+    MiddleClientWriterCancelled,
+
     // ============= Config Errors =============
     #[error("Config error: {0}")]
     Config(String),

src/healthcheck.rs

@@ -0,0 +1,211 @@
+use std::io::{Read, Write};
+use std::net::{Ipv4Addr, Ipv6Addr, SocketAddr, TcpStream};
+use std::time::Duration;
+
+use serde_json::Value;
+
+use crate::config::ProxyConfig;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum HealthcheckMode {
+    Liveness,
+    Ready,
+}
+
+impl HealthcheckMode {
+    pub(crate) fn from_cli_arg(value: &str) -> Option<Self> {
+        match value {
+            "liveness" => Some(Self::Liveness),
+            "ready" => Some(Self::Ready),
+            _ => None,
+        }
+    }
+
+    fn request_path(self) -> &'static str {
+        match self {
+            Self::Liveness => "/v1/health",
+            Self::Ready => "/v1/health/ready",
+        }
+    }
+}
+
+pub(crate) fn run(config_path: &str, mode: HealthcheckMode) -> i32 {
+    match run_inner(config_path, mode) {
+        Ok(()) => 0,
+        Err(error) => {
+            eprintln!("[telemt] healthcheck failed: {error}");
+            1
+        }
+    }
+}
+
+fn run_inner(config_path: &str, mode: HealthcheckMode) -> Result<(), String> {
+    let config =
+        ProxyConfig::load(config_path).map_err(|error| format!("config load failed: {error}"))?;
+    let api_cfg = &config.server.api;
+    if !api_cfg.enabled {
+        return Ok(());
+    }
+
+    let listen: SocketAddr = api_cfg
+        .listen
+        .parse()
+        .map_err(|_| format!("invalid API listen address: {}", api_cfg.listen))?;
+    if listen.port() == 0 {
+        return Err("API listen port is 0".to_string());
+    }
+    let target = probe_target(listen);
+
+    let mut stream = TcpStream::connect_timeout(&target, Duration::from_secs(2))
+        .map_err(|error| format!("connect {target} failed: {error}"))?;
+    stream
+        .set_read_timeout(Some(Duration::from_secs(2)))
+        .map_err(|error| format!("set read timeout failed: {error}"))?;
+    stream
+        .set_write_timeout(Some(Duration::from_secs(2)))
+        .map_err(|error| format!("set write timeout failed: {error}"))?;
+
+    let request = build_request(target, mode.request_path(), &api_cfg.auth_header);
+    stream
+        .write_all(request.as_bytes())
+        .map_err(|error| format!("request write failed: {error}"))?;
+    stream
+        .flush()
+        .map_err(|error| format!("request flush failed: {error}"))?;
+
+    let mut raw_response = Vec::new();
+    stream
+        .read_to_end(&mut raw_response)
+        .map_err(|error| format!("response read failed: {error}"))?;
+    let response =
+        String::from_utf8(raw_response).map_err(|_| "response is not valid UTF-8".to_string())?;
+
+    let (status_code, body) = split_response(&response)?;
+    if status_code != 200 {
+        return Err(format!("HTTP status {status_code}"));
+    }
+
+    validate_payload(mode, body)?;
+    Ok(())
+}
+
+fn probe_target(listen: SocketAddr) -> SocketAddr {
+    match listen {
+        SocketAddr::V4(addr) => {
+            let ip = if addr.ip().is_unspecified() {
+                Ipv4Addr::LOCALHOST
+            } else {
+                *addr.ip()
+            };
+            SocketAddr::from((ip, addr.port()))
+        }
+        SocketAddr::V6(addr) => {
+            let ip = if addr.ip().is_unspecified() {
+                Ipv6Addr::LOCALHOST
+            } else {
+                *addr.ip()
+            };
+            SocketAddr::from((ip, addr.port()))
+        }
+    }
+}
+
+fn build_request(target: SocketAddr, path: &str, auth_header: &str) -> String {
+    let mut request = format!(
+        "GET {path} HTTP/1.1\r\nHost: {}\r\nConnection: close\r\n",
+        target
+    );
+    if !auth_header.is_empty() {
+        request.push_str("Authorization: ");
+        request.push_str(auth_header);
+        request.push_str("\r\n");
+    }
+    request.push_str("\r\n");
+    request
+}
+
+fn split_response(response: &str) -> Result<(u16, &str), String> {
+    let header_end = response
+        .find("\r\n\r\n")
+        .ok_or_else(|| "invalid HTTP response headers".to_string())?;
+    let header = &response[..header_end];
+    let body = &response[header_end + 4..];
+    let status_line = header
+        .lines()
+        .next()
+        .ok_or_else(|| "missing HTTP status line".to_string())?;
+    let status_code = parse_status_code(status_line)?;
+    Ok((status_code, body))
+}
+
+fn parse_status_code(status_line: &str) -> Result<u16, String> {
+    let mut parts = status_line.split_whitespace();
+    let version = parts
+        .next()
+        .ok_or_else(|| "missing HTTP version".to_string())?;
+    if !version.starts_with("HTTP/") {
+        return Err(format!("invalid HTTP status line: {status_line}"));
+    }
+    let code = parts
+        .next()
+        .ok_or_else(|| "missing HTTP status code".to_string())?;
+    code.parse::<u16>()
+        .map_err(|_| format!("invalid HTTP status code: {code}"))
+}
+
+fn validate_payload(mode: HealthcheckMode, body: &str) -> Result<(), String> {
+    let payload: Value =
+        serde_json::from_str(body).map_err(|_| "response body is not valid JSON".to_string())?;
+    if payload.get("ok").and_then(Value::as_bool) != Some(true) {
+        return Err("response JSON has ok=false".to_string());
+    }
+
+    let data = payload
+        .get("data")
+        .ok_or_else(|| "response JSON has no data field".to_string())?;
+    match mode {
+        HealthcheckMode::Liveness => {
+            if data.get("status").and_then(Value::as_str) != Some("ok") {
+                return Err("liveness status is not ok".to_string());
+            }
+        }
+        HealthcheckMode::Ready => {
+            if data.get("ready").and_then(Value::as_bool) != Some(true) {
+                return Err("readiness flag is false".to_string());
+            }
+        }
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{HealthcheckMode, parse_status_code, split_response, validate_payload};
+
+    #[test]
+    fn parse_status_code_reads_http_200() {
+        let status = parse_status_code("HTTP/1.1 200 OK").expect("must parse status");
+        assert_eq!(status, 200);
+    }
+
+    #[test]
+    fn split_response_extracts_status_and_body() {
+        let response = "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\n\r\n{\"ok\":true}";
+        let (status, body) = split_response(response).expect("must split response");
+        assert_eq!(status, 200);
+        assert_eq!(body, "{\"ok\":true}");
+    }
+
+    #[test]
+    fn validate_payload_accepts_liveness_contract() {
+        let body = "{\"ok\":true,\"data\":{\"status\":\"ok\"}}";
+        validate_payload(HealthcheckMode::Liveness, body).expect("liveness payload must pass");
+    }
+
+    #[test]
+    fn validate_payload_rejects_not_ready() {
+        let body = "{\"ok\":true,\"data\":{\"ready\":false}}";
+        let result = validate_payload(HealthcheckMode::Ready, body);
+        assert!(result.is_err());
+    }
+}

src/ip_tracker.rs

@@ -9,30 +9,53 @@ use std::sync::Mutex;
 use std::sync::atomic::{AtomicU64, Ordering};
 use std::time::{Duration, Instant};
 
-use tokio::sync::{Mutex as AsyncMutex, RwLock};
+use tokio::sync::{Mutex as AsyncMutex, RwLock, RwLockWriteGuard};
 
 use crate::config::UserMaxUniqueIpsMode;
 
+const CLEANUP_DRAIN_BATCH_LIMIT: usize = 1024;
+const MAX_ACTIVE_IP_ENTRIES: u64 = 131_072;
+const MAX_RECENT_IP_ENTRIES: u64 = 262_144;
+
+/// Tracks active and recent client IPs for per-user admission control.
 #[derive(Debug, Clone)]
 pub struct UserIpTracker {
     active_ips: Arc<RwLock<HashMap<String, HashMap<IpAddr, usize>>>>,
     recent_ips: Arc<RwLock<HashMap<String, HashMap<IpAddr, Instant>>>>,
+    active_entry_count: Arc<AtomicU64>,
+    recent_entry_count: Arc<AtomicU64>,
+    active_cap_rejects: Arc<AtomicU64>,
+    recent_cap_rejects: Arc<AtomicU64>,
+    cleanup_deferred_releases: Arc<AtomicU64>,
     max_ips: Arc<RwLock<HashMap<String, usize>>>,
     default_max_ips: Arc<RwLock<usize>>,
     limit_mode: Arc<RwLock<UserMaxUniqueIpsMode>>,
     limit_window: Arc<RwLock<Duration>>,
     last_compact_epoch_secs: Arc<AtomicU64>,
-    cleanup_queue: Arc<Mutex<Vec<(String, IpAddr)>>>,
+    cleanup_queue_len: Arc<AtomicU64>,
+    cleanup_queue: Arc<Mutex<HashMap<(String, IpAddr), usize>>>,
     cleanup_drain_lock: Arc<AsyncMutex<()>>,
 }
 
+/// Point-in-time memory counters for user/IP limiter state.
 #[derive(Debug, Clone, Copy)]
 pub struct UserIpTrackerMemoryStats {
+    /// Number of users with active IP state.
     pub active_users: usize,
+    /// Number of users with recent IP state.
     pub recent_users: usize,
+    /// Number of active `(user, ip)` entries.
     pub active_entries: usize,
+    /// Number of recent-window `(user, ip)` entries.
     pub recent_entries: usize,
+    /// Number of deferred disconnect cleanups waiting to be drained.
     pub cleanup_queue_len: usize,
+    /// Number of new connections rejected by the global active-entry cap.
+    pub active_cap_rejects: u64,
+    /// Number of new connections rejected by the global recent-entry cap.
+    pub recent_cap_rejects: u64,
+    /// Number of release cleanups deferred through the cleanup queue.
+    pub cleanup_deferred_releases: u64,
 }
 
 impl UserIpTracker {
@@ -40,22 +63,81 @@ impl UserIpTracker {
         Self {
             active_ips: Arc::new(RwLock::new(HashMap::new())),
             recent_ips: Arc::new(RwLock::new(HashMap::new())),
+            active_entry_count: Arc::new(AtomicU64::new(0)),
+            recent_entry_count: Arc::new(AtomicU64::new(0)),
+            active_cap_rejects: Arc::new(AtomicU64::new(0)),
+            recent_cap_rejects: Arc::new(AtomicU64::new(0)),
+            cleanup_deferred_releases: Arc::new(AtomicU64::new(0)),
             max_ips: Arc::new(RwLock::new(HashMap::new())),
             default_max_ips: Arc::new(RwLock::new(0)),
             limit_mode: Arc::new(RwLock::new(UserMaxUniqueIpsMode::ActiveWindow)),
             limit_window: Arc::new(RwLock::new(Duration::from_secs(30))),
             last_compact_epoch_secs: Arc::new(AtomicU64::new(0)),
-            cleanup_queue: Arc::new(Mutex::new(Vec::new())),
+            cleanup_queue_len: Arc::new(AtomicU64::new(0)),
+            cleanup_queue: Arc::new(Mutex::new(HashMap::new())),
             cleanup_drain_lock: Arc::new(AsyncMutex::new(())),
         }
     }
 
+    fn decrement_counter(counter: &AtomicU64, amount: usize) {
+        if amount == 0 {
+            return;
+        }
+        let amount = amount as u64;
+        let _ = counter.fetch_update(Ordering::AcqRel, Ordering::Relaxed, |current| {
+            Some(current.saturating_sub(amount))
+        });
+    }
+
+    fn apply_active_cleanup(
+        active_ips: &mut HashMap<String, HashMap<IpAddr, usize>>,
+        user: &str,
+        ip: IpAddr,
+        pending_count: usize,
+    ) -> usize {
+        if pending_count == 0 {
+            return 0;
+        }
+
+        let mut remove_user = false;
+        let mut removed_active_entries = 0usize;
+        if let Some(user_ips) = active_ips.get_mut(user) {
+            if let Some(count) = user_ips.get_mut(&ip) {
+                if *count > pending_count {
+                    *count -= pending_count;
+                } else if user_ips.remove(&ip).is_some() {
+                    removed_active_entries = 1;
+                }
+            }
+            remove_user = user_ips.is_empty();
+        }
+        if remove_user {
+            active_ips.remove(user);
+        }
+        removed_active_entries
+    }
+
+    /// Queues a deferred active IP cleanup for a later async drain.
     pub fn enqueue_cleanup(&self, user: String, ip: IpAddr) {
         match self.cleanup_queue.lock() {
-            Ok(mut queue) => queue.push((user, ip)),
+            Ok(mut queue) => {
+                let count = queue.entry((user, ip)).or_insert(0);
+                if *count == 0 {
+                    self.cleanup_queue_len.fetch_add(1, Ordering::Relaxed);
+                }
+                *count = count.saturating_add(1);
+                self.cleanup_deferred_releases
+                    .fetch_add(1, Ordering::Relaxed);
+            }
             Err(poisoned) => {
                 let mut queue = poisoned.into_inner();
-                queue.push((user.clone(), ip));
+                let count = queue.entry((user.clone(), ip)).or_insert(0);
+                if *count == 0 {
+                    self.cleanup_queue_len.fetch_add(1, Ordering::Relaxed);
+                }
+                *count = count.saturating_add(1);
+                self.cleanup_deferred_releases
+                    .fetch_add(1, Ordering::Relaxed);
                 self.cleanup_queue.clear_poison();
                 tracing::warn!(
                     "UserIpTracker cleanup_queue lock poisoned; recovered and enqueued IP cleanup for {} ({})",
@@ -75,21 +157,38 @@ impl UserIpTracker {
     }
 
     #[cfg(test)]
-    pub(crate) fn cleanup_queue_mutex_for_tests(&self) -> Arc<Mutex<Vec<(String, IpAddr)>>> {
+    pub(crate) fn cleanup_queue_mutex_for_tests(
+        &self,
+    ) -> Arc<Mutex<HashMap<(String, IpAddr), usize>>> {
         Arc::clone(&self.cleanup_queue)
     }
 
     pub(crate) async fn drain_cleanup_queue(&self) {
-        // Serialize queue draining and active-IP mutation so check-and-add cannot
-        // observe stale active entries that are already queued for removal.
-        let _drain_guard = self.cleanup_drain_lock.lock().await;
+        if self.cleanup_queue_len.load(Ordering::Relaxed) == 0 {
+            return;
+        }
+        let Ok(_drain_guard) = self.cleanup_drain_lock.try_lock() else {
+            return;
+        };
+
         let to_remove = {
             match self.cleanup_queue.lock() {
                 Ok(mut queue) => {
                     if queue.is_empty() {
                         return;
                     }
-                    std::mem::take(&mut *queue)
+                    let mut drained =
+                        HashMap::with_capacity(queue.len().min(CLEANUP_DRAIN_BATCH_LIMIT));
+                    for _ in 0..CLEANUP_DRAIN_BATCH_LIMIT {
+                        let Some(key) = queue.keys().next().cloned() else {
+                            break;
+                        };
+                        if let Some(count) = queue.remove(&key) {
+                            self.cleanup_queue_len.fetch_sub(1, Ordering::Relaxed);
+                            drained.insert(key, count);
+                        }
+                    }
+                    drained
                 }
                 Err(poisoned) => {
                     let mut queue = poisoned.into_inner();
@@ -97,28 +196,34 @@ impl UserIpTracker {
                         self.cleanup_queue.clear_poison();
                         return;
                     }
-                    let drained = std::mem::take(&mut *queue);
+                    let mut drained =
+                        HashMap::with_capacity(queue.len().min(CLEANUP_DRAIN_BATCH_LIMIT));
+                    for _ in 0..CLEANUP_DRAIN_BATCH_LIMIT {
+                        let Some(key) = queue.keys().next().cloned() else {
+                            break;
+                        };
+                        if let Some(count) = queue.remove(&key) {
+                            self.cleanup_queue_len.fetch_sub(1, Ordering::Relaxed);
+                            drained.insert(key, count);
+                        }
+                    }
                     self.cleanup_queue.clear_poison();
                     drained
                 }
             }
         };
+        if to_remove.is_empty() {
+            return;
+        }
 
         let mut active_ips = self.active_ips.write().await;
-        for (user, ip) in to_remove {
-            if let Some(user_ips) = active_ips.get_mut(&user) {
-                if let Some(count) = user_ips.get_mut(&ip) {
-                    if *count > 1 {
-                        *count -= 1;
-                    } else {
-                        user_ips.remove(&ip);
-                    }
-                }
-                if user_ips.is_empty() {
-                    active_ips.remove(&user);
-                }
-            }
+        let mut removed_active_entries = 0usize;
+        for ((user, ip), pending_count) in to_remove {
+            removed_active_entries = removed_active_entries.saturating_add(
+                Self::apply_active_cleanup(&mut active_ips, &user, ip, pending_count),
+            );
         }
+        Self::decrement_counter(&self.active_entry_count, removed_active_entries);
     }
 
     fn now_epoch_secs() -> u64 {
@@ -128,6 +233,24 @@ impl UserIpTracker {
             .as_secs()
     }
 
+    async fn active_and_recent_write(
+        &self,
+    ) -> (
+        RwLockWriteGuard<'_, HashMap<String, HashMap<IpAddr, usize>>>,
+        RwLockWriteGuard<'_, HashMap<String, HashMap<IpAddr, Instant>>>,
+    ) {
+        loop {
+            let active_ips = self.active_ips.write().await;
+            match self.recent_ips.try_write() {
+                Ok(recent_ips) => return (active_ips, recent_ips),
+                Err(_) => {
+                    drop(active_ips);
+                    tokio::task::yield_now().await;
+                }
+            }
+        }
+    }
+
     async fn maybe_compact_empty_users(&self) {
         const COMPACT_INTERVAL_SECS: u64 = 60;
         let now_epoch_secs = Self::now_epoch_secs();
@@ -148,14 +271,16 @@ impl UserIpTracker {
             return;
         }
 
-        let mut active_ips = self.active_ips.write().await;
-        let mut recent_ips = self.recent_ips.write().await;
         let window = *self.limit_window.read().await;
         let now = Instant::now();
+        let (mut active_ips, mut recent_ips) = self.active_and_recent_write().await;
 
+        let mut pruned_recent_entries = 0usize;
         for user_recent in recent_ips.values_mut() {
-            Self::prune_recent(user_recent, now, window);
+            pruned_recent_entries =
+                pruned_recent_entries.saturating_add(Self::prune_recent(user_recent, now, window));
         }
+        Self::decrement_counter(&self.recent_entry_count, pruned_recent_entries);
 
         let mut users =
             Vec::<String>::with_capacity(active_ips.len().saturating_add(recent_ips.len()));
@@ -182,12 +307,17 @@ impl UserIpTracker {
         }
     }
 
+    pub async fn run_periodic_maintenance(self: Arc<Self>) {
+        let mut interval = tokio::time::interval(Duration::from_secs(1));
+        loop {
+            interval.tick().await;
+            self.drain_cleanup_queue().await;
+            self.maybe_compact_empty_users().await;
+        }
+    }
+
     pub async fn memory_stats(&self) -> UserIpTrackerMemoryStats {
-        let cleanup_queue_len = self
-            .cleanup_queue
-            .lock()
-            .unwrap_or_else(|poisoned| poisoned.into_inner())
-            .len();
+        let cleanup_queue_len = self.cleanup_queue_len.load(Ordering::Relaxed) as usize;
         let active_ips = self.active_ips.read().await;
         let recent_ips = self.recent_ips.read().await;
         let active_entries = active_ips.values().map(HashMap::len).sum();
@@ -199,6 +329,9 @@ impl UserIpTracker {
             active_entries,
             recent_entries,
             cleanup_queue_len,
+            active_cap_rejects: self.active_cap_rejects.load(Ordering::Relaxed),
+            recent_cap_rejects: self.recent_cap_rejects.load(Ordering::Relaxed),
+            cleanup_deferred_releases: self.cleanup_deferred_releases.load(Ordering::Relaxed),
         }
     }
 
@@ -229,11 +362,17 @@ impl UserIpTracker {
         max_ips.clone_from(limits);
     }
 
-    fn prune_recent(user_recent: &mut HashMap<IpAddr, Instant>, now: Instant, window: Duration) {
+    fn prune_recent(
+        user_recent: &mut HashMap<IpAddr, Instant>,
+        now: Instant,
+        window: Duration,
+    ) -> usize {
         if user_recent.is_empty() {
-            return;
+            return 0;
         }
+        let before = user_recent.len();
         user_recent.retain(|_, seen_at| now.duration_since(*seen_at) <= window);
+        before.saturating_sub(user_recent.len())
     }
 
     pub async fn check_and_add(&self, username: &str, ip: IpAddr) -> Result<(), String> {
@@ -252,26 +391,40 @@ impl UserIpTracker {
         let window = *self.limit_window.read().await;
         let now = Instant::now();
 
-        let mut active_ips = self.active_ips.write().await;
+        let (mut active_ips, mut recent_ips) = self.active_and_recent_write().await;
         let user_active = active_ips
             .entry(username.to_string())
             .or_insert_with(HashMap::new);
-
-        let mut recent_ips = self.recent_ips.write().await;
         let user_recent = recent_ips
             .entry(username.to_string())
             .or_insert_with(HashMap::new);
-        Self::prune_recent(user_recent, now, window);
+        let pruned_recent_entries = Self::prune_recent(user_recent, now, window);
+        Self::decrement_counter(&self.recent_entry_count, pruned_recent_entries);
+        let recent_contains_ip = user_recent.contains_key(&ip);
 
         if let Some(count) = user_active.get_mut(&ip) {
+            if !recent_contains_ip
+                && self.recent_entry_count.load(Ordering::Relaxed) >= MAX_RECENT_IP_ENTRIES
+            {
+                self.recent_cap_rejects.fetch_add(1, Ordering::Relaxed);
+                return Err(format!(
+                    "IP tracker recent entry cap reached: entries={}/{}",
+                    self.recent_entry_count.load(Ordering::Relaxed),
+                    MAX_RECENT_IP_ENTRIES
+                ));
+            }
             *count = count.saturating_add(1);
-            user_recent.insert(ip, now);
+            if user_recent.insert(ip, now).is_none() {
+                self.recent_entry_count.fetch_add(1, Ordering::Relaxed);
+            }
             return Ok(());
         }
 
+        let is_new_ip = !recent_contains_ip;
+
         if let Some(limit) = limit {
             let active_limit_reached = user_active.len() >= limit;
-            let recent_limit_reached = user_recent.len() >= limit;
+            let recent_limit_reached = user_recent.len() >= limit && is_new_ip;
             let deny = match mode {
                 UserMaxUniqueIpsMode::ActiveWindow => active_limit_reached,
                 UserMaxUniqueIpsMode::TimeWindow => recent_limit_reached,
@@ -291,30 +444,62 @@ impl UserIpTracker {
             }
         }
 
-        user_active.insert(ip, 1);
-        user_recent.insert(ip, now);
+        if self.active_entry_count.load(Ordering::Relaxed) >= MAX_ACTIVE_IP_ENTRIES {
+            self.active_cap_rejects.fetch_add(1, Ordering::Relaxed);
+            return Err(format!(
+                "IP tracker active entry cap reached: entries={}/{}",
+                self.active_entry_count.load(Ordering::Relaxed),
+                MAX_ACTIVE_IP_ENTRIES
+            ));
+        }
+        if is_new_ip && self.recent_entry_count.load(Ordering::Relaxed) >= MAX_RECENT_IP_ENTRIES {
+            self.recent_cap_rejects.fetch_add(1, Ordering::Relaxed);
+            return Err(format!(
+                "IP tracker recent entry cap reached: entries={}/{}",
+                self.recent_entry_count.load(Ordering::Relaxed),
+                MAX_RECENT_IP_ENTRIES
+            ));
+        }
+
+        if user_active.insert(ip, 1).is_none() {
+            self.active_entry_count.fetch_add(1, Ordering::Relaxed);
+        }
+        if user_recent.insert(ip, now).is_none() {
+            self.recent_entry_count.fetch_add(1, Ordering::Relaxed);
+        }
         Ok(())
     }
 
     pub async fn remove_ip(&self, username: &str, ip: IpAddr) {
         self.maybe_compact_empty_users().await;
         let mut active_ips = self.active_ips.write().await;
+        let mut removed_active_entries = 0usize;
         if let Some(user_ips) = active_ips.get_mut(username) {
             if let Some(count) = user_ips.get_mut(&ip) {
                 if *count > 1 {
                     *count -= 1;
                 } else {
-                    user_ips.remove(&ip);
+                    if user_ips.remove(&ip).is_some() {
+                        removed_active_entries = 1;
+                    }
                 }
             }
             if user_ips.is_empty() {
                 active_ips.remove(username);
             }
         }
+        Self::decrement_counter(&self.active_entry_count, removed_active_entries);
     }
 
     pub async fn get_recent_counts_for_users(&self, users: &[String]) -> HashMap<String, usize> {
         self.drain_cleanup_queue().await;
+        self.get_recent_counts_for_users_snapshot(users).await
+    }
+
+    pub(crate) async fn get_recent_counts_for_users_snapshot(
+        &self,
+        users: &[String],
+    ) -> HashMap<String, usize> {
         let window = *self.limit_window.read().await;
         let now = Instant::now();
         let recent_ips = self.recent_ips.read().await;
@@ -389,19 +574,29 @@ impl UserIpTracker {
 
     pub async fn get_stats(&self) -> Vec<(String, usize, usize)> {
         self.drain_cleanup_queue().await;
+        self.get_stats_snapshot().await
+    }
+
+    pub(crate) async fn get_stats_snapshot(&self) -> Vec<(String, usize, usize)> {
         let active_ips = self.active_ips.read().await;
+        let active_counts = active_ips
+            .iter()
+            .map(|(username, user_ips)| (username.clone(), user_ips.len()))
+            .collect::<Vec<_>>();
+        drop(active_ips);
+
         let max_ips = self.max_ips.read().await;
         let default_max_ips = *self.default_max_ips.read().await;
 
-        let mut stats = Vec::new();
-        for (username, user_ips) in active_ips.iter() {
+        let mut stats = Vec::with_capacity(active_counts.len());
+        for (username, active_count) in active_counts {
             let limit = max_ips
-                .get(username)
+                .get(&username)
                 .copied()
                 .filter(|limit| *limit > 0)
                 .or((default_max_ips > 0).then_some(default_max_ips))
                 .unwrap_or(0);
-            stats.push((username.clone(), user_ips.len(), limit));
+            stats.push((username, active_count, limit));
         }
 
         stats.sort_by(|a, b| a.0.cmp(&b.0));
@@ -410,20 +605,30 @@ impl UserIpTracker {
 
     pub async fn clear_user_ips(&self, username: &str) {
         let mut active_ips = self.active_ips.write().await;
-        active_ips.remove(username);
+        let removed_active_entries = active_ips
+            .remove(username)
+            .map(|ips| ips.len())
+            .unwrap_or(0);
         drop(active_ips);
+        Self::decrement_counter(&self.active_entry_count, removed_active_entries);
 
         let mut recent_ips = self.recent_ips.write().await;
-        recent_ips.remove(username);
+        let removed_recent_entries = recent_ips
+            .remove(username)
+            .map(|ips| ips.len())
+            .unwrap_or(0);
+        Self::decrement_counter(&self.recent_entry_count, removed_recent_entries);
     }
 
     pub async fn clear_all(&self) {
         let mut active_ips = self.active_ips.write().await;
         active_ips.clear();
         drop(active_ips);
+        self.active_entry_count.store(0, Ordering::Relaxed);
 
         let mut recent_ips = self.recent_ips.write().await;
         recent_ips.clear();
+        self.recent_entry_count.store(0, Ordering::Relaxed);
     }
 
     pub async fn is_ip_active(&self, username: &str, ip: IpAddr) -> bool {
@@ -851,4 +1056,19 @@ mod tests {
             .unwrap_or(false);
         assert!(!stale_exists);
     }
+
+    #[tokio::test]
+    async fn test_time_window_allows_same_ip_reconnect() {
+        let tracker = UserIpTracker::new();
+        tracker.set_user_limit("test_user", 1).await;
+        tracker
+            .set_limit_policy(UserMaxUniqueIpsMode::TimeWindow, 1)
+            .await;
+
+        let ip1 = test_ipv4(10, 4, 0, 1);
+
+        assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+        tracker.remove_ip("test_user", ip1).await;
+        assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+    }
 }

src/logging.rs

@@ -88,8 +88,10 @@ pub fn init_logging(
             // Use a custom fmt layer that writes to syslog
             let fmt_layer = fmt::Layer::default()
                 .with_ansi(false)
-                .with_target(true)
-                .with_writer(SyslogWriter::new);
+                .with_target(false)
+                .with_level(false)
+                .without_time()
+                .with_writer(SyslogMakeWriter::new());
 
             tracing_subscriber::registry()
                 .with(filter_layer)
@@ -137,12 +139,17 @@ pub fn init_logging(
 
 /// Syslog writer for tracing.
 #[cfg(unix)]
+#[derive(Clone, Copy)]
+struct SyslogMakeWriter;
+
+#[cfg(unix)]
+#[derive(Clone, Copy)]
 struct SyslogWriter {
-    _private: (),
+    priority: libc::c_int,
 }
 
 #[cfg(unix)]
-impl SyslogWriter {
+impl SyslogMakeWriter {
     fn new() -> Self {
         // Open syslog connection on first use
         static INIT: std::sync::Once = std::sync::Once::new();
@@ -153,7 +160,18 @@ impl SyslogWriter {
                 libc::openlog(ident, libc::LOG_PID | libc::LOG_NDELAY, libc::LOG_DAEMON);
             }
         });
-        Self { _private: () }
+        Self
+    }
+}
+
+#[cfg(unix)]
+fn syslog_priority_for_level(level: &tracing::Level) -> libc::c_int {
+    match *level {
+        tracing::Level::ERROR => libc::LOG_ERR,
+        tracing::Level::WARN => libc::LOG_WARNING,
+        tracing::Level::INFO => libc::LOG_INFO,
+        tracing::Level::DEBUG => libc::LOG_DEBUG,
+        tracing::Level::TRACE => libc::LOG_DEBUG,
     }
 }
 
@@ -168,26 +186,13 @@ impl std::io::Write for SyslogWriter {
             return Ok(buf.len());
         }
 
-        // Determine priority based on log level in the message
-        let priority = if msg.contains(" ERROR ") || msg.contains(" error ") {
-            libc::LOG_ERR
-        } else if msg.contains(" WARN ") || msg.contains(" warn ") {
-            libc::LOG_WARNING
-        } else if msg.contains(" INFO ") || msg.contains(" info ") {
-            libc::LOG_INFO
-        } else if msg.contains(" DEBUG ") || msg.contains(" debug ") {
-            libc::LOG_DEBUG
-        } else {
-            libc::LOG_INFO
-        };
-
         // Write to syslog
         let c_msg = std::ffi::CString::new(msg.as_bytes())
             .unwrap_or_else(|_| std::ffi::CString::new("(invalid utf8)").unwrap());
 
         unsafe {
             libc::syslog(
-                priority,
+                self.priority,
                 b"%s\0".as_ptr() as *const libc::c_char,
                 c_msg.as_ptr(),
             );
@@ -202,11 +207,19 @@ impl std::io::Write for SyslogWriter {
 }
 
 #[cfg(unix)]
-impl<'a> tracing_subscriber::fmt::MakeWriter<'a> for SyslogWriter {
+impl<'a> tracing_subscriber::fmt::MakeWriter<'a> for SyslogMakeWriter {
     type Writer = SyslogWriter;
 
     fn make_writer(&'a self) -> Self::Writer {
-        SyslogWriter::new()
+        SyslogWriter {
+            priority: libc::LOG_INFO,
+        }
+    }
+
+    fn make_writer_for(&'a self, meta: &tracing::Metadata<'_>) -> Self::Writer {
+        SyslogWriter {
+            priority: syslog_priority_for_level(meta.level()),
+        }
     }
 }
 
@@ -302,4 +315,29 @@ mod tests {
             LogDestination::Syslog
         ));
     }
+
+    #[cfg(unix)]
+    #[test]
+    fn test_syslog_priority_for_level_mapping() {
+        assert_eq!(
+            syslog_priority_for_level(&tracing::Level::ERROR),
+            libc::LOG_ERR
+        );
+        assert_eq!(
+            syslog_priority_for_level(&tracing::Level::WARN),
+            libc::LOG_WARNING
+        );
+        assert_eq!(
+            syslog_priority_for_level(&tracing::Level::INFO),
+            libc::LOG_INFO
+        );
+        assert_eq!(
+            syslog_priority_for_level(&tracing::Level::DEBUG),
+            libc::LOG_DEBUG
+        );
+        assert_eq!(
+            syslog_priority_for_level(&tracing::Level::TRACE),
+            libc::LOG_DEBUG
+        );
+    }
 }

src/maestro/admission.rs

@@ -17,6 +17,7 @@ pub(crate) async fn configure_admission_gate(
     route_runtime: Arc<RouteRuntimeController>,
     admission_tx: &watch::Sender<bool>,
     config_rx: watch::Receiver<Arc<ProxyConfig>>,
+    me_ready_rx: watch::Receiver<u64>,
 ) {
     if config.general.use_middle_proxy {
         if let Some(pool) = me_pool.as_ref() {
@@ -52,6 +53,7 @@ pub(crate) async fn configure_admission_gate(
             let admission_tx_gate = admission_tx.clone();
             let route_runtime_gate = route_runtime.clone();
             let mut config_rx_gate = config_rx.clone();
+            let mut me_ready_rx_gate = me_ready_rx;
             let mut admission_poll_ms = config.general.me_admission_poll_ms.max(1);
             tokio::spawn(async move {
                 let mut gate_open = initial_gate_open;
@@ -74,6 +76,11 @@ pub(crate) async fn configure_admission_gate(
                             fast_fallback_enabled = cfg.general.me2dc_fallback && cfg.general.me2dc_fast;
                             continue;
                         }
+                        changed = me_ready_rx_gate.changed() => {
+                            if changed.is_err() {
+                                break;
+                            }
+                        }
                         _ = tokio::time::sleep(Duration::from_millis(admission_poll_ms)) => {}
                     }
                     let ready = pool_for_gate.admission_ready_conditional_cast().await;

src/maestro/helpers.rs

@@ -1,6 +1,6 @@
 #![allow(clippy::items_after_test_module)]
 
-use std::path::PathBuf;
+use std::path::{Path, PathBuf};
 use std::time::Duration;
 
 use tokio::sync::watch;
@@ -17,13 +17,64 @@ use crate::transport::middle_proxy::{
 
 pub(crate) fn resolve_runtime_config_path(
     config_path_cli: &str,
-    startup_cwd: &std::path::Path,
+    startup_cwd: &Path,
+    config_path_explicit: bool,
 ) -> PathBuf {
-    let raw = PathBuf::from(config_path_cli);
-    let absolute = if raw.is_absolute() {
-        raw
+    if config_path_explicit {
+        let raw = PathBuf::from(config_path_cli);
+        let absolute = if raw.is_absolute() {
+            raw
+        } else {
+            startup_cwd.join(raw)
+        };
+        return absolute.canonicalize().unwrap_or(absolute);
+    }
+
+    let etc_telemt = std::path::Path::new("/etc/telemt");
+    let candidates = [
+        startup_cwd.join("config.toml"),
+        startup_cwd.join("telemt.toml"),
+        etc_telemt.join("telemt.toml"),
+        etc_telemt.join("config.toml"),
+    ];
+    for candidate in candidates {
+        if candidate.is_file() {
+            return candidate.canonicalize().unwrap_or(candidate);
+        }
+    }
+
+    startup_cwd.join("config.toml")
+}
+
+pub(crate) fn resolve_runtime_base_dir(
+    config_path: &Path,
+    startup_cwd: &Path,
+    config_path_explicit: bool,
+    data_path: Option<&Path>,
+) -> PathBuf {
+    if let Some(path) = data_path {
+        return normalize_runtime_dir(path, startup_cwd);
+    }
+
+    if startup_cwd != Path::new("/") {
+        return normalize_runtime_dir(startup_cwd, startup_cwd);
+    }
+
+    if config_path_explicit
+        && let Some(parent) = config_path.parent()
+        && !parent.as_os_str().is_empty()
+    {
+        return normalize_runtime_dir(parent, startup_cwd);
+    }
+
+    PathBuf::from("/etc/telemt")
+}
+
+fn normalize_runtime_dir(path: &Path, startup_cwd: &Path) -> PathBuf {
+    let absolute = if path.is_absolute() {
+        path.to_path_buf()
     } else {
-        startup_cwd.join(raw)
+        startup_cwd.join(path)
     };
     absolute.canonicalize().unwrap_or(absolute)
 }
@@ -31,6 +82,7 @@ pub(crate) fn resolve_runtime_config_path(
 /// Parsed CLI arguments.
 pub(crate) struct CliArgs {
     pub config_path: String,
+    pub config_path_explicit: bool,
     pub data_path: Option<PathBuf>,
     pub silent: bool,
     pub log_level: Option<String>,
@@ -39,6 +91,7 @@ pub(crate) struct CliArgs {
 
 pub(crate) fn parse_cli() -> CliArgs {
     let mut config_path = "config.toml".to_string();
+    let mut config_path_explicit = false;
     let mut data_path: Option<PathBuf> = None;
     let mut silent = false;
     let mut log_level: Option<String> = None;
@@ -74,6 +127,20 @@ pub(crate) fn parse_cli() -> CliArgs {
                     s.trim_start_matches("--data-path=").to_string(),
                 ));
             }
+            "--working-dir" => {
+                i += 1;
+                if i < args.len() {
+                    data_path = Some(PathBuf::from(args[i].clone()));
+                } else {
+                    eprintln!("Missing value for --working-dir");
+                    std::process::exit(0);
+                }
+            }
+            s if s.starts_with("--working-dir=") => {
+                data_path = Some(PathBuf::from(
+                    s.trim_start_matches("--working-dir=").to_string(),
+                ));
+            }
             "--silent" | "-s" => {
                 silent = true;
             }
@@ -111,13 +178,11 @@ pub(crate) fn parse_cli() -> CliArgs {
                     i += 1;
                 }
             }
-            s if s.starts_with("--working-dir") => {
-                if !s.contains('=') {
-                    i += 1;
-                }
-            }
             s if !s.starts_with('-') => {
-                config_path = s.to_string();
+                if !matches!(s, "run" | "start" | "stop" | "reload" | "status") {
+                    config_path = s.to_string();
+                    config_path_explicit = true;
+                }
             }
             other => {
                 eprintln!("Unknown option: {}", other);
@@ -128,6 +193,7 @@ pub(crate) fn parse_cli() -> CliArgs {
 
     CliArgs {
         config_path,
+        config_path_explicit,
         data_path,
         silent,
         log_level,
@@ -152,6 +218,7 @@ fn print_help() {
     eprintln!(
         "  --data-path <DIR>       Set data directory (absolute path; overrides config value)"
     );
+    eprintln!("  --working-dir <DIR>     Alias for --data-path");
     eprintln!("  --silent, -s            Suppress info logs");
     eprintln!("  --log-level <LEVEL>     debug|verbose|normal|silent");
     eprintln!("  --help, -h              Show this help");
@@ -197,7 +264,13 @@ fn print_help() {
 
 #[cfg(test)]
 mod tests {
-    use super::resolve_runtime_config_path;
+    use std::path::{Path, PathBuf};
+
+    use super::{
+        expected_handshake_close_description, is_expected_handshake_eof, peer_close_description,
+        resolve_runtime_base_dir, resolve_runtime_config_path,
+    };
+    use crate::error::{ProxyError, StreamError};
 
     #[test]
     fn resolve_runtime_config_path_anchors_relative_to_startup_cwd() {
@@ -210,7 +283,7 @@ mod tests {
         let target = startup_cwd.join("config.toml");
         std::fs::write(&target, " ").unwrap();
 
-        let resolved = resolve_runtime_config_path("config.toml", &startup_cwd);
+        let resolved = resolve_runtime_config_path("config.toml", &startup_cwd, true);
         assert_eq!(resolved, target.canonicalize().unwrap());
 
         let _ = std::fs::remove_file(&target);
@@ -226,11 +299,205 @@ mod tests {
         let startup_cwd = std::env::temp_dir().join(format!("telemt_cfg_path_missing_{nonce}"));
         std::fs::create_dir_all(&startup_cwd).unwrap();
 
-        let resolved = resolve_runtime_config_path("missing.toml", &startup_cwd);
+        let resolved = resolve_runtime_config_path("missing.toml", &startup_cwd, true);
         assert_eq!(resolved, startup_cwd.join("missing.toml"));
 
         let _ = std::fs::remove_dir(&startup_cwd);
     }
+
+    #[test]
+    fn resolve_runtime_config_path_uses_startup_candidates_when_not_explicit() {
+        let nonce = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        let startup_cwd =
+            std::env::temp_dir().join(format!("telemt_cfg_startup_candidates_{nonce}"));
+        std::fs::create_dir_all(&startup_cwd).unwrap();
+        let telemt = startup_cwd.join("telemt.toml");
+        std::fs::write(&telemt, " ").unwrap();
+
+        let resolved = resolve_runtime_config_path("config.toml", &startup_cwd, false);
+        assert_eq!(resolved, telemt.canonicalize().unwrap());
+
+        let _ = std::fs::remove_file(&telemt);
+        let _ = std::fs::remove_dir(&startup_cwd);
+    }
+
+    #[test]
+    fn resolve_runtime_config_path_defaults_to_startup_config_when_none_found() {
+        let nonce = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        let startup_cwd = std::env::temp_dir().join(format!("telemt_cfg_startup_default_{nonce}"));
+        std::fs::create_dir_all(&startup_cwd).unwrap();
+
+        let resolved = resolve_runtime_config_path("config.toml", &startup_cwd, false);
+        assert_eq!(resolved, startup_cwd.join("config.toml"));
+
+        let _ = std::fs::remove_dir(&startup_cwd);
+    }
+
+    #[test]
+    fn resolve_runtime_base_dir_prefers_cli_data_path() {
+        let nonce = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        let startup_cwd = std::env::temp_dir().join(format!("telemt_runtime_base_cwd_{nonce}"));
+        let data_path = std::env::temp_dir().join(format!("telemt_runtime_base_data_{nonce}"));
+        std::fs::create_dir_all(&startup_cwd).unwrap();
+        std::fs::create_dir_all(&data_path).unwrap();
+
+        let resolved = resolve_runtime_base_dir(
+            &startup_cwd.join("config.toml"),
+            &startup_cwd,
+            true,
+            Some(&data_path),
+        );
+        assert_eq!(resolved, data_path.canonicalize().unwrap());
+
+        let _ = std::fs::remove_dir(&data_path);
+        let _ = std::fs::remove_dir(&startup_cwd);
+    }
+
+    #[test]
+    fn resolve_runtime_base_dir_uses_working_directory_before_explicit_config_parent() {
+        let nonce = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        let startup_cwd = std::env::temp_dir().join(format!("telemt_runtime_base_start_{nonce}"));
+        let config_dir = std::env::temp_dir().join(format!("telemt_runtime_base_cfg_{nonce}"));
+        std::fs::create_dir_all(&startup_cwd).unwrap();
+        std::fs::create_dir_all(&config_dir).unwrap();
+
+        let resolved =
+            resolve_runtime_base_dir(&config_dir.join("telemt.toml"), &startup_cwd, true, None);
+        assert_eq!(resolved, startup_cwd.canonicalize().unwrap());
+
+        let _ = std::fs::remove_dir(&config_dir);
+        let _ = std::fs::remove_dir(&startup_cwd);
+    }
+
+    #[test]
+    fn resolve_runtime_base_dir_uses_explicit_config_parent_from_root() {
+        let nonce = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        let config_dir = std::env::temp_dir().join(format!("telemt_runtime_base_root_cfg_{nonce}"));
+        std::fs::create_dir_all(&config_dir).unwrap();
+
+        let resolved =
+            resolve_runtime_base_dir(&config_dir.join("telemt.toml"), Path::new("/"), true, None);
+        assert_eq!(resolved, config_dir.canonicalize().unwrap());
+
+        let _ = std::fs::remove_dir(&config_dir);
+    }
+
+    #[test]
+    fn resolve_runtime_base_dir_uses_systemd_working_directory_before_etc() {
+        let nonce = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        let startup_cwd = std::env::temp_dir().join(format!("telemt_runtime_base_systemd_{nonce}"));
+        std::fs::create_dir_all(&startup_cwd).unwrap();
+
+        let resolved =
+            resolve_runtime_base_dir(&startup_cwd.join("config.toml"), &startup_cwd, false, None);
+        assert_eq!(resolved, startup_cwd.canonicalize().unwrap());
+
+        let _ = std::fs::remove_dir(&startup_cwd);
+    }
+
+    #[test]
+    fn resolve_runtime_base_dir_falls_back_to_etc_from_root() {
+        let resolved = resolve_runtime_base_dir(
+            Path::new("/etc/telemt/config.toml"),
+            Path::new("/"),
+            false,
+            None,
+        );
+        assert_eq!(resolved, PathBuf::from("/etc/telemt"));
+    }
+
+    #[test]
+    fn expected_handshake_eof_matches_connection_reset() {
+        let err = ProxyError::Io(std::io::Error::from(std::io::ErrorKind::ConnectionReset));
+        assert!(is_expected_handshake_eof(&err));
+    }
+
+    #[test]
+    fn expected_handshake_eof_matches_stream_io_unexpected_eof() {
+        let err = ProxyError::Stream(StreamError::Io(std::io::Error::from(
+            std::io::ErrorKind::UnexpectedEof,
+        )));
+        assert!(is_expected_handshake_eof(&err));
+    }
+
+    #[test]
+    fn peer_close_description_is_human_readable_for_all_peer_close_kinds() {
+        let cases = [
+            (
+                std::io::ErrorKind::ConnectionReset,
+                "Peer reset TCP connection (RST)",
+            ),
+            (
+                std::io::ErrorKind::ConnectionAborted,
+                "Peer aborted TCP connection during transport",
+            ),
+            (
+                std::io::ErrorKind::BrokenPipe,
+                "Peer closed write side (broken pipe)",
+            ),
+            (
+                std::io::ErrorKind::NotConnected,
+                "Socket was already closed by peer",
+            ),
+        ];
+
+        for (kind, expected) in cases {
+            let err = ProxyError::Io(std::io::Error::from(kind));
+            assert_eq!(peer_close_description(&err), Some(expected));
+        }
+    }
+
+    #[test]
+    fn handshake_close_description_is_human_readable_for_all_expected_kinds() {
+        let cases = [
+            (
+                ProxyError::Io(std::io::Error::from(std::io::ErrorKind::UnexpectedEof)),
+                "Peer closed before sending full 64-byte MTProto handshake",
+            ),
+            (
+                ProxyError::Io(std::io::Error::from(std::io::ErrorKind::ConnectionReset)),
+                "Peer reset TCP connection during initial MTProto handshake",
+            ),
+            (
+                ProxyError::Io(std::io::Error::from(std::io::ErrorKind::ConnectionAborted)),
+                "Peer aborted TCP connection during initial MTProto handshake",
+            ),
+            (
+                ProxyError::Io(std::io::Error::from(std::io::ErrorKind::BrokenPipe)),
+                "Peer closed write side before MTProto handshake completed",
+            ),
+            (
+                ProxyError::Io(std::io::Error::from(std::io::ErrorKind::NotConnected)),
+                "Handshake socket was already closed by peer",
+            ),
+            (
+                ProxyError::Stream(StreamError::UnexpectedEof),
+                "Peer closed before sending full 64-byte MTProto handshake",
+            ),
+        ];
+
+        for (err, expected) in cases {
+            assert_eq!(expected_handshake_close_description(&err), Some(expected));
+        }
+    }
 }
 
 pub(crate) fn print_proxy_links(host: &str, port: u16, config: &ProxyConfig) {
@@ -360,7 +627,63 @@ pub(crate) async fn wait_until_admission_open(admission_rx: &mut watch::Receiver
 }
 
 pub(crate) fn is_expected_handshake_eof(err: &crate::error::ProxyError) -> bool {
-    err.to_string().contains("expected 64 bytes, got 0")
+    expected_handshake_close_description(err).is_some()
+}
+
+pub(crate) fn peer_close_description(err: &crate::error::ProxyError) -> Option<&'static str> {
+    fn from_kind(kind: std::io::ErrorKind) -> Option<&'static str> {
+        match kind {
+            std::io::ErrorKind::ConnectionReset => Some("Peer reset TCP connection (RST)"),
+            std::io::ErrorKind::ConnectionAborted => {
+                Some("Peer aborted TCP connection during transport")
+            }
+            std::io::ErrorKind::BrokenPipe => Some("Peer closed write side (broken pipe)"),
+            std::io::ErrorKind::NotConnected => Some("Socket was already closed by peer"),
+            _ => None,
+        }
+    }
+
+    match err {
+        crate::error::ProxyError::Io(ioe) => from_kind(ioe.kind()),
+        crate::error::ProxyError::Stream(crate::error::StreamError::Io(ioe)) => {
+            from_kind(ioe.kind())
+        }
+        _ => None,
+    }
+}
+
+pub(crate) fn expected_handshake_close_description(
+    err: &crate::error::ProxyError,
+) -> Option<&'static str> {
+    fn from_kind(kind: std::io::ErrorKind) -> Option<&'static str> {
+        match kind {
+            std::io::ErrorKind::UnexpectedEof => {
+                Some("Peer closed before sending full 64-byte MTProto handshake")
+            }
+            std::io::ErrorKind::ConnectionReset => {
+                Some("Peer reset TCP connection during initial MTProto handshake")
+            }
+            std::io::ErrorKind::ConnectionAborted => {
+                Some("Peer aborted TCP connection during initial MTProto handshake")
+            }
+            std::io::ErrorKind::BrokenPipe => {
+                Some("Peer closed write side before MTProto handshake completed")
+            }
+            std::io::ErrorKind::NotConnected => Some("Handshake socket was already closed by peer"),
+            _ => None,
+        }
+    }
+
+    match err {
+        crate::error::ProxyError::Io(ioe) => from_kind(ioe.kind()),
+        crate::error::ProxyError::Stream(crate::error::StreamError::UnexpectedEof) => {
+            Some("Peer closed before sending full 64-byte MTProto handshake")
+        }
+        crate::error::ProxyError::Stream(crate::error::StreamError::Io(ioe)) => {
+            from_kind(ioe.kind())
+        }
+        _ => None,
+    }
 }
 
 pub(crate) async fn load_startup_proxy_config_snapshot(

src/maestro/listeners.rs

@@ -9,11 +9,11 @@ use tokio::net::UnixListener;
 use tokio::sync::{Semaphore, watch};
 use tracing::{debug, error, info, warn};
 
-use crate::config::ProxyConfig;
+use crate::config::{ProxyConfig, RstOnCloseMode};
 use crate::crypto::SecureRandom;
 use crate::ip_tracker::UserIpTracker;
 use crate::proxy::ClientHandler;
-use crate::proxy::route_mode::{ROUTE_SWITCH_ERROR_MSG, RouteRuntimeController};
+use crate::proxy::route_mode::RouteRuntimeController;
 use crate::proxy::shared_state::ProxySharedState;
 use crate::startup::{COMPONENT_LISTENERS_BIND, StartupTracker};
 use crate::stats::beobachten::BeobachtenStore;
@@ -21,15 +21,32 @@ use crate::stats::{ReplayChecker, Stats};
 use crate::stream::BufferPool;
 use crate::tls_front::TlsFrontCache;
 use crate::transport::middle_proxy::MePool;
+use crate::transport::socket::set_linger_zero;
 use crate::transport::{ListenOptions, UpstreamManager, create_listener, find_listener_processes};
 
-use super::helpers::{is_expected_handshake_eof, print_proxy_links};
+use super::helpers::{
+    expected_handshake_close_description, is_expected_handshake_eof, peer_close_description,
+    print_proxy_links,
+};
 
 pub(crate) struct BoundListeners {
     pub(crate) listeners: Vec<(TcpListener, bool)>,
     pub(crate) has_unix_listener: bool,
 }
 
+fn listener_port_or_legacy(listener: &crate::config::ListenerConfig, config: &ProxyConfig) -> u16 {
+    listener.port.unwrap_or(config.server.port)
+}
+
+fn default_link_port(config: &ProxyConfig) -> u16 {
+    config
+        .server
+        .listeners
+        .first()
+        .and_then(|listener| listener.port)
+        .unwrap_or(config.server.port)
+}
+
 #[allow(clippy::too_many_arguments)]
 pub(crate) async fn bind_listeners(
     config: &Arc<ProxyConfig>,
@@ -62,7 +79,8 @@ pub(crate) async fn bind_listeners(
     let mut listeners = Vec::new();
 
     for listener_conf in &config.server.listeners {
-        let addr = SocketAddr::new(listener_conf.ip, config.server.port);
+        let listener_port = listener_port_or_legacy(listener_conf, config);
+        let addr = SocketAddr::new(listener_conf.ip, listener_port);
         if addr.is_ipv4() && !decision_ipv4_dc {
             warn!(%addr, "Skipping IPv4 listener: IPv4 disabled by [network]");
             continue;
@@ -105,11 +123,7 @@ pub(crate) async fn bind_listeners(
                 if config.general.links.public_host.is_none()
                     && !config.general.links.show.is_empty()
                 {
-                    let link_port = config
-                        .general
-                        .links
-                        .public_port
-                        .unwrap_or(config.server.port);
+                    let link_port = config.general.links.public_port.unwrap_or(listener_port);
                     print_proxy_links(&public_host, link_port, config);
                 }
 
@@ -157,7 +171,7 @@ pub(crate) async fn bind_listeners(
                     .general
                     .links
                     .public_port
-                    .unwrap_or(config.server.port),
+                    .unwrap_or(default_link_port(config)),
             )
         } else {
             let ip = detected_ip_v4.or(detected_ip_v6).map(|ip| ip.to_string());
@@ -172,7 +186,7 @@ pub(crate) async fn bind_listeners(
                     .general
                     .links
                     .public_port
-                    .unwrap_or(config.server.port),
+                    .unwrap_or(default_link_port(config)),
             )
         };
 
@@ -380,6 +394,15 @@ pub(crate) fn spawn_tcp_accept_loops(
             loop {
                 match listener.accept().await {
                     Ok((stream, peer_addr)) => {
+                        let rst_mode = config_rx.borrow().general.rst_on_close;
+                        #[cfg(unix)]
+                        let raw_fd = {
+                            use std::os::unix::io::AsRawFd;
+                            stream.as_raw_fd()
+                        };
+                        if matches!(rst_mode, RstOnCloseMode::Errors | RstOnCloseMode::Always) {
+                            let _ = set_linger_zero(&stream);
+                        }
                         if !*admission_rx_tcp.borrow() {
                             debug!(peer = %peer_addr, "Admission gate closed, dropping connection");
                             drop(stream);
@@ -454,6 +477,9 @@ pub(crate) fn spawn_tcp_accept_loops(
                                 shared,
                                 proxy_protocol_enabled,
                                 real_peer_report_for_handler,
+                                #[cfg(unix)]
+                                raw_fd,
+                                rst_mode,
                             )
                             .run()
                             .await
@@ -462,45 +488,32 @@ pub(crate) fn spawn_tcp_accept_loops(
                                     Ok(guard) => *guard,
                                     Err(_) => None,
                                 };
-                                let peer_closed = matches!(
-                                    &e,
-                                    crate::error::ProxyError::Io(ioe)
-                                        if matches!(
-                                            ioe.kind(),
-                                            std::io::ErrorKind::ConnectionReset
-                                                | std::io::ErrorKind::ConnectionAborted
-                                                | std::io::ErrorKind::BrokenPipe
-                                                | std::io::ErrorKind::NotConnected
-                                        )
-                                ) || matches!(
-                                    &e,
-                                    crate::error::ProxyError::Stream(
-                                        crate::error::StreamError::Io(ioe)
-                                    )
-                                        if matches!(
-                                            ioe.kind(),
-                                            std::io::ErrorKind::ConnectionReset
-                                                | std::io::ErrorKind::ConnectionAborted
-                                                | std::io::ErrorKind::BrokenPipe
-                                                | std::io::ErrorKind::NotConnected
-                                        )
-                                );
+                                let peer_close_reason = peer_close_description(&e);
+                                let handshake_close_reason =
+                                    expected_handshake_close_description(&e);
 
-                                let me_closed = matches!(
-                                    &e,
-                                    crate::error::ProxyError::Proxy(msg) if msg == "ME connection lost"
-                                );
-                                let route_switched = matches!(
-                                    &e,
-                                    crate::error::ProxyError::Proxy(msg) if msg == ROUTE_SWITCH_ERROR_MSG
-                                );
+                                let me_closed =
+                                    matches!(&e, crate::error::ProxyError::MiddleConnectionLost);
+                                let route_switched =
+                                    matches!(&e, crate::error::ProxyError::RouteSwitched);
 
-                                match (peer_closed, me_closed) {
-                                    (true, _) => {
+                                match (peer_close_reason, me_closed) {
+                                    (Some(reason), _) => {
                                         if let Some(real_peer) = real_peer {
-                                            debug!(peer = %peer_addr, real_peer = %real_peer, error = %e, "Connection closed by client");
+                                            debug!(
+                                                peer = %peer_addr,
+                                                real_peer = %real_peer,
+                                                error = %e,
+                                                close_reason = reason,
+                                                "Connection closed by peer"
+                                            );
                                         } else {
-                                            debug!(peer = %peer_addr, error = %e, "Connection closed by client");
+                                            debug!(
+                                                peer = %peer_addr,
+                                                error = %e,
+                                                close_reason = reason,
+                                                "Connection closed by peer"
+                                            );
                                         }
                                     }
                                     (_, true) => {
@@ -518,10 +531,23 @@ pub(crate) fn spawn_tcp_accept_loops(
                                         }
                                     }
                                     _ if is_expected_handshake_eof(&e) => {
+                                        let reason = handshake_close_reason
+                                            .unwrap_or("Peer closed during initial handshake");
                                         if let Some(real_peer) = real_peer {
-                                            info!(peer = %peer_addr, real_peer = %real_peer, error = %e, "Connection closed during initial handshake");
+                                            info!(
+                                                peer = %peer_addr,
+                                                real_peer = %real_peer,
+                                                error = %e,
+                                                close_reason = reason,
+                                                "Connection closed during initial handshake"
+                                            );
                                         } else {
-                                            info!(peer = %peer_addr, error = %e, "Connection closed during initial handshake");
+                                            info!(
+                                                peer = %peer_addr,
+                                                error = %e,
+                                                close_reason = reason,
+                                                "Connection closed during initial handshake"
+                                            );
                                         }
                                     }
                                     _ => {

src/maestro/me_startup.rs

@@ -3,7 +3,7 @@
 use std::sync::Arc;
 use std::time::Duration;
 
-use tokio::sync::RwLock;
+use tokio::sync::{RwLock, watch};
 use tracing::{error, info, warn};
 
 use crate::config::ProxyConfig;
@@ -29,6 +29,7 @@ pub(crate) async fn initialize_me_pool(
     rng: Arc<SecureRandom>,
     stats: Arc<Stats>,
     api_me_pool: Arc<RwLock<Option<Arc<MePool>>>>,
+    me_ready_tx: watch::Sender<u64>,
 ) -> Option<Arc<MePool>> {
     if !use_middle_proxy {
         return None;
@@ -66,6 +67,7 @@ pub(crate) async fn initialize_me_pool(
         match crate::transport::middle_proxy::fetch_proxy_secret_with_upstream(
             proxy_secret_path,
             config.general.proxy_secret_len_max,
+            config.general.proxy_secret_url.as_deref(),
             Some(upstream_manager.clone()),
         )
         .await
@@ -126,7 +128,11 @@ pub(crate) async fn initialize_me_pool(
                 .set_me_status(StartupMeStatus::Initializing, COMPONENT_ME_PROXY_CONFIG_V4)
                 .await;
             let cfg_v4 = load_startup_proxy_config_snapshot(
-                "https://core.telegram.org/getProxyConfig",
+                config
+                    .general
+                    .proxy_config_v4_url
+                    .as_deref()
+                    .unwrap_or("https://core.telegram.org/getProxyConfig"),
                 config.general.proxy_config_v4_cache_path.as_deref(),
                 me2dc_fallback,
                 "getProxyConfig",
@@ -158,7 +164,11 @@ pub(crate) async fn initialize_me_pool(
                 .set_me_status(StartupMeStatus::Initializing, COMPONENT_ME_PROXY_CONFIG_V6)
                 .await;
             let cfg_v6 = load_startup_proxy_config_snapshot(
-                "https://core.telegram.org/getProxyConfigV6",
+                config
+                    .general
+                    .proxy_config_v6_url
+                    .as_deref()
+                    .unwrap_or("https://core.telegram.org/getProxyConfigV6"),
                 config.general.proxy_config_v6_cache_path.as_deref(),
                 me2dc_fallback,
                 "getProxyConfigV6",
@@ -268,6 +278,8 @@ pub(crate) async fn initialize_me_pool(
                     config.general.me_socks_kdf_policy,
                     config.general.me_writer_cmd_channel_capacity,
                     config.general.me_route_channel_capacity,
+                    config.general.me_route_backpressure_enabled,
+                    config.general.me_route_fairshare_enabled,
                     config.general.me_route_backpressure_base_timeout_ms,
                     config.general.me_route_backpressure_high_timeout_ms,
                     config.general.me_route_backpressure_high_watermark_pct,
@@ -303,6 +315,7 @@ pub(crate) async fn initialize_me_pool(
                     let pool_bg = pool.clone();
                     let rng_bg = rng.clone();
                     let startup_tracker_bg = startup_tracker.clone();
+                    let me_ready_tx_bg = me_ready_tx.clone();
                     let retry_limit = if me_init_retry_attempts == 0 {
                         String::from("unlimited")
                     } else {
@@ -336,6 +349,9 @@ pub(crate) async fn initialize_me_pool(
                                         startup_tracker_bg
                                             .set_me_status(StartupMeStatus::Ready, "ready")
                                             .await;
+                                        me_ready_tx_bg.send_modify(|version| {
+                                            *version = version.saturating_add(1);
+                                        });
                                         info!(
                                             attempt = init_attempt,
                                             "Middle-End pool initialized successfully"
@@ -463,6 +479,9 @@ pub(crate) async fn initialize_me_pool(
                                 startup_tracker
                                     .set_me_status(StartupMeStatus::Ready, "ready")
                                     .await;
+                                me_ready_tx.send_modify(|version| {
+                                    *version = version.saturating_add(1);
+                                });
                                 info!(
                                     attempt = init_attempt,
                                     "Middle-End pool initialized successfully"

src/maestro/mod.rs

@@ -28,8 +28,8 @@ use tracing::{error, info, warn};
 use tracing_subscriber::{EnvFilter, fmt, prelude::*, reload};
 
 use crate::api;
-use crate::conntrack_control;
 use crate::config::{LogLevel, ProxyConfig};
+use crate::conntrack_control;
 use crate::crypto::SecureRandom;
 use crate::ip_tracker::UserIpTracker;
 use crate::network::probe::{decide_network_capabilities, log_probe_result, run_probe};
@@ -47,7 +47,7 @@ use crate::stats::{ReplayChecker, Stats};
 use crate::stream::BufferPool;
 use crate::transport::UpstreamManager;
 use crate::transport::middle_proxy::MePool;
-use helpers::{parse_cli, resolve_runtime_config_path};
+use helpers::{parse_cli, resolve_runtime_base_dir, resolve_runtime_config_path};
 
 #[cfg(unix)]
 use crate::daemon::{DaemonOptions, PidFile, drop_privileges};
@@ -81,23 +81,11 @@ pub async fn run() -> std::result::Result<(), Box<dyn std::error::Error>> {
     }
 }
 
-#[cfg(unix)]
-async fn run_inner(
-    daemon_opts: DaemonOptions,
+// Shared maestro startup and main loop. `drop_after_bind` runs on Unix after listeners are bound
+// (for privilege drop); it is a no-op on other platforms.
+async fn run_telemt_core(
+    drop_after_bind: impl FnOnce(),
 ) -> std::result::Result<(), Box<dyn std::error::Error>> {
-    // Acquire PID file if daemonizing or if explicitly requested
-    // Keep it alive until shutdown (underscore prefix = intentionally kept for RAII cleanup)
-    let _pid_file = if daemon_opts.daemonize || daemon_opts.pid_file.is_some() {
-        let mut pf = PidFile::new(daemon_opts.pid_file_path());
-        if let Err(e) = pf.acquire() {
-            eprintln!("[telemt] {}", e);
-            std::process::exit(1);
-        }
-        Some(pf)
-    } else {
-        None
-    };
-
     let process_started_at = Instant::now();
     let process_started_at_epoch_secs = SystemTime::now()
         .duration_since(UNIX_EPOCH)
@@ -112,6 +100,7 @@ async fn run_inner(
         .await;
     let cli_args = parse_cli();
     let config_path_cli = cli_args.config_path;
+    let config_path_explicit = cli_args.config_path_explicit;
     let data_path = cli_args.data_path;
     let cli_silent = cli_args.silent;
     let cli_log_level = cli_args.log_level;
@@ -123,7 +112,51 @@ async fn run_inner(
             std::process::exit(1);
         }
     };
-    let config_path = resolve_runtime_config_path(&config_path_cli, &startup_cwd);
+    if let Some(ref data_path) = data_path
+        && !data_path.is_absolute()
+    {
+        eprintln!(
+            "[telemt] data_path must be absolute: {}",
+            data_path.display()
+        );
+        std::process::exit(1);
+    }
+    let mut config_path =
+        resolve_runtime_config_path(&config_path_cli, &startup_cwd, config_path_explicit);
+    let runtime_base_dir = resolve_runtime_base_dir(
+        &config_path,
+        &startup_cwd,
+        config_path_explicit,
+        data_path.as_deref(),
+    );
+
+    if !runtime_base_dir.exists()
+        && let Err(e) = std::fs::create_dir_all(&runtime_base_dir)
+    {
+        eprintln!(
+            "[telemt] Can't create runtime directory {}: {}",
+            runtime_base_dir.display(),
+            e
+        );
+        std::process::exit(1);
+    }
+
+    if !runtime_base_dir.is_dir() {
+        eprintln!(
+            "[telemt] Runtime path exists but is not a directory: {}",
+            runtime_base_dir.display()
+        );
+        std::process::exit(1);
+    }
+
+    if let Err(e) = std::env::set_current_dir(&runtime_base_dir) {
+        eprintln!(
+            "[telemt] Can't use runtime directory {}: {}",
+            runtime_base_dir.display(),
+            e
+        );
+        std::process::exit(1);
+    }
 
     let mut config = match ProxyConfig::load(&config_path) {
         Ok(c) => c,
@@ -133,11 +166,98 @@ async fn run_inner(
                 std::process::exit(1);
             } else {
                 let default = ProxyConfig::default();
-                std::fs::write(&config_path, toml::to_string_pretty(&default).unwrap()).unwrap();
-                eprintln!(
-                    "[telemt] Created default config at {}",
-                    config_path.display()
-                );
+
+                let serialized =
+                    match toml::to_string_pretty(&default).or_else(|_| toml::to_string(&default)) {
+                        Ok(value) => Some(value),
+                        Err(serialize_error) => {
+                            eprintln!(
+                                "[telemt] Warning: failed to serialize default config: {}",
+                                serialize_error
+                            );
+                            None
+                        }
+                    };
+
+                if config_path_explicit {
+                    if let Some(serialized) = serialized.as_ref() {
+                        if let Err(write_error) = std::fs::write(&config_path, serialized) {
+                            eprintln!(
+                                "[telemt] Error: failed to create explicit config at {}: {}",
+                                config_path.display(),
+                                write_error
+                            );
+                            std::process::exit(1);
+                        }
+                        eprintln!(
+                            "[telemt] Created default config at {}",
+                            config_path.display()
+                        );
+                    } else {
+                        eprintln!(
+                            "[telemt] Warning: running with in-memory default config without writing to disk"
+                        );
+                    }
+                } else {
+                    let runtime_config_path = runtime_base_dir.join("telemt.toml");
+                    let fallback_config_path = runtime_base_dir.join("config.toml");
+                    let mut persisted = false;
+
+                    if let Some(serialized) = serialized.as_ref() {
+                        match std::fs::create_dir_all(&runtime_base_dir) {
+                            Ok(()) => match std::fs::write(&runtime_config_path, serialized) {
+                                Ok(()) => {
+                                    config_path = runtime_config_path;
+                                    eprintln!(
+                                        "[telemt] Created default config at {}",
+                                        config_path.display()
+                                    );
+                                    persisted = true;
+                                }
+                                Err(write_error) => {
+                                    eprintln!(
+                                        "[telemt] Warning: failed to write default config at {}: {}",
+                                        runtime_config_path.display(),
+                                        write_error
+                                    );
+                                }
+                            },
+                            Err(create_error) => {
+                                eprintln!(
+                                    "[telemt] Warning: failed to create {}: {}",
+                                    runtime_base_dir.display(),
+                                    create_error
+                                );
+                            }
+                        }
+
+                        if !persisted {
+                            match std::fs::write(&fallback_config_path, serialized) {
+                                Ok(()) => {
+                                    config_path = fallback_config_path;
+                                    eprintln!(
+                                        "[telemt] Created default config at {}",
+                                        config_path.display()
+                                    );
+                                    persisted = true;
+                                }
+                                Err(write_error) => {
+                                    eprintln!(
+                                        "[telemt] Warning: failed to write default config at {}: {}",
+                                        fallback_config_path.display(),
+                                        write_error
+                                    );
+                                }
+                            }
+                        }
+                    }
+
+                    if !persisted {
+                        eprintln!(
+                            "[telemt] Warning: running with in-memory default config without writing to disk"
+                        );
+                    }
+                }
                 default
             }
         }
@@ -297,6 +417,8 @@ async fn run_inner(
 
     let stats = Arc::new(Stats::new());
     stats.apply_telemetry_policy(TelemetryPolicy::from_config(&config.general.telemetry));
+    let quota_state_path = config.general.quota_state_path.clone();
+    crate::quota_state::load_quota_state(&quota_state_path, stats.as_ref()).await;
 
     let upstream_manager = Arc::new(UpstreamManager::new(
         config.upstreams.clone(),
@@ -376,6 +498,7 @@ async fn run_inner(
             let config_rx_api = api_config_rx.clone();
             let admission_rx_api = admission_rx.clone();
             let config_path_api = config_path.clone();
+            let quota_state_path_api = quota_state_path.clone();
             let startup_tracker_api = startup_tracker.clone();
             let detected_ips_rx_api = detected_ips_rx.clone();
             tokio::spawn(async move {
@@ -389,6 +512,7 @@ async fn run_inner(
                     config_rx_api,
                     admission_rx_api,
                     config_path_api,
+                    quota_state_path_api,
                     detected_ips_rx_api,
                     process_started_at_epoch_secs,
                     startup_tracker_api,
@@ -540,6 +664,8 @@ async fn run_inner(
             .await;
     }
 
+    let (me_ready_tx, me_ready_rx) = watch::channel(0_u64);
+
     let me_pool: Option<Arc<MePool>> = me_startup::initialize_me_pool(
         use_middle_proxy,
         &config,
@@ -550,6 +676,7 @@ async fn run_inner(
         rng.clone(),
         stats.clone(),
         api_me_pool.clone(),
+        me_ready_tx.clone(),
     )
     .await;
 
@@ -586,6 +713,11 @@ async fn run_inner(
     ));
 
     let buffer_pool = Arc::new(BufferPool::with_config(64 * 1024, 4096));
+    let shared_state = ProxySharedState::new();
+    shared_state.traffic_limiter.apply_policy(
+        config.access.user_rate_limits.clone(),
+        config.access.cidr_rate_limits.clone(),
+    );
 
     connectivity::run_startup_connectivity(
         &config,
@@ -617,6 +749,8 @@ async fn run_inner(
         beobachten.clone(),
         api_config_tx.clone(),
         me_pool.clone(),
+        shared_state.clone(),
+        me_ready_tx.clone(),
     )
     .await;
     let config_rx = runtime_watches.config_rx;
@@ -630,10 +764,10 @@ async fn run_inner(
         route_runtime.clone(),
         &admission_tx,
         config_rx.clone(),
+        me_ready_rx,
     )
     .await;
     let _admission_tx_hold = admission_tx;
-    let shared_state = ProxySharedState::new();
     conntrack_control::spawn_conntrack_controller(
         config_rx.clone(),
         stats.clone(),
@@ -671,13 +805,8 @@ async fn run_inner(
         std::process::exit(1);
     }
 
-    // Drop privileges after binding sockets (which may require root for port < 1024)
-    if daemon_opts.user.is_some() || daemon_opts.group.is_some() {
-        if let Err(e) = drop_privileges(daemon_opts.user.as_deref(), daemon_opts.group.as_deref()) {
-            error!(error = %e, "Failed to drop privileges");
-            std::process::exit(1);
-        }
-    }
+    // On Unix, caller supplies privilege drop after bind (may require root for port < 1024).
+    drop_after_bind();
 
     runtime_tasks::apply_runtime_log_filter(
         has_rust_log,
@@ -692,7 +821,9 @@ async fn run_inner(
         &startup_tracker,
         stats.clone(),
         beobachten.clone(),
+        shared_state.clone(),
         ip_tracker.clone(),
+        tls_cache.clone(),
         config_rx.clone(),
     )
     .await;
@@ -720,7 +851,43 @@ async fn run_inner(
         max_connections.clone(),
     );
 
-    shutdown::wait_for_shutdown(process_started_at, me_pool, stats).await;
+    shutdown::wait_for_shutdown(process_started_at, me_pool, stats, quota_state_path).await;
 
     Ok(())
 }
+
+#[cfg(unix)]
+async fn run_inner(
+    daemon_opts: DaemonOptions,
+) -> std::result::Result<(), Box<dyn std::error::Error>> {
+    // Acquire PID file if daemonizing or if explicitly requested
+    // Keep it alive until shutdown (underscore prefix = intentionally kept for RAII cleanup)
+    let _pid_file = if daemon_opts.daemonize || daemon_opts.pid_file.is_some() {
+        let mut pf = PidFile::new(daemon_opts.pid_file_path());
+        if let Err(e) = pf.acquire() {
+            eprintln!("[telemt] {}", e);
+            std::process::exit(1);
+        }
+        Some(pf)
+    } else {
+        None
+    };
+
+    let user = daemon_opts.user.clone();
+    let group = daemon_opts.group.clone();
+
+    run_telemt_core(|| {
+        if user.is_some() || group.is_some() {
+            if let Err(e) = drop_privileges(user.as_deref(), group.as_deref(), _pid_file.as_ref()) {
+                error!(error = %e, "Failed to drop privileges");
+                std::process::exit(1);
+            }
+        }
+    })
+    .await
+}
+
+#[cfg(not(unix))]
+async fn run_inner() -> std::result::Result<(), Box<dyn std::error::Error>> {
+    run_telemt_core(|| {}).await
+}

src/maestro/runtime_tasks.rs

@@ -13,6 +13,7 @@ use crate::crypto::SecureRandom;
 use crate::ip_tracker::UserIpTracker;
 use crate::metrics;
 use crate::network::probe::NetworkProbe;
+use crate::proxy::shared_state::ProxySharedState;
 use crate::startup::{
     COMPONENT_CONFIG_WATCHER_START, COMPONENT_METRICS_START, COMPONENT_RUNTIME_READY,
     StartupTracker,
@@ -20,6 +21,7 @@ use crate::startup::{
 use crate::stats::beobachten::BeobachtenStore;
 use crate::stats::telemetry::TelemetryPolicy;
 use crate::stats::{ReplayChecker, Stats};
+use crate::tls_front::TlsFrontCache;
 use crate::transport::UpstreamManager;
 use crate::transport::middle_proxy::{MePool, MeReinitTrigger};
 
@@ -50,6 +52,8 @@ pub(crate) async fn spawn_runtime_tasks(
     beobachten: Arc<BeobachtenStore>,
     api_config_tx: watch::Sender<Arc<ProxyConfig>>,
     me_pool_for_policy: Option<Arc<MePool>>,
+    shared_state: Arc<ProxySharedState>,
+    me_ready_tx: watch::Sender<u64>,
 ) -> RuntimeWatches {
     let um_clone = upstream_manager.clone();
     let dc_overrides_for_health = config.dc_overrides.clone();
@@ -69,6 +73,18 @@ pub(crate) async fn spawn_runtime_tasks(
         rc_clone.run_periodic_cleanup().await;
     });
 
+    let stats_maintenance = stats.clone();
+    tokio::spawn(async move {
+        stats_maintenance
+            .run_periodic_user_stats_maintenance()
+            .await;
+    });
+
+    let ip_tracker_maintenance = ip_tracker.clone();
+    tokio::spawn(async move {
+        ip_tracker_maintenance.run_periodic_maintenance().await;
+    });
+
     let detected_ip_v4: Option<IpAddr> = probe.detected_ipv4.map(IpAddr::V4);
     let detected_ip_v6: Option<IpAddr> = probe.detected_ipv6.map(IpAddr::V6);
     debug!(
@@ -120,6 +136,8 @@ pub(crate) async fn spawn_runtime_tasks(
             if let Some(pool) = &me_pool_for_policy {
                 pool.update_runtime_transport_policy(
                     cfg.general.me_socks_kdf_policy,
+                    cfg.general.me_route_backpressure_enabled,
+                    cfg.general.me_route_fairshare_enabled,
                     cfg.general.me_route_backpressure_base_timeout_ms,
                     cfg.general.me_route_backpressure_high_timeout_ms,
                     cfg.general.me_route_backpressure_high_watermark_pct,
@@ -181,6 +199,41 @@ pub(crate) async fn spawn_runtime_tasks(
         }
     });
 
+    let limiter = shared_state.traffic_limiter.clone();
+    limiter.apply_policy(
+        config.access.user_rate_limits.clone(),
+        config.access.cidr_rate_limits.clone(),
+    );
+    let mut config_rx_rate_limits = config_rx.clone();
+    tokio::spawn(async move {
+        let mut prev_user_limits = config_rx_rate_limits
+            .borrow()
+            .access
+            .user_rate_limits
+            .clone();
+        let mut prev_cidr_limits = config_rx_rate_limits
+            .borrow()
+            .access
+            .cidr_rate_limits
+            .clone();
+        loop {
+            if config_rx_rate_limits.changed().await.is_err() {
+                break;
+            }
+            let cfg = config_rx_rate_limits.borrow_and_update().clone();
+            if prev_user_limits != cfg.access.user_rate_limits
+                || prev_cidr_limits != cfg.access.cidr_rate_limits
+            {
+                limiter.apply_policy(
+                    cfg.access.user_rate_limits.clone(),
+                    cfg.access.cidr_rate_limits.clone(),
+                );
+                prev_user_limits = cfg.access.user_rate_limits.clone();
+                prev_cidr_limits = cfg.access.cidr_rate_limits.clone();
+            }
+        }
+    });
+
     let beobachten_writer = beobachten.clone();
     let config_rx_beobachten = config_rx.clone();
     tokio::spawn(async move {
@@ -210,12 +263,14 @@ pub(crate) async fn spawn_runtime_tasks(
         let pool_clone_sched = pool.clone();
         let rng_clone_sched = rng.clone();
         let config_rx_clone_sched = config_rx.clone();
+        let me_ready_tx_sched = me_ready_tx.clone();
         tokio::spawn(async move {
             crate::transport::middle_proxy::me_reinit_scheduler(
                 pool_clone_sched,
                 rng_clone_sched,
                 config_rx_clone_sched,
                 reinit_rx,
+                me_ready_tx_sched,
             )
             .await;
         });
@@ -287,7 +342,9 @@ pub(crate) async fn spawn_metrics_if_configured(
     startup_tracker: &Arc<StartupTracker>,
     stats: Arc<Stats>,
     beobachten: Arc<BeobachtenStore>,
+    shared_state: Arc<ProxySharedState>,
     ip_tracker: Arc<UserIpTracker>,
+    tls_cache: Option<Arc<TlsFrontCache>>,
     config_rx: watch::Receiver<Arc<ProxyConfig>>,
 ) {
     // metrics_listen takes precedence; fall back to metrics_port for backward compat.
@@ -320,8 +377,10 @@ pub(crate) async fn spawn_metrics_if_configured(
             .await;
         let stats = stats.clone();
         let beobachten = beobachten.clone();
+        let shared_state = shared_state.clone();
         let config_rx_metrics = config_rx.clone();
         let ip_tracker_metrics = ip_tracker.clone();
+        let tls_cache_metrics = tls_cache.clone();
         let whitelist = config.server.metrics_whitelist.clone();
         let listen_backlog = config.server.listen_backlog;
         tokio::spawn(async move {
@@ -331,7 +390,9 @@ pub(crate) async fn spawn_metrics_if_configured(
                 listen_backlog,
                 stats,
                 beobachten,
+                shared_state,
                 ip_tracker_metrics,
+                tls_cache_metrics,
                 config_rx_metrics,
                 whitelist,
             )

src/maestro/shutdown.rs

@@ -8,6 +8,7 @@
 //!
 //! SIGHUP is handled separately in config/hot_reload.rs for config reload.
 
+use std::path::PathBuf;
 use std::sync::Arc;
 use std::time::{Duration, Instant};
 
@@ -48,9 +49,17 @@ pub(crate) async fn wait_for_shutdown(
     process_started_at: Instant,
     me_pool: Option<Arc<MePool>>,
     stats: Arc<Stats>,
+    quota_state_path: PathBuf,
 ) {
     let signal = wait_for_shutdown_signal().await;
-    perform_shutdown(signal, process_started_at, me_pool, &stats).await;
+    perform_shutdown(
+        signal,
+        process_started_at,
+        me_pool,
+        &stats,
+        quota_state_path,
+    )
+    .await;
 }
 
 /// Waits for any shutdown signal (SIGINT, SIGTERM, SIGQUIT).
@@ -79,6 +88,7 @@ async fn perform_shutdown(
     process_started_at: Instant,
     me_pool: Option<Arc<MePool>>,
     stats: &Stats,
+    quota_state_path: PathBuf,
 ) {
     let shutdown_started_at = Instant::now();
     info!(signal = %signal, "Received shutdown signal");
@@ -109,6 +119,22 @@ async fn perform_shutdown(
         }
     }
 
+    match crate::quota_state::save_quota_state(&quota_state_path, stats).await {
+        Ok(()) => {
+            info!(
+                path = %quota_state_path.display(),
+                "Persisted per-user quota state"
+            );
+        }
+        Err(error) => {
+            warn!(
+                error = %error,
+                path = %quota_state_path.display(),
+                "Failed to persist per-user quota state"
+            );
+        }
+    }
+
     let shutdown_secs = shutdown_started_at.elapsed().as_secs();
     info!(
         "Shutdown completed successfully in {} {}.",

src/maestro/tls_bootstrap.rs

@@ -10,6 +10,14 @@ use crate::tls_front::TlsFrontCache;
 use crate::tls_front::fetcher::TlsFetchStrategy;
 use crate::transport::UpstreamManager;
 
+fn tls_fetch_host_for_domain(mask_host: &str, primary_tls_domain: &str, domain: &str) -> String {
+    if mask_host.eq_ignore_ascii_case(primary_tls_domain) {
+        domain.to_string()
+    } else {
+        mask_host.to_string()
+    }
+}
+
 pub(crate) async fn bootstrap_tls_front(
     config: &ProxyConfig,
     tls_domains: &[String],
@@ -56,6 +64,7 @@ pub(crate) async fn bootstrap_tls_front(
         let cache_initial = cache.clone();
         let domains_initial = tls_domains.to_vec();
         let host_initial = mask_host.clone();
+        let primary_initial = config.censorship.tls_domain.clone();
         let unix_sock_initial = mask_unix_sock.clone();
         let scope_initial = tls_fetch_scope.clone();
         let upstream_initial = upstream_manager.clone();
@@ -64,7 +73,8 @@ pub(crate) async fn bootstrap_tls_front(
             let mut join = tokio::task::JoinSet::new();
             for domain in domains_initial {
                 let cache_domain = cache_initial.clone();
-                let host_domain = host_initial.clone();
+                let host_domain =
+                    tls_fetch_host_for_domain(&host_initial, &primary_initial, &domain);
                 let unix_sock_domain = unix_sock_initial.clone();
                 let scope_domain = scope_initial.clone();
                 let upstream_domain = upstream_initial.clone();
@@ -117,6 +127,7 @@ pub(crate) async fn bootstrap_tls_front(
         let cache_refresh = cache.clone();
         let domains_refresh = tls_domains.to_vec();
         let host_refresh = mask_host.clone();
+        let primary_refresh = config.censorship.tls_domain.clone();
         let unix_sock_refresh = mask_unix_sock.clone();
         let scope_refresh = tls_fetch_scope.clone();
         let upstream_refresh = upstream_manager.clone();
@@ -130,7 +141,8 @@ pub(crate) async fn bootstrap_tls_front(
                 let mut join = tokio::task::JoinSet::new();
                 for domain in domains_refresh.clone() {
                     let cache_domain = cache_refresh.clone();
-                    let host_domain = host_refresh.clone();
+                    let host_domain =
+                        tls_fetch_host_for_domain(&host_refresh, &primary_refresh, &domain);
                     let unix_sock_domain = unix_sock_refresh.clone();
                     let scope_domain = scope_refresh.clone();
                     let upstream_domain = upstream_refresh.clone();
@@ -186,3 +198,24 @@ pub(crate) async fn bootstrap_tls_front(
 
     tls_cache
 }
+
+#[cfg(test)]
+mod tests {
+    use super::tls_fetch_host_for_domain;
+
+    #[test]
+    fn tls_fetch_host_uses_each_domain_when_mask_host_is_primary_default() {
+        assert_eq!(
+            tls_fetch_host_for_domain("a.com", "a.com", "b.com"),
+            "b.com"
+        );
+    }
+
+    #[test]
+    fn tls_fetch_host_preserves_explicit_non_primary_mask_host() {
+        assert_eq!(
+            tls_fetch_host_for_domain("origin.example", "a.com", "b.com"),
+            "origin.example"
+        );
+    }
+}

src/main.rs

@@ -2,12 +2,13 @@
 
 mod api;
 mod cli;
-mod conntrack_control;
 mod config;
+mod conntrack_control;
 mod crypto;
 #[cfg(unix)]
 mod daemon;
 mod error;
+mod healthcheck;
 mod ip_tracker;
 #[cfg(test)]
 #[path = "tests/ip_tracker_encapsulation_adversarial_tests.rs"]
@@ -24,6 +25,7 @@ mod metrics;
 mod network;
 mod protocol;
 mod proxy;
+mod quota_state;
 mod service;
 mod startup;
 mod stats;

src/network/probe.rs

@@ -97,6 +97,7 @@ pub async fn run_probe(
         let UpstreamType::Direct {
             interface,
             bind_addresses,
+            ..
         } = &upstream.upstream_type
         else {
             continue;

src/protocol/tests/tls_security_tests.rs

@@ -1383,6 +1383,8 @@ fn emulated_server_hello_never_places_alpn_in_server_hello_extensions() {
         &session_id,
         &cached,
         false,
+        true,
+        ClientHelloTlsVersion::Tls13,
         &rng,
         Some(b"h2".to_vec()),
         0,
@@ -1624,6 +1626,34 @@ fn test_extract_alpn_multiple() {
     assert_eq!(alpn_str, vec!["h2", "spdy", "h3"]);
 }
 
+#[test]
+fn detect_client_hello_tls_version_prefers_supported_versions_tls13() {
+    let supported_versions = vec![4, 0x03, 0x04, 0x03, 0x03];
+    let ch = build_client_hello_with_exts(vec![(0x002b, supported_versions)], "example.com");
+    assert_eq!(
+        detect_client_hello_tls_version(&ch),
+        Some(ClientHelloTlsVersion::Tls13)
+    );
+}
+
+#[test]
+fn detect_client_hello_tls_version_falls_back_to_legacy_tls12() {
+    let ch = build_client_hello_with_exts(Vec::new(), "example.com");
+    assert_eq!(
+        detect_client_hello_tls_version(&ch),
+        Some(ClientHelloTlsVersion::Tls12)
+    );
+}
+
+#[test]
+fn detect_client_hello_tls_version_rejects_malformed_supported_versions() {
+    // list_len=3 is invalid because version vector must contain u16 pairs.
+    let malformed_supported_versions = vec![3, 0x03, 0x04, 0x03];
+    let ch =
+        build_client_hello_with_exts(vec![(0x002b, malformed_supported_versions)], "example.com");
+    assert!(detect_client_hello_tls_version(&ch).is_none());
+}
+
 #[test]
 fn extract_sni_rejects_zero_length_host_name() {
     let mut sni_ext = Vec::new();

src/protocol/tls.rs

@@ -811,6 +811,122 @@ pub fn extract_alpn_from_client_hello(handshake: &[u8]) -> Vec<Vec<u8>> {
     out
 }
 
+/// ClientHello TLS generation inferred from handshake fields.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ClientHelloTlsVersion {
+    Tls12,
+    Tls13,
+}
+
+/// Detect TLS generation from a ClientHello.
+///
+/// The parser prefers `supported_versions` (0x002b) when present and falls back
+/// to `legacy_version` for compatibility with TLS 1.2 style hellos.
+pub fn detect_client_hello_tls_version(handshake: &[u8]) -> Option<ClientHelloTlsVersion> {
+    if handshake.len() < 5 || handshake[0] != TLS_RECORD_HANDSHAKE {
+        return None;
+    }
+
+    let record_len = u16::from_be_bytes([handshake[3], handshake[4]]) as usize;
+    if handshake.len() < 5 + record_len {
+        return None;
+    }
+
+    let mut pos = 5; // after record header
+    if handshake.get(pos) != Some(&0x01) {
+        return None; // not ClientHello
+    }
+    pos += 1; // message type
+
+    if pos + 3 > handshake.len() {
+        return None;
+    }
+    let handshake_len = ((handshake[pos] as usize) << 16)
+        | ((handshake[pos + 1] as usize) << 8)
+        | handshake[pos + 2] as usize;
+    pos += 3; // handshake length bytes
+    if pos + handshake_len > 5 + record_len {
+        return None;
+    }
+
+    if pos + 2 + 32 > handshake.len() {
+        return None;
+    }
+    let legacy_version = u16::from_be_bytes([handshake[pos], handshake[pos + 1]]);
+    pos += 2 + 32; // version + random
+
+    let session_id_len = *handshake.get(pos)? as usize;
+    pos += 1 + session_id_len;
+    if pos + 2 > handshake.len() {
+        return None;
+    }
+
+    let cipher_len = u16::from_be_bytes([handshake[pos], handshake[pos + 1]]) as usize;
+    pos += 2 + cipher_len;
+    if pos >= handshake.len() {
+        return None;
+    }
+
+    let comp_len = *handshake.get(pos)? as usize;
+    pos += 1 + comp_len;
+    if pos + 2 > handshake.len() {
+        return None;
+    }
+
+    let ext_len = u16::from_be_bytes([handshake[pos], handshake[pos + 1]]) as usize;
+    pos += 2;
+    let ext_end = pos + ext_len;
+    if ext_end > handshake.len() {
+        return None;
+    }
+
+    while pos + 4 <= ext_end {
+        let etype = u16::from_be_bytes([handshake[pos], handshake[pos + 1]]);
+        let elen = u16::from_be_bytes([handshake[pos + 2], handshake[pos + 3]]) as usize;
+        pos += 4;
+        if pos + elen > ext_end {
+            return None;
+        }
+
+        if etype == extension_type::SUPPORTED_VERSIONS {
+            if elen < 1 {
+                return None;
+            }
+            let list_len = handshake[pos] as usize;
+            if list_len == 0 || list_len % 2 != 0 || 1 + list_len > elen {
+                return None;
+            }
+
+            let mut has_tls12 = false;
+            let mut ver_pos = pos + 1;
+            let ver_end = ver_pos + list_len;
+            while ver_pos + 1 < ver_end {
+                let version = u16::from_be_bytes([handshake[ver_pos], handshake[ver_pos + 1]]);
+                if version == 0x0304 {
+                    return Some(ClientHelloTlsVersion::Tls13);
+                }
+                if version == 0x0303 || version == 0x0302 || version == 0x0301 {
+                    has_tls12 = true;
+                }
+                ver_pos += 2;
+            }
+
+            if has_tls12 {
+                return Some(ClientHelloTlsVersion::Tls12);
+            }
+            return None;
+        }
+
+        pos += elen;
+    }
+
+    if legacy_version >= 0x0303 {
+        Some(ClientHelloTlsVersion::Tls12)
+    } else {
+        None
+    }
+}
+
 /// Check if bytes look like a TLS ClientHello
 pub fn is_tls_handshake(first_bytes: &[u8]) -> bool {
     if first_bytes.len() < 3 {

src/proxy/adaptive_buffers.rs

@@ -246,7 +246,9 @@ pub fn seed_tier_for_user(user: &str) -> AdaptiveTier {
         if now.saturating_duration_since(value.seen_at) <= PROFILE_TTL {
             return value.tier;
         }
-        profiles().remove_if(user, |_, v| now.saturating_duration_since(v.seen_at) > PROFILE_TTL);
+        profiles().remove_if(user, |_, v| {
+            now.saturating_duration_since(v.seen_at) > PROFILE_TTL
+        });
     }
     AdaptiveTier::Base
 }

src/proxy/client.rs

@@ -31,38 +31,63 @@ struct UserConnectionReservation {
     ip_tracker: Arc<UserIpTracker>,
     user: String,
     ip: IpAddr,
-    active: bool,
+    tracks_ip: bool,
+    state: SessionReservationState,
+}
+
+#[derive(Clone, Copy, PartialEq, Eq)]
+enum SessionReservationState {
+    Active,
+    Released,
 }
 
 impl UserConnectionReservation {
-    fn new(stats: Arc<Stats>, ip_tracker: Arc<UserIpTracker>, user: String, ip: IpAddr) -> Self {
+    fn new(
+        stats: Arc<Stats>,
+        ip_tracker: Arc<UserIpTracker>,
+        user: String,
+        ip: IpAddr,
+        tracks_ip: bool,
+    ) -> Self {
         Self {
             stats,
             ip_tracker,
             user,
             ip,
-            active: true,
+            tracks_ip,
+            state: SessionReservationState::Active,
         }
     }
 
+    fn mark_released(&mut self) -> bool {
+        if self.state != SessionReservationState::Active {
+            return false;
+        }
+        self.state = SessionReservationState::Released;
+        true
+    }
+
     async fn release(mut self) {
-        if !self.active {
+        if !self.mark_released() {
             return;
         }
-        self.ip_tracker.remove_ip(&self.user, self.ip).await;
-        self.active = false;
+        if self.tracks_ip {
+            self.ip_tracker.remove_ip(&self.user, self.ip).await;
+        }
         self.stats.decrement_user_curr_connects(&self.user);
     }
 }
 
 impl Drop for UserConnectionReservation {
     fn drop(&mut self) {
-        if !self.active {
+        if !self.mark_released() {
             return;
         }
-        self.active = false;
+        self.stats.increment_session_drop_fallback_total();
         self.stats.decrement_user_curr_connects(&self.user);
-        self.ip_tracker.enqueue_cleanup(self.user.clone(), self.ip);
+        if self.tracks_ip {
+            self.ip_tracker.enqueue_cleanup(self.user.clone(), self.ip);
+        }
     }
 }
 
@@ -324,17 +349,38 @@ fn record_beobachten_class(
     beobachten.record(class, peer_ip, beobachten_ttl(config));
 }
 
+fn classify_expected_64_got_0(kind: std::io::ErrorKind) -> Option<&'static str> {
+    match kind {
+        std::io::ErrorKind::UnexpectedEof => Some("expected_64_got_0_unexpected_eof"),
+        std::io::ErrorKind::ConnectionReset => Some("expected_64_got_0_connection_reset"),
+        std::io::ErrorKind::ConnectionAborted => Some("expected_64_got_0_connection_aborted"),
+        std::io::ErrorKind::BrokenPipe => Some("expected_64_got_0_broken_pipe"),
+        std::io::ErrorKind::NotConnected => Some("expected_64_got_0_not_connected"),
+        _ => None,
+    }
+}
+
+fn classify_handshake_failure_class(error: &ProxyError) -> &'static str {
+    match error {
+        ProxyError::Io(err) => classify_expected_64_got_0(err.kind()).unwrap_or("other"),
+        ProxyError::Stream(StreamError::UnexpectedEof) => "expected_64_got_0_unexpected_eof",
+        ProxyError::Stream(StreamError::Io(err)) => {
+            classify_expected_64_got_0(err.kind()).unwrap_or("other")
+        }
+        _ => "other",
+    }
+}
+
 fn record_handshake_failure_class(
     beobachten: &BeobachtenStore,
     config: &ProxyConfig,
     peer_ip: IpAddr,
     error: &ProxyError,
 ) {
-    let class = match error {
-        ProxyError::Io(err) if err.kind() == std::io::ErrorKind::UnexpectedEof => {
-            "expected_64_got_0"
-        }
-        ProxyError::Stream(StreamError::UnexpectedEof) => "expected_64_got_0",
+    // Keep beobachten buckets stable while detailed per-kind classification
+    // is tracked in API counters.
+    let class = match classify_handshake_failure_class(error) {
+        value if value.starts_with("expected_64_got_0_") => "expected_64_got_0",
         _ => "other",
     };
     record_beobachten_class(beobachten, config, peer_ip, class);
@@ -343,7 +389,7 @@ fn record_handshake_failure_class(
 #[inline]
 fn increment_bad_on_unknown_tls_sni(stats: &Stats, error: &ProxyError) {
     if matches!(error, ProxyError::UnknownTlsSni) {
-        stats.increment_connects_bad();
+        stats.increment_connects_bad_with_class("unknown_tls_sni");
     }
 }
 
@@ -433,6 +479,17 @@ where
     let mut local_addr = synthetic_local_addr(config.server.port);
 
     if proxy_protocol_enabled {
+        if !is_trusted_proxy_source(peer.ip(), &config.server.proxy_protocol_trusted_cidrs) {
+            stats.increment_connects_bad_with_class("proxy_protocol_untrusted");
+            warn!(
+                peer = %peer,
+                trusted = ?config.server.proxy_protocol_trusted_cidrs,
+                "Rejecting PROXY protocol header from untrusted source"
+            );
+            record_beobachten_class(&beobachten, &config, peer.ip(), "other");
+            return Err(ProxyError::InvalidProxyProtocol);
+        }
+
         let proxy_header_timeout =
             Duration::from_millis(config.server.proxy_protocol_header_timeout_ms.max(1));
         match timeout(
@@ -442,17 +499,6 @@ where
         .await
         {
             Ok(Ok(info)) => {
-                if !is_trusted_proxy_source(peer.ip(), &config.server.proxy_protocol_trusted_cidrs)
-                {
-                    stats.increment_connects_bad();
-                    warn!(
-                        peer = %peer,
-                        trusted = ?config.server.proxy_protocol_trusted_cidrs,
-                        "Rejecting PROXY protocol header from untrusted source"
-                    );
-                    record_beobachten_class(&beobachten, &config, peer.ip(), "other");
-                    return Err(ProxyError::InvalidProxyProtocol);
-                }
                 debug!(
                     peer = %peer,
                     client = %info.src_addr,
@@ -465,13 +511,13 @@ where
                 }
             }
             Ok(Err(e)) => {
-                stats.increment_connects_bad();
+                stats.increment_connects_bad_with_class("proxy_protocol_invalid_header");
                 warn!(peer = %peer, error = %e, "Invalid PROXY protocol header");
                 record_beobachten_class(&beobachten, &config, peer.ip(), "other");
                 return Err(e);
             }
             Err(_) => {
-                stats.increment_connects_bad();
+                stats.increment_connects_bad_with_class("proxy_protocol_header_timeout");
                 warn!(peer = %peer, timeout_ms = proxy_header_timeout.as_millis(), "PROXY protocol header timeout");
                 record_beobachten_class(&beobachten, &config, peer.ip(), "other");
                 return Err(ProxyError::InvalidProxyProtocol);
@@ -518,15 +564,15 @@ where
                 );
                 return Err(ProxyError::Io(e));
             }
-                Err(_) => {
-                    debug!(
-                        peer = %real_peer,
-                        idle_secs = first_byte_idle_secs,
-                        "Closing idle pooled connection before first client byte"
-                    );
-                    return Ok(());
-                }
+            Err(_) => {
+                debug!(
+                    peer = %real_peer,
+                    idle_secs = first_byte_idle_secs,
+                    "Closing idle pooled connection before first client byte"
+                );
+                return Ok(());
             }
+        }
     };
 
     let handshake_timeout = handshake_timeout_with_mask_grace(&config);
@@ -561,7 +607,7 @@ where
             // third-party clients or future Telegram versions.
             if !tls_clienthello_len_in_bounds(tls_len) {
                 debug!(peer = %real_peer, tls_len = tls_len, max_tls_len = MAX_TLS_PLAINTEXT_SIZE, "TLS handshake length out of bounds");
-                stats.increment_connects_bad();
+                stats.increment_connects_bad_with_class("tls_clienthello_len_out_of_bounds");
                 maybe_apply_mask_reject_delay(&config).await;
                 let (reader, writer) = tokio::io::split(stream);
                 return Ok(masking_outcome(
@@ -581,7 +627,7 @@ where
                 Ok(n) => n,
                 Err(e) => {
                     debug!(peer = %real_peer, error = %e, tls_len = tls_len, "TLS ClientHello body read failed; engaging masking fallback");
-                    stats.increment_connects_bad();
+                    stats.increment_connects_bad_with_class("tls_clienthello_read_error");
                     maybe_apply_mask_reject_delay(&config).await;
                     let initial_len = 5;
                     let (reader, writer) = tokio::io::split(stream);
@@ -599,7 +645,7 @@ where
 
             if body_read < tls_len {
                 debug!(peer = %real_peer, got = body_read, expected = tls_len, "Truncated in-range TLS ClientHello; engaging masking fallback");
-                stats.increment_connects_bad();
+                stats.increment_connects_bad_with_class("tls_clienthello_truncated");
                 maybe_apply_mask_reject_delay(&config).await;
                 let initial_len = 5 + body_read;
                 let (reader, writer) = tokio::io::split(stream);
@@ -623,7 +669,7 @@ where
             ).await {
                 HandshakeResult::Success(result) => result,
                 HandshakeResult::BadClient { reader, writer } => {
-                    stats.increment_connects_bad();
+                    stats.increment_connects_bad_with_class("tls_handshake_bad_client");
                     return Ok(masking_outcome(
                         reader,
                         writer,
@@ -663,7 +709,7 @@ where
                         wrap_tls_application_record(&pending_plaintext)
                     };
                     let reader = tokio::io::AsyncReadExt::chain(std::io::Cursor::new(pending_record), reader);
-                    stats.increment_connects_bad();
+                    stats.increment_connects_bad_with_class("tls_mtproto_bad_client");
                     debug!(
                         peer = %peer,
                         "Authenticated TLS session failed MTProto validation; engaging masking fallback"
@@ -693,7 +739,7 @@ where
         } else {
             if !config.general.modes.classic && !config.general.modes.secure {
                 debug!(peer = %real_peer, "Non-TLS modes disabled");
-                stats.increment_connects_bad();
+                stats.increment_connects_bad_with_class("direct_modes_disabled");
                 maybe_apply_mask_reject_delay(&config).await;
                 let (reader, writer) = tokio::io::split(stream);
                 return Ok(masking_outcome(
@@ -720,7 +766,7 @@ where
             ).await {
                 HandshakeResult::Success(result) => result,
                 HandshakeResult::BadClient { reader, writer } => {
-                    stats.increment_connects_bad();
+                    stats.increment_connects_bad_with_class("direct_mtproto_bad_client");
                     return Ok(masking_outcome(
                         reader,
                         writer,
@@ -757,6 +803,7 @@ where
         Ok(Ok(outcome)) => outcome,
         Ok(Err(e)) => {
             debug!(peer = %peer, error = %e, "Handshake failed");
+            stats_for_timeout.increment_handshake_failure_class(classify_handshake_failure_class(&e));
             record_handshake_failure_class(
                 &beobachten_for_timeout,
                 &config_for_timeout,
@@ -767,6 +814,7 @@ where
         }
         Err(_) => {
             stats_for_timeout.increment_handshake_timeouts();
+            stats_for_timeout.increment_handshake_failure_class("timeout");
             debug!(peer = %peer, "Handshake timeout");
             record_beobachten_class(
                 &beobachten_for_timeout,
@@ -804,6 +852,9 @@ pub struct RunningClientHandler {
     beobachten: Arc<BeobachtenStore>,
     shared: Arc<ProxySharedState>,
     proxy_protocol_enabled: bool,
+    #[cfg(unix)]
+    raw_fd: std::os::unix::io::RawFd,
+    rst_on_close: crate::config::RstOnCloseMode,
 }
 
 impl ClientHandler {
@@ -825,6 +876,11 @@ impl ClientHandler {
         proxy_protocol_enabled: bool,
         real_peer_report: Arc<std::sync::Mutex<Option<SocketAddr>>>,
     ) -> RunningClientHandler {
+        #[cfg(unix)]
+        let raw_fd = {
+            use std::os::unix::io::AsRawFd;
+            stream.as_raw_fd()
+        };
         Self::new_with_shared(
             stream,
             peer,
@@ -842,6 +898,9 @@ impl ClientHandler {
             ProxySharedState::new(),
             proxy_protocol_enabled,
             real_peer_report,
+            #[cfg(unix)]
+            raw_fd,
+            crate::config::RstOnCloseMode::Off,
         )
     }
 
@@ -863,6 +922,8 @@ impl ClientHandler {
         shared: Arc<ProxySharedState>,
         proxy_protocol_enabled: bool,
         real_peer_report: Arc<std::sync::Mutex<Option<SocketAddr>>>,
+        #[cfg(unix)] raw_fd: std::os::unix::io::RawFd,
+        rst_on_close: crate::config::RstOnCloseMode,
     ) -> RunningClientHandler {
         let normalized_peer = normalize_ip(peer);
         RunningClientHandler {
@@ -883,6 +944,9 @@ impl ClientHandler {
             beobachten,
             shared,
             proxy_protocol_enabled,
+            #[cfg(unix)]
+            raw_fd,
+            rst_on_close,
         }
     }
 }
@@ -901,6 +965,10 @@ impl RunningClientHandler {
             debug!(peer = %peer, error = %e, "Failed to configure client socket");
         }
 
+        #[cfg(unix)]
+        let raw_fd = self.raw_fd;
+        let rst_on_close = self.rst_on_close;
+
         let outcome = match self.do_handshake().await? {
             Some(outcome) => outcome,
             None => return Ok(()),
@@ -908,7 +976,14 @@ impl RunningClientHandler {
 
         // Phase 2: relay (WITHOUT handshake timeout — relay has its own activity timeouts)
         match outcome {
-            HandshakeOutcome::NeedsRelay(fut) | HandshakeOutcome::NeedsMasking(fut) => fut.await,
+            HandshakeOutcome::NeedsRelay(fut) => {
+                #[cfg(unix)]
+                if matches!(rst_on_close, crate::config::RstOnCloseMode::Errors) {
+                    let _ = crate::transport::socket::clear_linger_fd(raw_fd);
+                }
+                fut.await
+            }
+            HandshakeOutcome::NeedsMasking(fut) => fut.await,
         }
     }
 
@@ -916,6 +991,21 @@ impl RunningClientHandler {
         let mut local_addr = self.stream.local_addr().map_err(ProxyError::Io)?;
 
         if self.proxy_protocol_enabled {
+            if !is_trusted_proxy_source(
+                self.peer.ip(),
+                &self.config.server.proxy_protocol_trusted_cidrs,
+            ) {
+                self.stats
+                    .increment_connects_bad_with_class("proxy_protocol_untrusted");
+                warn!(
+                    peer = %self.peer,
+                    trusted = ?self.config.server.proxy_protocol_trusted_cidrs,
+                    "Rejecting PROXY protocol header from untrusted source"
+                );
+                record_beobachten_class(&self.beobachten, &self.config, self.peer.ip(), "other");
+                return Err(ProxyError::InvalidProxyProtocol);
+            }
+
             let proxy_header_timeout =
                 Duration::from_millis(self.config.server.proxy_protocol_header_timeout_ms.max(1));
             match timeout(
@@ -925,24 +1015,6 @@ impl RunningClientHandler {
             .await
             {
                 Ok(Ok(info)) => {
-                    if !is_trusted_proxy_source(
-                        self.peer.ip(),
-                        &self.config.server.proxy_protocol_trusted_cidrs,
-                    ) {
-                        self.stats.increment_connects_bad();
-                        warn!(
-                            peer = %self.peer,
-                            trusted = ?self.config.server.proxy_protocol_trusted_cidrs,
-                            "Rejecting PROXY protocol header from untrusted source"
-                        );
-                        record_beobachten_class(
-                            &self.beobachten,
-                            &self.config,
-                            self.peer.ip(),
-                            "other",
-                        );
-                        return Err(ProxyError::InvalidProxyProtocol);
-                    }
                     debug!(
                         peer = %self.peer,
                         client = %info.src_addr,
@@ -959,7 +1031,8 @@ impl RunningClientHandler {
                     }
                 }
                 Ok(Err(e)) => {
-                    self.stats.increment_connects_bad();
+                    self.stats
+                        .increment_connects_bad_with_class("proxy_protocol_invalid_header");
                     warn!(peer = %self.peer, error = %e, "Invalid PROXY protocol header");
                     record_beobachten_class(
                         &self.beobachten,
@@ -970,7 +1043,8 @@ impl RunningClientHandler {
                     return Err(e);
                 }
                 Err(_) => {
-                    self.stats.increment_connects_bad();
+                    self.stats
+                        .increment_connects_bad_with_class("proxy_protocol_header_timeout");
                     warn!(
                         peer = %self.peer,
                         timeout_ms = proxy_header_timeout.as_millis(),
@@ -1068,6 +1142,7 @@ impl RunningClientHandler {
             Ok(Ok(outcome)) => outcome,
             Ok(Err(e)) => {
                 debug!(peer = %peer_for_log, error = %e, "Handshake failed");
+                stats.increment_handshake_failure_class(classify_handshake_failure_class(&e));
                 record_handshake_failure_class(
                     &beobachten_for_timeout,
                     &config_for_timeout,
@@ -1078,6 +1153,7 @@ impl RunningClientHandler {
             }
             Err(_) => {
                 stats.increment_handshake_timeouts();
+                stats.increment_handshake_failure_class("timeout");
                 debug!(peer = %peer_for_log, "Handshake timeout");
                 record_beobachten_class(
                     &beobachten_for_timeout,
@@ -1113,7 +1189,8 @@ impl RunningClientHandler {
         // third-party clients or future Telegram versions.
         if !tls_clienthello_len_in_bounds(tls_len) {
             debug!(peer = %peer, tls_len = tls_len, max_tls_len = MAX_TLS_PLAINTEXT_SIZE, "TLS handshake length out of bounds");
-            self.stats.increment_connects_bad();
+            self.stats
+                .increment_connects_bad_with_class("tls_clienthello_len_out_of_bounds");
             maybe_apply_mask_reject_delay(&self.config).await;
             let (reader, writer) = self.stream.into_split();
             return Ok(masking_outcome(
@@ -1133,7 +1210,8 @@ impl RunningClientHandler {
             Ok(n) => n,
             Err(e) => {
                 debug!(peer = %peer, error = %e, tls_len = tls_len, "TLS ClientHello body read failed; engaging masking fallback");
-                self.stats.increment_connects_bad();
+                self.stats
+                    .increment_connects_bad_with_class("tls_clienthello_read_error");
                 maybe_apply_mask_reject_delay(&self.config).await;
                 let (reader, writer) = self.stream.into_split();
                 return Ok(masking_outcome(
@@ -1150,7 +1228,8 @@ impl RunningClientHandler {
 
         if body_read < tls_len {
             debug!(peer = %peer, got = body_read, expected = tls_len, "Truncated in-range TLS ClientHello; engaging masking fallback");
-            self.stats.increment_connects_bad();
+            self.stats
+                .increment_connects_bad_with_class("tls_clienthello_truncated");
             maybe_apply_mask_reject_delay(&self.config).await;
             let initial_len = 5 + body_read;
             let (reader, writer) = self.stream.into_split();
@@ -1187,7 +1266,7 @@ impl RunningClientHandler {
         {
             HandshakeResult::Success(result) => result,
             HandshakeResult::BadClient { reader, writer } => {
-                stats.increment_connects_bad();
+                stats.increment_connects_bad_with_class("tls_handshake_bad_client");
                 return Ok(masking_outcome(
                     reader,
                     writer,
@@ -1237,7 +1316,7 @@ impl RunningClientHandler {
                 };
                 let reader =
                     tokio::io::AsyncReadExt::chain(std::io::Cursor::new(pending_record), reader);
-                stats.increment_connects_bad();
+                stats.increment_connects_bad_with_class("tls_mtproto_bad_client");
                 debug!(
                     peer = %peer,
                     "Authenticated TLS session failed MTProto validation; engaging masking fallback"
@@ -1284,7 +1363,8 @@ impl RunningClientHandler {
 
         if !self.config.general.modes.classic && !self.config.general.modes.secure {
             debug!(peer = %peer, "Non-TLS modes disabled");
-            self.stats.increment_connects_bad();
+            self.stats
+                .increment_connects_bad_with_class("direct_modes_disabled");
             maybe_apply_mask_reject_delay(&self.config).await;
             let (reader, writer) = self.stream.into_split();
             return Ok(masking_outcome(
@@ -1324,7 +1404,7 @@ impl RunningClientHandler {
         {
             HandshakeResult::Success(result) => result,
             HandshakeResult::BadClient { reader, writer } => {
-                stats.increment_connects_bad();
+                stats.increment_connects_bad_with_class("direct_mtproto_bad_client");
                 return Ok(masking_outcome(
                     reader,
                     writer,
@@ -1360,8 +1440,8 @@ impl RunningClientHandler {
 
     /// Main dispatch after successful handshake.
     /// Two modes:
-    ///   - Direct: TCP relay to TG DC (existing behavior)  
-    ///   - Middle Proxy: RPC multiplex through ME pool (new — supports CDN DCs)
+    ///   - Direct: TCP relay to TG DC (existing behavior)
+    ///   - Middle Proxy: RPC multiplex through ME pool (supports CDN DCs)
     #[cfg(test)]
     async fn handle_authenticated_static<R, W>(
         client_reader: CryptoReader<R>,
@@ -1562,6 +1642,7 @@ impl RunningClientHandler {
             ip_tracker,
             user.to_string(),
             peer_addr.ip(),
+            true,
         ))
     }
 
@@ -1607,7 +1688,6 @@ impl RunningClientHandler {
         match ip_tracker.check_and_add(user, peer_addr.ip()).await {
             Ok(()) => {
                 ip_tracker.remove_ip(user, peer_addr.ip()).await;
-                stats.decrement_user_curr_connects(user);
             }
             Err(reason) => {
                 stats.decrement_user_curr_connects(user);
@@ -1623,6 +1703,7 @@ impl RunningClientHandler {
             }
         }
 
+        stats.decrement_user_curr_connects(user);
         Ok(())
     }
 }

src/proxy/direct_relay.rs

@@ -17,13 +17,12 @@ use crate::crypto::SecureRandom;
 use crate::error::{ProxyError, Result};
 use crate::protocol::constants::*;
 use crate::proxy::handshake::{HandshakeSuccess, encrypt_tg_nonce_with_ciphers, generate_tg_nonce};
+use crate::proxy::route_mode::{
+    RelayRouteMode, RouteCutoverState, affected_cutover_state, cutover_stagger_delay,
+};
 use crate::proxy::shared_state::{
     ConntrackCloseEvent, ConntrackClosePublishResult, ConntrackCloseReason, ProxySharedState,
 };
-use crate::proxy::route_mode::{
-    ROUTE_SWITCH_ERROR_MSG, RelayRouteMode, RouteCutoverState, affected_cutover_state,
-    cutover_stagger_delay,
-};
 use crate::stats::Stats;
 use crate::stream::{BufferPool, CryptoReader, CryptoWriter};
 use crate::transport::UpstreamManager;
@@ -316,6 +315,9 @@ where
 
     stats.increment_user_connects(user);
     let _direct_connection_lease = stats.acquire_direct_connection_lease();
+    let traffic_lease = shared
+        .traffic_limiter
+        .acquire_lease(user, success.peer.ip());
 
     let buffer_pool_trim = Arc::clone(&buffer_pool);
     let relay_activity_timeout = if shared.conntrack_pressure_active() {
@@ -329,7 +331,7 @@ where
     } else {
         Duration::from_secs(1800)
     };
-    let relay_result = crate::proxy::relay::relay_bidirectional_with_activity_timeout(
+    let relay_result = crate::proxy::relay::relay_bidirectional_with_activity_timeout_and_lease(
         client_reader,
         client_writer,
         tg_reader,
@@ -340,6 +342,7 @@ where
         Arc::clone(&stats),
         config.access.user_data_quota.get(user).copied(),
         buffer_pool,
+        traffic_lease,
         relay_activity_timeout,
     );
     tokio::pin!(relay_result);
@@ -356,7 +359,7 @@ where
                 "Cutover affected direct session, closing client connection"
             );
             tokio::time::sleep(delay).await;
-            break Err(ProxyError::Proxy(ROUTE_SWITCH_ERROR_MSG.to_string()));
+            break Err(ProxyError::RouteSwitched);
         }
         tokio::select! {
             result = &mut relay_result => {

src/proxy/masking.rs

@@ -2,6 +2,7 @@
 
 use crate::config::ProxyConfig;
 use crate::network::dns_overrides::resolve_socket_addr;
+use crate::protocol::tls;
 use crate::stats::beobachten::BeobachtenStore;
 use crate::transport::proxy_protocol::{ProxyProtocolV1Builder, ProxyProtocolV2Builder};
 #[cfg(unix)]
@@ -28,14 +29,10 @@ use tracing::debug;
 const MASK_TIMEOUT: Duration = Duration::from_secs(5);
 #[cfg(test)]
 const MASK_TIMEOUT: Duration = Duration::from_millis(50);
-/// Maximum duration for the entire masking relay.
-/// Limits resource consumption from slow-loris attacks and port scanners.
-#[cfg(not(test))]
-const MASK_RELAY_TIMEOUT: Duration = Duration::from_secs(60);
+/// Maximum duration for the entire masking relay under test (replaced by config at runtime).
 #[cfg(test)]
 const MASK_RELAY_TIMEOUT: Duration = Duration::from_millis(200);
-#[cfg(not(test))]
-const MASK_RELAY_IDLE_TIMEOUT: Duration = Duration::from_secs(5);
+/// Per-read idle timeout for masking relay and drain paths under test (replaced by config at runtime).
 #[cfg(test)]
 const MASK_RELAY_IDLE_TIMEOUT: Duration = Duration::from_millis(100);
 const MASK_BUFFER_SIZE: usize = 8192;
@@ -55,6 +52,7 @@ async fn copy_with_idle_timeout<R, W>(
     writer: &mut W,
     byte_cap: usize,
     shutdown_on_eof: bool,
+    idle_timeout: Duration,
 ) -> CopyOutcome
 where
     R: AsyncRead + Unpin,
@@ -63,22 +61,19 @@ where
     let mut buf = Box::new([0u8; MASK_BUFFER_SIZE]);
     let mut total = 0usize;
     let mut ended_by_eof = false;
-
-    if byte_cap == 0 {
-        return CopyOutcome {
-            total,
-            ended_by_eof,
-        };
-    }
+    let unlimited = byte_cap == 0;
 
     loop {
-        let remaining_budget = byte_cap.saturating_sub(total);
-        if remaining_budget == 0 {
-            break;
-        }
-
-        let read_len = remaining_budget.min(MASK_BUFFER_SIZE);
-        let read_res = timeout(MASK_RELAY_IDLE_TIMEOUT, reader.read(&mut buf[..read_len])).await;
+        let read_len = if unlimited {
+            MASK_BUFFER_SIZE
+        } else {
+            let remaining_budget = byte_cap.saturating_sub(total);
+            if remaining_budget == 0 {
+                break;
+            }
+            remaining_budget.min(MASK_BUFFER_SIZE)
+        };
+        let read_res = timeout(idle_timeout, reader.read(&mut buf[..read_len])).await;
         let n = match read_res {
             Ok(Ok(n)) => n,
             Ok(Err(_)) | Err(_) => break,
@@ -86,13 +81,13 @@ where
         if n == 0 {
             ended_by_eof = true;
             if shutdown_on_eof {
-                let _ = timeout(MASK_RELAY_IDLE_TIMEOUT, writer.shutdown()).await;
+                let _ = timeout(idle_timeout, writer.shutdown()).await;
             }
             break;
         }
         total = total.saturating_add(n);
 
-        let write_res = timeout(MASK_RELAY_IDLE_TIMEOUT, writer.write_all(&buf[..n])).await;
+        let write_res = timeout(idle_timeout, writer.write_all(&buf[..n])).await;
         match write_res {
             Ok(Ok(())) => {}
             Ok(Err(_)) | Err(_) => break,
@@ -230,13 +225,20 @@ where
     }
 }
 
-async fn consume_client_data_with_timeout_and_cap<R>(reader: R, byte_cap: usize)
-where
+async fn consume_client_data_with_timeout_and_cap<R>(
+    reader: R,
+    byte_cap: usize,
+    relay_timeout: Duration,
+    idle_timeout: Duration,
+) where
     R: AsyncRead + Unpin,
 {
-    if timeout(MASK_RELAY_TIMEOUT, consume_client_data(reader, byte_cap))
-        .await
-        .is_err()
+    if timeout(
+        relay_timeout,
+        consume_client_data(reader, byte_cap, idle_timeout),
+    )
+    .await
+    .is_err()
     {
         debug!("Timed out while consuming client data on masking fallback path");
     }
@@ -255,7 +257,11 @@ async fn wait_mask_connect_budget(started: Instant) {
 // sigma is chosen so ~99% of raw samples land inside [floor, ceiling] before clamp.
 // When floor > ceiling (misconfiguration), returns ceiling (the smaller value).
 // When floor == ceiling, returns that value. When both are 0, returns 0.
-pub(crate) fn sample_lognormal_percentile_bounded(floor: u64, ceiling: u64, rng: &mut impl Rng) -> u64 {
+pub(crate) fn sample_lognormal_percentile_bounded(
+    floor: u64,
+    ceiling: u64,
+    rng: &mut impl Rng,
+) -> u64 {
     if ceiling == 0 && floor == 0 {
         return 0;
     }
@@ -296,7 +302,9 @@ fn mask_outcome_target_budget(config: &ProxyConfig) -> Duration {
         }
         if ceiling > floor {
             let mut rng = rand::rng();
-            return Duration::from_millis(sample_lognormal_percentile_bounded(floor, ceiling, &mut rng));
+            return Duration::from_millis(sample_lognormal_percentile_bounded(
+                floor, ceiling, &mut rng,
+            ));
         }
         // ceiling <= floor: use the larger value (fail-closed: preserve longer delay)
         return Duration::from_millis(floor.max(ceiling));
@@ -321,6 +329,89 @@ async fn wait_mask_outcome_budget(started: Instant, config: &ProxyConfig) {
     }
 }
 
+#[cfg(test)]
+mod tls_domain_mask_host_tests {
+    use super::{mask_host_for_initial_data, matching_tls_domain_for_sni};
+    use crate::config::ProxyConfig;
+
+    fn client_hello_with_sni(sni_host: &str) -> Vec<u8> {
+        let mut body = Vec::new();
+        body.extend_from_slice(&[0x03, 0x03]);
+        body.extend_from_slice(&[0u8; 32]);
+        body.push(32);
+        body.extend_from_slice(&[0x42u8; 32]);
+        body.extend_from_slice(&2u16.to_be_bytes());
+        body.extend_from_slice(&[0x13, 0x01]);
+        body.push(1);
+        body.push(0);
+
+        let host_bytes = sni_host.as_bytes();
+        let mut sni_payload = Vec::new();
+        sni_payload.extend_from_slice(&((host_bytes.len() + 3) as u16).to_be_bytes());
+        sni_payload.push(0);
+        sni_payload.extend_from_slice(&(host_bytes.len() as u16).to_be_bytes());
+        sni_payload.extend_from_slice(host_bytes);
+
+        let mut extensions = Vec::new();
+        extensions.extend_from_slice(&0x0000u16.to_be_bytes());
+        extensions.extend_from_slice(&(sni_payload.len() as u16).to_be_bytes());
+        extensions.extend_from_slice(&sni_payload);
+        body.extend_from_slice(&(extensions.len() as u16).to_be_bytes());
+        body.extend_from_slice(&extensions);
+
+        let mut handshake = Vec::new();
+        handshake.push(0x01);
+        let body_len = (body.len() as u32).to_be_bytes();
+        handshake.extend_from_slice(&body_len[1..4]);
+        handshake.extend_from_slice(&body);
+
+        let mut record = Vec::new();
+        record.push(0x16);
+        record.extend_from_slice(&[0x03, 0x01]);
+        record.extend_from_slice(&(handshake.len() as u16).to_be_bytes());
+        record.extend_from_slice(&handshake);
+        record
+    }
+
+    fn config_with_tls_domains() -> ProxyConfig {
+        let mut config = ProxyConfig::default();
+        config.censorship.tls_domain = "a.com".to_string();
+        config.censorship.tls_domains = vec!["b.com".to_string(), "c.com".to_string()];
+        config.censorship.mask_host = Some("a.com".to_string());
+        config
+    }
+
+    #[test]
+    fn matching_tls_domain_accepts_primary_and_extra_domains_case_insensitively() {
+        let config = config_with_tls_domains();
+
+        assert_eq!(matching_tls_domain_for_sni(&config, "A.COM"), Some("a.com"));
+        assert_eq!(matching_tls_domain_for_sni(&config, "B.COM"), Some("b.com"));
+        assert_eq!(matching_tls_domain_for_sni(&config, "unknown.com"), None);
+    }
+
+    #[test]
+    fn mask_host_preserves_explicit_non_primary_origin() {
+        let mut config = config_with_tls_domains();
+        config.censorship.mask_host = Some("origin.example".to_string());
+
+        let initial_data = client_hello_with_sni("b.com");
+
+        assert_eq!(
+            mask_host_for_initial_data(&config, &initial_data),
+            "origin.example"
+        );
+    }
+
+    #[test]
+    fn mask_host_uses_matching_tls_domain_when_mask_host_is_primary_default() {
+        let config = config_with_tls_domains();
+        let initial_data = client_hello_with_sni("b.com");
+
+        assert_eq!(mask_host_for_initial_data(&config, &initial_data), "b.com");
+    }
+}
+
 /// Detect client type based on initial data
 fn detect_client_type(data: &[u8]) -> &'static str {
     // Check for HTTP request
@@ -353,6 +444,37 @@ fn parse_mask_host_ip_literal(host: &str) -> Option<IpAddr> {
     host.parse::<IpAddr>().ok()
 }
 
+fn matching_tls_domain_for_sni<'a>(config: &'a ProxyConfig, sni: &str) -> Option<&'a str> {
+    if config.censorship.tls_domain.eq_ignore_ascii_case(sni) {
+        return Some(config.censorship.tls_domain.as_str());
+    }
+
+    for domain in &config.censorship.tls_domains {
+        if domain.eq_ignore_ascii_case(sni) {
+            return Some(domain.as_str());
+        }
+    }
+
+    None
+}
+
+fn mask_host_for_initial_data<'a>(config: &'a ProxyConfig, initial_data: &[u8]) -> &'a str {
+    let configured_mask_host = config
+        .censorship
+        .mask_host
+        .as_deref()
+        .unwrap_or(&config.censorship.tls_domain);
+
+    if !configured_mask_host.eq_ignore_ascii_case(&config.censorship.tls_domain) {
+        return configured_mask_host;
+    }
+
+    tls::extract_sni_from_client_hello(initial_data)
+        .as_deref()
+        .and_then(|sni| matching_tls_domain_for_sni(config, sni))
+        .unwrap_or(configured_mask_host)
+}
+
 fn canonical_ip(ip: IpAddr) -> IpAddr {
     match ip {
         IpAddr::V6(v6) => v6
@@ -633,10 +755,18 @@ pub async fn handle_bad_client<R, W>(
         beobachten.record(client_type, peer.ip(), ttl);
     }
 
+    let relay_timeout = Duration::from_millis(config.censorship.mask_relay_timeout_ms);
+    let idle_timeout = Duration::from_millis(config.censorship.mask_relay_idle_timeout_ms);
+
     if !config.censorship.mask {
         // Masking disabled, just consume data
-        consume_client_data_with_timeout_and_cap(reader, config.censorship.mask_relay_max_bytes)
-            .await;
+        consume_client_data_with_timeout_and_cap(
+            reader,
+            config.censorship.mask_relay_max_bytes,
+            relay_timeout,
+            idle_timeout,
+        )
+        .await;
         return;
     }
 
@@ -668,7 +798,7 @@ pub async fn handle_bad_client<R, W>(
                     return;
                 }
                 if timeout(
-                    MASK_RELAY_TIMEOUT,
+                    relay_timeout,
                     relay_to_mask(
                         reader,
                         writer,
@@ -682,6 +812,7 @@ pub async fn handle_bad_client<R, W>(
                         config.censorship.mask_shape_above_cap_blur_max_bytes,
                         config.censorship.mask_shape_hardening_aggressive_mode,
                         config.censorship.mask_relay_max_bytes,
+                        idle_timeout,
                     ),
                 )
                 .await
@@ -697,6 +828,8 @@ pub async fn handle_bad_client<R, W>(
                 consume_client_data_with_timeout_and_cap(
                     reader,
                     config.censorship.mask_relay_max_bytes,
+                    relay_timeout,
+                    idle_timeout,
                 )
                 .await;
                 wait_mask_outcome_budget(outcome_started, config).await;
@@ -706,6 +839,8 @@ pub async fn handle_bad_client<R, W>(
                 consume_client_data_with_timeout_and_cap(
                     reader,
                     config.censorship.mask_relay_max_bytes,
+                    relay_timeout,
+                    idle_timeout,
                 )
                 .await;
                 wait_mask_outcome_budget(outcome_started, config).await;
@@ -714,11 +849,7 @@ pub async fn handle_bad_client<R, W>(
         return;
     }
 
-    let mask_host = config
-        .censorship
-        .mask_host
-        .as_deref()
-        .unwrap_or(&config.censorship.tls_domain);
+    let mask_host = mask_host_for_initial_data(config, initial_data);
     let mask_port = config.censorship.mask_port;
 
     // Fail closed when fallback points at our own listener endpoint.
@@ -736,8 +867,13 @@ pub async fn handle_bad_client<R, W>(
             local = %local_addr,
             "Mask target resolves to local listener; refusing self-referential masking fallback"
         );
-        consume_client_data_with_timeout_and_cap(reader, config.censorship.mask_relay_max_bytes)
-            .await;
+        consume_client_data_with_timeout_and_cap(
+            reader,
+            config.censorship.mask_relay_max_bytes,
+            relay_timeout,
+            idle_timeout,
+        )
+        .await;
         wait_mask_outcome_budget(outcome_started, config).await;
         return;
     }
@@ -771,7 +907,7 @@ pub async fn handle_bad_client<R, W>(
                 return;
             }
             if timeout(
-                MASK_RELAY_TIMEOUT,
+                relay_timeout,
                 relay_to_mask(
                     reader,
                     writer,
@@ -785,6 +921,7 @@ pub async fn handle_bad_client<R, W>(
                     config.censorship.mask_shape_above_cap_blur_max_bytes,
                     config.censorship.mask_shape_hardening_aggressive_mode,
                     config.censorship.mask_relay_max_bytes,
+                    idle_timeout,
                 ),
             )
             .await
@@ -800,6 +937,8 @@ pub async fn handle_bad_client<R, W>(
             consume_client_data_with_timeout_and_cap(
                 reader,
                 config.censorship.mask_relay_max_bytes,
+                relay_timeout,
+                idle_timeout,
             )
             .await;
             wait_mask_outcome_budget(outcome_started, config).await;
@@ -809,6 +948,8 @@ pub async fn handle_bad_client<R, W>(
             consume_client_data_with_timeout_and_cap(
                 reader,
                 config.censorship.mask_relay_max_bytes,
+                relay_timeout,
+                idle_timeout,
             )
             .await;
             wait_mask_outcome_budget(outcome_started, config).await;
@@ -830,6 +971,7 @@ async fn relay_to_mask<R, W, MR, MW>(
     shape_above_cap_blur_max_bytes: usize,
     shape_hardening_aggressive_mode: bool,
     mask_relay_max_bytes: usize,
+    idle_timeout: Duration,
 ) where
     R: AsyncRead + Unpin + Send + 'static,
     W: AsyncWrite + Unpin + Send + 'static,
@@ -851,11 +993,19 @@ async fn relay_to_mask<R, W, MR, MW>(
                 &mut mask_write,
                 mask_relay_max_bytes,
                 !shape_hardening_enabled,
+                idle_timeout,
             )
             .await
         },
         async {
-            copy_with_idle_timeout(&mut mask_read, &mut writer, mask_relay_max_bytes, true).await
+            copy_with_idle_timeout(
+                &mut mask_read,
+                &mut writer,
+                mask_relay_max_bytes,
+                true,
+                idle_timeout,
+            )
+            .await
         }
     );
 
@@ -883,23 +1033,27 @@ async fn relay_to_mask<R, W, MR, MW>(
 }
 
 /// Just consume all data from client without responding.
-async fn consume_client_data<R: AsyncRead + Unpin>(mut reader: R, byte_cap: usize) {
-    if byte_cap == 0 {
-        return;
-    }
-
+async fn consume_client_data<R: AsyncRead + Unpin>(
+    mut reader: R,
+    byte_cap: usize,
+    idle_timeout: Duration,
+) {
     // Keep drain path fail-closed under slow-loris stalls.
     let mut buf = Box::new([0u8; MASK_BUFFER_SIZE]);
     let mut total = 0usize;
+    let unlimited = byte_cap == 0;
 
     loop {
-        let remaining_budget = byte_cap.saturating_sub(total);
-        if remaining_budget == 0 {
-            break;
-        }
-
-        let read_len = remaining_budget.min(MASK_BUFFER_SIZE);
-        let n = match timeout(MASK_RELAY_IDLE_TIMEOUT, reader.read(&mut buf[..read_len])).await {
+        let read_len = if unlimited {
+            MASK_BUFFER_SIZE
+        } else {
+            let remaining_budget = byte_cap.saturating_sub(total);
+            if remaining_budget == 0 {
+                break;
+            }
+            remaining_budget.min(MASK_BUFFER_SIZE)
+        };
+        let n = match timeout(idle_timeout, reader.read(&mut buf[..read_len])).await {
             Ok(Ok(n)) => n,
             Ok(Err(_)) | Err(_) => break,
         };
@@ -909,7 +1063,7 @@ async fn consume_client_data<R: AsyncRead + Unpin>(mut reader: R, byte_cap: usiz
         }
 
         total = total.saturating_add(n);
-        if total >= byte_cap {
+        if !unlimited && total >= byte_cap {
             break;
         }
     }

src/proxy/mod.rs

@@ -68,6 +68,7 @@ pub mod relay;
 pub mod route_mode;
 pub mod session_eviction;
 pub mod shared_state;
+pub mod traffic_limiter;
 
 pub use client::ClientHandler;
 #[allow(unused_imports)]

src/proxy/relay.rs

@@ -52,6 +52,7 @@
 //! - `SharedCounters` (atomics) let the watchdog read stats without locking
 
 use crate::error::{ProxyError, Result};
+use crate::proxy::traffic_limiter::{RateDirection, TrafficLease, next_refill_delay};
 use crate::stats::{Stats, UserStats};
 use crate::stream::BufferPool;
 use std::io;
@@ -61,7 +62,7 @@ use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
 use std::task::{Context, Poll};
 use std::time::Duration;
 use tokio::io::{AsyncRead, AsyncWrite, AsyncWriteExt, ReadBuf, copy_bidirectional_with_sizes};
-use tokio::time::Instant;
+use tokio::time::{Instant, Sleep};
 use tracing::{debug, trace, warn};
 
 // ============= Constants =============
@@ -210,13 +211,27 @@ struct StatsIo<S> {
     stats: Arc<Stats>,
     user: String,
     user_stats: Arc<UserStats>,
+    traffic_lease: Option<Arc<TrafficLease>>,
+    c2s_rate_debt_bytes: u64,
+    c2s_wait: RateWaitState,
+    s2c_wait: RateWaitState,
+    quota_wait: RateWaitState,
     quota_limit: Option<u64>,
     quota_exceeded: Arc<AtomicBool>,
     quota_bytes_since_check: u64,
     epoch: Instant,
 }
 
+#[derive(Default)]
+struct RateWaitState {
+    sleep: Option<Pin<Box<Sleep>>>,
+    started_at: Option<Instant>,
+    blocked_user: bool,
+    blocked_cidr: bool,
+}
+
 impl<S> StatsIo<S> {
+    #[cfg(test)]
     fn new(
         inner: S,
         counters: Arc<SharedCounters>,
@@ -225,6 +240,28 @@ impl<S> StatsIo<S> {
         quota_limit: Option<u64>,
         quota_exceeded: Arc<AtomicBool>,
         epoch: Instant,
+    ) -> Self {
+        Self::new_with_traffic_lease(
+            inner,
+            counters,
+            stats,
+            user,
+            None,
+            quota_limit,
+            quota_exceeded,
+            epoch,
+        )
+    }
+
+    fn new_with_traffic_lease(
+        inner: S,
+        counters: Arc<SharedCounters>,
+        stats: Arc<Stats>,
+        user: String,
+        traffic_lease: Option<Arc<TrafficLease>>,
+        quota_limit: Option<u64>,
+        quota_exceeded: Arc<AtomicBool>,
+        epoch: Instant,
     ) -> Self {
         // Mark initial activity so the watchdog doesn't fire before data flows
         counters.touch(Instant::now(), epoch);
@@ -235,12 +272,94 @@ impl<S> StatsIo<S> {
             stats,
             user,
             user_stats,
+            traffic_lease,
+            c2s_rate_debt_bytes: 0,
+            c2s_wait: RateWaitState::default(),
+            s2c_wait: RateWaitState::default(),
+            quota_wait: RateWaitState::default(),
             quota_limit,
             quota_exceeded,
             quota_bytes_since_check: 0,
             epoch,
         }
     }
+
+    fn record_wait(
+        wait: &mut RateWaitState,
+        lease: Option<&Arc<TrafficLease>>,
+        direction: RateDirection,
+    ) {
+        let Some(started_at) = wait.started_at.take() else {
+            return;
+        };
+        let wait_ms = started_at.elapsed().as_millis().min(u128::from(u64::MAX)) as u64;
+        if let Some(lease) = lease {
+            lease.observe_wait_ms(direction, wait.blocked_user, wait.blocked_cidr, wait_ms);
+        }
+        wait.blocked_user = false;
+        wait.blocked_cidr = false;
+    }
+
+    fn arm_wait(wait: &mut RateWaitState, blocked_user: bool, blocked_cidr: bool) {
+        if wait.sleep.is_none() {
+            wait.sleep = Some(Box::pin(tokio::time::sleep(next_refill_delay())));
+            wait.started_at = Some(Instant::now());
+        }
+        wait.blocked_user |= blocked_user;
+        wait.blocked_cidr |= blocked_cidr;
+    }
+
+    fn poll_wait(
+        wait: &mut RateWaitState,
+        cx: &mut Context<'_>,
+        lease: Option<&Arc<TrafficLease>>,
+        direction: RateDirection,
+    ) -> Poll<()> {
+        let Some(sleep) = wait.sleep.as_mut() else {
+            return Poll::Ready(());
+        };
+        if sleep.as_mut().poll(cx).is_pending() {
+            return Poll::Pending;
+        }
+        wait.sleep = None;
+        Self::record_wait(wait, lease, direction);
+        Poll::Ready(())
+    }
+
+    fn settle_c2s_rate_debt(&mut self, cx: &mut Context<'_>) -> Poll<()> {
+        let Some(lease) = self.traffic_lease.as_ref() else {
+            self.c2s_rate_debt_bytes = 0;
+            return Poll::Ready(());
+        };
+
+        while self.c2s_rate_debt_bytes > 0 {
+            let consume = lease.try_consume(RateDirection::Up, self.c2s_rate_debt_bytes);
+            if consume.granted > 0 {
+                self.c2s_rate_debt_bytes = self.c2s_rate_debt_bytes.saturating_sub(consume.granted);
+                continue;
+            }
+            Self::arm_wait(
+                &mut self.c2s_wait,
+                consume.blocked_user,
+                consume.blocked_cidr,
+            );
+            if Self::poll_wait(&mut self.c2s_wait, cx, Some(lease), RateDirection::Up).is_pending()
+            {
+                return Poll::Pending;
+            }
+        }
+
+        if Self::poll_wait(&mut self.c2s_wait, cx, Some(lease), RateDirection::Up).is_pending() {
+            return Poll::Pending;
+        }
+
+        Poll::Ready(())
+    }
+
+    fn arm_quota_wait(&mut self, cx: &mut Context<'_>) -> Poll<()> {
+        Self::arm_wait(&mut self.quota_wait, false, false);
+        Self::poll_wait(&mut self.quota_wait, cx, None, RateDirection::Up)
+    }
 }
 
 #[derive(Debug)]
@@ -270,6 +389,8 @@ const QUOTA_NEAR_LIMIT_BYTES: u64 = 64 * 1024;
 const QUOTA_LARGE_CHARGE_BYTES: u64 = 16 * 1024;
 const QUOTA_ADAPTIVE_INTERVAL_MIN_BYTES: u64 = 4 * 1024;
 const QUOTA_ADAPTIVE_INTERVAL_MAX_BYTES: u64 = 64 * 1024;
+const QUOTA_RESERVE_SPIN_RETRIES: usize = 64;
+const QUOTA_RESERVE_MAX_ROUNDS: usize = 8;
 
 #[inline]
 fn quota_adaptive_interval_bytes(remaining_before: u64) -> u64 {
@@ -284,6 +405,25 @@ fn should_immediate_quota_check(remaining_before: u64, charge_bytes: u64) -> boo
     remaining_before <= QUOTA_NEAR_LIMIT_BYTES || charge_bytes >= QUOTA_LARGE_CHARGE_BYTES
 }
 
+fn refund_reserved_quota_bytes(user_stats: &UserStats, reserved_bytes: u64) {
+    if reserved_bytes == 0 {
+        return;
+    }
+    let mut current = user_stats.quota_used.load(Ordering::Relaxed);
+    loop {
+        let next = current.saturating_sub(reserved_bytes);
+        match user_stats.quota_used.compare_exchange_weak(
+            current,
+            next,
+            Ordering::Relaxed,
+            Ordering::Relaxed,
+        ) {
+            Ok(_) => return,
+            Err(observed) => current = observed,
+        }
+    }
+}
+
 impl<S: AsyncRead + Unpin> AsyncRead for StatsIo<S> {
     fn poll_read(
         self: Pin<&mut Self>,
@@ -294,8 +434,16 @@ impl<S: AsyncRead + Unpin> AsyncRead for StatsIo<S> {
         if this.quota_exceeded.load(Ordering::Acquire) {
             return Poll::Ready(Err(quota_io_error()));
         }
+        if this.settle_c2s_rate_debt(cx).is_pending() {
+            return Poll::Pending;
+        }
+        if buf.remaining() == 0 {
+            return Pin::new(&mut this.inner).poll_read(cx, buf);
+        }
 
         let mut remaining_before = None;
+        let mut reserved_read_bytes = 0u64;
+        let mut read_limit = buf.remaining();
         if let Some(limit) = this.quota_limit {
             let used_before = this.user_stats.quota_used();
             let remaining = limit.saturating_sub(used_before);
@@ -304,16 +452,96 @@ impl<S: AsyncRead + Unpin> AsyncRead for StatsIo<S> {
                 return Poll::Ready(Err(quota_io_error()));
             }
             remaining_before = Some(remaining);
+            read_limit = read_limit.min(remaining as usize);
+            if read_limit == 0 {
+                this.quota_exceeded.store(true, Ordering::Release);
+                return Poll::Ready(Err(quota_io_error()));
+            }
+
+            let desired = read_limit as u64;
+            let mut reserve_rounds = 0usize;
+            while reserved_read_bytes == 0 {
+                for _ in 0..QUOTA_RESERVE_SPIN_RETRIES {
+                    match this.user_stats.quota_try_reserve(desired, limit) {
+                        Ok(_) => {
+                            reserved_read_bytes = desired;
+                            break;
+                        }
+                        Err(crate::stats::QuotaReserveError::LimitExceeded) => {
+                            this.quota_exceeded.store(true, Ordering::Release);
+                            return Poll::Ready(Err(quota_io_error()));
+                        }
+                        Err(crate::stats::QuotaReserveError::Contended) => {
+                            this.stats.increment_quota_contention_total();
+                        }
+                    }
+                }
+
+                if reserved_read_bytes == 0 {
+                    reserve_rounds = reserve_rounds.saturating_add(1);
+                    if reserve_rounds >= QUOTA_RESERVE_MAX_ROUNDS {
+                        this.stats.increment_quota_contention_timeout_total();
+                        if this.arm_quota_wait(cx).is_pending() {
+                            return Poll::Pending;
+                        }
+                        reserve_rounds = 0;
+                    }
+                }
+            }
         }
 
-        let before = buf.filled().len();
+        let limited_read = read_limit < buf.remaining();
+        let read_result = if limited_read {
+            let mut limited_buf = ReadBuf::new(buf.initialize_unfilled_to(read_limit));
+            match Pin::new(&mut this.inner).poll_read(cx, &mut limited_buf) {
+                Poll::Ready(Ok(())) => {
+                    let n = limited_buf.filled().len();
+                    buf.advance(n);
+                    Poll::Ready(Ok(n))
+                }
+                Poll::Ready(Err(err)) => Poll::Ready(Err(err)),
+                Poll::Pending => Poll::Pending,
+            }
+        } else {
+            let before = buf.filled().len();
+            match Pin::new(&mut this.inner).poll_read(cx, buf) {
+                Poll::Ready(Ok(())) => {
+                    let n = buf.filled().len() - before;
+                    Poll::Ready(Ok(n))
+                }
+                Poll::Ready(Err(err)) => Poll::Ready(Err(err)),
+                Poll::Pending => Poll::Pending,
+            }
+        };
 
-        match Pin::new(&mut this.inner).poll_read(cx, buf) {
-            Poll::Ready(Ok(())) => {
-                let n = buf.filled().len() - before;
+        match read_result {
+            Poll::Ready(Ok(n)) => {
+                if reserved_read_bytes > n as u64 {
+                    let refund_bytes = reserved_read_bytes - n as u64;
+                    refund_reserved_quota_bytes(this.user_stats.as_ref(), refund_bytes);
+                    this.stats.add_quota_refund_bytes_total(refund_bytes);
+                }
                 if n > 0 {
                     let n_to_charge = n as u64;
 
+                    if let Some(remaining) = remaining_before {
+                        if should_immediate_quota_check(remaining, n_to_charge) {
+                            this.quota_bytes_since_check = 0;
+                        } else {
+                            this.quota_bytes_since_check =
+                                this.quota_bytes_since_check.saturating_add(n_to_charge);
+                            let interval = quota_adaptive_interval_bytes(remaining);
+                            if this.quota_bytes_since_check >= interval {
+                                this.quota_bytes_since_check = 0;
+                            }
+                        }
+                    }
+                    if let Some(limit) = this.quota_limit
+                        && this.user_stats.quota_used() >= limit
+                    {
+                        this.quota_exceeded.store(true, Ordering::Release);
+                    }
+
                     // C→S: client sent data
                     this.counters
                         .c2s_bytes
@@ -325,33 +553,30 @@ impl<S: AsyncRead + Unpin> AsyncRead for StatsIo<S> {
                         .add_user_octets_from_handle(this.user_stats.as_ref(), n_to_charge);
                     this.stats
                         .increment_user_msgs_from_handle(this.user_stats.as_ref());
-
-                    if let (Some(limit), Some(remaining)) = (this.quota_limit, remaining_before) {
-                        this.stats
-                            .quota_charge_post_write(this.user_stats.as_ref(), n_to_charge);
-                        if should_immediate_quota_check(remaining, n_to_charge) {
-                            this.quota_bytes_since_check = 0;
-                            if this.user_stats.quota_used() >= limit {
-                                this.quota_exceeded.store(true, Ordering::Release);
-                            }
-                        } else {
-                            this.quota_bytes_since_check =
-                                this.quota_bytes_since_check.saturating_add(n_to_charge);
-                            let interval = quota_adaptive_interval_bytes(remaining);
-                            if this.quota_bytes_since_check >= interval {
-                                this.quota_bytes_since_check = 0;
-                                if this.user_stats.quota_used() >= limit {
-                                    this.quota_exceeded.store(true, Ordering::Release);
-                                }
-                            }
-                        }
+                    if this.traffic_lease.is_some() {
+                        this.c2s_rate_debt_bytes =
+                            this.c2s_rate_debt_bytes.saturating_add(n_to_charge);
+                        let _ = this.settle_c2s_rate_debt(cx);
                     }
 
                     trace!(user = %this.user, bytes = n, "C->S");
                 }
                 Poll::Ready(Ok(()))
             }
-            other => other,
+            Poll::Pending => {
+                if reserved_read_bytes > 0 {
+                    refund_reserved_quota_bytes(this.user_stats.as_ref(), reserved_read_bytes);
+                    this.stats.add_quota_refund_bytes_total(reserved_read_bytes);
+                }
+                Poll::Pending
+            }
+            Poll::Ready(Err(err)) => {
+                if reserved_read_bytes > 0 {
+                    refund_reserved_quota_bytes(this.user_stats.as_ref(), reserved_read_bytes);
+                    this.stats.add_quota_refund_bytes_total(reserved_read_bytes);
+                }
+                Poll::Ready(Err(err))
+            }
         }
     }
 }
@@ -367,20 +592,122 @@ impl<S: AsyncWrite + Unpin> AsyncWrite for StatsIo<S> {
             return Poll::Ready(Err(quota_io_error()));
         }
 
-        let mut remaining_before = None;
-        if let Some(limit) = this.quota_limit {
-            let used_before = this.user_stats.quota_used();
-            let remaining = limit.saturating_sub(used_before);
-            if remaining == 0 {
-                this.quota_exceeded.store(true, Ordering::Release);
-                return Poll::Ready(Err(quota_io_error()));
+        let mut shaper_reserved_bytes = 0u64;
+        let mut write_buf = buf;
+        if let Some(lease) = this.traffic_lease.as_ref() {
+            if !buf.is_empty() {
+                loop {
+                    let consume = lease.try_consume(RateDirection::Down, buf.len() as u64);
+                    if consume.granted > 0 {
+                        shaper_reserved_bytes = consume.granted;
+                        if consume.granted < buf.len() as u64 {
+                            write_buf = &buf[..consume.granted as usize];
+                        }
+                        let _ = Self::poll_wait(
+                            &mut this.s2c_wait,
+                            cx,
+                            Some(lease),
+                            RateDirection::Down,
+                        );
+                        break;
+                    }
+
+                    Self::arm_wait(
+                        &mut this.s2c_wait,
+                        consume.blocked_user,
+                        consume.blocked_cidr,
+                    );
+                    if Self::poll_wait(&mut this.s2c_wait, cx, Some(lease), RateDirection::Down)
+                        .is_pending()
+                    {
+                        return Poll::Pending;
+                    }
+                }
+            } else {
+                let _ = Self::poll_wait(&mut this.s2c_wait, cx, Some(lease), RateDirection::Down);
             }
-            remaining_before = Some(remaining);
         }
 
-        match Pin::new(&mut this.inner).poll_write(cx, buf) {
+        let mut remaining_before = None;
+        let mut reserved_bytes = 0u64;
+        if let Some(limit) = this.quota_limit {
+            if !write_buf.is_empty() {
+                let mut reserve_rounds = 0usize;
+                while reserved_bytes == 0 {
+                    let used_before = this.user_stats.quota_used();
+                    let remaining = limit.saturating_sub(used_before);
+                    if remaining == 0 {
+                        if let Some(lease) = this.traffic_lease.as_ref() {
+                            lease.refund(RateDirection::Down, shaper_reserved_bytes);
+                        }
+                        this.quota_exceeded.store(true, Ordering::Release);
+                        return Poll::Ready(Err(quota_io_error()));
+                    }
+                    remaining_before = Some(remaining);
+
+                    let desired = remaining.min(write_buf.len() as u64);
+                    let mut saw_contention = false;
+                    for _ in 0..QUOTA_RESERVE_SPIN_RETRIES {
+                        match this.user_stats.quota_try_reserve(desired, limit) {
+                            Ok(_) => {
+                                reserved_bytes = desired;
+                                write_buf = &write_buf[..desired as usize];
+                                break;
+                            }
+                            Err(crate::stats::QuotaReserveError::LimitExceeded) => {
+                                break;
+                            }
+                            Err(crate::stats::QuotaReserveError::Contended) => {
+                                this.stats.increment_quota_contention_total();
+                                saw_contention = true;
+                            }
+                        }
+                    }
+
+                    if reserved_bytes == 0 {
+                        reserve_rounds = reserve_rounds.saturating_add(1);
+                        if reserve_rounds >= QUOTA_RESERVE_MAX_ROUNDS {
+                            this.stats.increment_quota_contention_timeout_total();
+                            if let Some(lease) = this.traffic_lease.as_ref() {
+                                lease.refund(RateDirection::Down, shaper_reserved_bytes);
+                            }
+                            let _ = this.arm_quota_wait(cx);
+                            return Poll::Pending;
+                        } else if saw_contention {
+                            std::hint::spin_loop();
+                        }
+                    }
+                }
+            } else {
+                let used_before = this.user_stats.quota_used();
+                let remaining = limit.saturating_sub(used_before);
+                if remaining == 0 {
+                    if let Some(lease) = this.traffic_lease.as_ref() {
+                        lease.refund(RateDirection::Down, shaper_reserved_bytes);
+                    }
+                    this.quota_exceeded.store(true, Ordering::Release);
+                    return Poll::Ready(Err(quota_io_error()));
+                }
+                remaining_before = Some(remaining);
+            }
+        }
+
+        match Pin::new(&mut this.inner).poll_write(cx, write_buf) {
             Poll::Ready(Ok(n)) => {
+                if reserved_bytes > n as u64 {
+                    let refund_bytes = reserved_bytes - n as u64;
+                    refund_reserved_quota_bytes(this.user_stats.as_ref(), refund_bytes);
+                    this.stats.add_quota_refund_bytes_total(refund_bytes);
+                }
+                if shaper_reserved_bytes > n as u64
+                    && let Some(lease) = this.traffic_lease.as_ref()
+                {
+                    lease.refund(RateDirection::Down, shaper_reserved_bytes - n as u64);
+                }
                 if n > 0 {
+                    if let Some(lease) = this.traffic_lease.as_ref() {
+                        Self::record_wait(&mut this.s2c_wait, Some(lease), RateDirection::Down);
+                    }
                     let n_to_charge = n as u64;
 
                     // S→C: data written to client
@@ -396,8 +723,6 @@ impl<S: AsyncWrite + Unpin> AsyncWrite for StatsIo<S> {
                         .increment_user_msgs_to_handle(this.user_stats.as_ref());
 
                     if let (Some(limit), Some(remaining)) = (this.quota_limit, remaining_before) {
-                        this.stats
-                            .quota_charge_post_write(this.user_stats.as_ref(), n_to_charge);
                         if should_immediate_quota_check(remaining, n_to_charge) {
                             this.quota_bytes_since_check = 0;
                             if this.user_stats.quota_used() >= limit {
@@ -420,7 +745,30 @@ impl<S: AsyncWrite + Unpin> AsyncWrite for StatsIo<S> {
                 }
                 Poll::Ready(Ok(n))
             }
-            other => other,
+            Poll::Ready(Err(err)) => {
+                if reserved_bytes > 0 {
+                    refund_reserved_quota_bytes(this.user_stats.as_ref(), reserved_bytes);
+                    this.stats.add_quota_refund_bytes_total(reserved_bytes);
+                }
+                if shaper_reserved_bytes > 0
+                    && let Some(lease) = this.traffic_lease.as_ref()
+                {
+                    lease.refund(RateDirection::Down, shaper_reserved_bytes);
+                }
+                Poll::Ready(Err(err))
+            }
+            Poll::Pending => {
+                if reserved_bytes > 0 {
+                    refund_reserved_quota_bytes(this.user_stats.as_ref(), reserved_bytes);
+                    this.stats.add_quota_refund_bytes_total(reserved_bytes);
+                }
+                if shaper_reserved_bytes > 0
+                    && let Some(lease) = this.traffic_lease.as_ref()
+                {
+                    lease.refund(RateDirection::Down, shaper_reserved_bytes);
+                }
+                Poll::Pending
+            }
         }
     }
 
@@ -502,6 +850,43 @@ pub async fn relay_bidirectional_with_activity_timeout<CR, CW, SR, SW>(
     _buffer_pool: Arc<BufferPool>,
     activity_timeout: Duration,
 ) -> Result<()>
+where
+    CR: AsyncRead + Unpin + Send + 'static,
+    CW: AsyncWrite + Unpin + Send + 'static,
+    SR: AsyncRead + Unpin + Send + 'static,
+    SW: AsyncWrite + Unpin + Send + 'static,
+{
+    relay_bidirectional_with_activity_timeout_and_lease(
+        client_reader,
+        client_writer,
+        server_reader,
+        server_writer,
+        c2s_buf_size,
+        s2c_buf_size,
+        user,
+        stats,
+        quota_limit,
+        _buffer_pool,
+        None,
+        activity_timeout,
+    )
+    .await
+}
+
+pub async fn relay_bidirectional_with_activity_timeout_and_lease<CR, CW, SR, SW>(
+    client_reader: CR,
+    client_writer: CW,
+    server_reader: SR,
+    server_writer: SW,
+    c2s_buf_size: usize,
+    s2c_buf_size: usize,
+    user: &str,
+    stats: Arc<Stats>,
+    quota_limit: Option<u64>,
+    _buffer_pool: Arc<BufferPool>,
+    traffic_lease: Option<Arc<TrafficLease>>,
+    activity_timeout: Duration,
+) -> Result<()>
 where
     CR: AsyncRead + Unpin + Send + 'static,
     CW: AsyncWrite + Unpin + Send + 'static,
@@ -519,11 +904,12 @@ where
     let mut server = CombinedStream::new(server_reader, server_writer);
 
     // Wrap client with stats/activity tracking
-    let mut client = StatsIo::new(
+    let mut client = StatsIo::new_with_traffic_lease(
         client_combined,
         Arc::clone(&counters),
         Arc::clone(&stats),
         user_owned.clone(),
+        traffic_lease,
         quota_limit,
         Arc::clone(&quota_exceeded),
         epoch,

src/proxy/route_mode.rs

@@ -4,8 +4,6 @@ use std::time::{Duration, SystemTime, UNIX_EPOCH};
 
 use tokio::sync::watch;
 
-pub(crate) const ROUTE_SWITCH_ERROR_MSG: &str = "Session terminated";
-
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 #[repr(u8)]
 pub(crate) enum RelayRouteMode {

src/proxy/shared_state.rs

@@ -1,15 +1,18 @@
 use std::collections::HashSet;
 use std::collections::hash_map::RandomState;
 use std::net::{IpAddr, SocketAddr};
-use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::atomic::{AtomicBool, AtomicU32, AtomicU64, Ordering};
 use std::sync::{Arc, Mutex};
 use std::time::Instant;
 
 use dashmap::DashMap;
 use tokio::sync::mpsc;
 
-use crate::proxy::handshake::{AuthProbeState, AuthProbeSaturationState};
+use crate::proxy::handshake::{AuthProbeSaturationState, AuthProbeState};
 use crate::proxy::middle_relay::{DesyncDedupRotationState, RelayIdleCandidateRegistry};
+use crate::proxy::traffic_limiter::TrafficLimiter;
+
+const HANDSHAKE_RECENT_USER_RING_LEN: usize = 64;
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub(crate) enum ConntrackCloseReason {
@@ -41,6 +44,13 @@ pub(crate) struct HandshakeSharedState {
     pub(crate) auth_probe_eviction_hasher: RandomState,
     pub(crate) invalid_secret_warned: Mutex<HashSet<(String, String)>>,
     pub(crate) unknown_sni_warn_next_allowed: Mutex<Option<Instant>>,
+    pub(crate) sticky_user_by_ip: DashMap<IpAddr, u32>,
+    pub(crate) sticky_user_by_ip_prefix: DashMap<u64, u32>,
+    pub(crate) sticky_user_by_sni_hash: DashMap<u64, u32>,
+    pub(crate) recent_user_ring: Box<[AtomicU32]>,
+    pub(crate) recent_user_ring_seq: AtomicU64,
+    pub(crate) auth_expensive_checks_total: AtomicU64,
+    pub(crate) auth_budget_exhausted_total: AtomicU64,
 }
 
 pub(crate) struct MiddleRelaySharedState {
@@ -56,6 +66,7 @@ pub(crate) struct MiddleRelaySharedState {
 pub(crate) struct ProxySharedState {
     pub(crate) handshake: HandshakeSharedState,
     pub(crate) middle_relay: MiddleRelaySharedState,
+    pub(crate) traffic_limiter: Arc<TrafficLimiter>,
     pub(crate) conntrack_pressure_active: AtomicBool,
     pub(crate) conntrack_close_tx: Mutex<Option<mpsc::Sender<ConntrackCloseEvent>>>,
 }
@@ -69,6 +80,16 @@ impl ProxySharedState {
                 auth_probe_eviction_hasher: RandomState::new(),
                 invalid_secret_warned: Mutex::new(HashSet::new()),
                 unknown_sni_warn_next_allowed: Mutex::new(None),
+                sticky_user_by_ip: DashMap::new(),
+                sticky_user_by_ip_prefix: DashMap::new(),
+                sticky_user_by_sni_hash: DashMap::new(),
+                recent_user_ring: std::iter::repeat_with(|| AtomicU32::new(0))
+                    .take(HANDSHAKE_RECENT_USER_RING_LEN)
+                    .collect::<Vec<_>>()
+                    .into_boxed_slice(),
+                recent_user_ring_seq: AtomicU64::new(0),
+                auth_expensive_checks_total: AtomicU64::new(0),
+                auth_budget_exhausted_total: AtomicU64::new(0),
             },
             middle_relay: MiddleRelaySharedState {
                 desync_dedup: DashMap::new(),
@@ -79,6 +100,7 @@ impl ProxySharedState {
                 relay_idle_registry: Mutex::new(RelayIdleCandidateRegistry::default()),
                 relay_idle_mark_seq: AtomicU64::new(0),
             },
+            traffic_limiter: TrafficLimiter::new(),
             conntrack_pressure_active: AtomicBool::new(false),
             conntrack_close_tx: Mutex::new(None),
         })
@@ -136,7 +158,8 @@ impl ProxySharedState {
     }
 
     pub(crate) fn set_conntrack_pressure_active(&self, active: bool) {
-        self.conntrack_pressure_active.store(active, Ordering::Relaxed);
+        self.conntrack_pressure_active
+            .store(active, Ordering::Relaxed);
     }
 
     pub(crate) fn conntrack_pressure_active(&self) -> bool {

src/proxy/tests/adaptive_buffers_record_race_security_tests.rs

@@ -1,6 +1,6 @@
 use super::*;
-use std::sync::atomic::{AtomicUsize, Ordering};
 use std::sync::Arc;
+use std::sync::atomic::{AtomicUsize, Ordering};
 use std::time::{Duration, Instant};
 
 static RACE_TEST_KEY_COUNTER: AtomicUsize = AtomicUsize::new(1_000_000);

src/proxy/tests/adaptive_buffers_security_tests.rs

@@ -65,9 +65,15 @@ fn adaptive_base_tier_buffers_unchanged() {
 fn adaptive_tier1_buffers_within_caps() {
     let (c2s, s2c) = direct_copy_buffers_for_tier(AdaptiveTier::Tier1, 65536, 262144);
     assert!(c2s > 65536, "Tier1 c2s should exceed Base");
-    assert!(c2s <= 128 * 1024, "Tier1 c2s should not exceed DIRECT_C2S_CAP_BYTES");
+    assert!(
+        c2s <= 128 * 1024,
+        "Tier1 c2s should not exceed DIRECT_C2S_CAP_BYTES"
+    );
     assert!(s2c > 262144, "Tier1 s2c should exceed Base");
-    assert!(s2c <= 512 * 1024, "Tier1 s2c should not exceed DIRECT_S2C_CAP_BYTES");
+    assert!(
+        s2c <= 512 * 1024,
+        "Tier1 s2c should not exceed DIRECT_S2C_CAP_BYTES"
+    );
 }
 
 #[test]

src/proxy/tests/client_masking_blackhat_campaign_tests.rs

@@ -31,11 +31,14 @@ fn new_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
             upstream_type: UpstreamType::Direct {
                 interface: None,
                 bind_addresses: None,
+                bindtodevice: None,
             },
             weight: 1,
             enabled: true,
             scopes: String::new(),
             selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
         }],
         1,
         1,

src/proxy/tests/client_masking_budget_security_tests.rs

@@ -27,11 +27,14 @@ fn build_harness(config: ProxyConfig) -> PipelineHarness {
             upstream_type: UpstreamType::Direct {
                 interface: None,
                 bind_addresses: None,
+                bindtodevice: None,
             },
             weight: 1,
             enabled: true,
             scopes: String::new(),
             selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
         }],
         1,
         1,