mirror of
https://github.com/telemt/telemt.git
synced 2026-11-22 07:16:38 +03:00
@@ -1,5 +1,10 @@
|
||||
# High-Load Configuration & Tuning Guide
|
||||
When deploying Telemt under high-traffic load (tens or hundreds of thousands of concurrent connections), the standard OS network stack limits can lead to packet drops, high CPU context switching, and connection failures. This guide covers Linux kernel tuning, hardware configuration, and architecture optimizations required to prepare the server for high-load scenarios.
|
||||
|
||||
[English](HIGH_LOAD.en.md) · [Русский](HIGH_LOAD.ru.md) · [Deutsch](HIGH_LOAD.de.md)
|
||||
|
||||
Use this guide when measured load exposes a specific resource limit. The values below are example capacities, not a tested guarantee of a particular connection count. Record the kernel version, active configuration, connection rate, memory use and latency before changing a setting. Save the previous values and change one group at a time so you can compare and revert it.
|
||||
|
||||
For terminology, see the [shared glossary](../TERMINOLOGY.md).
|
||||
|
||||
---
|
||||
## 1. System Limits & File Descriptors
|
||||
@@ -51,45 +56,57 @@ net.ipv4.tcp_max_syn_backlog = 65535
|
||||
net.ipv4.tcp_syncookies = 1
|
||||
```
|
||||
### 2.2 Port Exhaustion & TIME-WAIT Sockets
|
||||
High churn rates lead to ephemeral port exhaustion. Expand the range and rapidly recycle closed sockets:
|
||||
First distinguish failed outbound connects caused by exhausted source ports from a large but harmless TIME-WAIT population. Inspect the failing error, destination tuples and `ss -s`. Expanding the ephemeral range can help when this is the limiting resource; account for ports reserved by other services:
|
||||
|
||||
```ini
|
||||
net.ipv4.ip_local_port_range = 10000 65535
|
||||
net.ipv4.tcp_fin_timeout = 15
|
||||
net.ipv4.tcp_tw_reuse = 1
|
||||
net.ipv4.tcp_max_tw_buckets = 2000000
|
||||
```
|
||||
### 2.3 TCP Keepalive (Aggressive Dead Connection Culling)
|
||||
By default, Linux keeps silent, dropped connections open for over 2 hours. This consumes memory at scale. The values below start probing after five idle minutes and abandon an unresponsive peer after the subsequent probe budget, roughly 7–8 minutes after it became idle:
|
||||
|
||||
`tcp_tw_reuse` controls reuse of TIME-WAIT sockets when the protocol permits it. In the referenced kernel documentation, `0` disables it, `1` enables it globally and `2` limits it to loopback; inspect your running kernel's current value before changing it. `tcp_max_tw_buckets` limits retained TIME-WAIT entries, not the duration of TIME-WAIT.
|
||||
|
||||
`tcp_fin_timeout` applies to orphaned connections in `FIN_WAIT_2`; reducing it does not shorten `TIME_WAIT`. Keep these mechanisms separate when investigating port exhaustion. See the [Linux IP sysctl reference](https://docs.kernel.org/networking/ip-sysctl.html).
|
||||
|
||||
### 2.3 TCP Keepalive
|
||||
These sysctls are defaults for sockets with TCP keepalive enabled that do not override the corresponding options. They start probing after five idle minutes and exhaust the subsequent probe budget after roughly 7–8 minutes of total inactivity:
|
||||
|
||||
```ini
|
||||
net.ipv4.tcp_keepalive_time = 300
|
||||
net.ipv4.tcp_keepalive_intvl = 30
|
||||
net.ipv4.tcp_keepalive_probes = 5
|
||||
```
|
||||
|
||||
Telemt overrides keepalive time and interval on client sockets using `timeouts.client_keepalive` (default 15 seconds). On Linux its ME sockets use 30 seconds idle, a 10-second interval and 3 probes. These are TCP socket settings; ME RPC Ping/Pong, `timeouts.client_ack` and relay idle policies impose separate checks. The sysctl example therefore does not define the lifetime of every Telemt connection. Verify the relevant socket and configured application timeout.
|
||||
|
||||
### 2.4 TCP Buffers & Congestion Control
|
||||
Optimize memory usage per socket and switch to BBR (Bottleneck Bandwidth and Round-trip propagation time) to improve latency on lossy networks:
|
||||
Measure memory pressure, throughput and p95/p99 latency with the same workload before and after changing buffers. The maximum below is a ceiling for an eligible socket, not a fixed allocation for every connection. Telemt also sets socket buffer sizes explicitly, so kernel defaults alone do not describe its effective buffers.
|
||||
|
||||
```ini
|
||||
# Core buffer sizes
|
||||
# Example buffer ceilings: size them for the available memory and workload.
|
||||
net.core.rmem_default = 262144
|
||||
net.core.wmem_default = 262144
|
||||
net.core.rmem_max = 16777216
|
||||
net.core.wmem_max = 16777216
|
||||
# TCP-specific buffers (min, default, max)
|
||||
net.ipv4.tcp_rmem = 4096 87380 16777216
|
||||
net.ipv4.tcp_wmem = 4096 65536 16777216
|
||||
# Enable BBR
|
||||
```
|
||||
|
||||
Check available congestion-control algorithms with `sysctl net.ipv4.tcp_available_congestion_control`. If BBR is supported, evaluate it against the current algorithm under representative RTT, loss and load; this guide does not establish that it always improves latency. An example BBR configuration is:
|
||||
|
||||
```ini
|
||||
net.core.default_qdisc = fq
|
||||
net.ipv4.tcp_congestion_control = bbr
|
||||
```
|
||||
|
||||
|
||||
---
|
||||
## 3. Conntrack (Netfilter) Tuning
|
||||
If your server uses `iptables`, `ufw`, or `firewalld`, the Linux kernel tracks every connection state in a table (`nf_conntrack`). When this table fills up, Linux drops new packets.
|
||||
Stateful firewall and NAT rules can use `nf_conntrack` to track connections. Check whether tracking is active on the relevant route, especially with NOTRACK rules. Exhausting the conntrack table can cause new packets to be dropped.
|
||||
Check your current limit and usage:
|
||||
```bash
|
||||
sysctl net.netfilter.nf_conntrack_max
|
||||
sysctl net.netfilter.nf_conntrack_count
|
||||
```
|
||||
If it gets close to the limit, tune it up, and reduce the time established connections linger in the tracker:
|
||||
If measured occupancy approaches the limit and memory permits, evaluate a larger table. Shorter tracking timeouts can remove idle NAT/firewall state needed by long-lived connections, so validate them separately. These are example values, not a universal profile:
|
||||
```ini
|
||||
# In /etc/sysctl.d/99-telemt-highload.conf
|
||||
net.netfilter.nf_conntrack_max = 2097152
|
||||
@@ -138,7 +155,7 @@ backend telemt_backend
|
||||
# Preserve the client IP for Telemt through PROXY v2
|
||||
server telemt_core 10.10.10.1:443 maxconn 250000 send-proxy-v2 check inter 5s
|
||||
```
|
||||
**Important**: Telemt must be configured to process the `PROXY` protocol on port `443` for this chain to work and preserve client IPs.
|
||||
**Important**: configure the explicit Telemt listener for PROXY protocol and set `server.proxy_protocol_trusted_cidrs` to the immediate HAProxy addresses. Check its bind address and host firewall. The [two-hop example](../Setup_examples/VPS_DOUBLE_HOP.en.md#step-2-installing-telemt-on-server-b-conditionally-netherlands) shows the complete listener setup.
|
||||
|
||||
### 4.2 WEB deployment
|
||||
|
||||
|
||||
@@ -1,12 +1,17 @@
|
||||
# Руководство по High-Load конфигурации и тюнингу
|
||||
При развертывании Telemt под высокой нагрузкой (десятки и сотни тысяч одновременных подключений), стандартные ограничения сетевого стека ОС могут приводить к потерям пакетов, переключениям контекста CPU и отказам в соединениях. В данном руководстве описана настройка ядра Linux, системных лимитов и аппаратной конфигурации для работы в подобных сценариях.
|
||||
# Настройка Telemt для высокой нагрузки
|
||||
|
||||
[English](HIGH_LOAD.en.md) · [Русский](HIGH_LOAD.ru.md) · [Deutsch](HIGH_LOAD.de.md)
|
||||
|
||||
Используйте это руководство, когда измерения показывают конкретное ограничение ресурсов. Значения ниже — примеры настройки, а не подтверждённая гарантия определённого числа соединений. Перед изменениями запишите версию ядра, действующую конфигурацию, частоту подключений, расход памяти и задержку. Сохраните прежние значения и меняйте одну группу настроек за раз, чтобы сравнить результат и при необходимости откатить изменение.
|
||||
|
||||
Термины объяснены в [общем словаре](../TERMINOLOGY.md).
|
||||
|
||||
---
|
||||
## 1. Системные лимиты и файловые дескрипторы
|
||||
|
||||
Также учитывайте [`server.max_connections`](../Config_params/CONFIG_PARAMS.ru.md#max_connections) при расчёте клиентской нагрузки, в том числе через ME. `0` снимает этот общий клиентский лимит и не ограничивает ME 128 клиентами. Ограничения дескрипторов ОС, пользовательские лимиты, очереди, бюджеты памяти и политики writer-ов продолжают действовать. Для изменения параметра нужен перезапуск процесса.
|
||||
Также учитывайте [`server.max_connections`](../Config_params/CONFIG_PARAMS.ru.md#max_connections) при расчёте клиентской нагрузки, в том числе через ME. `0` снимает этот общий клиентский лимит и не ограничивает ME 128 клиентами. Ограничения дескрипторов ОС, пользовательские лимиты, очереди, бюджеты памяти и политики ME Writer продолжают действовать. Для изменения параметра нужен перезапуск процесса.
|
||||
|
||||
Каждое TCP-сосоединение требует файлового дескриптора. При 100 тысячах соединений стандартные лимиты Linux (зачастую 1024 или 65535) будут исчерпаны немедленно.
|
||||
Каждое TCP-соединение требует файлового дескриптора. При 100 тысячах соединений стандартные лимиты Linux (зачастую 1024 или 65535) будут исчерпаны немедленно.
|
||||
### Общесистемные лимиты (`sysctl`)
|
||||
Увеличьте глобальный лимит файловых дескрипторов в `/etc/sysctl.conf`:
|
||||
```ini
|
||||
@@ -51,45 +56,57 @@ net.ipv4.tcp_max_syn_backlog = 65535
|
||||
net.ipv4.tcp_syncookies = 1
|
||||
```
|
||||
### 2.2 Исчерпание портов и TIME-WAIT сокеты
|
||||
Высокая текучесть приводит к нехватке временных (ephemeral) портов. Расширьте диапазон портов и позвольте ядру быстро переиспользовать закрытые сокеты:
|
||||
Сначала отличите ошибки исходящих подключений из-за нехватки портов от большого, но безвредного числа записей TIME-WAIT. Проверьте ошибку подключения, адреса и порты назначения и вывод `ss -s`. Если ограничение действительно связано с исходными портами, диапазон можно расширить с учётом портов, зарезервированных другими службами:
|
||||
|
||||
```ini
|
||||
net.ipv4.ip_local_port_range = 10000 65535
|
||||
net.ipv4.tcp_fin_timeout = 15
|
||||
net.ipv4.tcp_tw_reuse = 1
|
||||
net.ipv4.tcp_max_tw_buckets = 2000000
|
||||
```
|
||||
### 2.3 TCP Keepalive (Агрессивная очистка мертвых соединений)
|
||||
По умолчанию Linux держит "оборванные" TCP-сессии более 2 часов. Значения ниже начинают probes после пяти минут простоя и закрывают не отвечающий peer после последующего probe budget — примерно через 7–8 минут общего простоя:
|
||||
|
||||
`tcp_tw_reuse` управляет повторным использованием TIME-WAIT-сокетов, когда это допускает протокол. В указанной документации ядра `0` отключает повторное использование, `1` включает его глобально, `2` — только для loopback. Перед изменением проверьте значение в работающем ядре. `tcp_max_tw_buckets` ограничивает число сохраняемых записей, а не продолжительность TIME-WAIT.
|
||||
|
||||
`tcp_fin_timeout` действует на осиротевшие соединения в `FIN_WAIT_2`: его уменьшение не сокращает `TIME_WAIT`. При диагностике исчерпания портов различайте эти механизмы. См. [справочник IP sysctl ядра Linux](https://docs.kernel.org/networking/ip-sysctl.html).
|
||||
|
||||
### 2.3 TCP Keepalive
|
||||
Эти sysctl задают значения по умолчанию для сокетов с включённым TCP keepalive, если приложение не переопределило соответствующие параметры. Проверки начинаются после пяти минут простоя; с учётом последующих проб общий срок составляет примерно 7–8 минут:
|
||||
|
||||
```ini
|
||||
net.ipv4.tcp_keepalive_time = 300
|
||||
net.ipv4.tcp_keepalive_intvl = 30
|
||||
net.ipv4.tcp_keepalive_probes = 5
|
||||
```
|
||||
### 2.4 Буферы TCP и управление перегрузками (Congestion Control)
|
||||
Оптимизируйте использование памяти на сокет и переключитесь на алгоритм BBR (Bottleneck Bandwidth and Round-trip propagation time) для улучшения задержки на плохих сетях:
|
||||
|
||||
Для клиентских сокетов Telemt задаёт время ожидания и интервал через `timeouts.client_keepalive` — по умолчанию 15 секунд. Для ME-сокетов на Linux используются 30 секунд простоя, интервал 10 секунд и 3 пробы. Это параметры TCP; ME RPC Ping/Pong, `timeouts.client_ack` и политики простоя при передаче данных выполняют отдельные проверки. Поэтому пример sysctl не определяет срок жизни каждого соединения Telemt. Проверяйте нужный сокет и настроенный прикладной таймаут.
|
||||
|
||||
### 2.4 Буферы TCP и управление перегрузкой
|
||||
До и после изменения буферов сравните расход памяти, пропускную способность и задержки p95/p99 при одинаковой нагрузке. Максимум ниже задаёт верхнюю границу для подходящего сокета, а не постоянное выделение такого объёма каждому соединению. Telemt также явно устанавливает размеры буферов сокетов, поэтому одних системных значений по умолчанию недостаточно для оценки.
|
||||
|
||||
```ini
|
||||
# Core buffer sizes
|
||||
# Example buffer ceilings: size them for the available memory and workload.
|
||||
net.core.rmem_default = 262144
|
||||
net.core.wmem_default = 262144
|
||||
net.core.rmem_max = 16777216
|
||||
net.core.wmem_max = 16777216
|
||||
# TCP-specific buffers (min, default, max)
|
||||
net.ipv4.tcp_rmem = 4096 87380 16777216
|
||||
net.ipv4.tcp_wmem = 4096 65536 16777216
|
||||
# Enable BBR
|
||||
```
|
||||
|
||||
Проверьте доступные алгоритмы командой `sysctl net.ipv4.tcp_available_congestion_control`. Если BBR поддерживается, сравните его с действующим алгоритмом при характерных RTT, потерях и нагрузке. Это руководство не подтверждает универсального снижения задержки. Пример настройки BBR:
|
||||
|
||||
```ini
|
||||
net.core.default_qdisc = fq
|
||||
net.ipv4.tcp_congestion_control = bbr
|
||||
```
|
||||
|
||||
|
||||
---
|
||||
## 3. Тюнинг Conntrack (Netfilter)
|
||||
Если ваш сервер использует `iptables`, `ufw` или `firewalld`, ядро вынуждено отслеживать каждое соединение в таблице состояний (`nf_conntrack`). Когда эта таблица переполняется, Linux отбрасывает новые пакеты без уведомления приложения.
|
||||
Правила межсетевого экрана с отслеживанием состояния и NAT могут использовать `nf_conntrack`. Проверьте, включён ли учёт на нужном маршруте, особенно при наличии правил NOTRACK. Переполнение таблицы может приводить к отбрасыванию новых пакетов.
|
||||
Проверьте текущие лимиты и использование:
|
||||
```bash
|
||||
sysctl net.netfilter.nf_conntrack_max
|
||||
sysctl net.netfilter.nf_conntrack_count
|
||||
```
|
||||
Если вы близки к пределу, увеличьте таблицу и заставьте ядро быстрее удалять установленные соединения. Добавьте в `/etc/sysctl.d/99-telemt-highload.conf`:
|
||||
Если измеренное заполнение приближается к пределу и памяти достаточно, оцените увеличение таблицы. Короткие таймауты могут удалить состояние NAT или межсетевого экрана, нужное долгоживущим соединениям; проверяйте их отдельно. Ниже приведены примеры значений:
|
||||
```ini
|
||||
# In /etc/sysctl.d/99-telemt-highload.conf
|
||||
net.netfilter.nf_conntrack_max = 2097152
|
||||
@@ -99,16 +116,16 @@ net.netfilter.nf_conntrack_tcp_timeout_time_wait = 12
|
||||
```
|
||||
*Внимание: в зависимости от ОС, вам может потребоваться выполнить `modprobe nf_conntrack` перед установкой этих параметров.*
|
||||
|
||||
Когда `server.conntrack_control.inline_conntrack_control = true` и `[server.conntrack_control]` использует `notrack` или `hybrid`, один generation-fenced authority владеет только правилами conntrack control, созданными Telemt. Он применяет изменения IPv4 и IPv6, игнорирует устаревшие или конфликтующие публикации и повторяет неудачный reconcile через 1, 2, 4, 8, 16 и далее не более чем 30 секунд. Частичный многошаговый сбой запускает best-effort восстановление; неудачный rollback оставляет applied firewall state неизвестным до следующего успешного reconcile. `telemt_conntrack_control_state{flag="rule_apply_ok"}` показывает, действует ли требуемый набор правил. При включённой core telemetry попытки используют `telemt_conntrack_rule_reconcile_total{result="success"|"error"}` и `telemt_conntrack_rule_rollback_total{result="success"|"error"}`. При shutdown выполняется ограниченный 30 секундами best-effort cleanup собственных правил. Настройки conntrack control требуют перезапуска.
|
||||
При `server.conntrack_control.inline_conntrack_control = true` и режиме `notrack` или `hybrid` правилами, созданными Telemt, управляет один владелец. Он учитывает поколения конфигурации, применяет изменения IPv4 и IPv6 и отклоняет устаревшие или конфликтующие публикации. После ошибки повторяет согласование правил через 1, 2, 4, 8, 16 секунд, затем с паузой не более 30 секунд. При частичном сбое пытается восстановить прежние правила; если откат не удался, действующее состояние считается неизвестным до успешного согласования. `telemt_conntrack_control_state{flag="rule_apply_ok"}` показывает, применён ли требуемый набор. При включённой основной телеметрии попытки учитываются в `telemt_conntrack_rule_reconcile_total{result="success"|"error"}` и `telemt_conntrack_rule_rollback_total{result="success"|"error"}`. При завершении работы Telemt пытается удалить собственные правила в пределах 30 секунд. Изменение настроек conntrack требует перезапуска процесса.
|
||||
|
||||
---
|
||||
## 4. Архитектура: развёртывание за HAProxy
|
||||
|
||||
### 4.1 L4-развёртывание native MTProxy и TLS-front
|
||||
|
||||
Для массового native MTProxy- или TLS-front-трафика L4 HAProxy может поглощать всплески соединений перед передачей TCP streams в Telemt. Следующий пример **не подходит для WEB-listener**.
|
||||
Для массового native MTProxy- или TLS-front-трафика L4 HAProxy может поглощать всплески соединений перед передачей TCP-потоков в Telemt. Следующий пример **не подходит для WEB-listener**.
|
||||
|
||||
#### Оптимизация `haproxy.cfg` для High-Load
|
||||
#### Пример `haproxy.cfg` для высокой нагрузки
|
||||
```haproxy
|
||||
global
|
||||
# Disable detailed connection logs under load
|
||||
@@ -138,17 +155,17 @@ backend telemt_backend
|
||||
# Preserve the client IP for Telemt through PROXY v2
|
||||
server telemt_core 10.10.10.1:443 maxconn 250000 send-proxy-v2 check inter 5s
|
||||
```
|
||||
**Важно**: Telemt должен быть настроен на обработку протокола `PROXY` на порту `443`, чтобы получать оригинальные IP-адреса клиентов.
|
||||
**Важно**: включите PROXY protocol на явном listener Telemt и задайте в `server.proxy_protocol_trusted_cidrs` адреса непосредственного HAProxy. Проверьте адрес прослушивания и правила межсетевого экрана. Полная настройка listener показана в [примере двойного перехода](../Setup_examples/VPS_DOUBLE_HOP.ru.md#шаг-2-установка-telemt-на-сервере-b-условно-нидерланды).
|
||||
|
||||
### 4.2 WEB-развёртывание
|
||||
|
||||
WEB-режиму требуется L7 TLS-терминатор и приватный plain HTTP/1.1 listener Telemt с `proxy_protocol = false`; не используйте для него L4 backend с `send-proxy-v2` из предыдущего примера. Следуйте полному [руководству по WEB-прокси](../WEB/WEB_PROXY.ru.md), сохраняйте `Host`, точные path и query, WebSocket Upgrade headers и передавайте один перезаписанный `X-Forwarded-For` только от явно доверенных CIDR терминатора. Public ALPN должен предлагать `h2` для `https-lanes` и `http/1.1` для WebSocket Upgrade.
|
||||
WEB-режиму нужны TLS-терминатор уровня L7 и приватный HTTP/1.1 listener Telemt без шифрования, с `proxy_protocol = false`. Предыдущий пример L4 с `send-proxy-v2` для этого не подходит. Следуйте [руководству WEB](../WEB/WEB_PROXY.ru.md): сохраняйте `Host`, точный путь и строку запроса, а также заголовки WebSocket Upgrade. Передавайте один заново сформированный `X-Forwarded-For` только от явно доверенных CIDR терминатора. На публичном TLS-входе ALPN должен предлагать `h2` для `https-lanes` и `http/1.1` для WebSocket Upgrade.
|
||||
|
||||
Для WEB-listener задайте `web_client_ip_source = "x_forwarded_for"` и укажите в `web_trusted_proxy_cidrs` только адреса непосредственного HAProxy. Не доверяйте доступной клиентам подсети и не включайте PROXY protocol на этом listener.
|
||||
Для WEB-listener задайте `web_client_ip_source = "x_forwarded_for"`; в `web_trusted_proxy_cidrs` укажите только адреса непосредственного HAProxy. Не доверяйте доступной клиентам подсети и не включайте PROXY protocol на этом listener.
|
||||
|
||||
Направляйте весь vhost в один процесс Telemt. При совместном размещении по prefix сохраняйте настроенный `base_path` без rewrite; во время миграции направляйте в Telemt старое и новое поддеревья, пока ранее выпущенные процессом credentials ещё могут использоваться. Multi-process backend требует affinity всего vhost для bridge root, создания и восстановления session, uplink, downlink, DELETE, diagnostics и WebSocket Upgrade.
|
||||
Направляйте весь виртуальный хост в один процесс Telemt. При размещении в подкаталоге сохраняйте `base_path` без переписывания. Во время миграции направляйте в Telemt и старое, и новое поддеревья, пока ещё могут использоваться ранее выпущенные процессом токены. Если процессов несколько, закрепляйте за одним процессом весь виртуальный хост: страницу моста, создание и восстановление сессий, передачу в обе стороны, DELETE, диагностику и WebSocket Upgrade.
|
||||
|
||||
Например, следующий фрагмент HAProxy направляет только точный host и WEB-поддерево с завершающим слешем, не изменяя request target:
|
||||
Например, этот фрагмент HAProxy направляет в Telemt только указанный хост и WEB-поддерево с завершающим слешем, сохраняя исходный адрес запроса:
|
||||
|
||||
```haproxy
|
||||
frontend https_in
|
||||
@@ -169,16 +186,16 @@ backend telemt_web
|
||||
server telemt_web_1 127.0.0.1:18080 check
|
||||
```
|
||||
|
||||
Обрабатывайте путь без завершающего слеша `/telegram/web` вне этого backend, чтобы frontend не создавал redirect alias в аутентифицированное поддерево. Не добавляйте `set-path`, `replace-path` или path-компонент к адресу backend server. Значения 65 секунд — пример для defaults; client и server timeouts должны быть больше `web.timeouts.long_poll_secs` и удвоенного effective WebSocket liveness interval.
|
||||
Обрабатывайте путь без завершающего слеша `/telegram/web` вне этого backend, чтобы не создавать перенаправление в аутентифицированное поддерево. Не добавляйте `set-path`, `replace-path` или путь к адресу сервера backend. Таймаут 65 секунд подходит для настроек по умолчанию. Таймауты клиента и сервера должны превышать `web.timeouts.long_poll_secs` и удвоенный действующий интервал проверки активности WebSocket.
|
||||
|
||||
При расчёте capacity учитывайте одновременно публичные TLS sockets и приватные sockets между терминатором и Telemt. Совместно рассчитывайте file descriptors, upstream capacity терминатора, `web.limits.max_http_connections`, handler capacity, параллельные long polls и WebSocket lanes; upstream keepalive pool не является лимитом concurrency.
|
||||
При расчёте ёмкости учитывайте и публичные TLS-сокеты, и приватные соединения между терминатором и Telemt. Согласуйте лимиты файловых дескрипторов, исходящих соединений терминатора, `web.limits.max_http_connections`, обработчиков, параллельных долгих опросов и каналов WebSocket. Пул простаивающих keepalive-соединений не ограничивает число одновременных запросов.
|
||||
|
||||
---
|
||||
## 5. Диагностика и мониторинг
|
||||
|
||||
- **Переполнение listen queues**: проверяйте `ListenOverflows` и `ListenDrops` в `/proc/net/netstat` либо через `nstat`.
|
||||
- **Conntrack pressure**: проверяйте `nf_conntrack_count`, kernel logs и `telemt_conntrack_control_state{flag="rule_apply_ok"}`; при включённой core telemetry также проверяйте счётчики reconcile/rollback выше.
|
||||
- **File descriptors**: `cat /proc/sys/fs/file-nr` и лимиты процесса Telemt в `/proc/<pid>/limits`.
|
||||
- **Переполнение очередей входящих соединений**: проверяйте `ListenOverflows` и `ListenDrops` в `/proc/net/netstat` либо через `nstat`.
|
||||
- **Заполнение conntrack**: проверяйте `nf_conntrack_count`, журнал ядра и `telemt_conntrack_control_state{flag="rule_apply_ok"}`; при включённой основной телеметрии — также указанные выше счётчики согласования и отката правил.
|
||||
- **Файловые дескрипторы**: `cat /proc/sys/fs/file-nr` и лимиты процесса Telemt в `/proc/<pid>/limits`.
|
||||
- **Состояния соединений**: `ss -s`; избегайте полного сканирования через `netstat` на нагруженном сервере.
|
||||
- **Rate limiter contention**: при включённой core telemetry настройте alert на положительный прирост или rate counter, например `increase(telemt_rate_limiter_cas_retry_exhausted_total[5m]) > 0`, с группировкой по `scope`, `direction` и `operation`. Reserve exhaustion возвращает нулевой grant без классификации как настроенный throttle; refund exhaustion сохраняет списание. Эта метрика не является ни счётчиком dropped connections, ни счётчиком policy throttling.
|
||||
- **WEB**: объединяйте telemetry терминатора и внешний TLS probe с `/v1/runtime/web/status`, `telemt_web_tcp_accept_total{result="accepted"|"error"}` и остальными `telemt_web_*` metrics. Request path и `base_path` намеренно не используются как metric labels.
|
||||
- **Конкуренция за ограничитель скорости**: при включённой основной телеметрии отслеживайте рост счётчика, например `increase(telemt_rate_limiter_cas_retry_exhausted_total[5m]) > 0`, с группировкой по `scope`, `direction` и `operation`. Исчерпание попыток резервирования возвращает нулевое разрешение на передачу и не считается срабатыванием настроенного лимита. Исчерпание попыток возврата сохраняет списанный объём. Метрика не считает разорванные соединения или ограничения, предусмотренные политикой.
|
||||
- **WEB**: сопоставляйте телеметрию терминатора и внешнюю проверку TLS с `/v1/runtime/web/status`, `telemt_web_tcp_accept_total{result="accepted"|"error"}` и остальными метриками `telemt_web_*`. Путь запроса и `base_path` намеренно не используются как метки метрик.
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Telemt Tuning-Leitfaden: Middle-End und Upstreams
|
||||
|
||||
[English](TUNING.en.md) · [Русский](TUNING.ru.md) · [Deutsch](TUNING.de.md) · [EN / RU / DE terminology](../TERMINOLOGY.md)
|
||||
|
||||
Dieses Dokument beschreibt das aktuelle Laufzeitverhalten für Middle-End (ME) und Upstream-Routing basierend auf:
|
||||
- `src/config/types.rs`
|
||||
- `src/config/defaults.rs`
|
||||
@@ -8,6 +10,8 @@ Dieses Dokument beschreibt das aktuelle Laufzeitverhalten für Middle-End (ME) u
|
||||
|
||||
Die unten angegebenen `Default`-Werte sind Code-Defaults (bei fehlendem Schlüssel), nicht zwingend die Werte aus `config.full.toml`.
|
||||
|
||||
`Option<T>` und `null` in Typ- und Standardwertspalten beschreiben optionale interne Werte. TOML kennt kein `null`-Literal. Für die alten Aktualisierungsintervalle lassen Sie `general.update_every` weg und setzen die alten Schlüssel ausdrücklich; andernfalls beträgt das einheitliche Standardintervall 300 Sekunden. Null-Werte in Objektfeldern eines Konfigurations-PATCH werden ignoriert und entfernen keine Einstellungen.
|
||||
|
||||
## Middle-End-Parameter
|
||||
|
||||
### 1) ME-Grundmodus, NAT und STUN
|
||||
@@ -65,7 +69,7 @@ Die unten angegebenen `Default`-Werte sind Code-Defaults (bei fehlendem Schlüss
|
||||
| `general.proxy_secret_stable_snapshots` | `u8` | `2` | muss `> 0` sein | Anzahl identischer Secret-Snapshots vor Rotation. | `proxy_secret_stable_snapshots = 3` |
|
||||
| `general.proxy_secret_rotate_runtime` | `bool` | `true` | keine | Aktiviert Runtime-Rotation des Proxy-Secrets. | `proxy_secret_rotate_runtime = true` |
|
||||
| `general.proxy_secret_len_max` | `usize` | `256` | Bereich `[32,4096]` | Obergrenze für akzeptierte Secret-Länge. | `proxy_secret_len_max = 512` |
|
||||
| `general.update_every` | `Option<u64>` | `300` | wenn gesetzt: `> 0`; bei `null`: Legacy-Min-Fallback | Einheitliches Refresh-Intervall für ME-Config + Secret-Updater. | `update_every = 300` |
|
||||
| `general.update_every` | `Option<u64>` | `300` | wenn gesetzt: `> 0`; ohne diesen Schlüssel mit expliziten alten Intervallen: deren Minimum | Einheitliches Refresh-Intervall für ME-Config + Secret-Updater. | `update_every = 300` |
|
||||
| `general.me_pool_drain_ttl_secs` | `u64` | `90` | keine | Altersschwelle für Warnungen bei langem Drain und Untergrenze der Force-Close-Normalisierung; gewährt keine stale Binds. | `me_pool_drain_ttl_secs = 120` |
|
||||
| `general.me_bind_stale_mode` | `"never"`, `"ttl"` oder `"always"` | `"never"` | keine | Steuert neue Bindings auf draining stale Writer für nicht abgedeckte DC-Family-Gruppen. | `me_bind_stale_mode = "never"` |
|
||||
| `general.me_bind_stale_ttl_secs` | `u64` | `90` | keine | Stale-Bind-Fenster nur für `me_bind_stale_mode = "ttl"`; `0` deaktiviert den TTL-Ablauf für zulässige draining Writer. | `me_bind_stale_ttl_secs = 90` |
|
||||
@@ -74,11 +78,11 @@ Die unten angegebenen `Default`-Werte sind Code-Defaults (bei fehlendem Schlüss
|
||||
| `general.auto_degradation_enabled` | `bool` | `true` | keine | Reserviertes Kompatibilitätsfeld in aktueller Revision (kein aktiver Runtime-Consumer). | `auto_degradation_enabled = true` |
|
||||
| `general.degradation_min_unavailable_dc_groups` | `u8` | `2` | keine | Reservierter Kompatibilitäts-Schwellenwert in aktueller Revision (kein aktiver Runtime-Consumer). | `degradation_min_unavailable_dc_groups = 2` |
|
||||
|
||||
Eine Hardswap-Kandidatengeneration ist nur für denselben Desired-Map-Hash und dieselbe Endpoint-Revision maßgeblich. Wiederholte Versuche verwenden diese pending Generation höchstens 1800 Sekunden wieder; danach wird eine neue Generation angelegt. Der Commit validiert die Authority erneut und verlangt mindestens `me_pool_min_fresh_ratio` frische DC-Family-Coverage. Fehlende Gruppen blockieren den Commit bei `me_bind_stale_mode = "never"`; `ttl` oder `always` können mit policy-begrenztem stale Fallback für diese Gruppen committen. Abgedeckte alte Writer können sofort retiret werden; Hardswap ist daher ein atomarer Policy-Übergang, keine universelle Zero-Drop-Garantie.
|
||||
Eine für Hardswap vorbereitete Generation darf nur übernommen werden, solange der Hash der gewünschten ME-Zuordnung und die Revision der Verbindungsziele unverändert sind. Wiederholungsversuche verwenden sie höchstens 1800 Sekunden; danach wird eine neue Generation angelegt. Vor der Übernahme prüft Telemt diese Voraussetzungen erneut. Der Anteil der durch neue Verbindungen abgedeckten Gruppen aus DC und IP-Adressfamilie muss mindestens `me_pool_min_fresh_ratio` betragen. Bei `me_bind_stale_mode = "never"` blockiert jede fehlende Gruppe die Übernahme. Mit `ttl` oder `always` dürfen für solche Gruppen ältere Verbindungen innerhalb der gewählten Richtlinie weiterverwendet werden. Alte ME Writer bereits abgedeckter Gruppen können sofort außer Betrieb genommen werden. Der atomare Wechsel der Richtlinie garantiert daher nicht den Erhalt aller Verbindungen.
|
||||
|
||||
Writer-Replacement verwendet separat den cancellation-sicheren Zustand `Open -> Preparing -> Retiring`. `Preparing` verhindert doppelte Replacement-Arbeit, erlaubt aber weiterhin neue Binds. Unter dem Registry-Binding-Guard validiert der Commit das Opfer erneut, setzt es auf `Retiring`, um neue Binds zu blockieren, installiert und publiziert den Nachfolger und beginnt das Draining des Vorgängers, bevor der Guard freigegeben wird. Das Verwerfen einer Reservation vor dieser Commit-Grenze stellt `Open` wieder her.
|
||||
Der Austausch eines einzelnen ME Writers verwendet die Zustände `Open -> Preparing -> Retiring` und berücksichtigt den Abbruch der Operation. `Preparing` verhindert einen zweiten Austausch desselben Writers, lässt aber neue Stream-Zuordnungen zu. Unter der Sperre des Zuordnungsregisters prüft Telemt den bisherigen Writer erneut, setzt ihn auf `Retiring`, um neue Zuordnungen zu sperren, installiert und veröffentlicht den Nachfolger und beginnt, den Vorgänger auslaufen zu lassen. Erst dann wird die Sperre freigegeben. Wird die Reservierung vor dieser Übernahmegrenze verworfen, gilt wieder `Open`.
|
||||
|
||||
Pending-Alter, Writer-Anzahl und -Defizit, fehlende DC-Gruppen, Map-Aktualität, verwaiste Warm-Writer und die Phasen `preparing`/`retiring` sind über `/v1/runtime/me_pool_state` sichtbar. Die entsprechenden Gauges `telemt_me_hardswap_*` und `telemt_me_writer_replacement_current` liefern Null, wenn ME-Telemetrie `silent` ist oder kein aktiver ME-Snapshot vorliegt. In Prometheus muss `telemt_me_hardswap_pending_map_current` zusammen mit `telemt_me_hardswap_pending` ausgewertet werden: Map-Currency Null bedeutet auch, dass keine pending Generation existiert; die API verwendet dann `null`. Alarmieren Sie bei einem Pending-Alter nahe 1800 Sekunden, dauerhaftem Defizit oder fehlenden Gruppen, stale Map, verwaisten Warm-Writern oder nicht konvergierenden Replacement-Phasen.
|
||||
`/v1/runtime/me_pool_state` zeigt das Alter der wartenden Generation, Anzahl und Defizit der ME Writer, fehlende DC-Gruppen, die Aktualität der Zuordnung, vorbereitete Verbindungen ohne Besitzer und die Phasen `preparing`/`retiring`. Die Messwerte `telemt_me_hardswap_*` und `telemt_me_writer_replacement_current` sind null, wenn die ME-Telemetrie auf `silent` steht oder kein aktiver Zustandsstand vorliegt. Werten Sie `telemt_me_hardswap_pending_map_current` zusammen mit `telemt_me_hardswap_pending` aus: Null kann auch bedeuten, dass keine Generation wartet, statt dass die Zuordnung veraltet ist. Die API liefert dann `null`. Richten Sie Alarme für ein Alter nahe 1800 Sekunden, anhaltende Defizite oder fehlende Gruppen, veraltete Zuordnungen, vorbereitete Verbindungen ohne Besitzer und festhängende Austauschphasen ein.
|
||||
|
||||
## Deprecated / Legacy Parameter
|
||||
|
||||
@@ -86,8 +90,8 @@ Pending-Alter, Writer-Anzahl und -Defizit, fehlende DC-Gruppen, Map-Aktualität,
|
||||
|---|---|---|---|---|
|
||||
| `general.middle_proxy_nat_stun` | Deprecated | `network.stun_servers` | Wird nur dann in `network.stun_servers` gemerged, wenn `network.stun_servers` nicht explizit gesetzt ist. | Wert nach `network.stun_servers` verschieben, Legacy-Key entfernen. |
|
||||
| `general.middle_proxy_nat_stun_servers` | Deprecated | `network.stun_servers` | Wird nur dann in `network.stun_servers` gemerged, wenn `network.stun_servers` nicht explizit gesetzt ist. | Werte nach `network.stun_servers` verschieben, Legacy-Key entfernen. |
|
||||
| `general.proxy_secret_auto_reload_secs` | Deprecated | `general.update_every` | Nur aktiv, wenn `update_every = null` (Legacy-Fallback). | `general.update_every` explizit setzen, Legacy-Key entfernen. |
|
||||
| `general.proxy_config_auto_reload_secs` | Deprecated | `general.update_every` | Nur aktiv, wenn `update_every = null` (Legacy-Fallback). | `general.update_every` explizit setzen, Legacy-Key entfernen. |
|
||||
| `general.proxy_secret_auto_reload_secs` | Deprecated | `general.update_every` | Aktiv, wenn `update_every` fehlt und alte Intervalle ausdrücklich gesetzt sind. | `general.update_every` explizit setzen, Legacy-Key entfernen. |
|
||||
| `general.proxy_config_auto_reload_secs` | Deprecated | `general.update_every` | Aktiv, wenn `update_every` fehlt und alte Intervalle ausdrücklich gesetzt sind. | `general.update_every` explizit setzen, Legacy-Key entfernen. |
|
||||
|
||||
## Wie Upstreams konfiguriert werden
|
||||
|
||||
@@ -182,26 +186,35 @@ weight = 2
|
||||
enabled = true
|
||||
```
|
||||
|
||||
### Beispiel 5: Gemischte Upstreams mit Scopes
|
||||
### Upstream anhand des Benutzernamens auswählen
|
||||
|
||||
Im Direct-Relay wählt ein Benutzer namens `scope_premium` den exakten Scope `premium`. Der Suffix muss aus 1–64 ASCII-Buchstaben, Ziffern oder Bindestrichen bestehen. Ohne gültigen Suffix erfolgt die Auswahl ohne Scope. Gibt es zu einem gültigen Scope keinen passenden Upstream, schlägt die Verbindung fehl; sie weicht nicht auf eine unmarkierte Route aus. Scope-Tags erstellen keine Benutzer und ersetzen keine Authentifizierung.
|
||||
|
||||
Ein ausgewählter Scope ersetzt die SOCKS4-`user_id` sowie SOCKS5-Benutzername und -Passwort. Im Beispiel muss der SOCKS5-Server `premium` sowohl als Benutzername als auch als Passwort akzeptieren. Gewöhnliche Benutzer verwenden die unmarkierte direkte Route. Ersetzen Sie Secret und SOCKS-Adresse vor dem Einsatz.
|
||||
|
||||
```toml
|
||||
[general]
|
||||
use_middle_proxy = false
|
||||
|
||||
[access.users]
|
||||
scope_premium = "0123456789abcdef0123456789abcdef"
|
||||
|
||||
[[upstreams]]
|
||||
type = "direct"
|
||||
weight = 5
|
||||
enabled = true
|
||||
scopes = ""
|
||||
|
||||
[[upstreams]]
|
||||
type = "socks5"
|
||||
address = "203.0.113.40:1080"
|
||||
username = "edge"
|
||||
password = "edgepass"
|
||||
weight = 3
|
||||
enabled = true
|
||||
scopes = "premium,me"
|
||||
username = "premium"
|
||||
password = "premium"
|
||||
scopes = "premium"
|
||||
```
|
||||
|
||||
### Beispiel 5: ME-orientiertes Tuning-Profil
|
||||
Diese benutzerbezogene Auswahl gilt für Direct-Relay. ME-Verbindungen übergeben derzeit keinen Benutzerscope; das Tag `me` wählt daher nicht automatisch einen ME-Upstream. TLS-Profilabfragen verwenden die separate Einstellung `censorship.tls_fetch_scope`. Siehe [Scope-Filterung](../Config_params/CONFIG_PARAMS.de.md#scopes).
|
||||
|
||||
|
||||
### Beispiel 6: ME-orientiertes Tuning-Profil
|
||||
|
||||
```toml
|
||||
[general]
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Telemt Tuning Guide: Middle-End and Upstreams
|
||||
|
||||
[English](TUNING.en.md) · [Русский](TUNING.ru.md) · [Deutsch](TUNING.de.md) · [EN / RU / DE terminology](../TERMINOLOGY.md)
|
||||
|
||||
This document describes the current runtime behavior for Middle-End (ME) and upstream routing based on:
|
||||
- `src/config/types.rs`
|
||||
- `src/config/defaults.rs`
|
||||
@@ -8,6 +10,8 @@ This document describes the current runtime behavior for Middle-End (ME) and ups
|
||||
|
||||
Defaults below are code defaults (used when a key is omitted), not necessarily values from `config.full.toml` examples.
|
||||
|
||||
`Option<T>` and `null` in type/default columns describe optional internal values. TOML has no `null` literal. To use legacy update intervals, omit `general.update_every` and explicitly set the legacy keys; otherwise the unified default is 300 seconds. Object-valued null members in config PATCH are ignored, not used to remove settings.
|
||||
|
||||
## Middle-End Parameters
|
||||
|
||||
### 1) Core ME mode, NAT, and STUN
|
||||
@@ -15,7 +19,7 @@ Defaults below are code defaults (used when a key is omitted), not necessarily v
|
||||
| Parameter | Type | Default | Constraints / validation | Runtime effect | Example |
|
||||
|---|---|---:|---|---|---|
|
||||
| `general.use_middle_proxy` | `bool` | `true` | none | Enables ME transport mode. If `false`, Direct mode is used. | `use_middle_proxy = true` |
|
||||
| `general.proxy_secret_path` | `Option<String>` | `"proxy-secret"` | path may be `null` | Path to Telegram infrastructure proxy-secret file. | `proxy_secret_path = "proxy-secret"` |
|
||||
| `general.proxy_secret_path` | `Option<String>` | `"proxy-secret"` | optional internal path; TOML has no `null` | Path to Telegram infrastructure proxy-secret file. | `proxy_secret_path = "proxy-secret"` |
|
||||
| `general.middle_proxy_nat_ip` | `Option<IpAddr>` | `null` | valid IP when set | Manual public NAT IP override for ME address material. | `middle_proxy_nat_ip = "203.0.113.10"` |
|
||||
| `general.middle_proxy_nat_probe` | `bool` | `true` | none | Enables ME NAT probing when ME mode and `network.stun_use` are both enabled. | `middle_proxy_nat_probe = true` |
|
||||
| `general.stun_nat_probe_concurrency` | `usize` | `8` | must be `> 0` | Max parallel STUN probes during NAT discovery. | `stun_nat_probe_concurrency = 16` |
|
||||
@@ -65,7 +69,7 @@ Defaults below are code defaults (used when a key is omitted), not necessarily v
|
||||
| `general.proxy_secret_stable_snapshots` | `u8` | `2` | must be `> 0` | Number of identical proxy-secret snapshots required before rotation. | `proxy_secret_stable_snapshots = 3` |
|
||||
| `general.proxy_secret_rotate_runtime` | `bool` | `true` | none | Enables runtime proxy-secret rotation. | `proxy_secret_rotate_runtime = true` |
|
||||
| `general.proxy_secret_len_max` | `usize` | `256` | must be within `[32,4096]` | Upper limit for accepted proxy-secret length. | `proxy_secret_len_max = 512` |
|
||||
| `general.update_every` | `Option<u64>` | `300` | if set: must be `> 0`; if `null`: legacy min fallback | Unified refresh interval for ME config + secret updater. | `update_every = 300` |
|
||||
| `general.update_every` | `Option<u64>` | `300` | if set: must be `> 0`; omitted with explicit legacy keys: legacy minimum | Unified refresh interval for ME config + secret updater. | `update_every = 300` |
|
||||
| `general.me_pool_drain_ttl_secs` | `u64` | `90` | none | Age threshold for prolonged-drain warnings and the lower-bound normalization of force-close timeout; it does not grant stale binds. | `me_pool_drain_ttl_secs = 120` |
|
||||
| `general.me_bind_stale_mode` | `"never"`, `"ttl"`, or `"always"` | `"never"` | none | Controls whether new bindings may use draining stale writers for uncovered DC-family groups. | `me_bind_stale_mode = "never"` |
|
||||
| `general.me_bind_stale_ttl_secs` | `u64` | `90` | none | Stale-bind eligibility window used only when `me_bind_stale_mode = "ttl"`; `0` disables TTL expiry for eligible draining writers. | `me_bind_stale_ttl_secs = 90` |
|
||||
@@ -86,8 +90,8 @@ Operators can observe pending age, writer count and deficit, missing DC groups,
|
||||
|---|---|---|---|---|
|
||||
| `general.middle_proxy_nat_stun` | Deprecated | `network.stun_servers` | Merged into `network.stun_servers` only when `network.stun_servers` is not explicitly set. | Move value into `network.stun_servers` and remove legacy key. |
|
||||
| `general.middle_proxy_nat_stun_servers` | Deprecated | `network.stun_servers` | Merged into `network.stun_servers` only when `network.stun_servers` is not explicitly set. | Move values into `network.stun_servers` and remove legacy key. |
|
||||
| `general.proxy_secret_auto_reload_secs` | Deprecated | `general.update_every` | Used only when `update_every = null` (legacy fallback path). | Set `general.update_every` explicitly and remove legacy key. |
|
||||
| `general.proxy_config_auto_reload_secs` | Deprecated | `general.update_every` | Used only when `update_every = null` (legacy fallback path). | Set `general.update_every` explicitly and remove legacy key. |
|
||||
| `general.proxy_secret_auto_reload_secs` | Deprecated | `general.update_every` | Used when `update_every` is omitted and legacy intervals are explicitly configured. | Set `general.update_every` explicitly and remove legacy key. |
|
||||
| `general.proxy_config_auto_reload_secs` | Deprecated | `general.update_every` | Used when `update_every` is omitted and legacy intervals are explicitly configured. | Set `general.update_every` explicitly and remove legacy key. |
|
||||
|
||||
## How Upstreams Are Configured
|
||||
|
||||
@@ -182,26 +186,35 @@ weight = 2
|
||||
enabled = true
|
||||
```
|
||||
|
||||
### Example 5: Mixed upstreams with scopes
|
||||
### Selecting an upstream by user scope
|
||||
|
||||
In Direct relay, a user named `scope_premium` selects the exact scope `premium`. The suffix must contain 1–64 ASCII letters, digits or hyphens. A missing or invalid suffix uses unscoped selection. With a valid scope and no matching upstream, the connection fails; it does not fall back to an unscoped route. Scope tags do not create users or grant authorization.
|
||||
|
||||
For a selected scope, SOCKS4 `user_id` and SOCKS5 username/password are replaced by that scope string. In this example the SOCKS5 server must accept `premium` as both username and password. Ordinary users select the unscoped direct route. Replace the example secret and SOCKS address before use.
|
||||
|
||||
```toml
|
||||
[general]
|
||||
use_middle_proxy = false
|
||||
|
||||
[access.users]
|
||||
scope_premium = "0123456789abcdef0123456789abcdef"
|
||||
|
||||
[[upstreams]]
|
||||
type = "direct"
|
||||
weight = 5
|
||||
enabled = true
|
||||
scopes = ""
|
||||
|
||||
[[upstreams]]
|
||||
type = "socks5"
|
||||
address = "203.0.113.40:1080"
|
||||
username = "edge"
|
||||
password = "edgepass"
|
||||
weight = 3
|
||||
enabled = true
|
||||
scopes = "premium,me"
|
||||
username = "premium"
|
||||
password = "premium"
|
||||
scopes = "premium"
|
||||
```
|
||||
|
||||
### Example 5: ME-focused tuning profile
|
||||
This per-user mechanism belongs to Direct relay. ME dialing currently passes no user scope, so a tag named `me` does not automatically select a ME upstream. TLS-front metadata fetches use the separate `censorship.tls_fetch_scope` setting. See [scope filtering](../Config_params/CONFIG_PARAMS.en.md#scopes).
|
||||
|
||||
|
||||
### Example 6: ME-focused tuning profile
|
||||
|
||||
```toml
|
||||
[general]
|
||||
|
||||
@@ -1,99 +1,103 @@
|
||||
# Руководство по тюнингу Telemt: Middle-End и Upstreams
|
||||
|
||||
[English](TUNING.en.md) · [Русский](TUNING.ru.md) · [Deutsch](TUNING.de.md) · [EN / RU / DE terminology](../TERMINOLOGY.md)
|
||||
|
||||
Документ описывает актуальное поведение Middle-End (ME) и маршрутизации через upstream на основе:
|
||||
- `src/config/types.rs`
|
||||
- `src/config/defaults.rs`
|
||||
- `src/config/load.rs`
|
||||
- `src/transport/upstream.rs`
|
||||
|
||||
Значения `Default` ниже — это значения из кода при отсутствии ключа в конфиге, а не обязательно значения из примеров `config.full.toml`.
|
||||
Значения `По умолчанию` ниже — это значения из кода при отсутствии ключа в конфиге, а не обязательно значения из примеров `config.full.toml`.
|
||||
|
||||
`Option<T>` и `null` в столбцах типов и значений по умолчанию обозначают необязательные внутренние значения. В TOML нет литерала `null`. Для старых интервалов обновления не задавайте `general.update_every` и явно укажите старые ключи; в остальных случаях общий интервал по умолчанию равен 300 секундам. Значения null в полях объекта PATCH конфигурации игнорируются и не удаляют настройки.
|
||||
|
||||
## Параметры Middle-End
|
||||
|
||||
### 1) Базовый режим ME, NAT и STUN
|
||||
|
||||
| Параметр | Тип | Default | Ограничения / валидация | Влияние на runtime | Пример |
|
||||
| Параметр | Тип | По умолчанию | Ограничения / валидация | Влияние на работу | Пример |
|
||||
|---|---|---:|---|---|---|
|
||||
| `general.use_middle_proxy` | `bool` | `true` | нет | Включает транспорт ME. При `false` используется Direct-режим. | `use_middle_proxy = true` |
|
||||
| `general.proxy_secret_path` | `Option<String>` | `"proxy-secret"` | путь может быть `null` | Путь к инфраструктурному proxy-secret Telegram. | `proxy_secret_path = "proxy-secret"` |
|
||||
| `general.middle_proxy_nat_ip` | `Option<IpAddr>` | `null` | валидный IP при задании | Ручной override публичного NAT IP для адресного материала ME. | `middle_proxy_nat_ip = "203.0.113.10"` |
|
||||
| `general.middle_proxy_nat_probe` | `bool` | `true` | нет | Включает NAT probing, когда одновременно включены ME-режим и `network.stun_use`. | `middle_proxy_nat_probe = true` |
|
||||
| `general.proxy_secret_path` | `Option<String>` | `"proxy-secret"` | необязательный путь; в TOML нет `null` | Путь к инфраструктурному proxy-secret Telegram. | `proxy_secret_path = "proxy-secret"` |
|
||||
| `general.middle_proxy_nat_ip` | `Option<IpAddr>` | `null` | валидный IP при задании | Явный публичный IP за NAT для вычисления адресной части ключей ME. | `middle_proxy_nat_ip = "203.0.113.10"` |
|
||||
| `general.middle_proxy_nat_probe` | `bool` | `true` | нет | Проверяет внешний адрес за NAT, если включены ME и `network.stun_use`. | `middle_proxy_nat_probe = true` |
|
||||
| `general.stun_nat_probe_concurrency` | `usize` | `8` | должно быть `> 0` | Максимум параллельных STUN-проб при NAT-детекте. | `stun_nat_probe_concurrency = 16` |
|
||||
| `network.stun_use` | `bool` | `true` | нет | Глобальный переключатель STUN. При `false` STUN отключен. | `stun_use = true` |
|
||||
| `network.stun_servers` | `Vec<String>` | встроенный публичный пул | удаляются дубликаты и пустые значения | Основной список STUN-серверов для NAT/public endpoint discovery. | `stun_servers = ["stun1.l.google.com:19302"]` |
|
||||
| `network.stun_tcp_fallback` | `bool` | `true` | нет | Включает TCP fallback, если UDP STUN недоступен. | `stun_tcp_fallback = true` |
|
||||
| `network.http_ip_detect_urls` | `Vec<String>` | `ifconfig.me` + `api.ipify.org` | нет | HTTP fallback для определения публичного IPv4 при недоступности STUN. | `http_ip_detect_urls = ["https://api.ipify.org"]` |
|
||||
| `general.stun_iface_mismatch_ignore` | `bool` | `false` | нет | Зарезервированный флаг в текущей ревизии (runtime его не использует). | `stun_iface_mismatch_ignore = false` |
|
||||
| `timeouts.me_one_retry` | `u8` | `12` | нет | Количество быстрых reconnect-попыток для DC с одним endpoint. | `me_one_retry = 6` |
|
||||
| `network.stun_servers` | `Vec<String>` | встроенный публичный пул | удаляются дубликаты и пустые значения | Основной список STUN-серверов для определения внешнего адреса и порта за NAT. | `stun_servers = ["stun1.l.google.com:19302"]` |
|
||||
| `network.stun_tcp_fallback` | `bool` | `true` | нет | Разрешает резервную проверку по TCP, когда STUN по UDP недоступен. | `stun_tcp_fallback = true` |
|
||||
| `network.http_ip_detect_urls` | `Vec<String>` | `ifconfig.me` + `api.ipify.org` | нет | Резервные HTTP-сервисы для определения публичного IPv4 при недоступности STUN. | `http_ip_detect_urls = ["https://api.ipify.org"]` |
|
||||
| `general.stun_iface_mismatch_ignore` | `bool` | `false` | нет | Зарезервированный флаг; в текущей ревизии не влияет на работу. | `stun_iface_mismatch_ignore = false` |
|
||||
| `timeouts.me_one_retry` | `u8` | `12` | нет | Число быстрых повторных подключений для DC с одним адресом подключения. | `me_one_retry = 6` |
|
||||
| `timeouts.me_one_timeout_ms` | `u64` | `1200` | нет | Таймаут одной быстрой попытки (мс). | `me_one_timeout_ms = 1500` |
|
||||
|
||||
### 2) Размер пула, keepalive и reconnect-политика
|
||||
|
||||
| Параметр | Тип | Default | Ограничения / валидация | Влияние на runtime | Пример |
|
||||
| Параметр | Тип | По умолчанию | Ограничения / валидация | Влияние на работу | Пример |
|
||||
|---|---|---:|---|---|---|
|
||||
| `general.middle_proxy_pool_size` | `usize` | `8` | нет | Не влияющий на enforcement compatibility/startup-log input; active writer targets определяет DC-family floor policy. | `middle_proxy_pool_size = 12` |
|
||||
| `general.middle_proxy_warm_standby` | `usize` | `16` | нет | Зарезервированное поле совместимости в текущей ревизии (активного runtime-consumer нет). | `middle_proxy_warm_standby = 16` |
|
||||
| `general.middle_proxy_pool_size` | `usize` | `8` | нет | Поле совместимости и стартового журнала. Целевое число активных ME Writer задаёт политика минимального покрытия групп «DC + семейство IP». | `middle_proxy_pool_size = 12` |
|
||||
| `general.middle_proxy_warm_standby` | `usize` | `16` | нет | Поле совместимости; в текущей ревизии не влияет на работу. | `middle_proxy_warm_standby = 16` |
|
||||
| `general.me_keepalive_enabled` | `bool` | `true` | нет | Включает периодические keepalive/ping кадры ME. | `me_keepalive_enabled = true` |
|
||||
| `general.me_keepalive_interval_secs` | `u64` | `8` | нет | Базовый интервал keepalive (сек). | `me_keepalive_interval_secs = 20` |
|
||||
| `general.me_keepalive_jitter_secs` | `u64` | `2` | нет | Джиттер keepalive для предотвращения синхронных всплесков. | `me_keepalive_jitter_secs = 3` |
|
||||
| `general.me_keepalive_payload_random` | `bool` | `true` | нет | Рандомизирует payload keepalive-кадров. | `me_keepalive_payload_random = true` |
|
||||
| `general.me_warmup_stagger_enabled` | `bool` | `true` | нет | Включает staggered warmup дополнительных ME-коннектов. | `me_warmup_stagger_enabled = true` |
|
||||
| `general.me_warmup_step_delay_ms` | `u64` | `500` | нет | Базовая задержка между шагами warmup (мс). | `me_warmup_step_delay_ms = 300` |
|
||||
| `general.me_warmup_step_jitter_ms` | `u64` | `300` | нет | Дополнительный случайный warmup-джиттер (мс). | `me_warmup_step_jitter_ms = 200` |
|
||||
| `general.me_reconnect_max_concurrent_per_dc` | `u32` | `8` | нет | Ограничивает параллельные reconnect worker'ы на один DC. | `me_reconnect_max_concurrent_per_dc = 12` |
|
||||
| `general.me_reconnect_backoff_base_ms` | `u64` | `500` | нет | Начальный backoff reconnect (мс). | `me_reconnect_backoff_base_ms = 250` |
|
||||
| `general.me_reconnect_backoff_cap_ms` | `u64` | `30000` | нет | Верхняя граница backoff reconnect (мс). | `me_reconnect_backoff_cap_ms = 10000` |
|
||||
| `general.me_reconnect_fast_retry_count` | `u32` | `16` | нет | Бюджет быстрых retry до длинного backoff. | `me_reconnect_fast_retry_count = 8` |
|
||||
| `general.me_writer_byte_budget_bytes` | `usize` | `33570816` | кратно `16384`; динамический минимум для `max_client_frame`; максимум `268435456` | Ограниченные byte permits для исходящей staging queue каждого ME writer. | `me_writer_byte_budget_bytes = 33570816` |
|
||||
| `general.me_keepalive_payload_random` | `bool` | `true` | нет | Добавляет случайные данные в полезную нагрузку кадров keepalive. | `me_keepalive_payload_random = true` |
|
||||
| `general.me_warmup_stagger_enabled` | `bool` | `true` | нет | Готовит дополнительные ME-соединения постепенно. | `me_warmup_stagger_enabled = true` |
|
||||
| `general.me_warmup_step_delay_ms` | `u64` | `500` | нет | Базовая задержка между шагами подготовки соединений, мс. | `me_warmup_step_delay_ms = 300` |
|
||||
| `general.me_warmup_step_jitter_ms` | `u64` | `300` | нет | Дополнительный случайный разброс задержки при подготовке соединений, мс. | `me_warmup_step_jitter_ms = 200` |
|
||||
| `general.me_reconnect_max_concurrent_per_dc` | `u32` | `8` | нет | Ограничивает число параллельных задач повторного подключения для одного DC. | `me_reconnect_max_concurrent_per_dc = 12` |
|
||||
| `general.me_reconnect_backoff_base_ms` | `u64` | `500` | нет | Начальная задержка перед повторным подключением, мс. | `me_reconnect_backoff_base_ms = 250` |
|
||||
| `general.me_reconnect_backoff_cap_ms` | `u64` | `30000` | нет | Верхняя граница задержки перед повторным подключением, мс. | `me_reconnect_backoff_cap_ms = 10000` |
|
||||
| `general.me_reconnect_fast_retry_count` | `u32` | `16` | нет | Число быстрых повторных попыток до перехода к увеличенным задержкам. | `me_reconnect_fast_retry_count = 8` |
|
||||
| `general.me_writer_byte_budget_bytes` | `usize` | `33570816` | кратно `16384`; динамический минимум для `max_client_frame`; максимум `268435456` | Лимит байтов, зарезервированных для исходящей очереди каждого ME Writer. | `me_writer_byte_budget_bytes = 33570816` |
|
||||
|
||||
### 3) Reinit/hardswap, ротация секрета и деградация
|
||||
|
||||
| Параметр | Тип | Default | Ограничения / валидация | Влияние на runtime | Пример |
|
||||
| Параметр | Тип | По умолчанию | Ограничения / валидация | Влияние на работу | Пример |
|
||||
|---|---|---:|---|---|---|
|
||||
| `general.hardswap` | `bool` | `true` | нет | Включает generation-based стратегию hardswap для ME-пула. | `hardswap = true` |
|
||||
| `general.me_reinit_every_secs` | `u64` | `900` | должно быть `> 0` | Интервал периодического reinit ME-пула. | `me_reinit_every_secs = 600` |
|
||||
| `general.me_reinit_singleflight` | `bool` | `true` | нет | Сериализует reinit cycles из всех trigger sources. | `me_reinit_singleflight = true` |
|
||||
| `general.me_reinit_max_concurrency` | `usize` | `2` | диапазон `[1,8]`; эффективное значение `1` при singleflight | Ограничивает параллельные generation warmup; дополнительные triggers объединяются в один rerun. | `me_reinit_max_concurrency = 2` |
|
||||
| `general.me_reinit_trigger_channel` | `usize` | `64` | диапазон `[1,4096]` | Ограничивает очередь reinit triggers в каждом runtime generation. | `me_reinit_trigger_channel = 64` |
|
||||
| `general.me_reinit_coalesce_window_ms` | `u64` | `200` | нет | Объединяет burst triggers перед одним reinit cycle. | `me_reinit_coalesce_window_ms = 200` |
|
||||
| `general.me_hardswap_warmup_delay_min_ms` | `u64` | `1000` | должно быть `<= me_hardswap_warmup_delay_max_ms` | Нижняя граница пауз между warmup dial попытками. | `me_hardswap_warmup_delay_min_ms = 500` |
|
||||
| `general.me_hardswap_warmup_delay_max_ms` | `u64` | `2000` | должно быть `> 0` | Верхняя граница пауз между warmup dial попытками. | `me_hardswap_warmup_delay_max_ms = 1200` |
|
||||
| `general.me_hardswap_warmup_extra_passes` | `u8` | `3` | диапазон `[0,10]` | Дополнительные warmup-проходы после базового. | `me_hardswap_warmup_extra_passes = 2` |
|
||||
| `general.me_hardswap_warmup_pass_backoff_base_ms` | `u64` | `500` | должно быть `> 0` | Базовый backoff между extra-pass в warmup. | `me_hardswap_warmup_pass_backoff_base_ms = 400` |
|
||||
| `general.me_config_stable_snapshots` | `u8` | `2` | должно быть `> 0` | Количество одинаковых snapshot перед применением ME map update. | `me_config_stable_snapshots = 3` |
|
||||
| `general.me_config_apply_cooldown_secs` | `u64` | `300` | нет | Cooldown между применёнными обновлениями ME map. | `me_config_apply_cooldown_secs = 120` |
|
||||
| `general.proxy_secret_stable_snapshots` | `u8` | `2` | должно быть `> 0` | Количество одинаковых snapshot перед runtime-rotation proxy-secret. | `proxy_secret_stable_snapshots = 3` |
|
||||
| `general.proxy_secret_rotate_runtime` | `bool` | `true` | нет | Включает runtime-ротацию proxy-secret. | `proxy_secret_rotate_runtime = true` |
|
||||
| `general.hardswap` | `bool` | `true` | нет | Включает смену поколений пула ME по стратегии hardswap. | `hardswap = true` |
|
||||
| `general.me_reinit_every_secs` | `u64` | `900` | должно быть `> 0` | Интервал периодической переинициализации пула ME. | `me_reinit_every_secs = 600` |
|
||||
| `general.me_reinit_singleflight` | `bool` | `true` | нет | Выполняет переинициализации последовательно независимо от источника запроса. | `me_reinit_singleflight = true` |
|
||||
| `general.me_reinit_max_concurrency` | `usize` | `2` | диапазон `[1,8]`; эффективное значение `1` при singleflight | Ограничивает параллельную подготовку поколений; дополнительные запросы объединяются в один повторный запуск. | `me_reinit_max_concurrency = 2` |
|
||||
| `general.me_reinit_trigger_channel` | `usize` | `64` | диапазон `[1,4096]` | Ограничивает очередь запросов переинициализации в каждом поколении. | `me_reinit_trigger_channel = 64` |
|
||||
| `general.me_reinit_coalesce_window_ms` | `u64` | `200` | нет | Объединяет всплеск запросов в один цикл переинициализации. | `me_reinit_coalesce_window_ms = 200` |
|
||||
| `general.me_hardswap_warmup_delay_min_ms` | `u64` | `1000` | должно быть `<= me_hardswap_warmup_delay_max_ms` | Нижняя граница паузы между попытками подключения при подготовке поколения. | `me_hardswap_warmup_delay_min_ms = 500` |
|
||||
| `general.me_hardswap_warmup_delay_max_ms` | `u64` | `2000` | должно быть `> 0` | Верхняя граница паузы между попытками подключения при подготовке поколения. | `me_hardswap_warmup_delay_max_ms = 1200` |
|
||||
| `general.me_hardswap_warmup_extra_passes` | `u8` | `3` | диапазон `[0,10]` | Число дополнительных проходов подготовки после основного. | `me_hardswap_warmup_extra_passes = 2` |
|
||||
| `general.me_hardswap_warmup_pass_backoff_base_ms` | `u64` | `500` | должно быть `> 0` | Базовая задержка между дополнительными проходами подготовки. | `me_hardswap_warmup_pass_backoff_base_ms = 400` |
|
||||
| `general.me_config_stable_snapshots` | `u8` | `2` | должно быть `> 0` | Число одинаковых снимков карты ME, необходимых перед её обновлением. | `me_config_stable_snapshots = 3` |
|
||||
| `general.me_config_apply_cooldown_secs` | `u64` | `300` | нет | Минимальная пауза между применёнными обновлениями карты ME. | `me_config_apply_cooldown_secs = 120` |
|
||||
| `general.proxy_secret_stable_snapshots` | `u8` | `2` | должно быть `> 0` | Число одинаковых снимков секрета перед его заменой во время работы. | `proxy_secret_stable_snapshots = 3` |
|
||||
| `general.proxy_secret_rotate_runtime` | `bool` | `true` | нет | Разрешает замену инфраструктурного секрета без перезапуска процесса. | `proxy_secret_rotate_runtime = true` |
|
||||
| `general.proxy_secret_len_max` | `usize` | `256` | диапазон `[32,4096]` | Верхний лимит длины принимаемого proxy-secret. | `proxy_secret_len_max = 512` |
|
||||
| `general.update_every` | `Option<u64>` | `300` | если задано: `> 0`; если `null`: fallback на legacy минимум | Единый интервал refresh для ME config + secret updater. | `update_every = 300` |
|
||||
| `general.me_pool_drain_ttl_secs` | `u64` | `90` | нет | Возрастной порог предупреждений о долгом drain и нижняя граница нормализации force-close timeout; stale binds он не разрешает. | `me_pool_drain_ttl_secs = 120` |
|
||||
| `general.me_bind_stale_mode` | `"never"`, `"ttl"` или `"always"` | `"never"` | нет | Управляет новыми bindings на draining stale writers для непокрытых DC-family groups. | `me_bind_stale_mode = "never"` |
|
||||
| `general.me_bind_stale_ttl_secs` | `u64` | `90` | нет | Окно stale-bind только для `me_bind_stale_mode = "ttl"`; `0` отключает TTL expiry для разрешённых draining writers. | `me_bind_stale_ttl_secs = 90` |
|
||||
| `general.me_pool_min_fresh_ratio` | `f32` | `0.8` | диапазон `[0.0,1.0]` | Минимальная доля fresh DC-family coverage при commit. | `me_pool_min_fresh_ratio = 0.9` |
|
||||
| `general.me_reinit_drain_timeout_secs` | `u64` | `90` | `0` использует safety fallback 300 секунд; effective value ниже drain TTL повышается до TTL | Таймаут force-close для draining stale writer. | `me_reinit_drain_timeout_secs = 0` |
|
||||
| `general.auto_degradation_enabled` | `bool` | `true` | нет | Зарезервированный флаг совместимости в текущей ревизии (активного runtime-consumer нет). | `auto_degradation_enabled = true` |
|
||||
| `general.degradation_min_unavailable_dc_groups` | `u8` | `2` | нет | Зарезервированный порог совместимости в текущей ревизии (активного runtime-consumer нет). | `degradation_min_unavailable_dc_groups = 2` |
|
||||
| `general.update_every` | `Option<u64>` | `300` | если задано: `> 0`; при отсутствии с явно заданными старыми ключами — их минимум | Общий интервал обновления карты ME и инфраструктурного секрета. | `update_every = 300` |
|
||||
| `general.me_pool_drain_ttl_secs` | `u64` | `90` | нет | Порог предупреждения о долгом завершении обслуживания и нижняя граница таймаута принудительного закрытия. Не разрешает новые привязки к старым соединениям. | `me_pool_drain_ttl_secs = 120` |
|
||||
| `general.me_bind_stale_mode` | `"never"`, `"ttl"` или `"always"` | `"never"` | нет | Разрешает или запрещает новые привязки к старым ME Writer для групп «DC + семейство IP», не обеспеченных новым поколением. | `me_bind_stale_mode = "never"` |
|
||||
| `general.me_bind_stale_ttl_secs` | `u64` | `90` | нет | Срок допуска старых соединений только для режима `ttl`; `0` отключает истечение этого срока для разрешённых ME Writer. | `me_bind_stale_ttl_secs = 90` |
|
||||
| `general.me_pool_min_fresh_ratio` | `f32` | `0.8` | диапазон `[0.0,1.0]` | Минимальная доля групп «DC + семейство IP», обеспеченных новым поколением перед переходом. | `me_pool_min_fresh_ratio = 0.9` |
|
||||
| `general.me_reinit_drain_timeout_secs` | `u64` | `90` | `0` означает резервный срок 300 секунд; значение ниже срока drain повышается до него | Срок до принудительного закрытия старых ME Writer, завершающих обслуживание. | `me_reinit_drain_timeout_secs = 0` |
|
||||
| `general.auto_degradation_enabled` | `bool` | `true` | нет | Флаг совместимости; в текущей ревизии не влияет на работу. | `auto_degradation_enabled = true` |
|
||||
| `general.degradation_min_unavailable_dc_groups` | `u8` | `2` | нет | Порог совместимости; в текущей ревизии не влияет на работу. | `degradation_min_unavailable_dc_groups = 2` |
|
||||
|
||||
Candidate generation hardswap авторитетна только для того же desired-map hash и endpoint revision. Повторные попытки переиспользуют pending generation не более 1800 секунд; после TTL создаётся новая generation. Commit повторно проверяет authority и требует fresh DC-family coverage не ниже `me_pool_min_fresh_ratio`. Отсутствующие groups блокируют commit при `me_bind_stale_mode = "never"`; `ttl` или `always` позволяют commit с ограниченным policy stale fallback для этих groups. Покрытые старые writers могут сразу перейти в retirement, поэтому hardswap является атомарной сменой policy, а не универсальной zero-drop гарантией.
|
||||
Подготовленное для hardswap поколение можно применить только при неизменных хеше требуемой карты ME и ревизии адресов подключения. При повторных попытках оно используется не дольше 1800 секунд, после чего создаётся новое. Перед фиксацией перехода Telemt заново проверяет эти условия и долю групп «DC + семейство IP», обеспеченных новыми соединениями: она должна быть не ниже `me_pool_min_fresh_ratio`. При `me_bind_stale_mode = "never"` отсутствие любой группы блокирует переход. Режимы `ttl` и `always` допускают для таких групп резервное использование старых соединений в пределах выбранной политики. Старые ME Writer для уже обеспеченных групп могут сразу выводиться из обслуживания. Поэтому атомарность смены политики не означает, что hardswap гарантированно сохранит все соединения.
|
||||
|
||||
Writer replacement использует отдельное cancellation-safe состояние `Open -> Preparing -> Retiring`. `Preparing` запрещает дублирующую replacement work, но разрешает новые binds. Под registry binding guard commit повторно проверяет victim, переводит его в `Retiring`, чтобы запретить новые binds, устанавливает и публикует successor и начинает drain predecessor до освобождения guard. Отмена reservation до этой commit boundary возвращает `Open`.
|
||||
Замена отдельного ME Writer использует состояния `Open -> Preparing -> Retiring` и корректно обрабатывает отмену операции. В `Preparing` нельзя запустить вторую замену того же компонента, но можно привязывать к нему новые потоки. При фиксации замены Telemt под блокировкой реестра привязок заново проверяет заменяемый ME Writer, переводит его в `Retiring`, запрещая новые привязки, устанавливает и публикует замену и начинает завершение обслуживания прежнего компонента. Только после этого блокировка снимается. Отмена резервирования до этой границы возвращает состояние `Open`.
|
||||
|
||||
Возраст pending generation, число и дефицит writers, отсутствующие DC groups, актуальность map, orphan warm writers и фазы `preparing`/`retiring` доступны через `/v1/runtime/me_pool_state`. Соответствующие gauges `telemt_me_hardswap_*` и `telemt_me_writer_replacement_current` равны нулю, когда ME telemetry имеет уровень `silent` или активный ME snapshot недоступен. В Prometheus `telemt_me_hardswap_pending_map_current` следует проверять вместе с `telemt_me_hardswap_pending`: нулевая map currency также означает отсутствие pending generation, тогда как API возвращает `null`. Настройте alerts на pending age около 1800 секунд, устойчивый deficit или missing groups, stale map, orphan warm writers и не сходящиеся replacement phases.
|
||||
Эндпоинт `/v1/runtime/me_pool_state` показывает возраст ожидающего поколения, число и дефицит ME Writer, отсутствующие группы DC, актуальность карты, подготовленные соединения без владельца и фазы `preparing`/`retiring`. Метрики `telemt_me_hardswap_*` и `telemt_me_writer_replacement_current` равны нулю при уровне ME-телеметрии `silent` или отсутствии активного снимка состояния. Проверяйте `telemt_me_hardswap_pending_map_current` вместе с `telemt_me_hardswap_pending`: ноль может означать отсутствие ожидающего поколения, а не устаревшую карту. В таком случае API возвращает `null`. Настройте оповещения при возрасте ожидающего поколения около 1800 секунд, устойчивом дефиците соединений или групп, устаревшей карте, подготовленных соединениях без владельца и затянувшихся фазах замены.
|
||||
|
||||
## Устаревшие / legacy параметры
|
||||
## Устаревшие параметры
|
||||
|
||||
| Параметр | Статус | Замена | Текущее поведение | Рекомендация миграции |
|
||||
|---|---|---|---|---|
|
||||
| `general.middle_proxy_nat_stun` | Deprecated | `network.stun_servers` | Добавляется в `network.stun_servers`, только если `network.stun_servers` не задан явно. | Перенести значение в `network.stun_servers`, legacy-ключ удалить. |
|
||||
| `general.middle_proxy_nat_stun_servers` | Deprecated | `network.stun_servers` | Добавляется в `network.stun_servers`, только если `network.stun_servers` не задан явно. | Перенести значения в `network.stun_servers`, legacy-ключ удалить. |
|
||||
| `general.proxy_secret_auto_reload_secs` | Deprecated | `general.update_every` | Используется только если `update_every = null` (legacy fallback). | Явно задать `general.update_every`, legacy-ключ удалить. |
|
||||
| `general.proxy_config_auto_reload_secs` | Deprecated | `general.update_every` | Используется только если `update_every = null` (legacy fallback). | Явно задать `general.update_every`, legacy-ключ удалить. |
|
||||
| `general.middle_proxy_nat_stun` | Устарел | `network.stun_servers` | Добавляется в `network.stun_servers`, только если `network.stun_servers` не задан явно. | Перенести значение в `network.stun_servers`, старый ключ удалить. |
|
||||
| `general.middle_proxy_nat_stun_servers` | Устарел | `network.stun_servers` | Добавляется в `network.stun_servers`, только если `network.stun_servers` не задан явно. | Перенести значения в `network.stun_servers`, старый ключ удалить. |
|
||||
| `general.proxy_secret_auto_reload_secs` | Устарел | `general.update_every` | Используется, если `update_every` отсутствует, а старые интервалы заданы явно. | Явно задать `general.update_every`, старый ключ удалить. |
|
||||
| `general.proxy_config_auto_reload_secs` | Устарел | `general.update_every` | Используется, если `update_every` отсутствует, а старые интервалы заданы явно. | Явно задать `general.update_every`, старый ключ удалить. |
|
||||
|
||||
## Как конфигурируются Upstreams
|
||||
|
||||
### Схема upstream
|
||||
|
||||
| Поле | Применимость | Тип | Обязательно | Default | Назначение |
|
||||
| Поле | Применимость | Тип | Обязательно | По умолчанию | Назначение |
|
||||
|---|---|---|---|---|---|
|
||||
| `[[upstreams]].type` | все upstream | `"direct" \| "socks4" \| "socks5" \| "shadowsocks"` | да | n/a | Тип upstream транспорта. |
|
||||
| `[[upstreams]].weight` | все upstream | `u16` | нет | `1` | Базовый вес в weighted-random выборе. |
|
||||
@@ -114,7 +118,7 @@ Writer replacement использует отдельное cancellation-safe с
|
||||
| `url` | `shadowsocks` | `String` | да | n/a | Shadowsocks SIP002 URL (`ss://...`). В runtime API раскрывается только `host:port`. |
|
||||
| `interface` | `shadowsocks` | `Option<String>` | нет | `null` | Необязательный исходящий bind-интерфейс или literal локальный IP. |
|
||||
|
||||
### Runtime-правила
|
||||
### Правила выбора соединения
|
||||
|
||||
1. Если `[[upstreams]]` отсутствует, loader добавляет один upstream `direct` по умолчанию.
|
||||
2. Scope-фильтрация — по точному совпадению токена:
|
||||
@@ -135,7 +139,7 @@ Writer replacement использует отдельное cancellation-safe с
|
||||
10. В ME-режиме через SOCKS корректные публичные `BND.ADDR/BND.PORT` с ненулевым портом задают полный исходный кортеж KDF. Семейство адреса должно совпадать с логическим ME-назначением независимо от семейства TCP-соединения к SOCKS. Для IPv4-mapped назначения нужен обычный IPv4 BND; IPv4-compatible IPv6 остаётся IPv6.
|
||||
11. `shadowsocks` upstream требует `general.use_middle_proxy = false`. При включенном ME-режиме конфиг отклоняется при загрузке.
|
||||
|
||||
## Примеры конфигурации Upstreams
|
||||
## Примеры настройки апстримов
|
||||
|
||||
### Пример 1: минимальный direct upstream
|
||||
|
||||
@@ -182,26 +186,35 @@ weight = 2
|
||||
enabled = true
|
||||
```
|
||||
|
||||
### Пример 5: смешанные upstream с scopes
|
||||
### Выбор апстрима по имени пользователя
|
||||
|
||||
В Direct-режиме пользователь `scope_premium` выбирает точный scope `premium`. Часть имени после `scope_` должна содержать 1–64 латинские буквы ASCII, цифры или дефисы. Пустой или некорректный суффикс включает обычный выбор без scope. Если корректный scope задан, но подходящего апстрима нет, соединение завершается ошибкой; перехода на маршрут без scope не происходит. Метки scope не создают пользователей и не заменяют аутентификацию.
|
||||
|
||||
При выборе scope его строка подставляется вместо `user_id` SOCKS4 и вместо имени и пароля SOCKS5. В этом примере SOCKS5-сервер должен принимать `premium` и как имя, и как пароль. Обычные пользователи выбирают прямой маршрут без scope. Перед использованием замените секрет и адрес SOCKS-сервера.
|
||||
|
||||
```toml
|
||||
[general]
|
||||
use_middle_proxy = false
|
||||
|
||||
[access.users]
|
||||
scope_premium = "0123456789abcdef0123456789abcdef"
|
||||
|
||||
[[upstreams]]
|
||||
type = "direct"
|
||||
weight = 5
|
||||
enabled = true
|
||||
scopes = ""
|
||||
|
||||
[[upstreams]]
|
||||
type = "socks5"
|
||||
address = "203.0.113.40:1080"
|
||||
username = "edge"
|
||||
password = "edgepass"
|
||||
weight = 3
|
||||
enabled = true
|
||||
scopes = "premium,me"
|
||||
username = "premium"
|
||||
password = "premium"
|
||||
scopes = "premium"
|
||||
```
|
||||
|
||||
### Пример 5: профиль тюнинга под ME
|
||||
Этот механизм выбора по пользователю действует в Direct-режиме. При подключении ME пользовательский scope сейчас не передаётся: метка `me` сама по себе не выбирает апстрим ME. Для получения TLS-профилей применяется отдельная настройка `censorship.tls_fetch_scope`. См. [правила фильтрации](../Config_params/CONFIG_PARAMS.ru.md#scopes).
|
||||
|
||||
|
||||
### Пример 6: профиль настройки ME
|
||||
|
||||
```toml
|
||||
[general]
|
||||
|
||||
@@ -222,6 +222,7 @@ operations or pending publication; they are not silently promoted to success.
|
||||
| `GET /v1/users` | Returns disk-first user views sorted by username. |
|
||||
| `POST /v1/users` | Creates a user and returns the effective user view plus secret. |
|
||||
| `GET /v1/users/{username}` | Returns one disk-first user view or `404` when absent. |
|
||||
| `GET /v1/users/{username}/links?transport=web` | Credential-bearing WEB links for this user's exact profiles; effective by default, explicitly unusable desired preview available. |
|
||||
| `PATCH /v1/users/{username}` | Updates selected per-user fields with JSON Merge Patch semantics. |
|
||||
| `DELETE /v1/users/{username}` | Deletes one user and related API-managed per-user access-map entries. It does not modify `access.user_source_deny`. |
|
||||
| `POST /v1/users/{username}/rotate-secret` | Rotates one user's secret and returns the effective secret. |
|
||||
@@ -234,6 +235,7 @@ operations or pending publication; they are not silently promoted to success.
|
||||
| HTTP | `error.code` | Trigger |
|
||||
| --- | --- | --- |
|
||||
| `400` | `bad_request` | Invalid JSON, validation failures, malformed request body. |
|
||||
| `400` | `too_many_links` | WEB link projection exceeds 4096 rows; no partial link response is returned. |
|
||||
| `400` | `access_not_editable` | `PATCH /v1/config` body contains an `access` key (managed via users API). |
|
||||
| `400` | `section_not_editable` | `PATCH /v1/config` body contains an unknown top-level key or a non-null, non-object partial section. |
|
||||
| `400` | `field_not_editable` | `PATCH /v1/config` body contains a forbidden nested field under a partially editable section (e.g. `server.api.auth_header`, `server.port`, `network.ipv4`). |
|
||||
@@ -243,7 +245,7 @@ operations or pending publication; they are not silently promoted to success.
|
||||
| `404` | `not_found` | Unknown route, unknown user, or unsupported sub-route. |
|
||||
| `405` | `method_not_allowed` | Unsupported method for `/v1/users/{username}` route shape. |
|
||||
| `409` | `revision_conflict` | `If-Match` mismatch, or the source graph/owner changed during a fenced write. |
|
||||
| `409` | `runtime_conflict` | Active generation/config publication changed during config preparation, or `If-Runtime-Match` is stale. |
|
||||
| `409` | `runtime_conflict` | Active generation/config publication changed during config preparation, `If-Runtime-Match` is stale, or WEB link configuration/admission changed while being sampled. |
|
||||
| `429` | `config_preflight_busy` | Both config preflight preparation slots are occupied. |
|
||||
| `504` | `config_preflight_timeout` | Config preflight exceeded its 30-second deadline. |
|
||||
| `409` | `reload_in_progress` | Another reload operation is non-terminal. |
|
||||
@@ -294,9 +296,8 @@ applied. Reading that revision requires the source graph to remain readable.
|
||||
### CapabilitiesData
|
||||
|
||||
Top-level fields are `api_version` (`v1`), `schema_version` (`1`),
|
||||
`software_version`, `config_schema`, `openapi_artifact`, `read_only`,
|
||||
`availability_scope`, and `operations`. `openapi_artifact` identifies the versioned
|
||||
repository artifact; it is not another HTTP route.
|
||||
`software_version`, `config_schema`, `read_only`, `availability_scope`, and
|
||||
`operations`.
|
||||
|
||||
Each operation has a stable `id`, `method`, canonical `path`, optional `aliases`,
|
||||
`gate`, possible success status codes in `success`, `credential_bearing`, optional
|
||||
@@ -371,20 +372,19 @@ validation, and reset is unsupported. One mutation may touch only one independen
|
||||
writable source. This differs from supported user PATCH fields, where null
|
||||
removes an override. Discovery does not expand either write allowlist.
|
||||
|
||||
### Versioned artifact and maintenance
|
||||
### Contract maintenance
|
||||
|
||||
[openapi-v1.json](openapi-v1.json) publishes the implemented routes, aliases,
|
||||
request shapes and common response envelopes, with detailed schemas for both
|
||||
discovery responses. Legacy response payloads and query filters remain described
|
||||
in this reference. The artifact is intentionally not a complete configuration
|
||||
validator; `/v1/config/schema` supplements it with field contracts.
|
||||
`GET /v1/capabilities` lists implemented routes, aliases and operation metadata;
|
||||
`GET /v1/config/schema` describes configuration field contracts. Request shapes,
|
||||
response envelopes and query filters are documented in this reference.
|
||||
|
||||
Regenerate with `python3 tools/generate_api_openapi.py` and verify with
|
||||
`python3 tools/generate_api_openapi.py --check`. `cargo test --bin telemt
|
||||
api::discovery` checks route/field inventories, defaults, enums, application
|
||||
classification, credential exclusion and HTTP admission. Contract changes must
|
||||
update the registry and artifact together. Additive metadata and operations are
|
||||
compatible; incompatible discovery changes require a new `schema_version`.
|
||||
`cargo test --bin telemt api::discovery` checks the operation catalog directly
|
||||
against routing, plus field inventories, defaults, enums, application
|
||||
classification, credential exclusion and HTTP admission. The Python client
|
||||
suite checks user fields against the Rust request DTOs. Contract changes must
|
||||
update the runtime registries, request DTOs, clients and documentation together.
|
||||
Additive metadata and operations are compatible; incompatible discovery changes
|
||||
require a new `schema_version`.
|
||||
|
||||
## Body and JSON Semantics
|
||||
|
||||
@@ -1832,7 +1832,7 @@ JA3 follows the Salesforce ClientHello field order. JA4 follows the FoxIO TLS-cl
|
||||
|
||||
#### `UserLinks`
|
||||
|
||||
`UserLinks` contains only native MTProxy links. It never contains a WEB `tg://webproxy` link; WEB links use a separate startup-only derivation contract based on every configured exact hostname selected by `web.vhosts[].host` or `hosts` (never a wildcard pattern), `base_path`, and profile secret mode.
|
||||
`UserLinks` contains only native MTProxy links. WEB `tg://webproxy` links are available separately through [WEB user links](#web-user-links), using the same formatter as startup output and each exact hostname selected by `web.vhosts[].host` or `hosts`, `base_path`, and profile secret mode.
|
||||
|
||||
| Field | Type | Description |
|
||||
| --- | --- | --- |
|
||||
@@ -1859,6 +1859,71 @@ Link generation uses active config and enabled modes:
|
||||
- Final compatibility fallback uses `listen_addr_ipv4`/`listen_addr_ipv6` when routable, otherwise `"UNKNOWN"`.
|
||||
- User rows are sorted by `username` in ascending lexical order.
|
||||
|
||||
### WEB user links
|
||||
|
||||
`GET /v1/users/{username}/links?transport=web` returns the common success envelope
|
||||
with the captured desired-source revision. `transport=web` is required;
|
||||
`view=effective` is the default and `view=desired` requests a preview. Unknown,
|
||||
duplicate or invalid query parameters return `400 bad_request`. The endpoint
|
||||
inherits API authentication, whitelist and enabled gates, permits `read_only`,
|
||||
and advertises `credential_bearing=true` in capabilities.
|
||||
|
||||
| Data field | Type | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `username`, `transport`, `view` | `string` | Requested user, `web`, and `effective` or `desired`. |
|
||||
| `state` | `string` | `available`, `pending`, `unavailable`, or `preview`. |
|
||||
| `usable` | `bool` | True only for an available effective projection passing the checks below. |
|
||||
| `reason` | optional `string` | Stable state reason; absent for available links. |
|
||||
| `runtime` | object | Sampled active `active_generation`, `config_epoch`, and opaque `runtime_match`, also when returning a desired preview. |
|
||||
| `admission_epoch`, `web_lifecycle_epoch` | `u64` | Sampled process user-admission and WEB publication epochs. |
|
||||
| `links` | object array | At most 4096 rows, each with `host`, `base_path`, `secret_mode`, and credential-bearing `link`. |
|
||||
|
||||
Only profiles belonging to the route user are included. `host` and `hosts`
|
||||
expand to exact normalized hostnames; wildcard selectors are never links.
|
||||
`base_path` is empty for root or a case-preserving path without outer slashes.
|
||||
`secret_mode` is `plain` or `dd`. Root links retain hexadecimal secrets; path
|
||||
links percent-encode `HOST/BASE` and encode `0x70 || client_secret` as unpadded
|
||||
base64url. The startup formatter supplies both representations.
|
||||
`general.links.show`, `public_host` and `public_port` do not filter or override
|
||||
these per-profile API links.
|
||||
|
||||
For `usable=true`, the active config must enable the user and WEB, its prepared
|
||||
exact profile must carry the current credential, and the initialized process
|
||||
admission authority must accept that credential. The sampled desired user must
|
||||
still exist, be enabled and have the same secret. The published WEB lifecycle
|
||||
must be `running` with a retained process runtime, nonempty listener set and open
|
||||
operator/generation admission. This is a configuration/admission snapshot, not a
|
||||
reservation or a guarantee of external TLS reachability, listener health, quota,
|
||||
expiration, source-IP policy, or client connectivity. No bootstrap token or
|
||||
session is issued by this read.
|
||||
|
||||
| State | Reasons and behavior |
|
||||
| --- | --- |
|
||||
| `available` | `usable=true`, nonempty effective links. |
|
||||
| `pending` | `user_pending`, `credential_pending`, `web_pending`, `web_config_pending`, or `profile_pending`; `usable=false`, empty links until publication/credential convergence. |
|
||||
| `unavailable` | `user_disabled`, `user_deleted`, `user_disabled_or_deleted`, `admission_unavailable`, `web_disabled`, `web_unavailable`, `admission_closed`, or `no_exact_profile`; `usable=false`, empty links. |
|
||||
| `preview` | `desired_preview`; encoded desired exact profiles, always `usable=false`, including when WEB is disabled or absent. No DNS resolution or static-site acquisition is performed. |
|
||||
|
||||
Disabled users receive no links in either view. A deleted user still present in
|
||||
the active config returns `unavailable/user_deleted` in the effective view;
|
||||
otherwise a missing user returns `404 not_found`. After secret rotation, old
|
||||
effective credentials are withheld until config, WEB binding and process
|
||||
admission agree. After a base-path edit, the existing effective path can remain
|
||||
available while `view=desired` previews the new path. A generation/config,
|
||||
admission or WEB lifecycle change during the read returns `409 runtime_conflict`
|
||||
without partial links; retry the GET. Invalid/unreadable desired source returns
|
||||
a bounded `500 internal_error` without source text.
|
||||
|
||||
```bash
|
||||
curl -sS 'http://127.0.0.1:9091/v1/users/alice/links?transport=web' \
|
||||
-H "Authorization: ${TELEMT_API_AUTH}"
|
||||
curl -sS 'http://127.0.0.1:9091/v1/users/alice/links?transport=web&view=desired' \
|
||||
-H "Authorization: ${TELEMT_API_AUTH}"
|
||||
```
|
||||
|
||||
The response contains provisioning credentials. Host/path/link details remain
|
||||
absent from general WEB status and Prometheus labels.
|
||||
|
||||
### `CreateUserResponse`
|
||||
| Field | Type | Description |
|
||||
| --- | --- | --- |
|
||||
|
||||
@@ -48,6 +48,7 @@ Existing statistics commands retain their names: `health`, `info`, `status`,
|
||||
| `reload-status ID` | `reload_status(id)` | Read one retained operation. |
|
||||
| `reload-wait ID [--expected-revision REV]` | `wait_reload(id, ...)` | Poll to `succeeded`, `failed` or `rolled_back`. |
|
||||
| `users`, `user NAME` | `list_users()`, `get_user(name)` | User/link responses can carry provisioning secrets. |
|
||||
| `user-links NAME [--transport web] [--view effective]` | `user_links(name, transport="web", view="effective")` | Credential-bearing exact WEB profiles; `view="desired"` always returns an unusable preview. |
|
||||
| `create NAME`, `patch NAME`, `delete NAME` | `create_user()`, `patch_user()`, `delete_user()` | Existing convenience methods and command names remain available. |
|
||||
| `patch NAME --json FILE` or `--clear FIELD` | `patch_user_fields(name, fields)` | Exact omitted/null/value semantics. |
|
||||
| `secret NAME [--secret HEX]` | `rotate_secret(name, ...)` | Implemented rotation endpoint, not a reserved route. |
|
||||
@@ -69,11 +70,24 @@ Existing statistics commands retain their names: `health`, `info`, `status`,
|
||||
| `web-resume --runtime-instance INSTANCE` | `web_resume(instance)` | Resumes operator admission subject to other policy gates. |
|
||||
| `gen-secret` | `TelemtAPI.generate_secret()` | Generates a new 32-hex secret locally. |
|
||||
|
||||
The client covers all 53 JSON operations in the operation catalog. Open the
|
||||
The client covers all 54 JSON operations in the operation catalog. Open the
|
||||
HTML `/web-status` viewer in a browser; it is not decoded as a JSON response.
|
||||
Feature gates and missing runtime planes still return the server's documented
|
||||
errors. Discovery availability is a snapshot, not a reservation.
|
||||
|
||||
WEB provisioning uses the dedicated user-link endpoint. The client sends
|
||||
`transport=web` explicitly and defaults to `view=effective`. It preserves the
|
||||
server's `state`, `usable`, `reason`, runtime identity and link rows; a successful
|
||||
HTTP response alone does not mean a link is usable. After a rotation, retry a
|
||||
pending effective response after configuration publication. A desired preview
|
||||
contains credentials but always has `usable=false`. See the
|
||||
[WEB user-link contract](API.md#web-user-links).
|
||||
|
||||
```bash
|
||||
python3 tools/telemt_api.py user-links alice --json-output
|
||||
python3 tools/telemt_api.py user-links alice --view desired --json-output
|
||||
```
|
||||
|
||||
## Sparse values and user updates
|
||||
|
||||
`create`/`patch` accept `--secret`, `--ad-tag`, `--max-conns`, `--expires`,
|
||||
@@ -294,7 +308,6 @@ Run the local mock HTTP and CLI contract suite from the repository root:
|
||||
|
||||
```bash
|
||||
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tools/tests -v
|
||||
python3 tools/generate_api_openapi.py --check
|
||||
```
|
||||
|
||||
These checks need no live proxy, Telegram connection or deployment credentials.
|
||||
|
||||
@@ -0,0 +1,74 @@
|
||||
# Telemt auf der Kommandozeile
|
||||
|
||||
[English](CLI.en.md) · [Русский](CLI.ru.md) · [Deutsch](CLI.de.md) · [Dokumentation](README.de.md)
|
||||
|
||||
Dieses Handbuch beschreibt die CLI des vorliegenden Quellstands. Prüfen Sie die installierte Version mit `telemt --version` und `telemt --help`. Geben Sie zuerst die Optionen und zuletzt den Konfigurationspfad an. Ohne Pfad verwendet Telemt `config.toml` im Arbeitsverzeichnis.
|
||||
|
||||
## Prozess starten und verwalten
|
||||
|
||||
```bash
|
||||
telemt run --log-level normal /etc/telemt/telemt.toml
|
||||
```
|
||||
|
||||
`run` kann entfallen. Unter systemd oder in einem Container sollte der Prozess im Vordergrund laufen; Start, Stopp und Neustart übernimmt die Dienstverwaltung. Unter Unix unterstützt Telemt auch einen eigenen Daemon-Modus:
|
||||
|
||||
```bash
|
||||
telemt start --pid-file /run/telemt/telemt.pid /etc/telemt/telemt.toml
|
||||
telemt status --pid-file /run/telemt/telemt.pid
|
||||
telemt reload --pid-file /run/telemt/telemt.pid
|
||||
telemt stop --pid-file /run/telemt/telemt.pid
|
||||
```
|
||||
|
||||
Verwenden Sie bei allen Befehlen dieselbe PID-Datei. Ihr Verzeichnis muss vorhanden sein und geeignete Eigentümerrechte haben. `status` prüft den dort verzeichneten Prozess, nicht die Betriebsbereitschaft des Proxys. `reload` sendet SIGHUP an die Konfigurationsüberwachung. Rückgabecode `0` bestätigt die Signalzustellung, nicht die Übernahme aller Einstellungen. Prüfen Sie das Protokoll und die [Regeln zur Konfigurationsübernahme](Config_params/CONFIG_PARAMS.de.md#konfigurationsänderungen-anwenden). Ein Generationswechsel über `POST /v1/system/reload` und ein Prozessneustart sind eigene Vorgänge.
|
||||
|
||||
`stop` sendet SIGTERM und wartet bis zu etwa zehn Sekunden auf das Entfernen der PID-Datei. Nach erfolgreicher Signalzustellung kann der Befehl `0` zurückgeben, obwohl der Prozess noch beendet wird. Prüfen Sie den Prozessstatus, wenn der nächste Schritt einen vollständig beendeten Prozess voraussetzt.
|
||||
|
||||
| Option | Bedeutung |
|
||||
| --- | --- |
|
||||
| `--daemon`, `-d` | Unix-Daemon-Modus; auch `start` aktiviert ihn. |
|
||||
| `--foreground`, `-f` | Prozess im Vordergrund ausführen. |
|
||||
| `--pid-file PATH` | Gemeinsame PID-Datei für Start, `status`, `reload` und `stop`. |
|
||||
| `--run-as-user USER`, `--run-as-group GROUP` | Benutzer und Gruppe des Unix-Prozesses. |
|
||||
| `--working-dir PATH` | Arbeitsverzeichnis des Unix-Prozesses. Ein absoluter Konfigurationspfad ist vorzuziehen. |
|
||||
| `--strict-runtime-paths` | Strengere Prüfung der Laufzeitpfade; bei Start und Daemon-Steuerung einheitlich verwenden. |
|
||||
|
||||
## Funktionsprüfung
|
||||
|
||||
```bash
|
||||
telemt healthcheck --mode liveness /etc/telemt/telemt.toml
|
||||
telemt healthcheck --mode ready /etc/telemt/telemt.toml
|
||||
```
|
||||
|
||||
`liveness` ist der Standardmodus und ruft `GET /v1/health` auf. `ready` ruft `GET /v1/health/ready` auf und verlangt `data.ready = true`. Beide erwarten HTTP `200` und `ok = true`; liveness verlangt zusätzlich `data.status = "ok"`.
|
||||
|
||||
Der Befehl liest API-Adresse und Autorisierungswert aus der angegebenen Konfiguration. Bind-Adressen für alle Schnittstellen werden über Loopback geprüft. Führen Sie den Befehl dort aus, wo die Adresse erreichbar und durch die API-Zugriffsliste zugelassen ist. Er öffnet keine MTProxy-Sitzung und prüft nicht den vollständigen Weg vom Client zu Telegram.
|
||||
|
||||
**Bei `server.api.enabled = false` endet der Befehl mit `0`, ohne eine Netzwerkanfrage zu senden.** Aktivieren Sie die API, bevor Sie das Ergebnis als Nachweis der Erreichbarkeit oder Bereitschaft verwenden. Rückgabecode `1` bedeutet einen Konfigurations- oder Prüffehler; ein ungültiger oder fehlender Wert für `--mode` ergibt `2`. Verbindungsaufbau, Lesen und Schreiben haben jeweils ein Zeitlimit von zwei Sekunden. Das ist keine gemeinsame Frist von zwei Sekunden für den gesamten Befehl.
|
||||
|
||||
## Protokollierung
|
||||
|
||||
| Option | Bedeutung |
|
||||
| --- | --- |
|
||||
| `--log-level LEVEL` | Stufe: `debug`, `verbose`, `normal` oder `silent`. |
|
||||
| `--silent`, `-s` | Informationsmeldungen unterdrücken. |
|
||||
| `--syslog` | Protokolle auf unterstützten Unix-Systemen an syslog senden. |
|
||||
| `--log-file PATH` | In eine Datei schreiben. |
|
||||
| `--log-file-daily PATH` | Dateiprotokollierung mit täglicher Rotation. |
|
||||
| `--log-rotation MODE` | `never`, `minutely`, `hourly`, `daily` oder `weekly`. |
|
||||
| `--log-max-size-bytes N` | Dateigröße als Schwelle für die Rotation. |
|
||||
| `--log-max-files N` | Höchstzahl aufzubewahrender Dateien. |
|
||||
| `--log-max-age-secs N` | Höchstalter aufzubewahrender Dateien in Sekunden. |
|
||||
|
||||
`RUST_LOG` hat Vorrang vor den Einstellungen der Protokollstufe. CLI-Optionen überschreiben die entsprechenden Konfigurationswerte. Pfade, Rotation und Aufbewahrung erklärt die [Referenz zur Protokollierung](Config_params/CONFIG_PARAMS.de.md#logging). Dateiausgabe und syslog schließen einander aus.
|
||||
|
||||
## Erstinstallation erzeugen
|
||||
|
||||
`--init` schreibt Konfigurations- und Dienstdateien und kann den Dienst starten. Es handelt sich um eine Installation, nicht um eine Konfigurationsprüfung; ein erneuter Aufruf kann vorhandene Dateien neu erzeugen. Prüfen und sichern Sie deshalb zuerst eine bestehende Installation.
|
||||
|
||||
```bash
|
||||
telemt --init --port 443 --domain example.com --user alice --config-dir /etc/telemt --no-start
|
||||
```
|
||||
|
||||
Übergeben Sie Optionswerte getrennt vom Optionsnamen, wie im Beispiel. Standardwerte sind Port `443`, Domain `www.google.com`, Benutzer `user` und Verzeichnis `/etc/telemt`. `--secret HEX` setzt ein Benutzergeheimnis aus 32 Hexadezimalzeichen; ohne diese Option wird eines erzeugt. `--no-start` verhindert den Dienststart, schreibt aber weiterhin die Installationsdateien. Diese Standardwerte unterscheiden sich von `install.sh`; die beiden Installationswege sind getrennt zu betrachten.
|
||||
|
||||
Zur API-Automatisierung dienen die englischen Referenzen für die [Control API](Architecture/API/API.md) und den [Python-Client mit CLI](Architecture/API/PYTHON_CLIENT.md). Das Python-Werkzeug ist vom hier beschriebenen Programm `telemt` unabhängig.
|
||||
@@ -0,0 +1,74 @@
|
||||
# Telemt command-line guide
|
||||
|
||||
[English](CLI.en.md) · [Русский](CLI.ru.md) · [Deutsch](CLI.de.md) · [Documentation](README.en.md)
|
||||
|
||||
This guide describes the CLI in this checkout. Check `telemt --version` and `telemt --help` for the installed binary. Put options before the final configuration path; without a path, Telemt uses `config.toml` in the working directory.
|
||||
|
||||
## Run and manage a process
|
||||
|
||||
```bash
|
||||
telemt run --log-level normal /etc/telemt/telemt.toml
|
||||
```
|
||||
|
||||
`run` is optional. Under systemd or in a container, keep the process in the foreground and use the service manager to start, stop and restart it. On Unix, Telemt also supports its own daemon mode:
|
||||
|
||||
```bash
|
||||
telemt start --pid-file /run/telemt/telemt.pid /etc/telemt/telemt.toml
|
||||
telemt status --pid-file /run/telemt/telemt.pid
|
||||
telemt reload --pid-file /run/telemt/telemt.pid
|
||||
telemt stop --pid-file /run/telemt/telemt.pid
|
||||
```
|
||||
|
||||
Use the same PID-file path for all commands and ensure its directory exists with appropriate ownership. `status` checks the process recorded in that file; it does not test proxy readiness. `reload` sends SIGHUP to the configuration watcher. Exit code `0` confirms signal delivery, not successful application of every setting. Check logs and the [configuration application rules](Config_params/CONFIG_PARAMS.en.md#applying-configuration-changes). A generation reload through `POST /v1/system/reload` and a process restart are separate operations.
|
||||
|
||||
`stop` sends SIGTERM and waits up to about ten seconds for PID-file cleanup. A successful signal can still return `0` while shutdown continues; check process status if subsequent work requires it to have exited.
|
||||
|
||||
| Option | Meaning |
|
||||
| --- | --- |
|
||||
| `--daemon`, `-d` | Enable Unix daemon mode; `start` also selects it. |
|
||||
| `--foreground`, `-f` | Keep execution in the foreground. |
|
||||
| `--pid-file PATH` | PID file shared with `status`, `reload` and `stop`. |
|
||||
| `--run-as-user USER`, `--run-as-group GROUP` | Select the account and group for the Unix process. |
|
||||
| `--working-dir PATH` | Working directory for the Unix process. Prefer an absolute configuration path. |
|
||||
| `--strict-runtime-paths` | Apply stricter checks to runtime paths; use consistently for daemon control. |
|
||||
|
||||
## Health checks
|
||||
|
||||
```bash
|
||||
telemt healthcheck --mode liveness /etc/telemt/telemt.toml
|
||||
telemt healthcheck --mode ready /etc/telemt/telemt.toml
|
||||
```
|
||||
|
||||
`liveness` is the default and probes `GET /v1/health`. `ready` probes `GET /v1/health/ready` and requires `data.ready = true`. Both require HTTP `200` and `ok = true`; liveness additionally requires `data.status = "ok"`.
|
||||
|
||||
The command reads the API address and authorization value from the supplied configuration. Wildcard listen addresses are probed through loopback. Run it where that address is reachable and permitted by the API whitelist. It does not open an MTProxy session or verify the complete client-to-Telegram path.
|
||||
|
||||
**If `server.api.enabled = false`, the command exits with `0` without a network probe.** Enable the API before treating this command as evidence of liveness or readiness. Exit code `1` means configuration/probe failure; invalid or missing `--mode` values return `2`. Connect, read and write operations have two-second timeouts; this is not a single two-second deadline for the whole command.
|
||||
|
||||
## Logging
|
||||
|
||||
| Option | Meaning |
|
||||
| --- | --- |
|
||||
| `--log-level LEVEL` | `debug`, `verbose`, `normal` or `silent`. |
|
||||
| `--silent`, `-s` | Suppress informational logging. |
|
||||
| `--syslog` | Send logs to syslog on supported Unix systems. |
|
||||
| `--log-file PATH` | Write logs to a file. |
|
||||
| `--log-file-daily PATH` | Enable file logging with daily rotation. |
|
||||
| `--log-rotation MODE` | `never`, `minutely`, `hourly`, `daily` or `weekly`. |
|
||||
| `--log-max-size-bytes N` | File size threshold for rotation. |
|
||||
| `--log-max-files N` | Retained file count limit. |
|
||||
| `--log-max-age-secs N` | Retained file age limit in seconds. |
|
||||
|
||||
`RUST_LOG` takes precedence over log-level settings. CLI logging options override their configuration counterparts. See [logging configuration](Config_params/CONFIG_PARAMS.en.md#logging) for path, rotation and retention semantics; file and syslog outputs are mutually exclusive.
|
||||
|
||||
## Generate an initial installation
|
||||
|
||||
`--init` writes configuration and service files and can start the service. It is an installation operation, not a configuration validator; running it again can regenerate existing files. Review and back up an existing installation first.
|
||||
|
||||
```bash
|
||||
telemt --init --port 443 --domain example.com --user alice --config-dir /etc/telemt --no-start
|
||||
```
|
||||
|
||||
Use separate option values as shown. Defaults are port `443`, domain `www.google.com`, user `user`, and directory `/etc/telemt`. `--secret HEX` supplies a 32-hex-digit user secret; omitting it generates one. `--no-start` prevents starting the service but still writes installation files. These defaults differ from those of `install.sh`; do not confuse the two installers.
|
||||
|
||||
For API automation, see the [Control API](Architecture/API/API.md) and [Python client and CLI](Architecture/API/PYTHON_CLIENT.md). The Python tool is separate from the `telemt` executable described here.
|
||||
@@ -0,0 +1,74 @@
|
||||
# Командная строка Telemt
|
||||
|
||||
[English](CLI.en.md) · [Русский](CLI.ru.md) · [Deutsch](CLI.de.md) · [Документация](README.ru.md)
|
||||
|
||||
Здесь описан CLI из текущего дерева исходников. Для установленной программы проверьте `telemt --version` и `telemt --help`. Указывайте параметры перед путём к конфигурации, а сам путь — последним. Без пути Telemt использует `config.toml` в рабочем каталоге.
|
||||
|
||||
## Запуск и управление процессом
|
||||
|
||||
```bash
|
||||
telemt run --log-level normal /etc/telemt/telemt.toml
|
||||
```
|
||||
|
||||
Слово `run` можно опустить. Под systemd или в контейнере оставляйте процесс на переднем плане и управляйте им через соответствующую службу. На Unix у Telemt также есть собственный режим демона:
|
||||
|
||||
```bash
|
||||
telemt start --pid-file /run/telemt/telemt.pid /etc/telemt/telemt.toml
|
||||
telemt status --pid-file /run/telemt/telemt.pid
|
||||
telemt reload --pid-file /run/telemt/telemt.pid
|
||||
telemt stop --pid-file /run/telemt/telemt.pid
|
||||
```
|
||||
|
||||
Во всех командах используйте один путь к PID-файлу. Его каталог должен существовать и принадлежать подходящему пользователю. `status` проверяет процесс из PID-файла, но не готовность прокси. `reload` отправляет SIGHUP обработчику изменений конфигурации. Код `0` подтверждает отправку сигнала, а не применение всех настроек. Проверьте журнал и [правила применения конфигурации](Config_params/CONFIG_PARAMS.ru.md#применение-изменений-конфигурации). Смена поколения через `POST /v1/system/reload` и перезапуск процесса — отдельные операции.
|
||||
|
||||
`stop` отправляет SIGTERM и ждёт удаления PID-файла примерно до десяти секунд. После успешной отправки сигнала команда может вернуть `0`, пока завершение ещё продолжается. Если дальнейшая операция требует остановленного процесса, проверьте его состояние.
|
||||
|
||||
| Параметр | Назначение |
|
||||
| --- | --- |
|
||||
| `--daemon`, `-d` | Режим демона Unix; команда `start` также включает его. |
|
||||
| `--foreground`, `-f` | Работа на переднем плане. |
|
||||
| `--pid-file PATH` | PID-файл для запуска и команд `status`, `reload`, `stop`. |
|
||||
| `--run-as-user USER`, `--run-as-group GROUP` | Пользователь и группа процесса на Unix. |
|
||||
| `--working-dir PATH` | Рабочий каталог процесса на Unix. Для конфигурации лучше указать абсолютный путь. |
|
||||
| `--strict-runtime-paths` | Более строгая проверка служебных путей; используйте одинаково при запуске и управлении демоном. |
|
||||
|
||||
## Проверка работоспособности
|
||||
|
||||
```bash
|
||||
telemt healthcheck --mode liveness /etc/telemt/telemt.toml
|
||||
telemt healthcheck --mode ready /etc/telemt/telemt.toml
|
||||
```
|
||||
|
||||
Режим `liveness` используется по умолчанию и обращается к `GET /v1/health`. Режим `ready` обращается к `GET /v1/health/ready` и требует `data.ready = true`. Оба ожидают HTTP `200` и `ok = true`; для liveness также нужно `data.status = "ok"`.
|
||||
|
||||
Команда берёт адрес API и значение авторизации из указанного конфига. Для адреса прослушивания всех интерфейсов проверка идёт через loopback. Запускайте её там, где этот адрес доступен и разрешён списком доступа API. Команда не открывает сессию MTProxy и не проверяет весь путь от клиента до Telegram.
|
||||
|
||||
**При `server.api.enabled = false` команда возвращает `0` без сетевой проверки.** Прежде чем использовать результат как подтверждение работоспособности или готовности, включите API. Код `1` означает ошибку чтения конфигурации или проверки; неизвестное либо пропущенное значение `--mode` даёт `2`. Для подключения, чтения и записи установлены таймауты по две секунды. Это не единый двухсекундный срок выполнения всей команды.
|
||||
|
||||
## Журналирование
|
||||
|
||||
| Параметр | Назначение |
|
||||
| --- | --- |
|
||||
| `--log-level LEVEL` | Уровень: `debug`, `verbose`, `normal` или `silent`. |
|
||||
| `--silent`, `-s` | Отключение информационных сообщений. |
|
||||
| `--syslog` | Отправка журнала в syslog на поддерживаемых Unix-системах. |
|
||||
| `--log-file PATH` | Запись журнала в файл. |
|
||||
| `--log-file-daily PATH` | Запись в файл с ежедневной ротацией. |
|
||||
| `--log-rotation MODE` | Ротация: `never`, `minutely`, `hourly`, `daily` или `weekly`. |
|
||||
| `--log-max-size-bytes N` | Порог размера файла для ротации. |
|
||||
| `--log-max-files N` | Максимальное число сохраняемых файлов. |
|
||||
| `--log-max-age-secs N` | Максимальный возраст сохраняемых файлов в секундах. |
|
||||
|
||||
`RUST_LOG` имеет приоритет над настройками уровня журнала. Параметры CLI переопределяют соответствующие поля конфига. Подробности путей, ротации и хранения приведены в [справочнике журналирования](Config_params/CONFIG_PARAMS.ru.md#logging). Вывод в файл и syslog взаимоисключающие.
|
||||
|
||||
## Создание начальной конфигурации
|
||||
|
||||
`--init` записывает конфигурацию и файлы службы, после чего может запустить службу. Это установка, а не проверка конфига; повторный запуск может заново создать существующие файлы. Сначала проверьте и сохраните действующую конфигурацию.
|
||||
|
||||
```bash
|
||||
telemt --init --port 443 --domain example.com --user alice --config-dir /etc/telemt --no-start
|
||||
```
|
||||
|
||||
Передавайте значения отдельно от имён параметров, как в примере. По умолчанию используются порт `443`, домен `www.google.com`, пользователь `user` и каталог `/etc/telemt`. `--secret HEX` задаёт пользовательский секрет из 32 шестнадцатеричных знаков; без этого параметра секрет создаётся автоматически. `--no-start` отменяет запуск службы, но файлы установки всё равно записываются. Значения по умолчанию отличаются от `install.sh`: это два разных способа установки.
|
||||
|
||||
Для автоматизации через API см. [Control API](Architecture/API/API.md) и [клиент Python с CLI](Architecture/API/PYTHON_CLIENT.md), оба справочника на английском. Утилита Python и описанная здесь программа `telemt` — разные инструменты.
|
||||
@@ -1,5 +1,7 @@
|
||||
# Telemt-Referenz der Konfigurationsparameter
|
||||
|
||||
[English](CONFIG_PARAMS.en.md) · [Русский](CONFIG_PARAMS.ru.md) · [Deutsch](CONFIG_PARAMS.de.md) · [Terminology](../TERMINOLOGY.md)
|
||||
|
||||
Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akzeptiert.
|
||||
|
||||
> [!NOTE]
|
||||
@@ -10,7 +12,20 @@ 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 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.
|
||||
## Konfigurationsänderungen anwenden
|
||||
|
||||
`Hot-Reload` beschreibt nur die Dateiüberwachung: `✔` bedeutet, dass sie den neuen Wert übernehmen kann; bei `✘` bleibt der aktive Wert erhalten. `telemt reload` sendet SIGHUP an dieselbe Dateiüberwachung und erzeugt keine neue Laufzeitgeneration.
|
||||
|
||||
| Verfahren | Einstellungen und Wirkung |
|
||||
| --- | --- |
|
||||
| Automatisches Neuladen der Datei | Mit `✔` markierte Felder, etwa `general.log_level`, `network.dns_overrides` und unterstützte Benutzerlimits. Die Übernahme erfolgt asynchron. Die Feldbeschreibung erläutert, ob laufende Vorgänge oder nur neue Verbindungen betroffen sind. |
|
||||
| Expliziter Generationswechsel | `[censorship]`, `[timeouts]`, `upstreams` und die von der Generation verwalteten API-Einstellungen. Verwenden Sie `POST /v1/system/reload` oder einen zulässigen Konfigurations-PATCH mit `reload=instant` bzw. `reload=drain`. Warten Sie auf den Abschluss der Operation. Ob bestehende Verbindungen erhalten bleiben, hängt vom Modus ab. |
|
||||
| Prozessneustart | `logging`, `general.data_path`, `general.quota_state_path`, `general.disable_colors`, `general.direct_relay_buffer_budget_max_bytes`, `server.metrics_listen`, `server.metrics_port`, `server.max_connections`, `server.conntrack_control`, `server.listen_unix_sock`, `server.listen_unix_sock_perm`, die API-Felder `enabled`/`listen`/`runtime_edge_events_capacity`, `web.limits`, `web.allow_wildcard_hosts` und `web.decoy_fasttrack_mode`. |
|
||||
| Bedingt anwendbar | Adressänderungen nativer Listener sind nur im unterstützten Rebind-Verfahren möglich. WEB-Listener, Socket- und Vertrauensregeln sowie SYN-Regeln erfordern einen Prozessneustart. WEB-Lern- und Diagnoseeinstellungen können zurückgestellt werden, wenn sie größere Prozesslimits voraussetzen. |
|
||||
|
||||
Für über die API bearbeitbare Felder zeigt `POST /v1/config/validate` vor dem Speichern `apply.watcher_paths`, `apply.generation_paths` und `apply.process_restart_paths`. Prüfen Sie danach das Operationsergebnis, `deferred_process_fields` und `GET /v1/config/state`. Das ältere Feld `restart_required` bedeutet, dass die Änderung außerhalb der Dateiüberwachung liegt; daraus folgt allein noch kein Prozessneustart. Siehe [API-Vertrag zum Neuladen](../Architecture/API/API.md#runtime-reload-endpoints) und [CLI-Referenz](../CLI.de.md).
|
||||
|
||||
WEB-Einstellungen haben unterschiedliche Lebensdauern: `carrier_method` und Retry-Jitter gelten für neu erzeugte Bridge-Seiten, `conveyor` wird für neue Sitzungen ausgehandelt, und Prozesslimits bleiben bis zum Neustart fest. Bestehende Seiten und Sitzungen behalten die im [WEB-Leitfaden](../WEB/WEB_PROXY.de.md) beschriebenen Regeln.
|
||||
|
||||
# Inhaltsverzeichnis
|
||||
- [Schlüssel auf oberster Ebene](#schlüssel-auf-oberster-ebene)
|
||||
@@ -28,6 +43,7 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
|
||||
- [web.debug](#webdebug)
|
||||
- [web.limits](#weblimits)
|
||||
- [web.limits.wildcard](#weblimitswildcard)
|
||||
- [web.retry_jitter](#webretry_jitter)
|
||||
- [web.timeouts](#webtimeouts)
|
||||
- [web.vhosts](#webvhosts)
|
||||
- [web.vhosts.decoy](#webvhostsdecoy)
|
||||
@@ -42,7 +58,7 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
|
||||
|
||||
| Schlüssel | Typ | Default | Hot-Reload |
|
||||
| --- | --- | --- | --- |
|
||||
| [`include`](#include) | `String` (Proberdirektive) | — | `✔` |
|
||||
| [`include`](#include) | `String` (Include-Anweisung) | — | `✔` |
|
||||
| [`show_link`](#show_link) | `"*"` oder `String[]` | `[]` (`ShowLink::None`) | `✘` |
|
||||
| [`logging`](#logging) | Tabelle | Default-Werte | `✘` |
|
||||
| [`dc_overrides`](#dc_overrides) | `Map<String, String or String[]>` | `{}` | `✘` |
|
||||
@@ -106,7 +122,7 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
|
||||
|
||||
## logging.destination
|
||||
- **Einschränkungen / Validierung**: Muss `stderr`, `syslog` oder `file` sein. `syslog` wird nur auf Unix-Plattformen unterstützt. `file` erfordert `logging.path`.
|
||||
- **Beschreibung**: Wählt das Runtime-Log-Ziel aus. CLI-Flags überschreiben diesen Wert.
|
||||
- **Beschreibung**: Legt fest, wohin Telemt Protokollmeldungen schreibt. Kommandozeilenoptionen haben Vorrang.
|
||||
- **Beispiel**:
|
||||
|
||||
```toml
|
||||
@@ -116,7 +132,7 @@ Dieses Dokument listet alle Konfigurationsschlüssel auf, die `config.toml` akze
|
||||
```
|
||||
## logging.path
|
||||
- **Einschränkungen / Validierung**: Erforderlich, wenn `logging.destination = "file"`; darf nicht leer sein.
|
||||
- **Beschreibung**: Dateipfad, der für die File-Logging verwendet wird. Bei der Zeitrotation wird der Dateiname als rollierendes Präfix verwendet.
|
||||
- **Beschreibung**: Pfad für die Protokolldatei. Bei zeitgesteuerter Rotation dient der Dateiname als Präfix der erzeugten Dateien.
|
||||
- **Beispiel**:
|
||||
|
||||
```toml
|
||||
@@ -2638,6 +2654,8 @@ Der WEB-Modus transportiert MTProxy-Datenverkehr von Telegram Desktop über HTTP
|
||||
| `enabled` | `bool` | `false` | `✔` |
|
||||
| `allow_wildcard_hosts` | `bool` | `false` | `✘` |
|
||||
| `carrier` | `"https"`, `"https-lanes"`, `"websocket"` oder `"websocket-lanes"` | `"https"` | `✔` |
|
||||
| [`carrier_method`](#webcarrier_method) | `"post"`, `"put"` | `"post"` | `✔` |
|
||||
| [`conveyor`](#webconveyor) | `bool` | `true` | `✔` |
|
||||
| `carriers` | `false` oder ein nicht leeres Array eindeutiger Carrier | `false` | `✔` |
|
||||
| `carrier_learning` | `bool` | `true` | `✔` |
|
||||
| `carrier_negotiation_aggressiveness` | `"conservative"`, `"balanced"` oder `"aggressive"` | `"conservative"` | `✔` |
|
||||
@@ -2658,6 +2676,24 @@ Fehlt `carriers` oder ist es `false`, sind Auto-Negotiation und Lernen deaktivie
|
||||
|
||||
`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.carrier_method
|
||||
|
||||
`"post"` (Standard) oder `"put"` bestimmt die HTTP-Methode neu erzeugter Bridge-Seiten für `/api/v1/up` und `/api/v1/down`, einschließlich Wiederholungen. Der Server akzeptiert unabhängig davon beide Methoden. Sitzungserstellung und Diagnose verwenden weiterhin `POST`, das Schließen einer Sitzung `DELETE` und WebSocket Upgrade `GET`. Der TLS-Terminator muss `POST` und `PUT` durchlassen. `put` ermöglicht die Wiederverwendung von Verbindungen in Linux-WebKitGTK-Implementierungen, die idempotente Methoden unterscheiden; eine geringere Latenz muss am jeweiligen Client gemessen werden.
|
||||
|
||||
Die Dateiüberwachung übernimmt diese Einstellung. Bestehende Seiten behalten ihre Methode auch bei der Wiederherstellung einer Sitzung. Zugangsdaten werden dadurch nicht rotiert und aktive Sitzungen nicht verschoben.
|
||||
|
||||
## web.conveyor
|
||||
|
||||
`true` (Standard) erlaubt HTTP-Uplink-Pipelining mit einem begrenzten Fenster für neue `https`- und `https-lanes`-Sitzungen. Der Client bietet über `X-Telemt-Up-Window` ausdrücklich einen Wert von `1` bis `4` an; der Server bestätigt das Fenster. Bei `false` oder einem WebSocket-Transport wird ein ausdrückliches Angebot mit Fenster `1` beantwortet. Ohne diesen Header bleiben Anfragen sequenziell, und die Antwort enthält keinen Fenster-Header. Das native `WELCOME`-Format bleibt unverändert.
|
||||
|
||||
Das ausgehandelte Fenster erlaubt DATA vor der OPEN-Bestätigung. Reihenfolge, identische Wiederholungen, Bestätigungsprüfungen und Speicherbudgets bleiben erhalten. Die Dateiüberwachung ändert die Regel für neue Sitzungen; bestehende Sitzungen behalten ihr Fenster. Diese Einstellung ist unabhängig von der automatischen Transportauswahl.
|
||||
|
||||
```toml
|
||||
[web]
|
||||
carrier_method = "post"
|
||||
conveyor = true
|
||||
```
|
||||
|
||||
# [web.debug]
|
||||
|
||||
Diese hot-reload-fähige Tabelle steuert den prozesseigenen serverseitigen WEB-Debug-Recorder, der am API-Listener als authentifiziertes HTML unter `GET /web-status` bereitgestellt wird. Die Erfassung ist standardmäßig deaktiviert. Gespeicherte und in Verarbeitung befindliche Datensätze bleiben durch die nur nach einem Neustart änderbaren Werte in `[web.limits]` begrenzt.
|
||||
@@ -2918,8 +2954,8 @@ Vor dem Hinzufügen von Mustern über die API muss `web.allow_wildcard_hosts` im
|
||||
client_handshake = 30
|
||||
```
|
||||
## client_first_byte_idle_secs
|
||||
- **Einschränkungen / Validierung**: `u64` (Sekunden). `0` deaktiviert die Erzwingung des Leerlaufs im ersten Byte.
|
||||
- **Beschreibung**: Maximale Leerlaufzeit zum Warten auf das erste Client-Payloadbyte nach dem Sitzungsaufbau.
|
||||
- **Einschränkungen / Validierung**: `u64` (Sekunden). `0` deaktiviert das Zeitlimit für das Warten auf das erste Client-Byte.
|
||||
- **Beschreibung**: Maximale Wartezeit auf das erste Client-Byte vor der Verarbeitung des Handshakes, nach einem gegebenenfalls erforderlichen PROXY-Header. Dieses Limit ist von `client_handshake` und den Leerlaufzeiten der Datenübertragung getrennt.
|
||||
- **Beispiel**:
|
||||
|
||||
```toml
|
||||
@@ -3043,7 +3079,7 @@ Vor dem Hinzufügen von Mustern über die API muss `web.allow_wildcard_hosts` im
|
||||
## tls_domain
|
||||
- **Einschränkungen / Validierung**: Muss ein nicht leerer Domainname sein. Darf keine Leerzeichen und kein `/` enthalten.
|
||||
- **Beschreibung**: Primäre Domäne, die für das Fake-TLS-Masking-/Fronting-Profil verwendet wird und als Standard-SNI-Domäne für Clients angezeigt wird.
|
||||
Dieser Wert wird Teil der generierten `ee`-Links; eine Änderung macht zuvor generierte Links ungültig.
|
||||
Dieser Wert wird Teil der erzeugten `ee`-Links. Um alte Links bei einem Domainwechsel zu erhalten, behalten Sie die bisherige Domain in `tls_domains` und wenden Sie die Konfiguration an.
|
||||
- **Beispiel**:
|
||||
|
||||
```toml
|
||||
@@ -3062,11 +3098,11 @@ Vor dem Hinzufügen von Mustern über die API muss `web.allow_wildcard_hosts` im
|
||||
```
|
||||
## unknown_sni_action
|
||||
- **Einschränkungen / Validierung**: `"drop"`, `"mask"`, `"accept"` oder `"reject_handshake"`.
|
||||
- **Beschreibung**: Aktion für TLS ClientHello mit unbekanntem/nicht konfiguriertem SNI.
|
||||
- `drop` — schließt die Verbindung ohne Antwort (stilles FIN nach Anwendung von `server_hello_delay`). Timing-identisch zum Success-Zweig, aber auf dem Wire leiser als ein echter Webserver.
|
||||
- `mask` — proxyt die Verbindung transparent zu `mask_host:mask_port` (TLS-Fronting). Der Client erhält ein echtes ServerHello vom Backend mit dessen echtem Zertifikat. Maximale Tarnung, öffnet aber für jede fehlgeleitete Anfrage eine ausgehende Verbindung.
|
||||
- `accept` — behandelt SNI so, als wäre es gültig, und fährt im Auth-Pfad fort. Schwächt die Resistenz gegen aktives Probing; nur in engen Szenarien sinnvoll.
|
||||
- `reject_handshake` — sendet einen fatalen TLS-Alert `unrecognized_name` (RFC 6066, AlertDescription = 112) und schließt die Verbindung. Auf dem Wire identisch zu einem modernen nginx mit `ssl_reject_handshake on;` im Default-vhost: wirkt wie ein gewöhnlicher HTTPS-Server, der den angefragten Namen schlicht nicht hostet. Empfohlen, wenn maximale Parität mit einem Standard-Webserver wichtiger ist als TLS-Fronting. `server_hello_delay` wird absichtlich **nicht** auf diesen Zweig angewendet, sodass der Alert wie bei Referenz-nginx „sofort“ gesendet wird.
|
||||
- **Beschreibung**: Regel für ein ClientHello, dessen SNI weder in `tls_domain` noch in `tls_domains` enthalten ist.
|
||||
- `drop` — Verbindung nach der konfigurierten ServerHello-Verzögerung ohne Antwort schließen. Dies ist der Standard; eine gleiche Verzögerung belegt keine zeitliche Ununterscheidbarkeit.
|
||||
- `mask` — den konfigurierten Masking-Pfad verwenden, sofern Masking aktiviert ist. Ein erreichbarer TLS-Zielserver kann seinen eigenen Handshake und sein Zertifikat liefern; der Client wird dabei nicht für MTProxy authentifiziert.
|
||||
- `accept` — MTProxy-Authentifizierung trotz unbekanntem SNI fortsetzen. Damit werden mehr Namen zugelassen; gültige Zugangsdaten bleiben erforderlich. Um bestimmte alte Links zu erhalten, tragen Sie deren Domains in `tls_domains` ein.
|
||||
- `reject_handshake` — einen fatalen TLS-Alert `unrecognized_name` (RFC 6066, AlertDescription = 112) senden und schließen. Die ServerHello-Verzögerung wird hier nicht angewendet. Dieser Ablehnungsmechanismus wird auch von nginx mit `ssl_reject_handshake on` verwendet; vollständige Ununterscheidbarkeit im Netz ist damit nicht belegt.
|
||||
- **Beispiel**:
|
||||
|
||||
```toml
|
||||
@@ -3148,7 +3184,7 @@ Vor dem Hinzufügen von Mustern über die API muss `web.allow_wildcard_hosts` im
|
||||
- Darf nicht leer sein, wenn gesetzt.
|
||||
- Nur Unix; auf Nicht-Unix-Plattformen abgelehnt.
|
||||
- Auf Unix muss der Pfad \(\le 107\) Bytes lang sein.
|
||||
- Mutually exclusive mit `mask_host`.
|
||||
- Kann nicht zusammen mit `mask_host` verwendet werden.
|
||||
- **Beschreibung**: Unix-Socket-Pfad für das Mask-Backend statt TCP `mask_host`/`mask_port`.
|
||||
- **Beispiel**:
|
||||
|
||||
@@ -3839,6 +3875,9 @@ Wenn Backend oder Netzwerk stark bandbreitenbeschränkt sind, reduzieren Sie zue
|
||||
enabled = false
|
||||
```
|
||||
## scopes
|
||||
|
||||
Das [vollständige Direct-Beispiel](../Advanced_settings/TUNING.de.md#upstream-anhand-des-benutzernamens-auswählen) erläutert Benutzernamen, den Ersatz von SOCKS-Zugangsdaten und das Verhalten ohne passenden Upstream.
|
||||
|
||||
- **Einschränkungen / Validierung**: `String`. Durch Kommas getrennte Liste; Leerzeichen werden beim Abgleich entfernt.
|
||||
- **Beschreibung**: Scope-Tags, die für die Upstream-Filterung auf Anfrageebene verwendet werden. Wenn eine Anfrage einen Bereich angibt, können nur Upstreams ausgewählt werden, deren `scopes` dieses Tag enthält. Wenn eine Anfrage keinen Bereich angibt, sind nur Upstreams mit leerem `scopes` berechtigt.
|
||||
- **Beispiel**:
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Telemt Config Parameters Reference
|
||||
|
||||
[English](CONFIG_PARAMS.en.md) · [Русский](CONFIG_PARAMS.ru.md) · [Deutsch](CONFIG_PARAMS.de.md) · [Terminology](../TERMINOLOGY.md)
|
||||
|
||||
This document lists all configuration keys accepted by `config.toml`.
|
||||
|
||||
> [!NOTE]
|
||||
@@ -10,7 +12,20 @@ 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 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.
|
||||
## Applying configuration changes
|
||||
|
||||
`Hot-Reload` describes the file watcher only: `✔` means it can publish the setting, `✘` means it retains the active value. `telemt reload` sends SIGHUP to this same watcher; it does not create a runtime generation.
|
||||
|
||||
| Application path | Settings and effect |
|
||||
| --- | --- |
|
||||
| Automatic file reload | Fields marked `✔`; examples include `general.log_level`, `network.dns_overrides` and supported user limits. Publication is asynchronous. Each field's description determines whether existing work or only new connections see it. |
|
||||
| Explicit generation reload | `[censorship]`, `[timeouts]`, `upstreams` and generation-owned API settings. Use `POST /v1/system/reload` or an editable config PATCH with `reload=instant` or `reload=drain`. Follow the returned operation to completion. Connection survival depends on the selected mode. |
|
||||
| Process restart | `logging`, `general.data_path`, `general.quota_state_path`, `general.disable_colors`, `general.direct_relay_buffer_budget_max_bytes`, `server.metrics_listen`, `server.metrics_port`, `server.max_connections`, `server.conntrack_control`, `server.listen_unix_sock`, `server.listen_unix_sock_perm`, API `enabled`/`listen`/`runtime_edge_events_capacity`, `web.limits`, `web.allow_wildcard_hosts`, and `web.decoy_fasttrack_mode`. |
|
||||
| Conditional | Native listener address changes can use only the supported rebind plan; WEB listeners, listener socket/trust policy and SYN rules require process restart. WEB learning/debug changes depending on larger process limits can also be deferred. |
|
||||
|
||||
For API-editable fields, `POST /v1/config/validate` reports `apply.watcher_paths`, `apply.generation_paths` and `apply.process_restart_paths` before saving. After an update, inspect the reload result, `deferred_process_fields` and `GET /v1/config/state`. The legacy `restart_required` flag means “outside the watcher subset”; it does not by itself require a process restart. See the [API reload contract](../Architecture/API/API.md#runtime-reload-endpoints) and [CLI reference](../CLI.en.md).
|
||||
|
||||
WEB settings have separate lifetimes: `carrier_method` and retry jitter belong to newly rendered bridge pages, `conveyor` is negotiated for new sessions, and process limits stay fixed until restart. Existing pages and sessions retain the policies described in the [WEB guide](../WEB/WEB_PROXY.en.md#lifecycle-and-reload-behavior).
|
||||
|
||||
# Table of contents
|
||||
- [Top-level keys](#top-level-keys)
|
||||
@@ -28,6 +43,7 @@ This document lists all configuration keys accepted by `config.toml`.
|
||||
- [web.debug](#webdebug)
|
||||
- [web.limits](#weblimits)
|
||||
- [web.limits.wildcard](#weblimitswildcard)
|
||||
- [web.retry_jitter](#webretry_jitter)
|
||||
- [web.timeouts](#webtimeouts)
|
||||
- [web.vhosts](#webvhosts)
|
||||
- [web.vhosts.decoy](#webvhostsdecoy)
|
||||
@@ -2632,6 +2648,8 @@ WEB mode carries Telegram Desktop MTProxy traffic through HTTPS terminated by an
|
||||
| `enabled` | `bool` | `false` | `✔` |
|
||||
| `allow_wildcard_hosts` | `bool` | `false` | `✘` |
|
||||
| `carrier` | `"https"`, `"https-lanes"`, `"websocket"`, or `"websocket-lanes"` | `"https"` | `✔` |
|
||||
| [`carrier_method`](#webcarrier_method) | `"post"`, `"put"` | `"post"` | `✔` |
|
||||
| [`conveyor`](#webconveyor) | `bool` | `true` | `✔` |
|
||||
| `carriers` | `false` or a non-empty array of unique carriers | `false` | `✔` |
|
||||
| `carrier_learning` | `bool` | `true` | `✔` |
|
||||
| `carrier_negotiation_aggressiveness` | `"conservative"`, `"balanced"`, or `"aggressive"` | `"conservative"` | `✔` |
|
||||
@@ -2652,6 +2670,24 @@ When `carriers` is missing or `false`, auto-negotiation and learning are disable
|
||||
|
||||
`carrier_learning` applies only while negotiation is enabled. Learning is process-local, in-memory, bounded, and positive-only: only a carrier that reaches the server-defined healthy state contributes evidence. `conservative` requires the broadest evidence and disables IP ranking, `balanced` admits moderate User-Agent/profile evidence plus eligible public-IP tie breaking, and `aggressive` reacts to the first bounded samples. Reported client failures remain diagnostic and never create negative evidence. Reload preserves evidence across a generation change only when enabled state, aggressiveness, evidence lifetime, and health window are identical; any semantic change advances the evidence epoch and fences stale outcomes. Because `[web.limits]` is process-owned, a reload that enables learning or negotiation using only a desired larger `max_carrier_learning_entries` atomically defers the dependent learning/carrier field rather than publishing an invalid effective combination. Disabling WEB stops issuance of new bridge and session credentials after reload; use the users API to revoke one user's active sessions.
|
||||
|
||||
## web.carrier_method
|
||||
|
||||
`"post"` (default) or `"put"` selects the HTTP method emitted by new bridge pages for `/api/v1/up` and `/api/v1/down`, including retries. The server accepts both methods independently of this setting. Session creation and diagnostics remain `POST`, session closure remains `DELETE`, and WebSocket Upgrade remains `GET`. Allow both `POST` and `PUT` through the TLS terminator. `put` supports connection reuse by Linux WebKitGTK implementations that distinguish idempotent methods; measure the actual client before assuming a latency improvement.
|
||||
|
||||
The watcher can apply this setting. Existing pages keep their method during session recovery; it does not rotate credentials or move established sessions.
|
||||
|
||||
## web.conveyor
|
||||
|
||||
`true` (default) permits bounded HTTP uplink pipelining for new `https` and `https-lanes` sessions. The client explicitly offers `X-Telemt-Up-Window: 1` through `4`; the reply confirms the window. With `false` or a WebSocket carrier, an explicit offer receives window `1`. A client without this header remains on the serialized path and receives no window header. Native `WELCOME` framing is unchanged.
|
||||
|
||||
The negotiated window allows DATA to be sent before the OPEN acknowledgment while preserving ordering, exact retries, acknowledgment checks and memory budgets. The watcher changes the policy for new sessions; existing sessions keep their negotiated window. This is independent of carrier auto-negotiation.
|
||||
|
||||
```toml
|
||||
[web]
|
||||
carrier_method = "post"
|
||||
conveyor = true
|
||||
```
|
||||
|
||||
# [web.debug]
|
||||
|
||||
This hot-reloadable table controls the process-owned server-side WEB debug recorder exposed as authenticated HTML at `GET /web-status` on the API listener. Collection is disabled by default. Retained and in-flight records remain bounded by restart-only values in `[web.limits]`.
|
||||
@@ -2896,7 +2932,7 @@ The process must already have `web.allow_wildcard_hosts` enabled before a patch
|
||||
```
|
||||
## client_first_byte_idle_secs
|
||||
- **Constraints / validation**: `u64` (seconds). `0` disables first-byte idle enforcement.
|
||||
- **Description**: Maximum idle time to wait for the first client payload byte after session setup.
|
||||
- **Description**: Maximum wait for the first client byte before parsing the client handshake, after any required PROXY header. This is separate from `client_handshake` and relay idle timeouts.
|
||||
- **Example**:
|
||||
|
||||
```toml
|
||||
@@ -3039,11 +3075,11 @@ The process must already have `web.allow_wildcard_hosts` enabled before a patch
|
||||
```
|
||||
## unknown_sni_action
|
||||
- **Constraints / validation**: `"drop"`, `"mask"`, `"accept"` or `"reject_handshake"`.
|
||||
- **Description**: Action for TLS ClientHello with unknown / non-configured SNI.
|
||||
- `drop` — close the connection without any response (silent FIN after `server_hello_delay` is applied). Timing-indistinguishable from the Success branch, but wire-quieter than what a real web server would do.
|
||||
- `mask` — transparently proxy the connection to `mask_host:mask_port` (TLS fronting). The client receives a real ServerHello from the backend with its real certificate. Maximum camouflage, but opens an outbound connection for every misdirected request.
|
||||
- `accept` — pretend the SNI is valid and continue on the auth path. Weakens active-probing resistance; only meaningful in narrow scenarios.
|
||||
- `reject_handshake` — emit a fatal TLS `unrecognized_name` alert (RFC 6066, AlertDescription = 112) and close the connection. Identical on the wire to a modern nginx with `ssl_reject_handshake on;` on its default vhost: looks like an ordinary HTTPS server that simply does not host the requested name. Recommended when the goal is maximal parity with a stock web server rather than TLS fronting. `server_hello_delay` is intentionally **not** applied to this branch, so the alert is emitted "instantly" the way a reference nginx would.
|
||||
- **Description**: Policy for a ClientHello whose SNI is outside `tls_domain` and `tls_domains`.
|
||||
- `drop` — close without a response after the configured ServerHello delay. This is the default; matching a delay does not establish timing indistinguishability.
|
||||
- `mask` — use the configured masking path when masking is enabled. A reachable TLS fallback can return its own handshake and certificate; this does not authenticate the client to MTProxy.
|
||||
- `accept` — continue MTProxy authentication despite the unknown SNI. It broadens the accepted names and still requires valid credentials. To preserve selected old links, add their domains to `tls_domains` instead.
|
||||
- `reject_handshake` — send a fatal TLS `unrecognized_name` alert (RFC 6066, AlertDescription = 112) and close. The configured ServerHello delay is not applied to this branch. This matches a rejection mechanism used by nginx with `ssl_reject_handshake on`, not a claim of full network indistinguishability.
|
||||
- **Example**:
|
||||
|
||||
```toml
|
||||
@@ -3816,6 +3852,9 @@ If your backend or network is very bandwidth-constrained, reduce cap first. If p
|
||||
enabled = false
|
||||
```
|
||||
## scopes
|
||||
|
||||
See the [complete Direct user-scope example](../Advanced_settings/TUNING.en.md#selecting-an-upstream-by-user-scope) for user naming, SOCKS credential replacement and behavior when no upstream matches.
|
||||
|
||||
- **Constraints / validation**: `String`. Comma-separated list; whitespace is trimmed during matching.
|
||||
- **Description**: Scope tags used for request-level upstream filtering. If a request specifies a scope, only upstreams whose `scopes` contains that tag can be selected. If a request does not specify a scope, only upstreams with empty `scopes` are eligible.
|
||||
- **Example**:
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Справочник параметров конфигурации Telemt
|
||||
|
||||
[English](CONFIG_PARAMS.en.md) · [Русский](CONFIG_PARAMS.ru.md) · [Deutsch](CONFIG_PARAMS.de.md) · [Terminology](../TERMINOLOGY.md)
|
||||
|
||||
В этом документе перечислены все ключи конфигурации, принимаемые `config.toml`.
|
||||
|
||||
> [!NOTE]
|
||||
@@ -10,7 +12,20 @@
|
||||
>
|
||||
> Параметры конфигурации, подробно описанные в этом документе, предназначены для опытных пользователей и для целей тонкой настройки. Изменение этих параметров без четкого понимания их функции может привести к нестабильности приложения или другому неожиданному поведению. Пожалуйста, действуйте осторожно и на свой страх и риск.
|
||||
|
||||
> `Hot-Reload` показывает, применяет ли config watcher изменение напрямую. `✘` означает, что watcher его не применяет; в зависимости от поля для полного эффекта требуется in-process reload runtime generation либо перезапуск процесса.
|
||||
## Применение изменений конфигурации
|
||||
|
||||
Столбец `Hot-Reload` описывает только автоматическое перечитывание файла: `✔` — новое значение может быть опубликовано, `✘` — сохраняется действующее значение. Команда `telemt reload` посылает SIGHUP тому же обработчику; новое поколение она не создаёт.
|
||||
|
||||
| Способ применения | Настройки и результат |
|
||||
| --- | --- |
|
||||
| Автоматически после изменения файла | Поля с `✔`, например `general.log_level`, `network.dns_overrides` и поддерживаемые лимиты пользователей. Применение асинхронное. В описании поля указано, затрагивает ли оно текущую работу или только новые соединения. |
|
||||
| Перезагрузка поколения | `[censorship]`, `[timeouts]`, `upstreams` и настройки API, принадлежащие поколению. Используйте `POST /v1/system/reload` или PATCH редактируемой конфигурации с `reload=instant` либо `reload=drain`. Дождитесь завершения операции. Сохранение действующих соединений зависит от выбранного режима. |
|
||||
| Перезапуск процесса | `logging`, `general.data_path`, `general.quota_state_path`, `general.disable_colors`, `general.direct_relay_buffer_budget_max_bytes`, `server.metrics_listen`, `server.metrics_port`, `server.max_connections`, `server.conntrack_control`, `server.listen_unix_sock`, `server.listen_unix_sock_perm`, поля API `enabled`/`listen`/`runtime_edge_events_capacity`, `web.limits`, `web.allow_wildcard_hosts` и `web.decoy_fasttrack_mode`. |
|
||||
| Зависит от изменения | Адрес нативного listener можно сменить только в рамках поддерживаемого плана перепривязки. WEB-listeners, параметры сокетов и доверия, а также правила ограничения SYN требуют перезапуска процесса. Изменения обучения и диагностики WEB могут откладываться, если требуют увеличения лимитов процесса. |
|
||||
|
||||
Для полей, доступных через API, `POST /v1/config/validate` до сохранения возвращает `apply.watcher_paths`, `apply.generation_paths` и `apply.process_restart_paths`. После изменения проверьте результат операции, `deferred_process_fields` и `GET /v1/config/state`. Старое поле `restart_required` означает, что изменение выходит за пределы автоматического перечитывания; само по себе оно не требует перезапуска процесса. См. [контракт перезагрузки API](../Architecture/API/API.md#runtime-reload-endpoints) и [команды Telemt](../CLI.ru.md).
|
||||
|
||||
У настроек WEB разные сроки действия: `carrier_method` и случайные задержки повторов закреплены за новыми страницами моста, `conveyor` согласуется для новых сессий, а лимиты процесса сохраняются до перезапуска. Политики существующих страниц и сессий описаны в [руководстве WEB](../WEB/WEB_PROXY.ru.md#lifecycle-и-reload).
|
||||
|
||||
# Содержание
|
||||
- [Ключи верхнего уровня](#ключи-верхнего-уровня)
|
||||
@@ -28,6 +43,7 @@
|
||||
- [web.debug](#webdebug)
|
||||
- [web.limits](#weblimits)
|
||||
- [web.limits.wildcard](#weblimitswildcard)
|
||||
- [web.retry_jitter](#webretry_jitter)
|
||||
- [web.timeouts](#webtimeouts)
|
||||
- [web.vhosts](#webvhosts)
|
||||
- [web.vhosts.decoy](#webvhostsdecoy)
|
||||
@@ -53,7 +69,7 @@
|
||||
| [`beobachten_file`](#beobachten_file) | `String` | `"cache/beobachten.txt"` | `✘` |
|
||||
|
||||
## include
|
||||
- **Ограничения / валидация**: значение должно быть одной строкой в виде `include = "path/to/file.toml"`. Значения параметра обрабатываются перед анализом TOML. Максимальное количество - 10.
|
||||
- **Ограничения / валидация**: значение должно быть одной строкой в виде `include = "path/to/file.toml"`. Значения параметра обрабатываются перед анализом TOML. Максимальная глубина вложенности включаемых файлов — 10.
|
||||
- **Описание**: Включает еще один файл TOML с помощью `include = "relative/or/absolute/path.toml"`; добавленные файлы обрабатываются рекурсивно.
|
||||
- **Пример**:
|
||||
|
||||
@@ -73,7 +89,7 @@
|
||||
# show_link = ["alice", "bob"]
|
||||
```
|
||||
## dc_overrides
|
||||
- **Ограничения / валидация**: значение должно быть положительным целым числом в формате строки (например, `"203"`). Значения разбираются как `SocketAddr` (`ip:port`). Пустые строки игнорируются.
|
||||
- **Ограничения / валидация**: ключ должен быть положительным индексом DC, записанным строкой (например, `"203"`). Значение — адрес или список адресов `SocketAddr` (`ip:port`). Пустые строки игнорируются.
|
||||
- **Описание**: Переопределяет DC эндпоинты для запросов с нестандартными DC; задается в виде строки с индексом DC, значение — один или несколько адресов `ip:port`.
|
||||
- **Пример**:
|
||||
|
||||
@@ -106,7 +122,7 @@
|
||||
|
||||
## logging.destination
|
||||
- **Ограничения / валидация**: Допустимы `stderr`, `syslog` или `file`. `syslog` поддерживается только на Unix. Для `file` требуется `logging.path`.
|
||||
- **Описание**: Выбирает runtime log destination. CLI-флаги имеют приоритет.
|
||||
- **Описание**: Определяет, куда Telemt записывает логи. Параметры командной строки имеют приоритет.
|
||||
- **Пример**:
|
||||
|
||||
```toml
|
||||
@@ -116,7 +132,7 @@
|
||||
```
|
||||
## logging.path
|
||||
- **Ограничения / валидация**: Обязателен при `logging.destination = "file"`; не может быть пустым.
|
||||
- **Описание**: Путь для файлового логирования. При time-based rotation имя файла используется как rolling prefix.
|
||||
- **Описание**: Путь для файлового логирования. При ротации по времени имя файла используется как префикс имён создаваемых файлов.
|
||||
- **Пример**:
|
||||
|
||||
```toml
|
||||
@@ -126,7 +142,7 @@
|
||||
```
|
||||
## logging.rotation
|
||||
- **Ограничения / валидация**: Допустимы `never`, `minutely`, `hourly`, `daily` или `weekly`.
|
||||
- **Описание**: Интервал time-based file rotation. `weekly` выполняет ротацию на границе воскресенья по UTC. `never` пишет точно в `logging.path`, если size rotation не включена.
|
||||
- **Описание**: Интервал ротации файлов по времени. `weekly` выполняет ротацию на границе воскресенья по UTC. `never` пишет точно в `logging.path`, если ротация по размеру выключена.
|
||||
- **Пример**:
|
||||
|
||||
```toml
|
||||
@@ -136,7 +152,7 @@
|
||||
rotation = "daily"
|
||||
```
|
||||
## logging.max_size_bytes
|
||||
- **Ограничения / валидация**: `0` отключает size rotation.
|
||||
- **Ограничения / валидация**: `0` отключает ротацию по размеру.
|
||||
- **Описание**: Ротирует непустой активный файл перед записью следующей целой записи, если она превысит этот предел в байтах.
|
||||
- **Пример**:
|
||||
|
||||
@@ -147,8 +163,8 @@
|
||||
max_size_bytes = 104857600
|
||||
```
|
||||
## logging.max_files
|
||||
- **Ограничения / валидация**: `0` отключает retention по количеству файлов.
|
||||
- **Описание**: Сохраняет не более указанного числа совпадающих log files, включая активный файл и архивы. Активный файл retention cleanup не удаляет.
|
||||
- **Ограничения / валидация**: `0` отключает ограничение числа сохраняемых файлов.
|
||||
- **Описание**: Сохраняет не более указанного числа файлов журнала, соответствующих настроенному имени, включая активный файл и архивы. Активный файл при очистке не удаляется.
|
||||
- **Пример**:
|
||||
|
||||
```toml
|
||||
@@ -159,8 +175,8 @@
|
||||
max_files = 14
|
||||
```
|
||||
## logging.max_age_secs
|
||||
- **Ограничения / валидация**: `0` отключает retention по возрасту.
|
||||
- **Описание**: Удаляет ротированные log files старше указанного числа секунд по времени изменения. Активный файл retention cleanup не удаляет.
|
||||
- **Ограничения / валидация**: `0` отключает удаление архивов по возрасту.
|
||||
- **Описание**: Удаляет архивные файлы журнала старше указанного числа секунд по времени изменения. Активный файл при очистке не удаляется.
|
||||
- **Пример**:
|
||||
|
||||
```toml
|
||||
@@ -410,7 +426,7 @@
|
||||
## proxy_config_v4_url
|
||||
- **Ограничения / валидация**: `String`. Если не указан, используется `"https://core.telegram.org/getProxyConfig"`.
|
||||
- **Описание**: Необязательный URL для получения `getProxyConfig` (IPv4). Telemt при всегда пытается выполнить новую загрузку с этого URL (и если не задан, использует `https://core.telegram.org/getProxyConfig`).
|
||||
- **Example**:
|
||||
- **Пример**:
|
||||
|
||||
```toml
|
||||
[general]
|
||||
@@ -428,7 +444,7 @@
|
||||
## proxy_config_v6_url
|
||||
- **Ограничения / валидация**: `String`. Если не указан, используется `"https://core.telegram.org/getProxyConfigV6"`.
|
||||
- **Описание**: Необязательный URL для получения `getProxyConfigV6` (IPv6). Telemt при всегда пытается выполнить новую загрузку с этого URL (и если не задан, использует `https://core.telegram.org/getProxyConfigV6`).
|
||||
- **Example**:
|
||||
- **Пример**:
|
||||
|
||||
```toml
|
||||
[general]
|
||||
@@ -1136,7 +1152,7 @@
|
||||
## me_route_backpressure_enabled
|
||||
- **Ограничения / валидация**: `bool`.
|
||||
- **Описание**: Включает адаптивные таймауты записи маршрута в зависимости от заполнения канала.
|
||||
- **Example**:
|
||||
- **Пример**:
|
||||
|
||||
```toml
|
||||
[general]
|
||||
@@ -1145,7 +1161,7 @@
|
||||
## me_route_fairshare_enabled
|
||||
- **Ограничения / валидация**: `bool`.
|
||||
- **Описание**: Включает справедливое распределение нагрузки маршрутизации между writer-потоками.
|
||||
- **Example**:
|
||||
- **Пример**:
|
||||
|
||||
```toml
|
||||
[general]
|
||||
@@ -1288,7 +1304,7 @@
|
||||
```
|
||||
## me_reinit_every_secs
|
||||
- **Ограничения / валидация**: Должно быть `> 0` (секунд).
|
||||
- **Описание**: Интервал для выполнения цикла повторной инициализации ME с нулевым временем простоя.
|
||||
- **Описание**: Интервал повторной инициализации ME. Сохранение соединений зависит от политики смены поколения и завершения старых соединений.
|
||||
- **Пример**:
|
||||
|
||||
```toml
|
||||
@@ -1961,7 +1977,7 @@
|
||||
## listen_backlog
|
||||
- **Ограничения / валидация**: `u32`. `0` использует системный backlog по умолчанию.
|
||||
- **Описание**: Значение backlog, передаваемое в `listen(2)` для TCP-сокетов.
|
||||
- **Example**:
|
||||
- **Пример**:
|
||||
|
||||
```toml
|
||||
[server]
|
||||
@@ -2282,7 +2298,7 @@ PATCH объекта server без конкретного редактируем
|
||||
## gray_action
|
||||
- **Ограничения / валидация**: `"drop"`, `"api"` или `"200"`.
|
||||
- **Описание**: Действует только для прямых TCP-клиентов вне `whitelist`: `"drop"` закрывает соединение без HTTP-ответа, `"api"` возвращает структурированный `403 forbidden`, а `"200"` — пустой `200 OK` с `text/html; charset=utf-8`. Этот параметр не разрешает доступ к API. Клиенты из whitelist по-прежнему проходят аутентификацию и проверку режима read-only; пустой ответ не является JSON-подтверждением успеха.
|
||||
- **Example**:
|
||||
- **Пример**:
|
||||
|
||||
```toml
|
||||
[server.api]
|
||||
@@ -2641,6 +2657,8 @@ WEB-режим переносит MTProxy-трафик Telegram Desktop внут
|
||||
| `enabled` | `bool` | `false` | `✔` |
|
||||
| `allow_wildcard_hosts` | `bool` | `false` | `✘` |
|
||||
| `carrier` | `"https"`, `"https-lanes"`, `"websocket"` или `"websocket-lanes"` | `"https"` | `✔` |
|
||||
| [`carrier_method`](#webcarrier_method) | `"post"`, `"put"` | `"post"` | `✔` |
|
||||
| [`conveyor`](#webconveyor) | `bool` | `true` | `✔` |
|
||||
| `carriers` | `false` или непустой массив уникальных carrier | `false` | `✔` |
|
||||
| `carrier_learning` | `bool` | `true` | `✔` |
|
||||
| `carrier_negotiation_aggressiveness` | `"conservative"`, `"balanced"` или `"aggressive"` | `"conservative"` | `✔` |
|
||||
@@ -2661,6 +2679,24 @@ WEB-режим переносит MTProxy-трафик Telegram Desktop внут
|
||||
|
||||
`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.carrier_method
|
||||
|
||||
Значение `"post"` (по умолчанию) или `"put"` выбирает HTTP-метод для `/api/v1/up` и `/api/v1/down` в новых страницах моста, включая повторы. Сервер принимает оба метода независимо от настройки. Создание сессии и диагностика используют `POST`, закрытие сессии — `DELETE`, WebSocket Upgrade — `GET`. TLS-терминатор должен пропускать `POST` и `PUT`. Вариант `put` позволяет переиспользовать соединения в реализациях Linux WebKitGTK, которые различают идемпотентные методы; влияние на задержку нужно измерять на целевом клиенте.
|
||||
|
||||
Настройка применяется при автоматическом перечитывании файла. Существующая страница сохраняет свой метод и при восстановлении сессии. Смена метода не заменяет учётные данные и не переносит активные сессии.
|
||||
|
||||
## web.conveyor
|
||||
|
||||
Значение `true` (по умолчанию) разрешает конвейерную отправку ограниченного числа HTTP-запросов для новых сессий `https` и `https-lanes`. Клиент явно предлагает окно от `1` до `4` через `X-Telemt-Up-Window`; сервер подтверждает его в ответе. При `false` или транспорте WebSocket явное предложение получает окно `1`. Клиент без этого заголовка продолжает последовательную отправку и не получает заголовок окна. Формат нативного `WELCOME` не меняется.
|
||||
|
||||
Согласованное окно позволяет отправить DATA до подтверждения OPEN, сохраняя порядок, точное повторение запросов, проверку подтверждений и бюджеты памяти. Автоматическое перечитывание меняет политику новых сессий; действующие сохраняют своё окно. Эта настройка независима от автоматического выбора транспорта.
|
||||
|
||||
```toml
|
||||
[web]
|
||||
carrier_method = "post"
|
||||
conveyor = true
|
||||
```
|
||||
|
||||
# [web.debug]
|
||||
|
||||
Эта hot-reloadable таблица управляет process-owned серверным WEB debug recorder, доступным на API-listener’е как аутентифицированный HTML по `GET /web-status`. Сбор по умолчанию отключён. Сохранённые и находящиеся в обработке записи ограничены значениями из `[web.limits]`, изменение которых требует перезапуска.
|
||||
@@ -2921,8 +2957,8 @@ bootstrap переживает reload только при сохранении
|
||||
```
|
||||
## client_first_byte_idle_secs
|
||||
- **Ограничения / валидация**: `u64` (секунды). `0` отключает проверку простоя до первого байта.
|
||||
- **Описание**: Максимальное время ожидания первого байта полезной нагрузки от клиента после установления сессии.
|
||||
- **Example**:
|
||||
- **Описание**: Максимальное ожидание первого байта клиента до разбора рукопожатия, после обязательного PROXY-заголовка, если он используется. Это отдельный предел от `client_handshake` и таймаутов простоя при передаче данных.
|
||||
- **Пример**:
|
||||
|
||||
```toml
|
||||
[timeouts]
|
||||
@@ -3063,11 +3099,11 @@ bootstrap переживает reload только при сохранении
|
||||
```
|
||||
## unknown_sni_action
|
||||
- **Ограничения / валидация**: `"drop"`, `"mask"`, `"accept"` или `"reject_handshake"`.
|
||||
- **Описание**: Действие для TLS ClientHello с неизвестным/ненастроенным SNI.
|
||||
- `drop` — закрыть соединение без ответа (молчаливый FIN после применения `server_hello_delay`). Поведение, неотличимое по таймингу от Success-ветки, но более «тихое», чем у обычного веб-сервера.
|
||||
- `mask` — прозрачно проксировать соединение на `mask_host:mask_port` (TLS-fronting). Клиент получает настоящий ServerHello от реального бэкенда с его сертификатом. Максимальный камуфляж, но порождает исходящее соединение на каждый чужой запрос.
|
||||
- `accept` — притвориться, что SNI валиден, и продолжить auth-путь. Снижает защиту от активного пробинга; осмысленно только в узких сценариях.
|
||||
- `reject_handshake` — отправить фатальный TLS-alert `unrecognized_name` (RFC 6066, AlertDescription = 112) и закрыть соединение. Поведение, идентичное современному nginx с `ssl_reject_handshake on;` на дефолтном vhost'е: на wire-уровне выглядит как обычный HTTPS-сервер, у которого просто нет такого домена. Рекомендуется, если цель — максимальная похожесть на стоковый веб-сервер, а не tls-fronting. `server_hello_delay` на эту ветку не применяется, чтобы alert улетал «мгновенно», как у эталонного nginx.
|
||||
- **Описание**: Политика для ClientHello с SNI, отсутствующим в `tls_domain` и `tls_domains`.
|
||||
- `drop` — закрыть соединение без ответа после настроенной задержки ServerHello. Это значение по умолчанию; совпадение задержки не доказывает неразличимость по времени ответа.
|
||||
- `mask` — использовать настроенный путь маскировки, если маскировка включена. Доступный TLS-сервер прикрытия может вернуть своё рукопожатие и сертификат; клиент при этом не проходит аутентификацию MTProxy.
|
||||
- `accept` — продолжить аутентификацию MTProxy, несмотря на неизвестный SNI. Допустимый набор имён расширяется, но корректные учётные данные по-прежнему обязательны. Для сохранения выбранных старых ссылок добавьте их домены в `tls_domains`.
|
||||
- `reject_handshake` — отправить фатальный TLS-alert `unrecognized_name` (RFC 6066, AlertDescription = 112) и закрыть соединение. Настроенная задержка ServerHello к этой ветке не применяется. Такой механизм отказа использует nginx с `ssl_reject_handshake on`; полная сетевая неразличимость из этого не следует.
|
||||
- **Пример**:
|
||||
|
||||
```toml
|
||||
@@ -3226,7 +3262,7 @@ bootstrap переживает reload только при сохранении
|
||||
## serverhello_compact
|
||||
- **Ограничения / валидация**: `bool`.
|
||||
- **Описание**: Включает компактный профиль ServerHello/Fake-TLS для снижения сигнатуры размера ответа.
|
||||
- **Example**:
|
||||
- **Пример**:
|
||||
|
||||
```toml
|
||||
[censorship]
|
||||
@@ -3320,7 +3356,7 @@ bootstrap переживает reload только при сохранении
|
||||
## mask_relay_timeout_ms
|
||||
- **Constraints / validation**: Должно быть больше или равно `mask_relay_idle_timeout_ms`.
|
||||
- **Description**: Жёсткий лимит по реальному времени (wall-clock) для полного маскирующего проксирования на fallback-путях без MTProto. Увеличивайте значение, если целевой сервис маскирования является долгоживущим (например, WebSocket-соединение). Значение по умолчанию: 60 000 мс (1 минута).
|
||||
- **Example**:
|
||||
- **Пример**:
|
||||
|
||||
```toml
|
||||
[censorship]
|
||||
@@ -3329,7 +3365,7 @@ bootstrap переживает reload только при сохранении
|
||||
## mask_relay_idle_timeout_ms
|
||||
- **Constraints / validation**: Должно быть меньше или равно `mask_relay_timeout_ms`.
|
||||
- **Description**: Тайм-аут простоя на каждую операцию чтения (per-read idle timeout) в маскирующем прокси и drain-пайплайнах. Ограничивает потребление ресурсов при атаках типа slow-loris и сканировании портов. Если операция чтения блокируется дольше заданного времени, соединение считается заброшенным и закрывается. Значение по умолчанию: 5 000 мс (5 с).
|
||||
- **Example**:
|
||||
- **Пример**:
|
||||
|
||||
```toml
|
||||
[censorship]
|
||||
@@ -3763,7 +3799,7 @@ bootstrap переживает reload только при сохранении
|
||||
## user_rate_limits
|
||||
- **Ограничения / валидация**: Таблица `username -> { up_bps, down_bps }`. Каждое направление должно быть в диапазоне `0..=100000000000`; `0` означает отсутствие лимита в этом направлении, при этом хотя бы одно направление должно быть ненулевым.
|
||||
- **Описание**: Персональные лимиты скорости по пользователям в битах/сек для отправки (`up_bps`) и получения (`down_bps`).
|
||||
- **Example**:
|
||||
- **Пример**:
|
||||
|
||||
```toml
|
||||
[access.user_rate_limits]
|
||||
@@ -3773,7 +3809,7 @@ bootstrap переживает reload только при сохранении
|
||||
- **API**: Поле доступно через `GET/PATCH /v1/access/policy`. Пропуск сохраняет значение; `null` для скаляра восстанавливает значение типа по умолчанию. Для `cidr_rate_limits` объект объединяется по ключам, запись со значением null удаляет правило, а `null` вместо всего объекта очищает правила. Объект скорости заменяет оба направления; единица — бит в секунду. Публикация идёт через watcher; ответ разделяет снимки `desired` и `effective`.
|
||||
- **Ограничения / валидация**: Таблица `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**:
|
||||
- **Пример**:
|
||||
|
||||
```toml
|
||||
[access.cidr_rate_limits]
|
||||
@@ -3842,6 +3878,9 @@ bootstrap переживает reload только при сохранении
|
||||
enabled = false
|
||||
```
|
||||
## scopes
|
||||
|
||||
См. [полный пример выбора апстрима по пользователю](../Advanced_settings/TUNING.ru.md#выбор-апстрима-по-имени-пользователя): формат имени, подмена учётных данных SOCKS и поведение при отсутствии подходящего маршрута.
|
||||
|
||||
- **Ограничения / валидация**: `String`. CСписок, разделенный запятыми; пробелы обрезаются во время сопоставления
|
||||
- **Описание**: Теги области (`scope`), используемые для фильтрации upstream-серверов на уровне запроса. Если в запросе указан `scope`, выбираются только те upstream’ы, у которых поле `scopes` содержит этот тег. Если scope в запросе не указан, допускаются только upstream’ы с пустым scopes.
|
||||
- **Пример**:
|
||||
|
||||
@@ -32,10 +32,12 @@ Leiten Sie den vollständigen konfigurierten WEB-Bereich an Telemt weiter. Beim
|
||||
| --- | --- | --- |
|
||||
| `GET` | `BASE?bridge=<capability>` | Erstes Bridge-Dokument oder, mit Recovery-`Accept`-Header und optionalem Bearer, die Recovery-Repräsentation. |
|
||||
| `POST`, `DELETE` | `BASEapi/v1/session` | Parent-Sitzung erstellen oder schließen. |
|
||||
| `POST` | `BASEapi/v1/up` | Uplink des HTTPS-Carriers. |
|
||||
| `POST` | `BASEapi/v1/down` | Downlink des HTTPS-Carriers. |
|
||||
| `POST`, `PUT` | `BASEapi/v1/up` | Uplink des HTTPS-Carriers. |
|
||||
| `POST`, `PUT` | `BASEapi/v1/down` | Downlink des HTTPS-Carriers. |
|
||||
| `GET` | `BASEapi/v1/ws` | WebSocket-Upgrade. |
|
||||
|
||||
`web.carrier_method` wählt `post` (Standard) oder `put` für neue Bridge-Seiten; der Server akzeptiert beide Methoden auf `/up` und `/down`. Bestehende Seiten behalten ihre Methode bei der Wiederherstellung. `web.conveyor = true` (Standard) erlaubt für neue HTTPS-Sitzungen ein ausdrücklich ausgehandeltes Sendefenster von 1 bis 4; deaktiviert bleibt der Upload sequenziell. Bestehende Sitzungen behalten ihr Fenster. Methoden für Sitzungserstellung, Löschung und WebSocket Upgrade bleiben unverändert. Siehe [Methoden- und Pipelining-Vertrag](../Config_params/CONFIG_PARAMS.de.md#webcarrier_method).
|
||||
|
||||
`POST BASEapi/v1/diagnostic` ist eine interne Sideband-Route der generierten Bridge und keine öffentliche Client-API. Das Routing ist groß-/kleinschreibungssensitiv und bytegenau: Es gibt keine Aliase, Varianten mit zusätzlichen oder percent-encoded Schrägstrichen und keine Query-Parameter an Carrier-Endpunkten. Ein falsch geformter Request mit einer vom aktuellen Prozess authentifizierten Capability oder einem solchen Bearer erhält lokal ein nicht cachebares `404`; ein nicht passender Request ohne authentisches Carrier-Material folgt dem konfigurierten Decoy. `base_path` ändert nur diese Routen des WEB-Listeners. Control API, `/web-status` und Prometheus-Metriken erhalten kein Präfix.
|
||||
|
||||
## Unterstützter Client-Vertrag
|
||||
@@ -57,7 +59,7 @@ tg://webproxy?server=proxy.example.com&secret=dd0123456789abcdef0123456789abcdef
|
||||
tg://webproxy?server=proxy.example.com%2Ftelegram%2Fweb&secret=cAABAgMEBQYHCAkKCwwNDg8
|
||||
```
|
||||
|
||||
Telemt gibt beim Prozessstart Links für die durch `[general.links].show` ausgewählten WEB-Profile über das vorhandene Log-Target `telemt::links` aus. Root-Links behalten das bisherige hexadezimale Secret. Bei einem Pfad-Link ist `HOST/BASE` im Parameter `server` percent-encoded; das Secret ist ungepolstertes base64url von `0x70 || client_secret`, wobei `client_secret` im Modus `plain` das rohe 16-Byte-Secret und im Modus `dd` den Wert `0xdd || secret` bezeichnet. Die Users-API liefert nur das rohe Secret und keinen WEB-Link. `[general.links].public_host` und `public_port` wirken nur auf native Links und überschreiben keine WEB-vhost-Links.
|
||||
Telemt gibt beim Prozessstart Links für die durch `[general.links].show` ausgewählten WEB-Profile über das vorhandene Log-Target `telemt::links` aus. Root-Links behalten das bisherige hexadezimale Secret. Bei einem Pfad-Link ist `HOST/BASE` im Parameter `server` percent-encoded; das Secret ist ungepolstertes base64url von `0x70 || client_secret`, wobei `client_secret` im Modus `plain` das rohe 16-Byte-Secret und im Modus `dd` den Wert `0xdd || secret` bezeichnet. `GET /v1/users/{username}/links?transport=web` liefert WEB-Links mit Zugangsdaten über denselben Formatter, unabhängig vom `show`-Filter für die Startausgabe. `[general.links].public_host` und `public_port` wirken nur auf native Links und überschreiben keine WEB-vhost-Links.
|
||||
|
||||
## Voraussetzungen
|
||||
|
||||
@@ -655,7 +657,7 @@ curl -sS -X POST http://127.0.0.1:9091/v1/users/web-user/rotate-secret \
|
||||
-d '{}'
|
||||
```
|
||||
|
||||
Nach einer Secret-Rotation erstellt der Config-Watcher die WEB-Capabilities neu. Die Users-API liefert das Secret, aber keine `tg://webproxy`-URL. Erstellen Sie den Link mit dem konfigurierten Hostnamen und der `plain`- oder `dd`-Darstellung des Profils. Entfernen und aktivieren Sie vor dem Löschen eines Benutzers zuerst das WEB-Profil, das auf ihn verweist, damit die resultierende Konfiguration gültig bleibt.
|
||||
Nach einer Secret-Rotation erstellt der Config-Watcher die WEB-Capabilities neu. Rufen Sie `GET /v1/users/{username}/links?transport=web` ab und prüfen Sie vor der Ausgabe wirksamer Links, ob `usable=true` gilt. Solange das veröffentlichte Profil und die prozessweite Zulassung das neue Secret nicht akzeptieren, enthält die Antwort keine Links und meldet pending oder unavailable. `view=desired` zeigt eine Vorschau für exakte konfigurierte Hosts und Pfade mit `usable=false`; Wildcard-Muster werden nie als Links ausgegeben. Die [Beschreibung der WEB-Links](../Architecture/API/API.md#web-user-links) erläutert Grenzen des Snapshots und Fehler. Entfernen und aktivieren Sie vor dem Löschen eines Benutzers zuerst das WEB-Profil, das auf ihn verweist, damit die resultierende Konfiguration gültig bleibt.
|
||||
|
||||
Der vollständige Vertrag für Requests, Revisionen, Fehler und alle Benutzer-Endpunkte steht in der [Dokumentation der Control API](../Architecture/API/API.md).
|
||||
|
||||
|
||||
@@ -32,10 +32,12 @@ Let `BASE` mean `/` for an empty `base_path`, or `/<base_path>/` otherwise. The
|
||||
| --- | --- | --- |
|
||||
| `GET` | `BASE?bridge=<capability>` | Initial bridge document, or the recovery representation when the recovery `Accept` header and optional bearer are present. |
|
||||
| `POST`, `DELETE` | `BASEapi/v1/session` | Create or close the parent session. |
|
||||
| `POST` | `BASEapi/v1/up` | HTTPS carrier uplink. |
|
||||
| `POST` | `BASEapi/v1/down` | HTTPS carrier downlink. |
|
||||
| `POST`, `PUT` | `BASEapi/v1/up` | HTTPS carrier uplink. |
|
||||
| `POST`, `PUT` | `BASEapi/v1/down` | HTTPS carrier downlink. |
|
||||
| `GET` | `BASEapi/v1/ws` | WebSocket Upgrade. |
|
||||
|
||||
`web.carrier_method` selects `post` (default) or `put` for new bridge pages; the server accepts both on `/up` and `/down`. Existing pages retain their method during recovery. `web.conveyor = true` (default) permits an explicitly negotiated uplink window of 1–4 for new HTTPS sessions; disabling it retains serialized uploads. Existing sessions keep their window. These settings do not alter session creation, deletion or WebSocket Upgrade methods. See the [method and conveyor contract](../Config_params/CONFIG_PARAMS.en.md#webcarrier_method).
|
||||
|
||||
`POST BASEapi/v1/diagnostic` is an internal generated-bridge sideband route, not a public client API. Route matching is case-sensitive and byte-exact: there are no aliases, extra-slash variants, percent-encoded slash variants, or query parameters on carrier endpoints. A wrong-shaped request containing a capability or bearer authenticated by the current process receives a local no-store `404`; an unmatched request without authentic carrier material follows the configured decoy. `base_path` changes only these WEB listener routes. It does not prefix the Control API, `/web-status`, or Prometheus metrics.
|
||||
|
||||
## Supported client contract
|
||||
@@ -57,7 +59,7 @@ tg://webproxy?server=proxy.example.com&secret=dd0123456789abcdef0123456789abcdef
|
||||
tg://webproxy?server=proxy.example.com%2Ftelegram%2Fweb&secret=cAABAgMEBQYHCAkKCwwNDg8
|
||||
```
|
||||
|
||||
Telemt prints links at process startup for WEB profiles selected by `[general.links].show` through the existing `telemt::links` log target. Root links keep the legacy hexadecimal secret. A path link percent-encodes `HOST/BASE` in `server` and uses unpadded base64url of `0x70 || client_secret`, where `client_secret` is the raw 16-byte secret in `plain` mode or `0xdd || secret` in `dd` mode. The users API returns only the raw secret, not a WEB link. `[general.links].public_host` and `public_port` affect native links only and do not override WEB vhost links.
|
||||
Telemt prints links at process startup for WEB profiles selected by `[general.links].show` through the existing `telemt::links` log target. Root links keep the legacy hexadecimal secret. A path link percent-encodes `HOST/BASE` in `server` and uses unpadded base64url of `0x70 || client_secret`, where `client_secret` is the raw 16-byte secret in `plain` mode or `0xdd || secret` in `dd` mode. `GET /v1/users/{username}/links?transport=web` returns credential-bearing WEB links using the same formatter, independently of the startup `show` filter. `[general.links].public_host` and `public_port` affect native links only and do not override WEB vhost links.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
@@ -641,7 +643,7 @@ curl -sS -X POST http://127.0.0.1:9091/v1/users/web-user/rotate-secret \
|
||||
-d '{}'
|
||||
```
|
||||
|
||||
The config watcher rebuilds WEB capabilities after a secret rotation. The users API returns the secret, not a `tg://webproxy` URL; construct the link with the configured hostname and the profile's `plain` or `dd` representation. Before deleting a user referenced by a WEB profile, remove and apply that profile first so the resulting configuration remains valid.
|
||||
The config watcher rebuilds WEB capabilities after a secret rotation. Read `GET /v1/users/{username}/links?transport=web` and check `usable=true` before provisioning its effective links. Until the published binding and process admission accept the new credential, the response withholds links as pending or unavailable. `view=desired` previews exact configured hosts and paths with `usable=false`; wildcard patterns are never emitted as links. See [WEB user links](../Architecture/API/API.md#web-user-links) for snapshot limits and errors. Before deleting a user referenced by a WEB profile, remove and apply that profile first so the resulting configuration remains valid.
|
||||
|
||||
See the complete [Control API contract](../Architecture/API/API.md) for request envelopes, revisions, failure modes, and all user endpoints.
|
||||
|
||||
|
||||
@@ -32,10 +32,12 @@ WEB-listener Telemt
|
||||
| --- | --- | --- |
|
||||
| `GET` | `BASE?bridge=<capability>` | Исходный bridge document или recovery representation при наличии recovery-заголовка `Accept` и необязательного bearer. |
|
||||
| `POST`, `DELETE` | `BASEapi/v1/session` | Создание или закрытие parent session. |
|
||||
| `POST` | `BASEapi/v1/up` | Uplink HTTPS carrier. |
|
||||
| `POST` | `BASEapi/v1/down` | Downlink HTTPS carrier. |
|
||||
| `POST`, `PUT` | `BASEapi/v1/up` | Uplink HTTPS carrier. |
|
||||
| `POST`, `PUT` | `BASEapi/v1/down` | Downlink HTTPS carrier. |
|
||||
| `GET` | `BASEapi/v1/ws` | WebSocket Upgrade. |
|
||||
|
||||
`web.carrier_method` выбирает `post` (по умолчанию) или `put` для новых страниц моста; сервер принимает оба метода на `/up` и `/down`. Существующие страницы сохраняют метод при восстановлении. `web.conveyor = true` (по умолчанию) разрешает явно согласуемое окно отправки от 1 до 4 для новых HTTPS-сессий; при отключении отправка последовательная. Действующие сессии сохраняют своё окно. Эти параметры не меняют методы создания и удаления сессии или WebSocket Upgrade. См. [контракт метода и конвейера](../Config_params/CONFIG_PARAMS.ru.md#webcarrier_method).
|
||||
|
||||
`POST BASEapi/v1/diagnostic` — внутренний sideband-маршрут сгенерированного bridge, а не публичный client API. Сопоставление путей регистрозависимо и побайтно точно: нет aliases, вариантов с лишним или percent-encoded слешем и query parameters у carrier endpoints. Запрос неправильной формы с capability или bearer, аутентифицированным текущим процессом, получает локальный не кэшируемый `404`; несовпавший запрос без подлинного carrier material следует в настроенный decoy. `base_path` меняет только эти маршруты WEB-listener. Он не добавляется к Control API, `/web-status` или Prometheus metrics.
|
||||
|
||||
## Поддерживаемый контракт клиента
|
||||
@@ -57,7 +59,7 @@ tg://webproxy?server=proxy.example.com&secret=dd0123456789abcdef0123456789abcdef
|
||||
tg://webproxy?server=proxy.example.com%2Ftelegram%2Fweb&secret=cAABAgMEBQYHCAkKCwwNDg8
|
||||
```
|
||||
|
||||
При запуске процесса Telemt печатает ссылки для WEB-профилей, выбранных в `[general.links].show`, через существующий log target `telemt::links`. Root-ссылки сохраняют прежний шестнадцатеричный secret. В path-ссылке `HOST/BASE` в параметре `server` percent-encoded, а secret равен base64url без padding от `0x70 || client_secret`, где `client_secret` — исходный 16-байтовый secret для режима `plain` либо `0xdd || secret` для режима `dd`. Users API возвращает только исходный секрет, а не WEB-ссылку. `[general.links].public_host` и `public_port` влияют только на нативные ссылки и не переопределяют ссылки WEB-vhost.
|
||||
При запуске процесса Telemt печатает ссылки для WEB-профилей, выбранных в `[general.links].show`, через существующий log target `telemt::links`. Root-ссылки сохраняют прежний шестнадцатеричный secret. В path-ссылке `HOST/BASE` в параметре `server` percent-encoded, а secret равен base64url без padding от `0x70 || client_secret`, где `client_secret` — исходный 16-байтовый secret для режима `plain` либо `0xdd || secret` для режима `dd`. `GET /v1/users/{username}/links?transport=web` возвращает WEB-ссылки с учётными данными через тот же форматтер, независимо от фильтра `show` для вывода при запуске. `[general.links].public_host` и `public_port` влияют только на нативные ссылки и не переопределяют ссылки WEB-vhost.
|
||||
|
||||
## Предварительные требования
|
||||
|
||||
@@ -648,7 +650,7 @@ curl -sS -X POST http://127.0.0.1:9091/v1/users/web-user/rotate-secret \
|
||||
-d '{}'
|
||||
```
|
||||
|
||||
После ротации секрета config watcher перестраивает WEB capabilities. Users API возвращает секрет, но не URL `tg://webproxy`; соберите ссылку из настроенного hostname и представления `plain` или `dd` соответствующего профиля. Перед удалением пользователя, на которого ссылается WEB-профиль, сначала удалите и примените этот профиль, чтобы итоговая конфигурация оставалась валидной.
|
||||
После ротации секрета config watcher перестраивает WEB capabilities. Запросите `GET /v1/users/{username}/links?transport=web` и проверьте `usable=true` перед выдачей действующих ссылок. Пока опубликованный профиль и механизм допуска процесса не принимают новый секрет, ответ не содержит ссылок и сообщает pending или unavailable. `view=desired` показывает предварительные ссылки для точных хостов и путей с `usable=false`; wildcard-шаблоны в ссылки не попадают. Ограничения снимка и ошибки описаны в [контракте WEB-ссылок](../Architecture/API/API.md#web-user-links). Перед удалением пользователя, на которого ссылается WEB-профиль, сначала удалите и примените этот профиль, чтобы итоговая конфигурация оставалась валидной.
|
||||
|
||||
Полный контракт запросов, revisions, ошибок и всех user endpoints приведён в [документации Control API](../Architecture/API/API.md).
|
||||
|
||||
|
||||
Reference in New Issue
Block a user