diff options
Diffstat (limited to 'doc/debuginfod.8')
| -rw-r--r-- | doc/debuginfod.8 | 96 |
1 files changed, 50 insertions, 46 deletions
diff --git a/doc/debuginfod.8 b/doc/debuginfod.8 index 342f524c..d2917285 100644 --- a/doc/debuginfod.8 +++ b/doc/debuginfod.8 @@ -34,17 +34,23 @@ debuginfod servers, it queries them for the same information, just as \fBdebuginfod-find\fP would. If successful, it locally caches then relays the file content to the original requester. -If the \fB\-F\fP option is given, each listed PATH creates a thread to -scan for matching ELF/DWARF/source files under the given physical -directory. Source files are matched with DWARF files based on the -AT_comp_dir (compilation directory) attributes inside it. Duplicate -directories are ignored. You may use a file name for a PATH, but -source code indexing may be incomplete; prefer using a directory that -contains the binaries. Caution: source files listed in the DWARF may -be a path \fIanywhere\fP in the file system, and debuginfod will -readily serve their content on demand. (Imagine a doctored DWARF file -that lists \fI/etc/passwd\fP as a source file.) If this is a concern, -audit your binaries with tools such as: +Indexing the given PATHs proceeds using multiple threads. One thread +periodically traverses all the given PATHs logically or physically +(see the \fB\-L\fP option). Duplicate PATHs are ignored. You may use +a file name for a PATH, but source code indexing may be incomplete; +prefer using a directory that contains the binaries. The traversal +thread enumerates all matching files (see the \fB\-I\fP and \fB\-X\fP +options) into a work queue. A collection of scanner threads (see the +\fB\-c\fP option) wait at the work queue to analyze files in parallel. + +If the \fB\-F\fP option is given, each file is scanned as an ELF/DWARF +file. Source files are matched with DWARF files based on the +AT_comp_dir (compilation directory) attributes inside it. Caution: +source files listed in the DWARF may be a path \fIanywhere\fP in the +file system, and debuginfod will readily serve their content on +demand. (Imagine a doctored DWARF file that lists \fI/etc/passwd\fP +as a source file.) If this is a concern, audit your binaries with +tools such as: .SAMPLE % eu-readelf -wline BINARY | sed -n '/^Directory.table/,/^File.name.table/p' @@ -55,42 +61,35 @@ or even use debuginfod itself: ^C .ESAMPLE -If the \fB\-R\fP and/or \fB-U\fP option is given, each listed PATH -creates a thread to scan for ELF/DWARF/source files contained in -archive files. If \-R is given, the will scan RPMs; and/or if \-U is -given, they will scan DEB / DDEB files. (The terms RPM and DEB and -DDEB are used synonymously as "archives" in diagnostic messages.) -Duplicate directories are ignored. You may use a file name for a -PATH, but source code indexing may be incomplete. Instead, use a -directory that contains normal RPMs alongside debuginfo/debugsource -RPMs. Because of complications such as DWZ-compressed debuginfo, may -require \fItwo\fP scan passes to identify all source code. Source -files for RPMs are only served from other RPMs, so the caution for \-F -does not apply. Note that due to Debian/Ubuntu packaging policies & -mechanisms, debuginfod cannot resolve source files for DEB/DDEB at -all. - -If no PATH is listed, or neither \-F nor \-R nor \-U option is given, then -\fBdebuginfod\fP will simply serve content that it scanned into its -index in previous runs: the data is cumulative. - -File names must match extended regular expressions given by the \-I -option and not the \-X option (if any) in order to be considered. +If the \fB\-R\fP and/or \fB-U\fP option is given, each file is scanned +as an archive file that may contain ELF/DWARF/source files. If \-R is +given, the will scan RPMs; and/or if \-U is given, they will scan DEB +/ DDEB files. (The terms RPM and DEB and DDEB are used synonymously +as "archives" in diagnostic messages.) Because of complications such +as DWZ-compressed debuginfo, may require \fItwo\fP traversal passes to +identify all source code. Source files for RPMs are only served from +other RPMs, so the caution for \-F does not apply. Note that due to +Debian/Ubuntu packaging policies & mechanisms, debuginfod cannot +resolve source files for DEB/DDEB at all. + +If no PATH is listed, or neither \fB\-F\fP nor \fB\-R\fP nor \fB\-U\fP +option is given, then \fBdebuginfod\fP will simply serve content that +it accumulated into its index in all previous runs. .SH OPTIONS .TP .B "\-F" -Activate ELF/DWARF file scanning threads. The default is off. +Activate ELF/DWARF file scanning. The default is off. .TP .B "\-R" -Activate RPM patterns in archive scanning threads. The default is off. +Activate RPM patterns in archive scanning. The default is off. .TP .B "\-U" -Activate DEB/DDEB patterns in archive scanning threads. The default is off. +Activate DEB/DDEB patterns in archive scanning. The default is off. .TP .B "\-d FILE" "\-\-database=FILE" @@ -100,7 +99,7 @@ data. It will contain absolute file path names, so it may not be portable across machines. It may be frequently read/written, so it should be on a fast filesytem. It should not be shared across machines or users, to maximize sqlite locking performance. The -default database file is $HOME/.debuginfod.sqlite. +default database file is \%$HOME/.debuginfod.sqlite. .TP .B "\-D SQL" "\-\-ddl=SQL" @@ -129,7 +128,7 @@ inclusion or exclusion filtering: they are all processed.) .TP .B "\-t SECONDS" "\-\-rescan\-time=SECONDS" Set the rescan time for the file and archive directories. This is the -amount of time the scanning threads will wait after finishing a scan, +amount of time the traversal thread will wait after finishing a scan, before doing it again. A rescan for unchanged files is fast (because the index also stores the file mtimes). A time of zero is acceptable, and means that only one initial scan should performed. The default @@ -161,11 +160,11 @@ do maximal-grooming. See also the \fIDATA MANAGEMENT\fP section. .TP .B "\-c NUM" "\-\-concurrency=NUM" -Set the concurrency limit for all the scanning threads. While many -threads may be spawned to cover all the given PATHs, only NUM may -concurrently do CPU-intensive operations like parsing an ELF file -or an archive. The default is the number of processors on the system; -the minimum is 1. +Set the concurrency limit for the scanning queue threads, which work +together to process archives & files located by the traversal thread. +This important for controlling CPU-intensive operations like parsing +an ELF file and especially decompressing archives. The default is the +number of processors on the system; the minimum is 1. .TP .B "\-L" @@ -356,24 +355,29 @@ enabled. .SH "ENVIRONMENT VARIABLES" -.TP 21 +.TP +.B TMPDIR +This environment variable points to a file system to be used for +temporary files. The default is /tmp. + +.TP .B DEBUGINFOD_URLS This environment variable contains a list of URL prefixes for trusted debuginfod instances. Alternate URL prefixes are separated by space. Avoid referential loops that cause a server to contact itself, directly or indirectly - the results would be hilarious. -.TP 21 +.TP .B DEBUGINFOD_TIMEOUT This environment variable governs the timeout for each debuginfod HTTP connection. A server that fails to respond within this many seconds is skipped. The default is 5. -.TP 21 +.TP .B DEBUGINFOD_CACHE_PATH This environment variable governs the location of the cache where downloaded files are kept. It is cleaned periodically as this -program is reexecuted. The default is $HOME/.debuginfod_client_cache. +program is reexecuted. The default is \%$HOME/.debuginfod_client_cache. .\" XXX describe cache eviction policy .SH FILES |