|
Packit Service |
97d2fb |
'\"! tbl | nroff \-man
|
|
Packit Service |
97d2fb |
'\" t macro stdmacro
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.de SAMPLE
|
|
Packit Service |
97d2fb |
.br
|
|
Packit Service |
97d2fb |
.RS 0
|
|
Packit Service |
97d2fb |
.nf
|
|
Packit Service |
97d2fb |
.nh
|
|
Packit Service |
97d2fb |
..
|
|
Packit Service |
97d2fb |
.de ESAMPLE
|
|
Packit Service |
97d2fb |
.hy
|
|
Packit Service |
97d2fb |
.fi
|
|
Packit Service |
97d2fb |
.RE
|
|
Packit Service |
97d2fb |
..
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.TH DEBUGINFOD 8
|
|
Packit Service |
97d2fb |
.SH NAME
|
|
Packit Service |
97d2fb |
debuginfod \- debuginfo-related http file-server daemon
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.SH SYNOPSIS
|
|
Packit Service |
97d2fb |
.B debuginfod
|
|
Packit Service |
97d2fb |
[\fIOPTION\fP]... [\fIPATH\fP]...
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.SH DESCRIPTION
|
|
Packit Service |
97d2fb |
\fBdebuginfod\fP serves debuginfo-related artifacts over HTTP. It
|
|
Packit Service |
97d2fb |
periodically scans a set of directories for ELF/DWARF files and their
|
|
Packit Service |
97d2fb |
associated source code, as well as archive files containing the above, to
|
|
Packit Service |
97d2fb |
build an index by their buildid. This index is used when remote
|
|
Packit Service |
97d2fb |
clients use the HTTP webapi, to fetch these files by the same buildid.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
If a debuginfod cannot service a given buildid artifact request
|
|
Packit Service |
97d2fb |
itself, and it is configured with information about upstream
|
|
Packit Service |
97d2fb |
debuginfod servers, it queries them for the same information, just as
|
|
Packit Service |
97d2fb |
\fBdebuginfod-find\fP would. If successful, it locally caches then
|
|
Packit Service |
97d2fb |
relays the file content to the original requester.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
Indexing the given PATHs proceeds using multiple threads. One thread
|
|
Packit Service |
97d2fb |
periodically traverses all the given PATHs logically or physically
|
|
Packit Service |
97d2fb |
(see the \fB\-L\fP option). Duplicate PATHs are ignored. You may use
|
|
Packit Service |
97d2fb |
a file name for a PATH, but source code indexing may be incomplete;
|
|
Packit Service |
97d2fb |
prefer using a directory that contains the binaries. The traversal
|
|
Packit Service |
97d2fb |
thread enumerates all matching files (see the \fB\-I\fP and \fB\-X\fP
|
|
Packit Service |
97d2fb |
options) into a work queue. A collection of scanner threads (see the
|
|
Packit Service |
97d2fb |
\fB\-c\fP option) wait at the work queue to analyze files in parallel.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
If the \fB\-F\fP option is given, each file is scanned as an ELF/DWARF
|
|
Packit Service |
97d2fb |
file. Source files are matched with DWARF files based on the
|
|
Packit Service |
97d2fb |
AT_comp_dir (compilation directory) attributes inside it. Caution:
|
|
Packit Service |
97d2fb |
source files listed in the DWARF may be a path \fIanywhere\fP in the
|
|
Packit Service |
97d2fb |
file system, and debuginfod will readily serve their content on
|
|
Packit Service |
97d2fb |
demand. (Imagine a doctored DWARF file that lists \fI/etc/passwd\fP
|
|
Packit Service |
97d2fb |
as a source file.) If this is a concern, audit your binaries with
|
|
Packit Service |
97d2fb |
tools such as:
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.SAMPLE
|
|
Packit Service |
97d2fb |
% eu-readelf -wline BINARY | sed -n '/^Directory.table/,/^File.name.table/p'
|
|
Packit Service |
97d2fb |
or
|
|
Packit Service |
97d2fb |
% eu-readelf -wline BINARY | sed -n '/^Directory.table/,/^Line.number/p'
|
|
Packit Service |
97d2fb |
or even use debuginfod itself:
|
|
Packit Service |
97d2fb |
% debuginfod -vvv -d :memory: -F BINARY 2>&1 | grep 'recorded.*source'
|
|
Packit Service |
97d2fb |
^C
|
|
Packit Service |
97d2fb |
.ESAMPLE
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
If any of the \fB\-R\fP, \fB-U\fP, or \fB-Z\fP options is given, each
|
|
Packit Service |
97d2fb |
file is scanned as an archive file that may contain ELF/DWARF/source
|
|
Packit Service |
97d2fb |
files. Archive files are recognized by extension. If \-R is given,
|
|
Packit Service |
97d2fb |
".rpm" files are scanned; if \-D is given, ".deb" and ".ddeb" files
|
|
Packit Service |
97d2fb |
are scanned; if \-Z is given, the listed extensions are scanned.
|
|
Packit Service |
97d2fb |
Because of complications such as DWZ-compressed debuginfo, may require
|
|
Packit Service |
97d2fb |
\fItwo\fP traversal passes to identify all source code. Source files
|
|
Packit Service |
97d2fb |
for RPMs are only served from other RPMs, so the caution for \-F does
|
|
Packit Service |
97d2fb |
not apply. Note that due to Debian/Ubuntu packaging policies &
|
|
Packit Service |
97d2fb |
mechanisms, debuginfod cannot resolve source files for DEB/DDEB at
|
|
Packit Service |
97d2fb |
all.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
If no PATH is listed, or none of the scanning options is given, then
|
|
Packit Service |
97d2fb |
\fBdebuginfod\fP will simply serve content that it accumulated into
|
|
Packit Service |
97d2fb |
its index in all previous runs, and federate to any upstream
|
|
Packit Service |
97d2fb |
debuginfod servers.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.SH OPTIONS
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.TP
|
|
Packit Service |
97d2fb |
.B "\-F"
|
|
Packit Service |
97d2fb |
Activate ELF/DWARF file scanning. The default is off.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.TP
|
|
Packit Service |
97d2fb |
.B "\-Z EXT" "\-Z EXT=CMD"
|
|
Packit Service |
97d2fb |
Activate an additional pattern in archive scanning. Files with name
|
|
Packit Service |
97d2fb |
extension EXT (include the dot) will be processed. If CMD is given,
|
|
Packit Service |
97d2fb |
it is invoked with the file name added to its argument list, and
|
|
Packit Service |
97d2fb |
should produce a common archive on its standard output. Otherwise,
|
|
Packit Service |
97d2fb |
the file is read as if CMD were "cat". Since debuginfod internally
|
|
Packit Service |
97d2fb |
uses \fBlibarchive\fP to read archive files, it can accept a wide
|
|
Packit Service |
97d2fb |
range of archive formats and compression modes. The default is no
|
|
Packit Service |
97d2fb |
additional patterns. This option may be repeated.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.TP
|
|
Packit Service |
97d2fb |
.B "\-R"
|
|
Packit Service |
97d2fb |
Activate RPM patterns in archive scanning. The default is off.
|
|
Packit Service |
97d2fb |
Equivalent to \fB\%\-Z\~.rpm=cat\fP, since libarchive can natively
|
|
Packit Service |
97d2fb |
process RPM archives. If your version of libarchive is much older
|
|
Packit Service |
97d2fb |
than 2020, be aware that some distributions have switched to an
|
|
Packit Service |
97d2fb |
incompatible zstd compression for their payload. You may experiment
|
|
Packit Service |
97d2fb |
with \fB\%\-Z\ .rpm='(rpm2cpio|zstdcat)<'\fP instead of \fB\-R\fP.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.TP
|
|
Packit Service |
97d2fb |
.B "\-U"
|
|
Packit Service |
97d2fb |
Activate DEB/DDEB patterns in archive scanning. The default is off.
|
|
Packit Service |
97d2fb |
Equivalent to \fB\%\-Z\ .deb='dpkg-deb\ \-\-fsys\-tarfile\fP'
|
|
Packit Service |
97d2fb |
\fB\%\-Z\ .ddeb='dpkg-deb\ \-\-fsys\-tarfile'\fP.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.TP
|
|
Packit Service |
97d2fb |
.B "\-d FILE" "\-\-database=FILE"
|
|
Packit Service |
97d2fb |
Set the path of the sqlite database used to store the index. This
|
|
Packit Service |
97d2fb |
file is disposable in the sense that a later rescan will repopulate
|
|
Packit Service |
97d2fb |
data. It will contain absolute file path names, so it may not be
|
|
Packit Service |
97d2fb |
portable across machines. It may be frequently read/written, so it
|
|
Packit Service |
97d2fb |
should be on a fast filesytem. It should not be shared across
|
|
Packit Service |
97d2fb |
machines or users, to maximize sqlite locking performance. The
|
|
Packit Service |
97d2fb |
default database file is \%$HOME/.debuginfod.sqlite.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.TP
|
|
Packit Service |
97d2fb |
.B "\-D SQL" "\-\-ddl=SQL"
|
|
Packit Service |
97d2fb |
Execute given sqlite statement after the database is opened and
|
|
Packit Service |
97d2fb |
initialized as extra DDL (SQL data definition language). This may be
|
|
Packit Service |
97d2fb |
useful to tune performance-related pragmas or indexes. May be
|
|
Packit Service |
97d2fb |
repeated. The default is nothing extra.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.TP
|
|
Packit Service |
97d2fb |
.B "\-p NUM" "\-\-port=NUM"
|
|
Packit Service |
97d2fb |
Set the TCP port number (0 < NUM < 65536) on which debuginfod should
|
|
Packit Service |
97d2fb |
listen, to service HTTP requests. Both IPv4 and IPV6 sockets are
|
|
Packit Service |
97d2fb |
opened, if possible. The webapi is documented below. The default
|
|
Packit Service |
97d2fb |
port number is 8002.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.TP
|
|
Packit Service |
97d2fb |
.B "\-I REGEX" "\-\-include=REGEX" "\-X REGEX" "\-\-exclude=REGEX"
|
|
Packit Service |
97d2fb |
Govern the inclusion and exclusion of file names under the search
|
|
Packit Service |
97d2fb |
paths. The regular expressions are interpreted as unanchored POSIX
|
|
Packit Service |
97d2fb |
extended REs, thus may include alternation. They are evaluated
|
|
Packit Service |
97d2fb |
against the full path of each file, based on its \fBrealpath(3)\fP
|
|
Packit Service |
97d2fb |
canonicalization. By default, all files are included and none are
|
|
Packit Service |
97d2fb |
excluded. A file that matches both include and exclude REGEX is
|
|
Packit Service |
97d2fb |
excluded. (The \fIcontents\fP of archive files are not subject to
|
|
Packit Service |
97d2fb |
inclusion or exclusion filtering: they are all processed.) Only the
|
|
Packit Service |
97d2fb |
last of each type of regular expression given is used.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.TP
|
|
Packit Service |
97d2fb |
.B "\-t SECONDS" "\-\-rescan\-time=SECONDS"
|
|
Packit Service |
97d2fb |
Set the rescan time for the file and archive directories. This is the
|
|
Packit Service |
97d2fb |
amount of time the traversal thread will wait after finishing a scan,
|
|
Packit Service |
97d2fb |
before doing it again. A rescan for unchanged files is fast (because
|
|
Packit Service |
97d2fb |
the index also stores the file mtimes). A time of zero is acceptable,
|
|
Packit Service |
97d2fb |
and means that only one initial scan should performed. The default
|
|
Packit Service |
97d2fb |
rescan time is 300 seconds. Receiving a SIGUSR1 signal triggers a new
|
|
Packit Service |
97d2fb |
scan, independent of the rescan time (including if it was zero),
|
|
Packit Service |
97d2fb |
interrupting a groom pass (if any).
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.TP
|
|
Packit Service |
97d2fb |
.B "\-g SECONDS" "\-\-groom\-time=SECONDS"
|
|
Packit Service |
97d2fb |
Set the groom time for the index database. This is the amount of time
|
|
Packit Service |
97d2fb |
the grooming thread will wait after finishing a grooming pass before
|
|
Packit Service |
97d2fb |
doing it again. A groom operation quickly rescans all previously
|
|
Packit Service |
97d2fb |
scanned files, only to see if they are still present and current, so
|
|
Packit Service |
97d2fb |
it can deindex obsolete files. See also the \fIDATA MANAGEMENT\fP
|
|
Packit Service |
97d2fb |
section. The default groom time is 86400 seconds (1 day). A time of
|
|
Packit Service |
97d2fb |
zero is acceptable, and means that only one initial groom should be
|
|
Packit Service |
97d2fb |
performed. Receiving a SIGUSR2 signal triggers a new grooming pass,
|
|
Packit Service |
97d2fb |
independent of the groom time (including if it was zero), interrupting
|
|
Packit Service |
97d2fb |
a rescan pass (if any)..
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.TP
|
|
Packit Service |
97d2fb |
.B "\-G"
|
|
Packit Service |
97d2fb |
Run an extraordinary maximal-grooming pass at debuginfod startup.
|
|
Packit Service |
97d2fb |
This pass can take considerable time, because it tries to remove any
|
|
Packit Service |
97d2fb |
debuginfo-unrelated content from the archive-related parts of the index.
|
|
Packit Service |
97d2fb |
It should not be run if any recent archive-related indexing operations
|
|
Packit Service |
97d2fb |
were aborted early. It can take considerable space, because it
|
|
Packit Service |
97d2fb |
finishes up with an sqlite "vacuum" operation, which repacks the
|
|
Packit Service |
97d2fb |
database file by triplicating it temporarily. The default is not to
|
|
Packit Service |
97d2fb |
do maximal-grooming. See also the \fIDATA MANAGEMENT\fP section.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.TP
|
|
Packit Service |
97d2fb |
.B "\-c NUM" "\-\-concurrency=NUM"
|
|
Packit Service |
97d2fb |
Set the concurrency limit for the scanning queue threads, which work
|
|
Packit Service |
97d2fb |
together to process archives & files located by the traversal thread.
|
|
Packit Service |
97d2fb |
This important for controlling CPU-intensive operations like parsing
|
|
Packit Service |
97d2fb |
an ELF file and especially decompressing archives. The default is the
|
|
Packit Service |
97d2fb |
number of processors on the system; the minimum is 1.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.TP
|
|
Packit Service |
97d2fb |
.B "\-L"
|
|
Packit Service |
97d2fb |
Traverse symbolic links encountered during traversal of the PATHs,
|
|
Packit Service |
97d2fb |
including across devices - as in \fIfind\ -L\fP. The default is to
|
|
Packit Service |
97d2fb |
traverse the physical directory structure only, stay on the same
|
|
Packit Service |
97d2fb |
device, and ignore symlinks - as in \fIfind\ -P\ -xdev\fP. Caution: a
|
|
Packit Service |
97d2fb |
loops in the symbolic directory tree might lead to \fIinfinite
|
|
Packit Service |
97d2fb |
traversal\fP.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.TP
|
|
Packit Service |
97d2fb |
.B "\-\-fdcache\-fds=NUM" "\-\-fdcache\-mbs=MB" "\-\-fdcache\-prefetch=NUM2"
|
|
Packit Service |
97d2fb |
Configure limits on a cache that keeps recently extracted files from
|
|
Packit Service |
97d2fb |
archives. Up to NUM requested files and up to a total of MB megabytes
|
|
Packit Service |
97d2fb |
will be kept extracted, in order to avoid having to decompress their
|
|
Packit Service |
97d2fb |
archives over and over again. In addition, up to NUM2 other files
|
|
Packit Service |
97d2fb |
from an archive may be prefetched into the cache before they are even
|
|
Packit Service |
97d2fb |
requested. The default NUM, NUM2, and MB values depend on the
|
|
Packit Service |
97d2fb |
concurrency of the system, and on the available disk space on the
|
|
Packit Service |
97d2fb |
$TMPDIR or \fB/tmp\fP filesystem. This is because that is where the
|
|
Packit Service |
97d2fb |
most recently used extracted files are kept. Grooming cleans this
|
|
Packit Service |
97d2fb |
cache.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.TP
|
|
Packit Service |
97d2fb |
.B "\-v"
|
|
Packit Service |
97d2fb |
Increase verbosity of logging to the standard error file descriptor.
|
|
Packit Service |
97d2fb |
May be repeated to increase details. The default verbosity is 0.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.SH WEBAPI
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.\" Much of the following text is duplicated with debuginfod-find.1
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
debuginfod's webapi resembles ordinary file service, where a GET
|
|
Packit Service |
97d2fb |
request with a path containing a known buildid results in a file.
|
|
Packit Service |
97d2fb |
Unknown buildid / request combinations result in HTTP error codes.
|
|
Packit Service |
97d2fb |
This file service resemblance is intentional, so that an installation
|
|
Packit Service |
97d2fb |
can take advantage of standard HTTP management infrastructure.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
There are three requests. In each case, the buildid is encoded as a
|
|
Packit Service |
97d2fb |
lowercase hexadecimal string. For example, for a program \fI/bin/ls\fP,
|
|
Packit Service |
97d2fb |
look at the ELF note GNU_BUILD_ID:
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.SAMPLE
|
|
Packit Service |
97d2fb |
% readelf -n /bin/ls | grep -A4 build.id
|
|
Packit Service |
97d2fb |
Note section [ 4] '.note.gnu.buildid' of 36 bytes at offset 0x340:
|
|
Packit Service |
97d2fb |
Owner Data size Type
|
|
Packit Service |
97d2fb |
GNU 20 GNU_BUILD_ID
|
|
Packit Service |
97d2fb |
Build ID: 8713b9c3fb8a720137a4a08b325905c7aaf8429d
|
|
Packit Service |
97d2fb |
.ESAMPLE
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
Then the hexadecimal BUILDID is simply:
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.SAMPLE
|
|
Packit Service |
97d2fb |
8713b9c3fb8a720137a4a08b325905c7aaf8429d
|
|
Packit Service |
97d2fb |
.ESAMPLE
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.SS /buildid/\fIBUILDID\fP/debuginfo
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
If the given buildid is known to the server, this request will result
|
|
Packit Service |
97d2fb |
in a binary object that contains the customary \fB.*debug_*\fP
|
|
Packit Service |
97d2fb |
sections. This may be a split debuginfo file as created by
|
|
Packit Service |
97d2fb |
\fBstrip\fP, or it may be an original unstripped executable.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.SS /buildid/\fIBUILDID\fP/executable
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
If the given buildid is known to the server, this request will result
|
|
Packit Service |
97d2fb |
in a binary object that contains the normal executable segments. This
|
|
Packit Service |
97d2fb |
may be a executable stripped by \fBstrip\fP, or it may be an original
|
|
Packit Service |
97d2fb |
unstripped executable. \fBET_DYN\fP shared libraries are considered
|
|
Packit Service |
97d2fb |
to be a type of executable.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.SS /buildid/\fIBUILDID\fP/source\fI/SOURCE/FILE\fP
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
If the given buildid is known to the server, this request will result
|
|
Packit Service |
97d2fb |
in a binary object that contains the source file mentioned. The path
|
|
Packit Service |
97d2fb |
should be absolute. Relative path names commonly appear in the DWARF
|
|
Packit Service |
97d2fb |
file's source directory, but these paths are relative to
|
|
Packit Service |
97d2fb |
individual compilation unit AT_comp_dir paths, and yet an executable
|
|
Packit Service |
97d2fb |
is made up of multiple CUs. Therefore, to disambiguate, debuginfod
|
|
Packit Service |
97d2fb |
expects source queries to prefix relative path names with the CU
|
|
Packit Service |
97d2fb |
compilation-directory, followed by a mandatory "/".
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
Note: the caller may or may not elide \fB../\fP or \fB/./\fP or extraneous
|
|
Packit Service |
97d2fb |
\fB///\fP sorts of path components in the directory names. debuginfod
|
|
Packit Service |
97d2fb |
accepts both forms. Specifically, debuginfod canonicalizes path names
|
|
Packit Service |
97d2fb |
according to RFC3986 section 5.2.4 (Remove Dot Segments), plus reducing
|
|
Packit Service |
97d2fb |
any \fB//\fP to \fB/\fP in the path.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
For example:
|
|
Packit Service |
97d2fb |
.TS
|
|
Packit Service |
97d2fb |
l l.
|
|
Packit Service |
97d2fb |
#include <stdio.h> /buildid/BUILDID/source/usr/include/stdio.h
|
|
Packit Service |
97d2fb |
/path/to/foo.c /buildid/BUILDID/source/path/to/foo.c
|
|
Packit Service |
97d2fb |
\../bar/foo.c AT_comp_dir=/zoo/ /buildid/BUILDID/source/zoo//../bar/foo.c
|
|
Packit Service |
97d2fb |
.TE
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.SS /metrics
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
This endpoint returns a Prometheus formatted text/plain dump of a
|
|
Packit Service |
97d2fb |
variety of statistics about the operation of the debuginfod server.
|
|
Packit Service |
97d2fb |
The exact set of metrics and their meanings may change in future
|
|
Packit Service |
97d2fb |
versions. Caution: configuration information (path names, versions)
|
|
Packit Service |
97d2fb |
may be disclosed.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.SH DATA MANAGEMENT
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
debuginfod stores its index in an sqlite database in a densely packed
|
|
Packit Service |
97d2fb |
set of interlinked tables. While the representation is as efficient
|
|
Packit Service |
97d2fb |
as we have been able to make it, it still takes a considerable amount
|
|
Packit Service |
97d2fb |
of data to record all debuginfo-related data of potentially a great
|
|
Packit Service |
97d2fb |
many files. This section offers some advice about the implications.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
As a general explanation for size, consider that debuginfod indexes
|
|
Packit Service |
97d2fb |
ELF/DWARF files, it stores their names and referenced source file
|
|
Packit Service |
97d2fb |
names, and buildids will be stored. When indexing archives, it stores
|
|
Packit Service |
97d2fb |
every file name \fIof or in\fP an archive, every buildid, plus every
|
|
Packit Service |
97d2fb |
source file name referenced from a DWARF file. (Indexing archives
|
|
Packit Service |
97d2fb |
takes more space because the source files often reside in separate
|
|
Packit Service |
97d2fb |
subpackages that may not be indexed at the same pass, so extra
|
|
Packit Service |
97d2fb |
metadata has to be kept.)
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
Getting down to numbers, in the case of Fedora RPMs (essentially,
|
|
Packit Service |
97d2fb |
gzip-compressed cpio files), the sqlite index database tends to be
|
|
Packit Service |
97d2fb |
from 0.5% to 3% of their size. It's larger for binaries that are
|
|
Packit Service |
97d2fb |
assembled out of a great many source files, or packages that carry
|
|
Packit Service |
97d2fb |
much debuginfo-unrelated content. It may be even larger during the
|
|
Packit Service |
97d2fb |
indexing phase due to temporary sqlite write-ahead-logging files;
|
|
Packit Service |
97d2fb |
these are checkpointed (cleaned out and removed) at shutdown. It may
|
|
Packit Service |
97d2fb |
be helpful to apply tight \-I or \-X regular-expression constraints to
|
|
Packit Service |
97d2fb |
exclude files from scanning that you know have no debuginfo-relevant
|
|
Packit Service |
97d2fb |
content.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
As debuginfod runs, it periodically rescans its target directories,
|
|
Packit Service |
97d2fb |
and any new content found is added to the database. Old content, such
|
|
Packit Service |
97d2fb |
as data for files that have disappeared or that have been replaced
|
|
Packit Service |
97d2fb |
with newer versions is removed at a periodic \fIgrooming\fP pass.
|
|
Packit Service |
97d2fb |
This means that the sqlite files grow fast during initial indexing,
|
|
Packit Service |
97d2fb |
slowly during index rescans, and periodically shrink during grooming.
|
|
Packit Service |
97d2fb |
There is also an optional one-shot \fImaximal grooming\fP pass is
|
|
Packit Service |
97d2fb |
available. It removes information debuginfo-unrelated data from the
|
|
Packit Service |
97d2fb |
archive content index such as file names found in archives ("archive
|
|
Packit Service |
97d2fb |
sdef" records) that are not referred to as source files from any
|
|
Packit Service |
97d2fb |
binaries find in archives ("archive sref" records). This can save
|
|
Packit Service |
97d2fb |
considerable disk space. However, it is slow and temporarily requires
|
|
Packit Service |
97d2fb |
up to twice the database size as free space. Worse: it may result in
|
|
Packit Service |
97d2fb |
missing source-code info if the archive traversals were interrupted,
|
|
Packit Service |
97d2fb |
so that not all source file references were known. Use it rarely to
|
|
Packit Service |
97d2fb |
polish a complete index.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
You should ensure that ample disk space remains available. (The flood
|
|
Packit Service |
97d2fb |
of error messages on -ENOSPC is ugly and nagging. But, like for most
|
|
Packit Service |
97d2fb |
other errors, debuginfod will resume when resources permit.) If
|
|
Packit Service |
97d2fb |
necessary, debuginfod can be stopped, the database file moved or
|
|
Packit Service |
97d2fb |
removed, and debuginfod restarted.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
sqlite offers several performance-related options in the form of
|
|
Packit Service |
97d2fb |
pragmas. Some may be useful to fine-tune the defaults plus the
|
|
Packit Service |
97d2fb |
debuginfod extras. The \-D option may be useful to tell debuginfod to
|
|
Packit Service |
97d2fb |
execute the given bits of SQL after the basic schema creation
|
|
Packit Service |
97d2fb |
commands. For example, the "synchronous", "cache_size",
|
|
Packit Service |
97d2fb |
"auto_vacuum", "threads", "journal_mode" pragmas may be fun to tweak
|
|
Packit Service |
97d2fb |
via \-D, if you're searching for peak performance. The "optimize",
|
|
Packit Service |
97d2fb |
"wal_checkpoint" pragmas may be useful to run periodically, outside
|
|
Packit Service |
97d2fb |
debuginfod. The default settings are performance- rather than
|
|
Packit Service |
97d2fb |
reliability-oriented, so a hardware crash might corrupt the database.
|
|
Packit Service |
97d2fb |
In these cases, it may be necessary to manually delete the sqlite
|
|
Packit Service |
97d2fb |
database and start over.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
As debuginfod changes in the future, we may have no choice but to
|
|
Packit Service |
97d2fb |
change the database schema in an incompatible manner. If this
|
|
Packit Service |
97d2fb |
happens, new versions of debuginfod will issue SQL statements to
|
|
Packit Service |
97d2fb |
\fIdrop\fP all prior schema & data, and start over. So, disk space
|
|
Packit Service |
97d2fb |
will not be wasted for retaining a no-longer-useable dataset.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
In summary, if your system can bear a 0.5%-3% index-to-archive-dataset
|
|
Packit Service |
97d2fb |
size ratio, and slow growth afterwards, you should not need to
|
|
Packit Service |
97d2fb |
worry about disk space. If a system crash corrupts the database,
|
|
Packit Service |
97d2fb |
or you want to force debuginfod to reset and start over, simply
|
|
Packit Service |
97d2fb |
erase the sqlite file before restarting debuginfod.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.SH SECURITY
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
debuginfod \fBdoes not\fP include any particular security features.
|
|
Packit Service |
97d2fb |
While it is robust with respect to inputs, some abuse is possible. It
|
|
Packit Service |
97d2fb |
forks a new thread for each incoming HTTP request, which could lead to
|
|
Packit Service |
97d2fb |
a denial-of-service in terms of RAM, CPU, disk I/O, or network I/O.
|
|
Packit Service |
97d2fb |
If this is a problem, users are advised to install debuginfod with a
|
|
Packit Service |
97d2fb |
HTTPS reverse-proxy front-end that enforces site policies for
|
|
Packit Service |
97d2fb |
firewalling, authentication, integrity, authorization, and load
|
|
Packit Service |
97d2fb |
control. The \fI/metrics\fP webapi endpoint is probably not
|
|
Packit Service |
97d2fb |
appropriate for disclosure to the public.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
When relaying queries to upstream debuginfods, debuginfod \fBdoes not\fP
|
|
Packit Service |
97d2fb |
include any particular security features. It trusts that the binaries
|
|
Packit Service |
97d2fb |
returned by the debuginfods are accurate. Therefore, the list of
|
|
Packit Service |
97d2fb |
servers should include only trustworthy ones. If accessed across HTTP
|
|
Packit Service |
97d2fb |
rather than HTTPS, the network should be trustworthy. Authentication
|
|
Packit Service |
97d2fb |
information through the internal \fIlibcurl\fP library is not currently
|
|
Packit Service |
97d2fb |
enabled.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.SH "ENVIRONMENT VARIABLES"
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.TP
|
|
Packit Service |
97d2fb |
.B TMPDIR
|
|
Packit Service |
97d2fb |
This environment variable points to a file system to be used for
|
|
Packit Service |
97d2fb |
temporary files. The default is /tmp.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.TP
|
|
Packit Service |
97d2fb |
.B DEBUGINFOD_URLS
|
|
Packit Service |
97d2fb |
This environment variable contains a list of URL prefixes for trusted
|
|
Packit Service |
97d2fb |
debuginfod instances. Alternate URL prefixes are separated by space.
|
|
Packit Service |
97d2fb |
Avoid referential loops that cause a server to contact itself, directly
|
|
Packit Service |
97d2fb |
or indirectly - the results would be hilarious.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.TP
|
|
Packit Service |
97d2fb |
.B DEBUGINFOD_TIMEOUT
|
|
Packit Service |
97d2fb |
This environment variable governs the timeout for each debuginfod HTTP
|
|
Packit Service |
97d2fb |
connection. A server that fails to provide at least 100K of data
|
|
Packit Service |
97d2fb |
within this many seconds is skipped. The default is 90 seconds. (Zero
|
|
Packit Service |
97d2fb |
or negative means "no timeout".)
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.TP
|
|
Packit Service |
97d2fb |
.B DEBUGINFOD_CACHE_PATH
|
|
Packit Service |
97d2fb |
This environment variable governs the location of the cache where
|
|
Packit Service |
97d2fb |
downloaded files are kept. It is cleaned periodically as this
|
|
Packit Service |
97d2fb |
program is reexecuted. If XDG_CACHE_HOME is set then
|
|
Packit Service |
97d2fb |
$XDG_CACHE_HOME/debuginfod_client is the default location, otherwise
|
|
Packit Service |
97d2fb |
$HOME/.cache/debuginfod_client is used. For more information regarding
|
|
Packit Service |
97d2fb |
the client cache see \fIdebuginfod_find_debuginfo(3)\fP.
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.SH FILES
|
|
Packit Service |
97d2fb |
.LP
|
|
Packit Service |
97d2fb |
.PD .1v
|
|
Packit Service |
97d2fb |
.TP 20
|
|
Packit Service |
97d2fb |
.B $HOME/.debuginfod.sqlite
|
|
Packit Service |
97d2fb |
Default database file.
|
|
Packit Service |
97d2fb |
.PD
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.TP 20
|
|
Packit Service |
97d2fb |
.B $XDG_CACHE_HOME/debuginfod_client
|
|
Packit Service |
97d2fb |
Default cache directory for content from upstream debuginfods.
|
|
Packit Service |
97d2fb |
If XDG_CACHE_HOME is not set then \fB$HOME/.cache/debuginfod_client\fP
|
|
Packit Service |
97d2fb |
is used.
|
|
Packit Service |
97d2fb |
.PD
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
|
|
Packit Service |
97d2fb |
.SH "SEE ALSO"
|
|
Packit Service |
97d2fb |
.I "debuginfod-find(1)"
|
|
Packit Service |
97d2fb |
.I "sqlite3(1)"
|
|
Packit Service |
97d2fb |
.I \%https://prometheus.io/docs/instrumenting/exporters/
|