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