How Debian Reportbug Collects System Metadata

When reporting a bug in the Debian operating system, the reportbug utility automates the collection of critical diagnostic information to help package maintainers reproduce and resolve issues. This article explains the underlying mechanisms reportbug uses to gather package versions, system architectures, hardware details, and environment configurations, and how it formats this metadata into a structured report.

Querying the Package Management Database

The primary source for package version metadata is Debian's low-level package manager, dpkg. When you specify a package to report against, reportbug queries the local dpkg status database (/var/lib/dpkg/status) using tools like dpkg-query.

Through this interface, reportbug extracts:

  • Package Status and Version: The exact upstream and Debian release version installed.
  • Architecture: The binary architecture for which the package was compiled (such as amd64 or arm64).
  • Dependencies and Recommendations: The current installation status and version numbers of all dependencies, recommendations, and suggested packages defined in the package control fields.
  • Modified Configuration Files (Conffiles): It checks the checksums of the package’s default configuration files against what is currently on the disk, flagging any customized files for review.

reportbug also interacts with APT to determine pinning priorities, repository sources, and whether the installed package originated from stable, testing, unstable, or an external repository.

Package-Specific Bug Scripts

Debian packages can provide custom hooks that instruct reportbug to collect specialized hardware or configuration data relevant only to that software. These files reside in the /usr/share/bug/<package-name>/ directory.

If an executable named script exists in that directory, reportbug runs it automatically in a subshell and appends its standard output to the bug report. For example:

  • Kernel and driver packages provide scripts that invoke tools like lspci, lsusb, dmesg, and parse /proc/cpuinfo to extract relevant hardware controller data.
  • Display server packages (like Xorg or Wayland compositors) run scripts that collect graphics card identifiers, active display drivers, and monitor configurations.
  • System daemons run scripts that filter and append sanitized service logs or non-sensitive configuration parameters.

Gathering Kernel and System Environment Data

For general system metadata, reportbug queries standard Unix utilities and the Linux virtual filesystems (/proc and /sys):

  • Kernel Version: Retrieved via the uname system call or utility (e.g., uname -a), recording the kernel release, compilation date, and SMP status.
  • System Architecture: Obtained via dpkg --print-architecture and dpkg --print-foreign-architectures to show whether multiarch (such as 32-bit compatibility on 64-bit systems) is active.
  • Locale and Shell: The tool reads current environment variables (such as LANG, LC_ALL, and SHELL) to document localization settings that could affect software behavior.

User Review and Redaction

Once the scripts and database queries complete, reportbug aggregates the metadata into standardized Debian Bug Tracking System (BTS) pseudo-headers and plain-text sections.

Before transmission, reportbug spawns a text editor displaying the complete compiled draft. This gives the user full control to inspect, redact, or supplement the collected hardware details, file paths, and version strings before the report is sent to the maintainer.