systemd-hwdb

Update the binary hardware database in /etc/udev

$ systemd-hwdb update

$ systemd-hwdb query [modalias]

$ systemd-hwdb [[-s|--strict]] update

$ systemd-hwdb --usr update

$ systemd-hwdb [[-r|--root]] [path/to/root] update

systemd-hwdb [OPTIONS...] [COMMAND] [ARGUMENTS...]

Common commands include:
systemd-hwdb update [--usr|--etc] [--root=PATH]
systemd-hwdb query [MODALIAS...]
systemd-hwdb print-all

-h, --help
    Displays a short help text and exits.

--version
    Shows the version information and exits.

--usr
    When used with the update command, compiles the database to /usr/lib/udev/hwdb.bin.

--etc
    When used with the update command, compiles the database to /etc/udev/hwdb.bin. This is the default location for local modifications.

--root=PATH
    Specifies an alternative root directory for searching source .hwdb files and compiling the database.

-p, --pretty
    Formats the output of the query command into human-readable key=value pairs.

-s, --separator=CHARACTER
    Specifies a custom character to separate properties when querying. Defaults to a newline character (\n).

--debug
    Enables verbose debug messages during execution.

The systemd-hwdb command is a utility used to manage the hardware database (hwdb) employed by udev and, consequently, systemd.

Its primary functions include compiling the source .hwdb files into a binary database, hwdb.bin, and querying this database for specific hardware properties. This database is crucial for identifying various hardware components and applying configuration settings such as keyboard layouts, accelerometer orientations, or touchscreen calibrations.

Source files are typically found in /usr/lib/udev/hwdb.d/ and /etc/udev/hwdb.d/. When systemd-hwdb is used to update the database, it compiles these text files, which contain rules matching hardware identifiers (like PCI IDs or USB IDs) to property key-value pairs. The resulting hwdb.bin file is then used by udev to automatically configure devices as they are detected.

Any modifications to the .hwdb source files necessitate running systemd-hwdb update to recompile the database. For these changes to take effect on already-plugged-in devices, a udevadm trigger or udevadm control --reload-rules command is often required.

After modifying .hwdb source files, it is crucial to run systemd-hwdb update to recompile the database.

For changes to take effect on devices that are already plugged in, you often need to instruct udev to re-process events or reload its rules, typically using udevadm trigger or udevadm control --reload-rules.

Custom .hwdb files placed in /etc/udev/hwdb.d/ will override or extend system-provided files in /usr/lib/udev/hwdb.d/, allowing for local customizations.

Beyond its options, systemd-hwdb supports several commands to perform specific actions:

update: Compiles the hardware database from all .hwdb source files found in configured directories (e.g., /usr/lib/udev/hwdb.d/ and /etc/udev/hwdb.d/) into a binary hwdb.bin file.

query [MODALIAS...]: Queries the compiled hardware database for properties matching the provided MODALIAS strings. MODALIAS is a string representing a device's hardware identification.

print-all: Dumps the entire contents of the compiled hardware database to standard output, showing all stored properties for all matched hardware identifiers.

The hardware database is populated by text files with the .hwdb extension. These files contain rules that map hardware identifiers (such as vendor/product IDs for PCI, USB, or DMI) to device properties. Each entry typically starts with a matching rule, followed by key-value pairs. For instance, a rule might identify a specific keyboard model and assign properties like KEYBOARD_KEY_a=a_new_scan_code or ACCEL_MOUNT_MATRIX=... to correct sensor orientations. These files are processed by systemd-hwdb during the update process to create the efficient binary database.

The systemd-hwdb utility is an integral part of the systemd ecosystem. It was introduced as part of systemd's broader efforts to unify and standardize Linux system management, particularly its hardware device management components inherited from udev. Its development aligns with the evolution of udev from a separate project into a core component of systemd, providing a consistent mechanism for handling hardware properties and configuration.

systemd(1), udev(7), udevadm(8)