systemd-hwdb: Hardware database management

systemd-hwdb: Hardware database management

A pragmatic guide to updating and querying the systemd hardware database. This tool helps udev map hardware to its properties using a centralized database.

Quick start with real examples

  • Update the hardware database in the default location (/etc/udev):
systemd-hwdb update
  • Query the database for a specific modalias and print the result:
systemd-hwdb query {{modalias}}
  • Update with strict parsing (non-zero exit on parsing errors):
systemd-hwdb --strict update
  • Update the database in the vendor-provided system directory (/usr/lib/udev):
systemd-hwdb --usr update
  • Update the database at an alternate root path (useful for chroot or container scenarios):
systemd-hwdb --root /path/to/root update

Tip: If you see a message about a stale cache (e.g., 62 days), run a metadata refresh or update as soon as possible.

What does systemd-hwdb do?

  • Reads and updates the compiled hardware database that udev uses to identify hardware.
  • Ensures udev rules and metadata have accurate hardware classifications.
  • Supports multiple locations (default, usr, or a custom root) to fit different system layouts.

Common workflows

1) Update the database from sources

  • Default (undisturbed by root or usr paths):
systemd-hwdb update
  • With strict parsing to catch misformatted entries:
systemd-hwdb --strict update
  • Update for the system’s [usr] database location:
systemd-hwdb --usr update
  • Update the database in a custom root (useful for chroot, containers, or image builds):
systemd-hwdb --root /path/to/root update

2) Query a specific hardware entry

  • Find information for a modalias (string that matches hardware IDs):
systemd-hwdb query {{modalias}}
  • The output is intended for humans, but can be parsed by scripts as needed.

Practical tips and pitfalls

  • Always run an update after adding or editing hwdb files in /etc/udev/hwdb.d or /usr/lib/udev/hwdb.d. Without updating, changes are not reflected.
  • If you manage a minimal/root filesystem, you may need to update the database inside the root path with —root to ensure the target image has the latest data.
  • Using —strict helps catch malformed hwdb entries early, but can cause scripts to fail if the hwdb contains errors.
  • After updating, you may need to reload udev to pick up new data:
sudo systemctl restart systemd-udevd

Troubleshooting quick checks

  • Verify the update completed without errors; look for exit code 0.
  • Check that the hwdb files were updated in the expected directory (e.g., /etc/udev/hwdb.d or /usr/lib/udev/hwdb.d).
  • If queries return nothing, ensure the modalias exists in the hwdb and that the database cache is up to date.

Summary

systemd-hwdb is a focused tool to manage the binary hardware database used by udev. Use update commands to refresh the cache, and query to inspect mappings for specific hardware identifiers. With strict mode and root-path options, you can tailor maintenance to your system layout and quality checks.

See Also