drgn_tools.ini

# Copyright (c) 2025, Oracle and/or its affiliates.
# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/

[debuginfo]

##########################
## FINDER CONFIGURATION ##
##########################

# These configurations affect the behavior of the Oracle plugin and its debug
# info finders. They specify paths and how the finders behave. However, they do
# not control *which* finders get enabled or when.
#
# Paths here will be formatted using Python's str.format() function, with the
# following string keys available:
#
# - bits: 32 or 64 depending on the architecture of the kernel
# - rpm: the name of the debuginfo RPM for this kernel version
# - ol_version, olver: the "major version" of Oracle Linux for that kernel
# - arch: the architecture string from the kernel release string
# - uname: the kernel release string
# - vmcore_path: the original path of the core dump
#
# Further string keys can be defined using "expansions", see that section below.

# Controls the path where drgn-tools searches for DWARF debuginfo, and where it
# would extract the files from a debuginfo RPM. This path does not need to
# exist. If drgn-tools downloads or extracts debuginfo, it will create the
# directory automatically.
#
# vmlinux_repo = ~/vmlinux_repo/{bits}/{uname}

# Controls the path where drgn-tools searches for debuginfo RPMs on the system.
# This could be a remote filesystem mount, or possibly just a cache directory.
# If drgn-tools downloads an RPM, and RPM caching is enabled, then this is the
# path where the RPM is stored. Again, the path need not exist, but if
# drgn-tools downloads & caches an RPM, it will create the path.
#
# rpm_path_format = ~/vmlinux_repo/{bits}/rpms/{rpm}

# Controls the URL that drgn-tools will try to download DWARF debuginfo RPMs
# from. Multiple URLs can be specified, and they will be tried in order.
#
# urls = https://oss.oracle.com/ol{olver}/debuginfo/{rpm}

# Controls whether downloaded RPMs should be cached for later use.
#
# rpm_cache = false

#######################
## FINDER ENABLEMENT ##
#######################

# Unlike the above section, these configurations control whether or not each
# debug info finder is enabled for the "drgn" command. Please note that Corelens
# and drgn_tools.cli(DRGN) do not use these defaults: they set their own logic.
# These controls *only* impact the drgn command. By default, only the
# "ol-vmlinux-repo" finder is enabled for the drgn command.

# Controls whether debuginfo should be automatically extracted out of RPMs that
# are found locally (in the vmlinux_repo directory). In other words, set this to
# "true" so that the "ol-local-rpm" finder is enabled by default.
#
# enable_extract = false

# Controls whether RPMs should be automatically downloaded. In other words, set
# this to "true" so that the "ol-download" finder is enabled by default.
#
# enable_download = false

# Controls whether CTF is enabled. In other words, set this to "true" so that
# the "ctf" finder is enabled by default. Note that DWARF finders take
# precedence. So, if you have enable_extract and/or enable_download enabled,
# then drgn-tools will try to download/extract debuginfo prior to loading CTF,
# and it's likely that you won't actually end up using CTF. This is fine: CTF is
# less powerful than DWARF, but it's important to know.
#
# enable_ctf = false

# Disables all DWARF finders (including drgn's standard debug info finder).
# This is generally not that useful, but if you're trying to configure a system
# so that it only uses CTF, this could be useful. This disables ol-vmlinux-repo,
# ol-local-rpm, and ol-download, as well as drgn's "standard" finder.
#
# disable_dwarf = false

[extractions]

# Extractions are an uncommonly used feature, which add flexibility for
# constructing paths. The string configurations above, such as vmlinux_repo,
# rpm_path_format, and urls, each can specify an important path for finding
# debuginfo. They are able to use Python formatting strings, using pre-defined
# fields related to the kernel version and vmcore path.
#
# However, in some cases the path can't be determined just from the kernel
# version or vmcore_path. For example, one requirement might be storing the
# debuginfo in a subdirectory adjacent to the vmcore. For such a requirement,
# you could use an expansion to achieve it.
#
# Expansions define a new field, and they must be of the form:
#
#     new_field = old_field:default_value:regex
#
# Where:
#     old_field: the name of the field you're extracting text from
#     default_value: the value to use for the new_field if old_field doesn't
#       exist or the regex does not match
#     regex: a regular expression pattern. Group number 1 from this regex will
#       be used for the new_field value.
#
# For example, the following extracts the directory containing the vmcore to a
# new field named vmcore_dir. If for any reason the extraction could not work,
# we fall back to "/var/tmp/" for safety:
#
#     [extractions]
#     vmcore_dir = vmcore_path:/var/tmp/:^(.*/)[^/]+$
#
# With this, you can specify that debuginfo should be extracted adjacent to the
# vmcore, or even in the same directory:
#
#     vmlinux_repo = {vmcore_dir}/debuginfo
#     vmlinux_repo = {vmcore_dir}