Programmable debugger
Go to file
Omar Sandoval b8aa2dcfc5 drgndoc: format None, True, and False as roles
Signed-off-by: Omar Sandoval <osandov@osandov.com>
2020-08-11 22:51:56 -07:00
docs drgndoc: format None, True, and False as roles 2020-08-11 22:51:56 -07:00
drgn helpers: add kaslr_offset() and move pgtable_l5_enabled() 2020-07-27 17:00:16 -07:00
examples/linux Update copyright headers to Facebook and add missing headers 2020-05-15 15:13:02 -07:00
libdrgn drgn 0.0.7 2020-07-27 23:32:32 -07:00
scripts Update copyright headers to Facebook and add missing headers 2020-05-15 15:13:02 -07:00
tests helpers: add kaslr_offset() and move pgtable_l5_enabled() 2020-07-27 17:00:16 -07:00
tools Update copyright headers to Facebook and add missing headers 2020-05-15 15:13:02 -07:00
vmtest vmtest: check that downloaded file is not truncated 2020-07-27 12:19:46 -07:00
_drgn.pyi helpers: add kaslr_offset() and move pgtable_l5_enabled() 2020-07-27 17:00:16 -07: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 Add scripts/cscope.sh 2020-04-27 17:07:15 -07:00
.readthedocs.yml Add type hint stubs and generate documentation from them 2020-02-25 13:39:06 -08:00
.travis.yml travis: fix spurious VM crashes 2020-08-04 16:36:09 -07:00
CONTRIBUTING.rst Add CONTRIBUTING.rst 2020-07-07 17:44:02 -07:00
COPYING License under GPL-3.0 or later 2018-04-15 15:03:33 -07:00
MANIFEST.in Add examples and tools to source distribution 2020-04-27 16:53:14 -07:00
README.rst README: use code-block instead of highlight 2020-07-27 23:28:23 -07:00
setup.py setup.py: import setuptools before distutils 2020-07-18 01:41:12 -07:00
util.py Update copyright headers to Facebook and add missing headers 2020-05-15 15:13:02 -07:00

drgn
====

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

.. image:: https://travis-ci.org/osandov/drgn.svg?branch=master
    :target: https://travis-ci.org/osandov/drgn
    :alt: Build 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/master/tools>`_.

drgn was developed for debugging the Linux kernel (as an alternative to the
`crash <http://people.redhat.com/anderson/>`_ 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>`_.

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

.. start-install-dependencies

Install dependencies:

Arch Linux:

.. code-block:: console

    $ sudo pacman -S --needed autoconf automake bison bzip2 flex gawk gcc libtool make pkgconf python python-setuptools xz zlib

Debian/Ubuntu:

.. code-block:: console

    $ sudo apt-get install autoconf automake bison flex gawk gcc libbz2-dev liblzma-dev libtool make pkgconf python3 python3-dev python3-setuptools zlib1g-dev

Note that Debian Stretch, Ubuntu Trusty, and Ubuntu Xenial (and older) ship
Python versions which are too old. Python 3.6 or newer must be installed
manually.

Fedora:

.. code-block:: console

    $ sudo dnf install autoconf automake bison bzip2-devel flex gawk gcc libtool make pkgconf python3 python3-devel python3-setuptools xz-devel zlib-devel

Optionally, install:

* `libkdumpfile <https://github.com/ptesarik/libkdumpfile>`_ if you want
  support for kdump-compressed kernel core dumps

.. end-install-dependencies

Then, run:

.. code-block:: console

    $ sudo pip3 install drgn

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``. The program
must have debugging symbols available.

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

.. code-block:: pycon

    $ sudo drgn
    >>> prog['init_task'].comm
    (char [16])"swapper/0"
    >>> d_path(fget(find_task(prog, 1), 0).f_path.address_of_())
    b'/dev/null'
    >>> max(task.stime for task in for_each_task(prog))
    (u64)4192109975952
    >>> sum(disk.gendisk.part0.nr_sects for disk in for_each_disk(prog))
    (sector_t)999705952

.. end-quick-start

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

License
-------

.. start-license

Copyright (c) Facebook, Inc. and its affiliates.

drgn is licensed under the `GPLv3
<https://www.gnu.org/licenses/gpl-3.0.en.html>`_ or later.

.. end-license