DEBUGINFOD-FIND(1)

🎀 NAME 🎀

debuginfod-find — request debuginfo-related data

okay so real talk, this one lives in the General Commands Manual, section 1 💖 it's your little errand-runner for asking debuginfod servers "hey bestie, can I have this file please" and it's genuinely so useful, no cap.

---

✨ SYNOPSIS ✨

debuginfod-find [OPTION]... debuginfo BUILDID
debuginfod-find [OPTION]... debuginfo PATH
debuginfod-find [OPTION]... executable BUILDID
debuginfod-find [OPTION]... executable PATH
debuginfod-find [OPTION]... source BUILDID /FILENAME
debuginfod-find [OPTION]... source PATH /FILENAME
debuginfod-find [OPTION]... metadata KEY VALUE

like… pick a mode, pick an identifier, and go 🦋

---

🌸 DESCRIPTION 🌸

debuginfod-find goes and queries one or more debuginfod servers for debuginfo-related data. If it gets a match, it saves the requested file into a local cache, prints the file name to standard output, and dips out with a success status of 0. If anything goes wrong, it exits with a failure status and yells an error message at standard error. periodt. 💅

The debuginfod system uses buildids to identify debuginfo-related data. These live as binary notes inside ELF/DWARF files, and they're written as lowercase hexadecimal. So for example, if you wanna see the buildid of a program like /bin/ls, go peek at the ELF note GNU_BUILD_ID:

% readelf -n /bin/ls | grep -A4 build.id
Note section [ 4] '.note.gnu.buildid' of 36 bytes at offset 0x340:
Owner          Data size  Type
GNU                   20  GNU_BUILD_ID
Build ID: 8713b9c3fb8a720137a4a08b325905c7aaf8429d

and then the hexadecimal BUILDID is literally just:

8713b9c3fb8a720137a4a08b325905c7aaf8429d

iconic, right? 😌

Now here's the cute part: instead of the hexadecimal BUILDID, debuginfod-find will also accept a PATH name pointing at an ELF binary, and it'll extract the buildid from it for you. This alternate mode kicks in if the file name has any character that isn't [0-9a-f]. And if you've got a file with a name that's ambiguously hex-looking — like deadbeef — you can still pass it by giving it an extra ./deadbeef path component. sneaky but valid 🫶

💜 debuginfo BUILDID

If the buildid you handed over is known to a server, this request gets you a binary object containing the customary .*debug_* sections. That might be a split debuginfo file as created by strip, or it might be an original unstripped executable. either way, slay.

💜 executable BUILDID

If the given buildid is known to the server, this request gets you a binary object containing the normal executable segments. This may be an executable stripped by strip, or it may be an original unstripped executable. And yes — ET_DYN shared libraries count as a type of executable here. bestie said "close enough, it's family" 💖

💜 source BUILDID /SOURCE/FILE

If the given buildid is known to the server, this request gets you a binary object containing the source file you mentioned. The path should be absolute.

Here's the thing though — relative path names show up constantly in the DWARF file's source directory, but those paths are relative to each individual compilation unit's AT_comp_dir paths, and a single executable is made up of multiple CUs. so to disambiguate, debuginfod expects source queries to prefix relative path names with the CU compilation-directory, followed by a mandatory /. the way that slash is not optional, ok 😭

Note: for software packaged by distributions, the CU compilation-directory may not be obvious. You can find it by inspecting AT_comp_dir values in downloaded debuginfo. For example, the comp_dir of the Fedora 37 version of /bin/ls can be found like this:

% debuginfod-find debuginfo /bin/ls
~/.cache/debuginfod_client/03529d48345409576cd5c82a56ad08555088d353/
% eu-readelf -w ~/.cache/debuginfod_client/03529d48345409576cd5c82a56ad08555088d353/debuginfo | grep comp_dir
           comp_dir             (line_strp) "/usr/src/debug/coreutils-9.1-6.fc37.x86_64/separate"

Note: the caller may or may not elide ../ or /./ or extraneous /// sorts of path components in the directory names. debuginfod accepts both forms. Specifically, debuginfod canonicalizes path names according to RFC3986 section 5.2.4 (Remove Dot Segments), plus reducing any // to / in the path.

For example:

#include <stdio.h>               source BUILDID /usr/include/stdio.h
/path/to/foo.c                   source BUILDID /path/to/foo.c
../bar/foo.c AT_comp_dir=/zoo/   source BUILDID /zoo//../bar/foo.c

see how that last one just… works? 🧚

💜 section BUILDID SECTION-NAME

If the given buildid is known to the server, this request gets you a binary file containing the raw section contents — whether it's found in an executable or in a separated debuginfo file. doesn't matter where it's hiding, we're getting it. 🔥

💜 metadata KEY VALUE

All the designated debuginfod servers get queried for metadata about all files matching a given key/value query in their index. The results include names and buildids, which you can totally use in future queries to fetch the actual files. it's giving "preview before you commit" energy ✨

• file — VALUE: path — exact match path, including in archives
• glob — VALUE: pattern — shell-style glob match pattern, including in archives, as in fnmatch(FNM_PATHNAME)
• buildid — VALUE: hex — all executables and debuginfo files matching the given buildid

The resulting output will look something like the following:

{
  "results":[
    {
      "type":"executable",
      "buildid":"f0aa15b8aba4f3c28cac3c2a73801fefa644a9f2",
      "file":"/usr/local/bin/hello",
      "archive":"/opt/elfutils/tests/test-2290642/R/rhel7/hello2-1.0-2.x86_64.rpm"
    },
    {
      "type":"executable",
      "buildid":"bc1febfd03ca05e030f0d205f7659db29f8a4b30",
      "file":"hello2"
    }
  ],
  "complete":true }

The results of the search are output to stdout as a JSON object containing an array of objects, supplying metadata about each match, as well as a boolean value corresponding to the completeness of the result. The result is considered complete if all of the queries to upstream servers returned complete results and the local query succeeded. This metadata report may be cached. It may be incomplete and may contain duplicates. Additional JSON object fields may be present. so like, don't be shocked if you see extra stuff in there, it's fine 🙈

The fields:

• buildid — TYPE: string — hexadecimal buildid associated with the file
• type — TYPE: string — one of debuginfo or executable
• file — TYPE: string — matched file name, outside or inside the archive
• archive — TYPE: string — archive containing matched file name, if any

It's worth noting that type cannot be source, since in order to perform such a search fast enough, additional indexing would need to be added to the database, which would nearly double its size. yeah no, we're not doing that 💀

The search also always combines both files and archives in the results, and at this time further granularity is not available. that's just the vibe check result, sorry bestie.

---

👑 OPTIONS 👑

• -v, --verbose — Increase verbosity, including printing frequent download-progress messages and printing the http response headers from the server. very "narrator voice on" of it 🎀
• --help, --usage — Print some help and exit. classic.

---

🌈 SECURITY 🌈

If IMA signature(s) are available from the RPMs that contain the requested files, then debuginfod will extract those signatures into response headers, and debuginfod-find will perform verification upon the files. Validation policy is controlled via tags inserted into $DEBUGINFOD_URLS. By default, debuginfod-find acts in ignore mode. 👀

If accessed across HTTP rather than HTTPS, the network should be trustworthy. Authentication information through the internal libcurl library is not currently enabled, except for the basic plaintext http[s]://userid:password@hostname/ style. (The debuginfod server does not perform authentication, but a front-end proxy server could.)

The following information is generic. Some debuginfod clients may internally override defaults listed here.

---

✨ bestie there is literally MORE of this page, we are NOT done, keep going 💅

✨ ENVIRONMENT VARIABLES ✨

okay bestie, gather round the group chat 💖 these env vars are the behind-the-scenes besties that tell the debuginfod client what to do. no skipping, they all matter.

💾 $TMPDIR

points to the file system used for temporary files. the default is /tmp. simple, iconic.

🌐 $DEBUGINFOD_URLS

this one is a list of URL prefixes for trusted debuginfod instances. alternate URL prefixes are separated by a space. it may be set by /etc/profile.d scripts reading /etc/debuginfod/*.urls files. it can also contain policy defining tags that dictate the response policy for verifying per-file IMA signatures in RPMs. as the space separated list is read left to right, when you hit a tag, the subsequent URLs up to the next tag get handled using that specified policy. all URLs before the first tag use the default policy, ima:ignore. for example:

DEBUGINFOD_URLS="https://foo.com ima:enforcing https://bar.ca http://localhost:8002/ ima:ignore https://baz.org"

so foo.com and baz.org use the default ignore policy, while bar.ca and localhost use an enforcing policy. the policy tag can be one of these:

• ima:enforcing — every downloaded file requires a valid signature, fully protecting integrity. no shortcuts.
• ima:ignore — skips verification altogether, providing no protection. it's giving trusting.

alerts of validation failure will be directed as specified in $DEBUGINFOD_VERBOSE. 👀

🗂️ $DEBUGINFOD_CACHE_PATH

this governs the location of the cache where downloaded files and cache-control files are kept. the default directory is chosen based on other environment variables, see below. it's the cache queen's address 💅

📈 $DEBUGINFOD_PROGRESS

governs the default progress function. if set, and if a progressfn is not explicitly set, then the library will configure a default progressfn. this function will append a simple progress message periodically to stderr. the default is no progress function output. so if you want lil updates, set it; if not, silence is golden ✨

🗣️ $DEBUGINFOD_VERBOSE

governs the default file descriptor for verbose output. if set, and if a verbose fd is not explicitly set, then the verbose output will be produced on STDERR_FILENO. yes bestie, it's chatty on purpose.

🔁 $DEBUGINFOD_RETRY_LIMIT

governs the default limit of retry attempts. if a query failed with errno other than ENOENT, will initiate several attempts within the limit. so like, it's not giving up unless the error is ENOENT. periodt.

⏳ $DEBUGINFOD_TIMEOUT

governs the download commencing timeout, in seconds, for each debuginfod HTTP connection. a server is skipped if it either fails to establish a connection within the timeout or fails to provide at least 100K of data within the timeout. the default is 90 seconds. zero or negative means "no timeout". so you can wait forever if you want, but that's a choice 🙈

🕰️ $DEBUGINFOD_MAXTIME

dictates how long the client will wait to complete the download a file found on a server, in seconds. it is best used to ensure that a file is downloaded quickly or be rejected. the default is 0 (infinite time). so by default, it's patient like a saint.

📦 $DEBUGINFOD_MAXSIZE

dictates the maximum size of a file to download in bytes. this is best used if the user would like to ensure only small files are downloaded. a value of 0 causes no consideration for size, and the client may attempt to download a file of any size. the default is 0 (infinite size). tiny file only? set it. big chaotic energy? leave it at 0. 💀

📨 $DEBUGINFOD_HEADERS_FILE

points to a file that supplies headers to outbound HTTP requests, one per line. the header lines shouldn't end with CRLF, unless that's the system newline convention. whitespace-only lines are skipped. so no empty lines with main character energy, they get ignored.

🔐 $DEBUGINFOD_IMA_CERT_PATH

contains a list of absolute directory paths holding X.509 certificates for RPM per-file IMA-verification. alternate paths are separated by colons. yes, colons. not commas. we love a specific separator. 🌈

---

🧺 CACHE 🧺

before each query, the debuginfod client library checks for a need to clean the cache. if it's time to clean, the library traverses the cache directory and removes downloaded debuginfo-related artifacts and newly empty directories, if they have not been accessed recently. it's giving spring cleaning but make it automated 🧹

control files are located directly under the cache directory. they contain simple decimal numbers to set cache-related configuration parameters. if the files do not exist, the client library creates the files with the default parameter values as content. so they manifest themselves, iconic.

after each query, the debuginfod client library deposits newly received files into a directory & file that is named based on the build-id. a failed query is also cached by a special file. the naming convention used for these artifacts is deliberately undocumented. so don't ask, bestie, it's a secret 💅

📂 Cache directories

• $XDG_CACHE_HOME/debuginfod_client/ — default cache directory, if $XDG_CACHE_HOME is set.
• $HOME/.cache/debuginfod_client/ — default cache directory, if $XDG_CACHE_HOME is not set.
• $HOME/.debuginfod_client_cache/ — deprecated cache directory, used only if preexisting. so like, only if it was already there. don't come for it.

🧮 Control files

• cache_clean_interval_s — this control file gives the interval between cache cleaning rounds, in seconds. the default is 86400, one day. 0 means "immediately". so if you set 0, it's clean-girl-clean-girl on loop.
• max_unused_age_s — this control file sets how long unaccessed debuginfo-related files are retained, in seconds. the default is 604800, one week. 0 means "immediately". no hoarding, periodt.
• cache_miss_s — this control file sets how long to remember a query failure, in seconds. new queries for the same artifacts within this time window are short-circuited (returning an immediate failure instead of sending a new query to servers). this accelerates queries that probably would still fail. the default is 600, 10 minutes. 0 means "forget immediately". so it's not holding grudges unless you tell it to.
• metadata_retention_s — this control file sets how long to remember the results of a metadata query. new queries for the same artifacts within this time window are short-circuited (repeating the same results). this accelerates queries that probably would probably have the same results. the default is 3600, 1 hour. 0 means "do not retain". yes, "probably would probably" is in the original, and we respect the chaos. 😭

---

👀 SEE ALSO 👀

• debuginfod(8)
• debuginfod_find_debuginfod(3)

and that's the whole page, bestie 🫶 — DEBUGINFOD-FIND(1), from the debuginfod source/version, dated whenever your local manpage footer says it was. go forth and debug like the main character you are 💅✨