astelm/telemt
1
0
Fork 0
mirror of https://github.com/telemt/telemt.git synced 2026-10-06 09:25:59 +03:00
Code Issues Packages Projects Releases Wiki Activity

Docs 3.5.8 Pull-Up

Browse Source 
Co-Authored-By: brekotis <93345790+brekotis@users.noreply.github.com>
This commit is contained in:
Alexey
2026-09-27 18:55:04 +03:00
parent 717a34771f
commit 56e0f000ba
18 changed files with 1137 additions and 458 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/Config_params/CONFIG_PARAMS.de.md
+115 -55
View File
@@ -10,10 +10,10 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
>
> Die in diesem Dokument beschriebenen Konfigurationsparameter richten sich an erfahrene Nutzer und dienen dem Feintuning. Änderungen ohne klares Verständnis der jeweiligen Funktion können zu Instabilität oder anderem unerwarteten Verhalten führen. Gehen Sie entsprechend vorsichtig und auf eigenes Risiko vor.
> `Hot-Reload` zeigt an, ob ein geänderter Wert vom Config-Watcher ohne Prozessneustart übernommen wird; `✘` bedeutet, dass für den Runtime-Effekt ein Neustart erforderlich ist.
> `Hot-Reload` zeigt an, ob der Config-Watcher einen geänderten Wert direkt übernimmt. `✘` bedeutet, dass der Watcher ihn nicht anwendet; je nach Feld ist für die vollständige Wirkung ein prozessinterner Runtime-Generation-Reload oder ein Prozessneustart erforderlich.
# Inhaltsverzeichnis
- [Schlüssel auf oberster Ebene](#top-level-keys)
- [Schlüssel auf oberster Ebene](#schlüssel-auf-oberster-ebene)
- [logging](#logging)
- [general](#general)
- [general.modes](#generalmodes)
@@ -65,10 +65,10 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
- **Beispiel**:
```toml
# Links für alle konfigurierten User anzeigen
# Show links for all configured users
show_link = "*"
# oder: Links nur für ausgewählte User anzeigen
# Or show links only for selected users
# show_link = ["alice", "bob"]
```
## dc_overrides
@@ -87,8 +87,8 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
- **Beispiel**:
```toml
# Wenn ein Client ein unbekanntes/nicht standardisiertes DC ohne Override anfordert,
# wird er an diesen Default-Cluster weitergeleitet (1..=5).
# When a client requests an unknown or non-standard DC without an override,
# route it to this default cluster (1..=5).
default_dc = 2
```
@@ -204,6 +204,7 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
| [`me_keepalive_payload_random`](#me_keepalive_payload_random) | `bool` | `true` | `✘` |
| [`rpc_proxy_req_every`](#rpc_proxy_req_every) | `u64` | `0` | `✘` |
| [`me_writer_cmd_channel_capacity`](#me_writer_cmd_channel_capacity) | `usize` | `4096` | `✘` |
| [`me_writer_byte_budget_bytes`](#me_writer_byte_budget_bytes) | `usize` | `33570816` | `✘` |
| [`me_route_channel_capacity`](#me_route_channel_capacity) | `usize` | `768` | `✘` |
| [`me_c2me_channel_capacity`](#me_c2me_channel_capacity) | `usize` | `1024` | `✘` |
| [`me_c2me_send_timeout_ms`](#me_c2me_send_timeout_ms) | `u64` | `4000` | `✘` |
@@ -216,6 +217,7 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
| [`me_d2c_frame_buf_shrink_threshold_bytes`](#me_d2c_frame_buf_shrink_threshold_bytes) | `usize` | `262144` | `✔` |
| [`direct_relay_copy_buf_c2s_bytes`](#direct_relay_copy_buf_c2s_bytes) | `usize` | `65536` | `✔` |
| [`direct_relay_copy_buf_s2c_bytes`](#direct_relay_copy_buf_s2c_bytes) | `usize` | `262144` | `✔` |
| [`direct_relay_buffer_budget_max_bytes`](#direct_relay_buffer_budget_max_bytes) | `usize` | `0` | `✘` |
| [`crypto_pending_buffer`](#crypto_pending_buffer) | `usize` | `262144` | `✘` |
| [`max_client_frame`](#max_client_frame) | `usize` | `16777216` | `✘` |
| [`desync_all_full`](#desync_all_full) | `bool` | `false` | `✔` |
@@ -301,13 +303,14 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
| [`me_pool_drain_soft_evict_per_writer`](#me_pool_drain_soft_evict_per_writer) | `u8` | `2` | `✘` |
| [`me_pool_drain_soft_evict_budget_per_core`](#me_pool_drain_soft_evict_budget_per_core) | `u16` | `16` | `✘` |
| [`me_pool_drain_soft_evict_cooldown_ms`](#me_pool_drain_soft_evict_cooldown_ms) | `u64` | `1000` | `✘` |
| [`me_bind_stale_mode`](#me_bind_stale_mode) | `"never"`, `"ttl"` oder `"always"` | `"ttl"` | `✔` |
| [`me_bind_stale_mode`](#me_bind_stale_mode) | `"never"`, `"ttl"` oder `"always"` | `"never"` | `✔` |
| [`me_bind_stale_ttl_secs`](#me_bind_stale_ttl_secs) | `u64` | `90` | `✔` |
| [`me_pool_min_fresh_ratio`](#me_pool_min_fresh_ratio) | `f32` | `0.8` | `✔` |
| [`me_reinit_drain_timeout_secs`](#me_reinit_drain_timeout_secs) | `u64` | `90` | `✔` |
| [`proxy_secret_auto_reload_secs`](#proxy_secret_auto_reload_secs) | `u64` | `3600` | `✔` |
| [`proxy_config_auto_reload_secs`](#proxy_config_auto_reload_secs) | `u64` | `3600` | `✔` |
| [`me_reinit_singleflight`](#me_reinit_singleflight) | `bool` | `true` | `✔` |
| [`me_reinit_max_concurrency`](#me_reinit_max_concurrency) | `usize` | `2` | `✔` |
| [`me_reinit_trigger_channel`](#me_reinit_trigger_channel) | `usize` | `64` | `✘` |
| [`me_reinit_coalesce_window_ms`](#me_reinit_coalesce_window_ms) | `u64` | `200` | `✔` |
| [`me_deterministic_writer_sort`](#me_deterministic_writer_sort) | `bool` | `true` | `✔` |
@@ -346,6 +349,8 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
[general]
config_strict = true
```
- **Bekannte Einschränkung**: In dieser Revision weist `config_strict = true` die ansonsten unterstützten Schlüssel `access.user_source_deny` und `[[upstreams]].prefer` zurück. Lassen Sie den Strict-Modus deaktiviert, wenn einer dieser Schlüssel verwendet wird.
## prefer_ipv6
- **Einschränkungen / Validierung**: Veraltet. Verwenden Sie `network.prefer`.
- **Beschreibung**: Veraltetes Legacy-Einstellungsflag IPv6 wurde nach `network.prefer` migriert.
@@ -482,8 +487,8 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
stun_nat_probe_concurrency = 8
```
## middle_proxy_pool_size
- **Einschränkungen / Validierung**: `usize`. Der effektive Wert ist `max(value, 1)` zur Runtime (daher verhält sich `0` wie `1`).
- **Beschreibung**: Zielgröße des aktiven ME Writer-Pools.
- **Einschränkungen / Validierung**: `usize`. Der an die ME-Initialisierung übergebene Wert wird als `max(value, 1)` normalisiert.
- **Beschreibung**: Nicht erzwingender Kompatibilitätswert, der derzeit im ME-Initialisierungslog ausgegeben wird. Aktive Writer-Ziele werden aus der DC-Family-Floor-Policy abgeleitet, nicht aus diesem Wert.
- **Beispiel**:
```toml
@@ -574,16 +579,25 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
rpc_proxy_req_every = 0
```
## me_writer_cmd_channel_capacity
- **Einschränkungen / Validierung**: Muss `> 0` sein.
- **Beschreibung**: Kapazität des Befehlskanals pro Autor.
- **Einschränkungen / Validierung**: Muss innerhalb von `1..=16384` liegen.
- **Beschreibung**: Kapazität des Befehlskanals pro ME-Writer.
- **Beispiel**:
```toml
[general]
me_writer_cmd_channel_capacity = 4096
```
## me_writer_byte_budget_bytes
- **Einschränkungen / Validierung**: Muss ein Vielfaches von `16384` zwischen dem dynamischen Minimum und `268435456` sein. Das Minimum ist `2 * general.max_client_frame + 256`, auf `16384` aufgerundet; bei der Standard-Framegröße beträgt es `33570816`.
- **Beschreibung**: Residenter Speicheretat für die Daten-Queue jedes ME-Writers. Der Datei-Watcher baut vorhandene Writer für dieses Feld nicht neu; es wird wirksam, wenn über die API eine neue ME-/Runtime-Generation erstellt wird oder nach einem Neustart.
- **Beispiel**:
```toml
[general]
me_writer_byte_budget_bytes = 33570816
```
## me_route_channel_capacity
- **Einschränkungen / Validierung**: Muss `> 0` sein.
- **Einschränkungen / Validierung**: Muss innerhalb von `1..=8192` liegen.
- **Beschreibung**: Kapazität des ME-Antwortroutenkanals pro Verbindung.
- **Beispiel**:
@@ -592,7 +606,7 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
me_route_channel_capacity = 768
```
## me_c2me_channel_capacity
- **Einschränkungen / Validierung**: Muss `> 0` sein.
- **Einschränkungen / Validierung**: Muss innerhalb von `1..=8192` liegen.
- **Beschreibung**: Kapazität der Befehlswarteschlange pro Client (Client-Leser -> ME Absender).
- **Beispiel**:
@@ -690,6 +704,15 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
[general]
direct_relay_copy_buf_s2c_bytes = 262144
```
## direct_relay_buffer_budget_max_bytes
- **Einschränkungen / Validierung**: `0` oder ein Vielfaches von `4096` innerhalb von `16777216..=2147483648`.
- **Beschreibung**: Prozesseigene harte Obergrenze für Direct-Relay-Copy-Buffer; `0` leitet sie beim Prozessstart aus den cgroup-/Host-Speichergrenzen ab. Die Änderung wird bis zum Neustart zurückgestellt.
- **Beispiel**:
```toml
[general]
direct_relay_buffer_budget_max_bytes = 0
```
## crypto_pending_buffer
- **Einschränkungen / Validierung**: `usize` (Byte).
- **Beschreibung**: Maximaler Puffer für ausstehenden Chiffretext pro Client-Writer (Byte).
@@ -700,7 +723,7 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
crypto_pending_buffer = 262144
```
## max_client_frame
- **Einschränkungen / Validierung**: `usize` (Byte).
- **Einschränkungen / Validierung**: Muss innerhalb von `4096..=16777216` (Byte) liegen.
- **Beschreibung**: Maximal zulässige Client-Framegröße MTProto (Byte).
- **Beispiel**:
@@ -1213,7 +1236,7 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
me_route_hybrid_max_wait_ms = 3000
```
## me_route_blocking_send_timeout_ms
- **Einschränkungen / Validierung**: Muss innerhalb von `0..=5000` (Millisekunden) liegen. `0` behält das alte unbegrenzte Warteverhalten bei.
- **Einschränkungen / Validierung**: Muss innerhalb von `1..=5000` (Millisekunden) liegen.
- **Beschreibung**: Maximale Wartezeit für das Blockieren des Route-Channel-Sende-Fallbacks.
- **Beispiel**:
@@ -1291,7 +1314,7 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
```toml
[general]
# Standard: 3 (erlaubter Bereich: 0..=10)
# Default: 3 (allowed range: 0..=10)
me_hardswap_warmup_extra_passes = 3
```
## me_hardswap_warmup_pass_backoff_base_ms
@@ -1301,7 +1324,7 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
```toml
[general]
# Standard: 500
# Default: 500
me_hardswap_warmup_pass_backoff_base_ms = 500
```
## me_config_stable_snapshots
@@ -1311,7 +1334,7 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
```toml
[general]
# erfordern drei identische Snapshots, bevor ME Endpunktkartenaktualisierungen angewendet werden
# Require three identical snapshots before applying ME endpoint map updates
me_config_stable_snapshots = 3
```
## me_config_apply_cooldown_secs
@@ -1321,7 +1344,7 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
```toml
[general]
# erlaubt die sofortige Anwendung stabiler Snapshots (keine Abklingzeit)
# Allow applying stable snapshots immediately without a cooldown
me_config_apply_cooldown_secs = 0
```
## me_snapshot_require_http_2xx
@@ -1331,7 +1354,7 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
```toml
[general]
# ermöglicht das Anwenden von Snapshots, auch wenn der HTTP-Status nicht 2xx ist
# Allow applying snapshots even when the HTTP status is not 2xx
me_snapshot_require_http_2xx = false
```
## me_snapshot_reject_empty_map
@@ -1341,7 +1364,7 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
```toml
[general]
# Anwenden leerer Snapshots zulassen (mit Vorsicht verwenden)
# Allow applying empty snapshots with care
me_snapshot_reject_empty_map = false
```
## me_snapshot_min_proxy_for_lines
@@ -1351,7 +1374,7 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
```toml
[general]
# erfordern mindestens 10 Proxy_for-Zeilen, bevor ein Snapshot akzeptiert wird
# Require at least 10 proxy_for rows before accepting a snapshot
me_snapshot_min_proxy_for_lines = 10
```
## proxy_secret_stable_snapshots
@@ -1361,7 +1384,7 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
```toml
[general]
# erfordern zwei identische getProxySecret-Snapshots, bevor sie zur Runtime rotieren
# Require two identical getProxySecret snapshots before rotating at runtime
proxy_secret_stable_snapshots = 2
```
## proxy_secret_rotate_runtime
@@ -1371,7 +1394,7 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
```toml
[general]
# Deaktivieren Sie die Proxy-Secret-Rotation zur Runtime (Start verwendet weiterhin Proxy_secret_path/proxy_secret_len_max)
# Disable runtime proxy-secret rotation; startup still uses proxy_secret_path/proxy_secret_len_max
proxy_secret_rotate_runtime = false
```
## me_secret_atomic_snapshot
@@ -1381,7 +1404,7 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
```toml
[general]
# HINWEIS: Wenn use_middle_proxy=true, wird Telemt dies beim Laden automatisch aktivieren
# Telemt enables this automatically during load when use_middle_proxy=true
me_secret_atomic_snapshot = false
```
## proxy_secret_len_max
@@ -1391,17 +1414,17 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
```toml
[general]
# Standard: 256 (Byte)
# Default: 256 bytes
proxy_secret_len_max = 256
```
## me_pool_drain_ttl_secs
- **Einschränkungen / Validierung**: `u64` (Sekunden). `0` deaktiviert das Drain-TTL-Fenster (und unterdrückt Drain-TTL-Warnungen für nicht leere Draining-Writer).
- **Beschreibung**: Drain-TTL-Zeitfenster für stale ME-Writer nach Änderungen der Endpoint-Map. Während der TTL dürfen stale Writer nur als Fallback für neue Bindungen verwendet werden (abhängig von der Bindungsrichtlinie).
- **Beschreibung**: Altersschwelle für Warnungen bei langem Drain nach Endpoint-Map-Änderungen und Untergrenze bei der Normalisierung des Force-Close-Timeouts. Stale-Bind-Zulassung wird separat durch `me_bind_stale_mode` und `me_bind_stale_ttl_secs` gesteuert.
- **Beispiel**:
```toml
[general]
# Drain TTL deaktivieren (Draining Writer geben keine „Past Drain TTL“-Warnungen aus)
# Disable drain TTL warnings for writers that remain draining past the threshold
me_pool_drain_ttl_secs = 0
```
## me_instadrain
@@ -1476,17 +1499,17 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
```
## me_bind_stale_mode
- **Einschränkungen / Validierung**: `"never"`, `"ttl"` oder `"always"`.
- **Beschreibung**: Policy für neue Binds auf stale draining Writern.
- **Beschreibung**: Policy für neue Binds auf stale draining Writern in nicht abgedeckten DC-Family-Gruppen. Der Default `never` verlangt vollständige Gruppenabdeckung, bevor ein partieller Hardswap committen darf; `ttl` und `always` erlauben policy-begrenzten Fallback.
- **Beispiel**:
```toml
[general]
# veraltete Bindungen nur für ein begrenztes Zeitfenster zulassen
# Allow stale binds only for a limited time window
me_bind_stale_mode = "ttl"
```
## me_bind_stale_ttl_secs
- **Einschränkungen / Validierung**: `u64`.
- **Beschreibung**: TTL für stale Bind-Zulassung, wenn der stale mode `ttl` ist.
- **Beschreibung**: TTL für stale Bind-Zulassung im Modus `ttl`; `0` deaktiviert den TTL-Ablauf für zulässige draining Writer.
- **Beispiel**:
```toml
@@ -1496,22 +1519,22 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
```
## me_pool_min_fresh_ratio
- **Einschränkungen / Validierung**: Muss innerhalb von `[0.0, 1.0]` liegen.
- **Beschreibung**: Mindestanteil frischer Desired-DC-Coverage, bevor stale Writer gedraint werden.
- **Beschreibung**: Mindestanteil frischer DC-Family-Coverage beim Generation-Commit. Fehlende Gruppen blockieren den Commit unter `me_bind_stale_mode = "never"` auch dann, wenn dieses Verhältnis erreicht ist.
- **Beispiel**:
```toml
[general]
# erfordern >=90 % der gewünschten DC-Abdeckung, bevor stale Writer gedraint werden
# Require at least 90% desired-DC coverage before draining stale writers
me_pool_min_fresh_ratio = 0.9
```
## me_reinit_drain_timeout_secs
- **Einschränkungen / Validierung**: `u64`. `0` verwendet das Runtime-Sicherheits-Fallback-Timeout für erzwungenes Schließen. Wenn `> 0` und `< me_pool_drain_ttl_secs`, erhöht die Runtime den Wert auf TTL.
- **Beschreibung**: Force-Close-Timeout für draining stale Writer. Bei der Einstellung `0` entspricht das effektive Timeout dem Runtime-Safety-Fallback (300 Sekunden).
- **Einschränkungen / Validierung**: `u64`. `0` wählt zuerst den 300-Sekunden-Runtime-Sicherheitsfallback; anschließend wird das effektive Timeout mindestens auf `me_pool_drain_ttl_secs` angehoben.
- **Beschreibung**: Force-Close-Timeout für draining stale Writer. Der effektive Wert ist das Maximum aus dem konfigurierten Wert ungleich Null (oder 300 Sekunden bei `0`) und der Drain-TTL.
- **Beispiel**:
```toml
[general]
# Runtime-Safety-Fallback-Force-Close-Timeout (300 s) verwenden
# Use the runtime safety fallback force-close timeout of 300 seconds
me_reinit_drain_timeout_secs = 0
```
## proxy_secret_auto_reload_secs
@@ -1521,10 +1544,10 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
```toml
[general]
# Legacy-Modus: update_every weglassen, um Proxy_*_auto_reload_secs zu verwenden
# Legacy mode: omit update_every to use proxy_*_auto_reload_secs
proxy_secret_auto_reload_secs = 600
proxy_config_auto_reload_secs = 120
# effektives Aktualisierungsintervall = min(600, 120) = 120 Sekunden
# Effective updater interval = min(600, 120) = 120 seconds
```
## proxy_config_auto_reload_secs
- **Einschränkungen / Validierung**: Veraltet. Verwenden Sie `general.update_every`. Wenn `general.update_every` nicht explizit festgelegt ist, beträgt das effektive Legacy-Aktualisierungsintervall `min(proxy_secret_auto_reload_secs, proxy_config_auto_reload_secs)` und muss `> 0` betragen.
@@ -1533,10 +1556,10 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
```toml
[general]
# Legacy-Modus: update_every weglassen, um Proxy_*_auto_reload_secs zu verwenden
# Legacy mode: omit update_every to use proxy_*_auto_reload_secs
proxy_secret_auto_reload_secs = 600
proxy_config_auto_reload_secs = 120
# effektives Aktualisierungsintervall = min(600, 120) = 120 Sekunden
# Effective updater interval = min(600, 120) = 120 seconds
```
## me_reinit_singleflight
- **Einschränkungen / Validierung**: `bool`.
@@ -1547,9 +1570,18 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
[general]
me_reinit_singleflight = true
```
## me_reinit_max_concurrency
- **Einschränkungen / Validierung**: Muss innerhalb von `[1, 8]` liegen. Der effektive Wert ist `1`, solange `me_reinit_singleflight = true` ist.
- **Beschreibung**: Begrenzt gleichzeitige Warmups von ME-Generationen; zusätzliche Trigger werden zu genau einem ausstehenden Wiederholungslauf zusammengeführt.
- **Beispiel**:
```toml
[general]
me_reinit_max_concurrency = 2
```
## me_reinit_trigger_channel
- **Einschränkungen / Validierung**: Muss `> 0` sein.
- **Beschreibung**: Trigger-Queue-Kapazität für Reinit-Planer.
- **Einschränkungen / Validierung**: Muss innerhalb von `[1, 4096]` liegen.
- **Beschreibung**: Trigger-Queue-Kapazität für den Reinit-Planer. Eine neue Runtime-Generation erstellt ihren Kanal aus diesem Wert; der Datei-Watcher allein ändert die Größe des aktiven Kanals nicht.
- **Beispiel**:
```toml
@@ -1699,7 +1731,7 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
```toml
[general.links]
show = "*"
# oder:
# Or:
# show = ["alice", "bob"]
```
## public_host
@@ -1792,10 +1824,10 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
```toml
[network]
# IPv6 explizit aktivieren
# Enable IPv6 explicitly
ipv6 = true
# oder: IPv6 explizit deaktivieren
# Or disable IPv6 explicitly
# ipv6 = false
```
## prefer
@@ -1972,7 +2004,7 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
```toml
[server]
# Erzwingen Sie die Aktivierung von TCP, auch wenn auch ein Unix-Socket gebunden wird
# Force-enable TCP even when also binding a Unix socket
listen_unix_sock = "/run/telemt.sock"
listen_tcp = true
```
@@ -2561,6 +2593,8 @@ Der WEB-Modus transportiert MTProxy-Datenverkehr von Telegram Desktop über HTTP
| `carriers` | `false` oder ein nicht leeres Array eindeutiger Carrier | `false` | `✔` |
| `carrier_learning` | `bool` | `true` | `✔` |
| `carrier_negotiation_aggressiveness` | `"conservative"`, `"balanced"` oder `"aggressive"` | `"conservative"` | `✔` |
| `decoy_fasttrack_mode` | `"off"`, `"shadow"` oder `"enforce"` | `"off"` | `✘` |
| `http_connection_capacity_action` | `"drop"`, `"wait"` oder `"respond"` | `"drop"` | `✔` |
| `debug` | Tabelle | deaktiviert, begrenzte Defaults | `✔` |
| `limits` | Tabelle | begrenzte Defaults | `✘` |
| `timeouts` | Tabelle | begrenzte Defaults | `✔` |
@@ -2570,6 +2604,10 @@ Der WEB-Modus transportiert MTProxy-Datenverkehr von Telegram Desktop über HTTP
Fehlt `carriers` oder ist es `false`, sind Auto-Negotiation und Lernen deaktiviert und `carrier` ist der einzige Modus. Ein nicht leeres `carriers`-Array aktiviert die Start-Negotiation in der konfigurierten Reihenfolge; `carrier` wird genau einmal als letzter Fallback angehängt. Leere Arrays, Duplikate und `true` werden abgelehnt. Der Client darf nur vor dem Carrier-Commit zum nächsten Kandidaten wechseln; nach dem Commit erfordert ein Carrier-Wechsel eine neue Sitzung. Ein nativer Client ohne Metadaten, einschließlich Telegram iOS, verwendet immer den konfigurierten festen `carrier`, auch bei aktivierter Negotiation. Das aktuelle iOS unterstützt nur `https`; solche Bereitstellungen müssen daher `carrier = "https"` setzen. Die CFNetwork- und Darwin-User-Agent-Klassifizierung leitet keine Carrier-Unterstützung ab. Explizite native iOS-Capabilities werden mit `{https}` geschnitten; andere explizite Client-Capabilities gelten wie gemeldet.
`http_connection_capacity_action` gilt erst, nachdem Telemt eine private WEB-TCP-Verbindung akzeptiert hat und `max_http_connections` ausgeschöpft ist. `drop` schließt wie bisher sofort. `respond` sendet eine leere wiederholbare `503 Service Unavailable` mit `Retry-After: 1`, `Cache-Control: no-store` und `Connection: close`. `wait` wartet höchstens `http_overload_timeout_ms` auf normale Kapazität und beginnt danach die übliche HTTP-Verarbeitung; bei Timeout wird dieselbe begrenzte `503` gesendet. Höchstens `max_http_overload_connections` akzeptierte Sockets dürfen außerhalb der normalen Kapazität warten oder antworten.
`decoy_fasttrack_mode` ist restart-only und betrifft nur Capability-Arbeit für `GET/HEAD` am konfigurierten Basis-Root. `off` behält den vollständigen Scan bei, `shadow` zählt geeignete Requests ohne den Scan zu überspringen, und `enforce` überspringt ihn nur für `HEAD` oder eine fehlende/nicht kanonische `bridge`-Query. Ein kanonisch geformtes Bridge-`GET` scannt immer alle Profile des ausgewählten vhost. Die Optimierung begrenzt keine feindlichen kanonischen Probes; `enforce` muss hinter dem produktiven TLS-Terminator auf Timing-Unterscheidbarkeit geprüft werden.
`carrier_learning` wirkt nur bei aktivierter Negotiation. Das Lernen ist prozesslokal, speicherresident, begrenzt und ausschließlich positiv: Nur ein Carrier, der den serverdefinierten Zustand healthy erreicht, liefert Evidenz. `conservative` erfordert die breiteste Evidenz und deaktiviert IP-Ranking, `balanced` verwendet mittlere User-Agent-/Profil-Schwellen sowie geeignete öffentliche IPs nur als Tie-Breaker, und `aggressive` reagiert auf die ersten begrenzten Samples. Vom Client gemeldete Fehler bleiben rein diagnostisch und erzeugen keine negative Evidenz. Ein Reload wendet die Richtlinie auf neue Negotiation-Ketten an und verwirft inkompatible gespeicherte Evidenz. Das Deaktivieren von WEB beendet die Ausgabe neuer Bridge- und Session-Zugangsdaten; zum Widerrufen aktiver Sitzungen eines einzelnen Benutzers verwenden Sie die Users-API.
# [web.debug]
@@ -2580,6 +2618,7 @@ Diese hot-reload-fähige Tabelle steuert den prozesseigenen serverseitigen WEB-D
| --- | --- | --- | --- |
| `enabled` | `bool` | `false` | Aktiviert WEB-HTTP-, WebSocket-Message-, Frame- und Lifecycle-Debugdatensätze. |
| `capture_lifecycle` | `bool` | `true` | Zeichnet typisierte Bridge-, Sitzungs-, Stream-, Handshake-, Relay- und Close-Ereignisse auf. |
| `sideband` | `bool` | `false` | Aktiviert Lifecycle-Diagnostik der generierten Bridge; wirksam nur zusammen mit `enabled` und `capture_lifecycle`. |
| `capture_headers` | `bool` | `true` | Speichert Headernamen und nur ausdrücklich zugelassene Werte ohne Zugangsdaten. |
| `capture_timings` | `bool` | `true` | Speichert Zeitpunkte für Request-Body, fertige Response, Response-Body und WebSocket-Message-Verarbeitung. |
| `capture_frames` | `bool` | `true` | Zerlegt begrenzte Carrier-Bodys in Frame-Typ, Stream-ID, Länge, WINDOW- und Fehlermetadaten, ohne die Frame-Nutzlast zusätzlich zu speichern. |
@@ -2591,6 +2630,8 @@ Diese hot-reload-fähige Tabelle steuert den prozesseigenen serverseitigen WEB-D
Eine Änderung von `enabled` oder einem Erfassungsfeld löscht gespeicherte Datensätze und verwirft Commits, die unter der vorherigen Policy-Epoche begonnen wurden. Ändert sich nur das standardmäßige oder maximale Beobachtungsfenster, bleiben kompatible Datensätze erhalten. `full` speichert den vollständigen Body eines erkannten Carriers nur bis `web.limits.max_body_bytes`; Decoy-Bodys bleiben immer auf einen Präfix begrenzt. Ein Präfix, der nur mit einer gleichzeitig erhöhten, neustartpflichtigen Kapazität zulässig wäre, wird zusammen mit `web.debug` bis zum Neustart zurückgestellt. URI-Queries werden nie gespeichert, Werte von Credential-Headern werden ausgelassen, Body-Kopien werden von bekannten WEB-Capabilities und Bearer-Tokens bereinigt und Profilschlüssel ausschließlich als domänengetrennter Fingerprint mit 16 Hex-Zeichen dargestellt.
Wenn `enabled`, `sideband` und `capture_lifecycle` alle aktiv sind, senden neu generierte Bridge-Seiten begrenzte einmalige Lifecycle-Ereignisse an die exakte konfigurierte Basis plus `api/v1/diagnostic`. Die Route ist Telemt-intern und keine öffentliche Control API. Bereits ausgegebene Bridge-Dokumente erhalten dieses Verhalten durch Reload nicht nachträglich.
Die authentifizierte JSON-Steuerung kann den Ring mit `POST /v1/runtime/web/debug/clear` explizit löschen. Die erforderliche prozessbezogene `runtime_instance` sperrt veraltete Controller, die zurückgegebene Epoche sperrt laufende Writer und `leased_bytes` meldet Speicher, der noch von bereits gerenderten Snapshots gehalten wird.
# [web.limits]
@@ -2605,6 +2646,7 @@ Diese prozessweiten Obergrenzen begrenzen alle WEB-Register, Warteschlangen, Req
| `carrier_batch_bytes` | `usize` | `2097152` | Maximale Größe eines kodierten Downlink-Batches. |
| `max_frames_per_body` | `usize` | `4096` | Maximale Zahl geparster oder ausgegebener Frames pro Carrier-Body. |
| `max_http_connections` | `usize` | `1024` | Prozessweit akzeptierte WEB-HTTP-Verbindungen. |
| `max_http_overload_connections` | `usize` | `64` | Akzeptierte überlastete Sockets, die außerhalb normaler HTTP-Kapazität warten oder eine begrenzte wiederholbare Antwort senden dürfen. |
| `max_http_handlers` | `usize` | `512` | Prozessweit gleichzeitig ausgeführte HTTP-Handler; HTTPS-Lanes dürfen höchstens die Hälfte mit Long Polls belegen, der Rest bleibt für Session-, Uplink- und Steuerarbeit verfügbar. |
| `max_lane_open_waits_per_session` | `usize` | `16` | Kanonische Cursor-null-Downlink-Polls, die pro Sitzung auf ein konkurrierendes Lane-`OPEN` warten dürfen. |
| `pending_bytes_per_lane` | `usize` | `8388608` | Eingereihte und residente `DATA`-Bytes pro unabhängiger HTTPS- oder WebSocket-Lane. |
@@ -2659,6 +2701,7 @@ Sofern eine Zeile nichts anderes angibt, werden Timeouts in Sekunden angegeben u
| `long_poll_secs` | `u64` | `25` | `✔` | Maximale Dauer eines leeren Downlink-Long-Polls. |
| `bridge_request_secs` | `u64` | `10` | `✔` | Bridge-seitige Deadline eines HTTP-Versuchs bis zum vollständigen Lesen des Response-Bodys; `/down` erhält zusätzlich `long_poll_secs`. Bereich `1..=60`. |
| `bridge_retry_secs` | `u64` | `90` | `✔` | Absolutes Bridge-Retry-Fenster einschließlich Versuchen und Backoff; Bereich `1..=300` und nicht kleiner als `bridge_request_secs`. |
| `bridge_recovery_secs` | `u64` | `15` | `✔` | Absolutes Recovery-Fenster nach dem Commit für ein weiterlebendes Bridge-Dokument; Bereich `1..=60`, beim Recovery-Start fixiert. |
| `carrier_probe_coalesce_ms` | `u64` | `0` | `✔` | Optionales Bridge-Warten nach `OPEN` auf passendes `DATA`; Millisekunden im Bereich `0..=10`, wobei `0` sofortiges Probing beibehält. |
| `lane_open_wait_secs` | `u64` | `2` | `✔` | Wartezeit für einen kanonischen Cursor-null-Downlink, der sein Lane-`OPEN` überholt; höchstens `long_poll_secs`. |
| `carrier_health_secs` | `u64` | `30` | `✔` | Beobachtungsintervall nach dem Commit, bevor ein Carrier Learning-Evidenz liefern kann. |
@@ -2672,6 +2715,7 @@ Sofern eine Zeile nichts anderes angibt, werden Timeouts in Sekunden angegeben u
| `bootstrap_lifetime_secs` | `u64` | `120` | `✔` | Lebensdauer ungenutzter Bootstraps und geschlossener Token-Replay-Marker. |
| `reconnect_grace_secs` | `u64` | `120` | `✔` | Maximale Carrier-Inaktivität bis zum Schließen der Sitzung. |
| `http_idle_secs` | `u64` | `75` | `✔` | Idle-Grenze zwischen HTTP-Austauschvorgängen und bei ausbleibendem Fortschritt eines bereits ausgegebenen Response-Bodys. Explizit begrenzte Request-Body-, Long-Poll-, Decoy- und ausstehende Upgrade-Phasen behalten ihre eigenen Deadlines und werden nicht durch diesen Timer verkürzt. Der Wert wird beim Annehmen der Verbindung fixiert. |
| `http_overload_timeout_ms` | `u64` | `250` | `✔` | Deadline je Phase in Millisekunden, um bei akzeptierter Überlast auf Kapazität zu warten oder die wiederholbare Antwort zu schreiben; Bereich `1..=60000`. Wait-Timeout und Response-Write erhalten jeweils höchstens ein Phasenbudget. |
| `shutdown_secs` | `u64` | `15` | `✔` | Ein absolutes Budget für das Beenden des Prozesses, das von allen Listener-Acceptoren und Verbindungen sowie WEB-Sitzungs- und Hilfstask-Drains gemeinsam verwendet wird. Der aktive Wert wird beim Start des Shutdowns einmalig erfasst. |
| `decoy_header_secs` | `u64` | `30` | `✔` | Deadline für Verbindung und Response-Head eines HTTP-Decoys. |
@@ -2680,11 +2724,12 @@ Sofern eine Zeile nichts anderes angibt, werden Timeouts in Sekunden angegeben u
| Schlüssel | Typ | Erforderlich | Hot-Reload | Beschreibung |
| --- | --- | --- | --- | --- |
| `host` | `String` | ja | `✔` | Eindeutiger, kanonischer ACE-FQDN in Kleinbuchstaben ohne Port, Pfad, Zugangsdaten oder abschließenden Punkt. |
| `base_path` | `String` | nein | `✔` | Exaktes, groß-/kleinschreibungssensitives WEB-Präfix ohne führenden oder abschließenden Schrägstrich; standardmäßig leer. Höchstens 128 ASCII-Bytes in durch Schrägstriche getrennten Segmenten `[A-Za-z0-9][A-Za-z0-9_-]*`. |
| `public_addr` | `SocketAddr` | ja | `✔` | Konkrete öffentliche IP auf Port `443`; wird im Ziel-Tupel des inneren Relays verwendet. |
| `decoy` | Tabelle | ja | `✔` | Gewöhnlicher Site-Fallback für nicht authentifizierten oder ungültigen Datenverkehr. |
| `profiles` | Tabellen-Array | bei aktiviertem WEB | `✔` | Explizite Benutzer und Client-Secret-Modi für diesen Hostnamen. |
Der Hostname wird bei der Validierung normalisiert und muss von Telegram Desktop akzeptiert werden. Ein Bootstrap ist ein Bearer-Token: Client-Adresse und IP-Familie dürfen sich vor der Sitzungserstellung ändern. Ein ungenutzter Bootstrap bleibt über einen Konfigurations-Reload hinweg nur gültig, solange dieselbe Profilidentität aktiv bleibt.
Der Hostname wird bei der Validierung normalisiert und muss von Telegram Desktop akzeptiert werden. Ein leerer `base_path` behält die Root-Capability v1 und das bisherige hexadezimale Link-Secret. Ein nicht leerer Pfad verwendet die v2-Host/Pfad-Capability und einen Telegram-Desktop-Pfadlink mit percent-encoded `HOST/BASE` sowie dem base64url-Secret-Marker `0x70`. Das Routing verlangt das exakte Präfix mit abschließendem Schrägstrich und leitet es nie um, normalisiert oder entfernt es. Ein Bootstrap ist ein Bearer-Token: Client-Adresse und IP-Familie dürfen sich vor der Sitzungserstellung ändern. Ein ungenutzter Bootstrap bleibt über einen Konfigurations-Reload hinweg nur gültig, solange dieselbe Profilidentität aktiv bleibt.
# [web.vhosts.decoy]
@@ -2710,6 +2755,7 @@ Profilgrenzen müssen ungleich null sein und dürfen die zugehörigen globalen G
## WEB-Lebenszyklus und API-Verwaltung
- Config-Watcher und Generations-Reload wenden `web.enabled`, Carrier- und Negotiation-Richtlinie, `web.debug`, `web.timeouts`, vhosts, Profile und Decoy-Snapshots ohne Prozessneustart an. Ein einzelner unveränderlicher expandierter Source-Snapshot wird validiert und aktiviert; der Watcher einer Kandidatengeneration startet erst nach deren Aktivierung. Bestehende Sitzungen und laufende Negotiation-Ketten behalten Carrier-Kandidaten, Grenzen, Timeouts und absolute Deadlines ihres Ausgabezeitpunkts; neue Bridge-Sitzungen verwenden genau eine fixierte aktive Generation.
- Eine Änderung von `base_path` ersetzt atomar sowohl die Route für neue Requests als auch die abgeleitete Capability. Geben Sie zuerst neue Links aus und beenden Sie betroffene aktive Sitzungen: etablierte WebSockets und bereits geroutete Austauschvorgänge laufen weiter; spätere Requests an die alte Basis mit einem prozessauthentischen Bootstrap- oder Session-Token erhalten ein lokales, nicht cachebares `404`, während die nun inaktive alte Capability der gewöhnlichen Decoy-Behandlung folgt.
- Bestand und Vertrauensrichtlinie der WEB-Listener unter `server.listeners` sowie alle Werte in `web.limits` sind prozesseigen und erfordern einen Neustart.
- `GET /v1/config` liefert den vollständigen verfassten `[web]`-Baum außer dem abgeleiteten Snapshot `web.runtime`. `PATCH /v1/config` akzeptiert ein dünn besetztes `web`-Objekt, führt Tabellen tief zusammen, ersetzt Arrays vollständig, validiert den gesamten Kandidaten und meldet `web.limits` bis zum Neustart in `deferred_process_fields`.
- `GET /v1/runtime/web/status`, `/sessions`, `/sessions/{session_ref}` und `/operations/{operation_id}` stellen begrenzten, nicht geheimen Runtime-Zustand bereit. POST-Steuerungen schließen ausgewählte Sitzungen, löschen Debugdaten oder setzen Carrier-Learning zurück und verlangen die aktuelle zufällige `runtime_instance`.
@@ -2837,8 +2883,10 @@ Profilgrenzen müssen ungleich null sein und dürfen die zugehörigen globalen G
| [`tls_fetch_scope`](#tls_fetch_scope) | `String` | `""` | `✘` |
| [`tls_fetch`](#tls_fetch) | `Table` | integrierte Standardeinstellungen | `✘` |
| [`mask`](#mask) | `bool` | `true` | `✘` |
| [`mask_dynamic`](#mask_dynamic) | `bool` | `true` | `✘` |
| [`mask_host`](#mask_host) | `String` | — | `✘` |
| [`mask_port`](#mask_port) | `u16` | `443` | `✘` |
| [`exclusive_mask`](#exclusive_mask) | `Map<String, String>` | `{}` | `✘` |
| [`mask_unix_sock`](#mask_unix_sock) | `String` | — | `✘` |
| [`fake_cert_len`](#fake_cert_len) | `usize` | `2048` | `✘` |
| [`tls_emulation`](#tls_emulation) | `bool` | `true` | `✘` |
@@ -2926,11 +2974,20 @@ Profilgrenzen müssen ungleich null sein und dürfen die zugehörigen globalen G
[censorship]
mask = true
```
## mask_dynamic
- **Einschränkungen / Validierung**: `bool`.
- **Beschreibung**: Wenn weder `mask_host` noch `mask_unix_sock` gesetzt ist, wird eine passende ClientHello-SNI aus `tls_domain`/`tls_domains` als TCP-Mask-Ziel verwendet; ohne Treffer wird auf die primäre `tls_domain` zurückgegriffen. Ein passender `exclusive_mask`-Eintrag hat immer Vorrang vor regulären Zielen.
- **Beispiel**:
```toml
[censorship]
mask_dynamic = true
```
## mask_host
- **Einschränkungen / Validierung**: `String` (optional).
- Wenn `mask_unix_sock` gesetzt ist, muss `mask_host` ausgelassen werden (mutually exclusive).
- Wenn weder `mask_host` noch `mask_unix_sock` gesetzt ist, verwendet Telemt standardmäßig `tls_domain` als `mask_host`.
- **Beschreibung**: Upstream-Mask-Host für das TLS-Fronting-Relay.
- Wenn weder `mask_host` noch `mask_unix_sock` gesetzt ist, darf `mask_dynamic` eine passende konfigurierte SNI wählen; andernfalls verwendet Telemt `tls_domain`.
- **Beschreibung**: Expliziter Upstream-Mask-Host für das TLS-Fronting-Relay. Wenn gesetzt, deaktiviert er die dynamische SNI-Zielwahl mit Ausnahme von `exclusive_mask`-Overrides.
- **Beispiel**:
```toml
@@ -3444,8 +3501,9 @@ Wenn Backend oder Netzwerk stark bandbreitenbeschränkt sind, reduzieren Sie zue
user_max_tcp_conns_global_each = 200
[access.user_max_tcp_conns]
alice = 500 # uses 500, not the global cap
# bob hat keinen Eintrag → verwendet 200
# Alice uses 500 rather than the global cap.
alice = 500
# Bob has no entry and therefore uses 200.
```
## user_expirations
- **Einschränkungen / Validierung**: `Map<String, DateTime<Utc>>`. Jeder Wert muss eine gültige RFC3339/ISO-8601-Datumszeit sein.
@@ -3463,7 +3521,8 @@ Wenn Backend oder Netzwerk stark bandbreitenbeschränkt sind, reduzieren Sie zue
```toml
[access.user_data_quota]
alice = 1073741824 # 1 GiB
# Alice receives a 1 GiB quota.
alice = 1073741824
```
## user_max_unique_ips
- **Einschränkungen / Validierung**: `Map<String, usize>`.
@@ -3545,7 +3604,7 @@ Wenn Backend oder Netzwerk stark bandbreitenbeschränkt sind, reduzieren Sie zue
## user_rate_limits
- **Einschränkungen / Validierung**: Tabelle `username -> { up_bps, down_bps }`. Mindestens eine Richtung muss ungleich Null sein.
- **Einschränkungen / Validierung**: Tabelle `username -> { up_bps, down_bps }`. Jede Richtung muss in `0..=100000000000` liegen; `0` bedeutet für diese Richtung unbegrenzt, und mindestens eine Richtung muss ungleich Null sein.
- **Beschreibung**: Bandbreitenobergrenzen pro User in Bits/Sekunde für Upload (`up_bps`) und Download (`down_bps`).
- **Beispiel**:
@@ -3554,7 +3613,7 @@ Wenn Backend oder Netzwerk stark bandbreitenbeschränkt sind, reduzieren Sie zue
alice = { up_bps = 1048576, down_bps = 2097152 }
```
## cidr_rate_limits
- **Einschränkungen / Validierung**: Tabelle `CIDR oder Auto-Template -> { up_bps, down_bps }`. Explizite CIDR-Schlüssel müssen als `IpNetwork` parsbar sein; Auto-Template-Schlüssel müssen `*4/N` (`N=0..32`), `*6/N` (`N=0..128`) oder `*/N` (`N=0..32`) verwenden. Mindestens eine Richtung muss ungleich Null sein. Doppelte normalisierte Auto-Templates werden abgelehnt.
- **Einschränkungen / Validierung**: Tabelle `CIDR oder Auto-Template -> { up_bps, down_bps }`. Jede Richtung muss in `0..=100000000000` liegen; `0` bedeutet für diese Richtung unbegrenzt, und mindestens eine Richtung muss ungleich Null sein. Explizite CIDR-Schlüssel müssen als `IpNetwork` parsbar sein; Auto-Template-Schlüssel müssen `*4/N` (`N=0..32`), `*6/N` (`N=0..128`) oder `*/N` (`N=0..32`) verwenden. Doppelte normalisierte Auto-Templates werden abgelehnt.
- **Beschreibung**: Source-Subnetz-Bandbreitenlimits, die zusätzlich zu Per-User-Limits greifen. Explizite CIDR-Regeln verwenden Longest-Prefix-Wins und haben Vorrang vor Auto-Templates. Auto-Templates erzeugen Buckets lazy pro passendem Source-Subnetz: `*4/N` für IPv4, `*6/N` für IPv6 und `*/N` als Dual-Stack-Shorthand, bei dem IPv4 `/N` und IPv6 `/(N * 4)` nutzt.
- **Beispiel**:
@@ -3683,7 +3742,8 @@ Wenn Backend oder Netzwerk stark bandbreitenbeschränkt sind, reduzieren Sie zue
[[upstreams]]
type = "socks5"
address = "203.0.113.10:1080"
interface = "192.0.2.10" # explicit local bind IP
# Use an explicit local bind IP.
interface = "192.0.2.10"
```
## bind_addresses
- **Einschränkungen / Validierung**: `String[]` (optional). Gilt nur für `type = "direct"`.
docs/Config_params/CONFIG_PARAMS.en.md
+66 -25
View File
@@ -10,7 +10,7 @@ This document lists all configuration keys accepted by `config.toml`.
>
> 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.
> `Hot-Reload` marks whether a changed value is applied by the config watcher without restarting the process; `✘` means restart is required for runtime effect.
> `Hot-Reload` marks whether a changed value is applied directly by the config watcher. `✘` means the watcher does not apply it; depending on the field, full effect requires an in-process runtime-generation reload or a process restart.
# Table of contents
- [Top-level keys](#top-level-keys)
@@ -204,6 +204,7 @@ This document lists all configuration keys accepted by `config.toml`.
| [`me_keepalive_payload_random`](#me_keepalive_payload_random) | `bool` | `true` | `✘` |
| [`rpc_proxy_req_every`](#rpc_proxy_req_every) | `u64` | `0` | `✘` |
| [`me_writer_cmd_channel_capacity`](#me_writer_cmd_channel_capacity) | `usize` | `4096` | `✘` |
| [`me_writer_byte_budget_bytes`](#me_writer_byte_budget_bytes) | `usize` | `33570816` | `✘` |
| [`me_route_channel_capacity`](#me_route_channel_capacity) | `usize` | `768` | `✘` |
| [`me_c2me_channel_capacity`](#me_c2me_channel_capacity) | `usize` | `1024` | `✘` |
| [`me_c2me_send_timeout_ms`](#me_c2me_send_timeout_ms) | `u64` | `4000` | `✘` |
@@ -216,6 +217,7 @@ This document lists all configuration keys accepted by `config.toml`.
| [`me_d2c_frame_buf_shrink_threshold_bytes`](#me_d2c_frame_buf_shrink_threshold_bytes) | `usize` | `262144` | `✔` |
| [`direct_relay_copy_buf_c2s_bytes`](#direct_relay_copy_buf_c2s_bytes) | `usize` | `65536` | `✔` |
| [`direct_relay_copy_buf_s2c_bytes`](#direct_relay_copy_buf_s2c_bytes) | `usize` | `262144` | `✔` |
| [`direct_relay_buffer_budget_max_bytes`](#direct_relay_buffer_budget_max_bytes) | `usize` | `0` | `✘` |
| [`crypto_pending_buffer`](#crypto_pending_buffer) | `usize` | `262144` | `✘` |
| [`max_client_frame`](#max_client_frame) | `usize` | `16777216` | `✘` |
| [`desync_all_full`](#desync_all_full) | `bool` | `false` | `✔` |
@@ -301,7 +303,7 @@ This document lists all configuration keys accepted by `config.toml`.
| [`me_pool_drain_soft_evict_per_writer`](#me_pool_drain_soft_evict_per_writer) | `u8` | `2` | `✘` |
| [`me_pool_drain_soft_evict_budget_per_core`](#me_pool_drain_soft_evict_budget_per_core) | `u16` | `16` | `✘` |
| [`me_pool_drain_soft_evict_cooldown_ms`](#me_pool_drain_soft_evict_cooldown_ms) | `u64` | `1000` | `✘` |
| [`me_bind_stale_mode`](#me_bind_stale_mode) | `"never"`, `"ttl"`, or `"always"` | `"ttl"` | `✔` |
| [`me_bind_stale_mode`](#me_bind_stale_mode) | `"never"`, `"ttl"`, or `"always"` | `"never"` | `✔` |
| [`me_bind_stale_ttl_secs`](#me_bind_stale_ttl_secs) | `u64` | `90` | `✔` |
| [`me_pool_min_fresh_ratio`](#me_pool_min_fresh_ratio) | `f32` | `0.8` | `✔` |
| [`me_reinit_drain_timeout_secs`](#me_reinit_drain_timeout_secs) | `u64` | `90` | `✔` |
@@ -347,6 +349,8 @@ This document lists all configuration keys accepted by `config.toml`.
[general]
config_strict = true
```
- **Known limitation**: In this revision, `config_strict = true` rejects the otherwise supported `access.user_source_deny` and `[[upstreams]].prefer` keys. Keep strict mode disabled when either key is present.
## prefer_ipv6
- **Constraints / validation**: Deprecated. Use `network.prefer`.
- **Description**: Deprecated legacy IPv6 preference flag migrated to `network.prefer`.
@@ -483,8 +487,8 @@ This document lists all configuration keys accepted by `config.toml`.
stun_nat_probe_concurrency = 8
```
## middle_proxy_pool_size
- **Constraints / validation**: `usize`. Effective value is `max(value, 1)` at runtime (so `0` behaves as `1`).
- **Description**: Target size of active ME writer pool.
- **Constraints / validation**: `usize`. The value passed to ME initialization is normalized as `max(value, 1)`.
- **Description**: Non-enforcing compatibility input currently emitted in the ME initialization log. Active writer targets are derived from the DC-family floor policy, not this value.
- **Example**:
```toml
@@ -575,7 +579,7 @@ This document lists all configuration keys accepted by `config.toml`.
rpc_proxy_req_every = 0
```
## me_writer_cmd_channel_capacity
- **Constraints / validation**: Must be `> 0`.
- **Constraints / validation**: Must be within `1..=16384`.
- **Description**: Capacity of per-writer command channel.
- **Example**:
@@ -583,8 +587,17 @@ This document lists all configuration keys accepted by `config.toml`.
[general]
me_writer_cmd_channel_capacity = 4096
```
## me_writer_byte_budget_bytes
- **Constraints / validation**: Must be a multiple of `16384` within the dynamic minimum and `268435456`. The minimum is `2 * general.max_client_frame + 256`, rounded up to `16384`; with the default frame size it is `33570816`.
- **Description**: Resident byte budget for each ME writer data queue. The file watcher does not rebuild existing writers for this field; it takes effect when a new ME/runtime generation is built through the API or after restart.
- **Example**:
```toml
[general]
me_writer_byte_budget_bytes = 33570816
```
## me_route_channel_capacity
- **Constraints / validation**: Must be `> 0`.
- **Constraints / validation**: Must be within `1..=8192`.
- **Description**: Capacity of per-connection ME response route channel.
- **Example**:
@@ -593,7 +606,7 @@ This document lists all configuration keys accepted by `config.toml`.
me_route_channel_capacity = 768
```
## me_c2me_channel_capacity
- **Constraints / validation**: Must be `> 0`.
- **Constraints / validation**: Must be within `1..=8192`.
- **Description**: Capacity of per-client command queue (client reader -> ME sender).
- **Example**:
@@ -691,6 +704,15 @@ This document lists all configuration keys accepted by `config.toml`.
[general]
direct_relay_copy_buf_s2c_bytes = 262144
```
## direct_relay_buffer_budget_max_bytes
- **Constraints / validation**: `0`, or a multiple of `4096` within `16777216..=2147483648`.
- **Description**: Process-wide hard ceiling for Direct relay copy buffers. `0` derives the ceiling at process startup from cgroup or host memory limits. This field is process-owned and restart-deferred.
- **Example**:
```toml
[general]
direct_relay_buffer_budget_max_bytes = 0
```
## crypto_pending_buffer
- **Constraints / validation**: `usize` (bytes).
- **Description**: Max pending ciphertext buffer per client writer (bytes).
@@ -701,7 +723,7 @@ This document lists all configuration keys accepted by `config.toml`.
crypto_pending_buffer = 262144
```
## max_client_frame
- **Constraints / validation**: `usize` (bytes).
- **Constraints / validation**: Must be within `4096..=16777216` (bytes).
- **Description**: Maximum allowed client MTProto frame size (bytes).
- **Example**:
@@ -1214,7 +1236,7 @@ This document lists all configuration keys accepted by `config.toml`.
me_route_hybrid_max_wait_ms = 3000
```
## me_route_blocking_send_timeout_ms
- **Constraints / validation**: Must be within `0..=5000` (milliseconds). `0` keeps legacy unbounded wait behavior.
- **Constraints / validation**: Must be within `1..=5000` (milliseconds).
- **Description**: Maximum wait for blocking route-channel send fallback.
- **Example**:
@@ -1397,7 +1419,7 @@ This document lists all configuration keys accepted by `config.toml`.
```
## me_pool_drain_ttl_secs
- **Constraints / validation**: `u64` (seconds). `0` disables the drain-TTL window (and suppresses drain-TTL warnings for non-empty draining writers).
- **Description**: Drain-TTL time window for stale ME writers after endpoint map changes. During the TTL, stale writers may be used only as fallback for new bindings (depending on bind policy).
- **Description**: Age threshold for prolonged-drain warnings after endpoint map changes and the lower bound used when normalizing the force-close timeout. Stale-bind eligibility is controlled separately by `me_bind_stale_mode` and `me_bind_stale_ttl_secs`.
- **Example**:
```toml
@@ -1477,7 +1499,7 @@ This document lists all configuration keys accepted by `config.toml`.
```
## me_bind_stale_mode
- **Constraints / validation**: `"never"`, `"ttl"`, or `"always"`.
- **Description**: Policy for new binds on stale draining writers.
- **Description**: Policy for new binds on stale draining writers in uncovered DC-family groups. The default `never` requires complete group coverage before a partial hardswap can commit; `ttl` and `always` permit policy-bounded fallback.
- **Example**:
```toml
@@ -1487,7 +1509,7 @@ This document lists all configuration keys accepted by `config.toml`.
```
## me_bind_stale_ttl_secs
- **Constraints / validation**: `u64`.
- **Description**: TTL for stale bind allowance when stale mode is `ttl`.
- **Description**: TTL for stale bind allowance when stale mode is `ttl`; `0` disables TTL expiry for eligible draining writers.
- **Example**:
```toml
@@ -1497,7 +1519,7 @@ This document lists all configuration keys accepted by `config.toml`.
```
## me_pool_min_fresh_ratio
- **Constraints / validation**: Must be within `[0.0, 1.0]`.
- **Description**: Minimum fresh desired-DC coverage ratio before stale writers are drained.
- **Description**: Minimum fresh DC-family coverage ratio required at generation commit. Missing groups still block commit under `me_bind_stale_mode = "never"` even when this ratio is satisfied.
- **Example**:
```toml
@@ -1506,8 +1528,8 @@ This document lists all configuration keys accepted by `config.toml`.
me_pool_min_fresh_ratio = 0.9
```
## me_reinit_drain_timeout_secs
- **Constraints / validation**: `u64`. `0` uses the runtime safety fallback force-close timeout. If `> 0` and `< me_pool_drain_ttl_secs`, runtime bumps it to TTL.
- **Description**: Force-close timeout for draining stale writers. When set to `0`, the effective timeout is the runtime safety fallback (300 seconds).
- **Constraints / validation**: `u64`. `0` first selects the 300-second runtime safety fallback; the effective timeout is then raised to at least `me_pool_drain_ttl_secs`.
- **Description**: Force-close timeout for draining stale writers. The effective value is the greater of the configured non-zero value (or 300 seconds for `0`) and the drain TTL.
- **Example**:
```toml
@@ -1559,7 +1581,7 @@ This document lists all configuration keys accepted by `config.toml`.
```
## me_reinit_trigger_channel
- **Constraints / validation**: Must be within `[1, 4096]`.
- **Description**: Trigger queue capacity for reinit scheduler.
- **Description**: Trigger queue capacity for the reinit scheduler. A new runtime generation constructs its channel from this value; the file watcher alone does not resize the active channel.
- **Example**:
```toml
@@ -2596,6 +2618,7 @@ This hot-reloadable table controls the process-owned server-side WEB debug recor
| --- | --- | --- | --- |
| `enabled` | `bool` | `false` | Enables WEB HTTP, WebSocket-message, frame, and lifecycle debug records. |
| `capture_lifecycle` | `bool` | `true` | Records typed bridge, session, stream, handshake, relay, and close events. |
| `sideband` | `bool` | `false` | Enables generated-bridge lifecycle diagnostics; effective only when `enabled` and `capture_lifecycle` are also true. |
| `capture_headers` | `bool` | `true` | Retains header names and only allowlisted non-credential values. |
| `capture_timings` | `bool` | `true` | Retains request-body, response-ready, response-body, and WebSocket message-processing timing points. |
| `capture_frames` | `bool` | `true` | Parses bounded carrier bodies into frame type, stream ID, length, WINDOW, and error metadata without retaining frame payload separately. |
@@ -2607,6 +2630,8 @@ This hot-reloadable table controls the process-owned server-side WEB debug recor
Changing `enabled` or any capture field clears retained records and rejects commits started under the previous policy epoch. Changing only the default or maximum observation window preserves compatible retained records. `full` retains a complete recognized carrier body only up to `web.limits.max_body_bytes`; decoy bodies always remain prefix-bounded. A prefix that depends on a simultaneously increased restart-only capacity is deferred with `web.debug` until restart. URI queries are never retained, credential header values are omitted, body copies are scrubbed for known WEB capabilities and bearer tokens, and profile keys are represented only by a domain-separated 16-hex fingerprint.
When `enabled`, `sideband`, and `capture_lifecycle` are all true, newly generated bridge pages send bounded one-shot lifecycle events to the exact configured base plus `api/v1/diagnostic`. The route is internal to Telemt and does not expose a public control API. Existing bridge documents do not acquire sideband behavior after reload.
Authenticated JSON control may clear the ring explicitly with `POST /v1/runtime/web/debug/clear`; the required process `runtime_instance` fences stale controllers, the returned epoch fences in-flight writers, and `leased_bytes` reports memory still owned by already rendered snapshots.
# [web.limits]
@@ -2699,11 +2724,12 @@ Unless a row states otherwise, timeouts are measured in seconds and must be with
| Key | Type | Required | Hot-Reload | Description |
| --- | --- | --- | --- | --- |
| `host` | `String` | yes | `✔` | Unique, canonical lowercase ACE FQDN without port, path, credentials, or trailing dot. |
| `base_path` | `String` | no | `✔` | Exact case-sensitive WEB prefix without leading or trailing slash; empty by default. At most 128 ASCII bytes in slash-separated `[A-Za-z0-9][A-Za-z0-9_-]*` segments. |
| `public_addr` | `SocketAddr` | yes | `✔` | Concrete public IP on port `443`; used in the inner relay destination tuple. |
| `decoy` | table | yes | `✔` | Ordinary-site fallback for unauthenticated or invalid traffic. |
| `profiles` | array of tables | when enabled | `✔` | Explicit users and client secret modes exposed by this hostname. |
The hostname must be accepted by Telegram Desktop and is normalized during validation. A bootstrap is a bearer credential: its client address and address family may change before session creation. An unused bootstrap remains valid across a configuration reload only while the same profile identity is still active.
The hostname must be accepted by Telegram Desktop and is normalized during validation. An empty `base_path` keeps the root v1 capability and legacy hexadecimal link secret. A non-empty path uses the v2 host/path capability and a Telegram Desktop path link with percent-encoded `HOST/BASE` plus the `0x70` base64url secret marker. Routing requires the exact slash-terminated prefix and never redirects, normalizes, or strips it. A bootstrap is a bearer credential: its client address and address family may change before session creation. An unused bootstrap remains valid across a configuration reload only while the same profile identity is still active.
# [web.vhosts.decoy]
@@ -2729,6 +2755,7 @@ Profile limits must be non-zero and no greater than their corresponding global l
## WEB lifecycle and API management
- The config watcher and generation reload apply `web.enabled`, carrier and negotiation policy, `web.debug`, `web.timeouts`, vhosts, profiles, and decoy snapshots without a process restart. One immutable expanded source snapshot is validated and activated; a candidate generation's watcher starts only after that generation becomes active. Existing sessions and in-flight negotiation chains keep their issuance-time carrier candidates, limits, timeouts, and absolute deadlines; newly issued bridge sessions use one pinned active generation.
- Changing `base_path` atomically replaces both the new-request route and derived capability. Reissue links and drain affected live sessions first: established WebSockets and already routed exchanges continue; later old-base requests carrying a process-authentic bootstrap or session token receive a local no-store `404`, while the now-inactive old capability follows ordinary decoy handling.
- WEB listener inventory and trust policy under `server.listeners`, and every `web.limits` value, are process-owned and restart-required.
- `GET /v1/config` returns the complete authored `[web]` tree except the derived `web.runtime` snapshot. `PATCH /v1/config` accepts a sparse `web` object, deep-merges tables, replaces arrays wholesale, validates the complete candidate, and reports `web.limits` in `deferred_process_fields` until restart.
- `GET /v1/runtime/web/status`, `/sessions`, `/sessions/{session_ref}`, and `/operations/{operation_id}` expose bounded non-secret runtime state. POST controls close selected sessions, clear debug data, or reset carrier learning and require the current random `runtime_instance`.
@@ -2856,8 +2883,10 @@ Profile limits must be non-zero and no greater than their corresponding global l
| [`tls_fetch_scope`](#tls_fetch_scope) | `String` | `""` | `✘` |
| [`tls_fetch`](#tls_fetch) | `Table` | built-in defaults | `✘` |
| [`mask`](#mask) | `bool` | `true` | `✘` |
| [`mask_dynamic`](#mask_dynamic) | `bool` | `true` | `✘` |
| [`mask_host`](#mask_host) | `String` | — | `✘` |
| [`mask_port`](#mask_port) | `u16` | `443` | `✘` |
| [`exclusive_mask`](#exclusive_mask) | `Map<String, String>` | `{}` | `✘` |
| [`mask_unix_sock`](#mask_unix_sock) | `String` | — | `✘` |
| [`fake_cert_len`](#fake_cert_len) | `usize` | `2048` | `✘` |
| [`tls_emulation`](#tls_emulation) | `bool` | `true` | `✘` |
@@ -2945,11 +2974,20 @@ Profile limits must be non-zero and no greater than their corresponding global l
[censorship]
mask = true
```
## mask_dynamic
- **Constraints / validation**: `bool`.
- **Description**: When neither `mask_host` nor `mask_unix_sock` is configured, use a matching ClientHello SNI from `tls_domain`/`tls_domains` as the TCP mask target; if none matches, fall back to the primary `tls_domain`. A matching `exclusive_mask` entry always takes precedence over ordinary targets.
- **Example**:
```toml
[censorship]
mask_dynamic = true
```
## mask_host
- **Constraints / validation**: `String` (optional).
- If `mask_unix_sock` is set, `mask_host` must be omitted (mutually exclusive).
- If `mask_host` is not set and `mask_unix_sock` is not set, Telemt defaults `mask_host` to `tls_domain`.
- **Description**: Upstream mask host for TLS fronting relay.
- If neither `mask_host` nor `mask_unix_sock` is set, `mask_dynamic` may select a matching configured SNI; otherwise Telemt falls back to `tls_domain`.
- **Description**: Explicit upstream mask host for TLS fronting relay. When present, it disables dynamic SNI target selection except for `exclusive_mask` overrides.
- **Example**:
```toml
@@ -3463,8 +3501,9 @@ If your backend or network is very bandwidth-constrained, reduce cap first. If p
user_max_tcp_conns_global_each = 200
[access.user_max_tcp_conns]
alice = 500 # uses 500, not the global cap
# bob has no entry → uses 200
# Alice uses 500 rather than the global cap.
alice = 500
# Bob has no entry and therefore uses 200.
```
## user_expirations
- **Constraints / validation**: `Map<String, DateTime<Utc>>`. Each value must be a valid RFC3339 / ISO-8601 datetime.
@@ -3482,7 +3521,8 @@ If your backend or network is very bandwidth-constrained, reduce cap first. If p
```toml
[access.user_data_quota]
alice = 1073741824 # 1 GiB
# Alice receives a 1 GiB quota.
alice = 1073741824
```
## user_max_unique_ips
- **Constraints / validation**: `Map<String, usize>`.
@@ -3564,7 +3604,7 @@ If your backend or network is very bandwidth-constrained, reduce cap first. If p
## user_rate_limits
- **Constraints / validation**: Table `username -> { up_bps, down_bps }`. At least one direction must be non-zero.
- **Constraints / validation**: Table `username -> { up_bps, down_bps }`. Each direction must be within `0..=100000000000`; `0` means unlimited for that direction, and at least one direction must be non-zero.
- **Description**: Per-user bandwidth caps in bits/sec for upload (`up_bps`) and download (`down_bps`).
- **Example**:
@@ -3573,7 +3613,7 @@ If your backend or network is very bandwidth-constrained, reduce cap first. If p
alice = { up_bps = 1048576, down_bps = 2097152 }
```
## cidr_rate_limits
- **Constraints / validation**: Table `CIDR or auto-template -> { up_bps, down_bps }`. Explicit CIDR keys must parse as `IpNetwork`; auto-template keys must be `*4/N` (`N=0..32`), `*6/N` (`N=0..128`), or `*/N` (`N=0..32`). At least one direction must be non-zero. Duplicate normalized auto-templates are rejected.
- **Constraints / validation**: Table `CIDR or auto-template -> { up_bps, down_bps }`. Each direction must be within `0..=100000000000`; `0` means unlimited for that direction, and at least one direction must be non-zero. Explicit CIDR keys must parse as `IpNetwork`; auto-template keys must be `*4/N` (`N=0..32`), `*6/N` (`N=0..128`), or `*/N` (`N=0..32`). Duplicate normalized auto-templates are rejected.
- **Description**: Source-subnet bandwidth caps applied alongside per-user limits. Explicit CIDR rules use longest-prefix-wins and take priority over auto-templates. Auto-templates create buckets lazily per matched source subnet: `*4/N` for IPv4, `*6/N` for IPv6, and `*/N` as a dual-stack shorthand where IPv4 uses `/N` and IPv6 uses `/(N * 4)`.
- **Example**:
@@ -3702,7 +3742,8 @@ If your backend or network is very bandwidth-constrained, reduce cap first. If p
[[upstreams]]
type = "socks5"
address = "203.0.113.10:1080"
interface = "192.0.2.10" # explicit local bind IP
# Use an explicit local bind IP.
interface = "192.0.2.10"
```
## bind_addresses
- **Constraints / validation**: `String[]` (optional). Applies only to `type = "direct"`.
docs/Config_params/CONFIG_PARAMS.ru.md
+186 -35
View File
@@ -10,10 +10,11 @@
>
> Параметры конфигурации, подробно описанные в этом документе, предназначены для опытных пользователей и для целей тонкой настройки. Изменение этих параметров без четкого понимания их функции может привести к нестабильности приложения или другому неожиданному поведению. Пожалуйста, действуйте осторожно и на свой страх и риск.
> `Hot-Reload` показывает, применяет ли config watcher изменение без перезапуска процесса; `✘` означает, что для runtime-эффекта нужен перезапуск.
> `Hot-Reload` показывает, применяет ли config watcher изменение напрямую. `✘` означает, что watcher его не применяет; в зависимости от поля для полного эффекта требуется in-process reload runtime generation либо перезапуск процесса.
# Содержание
- [Ключи верхнего уровня](#top-level-keys)
- [Ключи верхнего уровня](#ключи-верхнего-уровня)
- [logging](#logging)
- [general](#general)
- [general.modes](#generalmodes)
- [general.links](#generallinks)
@@ -42,6 +43,7 @@
| --- | ---- | ------- | ---------- |
| [`include`](#include) | `String` (специальная директива) | — | `✔` |
| [`show_link`](#show_link) | `"*"` or `String[]` | `[]` (`ShowLink::None`) | `✘` |
| [`logging`](#logging) | Таблица | значения по умолчанию | `✘` |
| [`dc_overrides`](#dc_overrides) | `Map<String, String or String[]>` | `{}` | `✘` |
| [`default_dc`](#default_dc) | `u8` | — (эффективный резервный вариант: `2` в ME маршрутизации) | `✘` |
| [`beobachten`](#beobachten) | `bool` | `true` | `✘` |
@@ -80,7 +82,7 @@
"203" = ["149.154.175.100:443", "91.105.192.100:443"]
```
## default_dc
- **Ограничения / валидация**: целочисленное значение в диапазоне `1..=5`. Если значение выходит за пределы диапазона, клиент направляется к DC1; Middle-end маршрутизация направляет клиента к DC2, если DC1 не задан.
- **Ограничения / валидация**: Предполагаемый диапазон — `1..=5`. Явно заданное значение вне диапазона в Direct relay приводит к поведению DC1; при отсутствии значения Middle-End routing использует DC2.
- **Описание**: DC по умолчанию, используемый для нестандартных DC. Когда клиент запрашивает неизвестный/нестандартный DC без переопределения, telemt направляет его в этот кластер по умолчанию.
- **Пример**:
@@ -90,6 +92,84 @@
default_dc = 2
```
# [logging]
| Ключ | Тип | По умолчанию | Hot-Reload |
| --- | --- | --- | --- |
| [`destination`](#loggingdestination) | `"stderr"` / `"syslog"` / `"file"` | `"stderr"` | `✘` |
| [`path`](#loggingpath) | `String` | — | `✘` |
| [`rotation`](#loggingrotation) | `"never"` / `"minutely"` / `"hourly"` / `"daily"` / `"weekly"` | `"never"` | `✘` |
| [`max_size_bytes`](#loggingmax_size_bytes) | `u64` | `0` | `✘` |
| [`max_files`](#loggingmax_files) | `usize` | `0` | `✘` |
| [`max_age_secs`](#loggingmax_age_secs) | `u64` | `0` | `✘` |
## logging.destination
- **Ограничения / валидация**: Допустимы `stderr`, `syslog` или `file`. `syslog` поддерживается только на Unix. Для `file` требуется `logging.path`.
- **Описание**: Выбирает runtime log destination. CLI-флаги имеют приоритет.
- **Пример**:
```toml
[logging]
destination = "file"
path = "/var/log/telemt.log"
```
## logging.path
- **Ограничения / валидация**: Обязателен при `logging.destination = "file"`; не может быть пустым.
- **Описание**: Путь для файлового логирования. При time-based rotation имя файла используется как rolling prefix.
- **Пример**:
```toml
[logging]
destination = "file"
path = "/var/log/telemt.log"
```
## logging.rotation
- **Ограничения / валидация**: Допустимы `never`, `minutely`, `hourly`, `daily` или `weekly`.
- **Описание**: Интервал time-based file rotation. `weekly` выполняет ротацию на границе воскресенья по UTC. `never` пишет точно в `logging.path`, если size rotation не включена.
- **Пример**:
```toml
[logging]
destination = "file"
path = "/var/log/telemt.log"
rotation = "daily"
```
## logging.max_size_bytes
- **Ограничения / валидация**: `0` отключает size rotation.
- **Описание**: Ротирует непустой активный файл перед записью следующей целой записи, если она превысит этот предел в байтах.
- **Пример**:
```toml
[logging]
destination = "file"
path = "/var/log/telemt.log"
max_size_bytes = 104857600
```
## logging.max_files
- **Ограничения / валидация**: `0` отключает retention по количеству файлов.
- **Описание**: Сохраняет не более указанного числа совпадающих log files, включая активный файл и архивы. Активный файл retention cleanup не удаляет.
- **Пример**:
```toml
[logging]
destination = "file"
path = "/var/log/telemt.log"
rotation = "daily"
max_files = 14
```
## logging.max_age_secs
- **Ограничения / валидация**: `0` отключает retention по возрасту.
- **Описание**: Удаляет ротированные log files старше указанного числа секунд по времени изменения. Активный файл retention cleanup не удаляет.
- **Пример**:
```toml
[logging]
destination = "file"
path = "/var/log/telemt.log"
rotation = "daily"
max_age_secs = 1209600
```
# [general]
@@ -124,6 +204,7 @@
| [`me_keepalive_payload_random`](#me_keepalive_payload_random) | `bool` | `true` | `✘` |
| [`rpc_proxy_req_every`](#rpc_proxy_req_every) | `u64` | `0` | `✘` |
| [`me_writer_cmd_channel_capacity`](#me_writer_cmd_channel_capacity) | `usize` | `4096` | `✘` |
| [`me_writer_byte_budget_bytes`](#me_writer_byte_budget_bytes) | `usize` | `33570816` | `✘` |
| [`me_route_channel_capacity`](#me_route_channel_capacity) | `usize` | `768` | `✘` |
| [`me_c2me_channel_capacity`](#me_c2me_channel_capacity) | `usize` | `1024` | `✘` |
| [`me_c2me_send_timeout_ms`](#me_c2me_send_timeout_ms) | `u64` | `4000` | `✘` |
@@ -136,6 +217,7 @@
| [`me_d2c_frame_buf_shrink_threshold_bytes`](#me_d2c_frame_buf_shrink_threshold_bytes) | `usize` | `262144` | `✔` |
| [`direct_relay_copy_buf_c2s_bytes`](#direct_relay_copy_buf_c2s_bytes) | `usize` | `65536` | `✔` |
| [`direct_relay_copy_buf_s2c_bytes`](#direct_relay_copy_buf_s2c_bytes) | `usize` | `262144` | `✔` |
| [`direct_relay_buffer_budget_max_bytes`](#direct_relay_buffer_budget_max_bytes) | `usize` | `0` | `✘` |
| [`crypto_pending_buffer`](#crypto_pending_buffer) | `usize` | `262144` | `✘` |
| [`max_client_frame`](#max_client_frame) | `usize` | `16777216` | `✘` |
| [`desync_all_full`](#desync_all_full) | `bool` | `false` | `✔` |
@@ -221,13 +303,14 @@
| [`me_pool_drain_soft_evict_per_writer`](#me_pool_drain_soft_evict_per_writer) | `u8` | `2` | `✘` |
| [`me_pool_drain_soft_evict_budget_per_core`](#me_pool_drain_soft_evict_budget_per_core) | `u16` | `16` | `✘` |
| [`me_pool_drain_soft_evict_cooldown_ms`](#me_pool_drain_soft_evict_cooldown_ms) | `u64` | `1000` | `✘` |
| [`me_bind_stale_mode`](#me_bind_stale_mode) | `"never"`, `"ttl"`, or `"always"` | `"ttl"` | `✔` |
| [`me_bind_stale_mode`](#me_bind_stale_mode) | `"never"`, `"ttl"`, or `"always"` | `"never"` | `✔` |
| [`me_bind_stale_ttl_secs`](#me_bind_stale_ttl_secs) | `u64` | `90` | `✔` |
| [`me_pool_min_fresh_ratio`](#me_pool_min_fresh_ratio) | `f32` | `0.8` | `✔` |
| [`me_reinit_drain_timeout_secs`](#me_reinit_drain_timeout_secs) | `u64` | `90` | `✔` |
| [`proxy_secret_auto_reload_secs`](#proxy_secret_auto_reload_secs) | `u64` | `3600` | `✔` |
| [`proxy_config_auto_reload_secs`](#proxy_config_auto_reload_secs) | `u64` | `3600` | `✔` |
| [`me_reinit_singleflight`](#me_reinit_singleflight) | `bool` | `true` | `✔` |
| [`me_reinit_max_concurrency`](#me_reinit_max_concurrency) | `usize` | `2` | `✔` |
| [`me_reinit_trigger_channel`](#me_reinit_trigger_channel) | `usize` | `64` | `✘` |
| [`me_reinit_coalesce_window_ms`](#me_reinit_coalesce_window_ms) | `u64` | `200` | `✔` |
| [`me_deterministic_writer_sort`](#me_deterministic_writer_sort) | `bool` | `true` | `✔` |
@@ -266,6 +349,8 @@
[general]
config_strict = true
```
- **Известное ограничение**: В этой ревизии `config_strict = true` отклоняет иначе поддерживаемые ключи `access.user_source_deny` и `[[upstreams]].prefer`. Оставляйте strict mode выключенным, если используется любой из них.
## prefer_ipv6
- **Ограничения / валидация**: Устарело. Используйте `network.prefer`.
- **Описание**: Устаревший флаг предпочтения IPv6 перенесен в `network.prefer`.
@@ -402,8 +487,8 @@
stun_nat_probe_concurrency = 8
```
## middle_proxy_pool_size
- **Ограничения / валидация**: `usize`.
- **Описание**: Размер пула записи ME.
- **Ограничения / валидация**: `usize`. Перед передачей в ME initialization значение нормализуется как `max(value, 1)`.
- **Описание**: Не влияющий на enforcement compatibility input, который сейчас выводится в ME initialization log. Active writer targets определяет DC-family floor policy, а не это значение.
- **Пример**:
```toml
@@ -494,7 +579,7 @@
rpc_proxy_req_every = 0
```
## me_writer_cmd_channel_capacity
- **Ограничения / валидация**: Должно быть `> 0`.
- **Ограничения / валидация**: Должно быть в пределах `1..=16384`.
- **Описание**: Ёмкость (размер) канала команд для каждого отправителя.
- **Пример**:
@@ -502,8 +587,17 @@
[general]
me_writer_cmd_channel_capacity = 4096
```
## me_writer_byte_budget_bytes
- **Ограничения / валидация**: Должно быть кратно `16384` и находиться между динамическим минимумом и `268435456`. Минимум равен `2 * general.max_client_frame + 256` с округлением вверх до `16384`; при стандартном размере frame он равен `33570816`.
- **Описание**: Бюджет резидентной памяти для очереди данных каждого ME writer. File watcher не пересоздаёт существующие writer для этого поля; значение применяется при построении нового поколения ME/runtime через API либо после перезапуска.
- **Пример**:
```toml
[general]
me_writer_byte_budget_bytes = 33570816
```
## me_route_channel_capacity
- **Ограничения / валидация**: Должно быть `> 0`.
- **Ограничения / валидация**: Должно быть в пределах `1..=8192`.
- **Описание**: Количество ответов от ME, которое может одновременно находиться “в пути” или в очереди для одного соединения.
- **Пример**:
@@ -512,7 +606,7 @@
me_route_channel_capacity = 768
```
## me_c2me_channel_capacity
- **Ограничения / валидация**: Должно быть `> 0`.
- **Ограничения / валидация**: Должно быть в пределах `1..=8192`.
- **Описание**: Емкость очереди команд для каждого клиента (client reader -> ME sender).
- **Пример**:
@@ -610,6 +704,15 @@
[general]
direct_relay_copy_buf_s2c_bytes = 262144
```
## direct_relay_buffer_budget_max_bytes
- **Ограничения / валидация**: `0` либо значение, кратное `4096`, в диапазоне `16777216..=2147483648`.
- **Описание**: Process-wide жёсткий предел памяти Direct relay copy buffers; `0` вычисляет его при запуске по ограничениям памяти cgroup/хоста. Изменение откладывается до перезапуска процесса.
- **Пример**:
```toml
[general]
direct_relay_buffer_budget_max_bytes = 0
```
## crypto_pending_buffer
- **Ограничения / валидация**: `usize` (байт).
- **Описание**:Максимальный объём ожидающих (неотправленных) зашифрованных данных в буфере client writer (в байтах).
@@ -620,7 +723,7 @@
crypto_pending_buffer = 262144
```
## max_client_frame
- **Ограничения / валидация**: `usize` (байт).
- **Ограничения / валидация**: Должно быть в пределах `4096..=16777216` (байт).
- **Описание**: Максимально допустимый размер кадра MTProto клиента (в байтах).
- **Пример**:
@@ -710,7 +813,7 @@
me_warmup_step_jitter_ms = 300
```
## me_reconnect_max_concurrent_per_dc
- **Ограничения / валидация**: `u32`.
- **Ограничения / валидация**: `u32`. Runtime использует эффективное значение `max(value, 1)`, поэтому `0` работает как `1`.
- **Описание**: Ограничить количество одновременно работающих процессов переподключения (reconnect workers) к DC во время восстановления работоспособности.
- **Пример**:
@@ -737,7 +840,7 @@
me_reconnect_backoff_cap_ms = 30000
```
## me_reconnect_fast_retry_count
- **Ограничения / валидация**: `u32`.
- **Ограничения / валидация**: `u32`. Runtime использует эффективное значение `max(value, 1)`, поэтому `0` работает как `1`.
- **Описание**: Лимит немедленных повторных попыток подключения перед тем, как включается долгий backoff (увеличивающаяся задержка между попытками).
- **Пример**:
@@ -1133,7 +1236,7 @@
me_route_hybrid_max_wait_ms = 3000
```
## me_route_blocking_send_timeout_ms
- **Ограничения / валидация**: Должно быть в пределах `0..=5000` (миллисекунд). `0` - неограниченное время ожидания.
- **Ограничения / валидация**: Должно быть в пределах `1..=5000` (миллисекунд).
- **Описание**: Максимальное время ожидания для блокировки отправки через канал маршрутизации при fallback.
- **Пример**:
@@ -1316,7 +1419,7 @@
```
## me_pool_drain_ttl_secs
- **Ограничения / валидация**: `u64` (секунды). `0` - отключает период drain-TTL и подавляет предупреждения drain-TTL для ненулевых (непустых) writer’ов, находящихся в состоянии **draining**.
- **Описание**: Временной интервал Drain-TTL для устаревших ME writer’ов после изменения карты endpoint’ов. В течение TTL устаревшие writer’ы могут использоваться только как fallback для новых биндов (в зависимости от политики биндов).
- **Описание**: Возрастной порог предупреждений о долгом drain после изменения endpoint map и нижняя граница нормализации force-close timeout. Разрешение stale binds отдельно задают `me_bind_stale_mode` и `me_bind_stale_ttl_secs`.
- **Пример**:
```toml
@@ -1396,7 +1499,7 @@
```
## me_bind_stale_mode
- **Ограничения / валидация**: `"never"`, `"ttl"` или `"always"`.
- **Описание**: Политика разрешения новых биндов к устаревшим writer’ам.
- **Описание**: Политика новых binds на stale draining writers в непокрытых DC-family groups. Значение по умолчанию `never` требует полного покрытия groups перед частичным hardswap commit; `ttl` и `always` разрешают ограниченный policy fallback.
- **Пример**:
```toml
@@ -1406,7 +1509,7 @@
```
## me_bind_stale_ttl_secs
- **Ограничения / валидация**: `u64`.
- **Описание**: TTL для разрешения биндов к устаревшим writer’ам при режиме `ttl`.
- **Описание**: TTL для разрешения binds к stale writers в режиме `ttl`; `0` отключает TTL expiry для разрешённых draining writers.
- **Пример**:
```toml
@@ -1416,7 +1519,7 @@
```
## me_pool_min_fresh_ratio
- **Ограничения / валидация**: Должно быть в пределах `[0.0, 1.0]`.
- **Описание**: Минимальный коэффициент актуального (fresh) покрытия DC перед началом удаления устаревших writer’ов.
- **Описание**: Минимальная доля fresh DC-family coverage при generation commit. При `me_bind_stale_mode = "never"` отсутствующие groups блокируют commit, даже если эта доля достигнута.
- **Пример**:
```toml
@@ -1425,8 +1528,8 @@
me_pool_min_fresh_ratio = 0.9
```
## me_reinit_drain_timeout_secs
- **Ограничения / валидация**: `u64`. `0` - используется безопасный системный fallback. Если значение `> 0` и `< me_pool_drain_ttl_secs`, повышает его до значения TTL.
- **Описание**: Таймаут принудительного закрытия устаревших writer’ов при очистке/повторной инициализации. При `0` используется безопасный системный fallback (300 секунд).
- **Ограничения / валидация**: `u64`. `0` сначала выбирает runtime safety fallback 300 секунд; затем effective timeout повышается как минимум до `me_pool_drain_ttl_secs`.
- **Описание**: Таймаут принудительного закрытия draining stale writers. Effective value равен максимуму из заданного ненулевого значения (или 300 секунд при `0`) и drain TTL.
- **Пример**:
```toml
@@ -1467,9 +1570,18 @@
[general]
me_reinit_singleflight = true
```
## me_reinit_max_concurrency
- **Ограничения / валидация**: Должно быть в пределах `[1, 8]`. Эффективное значение равно `1`, пока `me_reinit_singleflight = true`.
- **Описание**: Ограничивает число одновременных прогревов поколений ME; лишние триггеры объединяются в один ожидающий повторный запуск.
- **Пример**:
```toml
[general]
me_reinit_max_concurrency = 2
```
## me_reinit_trigger_channel
- **Ограничения / валидация**: Должно быть `> 0`.
- **Описание**: Емкость очереди триггеров для планировщика повторной инициализации.
- **Ограничения / валидация**: Должно быть в пределах `[1, 4096]`.
- **Описание**: Ёмкость очереди triggers для reinit scheduler. Новая runtime generation создаёт канал из этого значения; один file watcher не изменяет размер активного канала.
- **Пример**:
```toml
@@ -2487,6 +2599,8 @@ WEB-режим переносит MTProxy-трафик Telegram Desktop внут
| `carriers` | `false` или непустой массив уникальных carrier | `false` | `✔` |
| `carrier_learning` | `bool` | `true` | `✔` |
| `carrier_negotiation_aggressiveness` | `"conservative"`, `"balanced"` или `"aggressive"` | `"conservative"` | `✔` |
| `decoy_fasttrack_mode` | `"off"`, `"shadow"` или `"enforce"` | `"off"` | `✘` |
| `http_connection_capacity_action` | `"drop"`, `"wait"` или `"respond"` | `"drop"` | `✔` |
| `debug` | таблица | выключено, ограниченные defaults | `✔` |
| `limits` | таблица | ограниченные defaults | `✘` |
| `timeouts` | таблица | ограниченные defaults | `✔` |
@@ -2496,6 +2610,10 @@ WEB-режим переносит MTProxy-трафик Telegram Desktop внут
Если `carriers` отсутствует или равен `false`, auto-negotiation и обучение выключены, а `carrier` задаёт единственный режим. Непустой массив `carriers` включает стартовый перебор в заданном порядке; `carrier` ровно один раз добавляется последним fallback-вариантом. Пустой массив, дубликаты и `true` запрещены. Клиент может перейти к следующему кандидату только до commit carrier; для смены carrier после commit нужна новая сессия. Native-клиент без метаданных, включая Telegram iOS, всегда использует настроенный фиксированный `carrier`, даже при включённом auto-negotiation. Текущий iOS поддерживает только `https`, поэтому такой deployment должен задавать `carrier = "https"`. Классификация User-Agent CFNetwork и Darwin не определяет поддержку carrier. Явные capabilities нативного iOS пересекаются с `{https}`; capabilities остальных явных клиентов применяются как переданы.
`http_connection_capacity_action` применяется только после того, как Telemt принял приватное WEB TCP connection и исчерпал `max_http_connections`. `drop` сохраняет немедленное закрытие. `respond` отправляет пустой повторяемый `503 Service Unavailable` с `Retry-After: 1`, `Cache-Control: no-store` и `Connection: close`. `wait` ожидает обычную capacity не более `http_overload_timeout_ms`, затем переходит к нормальной HTTP-обработке; по timeout отправляется тот же ограниченный `503`. Вне обычной capacity могут ожидать или отвечать не более `max_http_overload_connections` принятых sockets.
`decoy_fasttrack_mode` требует перезапуска и управляет только capability work для `GET/HEAD` на настроенном base root. `off` сохраняет полный scan, `shadow` считает подходящие requests, но не пропускает scan, а `enforce` пропускает его только для `HEAD` или отсутствующего/неканонического параметра `bridge`. Канонический bridge-shaped `GET` всегда сканирует все профили выбранного vhost. Оптимизация не ограничивает враждебные канонические probes; `enforce` необходимо проверять на различимость timing за production TLS-терминатором.
`carrier_learning` действует только при включённом auto-negotiation. Обучение локально для процесса, хранится в памяти, ограничено и учитывает только положительный результат: evidence добавляет лишь carrier, достигший определённого сервером состояния healthy. `conservative` требует наиболее широкой выборки и отключает ранжирование по IP, `balanced` использует умеренные пороги для User-Agent/профиля и допустимый публичный IP только для разрешения равенства, а `aggressive` реагирует на первые ограниченные samples. Сообщённые клиентом ошибки остаются только диагностикой и не создают отрицательный evidence. Reload применяет новую policy к новым цепочкам negotiation и инвалидирует несовместимый сохранённый evidence. Отключение WEB прекращает выдачу новых bridge- и session-credentials; для отзыва активных сессий отдельного пользователя используйте users API.
# [web.debug]
@@ -2506,6 +2624,7 @@ WEB-режим переносит MTProxy-трафик Telegram Desktop внут
| --- | --- | --- | --- |
| `enabled` | `bool` | `false` | Включает WEB HTTP, WebSocket-message, frame и lifecycle debug records. |
| `capture_lifecycle` | `bool` | `true` | Записывает типизированные события bridge, session, stream, handshake, relay и close. |
| `sideband` | `bool` | `false` | Включает lifecycle diagnostics из сгенерированного bridge; действует только вместе с `enabled` и `capture_lifecycle`. |
| `capture_headers` | `bool` | `true` | Сохраняет имена headers и только разрешённые значения без credentials. |
| `capture_timings` | `bool` | `true` | Сохраняет timing points для request body, готового response, response body и обработки WebSocket messages. |
| `capture_frames` | `bool` | `true` | Разбирает bounded carrier bodies в тип frame, stream ID, длину, WINDOW и метаданные ошибок, не сохраняя frame payload отдельно. |
@@ -2517,6 +2636,8 @@ WEB-режим переносит MTProxy-трафик Telegram Desktop внут
Изменение `enabled` или любого поля capture очищает сохранённые записи и отклоняет commits, начатые в предыдущую policy epoch. Изменение только стандартного или максимального окна наблюдения сохраняет совместимые записи. `full` сохраняет полное тело распознанного carrier только до `web.limits.max_body_bytes`; decoy bodies всегда остаются ограничены настроенным prefix. Prefix, который помещается только в одновременно увеличенную restart-only ёмкость, откладывается вместе с `web.debug` до перезапуска. URI queries никогда не сохраняются, значения credential headers исключаются, копии body очищаются от известных WEB capabilities и bearer tokens, а ключи профилей представлены только domain-separated fingerprint из 16 hex-символов.
Когда `enabled`, `sideband` и `capture_lifecycle` одновременно включены, новые сгенерированные bridge pages отправляют ограниченные одноразовые lifecycle events по точному настроенному base плюс `api/v1/diagnostic`. Это внутренний route Telemt, а не публичный Control API. Уже выданные bridge documents не получают sideband после reload.
Аутентифицированное JSON-управление может явно очистить ring через `POST /v1/runtime/web/debug/clear`: обязательный process `runtime_instance` защищает от устаревшего controller, возвращаемый epoch отсекает in-flight writers, а `leased_bytes` показывает память, всё ещё удерживаемую уже отрисовываемыми snapshots.
# [web.limits]
@@ -2531,6 +2652,7 @@ WEB-режим переносит MTProxy-трафик Telegram Desktop внут
| `carrier_batch_bytes` | `usize` | `2097152` | Максимальный закодированный downlink batch. |
| `max_frames_per_body` | `usize` | `4096` | Максимальное число frames в одном carrier body. |
| `max_http_connections` | `usize` | `1024` | Принятые WEB HTTP connections на весь процесс. |
| `max_http_overload_connections` | `usize` | `64` | Принятые перегруженные sockets, которым разрешено ожидать или отправить ограниченный повторяемый ответ вне обычной HTTP capacity. |
| `max_http_handlers` | `usize` | `512` | Одновременно выполняемые HTTP handlers на весь процесс; HTTPS lanes могут занять long polls не более половины лимита, оставляя остаток для session, uplink и control work. |
| `max_lane_open_waits_per_session` | `usize` | `16` | Канонические downlink polls с cursor zero, которые могут ожидать конкурирующий lane `OPEN` в одной сессии. |
| `pending_bytes_per_lane` | `usize` | `8388608` | Байты queued и resident `DATA`, разрешённые одной независимой HTTPS- или WebSocket-lane. |
@@ -2585,6 +2707,7 @@ WEB-режим переносит MTProxy-трафик Telegram Desktop внут
| `long_poll_secs` | `u64` | `25` | `✔` | Максимальная длительность пустого downlink long poll. |
| `bridge_request_secs` | `u64` | `10` | `✔` | Deadline одной HTTP attempt в bridge до полного чтения response body; для `/down` дополнительно разрешён `long_poll_secs`. Диапазон `1..=60`. |
| `bridge_retry_secs` | `u64` | `90` | `✔` | Абсолютное окно повторов bridge, включая attempts и backoff; диапазон `1..=300`, не меньше `bridge_request_secs`. |
| `bridge_recovery_secs` | `u64` | `15` | `✔` | Абсолютное окно recovery после commit для сохранившегося bridge document; диапазон `1..=60`, фиксируется при начале recovery. |
| `carrier_probe_coalesce_ms` | `u64` | `0` | `✔` | Опциональное ожидание bridge после `OPEN` для соответствующего `DATA`; миллисекунды в диапазоне `0..=10`, где `0` сохраняет немедленный probe. |
| `lane_open_wait_secs` | `u64` | `2` | `✔` | Ожидание канонического downlink с cursor zero, опередившего свой lane `OPEN`; не больше `long_poll_secs`. |
| `carrier_health_secs` | `u64` | `30` | `✔` | Интервал наблюдения после commit, необходимый для добавления carrier-learning evidence. |
@@ -2598,6 +2721,7 @@ WEB-режим переносит MTProxy-трафик Telegram Desktop внут
| `bootstrap_lifetime_secs` | `u64` | `120` | `✔` | Срок неиспользованного bootstrap и replay-marker закрытого token. |
| `reconnect_grace_secs` | `u64` | `120` | `✔` | Максимальная неактивность carrier до закрытия сессии. |
| `http_idle_secs` | `u64` | `75` | `✔` | Лимит простоя между HTTP-обменами и при отсутствии прогресса уже выданного response body. Явно ограниченные фазы request body, long poll, decoy и ожидания Upgrade сохраняют собственные deadlines и не обрываются этим таймером. Значение фиксируется при приёме connection. |
| `http_overload_timeout_ms` | `u64` | `250` | `✔` | Deadline каждой фазы в миллисекундах для ожидания capacity или записи повторяемого ответа после принятия перегруженного socket; диапазон `1..=60000`. Timeout ожидания и запись ответа получают не более одного бюджета фазы каждый. |
| `shutdown_secs` | `u64` | `15` | `✔` | Один абсолютный бюджет завершения процесса, общий для всех listener acceptors и connections, а также для WEB sessions и auxiliary tasks. Активное значение фиксируется один раз при начале shutdown. |
| `decoy_header_secs` | `u64` | `30` | `✔` | Deadline подключения и получения response head от HTTP decoy. |
@@ -2606,11 +2730,12 @@ WEB-режим переносит MTProxy-трафик Telegram Desktop внут
| Ключ | Тип | Обязательный | Hot-Reload | Описание |
| --- | --- | --- | --- | --- |
| `host` | `String` | да | `✔` | Уникальный канонический lowercase ACE FQDN без порта, пути, credentials и завершающей точки. |
| `base_path` | `String` | нет | `✔` | Точный регистрозависимый WEB-prefix без начального и завершающего слеша; по умолчанию пуст. Не более 128 ASCII-байт в разделённых слешами сегментах `[A-Za-z0-9][A-Za-z0-9_-]*`. |
| `public_addr` | `SocketAddr` | да | `✔` | Конкретный публичный IP на порту `443`, используемый во внутреннем destination tuple relay. |
| `decoy` | таблица | да | `✔` | Обычный сайт для неаутентифицированного или некорректного трафика. |
| `profiles` | массив таблиц | при включённом WEB | `✔` | Явные пользователи и client secret modes для этого hostname. |
Hostname нормализуется при валидации и должен приниматься Telegram Desktop. Bootstrap является bearer credential: адрес клиента и его IP-семейство могут измениться до создания session. Неиспользованный bootstrap остаётся действительным после reload конфигурации, только пока активен профиль с той же identity.
Hostname нормализуется при валидации и должен приниматься Telegram Desktop. Пустой `base_path` сохраняет root-capability v1 и прежний шестнадцатеричный secret ссылки. Непустой путь использует capability v2 по host/path и Telegram Desktop path-ссылку с percent-encoded `HOST/BASE` и base64url-маркером secret `0x70`. Маршрутизация требует точного prefix с завершающим слешем и никогда не перенаправляет, не нормализует и не удаляет его. Bootstrap является bearer credential: адрес клиента и его IP-семейство могут измениться до создания session. Неиспользованный bootstrap остаётся действительным после reload конфигурации, только пока активен профиль с той же identity.
# [web.vhosts.decoy]
@@ -2636,6 +2761,7 @@ Hostname нормализуется при валидации и должен п
## Lifecycle WEB и управление через API
- Config watcher и generation reload применяют `web.enabled`, policy carrier/negotiation, `web.debug`, `web.timeouts`, vhosts, profiles и decoy snapshots без перезапуска процесса. Валидируется и активируется один immutable expanded source snapshot; watcher candidate generation запускается только после активации этого поколения. Существующие сессии и начатые negotiation chains сохраняют issuance-time carrier candidates, limits, timeouts и абсолютные deadlines; новые bridge sessions используют одно зафиксированное активное поколение.
- Изменение `base_path` атомарно заменяет и маршрут новых запросов, и производную capability. Сначала выпустите новые ссылки и завершите затронутые активные sessions: установленные WebSockets и уже маршрутизированные обмены продолжаются; последующие запросы к старому base с подлинным для процесса bootstrap- или session-token получают локальный no-store `404`, а ставшая неактивной прежняя capability обрабатывается как обычный decoy traffic.
- Состав WEB-listeners и их trust policy в `server.listeners`, а также все значения `web.limits` принадлежат процессу и требуют перезапуска.
- `GET /v1/config` возвращает полное авторское дерево `[web]`, кроме производного snapshot `web.runtime`. `PATCH /v1/config` принимает sparse object `web`, глубоко сливает tables, целиком заменяет arrays, валидирует полный candidate и указывает `web.limits` в `deferred_process_fields` до перезапуска.
- `GET /v1/runtime/web/status`, `/sessions`, `/sessions/{session_ref}` и `/operations/{operation_id}` предоставляют bounded несекретное runtime-состояние. POST controls закрывают выбранные сессии, очищают debug или сбрасывают carrier learning и требуют текущий случайный `runtime_instance`.
@@ -2763,8 +2889,10 @@ Hostname нормализуется при валидации и должен п
| [`tls_fetch_scope`](#tls_fetch_scope) | `String` | `""` | `✘` |
| [`tls_fetch`](#tls_fetch) | `Table` | built-in defaults | `✘` |
| [`mask`](#mask) | `bool` | `true` | `✘` |
| [`mask_dynamic`](#mask_dynamic) | `bool` | `true` | `✘` |
| [`mask_host`](#mask_host) | `String` | — | `✘` |
| [`mask_port`](#mask_port) | `u16` | `443` | `✘` |
| [`exclusive_mask`](#exclusive_mask) | `Map<String, String>` | `{}` | `✘` |
| [`mask_unix_sock`](#mask_unix_sock) | `String` | — | `✘` |
| [`fake_cert_len`](#fake_cert_len) | `usize` | `2048` | `✘` |
| [`tls_emulation`](#tls_emulation) | `bool` | `true` | `✘` |
@@ -2783,8 +2911,8 @@ Hostname нормализуется при валидации и должен п
| [`mask_shape_above_cap_blur`](#mask_shape_above_cap_blur) | `bool` | `false` | `✘` |
| [`mask_shape_above_cap_blur_max_bytes`](#mask_shape_above_cap_blur_max_bytes) | `usize` | `512` | `✘` |
| [`mask_relay_max_bytes`](#mask_relay_max_bytes) | `usize` | `5242880` | `✘` |
| [`mask_relay_timeout_ms`](mask_relay_timeout_ms) | `u64` | `60_000` | `✘` |
| [`mask_relay_idle_timeout_ms`](mask_relay_idle_timeout_ms) | `u64` | `5_000` | `✘` |
| [`mask_relay_timeout_ms`](#mask_relay_timeout_ms) | `u64` | `60_000` | `✘` |
| [`mask_relay_idle_timeout_ms`](#mask_relay_idle_timeout_ms) | `u64` | `5_000` | `✘` |
| [`mask_classifier_prefetch_timeout_ms`](#mask_classifier_prefetch_timeout_ms) | `u64` | `5` | `✘` |
| [`mask_timing_normalization_enabled`](#mask_timing_normalization_enabled) | `bool` | `false` | `✘` |
| [`mask_timing_normalization_floor_ms`](#mask_timing_normalization_floor_ms) | `u64` | `0` | `✘` |
@@ -2831,9 +2959,9 @@ Hostname нормализуется при валидации и должен п
[censorship]
tls_fetch_scope = "fetch"
```
# censorship.tls_fetch
## tls_fetch
- **Ограничения / валидация**: Таблица, см. секцию `[censorship.tls_fetch]` ниже.
- **Описание**: Настройки стратегии получения TLS-front метаданных (поведение загрузки и обновления bootstrap и данных эмуляции TLS)..
- **Описание**: Настройки стратегии получения TLS-front метаданных (поведение загрузки и обновления bootstrap и данных эмуляции TLS).
- **Пример**:
```toml
@@ -2844,18 +2972,27 @@ Hostname нормализуется при валидации и должен п
```
## mask
- **Ограничения / валидация**: `bool`.
- **Описание**: Включает режим маскировки/верхнего уровня. Принимаются все SNI, которые похожи на заданный в `tls_domain`.
- **Описание**: Включает режим masking/fronting relay.
- **Пример**:
```toml
[censorship]
mask = true
```
## mask_dynamic
- **Ограничения / валидация**: `bool`.
- **Описание**: Когда не заданы ни `mask_host`, ни `mask_unix_sock`, совпадающий с `tls_domain`/`tls_domains` SNI из ClientHello используется как TCP mask target; при отсутствии совпадения применяется основной `tls_domain`. Совпавший `exclusive_mask` всегда имеет приоритет над обычными целями.
- **Пример**:
```toml
[censorship]
mask_dynamic = true
```
## mask_host
- **Ограничения / валидация**: `String` (необязательный параметр).
- Если задан параметр `mask_unix_sock`, `mask_host` не должен быть задан.
- Если не задан параметр `mask_host` и `mask_unix_sock` не задан, Telemt по умолчанию устанавливает для `mask_host` значение `tls_domain`.
- **Описание**: Хост, используемый для маскировки при TLS-fronting.
- Если не заданы ни `mask_host`, ни `mask_unix_sock`, `mask_dynamic` может выбрать совпадающий настроенный SNI; иначе Telemt использует `tls_domain`.
- **Описание**: Явный upstream host для TLS-fronting relay. Если он задан, dynamic SNI target selection отключён, кроме переопределений `exclusive_mask`.
- **Пример**:
```toml
@@ -3303,6 +3440,7 @@ Hostname нормализуется при валидации и должен п
| Ключ | Тип | По умолчанию | Hot-Reload |
| --- | ---- | ------- | ---------- |
| [`users`](#users) | `Map<String, String>` | `{"default": "000…000"}` | `✔` |
| [`user_enabled`](#user_enabled-1) | `Map<String, bool>` | `{}` | `✔` |
| [`user_ad_tags`](#user_ad_tags) | `Map<String, String>` | `{}` | `✔` |
| [`user_max_tcp_conns`](#user_max_tcp_conns) | `Map<String, usize>` | `{}` | `✔` |
| [`user_max_tcp_conns_global_each`](#user_max_tcp_conns_global_each) | `usize` | `0` | `✔` |
@@ -3329,6 +3467,16 @@ Hostname нормализуется при валидации и должен п
alice = "00112233445566778899aabbccddeeff"
bob = "0123456789abcdef0123456789abcdef"
```
## user_enabled
- **Ограничения / валидация**: `Map<String, bool>`.
- **Описание**: Необязательные per-user overrides. Пользователь без записи включён. `false` запрещает новые sessions; `true` допустим, но эквивалентен удалению override. API enable удаляет override, а disable записывает `false`.
- **Runtime-поведение**: Hot reload применяет карту немедленно. После успешной аутентификации отключённому пользователю отказывают, а его активные runtime sessions отменяются.
- **Пример**:
```toml
[access.user_enabled]
alice = false
```
## user_ad_tags
- **Ограничения / валидация**: Каждое значение должно содержать **ровно 32 шестнадцатеричных символа** (тот же формат, что и в `general.ad_tag`). Тег со всеми нулями разрешен, но в логи будет записано предупреждение.
- **Описание**: Переопределение рекламного тега спонсируемого канала для каждого пользователя. Когда у пользователя есть запись здесь, она имеет приоритет над `general.ad_tag`.
@@ -3360,8 +3508,9 @@ Hostname нормализуется при валидации и должен п
user_max_tcp_conns_global_each = 200
[access.user_max_tcp_conns]
alice = 500 # uses 500, not the global cap
# bob has no entry > uses 200
# Alice uses 500 rather than the global cap.
alice = 500
# Bob has no entry and therefore uses 200.
```
## user_expirations
- **Ограничения / валидация**: `Map<String, DateTime<Utc>>`. Каждое значение должно быть валидной датой и временем в формате RFC3339/ISO-8601.
@@ -3379,7 +3528,8 @@ Hostname нормализуется при валидации и должен п
```toml
[access.user_data_quota]
alice = 1073741824 # 1 GiB
# Alice receives a 1 GiB quota.
alice = 1073741824
```
## user_max_unique_ips
- **Ограничения / валидация**: `Map<String, usize>`.
@@ -3461,7 +3611,7 @@ Hostname нормализуется при валидации и должен п
## user_rate_limits
- **Ограничения / валидация**: Таблица `username -> { up_bps, down_bps }`. Должно быть ненулевое значение хотя бы в одном направлении.
- **Ограничения / валидация**: Таблица `username -> { up_bps, down_bps }`. Каждое направление должно быть в диапазоне `0..=100000000000`; `0` означает отсутствие лимита в этом направлении, при этом хотя бы одно направление должно быть ненулевым.
- **Описание**: Персональные лимиты скорости по пользователям в битах/сек для отправки (`up_bps`) и получения (`down_bps`).
- **Example**:
@@ -3470,7 +3620,7 @@ Hostname нормализуется при валидации и должен п
alice = { up_bps = 1048576, down_bps = 2097152 }
```
## cidr_rate_limits
- **Ограничения / валидация**: Таблица `CIDR или auto-template -> { up_bps, down_bps }`. Explicit CIDR-ключи должны корректно разбираться как `IpNetwork`; auto-template ключи должны иметь вид `*4/N` (`N=0..32`), `*6/N` (`N=0..128`) или `*/N` (`N=0..32`). Хотя бы одно направление должно быть ненулевым. Дублирующиеся нормализованные auto-template отклоняются.
- **Ограничения / валидация**: Таблица `CIDR или auto-template -> { up_bps, down_bps }`. Каждое направление должно быть в диапазоне `0..=100000000000`; `0` означает отсутствие лимита в этом направлении, при этом хотя бы одно направление должно быть ненулевым. Explicit CIDR-ключи должны корректно разбираться как `IpNetwork`; auto-template ключи должны иметь вид `*4/N` (`N=0..32`), `*6/N` (`N=0..128`) или `*/N` (`N=0..32`). Дублирующиеся нормализованные auto-template отклоняются.
- **Описание**: Лимиты скорости для подсетей источников, применяются поверх пользовательских ограничений. Explicit CIDR-правила используют longest-prefix-wins и имеют приоритет над auto-template. Auto-template создают bucket’ы лениво по matched source subnet: `*4/N` для IPv4, `*6/N` для IPv6, а `*/N` является dual-stack shorthand, где IPv4 использует `/N`, а IPv6 — `/(N * 4)`.
- **Example**:
@@ -3599,7 +3749,8 @@ Hostname нормализуется при валидации и должен п
[[upstreams]]
type = "socks5"
address = "203.0.113.10:1080"
interface = "192.0.2.10" # explicit local bind IP
# Use an explicit local bind IP.
interface = "192.0.2.10"
```
## bind_addresses
- **Ограничения / валидация**: `String[]` (необязательный параметр). Применяется в случае, если `type = "direct"`.