Programmable debugger
Go to file
Omar Sandoval c911ccdd36 tests: build test kernel module with kernel.org compiler
Now we'll always get the same compiler that was used for the actual
kernel build. Also split this into its own runnable module, vmtest.kmod,
for testing and custom scripting.

Signed-off-by: Omar Sandoval <osandov@osandov.com>
2023-02-18 01:42:38 -08:00
.github/workflows CI: build vmtest kernels for all architectures 2023-02-16 17:58:14 -08:00
contrib contrib: vmstat.py: move implementation comment out of docstring 2023-02-03 11:44:04 -08:00
docs cli: Separate the main function from the REPL 2023-02-01 09:30:02 -08:00
drgn mm: introduce new helper function totalram_pages 2023-02-08 08:07:56 -08:00
libdrgn libdrgn: handle GNU Debug Fission attributes, forms, and opcodes 2023-02-08 13:25:45 -08:00
LICENSES Relicense drgn from GPLv3+ to LGPLv2.1+ 2022-11-01 17:05:16 -07:00
scripts scripts: Allow building just one Python release 2023-01-30 12:20:15 -08:00
tests mm: introduce new helper function totalram_pages 2023-02-08 08:07:56 -08:00
tools Relicense drgn from GPLv3+ to LGPLv2.1+ 2022-11-01 17:05:16 -07:00
vmtest tests: build test kernel module with kernel.org compiler 2023-02-18 01:42:38 -08:00
_drgn.pyi helpers: idr: Enable idr helpers to work with older kernel. 2023-01-23 17:32:17 -08:00
.editorconfig editorconfig: Update styles for pyi and c files 2020-02-27 09:37:26 -08:00
.flake8 pre-commit: add flake8 2022-05-17 15:26:41 -07:00
.git-blame-ignore-revs Add .git-blame-ignore-revs 2020-01-14 12:03:26 -08:00
.gitignore Fix some cosmetic nits in Packit config and .gitignore 2021-10-29 13:19:32 -07:00
.packit.yaml Revert "packit: temporarily work around examples directory" 2023-01-13 10:38:54 -08:00
.pre-commit-config.yaml pre-commit: Update isort version to 5.12.0 2023-01-30 10:24:41 -08:00
.readthedocs.yml docs: set required Sphinx version for Read the Docs 2021-08-17 15:01:14 -07:00
CONTRIBUTING.rst pre-commit: add flake8 2022-05-17 15:26:41 -07:00
COPYING Bring back COPYING 2022-11-02 22:57:40 -07:00
MANIFEST.in vmtest.kbuild: add patch for BTFIDS errors with newer pahole 2023-02-16 02:23:04 -08:00
pyproject.toml Format imports with isort 2020-08-20 16:55:07 -07:00
pytest.ini Tell pytest not to match classes/functions starting with "test" 2021-08-12 14:46:47 -07:00
README.rst Relicense drgn from GPLv3+ to LGPLv2.1+ 2022-11-01 17:05:16 -07:00
setup.py tests: build test kernel module with kernel.org compiler 2023-02-18 01:42:38 -08:00
util.py Relicense drgn from GPLv3+ to LGPLv2.1+ 2022-11-01 17:05:16 -07:00

drgn
====

.. image:: https://img.shields.io/pypi/v/drgn
    :target: https://pypi.org/project/drgn/
    :alt: PyPI

.. image:: https://github.com/osandov/drgn/workflows/CI/badge.svg
    :target: https://github.com/osandov/drgn/actions
    :alt: CI Status

.. 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
    :target: https://github.com/psf/black

.. start-introduction

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:

.. 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"

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
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>`_.

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.

.. end-introduction

Documentation can be found at `drgn.readthedocs.io
<https://drgn.readthedocs.io>`_.

.. start-installation

Installation
------------

Package Manager
^^^^^^^^^^^^^^^

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

.. image:: https://repology.org/badge/vertical-allrepos/drgn.svg
    :target: https://repology.org/project/drgn/versions
    :alt: Packaging Status

* Fedora >= 32

  .. code-block:: console

      $ sudo dnf install drgn

* RHEL/CentOS >= 8

  `Enable EPEL <https://docs.fedoraproject.org/en-US/epel/#_quickstart>`_. Then:

  .. code-block:: console

      $ sudo dnf install drgn

* Arch Linux

  Install the `drgn <https://aur.archlinux.org/packages/drgn/>`_ package from
  the `AUR <https://wiki.archlinux.org/title/Arch_User_Repository>`_.

* Debian >= 12 (Bookworm)

  .. code-block:: console

    $ sudo apt install python3-drgn

* openSUSE

  .. code-block:: console

      $ sudo zypper install python3-drgn

* 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

pip
^^^

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:

.. code-block:: console

    $ 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
^^^^^^^^^^^

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

* 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

  .. code-block:: console

      $ 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 <https://github.com/ptesarik/libkdumpfile>`_ from
  source if you want support for the makedumpfile format.

  Replace ``dnf`` with ``yum`` for RHEL/CentOS < 8.

* Debian/Ubuntu

  .. code-block:: console

      $ 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

  .. code-block:: console

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

  Optionally, install `libkdumpfile
  <https://aur.archlinux.org/packages/libkdumpfile/>`__ from the AUR or from
  source if you want support for the makedumpfile format.

* 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

Then, run:

.. code-block:: console

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

.. end-installation

See the `installation documentation
<https://drgn.readthedocs.io/en/latest/installation.html>`_ for more options.

Quick Start
-----------

.. start-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
<https://drgn.readthedocs.io/en/latest/getting_debugging_symbols.html>`_ for
whatever you are debugging.

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

.. code-block:: pycon

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

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'

.. end-quick-start

See the `user guide <https://drgn.readthedocs.io/en/latest/user_guide.html>`_
for more details and features.

License
-------

.. start-license

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

drgn is licensed under the `LGPLv2.1
<https://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html>`_ or later.

.. end-license