0.0.31 (Released April 16th, 2025)¶
These are some of the highlights of drgn 0.0.31. See the GitHub release for the full release notes, including more improvements and bug fixes.
Fun fact: this is the largest release of drgn since the first ever release, both in terms of number of commits and changed lines of code.
Module API¶
One of the first things drgn does when it starts up is figure out what binaries are loaded in your program: executables, shared libraries, Linux kernel image, Linux kernel modules, etc. Until this release, this all happened internally to drgn with no way to inspect or override it. This release adds new APIs to address this.
First, the drgn.Module
class and its subclasses were added to
represent binaries used by a program.
drgn.Program
gained a couple of methods for querying what modules were
created for a program, drgn.Program.modules()
and
drgn.Program.module()
:
>>> for module in prog.modules():
... print(module)
...
prog.main_module(name='kernel')
prog.relocatable_module(name='scsi_dh_rdac', address=0xffffffffc02fb000)
prog.relocatable_module(name='nvme', address=0xffffffffc051f000)
prog.relocatable_module(name='spi_intel', address=0xffffffffc0fa3000)
...
>>> prog.module("kernel")
prog.main_module(name='kernel')
>>> prog.module(0xffffffff92811100)
prog.main_module(name='kernel')
Modules are normally created automatically for all loaded binaries when
debugging symbols are loaded. This can also be done manually with
drgn.Program.loaded_modules()
or
drgn.Program.create_loaded_modules()
. Arbitrary modules can also be
created manually. This enables more
advanced use cases.
Options for Finding Debugging Symbols¶
drgn now provides much more control over how debugging symbols are found.
The --try-symbols-by
and --no-symbols-by
command line
options allow enabling or disabling methods of searching for debugging symbols.
The --debug-directory
and --no-default-debug-directories
options allow controlling the directories that are searched for debugging
symbols. The --kernel-directory
and
--no-default-kernel-directories
options allow controlling the
directories that are searched for Linux kernel files.
For example, if you have a kernel core dump and a directory containing kernel debugging symbols:
$ ls
kernel-6.15.0-rc1-debuginfo vmcore
$ drgn -c vmcore --kernel-directory kernel-6.15.0-rc1-debuginfo
These options are also available programmatically as
drgn.Program.debug_info_options
.
Stricter Debugging Symbol File Matching¶
A common pitfall for users is passing the wrong debugging symbol file to
-s
(for example, the vmlinux from a different kernel build, or a
kernel module or library that wasn’t loaded at the time). Before this release,
drgn was quite permissive and would use the file anyways, usually with
confusing results.
Starting in this release, drgn now always checks that files passed to
-s
or drgn.Program.load_debug_info()
correspond to a loaded
module (based on build IDs). If not, it logs a warning and ignores them.
However, there are valid use cases for adding unloaded files, like corrupted
core dumps or reading debugging symbols from arbitrary files. If you really
want to use a file for a specific module, then you can find the module with
drgn.Program.modules()
or drgn.Program.module()
and add the
file with drgn.Module.try_file(path, force=True)
. If you really want to load debugging symbols from a
file without associating it with a loaded module, you can use
--extra-symbols
or
drgn.Program.extra_module(...).try_file(path)
.
Debuginfod Integration¶
debuginfod is a service for automatically downloading debugging symbols. drgn has had partial debuginfod support for a long time (via the libdwfl library), with a few important limitations:
It couldn’t use debuginfod for the Linux kernel.
Downloads couldn’t be interrupted with Ctrl-C.
The download progress bar wasn’t very pretty.
This release improves drgn’s integration with debuginfod and fixes these issues.
There’s still one caveat for the Linux kernel: drgn only enables debuginfod for the Linux kernel on Fedora, because other distributions haven’t yet deployed the fix for extremely slow downloads of kernel debugging symbols on their debuginfod servers. Contact your distribution to request that they update their debuginfod server to at least elfutils 0.192 and compress their kernel debug info packages with parallel xz.
Custom Debugging Information Finders¶
If the above options for finding debugging symbols don’t provide enough flexibility, you can define totally custom ways of finding debugging symbols by registering a debugging information finder. See here for an example.
Plugins¶
drgn now has a basic plugin system. Currently, the main use case is automatically setting system- or user-specific configuration when drgn starts up. For example, system administrators may install a plugin that registers a debugging information finder for their specific system. See here for an overview and here for an example.
Running Code Snippets on the Command Line¶
Sometimes, you don’t want an interactive drgn session or a full drgn script;
you just want to run a short snippet of code. In this release, Stephen Brennan
added the -e
option, which takes a string of code to evaluate:
$ python3 -m drgn -e 'print(kaslr_offset())'
251658240
(We would have used -c
like the Python CLI, but that is already used to
specify a core dump.)
Kernel Stack Unwinding Without Debugging Symbols¶
drgn has had support for the Linux kernel’s ORC unwinder for a long time. However, although ORC data is typically saved in kernel core dumps, drgn previously only supported reading ORC data from the kernel debugging symbol files.
In this release, Stephen Brennan expanded drgn’s ORC support to be able to read ORC data directly from the core dump. This enables reliable stack unwinding even through unknown or out-of-tree kernel modules. This is the latest step towards support for debugging the Linux kernel without full DWARF debugging information.
Linux 6.14 and 6.15 Support¶
A change in Linux 6.14 broke how drgn determines module section addresses. This error on startup is fixed in this release:
/lib/modules/6.14.2/kernel/fs/binfmt_misc.ko (could not get section addresses: 'struct module_sect_attrs' has no member 'nsections')
A change in Linux 6.15 broke the kernfs
helpers.
This error is fixed in this release:
AttributeError: 'struct kernfs_node' has no member 'parent'
Another change in Linux 6.15 broke the
path_lookup()
helper’s handling of mount points.
This is fixed in this release.