drgn 0.2.0

Programmable debugger

drgn (pronounced “dragon”) is a debugger with an emphasis on programmability. drgn exposes the types and variables in a program for easy, expressive scripting in Python. For example, you can debug the Linux kernel:

>>> from drgn.helpers.linux import list_for_each_entry
>>> for mod in list_for_each_entry('struct module',
...                                prog['modules'].address_of_(),
...                                'list'):
...    if mod.refcnt.counter > 10:
...        print(mod.name)
...
(char [56])"snd"
(char [56])"evdev"
(char [56])"i915"

Although other debuggers like GDB have scripting support, drgn aims to make scripting as natural as possible so that debugging feels like coding. This makes it well-suited for introspecting the complex, inter-connected state in large programs.

Additionally, drgn is designed as a library that can be used to build debugging and introspection tools; see the official tools.

drgn was developed at Meta for debugging the Linux kernel (as an alternative to the crash utility), but it can also debug userspace programs written in C. C++ support is in progress.

Documentation can be found at drgn.readthedocs.io.

Installation

Package Manager

drgn can be installed using the package manager on some Linux distributions.

• Fedora, RHEL/CentOS Stream >= 9

  $ sudo dnf install drgn

• RHEL/CentOS < 9

  Enable EPEL. Then:

  $ sudo dnf install drgn

• Oracle Linux >= 8

  Enable the ol8_addons or ol9_addons repository. Then:

  $ sudo dnf config-manager --enable ol8_addons  # OR: ol9_addons
  $ sudo dnf install drgn

  drgn is also available for Python versions in application streams. For example, use dnf install python3.12-drgn to install drgn for Python 3.12. See the documentation for drgn in Oracle Linux 9 and Oracle Linux 8 for more information.

• Debian >= 12 (Bookworm)/Ubuntu >= 24.04 (Noble Numbat)

  $ sudo apt install python3-drgn

  To get the latest version on Ubuntu, enable the michel-slm/kernel-utils PPA first.

• Arch Linux

  $ sudo pacman -S drgn

• Gentoo

  $ sudo emerge dev-debug/drgn

• openSUSE

  $ sudo zypper install python3-drgn

pip

If your Linux distribution doesn’t package the latest release of drgn, you can install it with pip.

First, install pip. Then, run:

$ sudo pip3 install drgn

This will install a binary wheel by default. If you get a build error, then pip wasn’t able to use the binary wheel. Install the dependencies listed below and try again.

Note that RHEL/CentOS 7, Debian 10 (“buster”), and Ubuntu 18.04 (“Bionic Beaver”) (and older) ship Python versions which are too old. Python 3.8 or newer must be installed.

From Source

To get the development version of drgn, you will need to build it from source. First, install dependencies:

• Fedora, RHEL/CentOS Stream >= 9

  $ sudo dnf install autoconf automake check-devel elfutils-debuginfod-client-devel elfutils-devel gcc git json-c-devel libkdumpfile-devel libtool make pcre2-devel pkgconf python3 python3-devel python3-pip python3-setuptools xz-devel

• RHEL/CentOS < 9, Oracle Linux

  $ sudo dnf install autoconf automake check-devel elfutils-devel gcc git json-c-devel libtool make pcre2-devel pkgconf python3 python3-devel python3-pip python3-setuptools xz-devel

  Optionally, install libkdumpfile-devel from EPEL on RHEL/CentOS >= 8 or install libkdumpfile from source if you want support for the makedumpfile format. For Oracle Linux >= 7, libkdumpfile-devel can be installed directly from the corresponding addons repository (e.g. ol9_addons).

  Replace dnf with yum for RHEL/CentOS/Oracle Linux < 8.

  When building on RHEL/CentOS/Oracle Linux < 8, you may need to use a newer version of GCC, for example, using the devtoolset-12 developer toolset. Check your distribution’s documentation for information on installing and using these newer toolchains.

• Debian/Ubuntu

  $ sudo apt install autoconf automake check gcc git libdebuginfod-dev libjson-c-dev libkdumpfile-dev liblzma-dev libelf-dev libdw-dev libpcre2-dev libtool make pkgconf python3 python3-dev python3-pip python3-setuptools zlib1g-dev

  On Debian <= 11 (Bullseye) and Ubuntu <= 22.04 (Jammy Jellyfish), libkdumpfile-dev is not available, so you must install libkdumpfile from source if you want support for the makedumpfile format.

• Arch Linux

  $ sudo pacman -S --needed autoconf automake check gcc git json-c libelf libkdumpfile libtool make pcre2 pkgconf python python-pip python-setuptools xz

• Gentoo

  $ sudo emerge --noreplace --oneshot dev-build/autoconf dev-build/automake dev-libs/check dev-libs/elfutils dev-libs/json-c dev-libs/libpcre2 sys-devel/gcc dev-vcs/git dev-libs/libkdumpfile dev-build/libtool dev-build/make dev-python/pip virtual/pkgconfig dev-lang/python dev-python/setuptools app-arch/xz-utils

• openSUSE

  $ sudo zypper install autoconf automake check-devel gcc git libdebuginfod-devel libdw-devel libelf-devel libjson-c-devel libkdumpfile-devel libtool make pcre2-devel pkgconf python3 python3-devel python3-pip python3-setuptools xz-devel

Then, run:

$ git clone https://github.com/osandov/drgn.git
$ cd drgn
$ python3 setup.py build
$ sudo python3 setup.py install

See the installation documentation for more options.

Quick Start

drgn debugs the running kernel by default; simply run drgn. To debug a running program, run drgn -p $PID. To debug a core dump (either a kernel vmcore or a userspace core dump), run drgn -c $PATH. Make sure to install debugging symbols for whatever you are debugging.

Then, you can access variables in the program with prog["name"] and access structure members with .:

$ drgn
>>> prog["init_task"].comm
(char [16])"swapper/0"

You can use various predefined helpers:

>>> len(list(bpf_prog_for_each()))
11
>>> task = find_task(115)
>>> cmdline(task)
[b'findmnt', b'-p']

You can get stack traces with stack_trace() and access parameters or local variables with trace["name"]:

>>> trace = stack_trace(task)
>>> trace[5]
#5 at 0xffffffff8a5a32d0 (do_sys_poll+0x400/0x578) in do_poll at ./fs/select.c:961:8 (inlined)
>>> poll_list = trace[5]["list"]
>>> file = fget(task, poll_list.entries[0].fd)
>>> d_path(file.f_path.address_of_())
b'/proc/115/mountinfo'

See the user guide for more details and features.

Getting Help

• The GitHub issue tracker is the preferred method to report issues.

• There is also a Linux Kernel Debuggers Matrix room and a linux-debuggers mailing list on vger.

License

Copyright (c) Meta Platforms, Inc. and affiliates.

drgn is licensed under the LGPLv2.1 or later.