Programmable debugger
Go to file
Omar Sandoval ad23378977 Update elfutils and libkdumpfile in manylinux wheels
Use the latest version of elfutils (0.186) and libkdumpfile (0.4.1). We
can drop the elfutils patch since 0.186 has the fix (and we have our own
workaround), but we need a new patch to build libkdumpfile.

Signed-off-by: Omar Sandoval <osandov@osandov.com>
2021-12-08 15:13:09 -08:00
.github/workflows CI: add Python 3.10 2021-11-03 17:38:31 -07:00
docs libdrgn: debug_info: report userspace core dump debug info ourselves 2021-12-08 12:11:10 -08:00
drgn Update copyright headers to Meta 2021-11-21 15:59:44 -08:00
examples/linux Update copyright headers to Meta 2021-11-21 15:59:44 -08:00
libdrgn libdrgn: memory_reader: remove unnecessary include 2021-12-08 15:12:11 -08:00
scripts Update elfutils and libkdumpfile in manylinux wheels 2021-12-08 15:13:09 -08:00
tests libdrgn: fix handling of p_filesz < p_memsz in core dumps 2021-12-08 00:02:44 -08:00
tools Update copyright headers to Meta 2021-11-21 15:59:44 -08:00
vmtest Update copyright headers to Meta 2021-11-21 15:59:44 -08:00
_drgn.pyi Update copyright headers to Meta 2021-11-21 15:59:44 -08:00
.editorconfig editorconfig: Update styles for pyi and c files 2020-02-27 09:37:26 -08: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 Fix some cosmetic nits in Packit config and .gitignore 2021-10-29 13:19:32 -07:00
.readthedocs.yml docs: set required Sphinx version for Read the Docs 2021-08-17 15:01:14 -07:00
CONTRIBUTING.rst docs: expand and reorganize installation instructions 2021-11-03 16:18:22 -07:00
COPYING License under GPL-3.0 or later 2018-04-15 15:03:33 -07:00
MANIFEST.in add COPYING to sdist 2021-04-20 11:17:51 -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 README: add libtool to build dependencies for Debian and Arch 2021-12-02 02:01:46 -08:00
setup.py Update copyright headers to Meta 2021-11-21 15:59:44 -08:00
util.py Update copyright headers to Meta 2021-11-21 15:59:44 -08: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. It is also 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>`_.

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/RHEL/CentOS

  .. code-block:: console

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

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

* Debian/Ubuntu

  .. code-block:: console

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

* Arch Linux

  .. code-block:: console

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

Optionally, install `libkdumpfile <https://github.com/ptesarik/libkdumpfile>`_
if you want support for the `makedumpfile
<https://github.com/makedumpfile/makedumpfile>`_ compressed kernel core dump
format. ``libkdumpfile`` is currently only packaged on Fedora and EPEL. For
other distributions, you must install it manually.

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