VK Cloud logo

Диагностическая утилита hw-bundle-util

hw-bundle-util — Linux-утилита от VK Cloud для сбора диагностических данных сервера Bare Metal. Утилита собирает сведения об оборудовании и ОС в один архив, например для обращения в техническую поддержку.

Утилита запускается пользователем вручную в ОС. Поддерживаются следующие Linux-дистрибутивы (amd64 и arm64):

  • Ubuntu 18.04/20.04/22.04/24.04,
  • Debian 10/11/12,
  • CentOS 8, CentOS Stream 9,
  • AlmaLinux 8/9,
  • Rocky Linux 8/9,
  • РЕД ОС 7/8.

Часть диагностической информации доступна только с правами суперпользователя, поэтому hw-bundle-util рекомендуется запускать с помощью sudo или напрямую из учетной записи root.

Утилита не изменяет данные пользователя и настройки ОС. После запуска рядом с исполняемым файлом создается директория для сбора диагностической информации. По умолчанию после успешного выполнения hw-bundle-util и формирования отчета, все временные файлы удаляются. При необходимости можно задать собственные параметры запуска.

Собираемая информация

Для сбора информации о разных компонентах системы используются вспомогательные утилиты, доступные в большинстве Linux-дистрибутивов, а также считывается системная информация из виртуальной файловой системы procfs.

hw-bundle-util использует следующие источники:

  • Характеристики платформы сервера Bare Metal (материнская плата, процессор, память, версия BIOS/UEFI): dmidecode.
  • Параметры ОС и системные показатели: hostname, hostnamectl, lscpu, /proc/cpuinfo, uname, /etc/os-release, /proc/uptime, /proc/loadavg.
  • Состояние оперативной памяти: free -h, /proc/meminfo.
  • Параметры файловой системы и накопителей: lsblk, blkid, /sys/block, /proc/partitions.
  • Показатели SMART: расширенный вывод smartctl по каждому найденному устройству.
  • Ошибки в работе оборудования из подсистемы EDAC: /sys/devices/system/edac, ras-mc-ctl, edac-util, /var/log/mcelog, записи rasdaemon и журнала ядра (dmesg).
  • Журнал ядра dmesg -T за последние 24 часа, journalctl --dmesg и последние записи /var/log/kern.log.
  • Состояние сети: параметры сетевых интерфейсов через ethtool, конфигурация DNS и проверка разрешения имен vk.ru и cloud.vk.ru (dig), проверка связности (ping) до шлюза, адресов vk.ru и cloud.vk.ru, а также до публичных DNS-серверов: 8.8.8.8, 8.8.4.4, 77.88.8.8, 77.88.8.88.
  • Текущее время и параметры системного времени: date, timedatectl.
  • Системные файлы: копии /proc/cmdline, /proc/uptime, /proc/cpuinfo, /proc/meminfo, /proc/sys/kernel/tainted, /etc/os-release, последние 10000 байтов /var/log/syslog или /var/log/messages.

Проверка скорости сети не выполняется.

Содержание отчета

По окончании работы утилиты рядом с исполняемым файлом создается архив bmaas-bundle.tar.gz со следующей структурой:

bmaas-bundle.tar.gz├── log.log└── bundle/    ├── hw-bundle-util.version    ├── sanitize.legend    ├── collect/    ├── exec/    │   └── <ПРОВЕРКА>/    │       ├── <ИМЯ_УТИЛИТЫ>[.<УТОЧНЕНИЕ>].stdout    │       ├── <ИМЯ_УТИЛИТЫ>[.<УТОЧНЕНИЕ>].stderr    │       ├── <ИМЯ_УТИЛИТЫ>.version    │       └── legend    └── collection.incomplete

Здесь:

  • log.log: журнал работы hw-bundle-util.

  • bundle/hw-bundle-util.version: версия hw-bundle-util, с помощью которой собран отчет.

  • bundle/sanitize.legend: перечень значений, которые были заменены в параметрах загрузки ядра перед упаковкой отчета.

  • bundle/collect/: файлы ОС, скопированные из системы. Копия /proc/cmdline предварительно очищается от секретов.

  • bundle/exec/<ПРОВЕРКА>/: результаты вызова вспомогательных утилит. Для каждой проверки создается отдельная директория, в которой находятся:

    • <ИМЯ_УТИЛИТЫ>[.<УТОЧНЕНИЕ>].stdout и <ИМЯ_УТИЛИТЫ>[.<УТОЧНЕНИЕ>].stderr: файлы с записью вывода из стандартного потока stdout, а также из стандартного потока ошибок stderr. Если в процессе работы впомогательной утилиты не было диагностических и отладочных сообщений, файл stderr будет отсутствовать.

      Здесь <УТОЧНЕНИЕ> — дополнительная информация о проверке. Например, для ethtool будет уточнено имя интерфейса ethtool.eth0.

    • <ИМЯ_УТИЛИТЫ>.version: версия вспомогательной утилиты.

    • legend: сводка о запуске вспомогательной утилиты — аргументы и причины отсутствия результатов.

  • bundle/collection.incomplete: перечень проверок, которые не удалось выполнить, и причины. Файл создается, только если данные собраны не полностью, например из-за отсутствия нужной вспомогательной утилиты в системе или запуска без прав root.

Перед созданием отчета очищаются учетные данные, фигурирующие в параметрах загрузки ядра. Удаление выполняется по известным паттернам хранения чувствительной информации, а также по ключевым словам password, passwd, token, secret, credential, apikey, api_key, accesskey, access_key. На месте удаленного значения остается запись вида secret:S0:secret-key:len=<КОЛИЧЕСТВО_СИМВОЛОВ>:fp=<ОТПЕЧАТОК>, остальная часть строки не изменяется. Здесь <ОТПЕЧАТОК> — последовательность символов, одинаковая для одного и того же секрета. Так можно узнать, где и какой секрет используется, не раскрывая его содержимое. Если повторно запустить утилиту, то в новом архиве записи тех же секретов изменятся. Это происходит потому, что отпечаток создается заново при каждом запуске.

Очистка применяется к файлу collect/cmdline, а также к выводу exec/kernel/dmesg.stdout и journalctl.stdout. Остальное содержимое включается в архив без изменений: вывод вспомогательных утилит, копии файлов из /proc, /sys и /etc, журнал работы самой утилиты. Из /var/log/syslog или /var/log/messages и /var/log/kern.log в архив попадают только последние записи, а не файл целиком.

Команды и параметры запуска

Формат запуска:

./hw-bundle-util [КОМАНДА] [ПАРАМЕТРЫ]

Команды

Команда

Назначение

collect

Сбор диагностических данных. Используется по умолчанию, если команда не указана

version

Вывод версии утилиты

Параметры

Параметр

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

Назначение

Справка

--help

—

Вывод справки. ./hw-bundle-util --help — справка по утилите, ./hw-bundle-util collect --help — справка по параметрам сбора

Параметры рабочей директории и журналирования команды collect

--working-dir

./bmaas-bundle

Рабочая директория. Архив создается рядом с ней и называется так же, но с расширением .tar.gz. Если директория уже существует, то при запуске утилиты ее содержание будет перезаписано

--console-log-level

info

Подробность вывода в терминал. Допустимые значения: debug, info, warn, error

--file-log-level

debug

Подробность записи в файл log.log внутри архива. Допустимые значения: debug, info, warn, error

--no-cleanup

Не используется

Не удалять собранное дерево каталогов после создания архива. По умолчанию оно удаляется, так как архив уже содержит те же данные

Параметры отправки архива команды collect

--upload-url

—

URL-адрес, по которому нужно отправить архив. Если параметр не указан, архив сохраняется только на диске рядом с исполняемым файлом или в директории, заданной параметром --working-dir

--upload-method

S3

Способ отправки. Допустимые значения: S3, PUT, POST. При другом значении утилита завершается с кодом возврата 3. Используется вместе с --upload-url. При отсутствии --upload-url параметр --upload-method игнорируется

--upload-timeout

10m

Ограничение времени на отправку

--additional-headers

—

Дополнительный HTTP-заголовок в формате 'ключ: значение'. Параметр можно указать несколько раз

--skip-ssl

Не используется

Не проверять сертификат сервера. Используется в окружениях с самоподписанным сертификатом

Коды возврата

Код

Значение

0

Успех: отчет собран полностью

1

Непредвиденная ошибка

3

Ошибка в аргументах командной строки

4

Передана неизвестная команда

6

Не удалось создать архив

7, 14

Не удалось создать директорию

8

Не удалось создать файл

9

Не удалось записать файл

10

Не удалось отправить архив

11, 12

Не удалось определить рабочую директорию

13

Не удалось удалить директорию

100

Отчет собран и доставлен, но часть проверок не дала данных. Подробнее в файле collection.incomplete

130

Прервано по SIGINT (CTRL+C)

143

Прервано по SIGTERM

Была ли статья полезна?