CLI in Docs

This commit is contained in:
Alexey
2026-11-11 23:52:01 +03:00
parent cd74d78eb5
commit 691051cad6
3 changed files with 222 additions and 0 deletions
+74
View File
@@ -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.
+74
View File
@@ -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.
+74
View File
@@ -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` — разные инструменты.