Programmable debugger
Go to file
Omar Sandoval 6cc41dbcf8 vmtest.vm: support running with root directory different from the host
This will be useful for testing different architectures (e.g., by
creating a rootfs with debootstrap) or different userspace environments.
For example, we can test busybox with something like:

  mkdir busyboxroot busyboxroot/bin busyboxroot/tmp
  cp "$(which busybox)" busyboxroot/bin
  busyboxroot/bin/busybox --install busyboxroot/bin
  python3 -Bm vmtest.vm -k '*' -r busyboxroot

Signed-off-by: Omar Sandoval <osandov@osandov.com>
2022-10-11 16:13:10 -07:00
.github/workflows vmtest: don't use BusyBox 2022-08-01 11:23:26 -07:00
docs libdrgn: linux_kernel: always use module list from core 2022-09-12 16:11:59 -07:00
drgn Fix vmcore stack traces on Linux < 4.9 or >= 5.16 and add drgn.helpers.linux.task_cpu() 2022-10-03 16:21:12 -07:00
examples/linux Move top-level drgn.helpers helpers into drgn.helpers.common submodules 2022-09-14 17:08:39 -07:00
libdrgn libdrgn: rename drgn_debug_info_module to drgn_module 2022-10-05 16:52:46 -07:00
scripts drgn.helpers.linux.mm: add compound page helpers 2022-09-09 15:54:43 -07:00
tests tests: enable MM tests on AArch64 2022-10-11 16:01:13 -07:00
tools Move top-level drgn.helpers helpers into drgn.helpers.common submodules 2022-09-14 17:08:39 -07:00
vmtest vmtest.vm: support running with root directory different from the host 2022-10-11 16:13:10 -07:00
_drgn.pyi Fix vmcore stack traces on Linux < 4.9 or >= 5.16 and add drgn.helpers.linux.task_cpu() 2022-10-03 16:21:12 -07: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 packit: disable rpmautospec 2022-08-25 15:35:30 -07:00
.pre-commit-config.yaml pre-commit: add flake8 2022-05-17 15:26:41 -07: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 License under GPL-3.0 or later 2018-04-15 15:03:33 -07:00
MANIFEST.in pre-commit: add flake8 2022-05-17 15:26:41 -07: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 docs: fix "Duplicate explicit target name" Sphinx warning 2022-08-25 13:26:36 -07:00
setup.py vmtest.vm: support running with root directory different from the host 2022-10-11 16:13:10 -07:00
util.py vmtest: get SYS_kexec_file_load from util.SYS 2022-10-11 16:08:20 -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.

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

* openSUSE

  .. code-block:: console

      $ sudo zypper 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 `GPLv3
<https://www.gnu.org/licenses/gpl-3.0.en.html>`_ or later.

.. end-license