pycrash(1)

NAME

pycrash - a Linux kernel crash dump debugger written in Python

SYNOPSIS

pycrash [options] <path-to-vmlinux> <path-to-vmcore>

DESCRIPTION

The pycrash utility is a Linux kernel crash debugger written in Python. It improves upon the original crash tool by adding support for symbolic backtraces and in that it is easily extensible by the user using a rich python interface that offers semantic helpers for various subsystems.

In order to operate properly, full debuginfo is required for the kernel image and all modules in use. Without options specifying other paths, the following defaults are used for locating the debuginfo and modules:

Kernel debuginfo:

  • <path-to-vmlinux>.debug
  • ./vmlinux-<kernel-version>.debug
  • /usr/lib/debug/.build-id/<xx>/<build-id>.debug
  • /usr/lib/debug/<path-to-vmlinux>.debug
  • /usr/lib/debug/boot/vmlinux-<kernel-version>.debug
  • /usr/lib/debug/boot/vmlinux-<kernel-version>

Module path:

  • ./modules
  • /lib/modules/<kernel-version>

Module debuginfo path:

  • ./modules.debug
  • /usr/lib/debug/.build-id/xx/<build-id>.debug
  • /usr/lib/debug/lib/modules/<kernel-version>

The build-id and kernel-version fields are detected within the kernel and modules and cannot be overridden.

OPTIONS

Each of the following options may be specified multiple times.

-r <dir> | --root <dir>

Use the specified directory as the root for all file searches. When using properly configured .build-id symbolic links, this is the best method to use as the debuginfo will be loaded automatically via gdb without searching for filenames. If this is the only option specified, the defaults documented above will be used relative to each root.

-m <dir> | --modules <dir>

Use the specified directory to search for modules

-d <dir> | --modules-debuginfo <dir>

Use the specified directory to search for module debuginfo

-D <dir> | --vmlinux-debuginfo <dir>

Use the specified directory to search for vmlinux debuginfo

-b <dir> | --build-dir <dir>

Use the specified directory as the root for all file searches. This directory should be the root of a built kernel source tree. This is shorthand for -r <dir> -m . -d . -D . and will override preceding options.

DEBUGGING OPTIONS:

-v | --verbose

Enable verbose output for debugging the debugger

--debug

Enable even noisier output for debugging the debugger

--gdb

Run the embedded gdb underneath a separate gdb instance. This is useful for debugging issues in gdb that are seen while running crash-python.

--valgrind

Run the embedded gdb underneath valgrind. This is useful for debugging memory leaks in gdb patches.

EXIT STATUS

pycrash returns a zero exit status if it succeeds. Non zero is returned in case of failure.

AVAILABILITY

pycrash is part of crash-python. Please refer to the GitHub repository at https://github.com/jeffmahoney/crash-python for more information.

SEE ALSO

gdb(1) libkdumpfile(7)