ADT

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

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

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

Назначение

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

1. Cистемных администраторов.
2. Опытных пользователей.
3. Cлужбы технической поддержки.

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

Установка

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

# apt-get update
# apt-get install adt

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

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

Запуск

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

# systemctl start alterator-manager.service
# systemctl enable alterator-manager.service

Запуск ADT

Вызов утилиты ADT возможен через графическое меню либо через терминал.

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

Интерфейс

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

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

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

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

Компоненты

• Alterator Manager
• executor

Руководство пользователя

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

Двойной щелчок мыши либо кнопка "Выбрать инструмент" перемещают пользователя к работе с набором тестов инструмента. Кнопка "Запустить все" автоматически запускает весь набор тестов выбранного инструмента.

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

Пример выполнения всех тестов:

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

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

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

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

1. Systemd служба alterator-manager во время запуска создает на шине D-Bus службу с именем "ru.basealt.alterator";
2. Systemd служба alterator-module-executor собирает информацию из файлов .backend обо всех установленных диагностических инструментах и создает объекты на D-Bus;
3. ADT формирует список диагностических инструментов, обращаясь к D-Bus службе "ru.basealt.alterator";
4. Таким же способом ADT запускает тест и получает информацию о результате его выполнения.

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

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

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

• исполняемый файл
• файл .backend
• файл .diagnostic

.backend и .diagnostic описывают сущности Alterator Entry

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

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

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

{param} - означает имя теста, который необходимо выполнить. При успешном завершении теста исполняемый файл должен завершиться с кодом возврата 0. При не успешном завершении теста - с кодом возврата отличным от 0. Лог выполнения нужно выводить в стандартный вывод.

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

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

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

1. Исполняемый файл рекомендуется разместить в каталоге согласно стандарту FHS (Filesystem Hierarchy Standard)
2. Для описания файлов .backend и .diagnostictool следует воспользоваться спецификацией Alterator Entry.

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

• ./backends для файла .backend
• ./diagnostictools для файла .diagnostictool

.diagnostictool

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

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

/usr/share/alterator/diagnostictool/

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

/etc/alterator/diagnostictool/

Файл .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

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

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

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

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

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

/etc/alterator/backends/system/  - если объект необходимо создать на системной шине

/etc/alterator/backends/user/  - если объект необходимо создать на сессионной шине

• [Alterator Entry] - описывает информацию об объекте и содержит следующие поля:
  • Type - содержит тип метода. Всегда имеет значение Backend
  • Module - всегда executor
  • Name - идентификатор инструмента (имя без пробелов)
  • Interface - идентификатор интерфейса. Имеет значение ru.basealt.alterator.diag1. Можно сократить до diag1
  • thread_limit - Указывает максимальное число потоков при одновременном выполнении нескольких методов.
• [Info] описывает метод Info и содержит следующие поля:
  • execute - в качестве параметра необходимо передать команду, выводящую содержимое файла .diagnostictool (cat <путь к файлу>)
  • stdout_bytes - всегда enabled?
  • thread_limit - всегда 3?
  • action_id - содержит идентификатор метода. Всегда имеет значение Info
• [Run] описывает метод Run и содержит следующие поля:
  • execute - содержит строку для запуска тестов вида <путь к исполняемому файлу> {param}
  • stdout_signal_name - всегда diag1_stdout_signal. ADT ожидает сигнал с таким именем.
  • stderr_signal_name - всегда diag1_stderr_signal. ADT ожидает сигнал с таким именем.
  • action_id - содержит идентификатор метода. Всегда имеет значение Run
• [List] описывает метод List и содержит следующие поля:
  • execute - содержит команду для вывода списка всех возможных тестов в виде <путь к исполняемому файлу> -l
  • stdout_strings - всегда enabled
  • action_id - содержит идентификатор метода. Всегда имеет значение List
• [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/diag/diag-example.diag

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

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

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

[Info]
execute = cat /usr/share/alterator/diag/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, описывающий тесты

[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

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

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

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

Необходимо проверить объект alterator-manager с именем “ru.basealt.alterator” на системной шине D-Bus. Используйте утилиту D-Feet:

# apt-get update
# apt-get install d-feet

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

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

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