view /ru/plugins/server-setup-base

server-setup-base

Local server baseline checks and controlled setup operations for ohtools.

Подписанprotocol v1linux/amd64Только локально

Установка

              sudo ohtools plugin install server-setup-base

Базовая настройка сервера

Назначение и поддерживаемые сценарии

server-setup-base проверяет, соответствует ли поддерживаемый сервер Debian или Ubuntu встроенному базовому профилю ohtools. Плагин умеет планировать и применять недостающее локальное состояние, а также обновлять разрешённые пакеты, только если необходимые файлы пакетов уже доступны локально.

Версия 1 содержит точные профили Debian 10, 11, 12 и 13, а также Ubuntu 20.04, 22.04 и 24.04. Плагин предназначен для первоначальной подготовки сервера, проверки отклонений, повторяемого приведения к профилю и ограниченного обновления состояния ohtools. Это не универсальная система управления конфигурацией.

Быстрый старт

Проверка без изменений:

ohtools setup check

Предварительный просмотр точного плана:

ohtools --dry-run setup apply

Применение после проверки плана. Host требует root, разрешение policy, доступность audit и подтверждение, если не указан --yes:

ohtools --yes setup apply

Проверка и применение только кэшированных обновлений пакетов:

ohtools --dry-run setup upgrade
ohtools --yes setup upgrade

Команды

setup check

Диагностическая read-only команда выбирает точный встроенный профиль, проверяет каждый объект и формирует checks для пакетов, системной группы и пользователя, каталогов, управляемого файла, sysctl и systemd unit. Отсутствие или отличие состояния обычно даёт warning. Неподдерживаемая платформа даёт critical check platform и структурированную ошибку конфигурации.

setup apply

При планировании повторяется полная проверка, после чего warning и critical объекты преобразуются в упорядоченный список изменений: пакеты, группы, пользователи, каталоги, файлы, sysctl и units. Execute принимает только digest текущего плана, повторно проверяет состояние, выполняет транзакцию, проверяет каждый изменённый объект и делает commit только после успешной проверки.

Установка пакетов использует apt-get --no-download; версия 1 никогда не скачивает пакет из репозитория. Ошибка изменения или проверки запускает ограниченный rollback.

setup upgrade

Плагин просит apt-get локально смоделировать --no-download --only-upgrade для трёх встроенных пакетов. В план попадают только разрешённые пакеты, обнаруженные этой симуляцией. Выполнение использует тот же plan digest, транзакцию, rollback и итоговую проверку, что и setup apply.

Команда не является обновлением дистрибутива, не добавляет репозитории и не скачивает пакеты.

Как это работает

Плагин определяет платформу внутри выбранного локального root и выбирает автоматически подходящий либо явно указанный точный профиль. Каждый профиль содержит неизменяемые спецификации пакетов, учётных записей, каталогов, управляемого файла, sysctl и unit.

Проверка выполняется по этапам:

Ограниченный вызов dpkg-query для ca-certificates, curl и jq.
Ограниченное чтение и строгий разбор /etc/group и /etc/passwd.
Проверка типа, режима, владельца и confinement каждого каталога.
Чтение управляемого файла без перехода по symlink и сравнение SHA-256, режима, владельца и группы.
Чтение встроенных sysctl через sysctl -n.
Проверка включения unit через systemctl is-enabled.
Формирование Result v1 с детерминированными ID checks и ID профиля.

Планирование mutation отклоняет skipped, error, partial и cancelled checks. Перед execute план пересчитывается, а digest сравнивается за постоянное время. Транзакция хранит undo-операции. Управляемые файлы заменяются атомарно, а commit возможен только после успешной итоговой проверки.

Доступ к данным

Плагин читает:

/etc/os-release под выбранным root для определения платформы;
/etc/group и /etc/passwd с лимитом account_file_limit_bytes;
/etc/ohtools/setup-state.yaml с лимитом managed_file_limit_bytes;
метаданные /etc/ohtools, /etc/ohtools/plugins, /var/lib/ohtools и /var/log/ohtools;
текущие значения sysctl и состояние systemd unit;
локальную базу dpkg и локальный APT cache через фиксированные команды.

После разрешения доверенного абсолютного пути вызываются dpkg-query, apt-get, groupadd, groupdel, useradd, userdel, sysctl и systemctl с фиксированной структурой argv. Shell не используется.

Apply может создать системную группу и пользователя ohtools, создать или исправить встроенные каталоги, атомарно заменить state-файл, установить два sysctl защиты ссылок и включить systemd-timesyncd.service.

Результаты и коды завершения

Плагин всегда использует Result schema v1. Основные префиксы check ID: package:, group:, user:, directory:, file:, sysctl: и unit:. Поле data.profile содержит выбранный встроенный профиль.

Ошибки чтения, которые не делают выполнение небезопасным, представлены skipped checks и структурированными errors. Отмена контекста и timeout остаются фатальными. Ошибки конфигурации и выбора платформы используют configuration exit mapping. Отсутствие executable использует dependency mapping. Неверный вызов или устаревший plan digest использует arguments mapping. Ошибка транзакции, rollback или проверки использует general failure mapping.

В JSON-режиме stdout содержит только Result. Диагностика остаётся в stderr, а вывод внешних команд не копируется в audit.

Конфигурация

Единственный путь конфигурации:

/etc/ohtools/plugins/server-setup-base.yaml

Значения по умолчанию:

profile: auto
managed_file_limit_bytes: 1048576
account_file_limit_bytes: 262144

profile может быть auto или точным встроенным ID, например debian-12 либо ubuntu-24.04. Явный профиль обязан совпадать с обнаруженной поддерживаемой платформой.

managed_file_limit_bytes принимает значения от 4096 до 8388608 байт. account_file_limit_bytes принимает значения от 4096 до 1048576 байт.

Используется строгий YAML. Неизвестные и повторяющиеся ключи, несколько документов, неверные диапазоны, symlink, небезопасный владелец или доступ на запись для группы либо остальных дают ошибку конфигурации. Пользовательский config, host --config, environment и XDG paths не могут переопределить эту системную конфигурацию.

Что можно изменить

Оператор может выбрать точный поддерживаемый профиль и изменить два лимита чтения в разрешённых диапазонах. Оператор также решает, когда подтверждать разрешённый mutation plan.

Host policy может дополнительно ограничить operational-команды. Содержимое локального package cache определяет, сможет ли setup apply установить отсутствующий пакет и сможет ли setup upgrade запланировать обновление.

Сопровождающие могут изменить встроенные профили, checks, лимиты и transaction adapters только через проверенное изменение исходного кода, тесты и новый immutable release плагина.

Зафиксированное поведение

Матрица платформ, три пакета, identity ohtools, пути и режимы каталогов, содержимое управляемого файла, sysctl защиты ссылок и systemd unit встроены в версию 1. Их нельзя передать через YAML.

Команда не принимает произвольные имена пакетов, пути, sysctl, units, shell fragments, repository URLs, credentials или remote hosts. Порядок apply, проверка plan digest, итоговая verification и rollback обязательны.

Безопасность

setup check работает read-only и не требует root. Обе mutation-команды объявляют в manifest требования root и confirmation и поддержку dry-run. Host отвечает за policy authorization, audit fail-closed, confirmation, timeout и redaction до запуска плагина.

Все operational-команды вызываются напрямую через argv с option terminators. Встроенные имена и значения проверяются до использования. Path traversal, symlink в управляемом пути, небезопасное владение, превышение лимита чтения, неполные checks, устаревший plan digest и операции с некэшированными пакетами отклоняются.

Rollback выполняется с пятиисекундным bounded context. Ошибка rollback редактируется и возвращается вместе с первичной ошибкой транзакции.

Диагностика проблем

Если профиль не найден, проверьте, что /etc/os-release определяет точный поддерживаемый Debian или Ubuntu, и удалите неверный явный профиль.
При exit 10 проверьте strict YAML, permissions, ownership, имена ключей, profile ID и диапазоны byte limits.
Если отсутствует dependency, восстановите executable из дистрибутива; не подставляйте shell wrapper раньше него в PATH.
Если для apply нет локальных package bytes, заполните разрешённый cache отдельным контролируемым процессом. Плагин не будет их скачивать.
Если план сообщает о неполных checks, устраните ошибку файла, executable, permissions или output limit и снова выполните setup check.
При устаревшем plan digest проверьте новый план вместо повторного применения прежнего digest.
После transaction failure изучите редактированный Result и root audit, исправьте локальную причину и выполните read-only check перед новым apply.

Ограничения и TODO

Версия 1 намеренно local-only. Bootstrap репозиториев, сетевое получение пакетов, credential references, remote orchestration и multi-host fan-out отложены. Будущее сетевое поведение потребует immutable coordinates, expected hashes, endpoint allowlists, HTTPS и signature verification, redirect limits, изоляцию секретов и отдельную авторизацию каждого сервера.

Актуальный backlog и критерии приёмки находятся в roadmap настройки сервера.

Совместимость и исходный код

Страница описывает server-setup-base 1.0.0 и plugin protocol v1. Запись подписанного каталога задаёт минимальную совместимую версию host и остаётся источником истины для установки, размера asset, SHA-256 и release history.

Реализация: internal/serversetup.

Команды manifest

Путь	Категория	Поведение	Безопасность
`setup check`	diagnostic	Check the compiled server setup baseline	read-only
`setup apply`	operational	Apply the compiled server setup baseline	root · dry-run · confirm
`setup upgrade`	operational	Upgrade ohtools-owned setup state	root · dry-run · confirm

История версий

Версия	Опубликована	Минимальный host	Артефакт
v1.0.0	28 июл. 2026 г.	v0.3.2	3.27 MiB `e42e556702fb…`