PyPI CI Status Documentation Status https://img.shields.io/badge/code%20style-black-000000.svg

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 >= 32

    $ sudo dnf install drgn

  • RHEL/CentOS >= 8

    Enable EPEL. Then:

    $ sudo dnf install drgn

  • Arch Linux

    Install the drgn package from the AUR.

  • 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 6, Debian Stretch, Ubuntu Trusty, and Ubuntu Xenial (and older) ship Python versions which are too old. Python 3.6 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

    $ sudo dnf install autoconf automake elfutils-devel gcc git libkdumpfile-devel libtool make pkgconf python3 python3-devel python3-pip python3-setuptools

  • RHEL/CentOS

    $ sudo dnf install autoconf automake elfutils-devel gcc git libtool make pkgconf python3 python3-devel python3-pip python3-setuptools

    Optionally, install libkdumpfile-devel from EPEL on RHEL/CentOS >= 8 or install libkdumpfile from source if you want support for the makedumpfile format.

    Replace dnf with yum for RHEL/CentOS < 8.

  • Debian/Ubuntu

    $ sudo apt-get install autoconf automake gcc git liblzma-dev libelf-dev libdw-dev libtool make pkgconf python3 python3-dev python3-pip python3-setuptools zlib1g-dev

    Optionally, install libkdumpfile from source if you want support for the makedumpfile format.

  • Arch Linux

    $ sudo pacman -S --needed autoconf automake gcc git libelf libtool make pkgconf python python-pip python-setuptools

    Optionally, install libkdumpfile from the AUR or from source if you want support for the makedumpfile format.

  • openSUSE

    $ sudo zypper install autoconf automake gcc git libdw-devel libelf-devel libkdumpfile-devel libtool make pkgconf python3 python3-devel python3-pip python3-setuptools

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; run sudo drgn. To debug a running program, run sudo 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 .:

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

You can use various predefined helpers:

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

You can get stack traces with prog.stack_trace() and access parameters or local variables with stack_trace['name']:

>>> trace = prog.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.

License

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

drgn is licensed under the GPLv3 or later.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.2.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for osandov from gravatar.com osandov

Credits

Author: Omar Sandoval

License

GNU General Public License v3 or later (GPLv3+) (GPL-3.0-or-later)

Requires

Python >=3.6

Classifiers

Report project as malware

Metadata

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.2.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for osandov from gravatar.com osandov

Credits

Author: Omar Sandoval

License

GNU General Public License v3 or later (GPLv3+) (GPL-3.0-or-later)

Requires

Python >=3.6

Classifiers

Report project as malware

Release files for drgn 0.0.21

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for drgn 0.0.21
File Size Uploaded
drgn-0.0.21.tar.gz 1.0 MB Details

Built distributions (wheels)

Table of built distributions (wheels) for drgn 0.0.21
File
drgn-0.0.21-cp310-cp310-manylinux_2_12_x86_64.manylinux2010_x86_64.whl 4.2 MB CPython 3.10 CPython 3.10 Linux glibc 2.12+ x86-64 Details
drgn-0.0.21-cp39-cp39-manylinux_2_12_x86_64.manylinux2010_x86_64.whl 4.2 MB CPython 3.9 CPython 3.9 Linux glibc 2.12+ x86-64 Details
drgn-0.0.21-cp38-cp38-manylinux_2_12_x86_64.manylinux2010_x86_64.whl 4.2 MB CPython 3.8 CPython 3.8 Linux glibc 2.12+ x86-64 Details
drgn-0.0.21-cp37-cp37m-manylinux_2_12_x86_64.manylinux2010_x86_64.whl 4.2 MB CPython 3.7 CPython 3.7 pymalloc Linux glibc 2.12+ x86-64 Details
drgn-0.0.21-cp36-cp36m-manylinux_2_12_x86_64.manylinux2010_x86_64.whl 4.2 MB CPython 3.6 CPython 3.6 pymalloc Linux glibc 2.12+ x86-64 Details

Total release size: 21.9 MB

Release files / drgn-0.0.21.tar.gz

Download URL drgn-0.0.21.tar.gz
Size 1.0 MB
Tags Source
SHA-256 checksum
How to use checksums 		305a6276033b52a9db3bf742e84dc946ff2e28be015b6c04a2d894c4eebf894f
BLAKE2b-256 checksum
How to use checksums 		7d83c3356ff1af45aa2892a6b62f819d9bd64c4ab0201b332e3a502387df1de4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing? 		No
Uploaded via twine/4.0.1 CPython/3.10.8

Release files / drgn-0.0.21-cp310-cp310-manylinux_2_12_x86_64.manylinux2010_x86_64.whl

Download URL drgn-0.0.21-cp310-cp310-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Size 4.2 MB
Tags CPython 3.10 Linux glibc 2.12+ x86-64
SHA-256 checksum
How to use checksums 		297642b0551dc1a1d1f61efbe99809e1b3405722d91f6df27f5314590417d4b6
BLAKE2b-256 checksum
How to use checksums 		1e967dd94e7670aa8e810207586be25c555cf65996abf58c4d5efffcc8351e2b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing? 		No
Uploaded via twine/4.0.1 CPython/3.10.8

Release files / drgn-0.0.21-cp39-cp39-manylinux_2_12_x86_64.manylinux2010_x86_64.whl

Download URL drgn-0.0.21-cp39-cp39-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Size 4.2 MB
Tags CPython 3.9 Linux glibc 2.12+ x86-64
SHA-256 checksum
How to use checksums 		87062790ab32cf692cbac06f21e9b416f0b45e0c1ae16939283d7895055bccca
BLAKE2b-256 checksum
How to use checksums 		63d96258527cb9317ea924e6e72bb9a45f59da4bd8cfa1da414f14463874ce94
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing? 		No
Uploaded via twine/4.0.1 CPython/3.10.8

Release files / drgn-0.0.21-cp38-cp38-manylinux_2_12_x86_64.manylinux2010_x86_64.whl

Download URL drgn-0.0.21-cp38-cp38-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Size 4.2 MB
Tags CPython 3.8 Linux glibc 2.12+ x86-64
SHA-256 checksum
How to use checksums 		135ab19971b958a65c90ad259f562be40d4aba236b2151c9245731b903ead08b
BLAKE2b-256 checksum
How to use checksums 		e50f5c09c17b389e5fe39611fa019ee0e2063b8778962ecf64b3bae4f6afb4be
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing? 		No
Uploaded via twine/4.0.1 CPython/3.10.8

Release files / drgn-0.0.21-cp37-cp37m-manylinux_2_12_x86_64.manylinux2010_x86_64.whl

Download URL drgn-0.0.21-cp37-cp37m-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Size 4.2 MB
Tags CPython 3.7 CPython 3.7 pymalloc Linux glibc 2.12+ x86-64
SHA-256 checksum
How to use checksums 		d462838d7b03c37422844468bf2b8d690f595d4ec041c667ffda85dc95790c35
BLAKE2b-256 checksum
How to use checksums 		07760de4be444212fd9e1b83250b9a1adb73c786f592bd37c41ad69a63626ce0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing? 		No
Uploaded via twine/4.0.1 CPython/3.10.8

Release files / drgn-0.0.21-cp36-cp36m-manylinux_2_12_x86_64.manylinux2010_x86_64.whl

Download URL drgn-0.0.21-cp36-cp36m-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Size 4.2 MB
Tags CPython 3.6 CPython 3.6 pymalloc Linux glibc 2.12+ x86-64
SHA-256 checksum
How to use checksums 		afbc9409ac8380883066f9c626509bedf643443982cc13dbb8e210ec8face039
BLAKE2b-256 checksum
How to use checksums 		b618b8bdcf2fe11caae82ced9cacbfd436fdb660ff9c842dccee6aceb463807d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing? 		No
Uploaded via twine/4.0.1 CPython/3.10.8
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page