debuginfod-find

Request data based on the build_id

$ debuginfod-find -vv debuginfo [build_id]

debuginfod-find [OPTIONS] TYPE [BUILDID | PATH]...

Deprecated forms (implied debuginfo type):
debuginfod-find [OPTIONS] BUILDID...
debuginfod-find [OPTIONS] -d|-x|-s [BUILDID] [PATH]...

Where:
`TYPE` specifies the kind of file to retrieve, e.g., buildid, debuginfo, executable, source, or src.
`BUILDID` is the unique hexadecimal identifier of an ELF binary or debuginfo file.
`PATH` is the full path to a source file as it was known during the original build process.

-v, --verbose
    Enables verbose output, showing URLs queried, download progress, and other diagnostic information.

-q, --quiet
    Suppresses all output except for errors. Useful for scripting.

-u <URL>, --url=<URL>
    Specifies one or more debuginfod server URLs to query. This option can be used multiple times and overrides the DEBUGINFOD_URLS environment variable.

-C <DIR>, --cache-dir=<DIR>
    Sets an alternative directory for caching downloaded files. By default, files are cached in ~/.cache/debuginfod_client.

-t <SECONDS>, --timeout=<SECONDS>
    Sets the network timeout in seconds for server queries. Defaults to 90 seconds.

--help
    Displays a help message and exits.

--version
    Displays version information and exits.

buildid <BUILDID>...
    Queries for an arbitrary file associated with a build ID and returns its canonical URL. This is less common for direct use and more for `debuginfod` internal routing.

debuginfo <BUILDID>...
    Finds and fetches the debuginfo file corresponding to the given build ID. This is the default action if no type is specified.

executable <BUILDID>...
    Finds and fetches the original executable file associated with the given build ID.

source <BUILDID> <PATH>...
    Finds and fetches the source file located at PATH within the build associated with the given build ID.

src <BUILDID> <PATH>...
    An alias for the source subcommand.

-d, --debuginfo (deprecated)
    Deprecated. Use the debuginfo subcommand instead.

-x, --executable (deprecated)
    Deprecated. Use the executable subcommand instead.

-s, --source (deprecated)
    Deprecated. Use the source or src subcommand instead.

debuginfod-find is a client-side command-line utility for the debuginfod service. It allows users to automatically locate and download debuginfo files, source code files, and executable files using their unique build IDs or original source paths. This greatly simplifies debugging efforts by providing on-demand access to necessary debugging symbols and source code, eliminating the need for manual searching or installing large debuginfo packages. The command queries configured debuginfod servers (typically specified via the DEBUGINFOD_URLS environment variable or command-line options) and intelligently caches downloaded files locally. It's particularly useful when integrating with debuggers like GDB, which can be configured to automatically use debuginfod-find to resolve missing symbols or source code.

debuginfod-find relies on active network connectivity to reach debuginfod servers. Its functionality is directly dependent on the availability and content provided by these configured servers.
Files downloaded are cached locally; users should ensure sufficient disk space for the cache directory, especially when dealing with large debuginfo files.
The tool strictly matches files using their unique Build IDs. An incorrect or missing build ID will prevent the file from being found.
Proxy server settings or firewall rules may interfere with direct connections to debuginfod servers.

DEBUGINFOD_URLS: This critical environment variable specifies a space-separated list of URLs to debuginfod servers that debuginfod-find will query. If not set, it may try a default URL if configured by the distribution, or it will not query any servers.
DEBUGINFOD_TIMEOUT: Controls the network timeout in seconds for all server queries made by debuginfod-find.
DEBUGINFOD_CACHE_PATH: Allows users to specify an alternative default cache directory for downloaded files, overriding ~/.cache/debuginfod_client.
DEBUGINFOD_VERBOSE: If set, enables verbose output, similar to the --verbose option.

debuginfod-find's core functionality relies on Build IDs. A build ID is a unique hexadecimal identifier embedded in ELF binaries (executables, shared libraries) and their corresponding debuginfo files during compilation and linking. This ensures that the retrieved debug information or source code precisely matches the specific version of the binary being debugged, preventing mismatches that could lead to incorrect debugging sessions. Tools like readelf -n can display the build ID of an ELF file.

The debuginfod project, including the debuginfod-find client, emerged as part of the elfutils package development around 2019-2020. Its inception aimed to revolutionize the distribution and retrieval of debug information in Linux environments, moving away from the cumbersome traditional method of installing large, distribution-specific debuginfo packages. By providing an on-demand, HTTP-based service, debuginfod-find significantly streamlined the debugging workflow for developers and system administrators, enabling quicker access to necessary symbols and source code without cluttering local systems. It quickly gained adoption in major Linux distributions.

debuginfod(8), gdb(1), objdump(1), readelf(1)