Alteratorctl

Данная страница находится в разработке.
Эта страница ещё не закончена. Информация, представленная здесь, может оказаться неполной или неверной.

Alteratorctl — консольная утилита для администрирования системы, основанная на архитектуре Alterator на D-Bus.

Назначение

Программа alteratorctl предназначена для:

Системных администраторов.
Опытных пользователей.

Alteratorctl является компонентом новой реализации проекта Альтератор, Alterator на D-Bus.

Установка

Команды установки Alteratorctl

# apt-get update
# apt-get install alteratorctl

Описание модулей

Приложение имеет модульную структуру. Каждый модуль позволяет изучать или конфигурировать тот или иной аспект системы и работает с определенным интерфейсом объектов на D-Bus.

Запуск модуля:

$ alteratorctl <имя_модуля> <команда_модуля>

Отображение возможностей модуля:

$ alteratorctl <имя_модуля> --help

Отображение списка модулей:

$ alteratorctl -m

В настоящий момент реализовано 7 модулей:

manager
Прямое взаимодействие с объектами Alterator на D-Bus: получить интерфейсы объекта, список объектов интерфейса, сигналы.

Интерфейс D-Bus: org.altlinux.alterator.manager (объект /org/altlinux/alterator).
editions
Просмотр доступных редакций и выбор текущей редакции.

Интерфейс D-Bus: org.altlinux.alterator.edition1 (объект /org/altlinux/alterator).
components
Управление компонентами (наборами пакетов): просмотр, поиск, статус, установка и удаление.

Интерфейс D-Bus: org.altlinux.alterator.component1 (объекты /org/altlinux/alterator/component_*).
diag
Запуск диагностических инструментов и тестов, формирование отчётов.

Интерфейс D-Bus: org.altlinux.alterator.diag1 (объекты /org/altlinux/alterator/diag_*).
packages
Управление пакетами и репозиториями (подмодули apt, repo, rpm).

Интерфейс D-Bus: org.altlinux.alterator.rpm1, org.altlinux.alterator.apt1, org.altlinux.alterator.repo1 (объекты /org/altlinux/alterator/rpm, /org/altlinux/alterator/apt, /org/altlinux/alterator/repo).
systeminfo
Получение системной информации (сводка и отдельные параметры).

Интерфейс D-Bus: org.altlinux.alterator.systeminfo1 (объект /org/altlinux/alterator/systeminfo).
services
Управление сервисами ALT Services: состояние, параметры, развёртывание и диагностика.

Интерфейс D-Bus: org.altlinux.alterator.service1 (объекты /org/altlinux/alterator/service_*).

Модуль services

Services — модуль alteratorctl для управления сервисами ALT Services из командной строки: получение списка сервисов и их состояния, просмотр параметров, развёртывание и настройка, запуск/остановка, резервное копирование и восстановление, деактивация, запуск диагностики.

Команды, которые меняют состояние системы (deploy/configure/undeploy/backup/restore и т.п.), как правило, требуют прав администратора и могут запрашивать подтверждение.

Начало работы

Рекомендуется начать со списка доступных сервисов и их состояния:

$ alteratorctl services
▲ Samba AD (service_samba_ad)    не развёрнут
■ Сервис Chrony (chrony_service) развёрнут, запущен

Для получения описания сервиса и схемы параметров используйте info:

$ alteratorctl services info <сервис>

Для вывода путей объектов на D-Bus (например, для сопоставления с busctl) используйте -v:

$ alteratorctl services -v
■ Сервис Chrony (chrony_service: /org/altlinux/alterator/service_chrony) развёрнут, запущен

Обозначения состояний

В списке сервисов используются маркеры:
■ — развёрнут, запущен.
● — развёрнут, остановлен.
▲ — не развёрнут.

Основные команды

list — список сервисов (команда по умолчанию).
info <сервис> — описание сервиса и схема параметров (alterator entry).
status <сервис> — текущее состояние и параметры сервиса.
resources <сервис> — ресурсы сервиса (порты/юниты/пути и т.п.; набор зависит от сервиса).
deploy / configure / start / stop / undeploy — управление состоянием сервиса.
backup / restore — резервное копирование и восстановление (если поддерживается сервисом).
diagnose — запуск диагностических тестов сервиса.
play <файл|-> — выполнить действие по playfile (как правило, экспортированному из Alt-Services).

Опции вывода списка

При выводе списка (без указания команды или с командой list) доступны опции форматирования:

-v / --verbose — показывать пути объектов сервиса на D-Bus.
-n / --name-only — показывать только имена сервисов.
-d / --display-name-only — показывать только отображаемые имена.
-p / --path-only — показывать только пути объектов на D-Bus.
-E / --except-status-markers — вывести список без маркеров состояния.
-H / --hide-markers-legend — скрыть легенду маркеров.

Опции выполнения

Эти опции относятся к командам управления и используются наиболее часто:

-y / --yes — автоматически отвечать «да» на запросы подтверждения (актуально для неинтерактивного запуска).
--no-default — не подставлять значения по умолчанию для параметров, которые не указаны явно.
-f / --force-deploy — принудительное развёртывание (если поддерживается сервисом).
-s / --autostart — запустить сервис сразу после развёртывания.
-a / --all — для диагностики: запустить все тесты текущего режима (пред- или постдиагностика).

Развёртывание через services play

Команда services play принимает playfile (JSON), экспортированный из Alt-Services. Этот способ удобен, когда требуется применить набор параметров, подготовленный в графическом интерфейсе.

Использование

$ alteratorctl services play <файл>
$ alteratorctl services play - < <файл>

Формат playfile (JSON)

В playfile указываются сервис, действие и параметры.

Минимальный набор полей: service — имя сервиса (например, chrony_service).
action — действие: deploy, undeploy, configure, backup, restore.
version — версия формата (поддерживается 1).
parameters — объект параметров.
options — объект опций (может отсутствовать или быть пустым).

Пример:

{
  "service": "chrony_service",
  "action": "deploy",
  "version": 1,
  "parameters": {
    "disableDefaultPoll": true
  },
  "options": {}
}

В options для deploy могут использоваться: autostart — запустить сервис после развёртывания.
force — принудительное развёртывание (если поддерживается конкретным сервисом).
prediag, postdiag — управление пред-/пост-диагностикой (в формате {"enable": true, "options": {...}}).

Развёртывание и настройка через параметры команд

Если playfile отсутствует, параметры можно передавать непосредственно через аргументы командной строки в виде --имя=значение:

$ alteratorctl services <команда> <сервис> --param=value --obj.field=value --arr.0.field=value

Правила синтаксиса: Вложенные параметры задаются через точку: --network.address=10.0.0.1.
Массивы индексируются числами: --users.0.name=alice, --users.1.name=bob.
Логический тип: только true или false.
Какие параметры обязательны и каких типов они бывают — зависит от сервиса; смотреть через alteratorctl services info <сервис>.

Пример:

$ alteratorctl services configure chrony_service --disableDefaultPoll=true
$ alteratorctl services configure chrony_service --ntpServersSettings.0.serverDomainName=time.example.org --ntpServersSettings.0.bursts=iburst

Если стандартный ввод не является TTY, для команд с подтверждением используйте -y/--yes.

Модуль components

Components — модуль alteratorctl для управления компонентами (наборами пакетов): просмотр списка компонентов, получение информации и статуса, установка и удаление компонентов.

Начало работы

Вывести дерево компонентов:

$ alteratorctl components
Обозначения:
  [*] Установлен(а)
  [ ] Не установлен(а)
  [~] Частично установлен(а)
  [?] Черновой элемент (--draft) или неизвестный статус установки

Проверить статус конкретного компонента:

$ alteratorctl components status alterator-base
Компонент: Альтератор - базовое управление системой
Категория: Альтератор
Статус: установлен
Список пакетов, входящих в компонент:
[*] alt-components-base
[*] alterator-backend-edition
[*] alteratorctl

Обозначения

Маркеры статуса установки компонента:
[*] — установлен(а).
[ ] — не установлен(а).
[~] — частично установлен(а).
[?] — черновой элемент (--draft) или неизвестный статус установки.

Основные команды

Команда указывается после имени модуля, если команду не указать, выводится дерево компонентов.
(без команды) — вывести дерево компонентов (поведение по умолчанию для alteratorctl components).
list — вывести список компонентов (команда по умолчанию для components list).
info <компонент> — вывести данные компонента в формате alterator entry (удобно для анализа схемы/состава).
description <компонент> — вывести описание компонента.
status <компонент> — вывести статус установки компонента и входящие пакеты.
search <строка> — найти компонент по имени или пути на D-Bus.
install <компонент> — установить компонент.
remove <компонент> — удалить компонент.

Формат вывода

Чаще всего используются аргументы форматирования components list:
-g / --graphic-tree — вывести дерево с псевдографикой (по умолчанию).
-t / --simple-tree — вывести упрощённое дерево.
-l / --list — вывести список компонентов (для отображаемых имён в этом режиме используется -e/--enable-display-name).
-i / --installed — только установленные компоненты.
-u / --not-installed — только неустановленные компоненты.
-c / --category <категория> — вывести компоненты выбранной категории.
--draft — показывать черновые компоненты.
-L / --ignore-legend — скрыть легенду обозначений.
-H / --hide-installation-markers — скрыть маркеры статуса установки.

Полный список опций форматирования и фильтрации включает опции, перечисленные выше, а также:
-v / --verbose — добавить вывод путей объектов на D-Bus.
-d / --display-name-only — показать только отображаемые имена компонентов и категорий.
-D / --no-display-name — скрыть отображаемые имена компонентов и категорий.
-e / --enable-display-name — показывать отображаемые имена при выводе в виде списка (components list -l).
-p / --path-only — показать только пути объектов на D-Bus.
-n / --name-only — показать только имена компонентов.
-N / --no-name — скрыть имена компонентов и категорий.
-s / --sections <section1> [<section2> ...] — отобразить только выбранные разделы текущей редакции.
-I / --ignore-sections — вывести все компоненты, игнорируя секции текущей редакции.
-o / --show-other — отобразить компоненты, не входящие ни в один раздел текущей редакции.

Установка и удаление компонентов

Операции install и remove изменяют пакетный состав системы и обычно требуют прав администратора.

--force-yes — автоматическое подтверждение установки/удаления (использовать с осторожностью).
--no-update — не обновлять списки пакетов перед установкой/удалением.

Опции, которые используются при удалении (потенциально опасны):
--allow-remove-manually — разрешить удаление зависимых пакетов, помеченных apt как установленные вручную.
-b / --allow-remove-base — разрешить удаление пакетов, входящих в базовые компоненты (при наличии установленной редакции).

Примечание: По умолчанию, утилита блокирует транзакции, которые неявно удаляют вручную установленные пакеты или пакеты, входящие в базовый набор компонентов (явно и по зависимостям).

Примеры

Найти компонент по имени:

$ alteratorctl components search docker

Найти компонент по пути объекта на D-Bus:

$ alteratorctl components search /org/altlinux/alterator/component_cgroup

Проверить статус установки компонента:

$ alteratorctl components status cgroup
Компонент: Инфраструктура Control groups
Категория: Контейнеризация
Статус: не установлен
Список пакетов, входящих в компонент:
[ ] cgroup

Установить компонент (интерактивно):

$ alteratorctl components install cgroup
Следующие компоненты будут установлены:
  cgroup
Следующие пакеты будут установлены:
  cgroup  libcgroup

Продолжить? [y/N] y
...
Завершено.

Удалить компонент (интерактивно):

$ alteratorctl components remove cgroup
Следующие компоненты будут удалены:
  cgroup
Следующие пакеты будут удалены:
  cgroup

Продолжить? [y/N] y
...
Завершено.

Повторить установку/удаление без обновления списков пакетов и без вопросов:

$ alteratorctl components install cgroup --force-yes --no-update
$ alteratorctl components remove cgroup --force-yes --no-update

Вывести список установленных компонентов (без легенды и маркеров):

$ alteratorctl components list -l -i -L -H

Модуль editions

Editions — модуль alteratorctl для работы с редакциями: просмотр доступных редакций и выбор текущей редакции.

Начало работы

Вывести список редакций:

$ alteratorctl editions

Показать текущую редакцию:

$ alteratorctl editions get

Выбрать редакцию:

$ alteratorctl editions set <редакция>

Основные команды

list — вывести список редакций (команда по умолчанию).
get — вывести имя текущей редакции.
set <редакция> — выбрать текущую редакцию (изменяет настройки).
description [<редакция>] — вывести описание указанной или текущей редакции.
info [<редакция>] — вывести информацию об указанной или текущей редакции.
license [<редакция>] — вывести лицензию указанной или текущей редакции.

Формат вывода

При выводе списка редакций слева может отображаться маркер * для текущей редакции. Чтобы скрыть маркер, используйте -H/--hide-installation-markers.

Опции форматирования вывода:
-v / --verbose — добавить вывод путей объектов на D-Bus.
-d / --display-name-only — показать только отображаемые имена.
-D / --no-display-name — скрыть отображаемые имена.
-p / --path-only — показать только пути объектов на D-Bus.
-n / --name-only — показать только имена редакций.
-N / --no-name — скрыть имена редакций.
-H / --hide-installation-markers — скрыть маркер текущей редакции.

Примеры

Посмотреть описание текущей редакции:

$ alteratorctl editions description

Посмотреть лицензию выбранной редакции:

$ alteratorctl editions license <редакция>

Модуль systeminfo

Systeminfo — модуль alteratorctl для получения системной информации: имя и ветка дистрибутива, версия ядра, сведения об аппаратном обеспечении и окружении рабочего стола.

Начало работы

Вывести краткую сводку:

$ alteratorctl systeminfo

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

$ alteratorctl systeminfo kernel
$ alteratorctl systeminfo cpu
$ alteratorctl systeminfo memory

Команды

name — имя операционной системы.
branch — ветка (например p11).
arch — архитектура.
hostname — имя хоста.
kernel — версия ядра операционной системы.
cpu — информация о ЦПУ.
gpu — информация о графическом процессоре.
memory — объём ОЗУ (в байтах).
drive — общий объём накопителя (в байтах).
monitor — сведения о мониторе.
motherboard — информация о материнской плате.
desktops — список установленных графических окружений.
locales — локали пользователей.

Примеры

Пример получения информации о ЦПУ:

$ alteratorctl systeminfo cpu
12th Gen Intel(R) Core(TM) i5-1235U (12) 1300Hz

Модуль packages

Packages — модуль alteratorctl для работы с пакетами и репозиториями. Модуль состоит из подмодулей apt, repo и rpm.

Синтаксис вызова:

$ alteratorctl packages <подмодуль> <команда> [аргументы] [опции]

Команды, которые изменяют систему (apt install/remove/reinstall, repo add/remove, rpm install/remove) требуют прав администратора.

Начало работы

Обновить информацию о пакетах:

$ alteratorctl packages apt update

Найти пакет(ы) по имени:

$ alteratorctl packages apt search docker-engine
docker-engine
docker-engine-rootless

Установить пакет:

$ alteratorctl packages apt install <пакет>

Проверить, что пакет установлен, и посмотреть сведения о нём:

$ alteratorctl packages rpm packageinfo <пакет>

Проверить список репозиториев:

$ alteratorctl packages repo list
rpm [alt] http://ftp.altlinux.org/pub/distributions/ALTLinux Sisyphus/noarch classic
rpm [alt] http://ftp.altlinux.org/pub/distributions/ALTLinux Sisyphus/x86_64 classic
rpm [alt] http://ftp.altlinux.org/pub/distributions/ALTLinux Sisyphus/x86_64-i586 classic

Подмодуль apt

Подмодуль apt используется для работы с APT: обновление информации о пакетах, поиск, установка и удаление.

Команды

info — вывести информацию о подмодуле в формате alterator entry.
update — обновить информацию о пакетах (аналог apt-get update).
last-update — вывести время последнего обновления пакетной базы.
search <имя> — вывести результат поиска по имени/шаблону.
list — вывести список доступных пакетов (обычно большой).
install <имя> — установить указанный пакет.
remove <имя> — удалить указанный пакет.
reinstall <имя> — переустановить указанный пакет.

Опции

--force-yes — автоматическое подтверждение установки/удаления (использовать с осторожностью).
--allow-remove-manually — разрешить удаление пакетов, помеченных apt как установленные вручную.

Примеры

Обновить информацию о пакетах:

$ alteratorctl packages apt update

Проверить время последнего обновления информации о пакетах:

$ alteratorctl packages apt last-update
2026-01-27 10:29:19 UTC

Для поиска по имени используйте search:

$ alteratorctl packages apt search chrony

Установить и удалить пакет (с подтверждением):

$ alteratorctl packages apt install <пакет>
$ alteratorctl packages apt remove <пакет>

Подмодуль repo

Подмодуль repo предназначен для просмотра и изменения списка репозиториев (sources.list), с которыми работает APT.

Команды

info — вывести информацию о подмодуле в формате alterator entry.
list — вывести список репозиториев из sources.list.
add <имя> — добавить репозиторий в sources.list (изменяет настройки).
remove <имя> — удалить репозиторий из sources.list (изменяет настройки).

Примеры

Обновление информации о пакетах после добавления или удаления репозиториев:

$ alteratorctl packages repo add <репозиторий>
$ alteratorctl packages apt update
$ alteratorctl packages repo remove <репозиторий>
$ alteratorctl packages apt update

Подмодуль rpm

Подмодуль rpm предназначен для просмотра установленных пакетов и выполнения операций на уровне rpm.

Команды

info — вывести информацию о подмодуле в формате alterator entry.
list — вывести список установленных пакетов.
packageinfo <имя> — вывести информацию об указанном пакете.
files <имя> — вывести файлы выбранного пакета.
install <путь> — установить пакет из rpm-файла.
remove <имя> — удалить указанный пакет.

Примеры

Показать первые строки списка установленных пакетов:

$ alteratorctl packages rpm list

Посмотреть сведения и файлы пакета:

$ alteratorctl packages rpm packageinfo alteratorctl
$ alteratorctl packages rpm files alteratorctl

Установить пакет из rpm-файла:

$ alteratorctl packages rpm install /path/to/pkg.rpm

Модуль diag

Diag — модуль alteratorctl для запуска диагностических инструментов и тестов, а также формирования отчётов.

Начало работы

Вывести список доступных диагностических инструментов:

$ alteratorctl diag list

Вывести список тестов выбранного инструмента:

$ alteratorctl diag list diag_domain_client

Запустить все тесты выбранного инструмента:

$ alteratorctl diag run diag_domain_client

Основные команды

list — вывести список диагностических инструментов или тестов выбранного инструмента (команда по умолчанию).
info <путь | имя> — вывести информацию о диагностическом инструменте в формате alterator entry (включая список тестов).
run <путь | имя> [<тест>] — запустить один тест или все тесты выбранного инструмента.
report <путь | имя> <файл> — сохранить отчёт в файл (расширение выбирается инструментом).

Опции

По умолчанию используется системная шина. Для выбора сессионной шины используйте --session.
-v / --verbose — добавить пути объектов на D-Bus к выводу списка инструментов, а также включить подробный вывод для run.
-d / --display-name-only — показывать только отображаемые имена.
-D / --no-display-name — скрыть отображаемые имена.
-p / --path-only — показывать только пути объектов на D-Bus.
-n / --name-only — показывать только имена инструментов и тестов.
-N / --no-name — скрыть имена инструментов и тестов.

Примеры

Список доступных инструментов (в том числе в машинно-удобном виде):

$ alteratorctl diag list
$ alteratorctl diag list -n
$ alteratorctl diag list -v

Посмотреть состав инструмента и список тестов:

$ alteratorctl diag info diag_domain_client
$ alteratorctl diag list diag_domain_client

Запустить один тест:

$ alteratorctl diag run diag_domain_client check_system_policy

Запустить все тесты инструмента:

$ alteratorctl diag run diag_domain_client

Сохранить отчёт:

$ alteratorctl diag report diag_domain_client diag_domain_client_report
$ alteratorctl diag report domain_controller domain_controller_report

Модуль manager

Manager — модуль alteratorctl для просмотра объектов, интерфейсов и сигналов на D-Bus.

Начало работы

Вывести пути объектов для известного интерфейса:

$ alteratorctl manager getobjects org.altlinux.alterator.service1

Проверить, какие интерфейсы доступны у объекта по пути:

$ alteratorctl manager getifaces /org/altlinux/alterator/systeminfo

Команды

getobjects <интерфейс> — вывести пути объектов, реализующих указанный интерфейс.
getifaces [<путь>] — вывести интерфейсы, доступные у объекта по указанному пути.
getsignals <путь> <интерфейс> <имя метода> — вывести сигналы указанного метода интерфейса указанного объекта.
По умолчанию модуль работает с системной шиной D-Bus. Для обращения к сессионной шине используйте опцию --session.

Примеры

Вывести список объектов сервисов и компонентов:

$ alteratorctl manager getobjects org.altlinux.alterator.service1
$ alteratorctl manager getobjects org.altlinux.alterator.component1

Объекты модуля systeminfo:

$ alteratorctl manager getobjects org.altlinux.alterator.systeminfo1

Разработчикам

Раздел предназначен для разработчиков и описывает внутреннее устройство alteratorctl.

Внутреннее устройство alteratorctl

Опишем типовой внутренний модуль alteratorctl и его архитектуру.

Внутренний клиентский модуль — объект класса, реализующего интерфейс AlteratorCtlModuleInterface по принципу, принятому в GLib для объектно-ориентированного программирования.

Интерфейс AlteratorCtlModuleInterface предполагает, что в модуле должны быть реализованы 3 метода:

run_with_args — запуск модуля с параметрами командной строки;
run — запуск модуля с контекстом;
print_help — вывод справки об использовании модуля.

Регистрация модуля

Модуль в alteratorctl необходимо зарегистрировать перед его использованием. Регистрация модуля осуществляется вызовом метода alterator_ctl_register_module() у объекта app типа AlteratorCtlApp в функции main.

В функцию передается указатель на объект типа AlteratorCtlApp, где происходит регистрация, и на структуру типа alterator_ctl_module_t, в которой есть указатели на конструкторы, деструкторы и id модуля.

Id модуля

Id модуля представляет собой указатель на строку, содержащую имя модуля. Именно по имени модуля alteratorctl понимает, какой модуль запустить. Модуль указывается первым после общих ключей alteratorctl в командной строке.

Например:

$ alteratorctl -v manager help

где:

-v — общий для модулей параметр;
manager — имя (id) запускаемого модуля;
help — подкоманда для модуля manager.

Конструктор модуля

Конструктор модуля — функция, возвращающая указатель на AlteratorCtlComponentsModule. Конструктор модуля принимает в виде параметров:

указатель на AlteratorCtlApp, в котором зарегистрирован модуль;
указатель на структуру типа alteratorctl_arguments_t, которая содержит общие для всех модулей параметры.

Деструктор

Деструктор — функция в структуре alterator_ctl_module_t. Принимает указатель на экземпляр класса внутреннего модуля, ресурсы которого будут освобождены.

Создание контекста модуля

Метод run_with_args
Этот метод запускает модуль, передавая ему параметры командной строки. Обычно в этом методе происходит парсинг аргументов командной строки, создается контекст модуля. И этот контекст передается в метод run.
Метод run
Метод run принимает контекст модуля и непосредственно выполняет необходимые запросы на D-Bus. Модуль должен быть выполнен таким образом, чтобы его можно было вызвать из другого модуля при инициализации контекста модуля. После выполнения метода run, контекст необходимо освободить специализированной функцией.
Метод print _help
Выводит в stdout описание команд и параметров командной строки модуля.