ADT

ALT Diagnostic Tool (ADT) — представляет собой инструмент для запуска тестов в терминале или в графическом интерфейсе.

Цель создания

Цель создания ADT — упрощение проведения диагностики и анализа работы системы. Работа ADT по поиску доступных тестов, их запуску и получению результатов работы теста осуществляется через D-Bus с использованием Alterator Manager и его модуля Executor. Благодаря подобной схеме реализации утилита диагностики системы получает доступ к интерфейсу взаимодействия на шине D-Bus. С использованием Alterator Manager и D-Bus возвращается информация о результатах выполнения теста.

Назначение

Утилита ADT позволяет:

• проводить диагностику системы посредством набора подготовленных утилит;
• выводить на экран результаты диагностики;
• сохранять файл журнала с результатами диагностики;
• выполнять операции, требующие привилегий, от учетной записи непривилигированного пользователя.

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

• системных администраторов;
• опытных пользователей;
• службы технической поддержки.

Возможности программы позволяют проводить диагностику системы в графическом приложении и записать файл с отчетом. Запуск инструментов диагностики регулируется системным администратором, позволяя создавать отчеты пользователям, не передавая им административные полномочия.

Установка

Для работы с ADT необходимо установить:

• ADT (пакет adt);
• диагностические инструменты (например, пакеты diag-domain-client, diag-domain-controller).

Установка ADT:

# apt-get install adt

Примечание: Вместе с adt устанавливаются:

• alterator-manager;
• alterator-module-executor;
• alterator-interface-diag.

Установка инструментов диагностики состояния клиента домена и состояния контроллера домена:

# apt-get install diag-domain-client diag-domain-controller

Запуск

Запуск службы alterator-manager

Запустить и добавить в автозагрузку службу alterator-manager:

# systemctl enable --now alterator-manager.service

Запуск ADT

Запустить ADT можно:

• из командной строки:

  $ adt
  

• в рабочей среде Mate: Меню → «Системные»→ «ADT»;
• в рабочей среде KDE5: «Меню запуска приложений»→ «Настройки»→ «ADT».

Интерфейс

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

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

Пользовательский интерфейс программы состоит из секций:

• Список инструментов диагностики.
• Описание инструмента.
• Действия пользователя.

Работа с ADT

Для работы с инструментом диагностики его необходимо выбрать в списке:

Двойной щелчок мыши либо кнопка «Выбрать инструмент» перемещают пользователя к работе с набором тестов инструмента:

В области управления инструментом диагностики доступны опции: «Отчет», «Запустить все тесты», «Назад». Напротив каждого теста находятся кнопки «Запустить» и «Журнал».

Нажатие на кнопку «Запустить все тесты» запускает весь набор тестов выбранного инструмента:

Для того чтобы запустить отдельный тест, необходимо нажать кнопку «Запустить», расположенную справа от названия теста:

Кнопка «Журнал» выводит отчет теста от утилиты инструмента диагностики (если инструмент поддерживает такую возможность):

Для поиска конкретного теста среди доступных можно воспользоваться строкой «Фильтр»:

Кнопка «Отчет» сохраняет в файл полный текст информации инструмента диагностики (если инструмент поддерживает такую возможность).

Примечание: Для возможности генерирования файла с отчетом, инструмент диагностики должен поддерживать опции -r, --report.

Руководство администратора

Спецификация

• Документация относится к Alterator Manager, компоненту Alterator на D-Bus.
• Код проекта

Компоненты

• Alterator Manager
• executor

Alterator-manager — модульный сервис, предназначенный для конфигурации посредством D-Bus. Весь функционал реализуется в виде модулей, а интерфейсы описываются в конфигурационных файлах «alterator entry».

Система межпроцессного взаимодействия D-Bus — механизм для обмена сообщениями между различными программами в операционной системе. D-Bus позволяет программам отправлять сообщения и вызывать методы других программ, обеспечивая совместную работу и координацию между приложениями. D-Bus представляет из себя совокупность следующих шин:

• Системная шина — создаётся при старте демона D-Bus. Предназначена для взаимодействия между различными системными службами, а также взаимодействие пользовательских приложений с этими службами;
• Сессионная шина — создаётся для каждого пользователя во время авторизации как отдельный экземпляр. Предназначена для взаимодействия между пользовательскими приложениями в рамках одной сессии.

На шинах D-Bus регистрируются службы, предоставляющие определенные функции. Они могут быть как частью операционной системы, так и сторонними приложениями.

Для каждой службы заводятся объекты, представляющие собой абстракции реальных ресурсов или служб.

У каждого объекта есть один или несколько интерфейсов, которые определяют, какие действия можно совершить с объектом. Интерфейсы описывают методы (функции), которые можно вызвать, свойства, которые можно запросить или изменить, и сигналы, которые объект может отправлять.

Объекты, создаваемые службами. Каждая служба может создавать объекты, которые представляют собой абстракции реальных ресурсов или служб. Например, служба сетевого менеджера может предоставлять объекты для каждого сетевого соединения.

Интерфейсы объектов. У каждого объекта есть один или несколько интерфейсов, которые определяют, какие действия можно совершить с объектом. Интерфейсы описывают методы (функции), которые можно вызвать, свойства, которые можно запросить или изменить, и сигналы, которые объект может отправлять.

Каждая служба поддерживающая D-Bus представлена в виде объектов на этих шинах. А взаимодействие между ними осуществляется посредством интерфейсов и методов этих объектов.

На системной шине методы запускаются с правами root и имеют высокие привилегии. На сессионной шине методы запускаются с правами пользователя и не имеют доступа к системным ресурсам, которые требуют высоких привилегий. С точки зрения alterator-manager диагностический инструмент является объектом на D-Bus, описанном в двух файлах «alterator entry»:

• .backend — описывает интерфейс диагностического инструмента, обеспечивающий взаимодействие с D-Bus. В нем же описываются методы интерфейса: info, run, list, report;
• .diagnostictool — описывает отображение диагностического инструмента в ADT. Содержит информацию о тестах, доступных в рамках описываемого диагностического инструмента.

alterator-module-executor — модуль альтератора для обработки файлов .backend и запуска исполняемых файлов.

Алгоритм работы

Алгоритм работы ALT Diagnostic Tool:

1. Systemd служба alterator-manager во время запуска создает на шине D-Bus службу с именем «ru.basealt.alterator».
2. Systemd служба alterator-module-executor собирает информацию из файлов .backend обо всех установленных диагностических инструментах и создает объекты на системной и сессионных (в зависимости от расположения backend-файлов) шинах D-Bus с именами вида «ru.basealt.alterator.<имя инструмента>».
3. ADT формирует список диагностических инструментов, обращаясь к D-Bus и получая информацию обо всех объектах сервиса «ru.basealt.alterator», имеющих интерфейс «ru.basealt.alterator.diag1».
4. Для каждого диагностического инструмента ADT вызывает на D-Bus метод List, чтобы получить список всех возможных тестов.
5. ADT запускает через D-Bus метод Run, передав ему в качестве параметра имя теста.
6. По коду возврата ADT получает информацию об успешном/не успешном прохождении теста, а из данных, полученных из stderr и stdout формирует журнал выполнения теста.

Блок-схема взаимодействия компонентов:

Разработка инструмента диагностики

Формат файлов инструмента диагностики

Минимальный набор файлов для инструмента диагностики в ADT:

• исполняемый файл;
• файлы .backend и .diagnostictool (или .diag), описывающие сущности Alterator Entry.

Примечание: Оба варианта .diag и .diagnostictool считаются верными.

Требования к исполняемому файлу

Исполняемый файл может быть как бинарным, так и текстовым (написанным на интерпретируемом языке). Файл должен поддерживать запуск в следующем виде:

/путь_к_исполняемому_файлу {param}

где {param} — означает имя теста, который необходимо выполнить.

При успешном завершении теста исполняемый файл должен завершиться с кодом возврата 0. При не успешном завершении теста — с кодом возврата отличным от 0.

Лог выполнения нужно выводить в стандартный вывод.

Необходима также поддержка следующих ключей:

• -l или --list — вывести список тестов. Список необходимо выводить в стандартный вывод. Имя каждого теста с новой строки;
• -r или --report — сгенерировать файл с отчетом. Файл с отчетом может представлять собой как текстовые данные, так и бинарные (например, архив). Его содержимое необходимо направить в стандартный вывод. ADT получит этот вывод и сохранит в файл с именем вида «имя_инструмента_дата» и суффиксом, указанным в файле .diagnostictool.

Исполняемый файл рекомендуется разместить в каталоге согласно стандарту FHS (Filesystem Hierarchy Standard).

Рекомендации к файлам .backend и .diagnostictool

Для описания файлов .backend и .diagnostictool следует воспользоваться спецификацией Alterator Entry.

Файлы .backend и .diagnostictool являются текстовыми и содержат описание в виде секций. Имеют следующий синтаксис:

[имя секции1]
Поле1 = значение
Поле2 = значение
ПолеN = значение
[имя секции2]
Поле1 = значение
Поле2 = значение
ПолеN = значение
[имя секцииN]
Поле1 = значение
Поле2 = значение
ПолеN = значение

Где:

• все поля чувствительны к регистру и должны начинаться с заглавной буквы;
• перед и после знака «=» пробелы;
• значения полей указываются без кавычек;
• значения могут содержать пробелы;
• если строка начинается с «#», то она считается комментарием и при чтении информации из файла игнорируется.

Имя каталога должно соответствовать суффиксу в имени файла:

• ./backends для файла .backend;
• ./diagnostictools для файла .diagnostictool (или .diag).

Файл .diagnostictool

Файл .diagnostictool имеет имя вида <имя диагностического инструмента>.diagnostictool.

Если разрабатываемый диагностический инструмент предполагается распространять, то файлы сущностей необходимо разместить в каталоге /usr/share/alterator/diagnostictools/. В противном случае, рекомендуется использовать каталог /etc/alterator/diagnostictools/.

Файл .diagnostictool содержит информацию для GUI. Он включает секцию [Alterator Entry] и секции, описывающие варианты тестирования.

Секция Alterator Entry:

• [Alterator Entry]
  • Name — идентификатор инструмента (имя без пробелов);
  • Type — всегда Diagnostictool;
  • DisplayName — имя инструмента;
  • DisplayName[локаль] — имя инструмента, выводящиеся в GUI, если используется интерфейс с использованием указанной в скобках локали;
  • Comment — описание инструмента;
  • Comment[локаль] — описание, выводящиеся в GUI, если используется интерфейс с использованием указанной в скобках локали;
  • Icon — имя файла с иконкой;
  • ReportSuffix — суффикс файла с отчетом. Этот файл будет создаваться при вызове метода Report.

Секции, описывающие варианты тестирования:

• [Название секции соответствует названию теста]
  • DisplayName — идентификатор теста (имя без пробелов);
  • DisplayName[локаль] — имя теста, выводящиеся в GUI, если используется интерфейс с использованием указанной в скобках локали;
  • Comment — описание теста;
  • Comment[локаль] — описание теста, выводящиеся в GUI, если используется интерфейс с использованием указанной в скобках локали.

Файл .backend

Файл .backend имеет имя вида <имя диагностического инструмента>.ru.basealt.alterator.backend.

Если разрабатываемый диагностический инструмент предполагается распространять, то файлы сущностей необходимо разместить в каталоге:

• /usr/share/alterator/backends/system — если объект необходимо создать на системной шине;
• /usr/share/alterator/backends/user — если объект необходимо создать на сессионной шине;

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

• /etc/alterator/backends/system/ — если объект необходимо создать на системной шине;
• /etc/alterator/backends/user/ — если объект необходимо создать на сессионной шине.

Секция Alterator Entry описывает информацию об объекте и содержит следующие поля:

• [Alterator Entry]
  • Type — содержит тип метода. Всегда имеет значение Backend;
  • Module — всегда executor;
  • Name — идентификатор инструмента (имя без пробелов);
  • Interface — идентификатор интерфейса. Имеет значение ru.basealt.alterator.diag1. Можно сократить до diag1;
  • thread_limit — указывает максимальное число потоков при одновременном выполнении нескольких методов.

Секция Info описывает метод Info и содержит следующие поля:

• [Info]
  • execute — в качестве параметра необходимо передать команду, выводящую содержимое файла .diagnostictool (cat <путь к файлу>);
  • stdout_bytes — всегда enabled;
  • thread_limit — всегда 3;
  • action_id — содержит идентификатор метода. Всегда имеет значение Info.

Секция Run описывает метод Run и содержит следующие поля:

• [Run]
  • execute — содержит строку для запуска тестов вида <путь к исполняемому файлу> {param} ;
  • stdout_signal_name — всегда diag1_stdout_signal. ADT ожидает сигнал с таким именем;
  • stderr_signal_name — всегда diag1_stderr_signal. ADT ожидает сигнал с таким именем;
  • action_id — содержит идентификатор метода. Всегда имеет значение Run.

Секция List описывает метод List и содержит следующие поля:

• [List]
  • execute — содержит команду для вывода списка всех возможных тестов в виде <путь к исполняемому файлу> -l;
  • stdout_strings — всегда enabled;
  • action_id — содержит идентификатор метода. Всегда имеет значение List.

Секция Report содержит следующие поля:

• [Report]
  • execute — содержит команду для создания отчета в виде <путь к исполняемому файлу> -R;
  • stdout_bytes — всегда enabled;
  • action_id — всегда Report.

Пример инструмента диагностики

Ниже представлен пример диагностического инструмента для определения производителя материнской платы.

Пример состоит из трех файлов:

• исполняемый файл: /usr/bin/diag-example;
• файл .backend: /usr/share/alterator/backends/diag-example.backend;
• файл .diag, описывающий тесты: /usr/share/alterator/diagnostictools/diag-example.diag.

Шаблон примера

Исполняемый файл

Содержимое исполняемого файла /usr/bin/diag-example:

Example diagnostic tool

#!/bin/bash
#
# Copyright (c) 2024 Evgeny Sinelnikov <sin@altlinux.org>
#
# Example diagnostic tool
#
# SPDX-License-Identifier: GPL-2.0-or-later
#

set -euo pipefail

. shell-getopt

PROG="${0##*/}"
PROG_VERSION='0.0.1'

cmd="run"
global_retval=0

print_version()
{
	cat <<EOF
$PROG version $PROG_VERSION
Written by Evgeny Sinelnikov <sin@altlinux.org>

Copyright (C) 2024 Evgeny Sinelnikov <sin@altlinux.org>
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
EOF
	exit
}

show_usage()
{
	cat <<EOF
$PROG - example diagnostic tool.

Usage: $PROG [options] [<diagnostic-task>]

Options:
  -l, --list                list of diagnostic tasks;
  -V, --version             print program version and exit;
  -h, --help                show this text and exit.

Report bugs to https://bugzilla.altlinux.org/

EOF
	exit
}

TEMP=$(getopt -n "$PROG" -o "l,V,h" -l "list,version,help" -- "$@") || show_usage
eval set -- "$TEMP"

while :; do
	case "$1" in
		--) shift; break
			;;
		-l|--list) cmd="list";
			;;
		-V|--version) print_version
			;;
		-h|--help) show_usage
			;;
		*) fatal "Unrecognized option: $1"
			;;
	esac
	shift
done

task_list="$*"

task_show()
{
	local func="$1"

	echo "$func"
}

task_run()
{
	local retval=126
	local func="$1"

	if test -n "$task_list"; then
		echo "$task_list" | tr ' ' '\n' | grep -q "^$func\$" ||
			return 0
	fi

	$func && retval=0 || retval="$?"
	test $retval = 0 || global_retval=1

	return $retval
}

task()
{
	local task="$1"

	case "$cmd" in
		list) task_show "$task"
			;;
		run) task_run "$task" && echo "[DONE]: $task" || echo "[FAIL]: $task"
			;;
		*) fatal "Unrecognized command: $cmd"
			;;
	esac
}

is_gigabyte()
{
	/usr/sbin/dmidecode -s baseboard-manufacturer | grep -q "^Gigabyte Technology"
}

is_std_def_kernel_running()
{
	uname -r | grep -q '^[[:digit:]]\+\.[[:digit:]]\+\.[[:digit:]]\+-std-def-'
}

task is_gigabyte
task is_std_def_kernel_running

exit "$global_retval"

Файл .backend

Содержимое файла /usr/share/alterator/backends/diag-example.backend:

[Alterator Entry]
Type = Backend
Module = executor
Name = diag_example
Interface = diag1

[Info]
execute = cat /usr/share/alterator/diagnostictools/diag-example.diag
stdout_bytes = enabled
stdout_byte_limit = 200000
action_id = Info

[Run]
execute = diag-example {param}
stdout_signal_name = diag_example_stdout_signal
stderr_signal_name = diag_example_stderr_signal
thread_limit = 1
action_id = Run

[List]
execute = diag-example -l
stdout_strings = enabled
stdout_strings_limit = 200000
action_id = List

Файл .diag, описывающий тесты

Содержимое файла /usr/share/alterator/diagnostictools/diag-example.diag:

[Alterator Entry]
Type = diag
Name = Example
DisplayName = Diagnostic tool example
DisplayName[ru] = Пример инструмента диагностики
Comment = Diagnostic tool comment
Comment[ru] = Комментарий к диагностическому инструменту
Icon = system-run

[is_gigabyte]
DisplayName = Is motherboard manufacturer — Gigabyte?
DisplayName[ru] = Производитель материнской платы — Gigabyte?

Отображение диагностического инструмента в интерфейсе ADT

Примечание: Для того чтобы новый диагностический инструмент отображался интерфейсе ADT, необходимо перезапустить alterator-manager:

# systemctl restart alterator-manager.service

Ошибки и нестандартные случаи

Диагностический инструмент не отображается

Необходимо проверить объект alterator-manager с именем «ru.basealt.alterator» на системной шине D-Bus.

Для этого можно использовать утилиту D-Feet (d-feet) или D-Spy (dspy).

В D-Feet и D-Spy можно посмотреть объекты заведенные как на системной шине, так и на сессионной шине для текущего пользователя.

D-Feet:

D-Spy:

Публикации на тему

• Тезисы XIX конференции разработчиков свободных программ 2023, Утилита диагностики системы ALT Diagnoctic Tool, Алексей Сапрунов
• Системный администратор, Linux-инструмент диагностики с графическим интерфейсом – ALT Diagnostic Tool, Aнтон Абрамов