Командная строка и каталог данных

Все параметры и переменные окружения headless Throne, где он хранит данные, как перезапускается и что означают его коды завершения.

На этой странице перечислены параметры и переменные окружения headless Throne, а также описано, где он хранит данные, как перезапускается и что означают его коды завершения. Параметры командной строки приложения для компьютера описаны в разделе Командная строка.

Параметры и переменные

Throne --headless --help выводит список параметров. Подходит и один дефис, и два (-data-dir — то же самое, что --data-dir), а значение указывается после пробела или =. Параметр имеет приоритет над соответствующей переменной. Переменная с пустым значением считается незаданной, кроме THRONE_API_ALLOW.

Параметр	Переменная	Что делает
`--headless`	`THRONE_HEADLESS=1`	Запуск без окна. Любое значение переменной, кроме пустого, `0`, `false`, `no` и `off`, включает этот режим.
`--data-dir DIR` (`-appdata DIR`)	`THRONE_DATA_DIR`	Каталог данных.
`--restart-mode MODE`	`THRONE_RESTART_MODE`	`auto` (по умолчанию), `exit` или `exec`. См. Режимы перезапуска.
`--no-resume`	`THRONE_RESUME=0`	Не запускать последний профиль при запуске.
`--no-kill-switch`	`THRONE_KILL_SWITCH=0`	Держать kill switch выключенным в этом запуске, даже если настройка `kill_switch` включена. Профили по-прежнему отклоняются, пока настройка не будет выключена. Предназначено для восстановления доступа.
`--log-format FORMAT`	`THRONE_LOG_FORMAT`	`auto` (по умолчанию), `journal` или `plain`. См. Логи.
`--api-listen LISTEN`	`THRONE_API_LISTEN`	Где слушает Throne API: `PORT` (на `127.0.0.1`), `IPv4:PORT`, `[IPv6]:PORT`, `*:PORT` (все адреса) или `off`. По умолчанию: `127.0.0.1:9095`, если API не включён в сохранённых настройках.
`--api-key-file FILE`	`THRONE_API_KEY_FILE`	Читать ключ API из этого файла; файл должен существовать. Такой файл создаёт `thronectl keygen -o FILE`. По умолчанию: `config/api.key` в каталоге данных, создаётся при первом запуске.
`--api-admin-lan`	`THRONE_API_ADMIN_LAN=1`	Отвечать на административные запросы (импорт, настройки, резервные копии, перезапуск) и из сети, а не только с этого устройства.
`--api-allow LIST`	`THRONE_API_ALLOW`	Адреса и подсети, которым разрешено пользоваться слушателем не на loopback, через запятую или пробел. Пустой список приводит к завершению с кодом 64. Чтобы разрешить все адреса, оставьте переменную незаданной.
`--debug`		Отладочное логирование.
`--service`		Только Windows: работа под управлением диспетчера служб (Service Control Manager), в режиме headless даже без `--headless`. При любом другом способе запуска приводит к завершению с кодом 64.
`--health`		Спросить работающий Throne о его состоянии. См. Throne --health.
`--print-connection`		Вывести `THRONE_ADDR` и `THRONE_KEY_FILE` для `thronectl`. См. Подключение thronectl к Throne.
`--check`		Проверить, может ли этот компьютер запустить headless Throne. См. Throne --check.
`--help`, `--version`		Вывести список параметров или версию.

Переменные типа «да/нет» принимают 1, true, yes, on, 0, false, no или off. Любое другое значение приводит к завершению с кодом 64.
Параметры и переменные --api-* при каждом запуске переопределяют сохранённые настройки API и никогда не сохраняются. Поэтому неудачную сохранённую настройку API всегда можно исправить из командной строки.
--health, --print-connection и --check работают без --headless. Используйте только один из них за раз и никогда вместе с --service.
Ссылка или файл в командной строке приводят к завершению с кодом 64. Импортируйте их через thronectl import.

С юнитом systemd задавайте переменные в /etc/throne/throne.env, а параметры — с помощью drop-in-файла. См. Debian, Ubuntu, Raspberry Pi OS, Fedora, openSUSE.

Каталог данных

Headless Throne использует первый подходящий вариант из списка:

--data-dir, затем THRONE_DATA_DIR. Относительный путь отсчитывается от папки, в которой запускается Throne.
STATE_DIRECTORY, которую systemd задаёт для StateDirectory=.
От root: /var/lib/throne в Linux, /Library/Application Support/Throne в macOS. В Windows с --service или от LocalSystem: C:\ProgramData\Throne.
Папка конфигурации пользователя, которую использует и приложение для компьютера: ~/.config/Throne в Linux, ~/Library/Preferences/Throne в macOS, %LOCALAPPDATA%\Throne в Windows. Если в Linux или macOS не задан HOME, Throne завершается с кодом 78; укажите каталог через --data-dir.

Headless Throne никогда не хранит данные рядом с программой, как это делает портативная установка приложения для компьютера. Чтобы использовать данные такой установки, передайте в --data-dir папку программы.

В Linux и macOS он создаёт недостающие каталоги, доступные для чтения только его пользователю. При запуске от root он отказывается использовать каталог данных, в который могут записывать другие пользователи (код 78), потому что в настройках указаны программы, которые запускает Throne. В Windows доступ к C:\ProgramData\Throne есть только у SYSTEM и администраторов (см. Папка данных); если в другой каталог могут записывать обычные пользователи, в лог записывается только предупреждение.

Что в нём находится:

Путь	Содержимое
`config/throne.db`	Профили, группы, профили маршрутизации и настройки, как в приложении для компьютера
`config/api.key`	Ключ API, доступный для чтения только пользователю Throne
`config/logs/throne.log`	Лог текущего запуска. В `crashed-<time>.log` сохраняется лог запуска, который завершился некорректно.
`config/crashes/`	Отчёты о сбоях
`config/headless-state.json`	Счётчики для возобновления профиля и для сбоев, а также сведения о том, как завершился последний запуск
`config/hwid`	Идентификатор устройства, если в системе его нет
`config/.lock`, `config/.instance`	Блокировка каталога данных и сокет, к которому обращается `--health`. В Windows экземпляр — это именованный канал, а не файл.

Режимы перезапуска

thronectl restart, восстановление резервной копии и сигнал SIGHUP перезапускают Throne. Как именно, определяет --restart-mode:

Режим	Что происходит
`exit`	Throne завершается с кодом 75, и менеджер служб запускает его снова.
`exec`	Throne перезапускается в том же процессе (Linux и macOS; идентификатор процесса не меняется). В Windows он запускает новый процесс Throne и завершается с кодом 0. Служба Windows всегда использует `exit`.
`auto`	`exit`, если Throne запустили systemd (через свой сокет уведомлений или пользовательский менеджер), launchd или init контейнера либо если он работает как служба Windows. `exec` в остальных случаях, например при запуске из терминала.

Поставляемые юниты, plist и образ Docker требуют auto или exit. Throne --check показывает, что выбирает auto. Если Throne запущен в терминале, закрытие терминала (обрыв связи, hang-up) останавливает Throne с кодом 0, а не перезапускает его.

Коды завершения

Перед завершением Throne записывает в лог EXIT <code>: <reason>. Что поставляемые файлы служб делают при каждом коде:

Код	Значение	Юнит systemd	Docker `unless-stopped`	plist launchd	Служба Windows
0	Остановка: `SIGTERM`, `SIGINT`, `thronectl shutdown`; в Windows также остановка службы, `Ctrl+C`, закрытие консоли, выход из системы или `taskkill` без `/F`. А также перезапуск в Windows вне службы, при котором уже запущен новый Throne.	Остаётся остановленным	Запускается снова, если не было `docker stop`	Остаётся остановленным	Остаётся остановленной
1	Запуск не удался по причине, которая может исчезнуть: блокировка, сокет экземпляра, база данных, IPC-слушатель ядра или адрес `--api-listen`, который не появился в течение 30 секунд	Запускается снова через 3 с	Запускается снова	Запускается снова через 10 с	Восстановление
3	Каталог данных использует другой Throne	Остаётся остановленным	Запускается снова	Повтор каждые 10 с	Восстановление
64	Неверный параметр, значение параметра или переменная либо `--service`, запущенный не диспетчером служб	Остаётся остановленным	Запускается снова	Повтор каждые 10 с	Восстановление
70	Ядро постоянно падало, и Throne прекратил попытки, или ядро было непригодно к работе в течение 60 секунд	Запускается снова	Запускается снова	Запускается снова	Восстановление
71	Профиль подключался 180 секунд или останавливался 90 секунд	Запускается снова	Запускается снова	Запускается снова	Восстановление
75	Запрошен перезапуск (с `--restart-mode exit` или в службе Windows) либо перезапуск `exec` не удалось выполнить	Запускается снова	Запускается снова	Запускается снова	Восстановление
78	Ошибка конфигурации: каталог данных (в том числе нет `HOME`, чтобы его найти, или в Windows `C:\ProgramData\Throne` принадлежит другому пользователю, доступен для записи другим пользователям или является ссылкой), файл ключа API, слушатель `--api-listen` или файл базы данных, который нельзя использовать	Остаётся остановленным	Запускается снова	Повтор каждые 10 с	Восстановление

«Восстановление» — это действия восстановления службы Windows: см. Служба Windows.

У юнита systemd нет ограничения на число запусков (StartLimitIntervalSec=0). Каждый thronectl restart, каждое восстановление и каждый SIGHUP — это новый запуск, и ограничение оставило бы Throne остановленным без API.
Docker ждёт всё дольше перед каждым следующим перезапуском подряд.
После трёх запусков подряд без работающего ядра Throne перестаёт завершаться с кодами 70 и 71 и вместо этого остаётся запущенным.
Если код 78 вызван базой данных, лог сообщает, что делать: переместите повреждённый config/throne.db в другое место вместе с его файлами -wal и -shm или верните резервную копию файла. Файлы только для чтения сделайте доступными для записи пользователю Throne.

Команды проверки завершаются со своими кодами:

Команда	0	1	2	64
`--health`	Исправен	Неисправен или ещё запускается	Ни один Throne не ответил, или служба Windows отклонила запрос из командной строки без повышенных прав	Неверный параметр
`--check`	Нет строк `[FAIL]`	Есть строка `[FAIL]`		Неверный параметр
`--print-connection`	Выведены обе строки		API выключен или не слушает, или его ключ хранится не в файле; или служба Windows отклонила запрос из командной строки	Неверный параметр

--health и --print-connection завершаются с кодом 78, если не находят каталог данных (нет HOME); укажите его через --data-dir.