From b1502b629b907700350c8652ceef6e71ad7a62bf Mon Sep 17 00:00:00 2001 From: Alexey <247128645+axkurcom@users.noreply.github.com> Date: Fri, 6 Nov 2026 22:48:06 +0300 Subject: [PATCH] DNS Overrides in Docs --- docs/Config_params/CONFIG_PARAMS.de.md | 41 +++++++++++++++++++++----- docs/Config_params/CONFIG_PARAMS.en.md | 38 +++++++++++++++++++----- docs/Config_params/CONFIG_PARAMS.ru.md | 39 +++++++++++++++++++----- 3 files changed, 94 insertions(+), 24 deletions(-) diff --git a/docs/Config_params/CONFIG_PARAMS.de.md b/docs/Config_params/CONFIG_PARAMS.de.md index 2e93502..18c7eb6 100644 --- a/docs/Config_params/CONFIG_PARAMS.de.md +++ b/docs/Config_params/CONFIG_PARAMS.de.md @@ -1903,11 +1903,12 @@ Gültige öffentliche SOCKS-Werte `BND.ADDR/BND.PORT` mit einem Port ungleich nu cache_public_ip_path = "cache/public_ip.txt" ``` ## dns_overrides - - **Einschränkungen / Validierung**: `String[]`. Jeder Eintrag muss das Format `host:port:ip` verwenden. - – `host`: Domänenname (darf nicht leer sein und darf nicht `:` enthalten) - – `port`: `u16` - – `ip`: IPv4 (`1.2.3.4`) oder in Klammern IPv6 (`[2001:db8::1]`). **Ungeklammertes IPv6 wird abgelehnt**. - - **Beschreibung**: Runtime DNS-Overrideen für `host:port`-Ziele. Nützlich, um bestimmte IP-Adressen für bestimmte Upstream-Domänen zu erzwingen, ohne das System-DNS zu berühren. + - **Einschränkungen / Validierung**: `String[]`, höchstens `4096` Einträge. Jeder Eintrag muss das Format `host:port:ip` verwenden. + - `host`: nichtleerer Domainname ohne `:`. + - `port`: `u16`. + - `ip`: IPv4 (`1.2.3.4`) oder IPv6 in eckigen Klammern (`[2001:db8::1]`). IPv6 ohne Klammern wird abgelehnt. + - **Beschreibung**: Überschreibt künftige `host:port`-Auflösungen über den Resolver der Generation, ohne das System-DNS zu ändern. Hostnamen werden ohne Beachtung der Groß-/Kleinschreibung verglichen; der Port muss übereinstimmen. Bei mehrfacher Angabe desselben Hosts und Ports gilt der letzte Eintrag. Der bestehende Dateiwächter veröffentlicht Änderungen; bereits aufgebaute Verbindungen behalten ihre Zieladressen. + - **Control API**: `GET /v1/config` liefert aus `[network]` nur `network.dns_overrides`, einschließlich des Standardwerts `[]`. `PATCH /v1/config` und `POST /v1/config/validate` akzeptieren dieses Feld; andere Netzwerkfelder werden weiterhin abgelehnt. Das Array ersetzt die gesamte Liste; `[]` leert sie, `null` dagegen nicht. Beim Speichern wird nur der Wert ersetzt oder die Schlüsselzuweisung in die zuständige Quelldatei eingefügt. Benachbarte Einstellungen und andere Include-Dateien bleiben erhalten. Uneindeutige Zuständigkeit oder mehrere betroffene Quelldateien führen zu `409 config_patch_not_atomic`. PATCH wartet nicht auf die Veröffentlichung durch den Dateiwächter; `GET /v1/config/state?sections=network` zeigt den Veröffentlichungsstand. Siehe [DNS overrides in der API](../Architecture/API/API.md#dns-overrides). - **Beispiel**: ```toml @@ -2216,8 +2217,26 @@ Hinweis: Der conntrack-control Worker wird **nur auf Linux** ausgeführt. Auf an # [server.api] -Hinweis: Dieser Abschnitt akzeptiert auch den Legacy-Alias `[server.admin_api]` (gleiches Schema wie `[server.api]`). +Der ältere Alias `[server.admin_api]` verwendet dasselbe Schema. +Alle Felder dieses Abschnitts sind mit `Hot-Reload = ✘` gekennzeichnet: Der +Dateiwächter behält die aktiven API-Einstellungen bei. Ein expliziter +Generationsreload übernimmt `whitelist`, `gray_action`, `auth_header`, +`request_body_limit_bytes`, `minimal_runtime_enabled`, +`minimal_runtime_cache_ttl_ms`, `runtime_edge_enabled`, +`runtime_edge_cache_ttl_ms`, `runtime_edge_top_n` und `read_only`. +`enabled`, `listen` und `runtime_edge_events_capacity` erfordern einen +Neustart des Prozesses. + +Ändern Sie die zuständige TOML-Datei und rufen Sie für Felder, die ein +Generationsreload übernehmen kann, `POST /v1/system/reload` auf. +`PATCH /v1/config` erlaubt unter `server` derzeit nur `server.listeners` und +kann `server.api.*` nicht ändern. `GET /v1/config/schema` beschreibt für jedes +Feld die API-Verfügbarkeit und das Übernahmeverhalten. `GET /v1/config/state` +zeigt Unterschiede zwischen Sollzustand und veröffentlichtem Zustand, ohne zu +bestätigen, dass alle Verbraucher die Einstellungen bereits übernommen haben. +Siehe [API-Referenz](../Architecture/API/API.md) und +[Python-Client-Anleitung](../Architecture/API/PYTHON_CLIENT.md). | Schlüssel | Typ | Default | Hot-Reload | | --- | --- | --- | --- | @@ -2246,7 +2265,7 @@ Hinweis: Dieser Abschnitt akzeptiert auch den Legacy-Alias `[server.admin_api]` ``` ## gray_action - **Einschränkungen / Validierung**: `"drop"`, `"api"` oder `"200"`. - - **Beschreibung**: API-Antwortrichtlinie für graue/eingeschränkte Staaten: Anfrage verwerfen, normale API-Antwort bereitstellen oder `200 OK` erzwingen. + - **Beschreibung**: Gilt nur für direkte TCP-Peers außerhalb von `whitelist`: `"drop"` schließt die Verbindung ohne HTTP-Antwort, `"api"` liefert ein strukturiertes `403 forbidden`, und `"200"` liefert ein leeres `200 OK` mit `text/html; charset=utf-8`. Die Einstellung gewährt keinen API-Zugriff. Erlaubte Peers durchlaufen weiterhin die Authentifizierung und die Prüfung des read-only-Modus; eine leere Antwort ist kein JSON-Erfolgsnachweis. - **Beispiel**: ```toml @@ -2281,7 +2300,7 @@ Hinweis: Dieser Abschnitt akzeptiert auch den Legacy-Alias `[server.admin_api]` auth_header = "Bearer MY_TOKEN" ``` ## request_body_limit_bytes - - **Einschränkungen / Validierung**: Muss `> 0` (Byte) sein. + - **Einschränkungen / Validierung**: `1..=1048576` (Bytes). - **Beschreibung**: Maximal akzeptierte HTTP-Anfragetextgröße (Byte). - **Beispiel**: @@ -3589,6 +3608,7 @@ Wenn Backend oder Netzwerk stark bandbreitenbeschränkt sind, reduzieren Sie zue alice = 500 ``` ## user_max_tcp_conns_global_each + - **API**: Das Feld ist über `GET/PATCH /v1/access/policy` verfügbar. Auslassen behält den Wert bei; `null` setzt ihn auf den Typstandard zurück. Die Veröffentlichung erfolgt über den Watcher; die Antwort trennt die Snapshots `desired` und `effective`. - **Einschränkungen / Validierung**: `usize`. `0` deaktiviert das geerbte Limit. - **Beschreibung**: Globale maximale Anzahl gleichzeitiger TCP-Verbindungen pro User, angewendet, wenn ein User **keinen positiven** Eintrag in `[access.user_max_tcp_conns]` hat (ein fehlender Schlüssel oder ein Wert von `0`, beides fällt auf diese Einstellung). Grenzwerte pro User, die größer als `0` in `user_max_tcp_conns` sind, haben Vorrang. - **Beispiel**: @@ -3651,6 +3671,7 @@ Wenn Backend oder Netzwerk stark bandbreitenbeschränkt sind, reduzieren Sie zue alice = 16 ``` ## user_max_unique_ips_global_each + - **API**: Das Feld ist über `GET/PATCH /v1/access/policy` verfügbar. Auslassen behält den Wert bei; `null` setzt ihn auf den Typstandard zurück. Die Veröffentlichung erfolgt über den Watcher; die Antwort trennt die Snapshots `desired` und `effective`. - **Einschränkungen / Validierung**: `usize`. `0` deaktiviert das geerbte Limit. - **Beschreibung**: Globales eindeutiges IP-Limit pro User, das angewendet wird, wenn ein User in `[access.user_max_unique_ips]` keine individuelle Override hat. - **Beispiel**: @@ -3660,6 +3681,7 @@ Wenn Backend oder Netzwerk stark bandbreitenbeschränkt sind, reduzieren Sie zue user_max_unique_ips_global_each = 8 ``` ## user_max_unique_ips_mode + - **API**: Das Feld ist über `GET/PATCH /v1/access/policy` verfügbar. Auslassen behält den Wert bei; `null` setzt ihn auf den Typstandard zurück. Die Veröffentlichung erfolgt über den Watcher; die Antwort trennt die Snapshots `desired` und `effective`. - **Einschränkungen / Validierung**: Muss einer von `"active_window"`, `"time_window"`, `"combined"` sein. - **Beschreibung**: Eindeutiger Source-IP-Limit-Abrechnungsmodus. - **Beispiel**: @@ -3669,6 +3691,7 @@ Wenn Backend oder Netzwerk stark bandbreitenbeschränkt sind, reduzieren Sie zue user_max_unique_ips_mode = "active_window" ``` ## user_max_unique_ips_window_secs + - **API**: Das Feld ist über `GET/PATCH /v1/access/policy` verfügbar. Auslassen behält den Wert bei; `null` setzt ihn auf den Typstandard zurück. Die Veröffentlichung erfolgt über den Watcher; die Antwort trennt die Snapshots `desired` und `effective`. - **Einschränkungen / Validierung**: Muss `> 0` sein. - **Beschreibung**: Fenstergröße (Sekunden), die von Abrechnungsmodi mit eindeutiger IP verwendet wird, die ein Zeitfenster enthalten (`"time_window"` und `"combined"`). - **Beispiel**: @@ -3678,6 +3701,7 @@ Wenn Backend oder Netzwerk stark bandbreitenbeschränkt sind, reduzieren Sie zue user_max_unique_ips_window_secs = 30 ``` ## user_source_deny + - **API**: `source_deny` in Benutzer-GET/create/PATCH stellt diese Liste bereit. Auslassen behält sie bei, ein Array ersetzt sie vollständig und `null` entfernt den konfigurierten Eintrag. Die strikte Validierung akzeptiert diese Map. `source_deny_status.runtime_reload_required` vergleicht gewünschte und veröffentlichte Regeln; angewendet werden sie mit `POST /v1/system/reload`. Der Watcher aktualisiert diese Regeln nicht; Speichern beendet keine Sitzungen. Beim Löschen eines Benutzers bleibt die Regel erhalten. Ein erneut angelegter Name übernimmt sie, sofern nicht ausdrücklich `source_deny=null` angegeben wird. - **Einschränkungen / Validierung**: Tabelle `username -> IpNetwork[]`. Jedes Netzwerk muss als CIDR parsen (zum Beispiel `203.0.113.0/24` oder `2001:db8::/32`). - **Beschreibung**: Source-IP/CIDR-Verweigerungsliste pro User wird **nach erfolgreicher Authentifizierung** in den Handshake-Pfaden TLS und MTProto angewendet. Eine übereinstimmende Source-IP wird über denselben Fail-Closed-Pfad wie eine ungültige Authentifizierung abgelehnt. - **Beispiel**: @@ -3730,6 +3754,7 @@ Wenn Backend oder Netzwerk stark bandbreitenbeschränkt sind, reduzieren Sie zue alice = { up_bps = 1048576, down_bps = 2097152 } ``` ## cidr_rate_limits + - **API**: Das Feld ist über `GET/PATCH /v1/access/policy` verfügbar. Auslassen behält den Wert bei; `null` setzt einen Skalar auf den Typstandard zurück. Bei `cidr_rate_limits` werden Schlüssel zusammengeführt, ein null-Eintrag löscht eine Regel und `null` für die gesamte Map löscht alle Regeln. Ratenobjekte ersetzen beide Richtungen, angegeben in Bit pro Sekunde. Die Veröffentlichung erfolgt über den Watcher; die Antwort trennt die Snapshots `desired` und `effective`. - **Einschränkungen / Validierung**: Tabelle `CIDR oder Auto-Template -> { up_bps, down_bps }`. Jede Richtung muss in `0..=100000000000` liegen; `0` bedeutet für diese Richtung unbegrenzt, und mindestens eine Richtung muss ungleich Null sein. Explizite CIDR-Schlüssel müssen als `IpNetwork` parsbar sein; Auto-Template-Schlüssel müssen `*4/N` (`N=0..32`), `*6/N` (`N=0..128`) oder `*/N` (`N=0..32`) verwenden. Doppelte normalisierte Auto-Templates werden abgelehnt. - **Beschreibung**: Source-Subnetz-Bandbreitenlimits, die zusätzlich zu Per-User-Limits greifen. Explizite CIDR-Regeln verwenden Longest-Prefix-Wins und haben Vorrang vor Auto-Templates. Auto-Templates erzeugen Buckets lazy pro passendem Source-Subnetz: `*4/N` für IPv4, `*6/N` für IPv6 und `*/N` als Dual-Stack-Shorthand, bei dem IPv4 `/N` und IPv6 `/(N * 4)` nutzt. - **Beispiel**: diff --git a/docs/Config_params/CONFIG_PARAMS.en.md b/docs/Config_params/CONFIG_PARAMS.en.md index 9ebdf9f..28929b6 100644 --- a/docs/Config_params/CONFIG_PARAMS.en.md +++ b/docs/Config_params/CONFIG_PARAMS.en.md @@ -1903,11 +1903,12 @@ A valid public SOCKS `BND.ADDR/BND.PORT` with a nonzero port supplies the comple cache_public_ip_path = "cache/public_ip.txt" ``` ## dns_overrides - - **Constraints / validation**: `String[]`. Each entry must use `host:port:ip` format. - - `host`: domain name (must be non-empty and must not contain `:`) - - `port`: `u16` - - `ip`: IPv4 (`1.2.3.4`) or bracketed IPv6 (`[2001:db8::1]`). **Unbracketed IPv6 is rejected**. - - **Description**: Runtime DNS overrides for `host:port` targets. Useful for forcing specific IPs for given upstream domains without touching system DNS. + - **Constraints / validation**: `String[]`, at most `4096` entries. Each entry must use `host:port:ip` format. + - `host`: domain name (must be nonempty and must not contain `:`). + - `port`: `u16`. + - `ip`: IPv4 (`1.2.3.4`) or bracketed IPv6 (`[2001:db8::1]`). Unbracketed IPv6 is rejected. + - **Description**: Overrides future `host:port` lookups through the generation resolver without changing system DNS. Host matching is case-insensitive and port-specific; the last duplicate host/port entry wins. The existing watcher publishes changes, while established connections keep their endpoints. + - **Control API**: `GET /v1/config` exposes only `network.dns_overrides` from `[network]`, including the default `[]`. `PATCH /v1/config` and `POST /v1/config/validate` accept this field; other network fields remain rejected. The array replaces the complete list; `[]` clears it, while `null` does not. Persistence changes only the value or inserts its declaration in the owning source, preserving sibling settings and other include files. Ambiguous or multiple source owners return `409 config_patch_not_atomic`. PATCH does not wait for watcher publication; inspect `GET /v1/config/state?sections=network` for publication evidence. See [DNS overrides in the API](../Architecture/API/API.md#dns-overrides). - **Example**: ```toml @@ -2216,8 +2217,23 @@ Note: The conntrack-control worker runs **only on Linux**. On other operating sy # [server.api] -Note: This section also accepts the legacy alias `[server.admin_api]` (same schema as `[server.api]`). +The legacy alias `[server.admin_api]` uses the same schema. +All fields in this section have `Hot-Reload = ✘`: the file watcher retains the +active API settings. Explicit generation reload applies `whitelist`, +`gray_action`, `auth_header`, `request_body_limit_bytes`, +`minimal_runtime_enabled`, `minimal_runtime_cache_ttl_ms`, +`runtime_edge_enabled`, `runtime_edge_cache_ttl_ms`, `runtime_edge_top_n`, and +`read_only`. `enabled`, `listen`, and `runtime_edge_events_capacity` require a +process restart. + +Edit the owning TOML source, then use `POST /v1/system/reload` for fields that a +generation reload can apply. `PATCH /v1/config` currently permits only +`server.listeners` under `server`; it cannot write `server.api.*`. +`GET /v1/config/schema` describes each field's exposure and application policy. +`GET /v1/config/state` reports desired/published differences without claiming +complete consumer convergence. See the [API reference](../Architecture/API/API.md) +and [Python client guide](../Architecture/API/PYTHON_CLIENT.md). | Key | Type | Default | Hot-Reload | | --- | ---- | ------- | ---------- | @@ -2246,7 +2262,7 @@ Note: This section also accepts the legacy alias `[server.admin_api]` (same sche ``` ## gray_action - **Constraints / validation**: `"drop"`, `"api"`, or `"200"`. - - **Description**: API response policy for gray/limited states: drop request, serve normal API response, or force `200 OK`. + - **Description**: Applies only to direct peers outside `whitelist`: `"drop"` closes the connection without an HTTP response, `"api"` returns structured `403 forbidden`, and `"200"` returns an empty `200 OK` with `text/html; charset=utf-8`. It never grants API access. Allowed peers still undergo authentication and read-only checks; an empty gray response is not a JSON success envelope. - **Example**: ```toml @@ -2281,7 +2297,7 @@ Note: This section also accepts the legacy alias `[server.admin_api]` (same sche auth_header = "Bearer MY_TOKEN" ``` ## request_body_limit_bytes - - **Constraints / validation**: Must be `> 0` (bytes). + - **Constraints / validation**: `1..=1048576` (bytes). - **Description**: Maximum accepted HTTP request body size (bytes). - **Example**: @@ -3572,6 +3588,7 @@ If your backend or network is very bandwidth-constrained, reduce cap first. If p alice = 500 ``` ## user_max_tcp_conns_global_each + - **API**: `GET/PATCH /v1/access/policy` exposes this field. Omission preserves it; scalar `null` restores the type default. Publication uses the watcher; the response separates `desired` and `effective` snapshots. - **Constraints / validation**: `usize`. `0` disables the inherited limit. - **Description**: Global per-user maximum concurrent TCP connections, applied when a user has **no positive** entry in `[access.user_max_tcp_conns]` (a missing key, or a value of `0`, both fall through to this setting). Per-user limits greater than `0` in `user_max_tcp_conns` take precedence. - **Example**: @@ -3634,6 +3651,7 @@ If your backend or network is very bandwidth-constrained, reduce cap first. If p alice = 16 ``` ## user_max_unique_ips_global_each + - **API**: `GET/PATCH /v1/access/policy` exposes this field. Omission preserves it; scalar `null` restores the type default. Publication uses the watcher; the response separates `desired` and `effective` snapshots. - **Constraints / validation**: `usize`. `0` disables the inherited limit. - **Description**: Global per-user unique IP limit applied when a user has no individual override in `[access.user_max_unique_ips]`. - **Example**: @@ -3643,6 +3661,7 @@ If your backend or network is very bandwidth-constrained, reduce cap first. If p user_max_unique_ips_global_each = 8 ``` ## user_max_unique_ips_mode + - **API**: `GET/PATCH /v1/access/policy` exposes this field. Omission preserves it; scalar `null` restores the type default. Publication uses the watcher; the response separates `desired` and `effective` snapshots. - **Constraints / validation**: Must be one of `"active_window"`, `"time_window"`, `"combined"`. - **Description**: Unique source IP limit accounting mode. - **Example**: @@ -3652,6 +3671,7 @@ If your backend or network is very bandwidth-constrained, reduce cap first. If p user_max_unique_ips_mode = "active_window" ``` ## user_max_unique_ips_window_secs + - **API**: `GET/PATCH /v1/access/policy` exposes this field. Omission preserves it; scalar `null` restores the type default. Publication uses the watcher; the response separates `desired` and `effective` snapshots. - **Constraints / validation**: Must be `> 0`. - **Description**: Window size (seconds) used by unique-IP accounting modes that include a time window (`"time_window"` and `"combined"`). - **Example**: @@ -3661,6 +3681,7 @@ If your backend or network is very bandwidth-constrained, reduce cap first. If p user_max_unique_ips_window_secs = 30 ``` ## user_source_deny + - **API**: `source_deny` in user GET/create/PATCH exposes this list. Omission retains it, an array replaces it, and `null` removes the authored entry. Strict validation accepts this map. `source_deny_status.runtime_reload_required` compares desired and published rules; apply with `POST /v1/system/reload`. The watcher does not update these rules, and saving does not cancel sessions. Deleting a user retains the rule; recreation inherits it unless `source_deny=null` is explicit. - **Constraints / validation**: Table `username -> IpNetwork[]`. Each network must parse as CIDR (for example `203.0.113.0/24` or `2001:db8::/32`). - **Description**: Per-user source IP/CIDR deny-list applied **after successful auth** in TLS and MTProto handshake paths. A matched source IP is rejected via the same fail-closed path as invalid auth. - **Example**: @@ -3713,6 +3734,7 @@ If your backend or network is very bandwidth-constrained, reduce cap first. If p alice = { up_bps = 1048576, down_bps = 2097152 } ``` ## cidr_rate_limits + - **API**: `GET/PATCH /v1/access/policy` exposes this field. Omission preserves it; scalar `null` restores the type default. For `cidr_rate_limits`, a map merges keys, a null entry deletes one rule, and whole-map `null` clears all rules. Rate objects replace both directions, in bits per second. Publication uses the watcher; the response separates `desired` and `effective` snapshots. - **Constraints / validation**: Table `CIDR or auto-template -> { up_bps, down_bps }`. Each direction must be within `0..=100000000000`; `0` means unlimited for that direction, and at least one direction must be non-zero. Explicit CIDR keys must parse as `IpNetwork`; auto-template keys must be `*4/N` (`N=0..32`), `*6/N` (`N=0..128`), or `*/N` (`N=0..32`). Duplicate normalized auto-templates are rejected. - **Description**: Source-subnet bandwidth caps applied alongside per-user limits. Explicit CIDR rules use longest-prefix-wins and take priority over auto-templates. Auto-templates create buckets lazily per matched source subnet: `*4/N` for IPv4, `*6/N` for IPv6, and `*/N` as a dual-stack shorthand where IPv4 uses `/N` and IPv6 uses `/(N * 4)`. - **Example**: diff --git a/docs/Config_params/CONFIG_PARAMS.ru.md b/docs/Config_params/CONFIG_PARAMS.ru.md index 43ffa1c..f8e1646 100644 --- a/docs/Config_params/CONFIG_PARAMS.ru.md +++ b/docs/Config_params/CONFIG_PARAMS.ru.md @@ -1905,11 +1905,12 @@ cache_public_ip_path = "cache/public_ip.txt" ``` ## dns_overrides - - **Ограничения / валидация**: `String[]`. Каждая запись должна использовать формат `host:port:ip`. - - `host`: доменное имя (не должно быть пустым и не должно содержать `:`) - - `port`: `u16` - - `ip`: IPv4 (`1.2.3.4`) или IPv6 в квадратных скобках (`[2001:db8::1]`). **Значения IPv6 без скобок отклоняются!** - - **Описание**: Переопределение DNS во время работы для `host:port`-соединений. Позволяет принудительно задавать IP для указанных доменов, не изменяя системный DNS. + - **Ограничения / валидация**: `String[]`, не более `4096` записей. Каждая запись задаётся в формате `host:port:ip`. + - `host`: доменное имя, непустое и без `:`. + - `port`: `u16`. + - `ip`: IPv4 (`1.2.3.4`) или IPv6 в квадратных скобках (`[2001:db8::1]`). IPv6 без скобок отклоняется. + - **Описание**: Переопределяет будущие запросы `host:port` через резолвер поколения, не меняя системный DNS. Имена сравниваются без учёта регистра, порт должен совпадать; при повторении пары имя/порт действует последняя запись. Изменения публикует существующий watcher, а установленные соединения сохраняют свои адреса назначения. + - **Control API**: `GET /v1/config` возвращает из `[network]` только `network.dns_overrides`, включая значение по умолчанию `[]`. `PATCH /v1/config` и `POST /v1/config/validate` принимают это поле; остальные поля network по-прежнему отклоняются. Массив заменяет весь список; `[]` очищает его, а `null` — нет. При сохранении заменяется только значение или добавляется объявление ключа в файле-владельце; соседние настройки и другие include-файлы сохраняются. Неоднозначное владение или несколько файлов-владельцев дают `409 config_patch_not_atomic`. PATCH не ждёт публикации watcher’ом; её состояние доступно через `GET /v1/config/state?sections=network`. См. [DNS overrides в API](../Architecture/API/API.md#dns-overrides). - **Пример**: ```toml @@ -2222,8 +2223,24 @@ # [server.api] -Примечание: В этом разделе также задается устаревший параметр `[server.admin_api]` (аналогично `[server.api]`). +Устаревший алиас `[server.admin_api]` использует ту же схему. +Для всех полей этого раздела указано `Hot-Reload = ✘`: watcher сохраняет +действующие настройки API. Явный reload поколения применяет `whitelist`, +`gray_action`, `auth_header`, `request_body_limit_bytes`, +`minimal_runtime_enabled`, `minimal_runtime_cache_ttl_ms`, +`runtime_edge_enabled`, `runtime_edge_cache_ttl_ms`, `runtime_edge_top_n` и +`read_only`. Для `enabled`, `listen` и `runtime_edge_events_capacity` нужен +перезапуск процесса. + +Измените TOML-файл, которому принадлежит настройка, затем вызовите +`POST /v1/system/reload` для полей, применяемых через reload поколения. +`PATCH /v1/config` сейчас допускает только `server.listeners` внутри `server` +и не позволяет менять `server.api.*`. `GET /v1/config/schema` описывает +доступность и способ применения каждого поля. `GET /v1/config/state` показывает +различия между желаемым и опубликованным состоянием, без обещания, что все +потребители уже применили настройки. См. [справочник API](../Architecture/API/API.md) +и [руководство по Python-клиенту](../Architecture/API/PYTHON_CLIENT.md). | Ключ | Тип | По умолчанию | Hot-Reload | | --- | ---- | ------- | ---------- | @@ -2252,7 +2269,7 @@ ``` ## gray_action - **Ограничения / валидация**: `"drop"`, `"api"` или `"200"`. - - **Описание**: Политика ответа API в «серых» (ограниченных) состояниях: сброс, обычный API-ответ, либо `200 OK`. + - **Описание**: Действует только для прямых TCP-клиентов вне `whitelist`: `"drop"` закрывает соединение без HTTP-ответа, `"api"` возвращает структурированный `403 forbidden`, а `"200"` — пустой `200 OK` с `text/html; charset=utf-8`. Этот параметр не разрешает доступ к API. Клиенты из whitelist по-прежнему проходят аутентификацию и проверку режима read-only; пустой ответ не является JSON-подтверждением успеха. - **Example**: ```toml @@ -2287,7 +2304,7 @@ auth_header = "Bearer MY_TOKEN" ``` ## request_body_limit_bytes - - **Ограничения / валидация**: Должно быть `> 0` (байт). + - **Ограничения / валидация**: `1..=1048576` (байт). - **Описание**: Максимальный принимаемый размер тела HTTP-запроса (в байтах). - **Пример**: @@ -3595,6 +3612,7 @@ bootstrap переживает reload только при сохранении alice = 500 ``` ## user_max_tcp_conns_global_each + - **API**: Поле доступно через `GET/PATCH /v1/access/policy`. Пропуск сохраняет значение; `null` восстанавливает значение типа по умолчанию. Публикация идёт через watcher; ответ разделяет снимки `desired` и `effective`. - **Ограничения / валидация**: `usize`. `0` - отключает лимит. - **Описание**: Глобальное максимальное количество одновременных TCP-соединений для каждого пользователя, применяется, когда у пользователя **нет** записи в `[access.user_max_tcp_conns]` (отсутствующее или равное `0` значения подпадают под это условие). Ограничения на пользователя, превышающие `0` в параметре `user_max_tcp_conns`, имеют приоритет. - **Пример**: @@ -3657,6 +3675,7 @@ bootstrap переживает reload только при сохранении alice = 16 ``` ## user_max_unique_ips_global_each + - **API**: Поле доступно через `GET/PATCH /v1/access/policy`. Пропуск сохраняет значение; `null` восстанавливает значение типа по умолчанию. Публикация идёт через watcher; ответ разделяет снимки `desired` и `effective`. - **Ограничения / валидация**: `usize`. `0` - отключает лимит. - **Описание**: Глобальный лимит на количество уникальных IP-адресов, с которых выполняется подключение, для каждого пользователя, когда у пользователя нет индивидуального переопределения в `[access.user_max_unique_ips]`. - **Пример**: @@ -3666,6 +3685,7 @@ bootstrap переживает reload только при сохранении user_max_unique_ips_global_each = 8 ``` ## user_max_unique_ips_mode + - **API**: Поле доступно через `GET/PATCH /v1/access/policy`. Пропуск сохраняет значение; `null` восстанавливает значение типа по умолчанию. Публикация идёт через watcher; ответ разделяет снимки `desired` и `effective`. - **Ограничения / валидация**: `"active_window"`, `"time_window"`, `"combined"`. - **Описание**: Режим учета лимита уникальных IP-адресов. - **Пример**: @@ -3675,6 +3695,7 @@ bootstrap переживает reload только при сохранении user_max_unique_ips_mode = "active_window" ``` ## user_max_unique_ips_window_secs + - **API**: Поле доступно через `GET/PATCH /v1/access/policy`. Пропуск сохраняет значение; `null` восстанавливает значение типа по умолчанию. Публикация идёт через watcher; ответ разделяет снимки `desired` и `effective`. - **Ограничения / валидация**: Должно быть `> 0`. - **Описание**: Размер временного окна (в секундах), используемого режимами учёта уникальных IP, которые работают с ограничением по времени (значения `"time_window"` и `"combined"`). - **Пример**: @@ -3684,6 +3705,7 @@ bootstrap переживает reload только при сохранении user_max_unique_ips_window_secs = 30 ``` ## user_source_deny + - **API**: Список доступен как `source_deny` в GET/create/PATCH пользователя. Пропуск сохраняет список, массив заменяет его целиком, а `null` удаляет запись из конфигурации. Строгая валидация принимает эту таблицу. `source_deny_status.runtime_reload_required` сравнивает сохранённые и опубликованные правила; для применения нужен `POST /v1/system/reload`. Watcher эти правила не обновляет; сохранение не отменяет сессии. Удаление пользователя сохраняет правило, которое наследуется при повторном создании имени, если явно не передать `source_deny=null`. - **Ограничения / валидация**: Таблица `username -> IpNetwork[]`. Каждая сеть должна разбираться как CIDR, например `203.0.113.0/24` или `2001:db8::/32`. - **Описание**: Deny-list исходных IP/CIDR для конкретного пользователя, применяемый **после успешной аутентификации** в TLS- и MTProto-handshake путях. Совпавший source IP отклоняется тем же fail-closed путём, что и невалидная аутентификация. - **Пример**: @@ -3736,6 +3758,7 @@ bootstrap переживает reload только при сохранении alice = { up_bps = 1048576, down_bps = 2097152 } ``` ## cidr_rate_limits + - **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**: