2019-04-04 09:27:23 +01:00
|
|
|
drgn
|
|
|
|
====
|
|
|
|
|
2020-01-23 23:14:58 +00:00
|
|
|
.. image:: https://img.shields.io/pypi/v/drgn
|
|
|
|
:target: https://pypi.org/project/drgn/
|
|
|
|
:alt: PyPI
|
|
|
|
|
2020-12-31 10:26:15 +00:00
|
|
|
.. image:: https://github.com/osandov/drgn/workflows/CI/badge.svg
|
|
|
|
:target: https://github.com/osandov/drgn/actions
|
|
|
|
:alt: CI Status
|
2019-04-11 21:16:48 +01:00
|
|
|
|
2019-04-04 09:27:23 +01:00
|
|
|
.. image:: https://readthedocs.org/projects/drgn/badge/?version=latest
|
|
|
|
:target: https://drgn.readthedocs.io/en/latest/?badge=latest
|
|
|
|
:alt: Documentation Status
|
|
|
|
|
|
|
|
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
|
2019-08-02 08:00:59 +01:00
|
|
|
:target: https://github.com/psf/black
|
2020-01-14 19:43:58 +00:00
|
|
|
|
2019-04-04 09:27:23 +01:00
|
|
|
.. start-introduction
|
|
|
|
|
2020-01-11 00:38:51 +00:00
|
|
|
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:
|
2019-04-04 09:27:23 +01:00
|
|
|
|
|
|
|
.. code-block:: pycon
|
|
|
|
|
|
|
|
>>> 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"
|
|
|
|
|
2020-01-11 00:38:51 +00:00
|
|
|
Although other debuggers like `GDB <https://www.gnu.org/software/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
|
2022-08-19 09:21:32 +01:00
|
|
|
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
|
|
|
|
<https://github.com/osandov/drgn/tree/main/tools>`_.
|
2020-01-11 00:38:51 +00:00
|
|
|
|
2021-11-22 00:01:39 +00:00
|
|
|
drgn was developed at `Meta <https://opensource.fb.com/>`_ for debugging the
|
|
|
|
Linux kernel (as an alternative to the `crash
|
|
|
|
<https://crash-utility.github.io/>`_ utility), but it can also debug userspace
|
|
|
|
programs written in C. C++ support is in progress.
|
2019-04-04 09:27:23 +01:00
|
|
|
|
|
|
|
.. end-introduction
|
|
|
|
|
|
|
|
Documentation can be found at `drgn.readthedocs.io
|
|
|
|
<https://drgn.readthedocs.io>`_.
|
|
|
|
|
2021-11-03 23:05:18 +00:00
|
|
|
.. start-installation
|
|
|
|
|
2019-04-04 09:27:23 +01:00
|
|
|
Installation
|
|
|
|
------------
|
|
|
|
|
2021-11-03 23:05:18 +00:00
|
|
|
Package Manager
|
|
|
|
^^^^^^^^^^^^^^^
|
2019-04-04 09:27:23 +01:00
|
|
|
|
2021-11-03 23:05:18 +00:00
|
|
|
drgn can be installed using the package manager on some Linux distributions.
|
2019-09-04 22:40:47 +01:00
|
|
|
|
2022-10-28 19:38:45 +01:00
|
|
|
.. image:: https://repology.org/badge/vertical-allrepos/drgn.svg
|
|
|
|
:target: https://repology.org/project/drgn/versions
|
|
|
|
:alt: Packaging Status
|
|
|
|
|
2021-11-03 23:05:18 +00:00
|
|
|
* Fedora >= 32
|
2020-07-28 07:28:23 +01:00
|
|
|
|
2021-11-03 23:05:18 +00:00
|
|
|
.. code-block:: console
|
2019-09-04 22:40:47 +01:00
|
|
|
|
2021-11-03 23:05:18 +00:00
|
|
|
$ sudo dnf install drgn
|
2019-09-04 22:40:47 +01:00
|
|
|
|
2021-11-03 23:05:18 +00:00
|
|
|
* RHEL/CentOS >= 8
|
2020-07-28 07:28:23 +01:00
|
|
|
|
2021-11-03 23:05:18 +00:00
|
|
|
`Enable EPEL <https://docs.fedoraproject.org/en-US/epel/#_quickstart>`_. Then:
|
|
|
|
|
|
|
|
.. code-block:: console
|
|
|
|
|
|
|
|
$ sudo dnf install drgn
|
|
|
|
|
|
|
|
* Arch Linux
|
2019-09-04 22:40:47 +01:00
|
|
|
|
2021-11-03 23:05:18 +00:00
|
|
|
Install the `drgn <https://aur.archlinux.org/packages/drgn/>`_ package from
|
|
|
|
the `AUR <https://wiki.archlinux.org/title/Arch_User_Repository>`_.
|
2019-09-04 22:40:47 +01:00
|
|
|
|
2022-10-28 19:38:45 +01:00
|
|
|
* Debian >= 12 (Bookworm)
|
|
|
|
|
|
|
|
.. code-block:: console
|
|
|
|
|
|
|
|
$ sudo apt install python3-drgn
|
|
|
|
|
2022-08-17 07:29:35 +01:00
|
|
|
* openSUSE
|
|
|
|
|
|
|
|
.. code-block:: console
|
|
|
|
|
|
|
|
$ sudo zypper install python3-drgn
|
|
|
|
|
2022-10-28 19:38:45 +01:00
|
|
|
* Ubuntu
|
|
|
|
|
|
|
|
Enable the `michel-slm/kernel-utils PPA <https://launchpad.net/~michel-slm/+archive/ubuntu/kernel-utils>`_.
|
|
|
|
Then:
|
|
|
|
|
|
|
|
.. code-block:: console
|
|
|
|
|
|
|
|
$ sudo apt install python3-drgn
|
|
|
|
|
2021-11-03 23:05:18 +00:00
|
|
|
pip
|
|
|
|
^^^
|
2019-09-04 22:40:47 +01:00
|
|
|
|
2021-11-03 23:05:18 +00:00
|
|
|
If your Linux distribution doesn't package the latest release of drgn, you can
|
|
|
|
install it with `pip <https://pip.pypa.io/>`_.
|
|
|
|
|
|
|
|
First, `install pip
|
|
|
|
<https://packaging.python.org/guides/installing-using-linux-tools/#installing-pip-setuptools-wheel-with-linux-package-managers>`_.
|
|
|
|
Then, run:
|
2020-07-28 07:28:23 +01:00
|
|
|
|
|
|
|
.. code-block:: console
|
2019-09-04 22:40:47 +01:00
|
|
|
|
2021-11-03 23:05:18 +00:00
|
|
|
$ 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
|
|
|
|
<#from-source>`_ 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
|
|
|
|
^^^^^^^^^^^
|
2019-04-04 09:27:23 +01:00
|
|
|
|
2021-11-03 23:05:18 +00:00
|
|
|
To get the development version of drgn, you will need to build it from source.
|
|
|
|
First, install dependencies:
|
2019-08-02 08:00:59 +01:00
|
|
|
|
2022-08-19 09:26:50 +01:00
|
|
|
* Fedora
|
|
|
|
|
|
|
|
.. code-block:: console
|
|
|
|
|
|
|
|
$ sudo dnf install autoconf automake elfutils-devel gcc git libkdumpfile-devel libtool make pkgconf python3 python3-devel python3-pip python3-setuptools
|
|
|
|
|
|
|
|
* RHEL/CentOS
|
2019-08-02 08:00:59 +01:00
|
|
|
|
2021-11-03 23:05:18 +00:00
|
|
|
.. code-block:: console
|
|
|
|
|
2022-03-03 00:09:00 +00:00
|
|
|
$ sudo dnf install autoconf automake elfutils-devel gcc git libtool make pkgconf python3 python3-devel python3-pip python3-setuptools
|
2021-11-03 23:05:18 +00:00
|
|
|
|
2022-08-19 09:26:50 +01:00
|
|
|
Optionally, install ``libkdumpfile-devel`` from EPEL on RHEL/CentOS >= 8 or
|
|
|
|
install `libkdumpfile <https://github.com/ptesarik/libkdumpfile>`_ from
|
|
|
|
source if you want support for the makedumpfile format.
|
|
|
|
|
2021-11-03 23:05:18 +00:00
|
|
|
Replace ``dnf`` with ``yum`` for RHEL/CentOS < 8.
|
|
|
|
|
|
|
|
* Debian/Ubuntu
|
|
|
|
|
|
|
|
.. code-block:: console
|
|
|
|
|
2022-03-03 00:09:00 +00:00
|
|
|
$ 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
|
2021-11-03 23:05:18 +00:00
|
|
|
|
2022-08-19 09:26:50 +01:00
|
|
|
Optionally, install libkdumpfile from source if you want support for the
|
|
|
|
makedumpfile format.
|
|
|
|
|
2021-11-03 23:05:18 +00:00
|
|
|
* Arch Linux
|
|
|
|
|
|
|
|
.. code-block:: console
|
|
|
|
|
2022-03-03 00:09:00 +00:00
|
|
|
$ sudo pacman -S --needed autoconf automake gcc git libelf libtool make pkgconf python python-pip python-setuptools
|
2021-11-03 23:05:18 +00:00
|
|
|
|
2022-08-17 07:29:35 +01:00
|
|
|
Optionally, install `libkdumpfile
|
2022-08-25 21:26:36 +01:00
|
|
|
<https://aur.archlinux.org/packages/libkdumpfile/>`__ from the AUR or from
|
2022-08-19 09:26:50 +01:00
|
|
|
source if you want support for the makedumpfile format.
|
2022-08-17 07:29:35 +01:00
|
|
|
|
|
|
|
* openSUSE
|
|
|
|
|
|
|
|
.. code-block:: console
|
|
|
|
|
|
|
|
$ sudo zypper install autoconf automake gcc git libdw-devel libelf-devel libkdumpfile-devel libtool make pkgconf python3 python3-devel python3-pip python3-setuptools
|
2019-09-04 22:40:47 +01:00
|
|
|
|
2020-07-28 07:28:23 +01:00
|
|
|
Then, run:
|
|
|
|
|
|
|
|
.. code-block:: console
|
2019-04-04 09:27:23 +01:00
|
|
|
|
2021-11-03 23:05:18 +00:00
|
|
|
$ git clone https://github.com/osandov/drgn.git
|
|
|
|
$ cd drgn
|
|
|
|
$ python3 setup.py build
|
|
|
|
$ sudo python3 setup.py install
|
|
|
|
|
|
|
|
.. end-installation
|
2019-04-04 09:27:23 +01:00
|
|
|
|
|
|
|
See the `installation documentation
|
2020-01-23 23:14:58 +00:00
|
|
|
<https://drgn.readthedocs.io/en/latest/installation.html>`_ for more options.
|
2019-04-04 09:27:23 +01:00
|
|
|
|
|
|
|
Quick Start
|
|
|
|
-----------
|
|
|
|
|
|
|
|
.. start-quick-start
|
|
|
|
|
2019-06-28 22:04:15 +01:00
|
|
|
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
|
2021-11-03 00:48:36 +00:00
|
|
|
kernel vmcore or a userspace core dump), run ``drgn -c $PATH``. Make sure to
|
|
|
|
`install debugging symbols
|
|
|
|
<https://drgn.readthedocs.io/en/latest/getting_debugging_symbols.html>`_ for
|
|
|
|
whatever you are debugging.
|
2019-04-04 09:27:23 +01:00
|
|
|
|
2021-07-31 20:16:38 +01:00
|
|
|
Then, you can access variables in the program with ``prog['name']`` and access
|
|
|
|
structure members with ``.``:
|
2019-04-04 09:27:23 +01:00
|
|
|
|
|
|
|
.. code-block:: pycon
|
|
|
|
|
2019-06-28 22:04:15 +01:00
|
|
|
$ sudo drgn
|
2019-04-04 09:27:23 +01:00
|
|
|
>>> prog['init_task'].comm
|
|
|
|
(char [16])"swapper/0"
|
2021-07-31 20:16:38 +01:00
|
|
|
|
|
|
|
You can use various predefined helpers:
|
|
|
|
|
|
|
|
.. code-block:: pycon
|
|
|
|
|
|
|
|
>>> 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']``:
|
|
|
|
|
|
|
|
.. code-block:: pycon
|
|
|
|
|
|
|
|
>>> 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'
|
2019-04-04 09:27:23 +01:00
|
|
|
|
|
|
|
.. end-quick-start
|
|
|
|
|
|
|
|
See the `user guide <https://drgn.readthedocs.io/en/latest/user_guide.html>`_
|
2021-07-31 20:16:38 +01:00
|
|
|
for more details and features.
|
2019-04-04 09:27:23 +01:00
|
|
|
|
|
|
|
License
|
|
|
|
-------
|
|
|
|
|
|
|
|
.. start-license
|
|
|
|
|
2021-11-21 23:59:44 +00:00
|
|
|
Copyright (c) Meta Platforms, Inc. and affiliates.
|
2019-04-04 09:27:23 +01:00
|
|
|
|
|
|
|
drgn is licensed under the `GPLv3
|
|
|
|
<https://www.gnu.org/licenses/gpl-3.0.en.html>`_ or later.
|
|
|
|
|
|
|
|
.. end-license
|