hw-bundle-util diagnostic utility
hw-bundle-util is a Linux utility from VK Cloud for collecting diagnostic data from a Bare Metal server. The utility gathers information about the hardware and the OS into a single archive, for example, to attach to a request to technical support.
The utility is run manually by the user in the OS. The following Linux distributions (amd64 and arm64) are supported:
- 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,
- RED OS 7/8.
Some diagnostic information is available only with superuser privileges, so it is recommended to run hw-bundle-util using sudo or directly from the root account.
The utility does not modify user data or OS settings. After the launch, a directory for collecting diagnostic information is created next to the executable file. By default, after hw-bundle-util completes successfully and the report is generated, all temporary files are deleted. If necessary, you can set custom launch parameters.
To collect information about various system components, auxiliary utilities available in most Linux distributions are used. System information is also read from the procfs virtual file system.
hw-bundle-util uses the following sources:
- Bare Metal server platform characteristics (motherboard, processor, memory, BIOS/UEFI version):
dmidecode. - OS parameters and system metrics:
hostname,hostnamectl,lscpu,/proc/cpuinfo,uname,/etc/os-release,/proc/uptime,/proc/loadavg. - RAM state:
free -h,/proc/meminfo. - File system and storage device parameters:
lsblk,blkid,/sys/block,/proc/partitions. - SMART metrics: extended
smartctloutput for each detected device. - Hardware errors from the EDAC subsystem:
/sys/devices/system/edac,ras-mc-ctl,edac-util,/var/log/mcelog,rasdaemonrecords, and the kernel log (dmesg). - Kernel log
dmesg -Tfor the last 24 hours,journalctl --dmesg, and the latest entries of/var/log/kern.log. - Network state: network interface parameters via
ethtool, DNS configuration and name resolution check forvk.ruandcloud.vk.ru(dig), connectivity check (ping) to the gateway, the addresses ofvk.ruandcloud.vk.ru, and the public DNS servers8.8.8.8,8.8.4.4,77.88.8.8,77.88.8.88. - Current time and system time parameters:
date,timedatectl. - System files: copies of
/proc/cmdline,/proc/uptime,/proc/cpuinfo,/proc/meminfo,/proc/sys/kernel/tainted,/etc/os-release, and the last 10000 bytes of/var/log/syslogor/var/log/messages.
Network speed is not tested.
When the utility finishes, the bmaas-bundle.tar.gz archive with the following structure is created next to the executable file:
bmaas-bundle.tar.gz├── log.log└── bundle/├── hw-bundle-util.version├── sanitize.legend├── collect/├── exec/│ └── <CHECK>/│ ├── <UTILITY_NAME>[.<DETAIL>].stdout│ ├── <UTILITY_NAME>[.<DETAIL>].stderr│ ├── <UTILITY_NAME>.version│ └── legend└── collection.incomplete
Where:
-
log.log: thehw-bundle-utiloperation log. -
bundle/hw-bundle-util.version: the version ofhw-bundle-utilthat was used to generate the report. -
bundle/sanitize.legend: the list of values that were replaced in the kernel boot parameters before the report was packed. -
bundle/collect/: OS files copied from the system. The copy of/proc/cmdlineis cleared of secrets beforehand. -
bundle/exec/<CHECK>/: results of calling auxiliary utilities. A separate directory is created for each check, containing:-
<UTILITY_NAME>[.<DETAIL>].stdoutand<UTILITY_NAME>[.<DETAIL>].stderr: files with the output from the standard output streamstdoutand from the standard error streamstderr. If the auxiliary utility produced no diagnostic or debug messages, thestderrfile is absent.Here
<DETAIL>is additional information about the check. For example, forethtool, the interface name is specified:ethtool.eth0. -
<UTILITY_NAME>.version: the version of the auxiliary utility. -
legend: a summary of the auxiliary utility launch: arguments and reasons for missing results.
-
-
bundle/collection.incomplete: the list of checks that could not be completed, with the reasons. The file is created only if the data is not collected completely, for example, because a required auxiliary utility is missing in the system or the utility was run without root privileges.
Before the report is created, credentials that appear in the kernel boot parameters are cleared. Removal is performed using known patterns of storing sensitive information, as well as the keywords password, passwd, token, secret, credential, apikey, api_key, accesskey, access_key. In place of the removed value, an entry like secret:S0:secret-key:len=<CHARACTER_COUNT>:fp=<FINGERPRINT> remains, and the rest of the line is not changed. Here <FINGERPRINT> is a sequence of characters that is the same for the same secret. This way, you can find out where and which secret is used without disclosing its contents. If you run the utility again, the entries for the same secrets in the new archive will differ. This happens because the fingerprint is regenerated on each run.
Cleaning is applied to the collect/cmdline file, as well as to the output of exec/kernel/dmesg.stdout and journalctl.stdout. The rest of the content is included in the archive unchanged: the output of auxiliary utilities, copies of files from /proc, /sys, and /etc, and the operation log of the utility itself. From /var/log/syslog or /var/log/messages and /var/log/kern.log, only the latest entries are included in the archive, not the entire file.
Launch format:
./hw-bundle-util [COMMAND] [OPTIONS]
Command | Purpose |
|---|---|
| Collecting diagnostic data. Used by default if no command is specified |
| Displaying the utility version |
Parameter | Default value | Purpose |
|---|---|---|
Help | ||
| — | Displaying help. |
Working directory and logging parameters of the | ||
|
| Working directory. The archive is created next to it and has the same name but with the |
|
| Verbosity of terminal output. Valid values: |
|
| Verbosity of writing to the |
| Not used | Do not delete the collected directory tree after the archive is created. By default, it is deleted because the archive already contains the same data |
Archive upload parameters of the | ||
| — | URL to which the archive must be sent. If the parameter is not specified, the archive is saved only on disk next to the executable file or in the directory set by the |
|
| Upload method. Valid values: |
|
| Time limit for the upload |
| — | Additional HTTP header in the |
| Not used | Do not verify the server certificate. Used in environments with a self-signed certificate |
Code | Description |
|---|---|
| Success: the report is collected completely |
| Unexpected error |
| Error in command-line arguments |
| Unknown command passed |
| Failed to create the archive |
| Failed to create the directory |
| Failed to create the file |
| Failed to write the file |
| Failed to send the archive |
| Failed to determine the working directory |
| Failed to delete the directory |
| The report is collected and delivered, but some checks produced no data. For details, see the |
| Interrupted by |
| Interrupted by |