| 1 |
.\" t |
| 2 |
.TH WARNING::BUILDID 7stap |
| 3 |
.SH NAME |
| 4 |
warning::buildid \- build-id verification failures |
| 5 |
|
| 6 |
.\" macros |
| 7 |
.de SAMPLE |
| 8 |
.br |
| 9 |
.RS |
| 10 |
.nf |
| 11 |
.nh |
| 12 |
.. |
| 13 |
.de ESAMPLE |
| 14 |
.hy |
| 15 |
.fi |
| 16 |
.RE |
| 17 |
.. |
| 18 |
|
| 19 |
|
| 20 |
.SH DESCRIPTION |
| 21 |
|
| 22 |
Because systemtap's script translation / execution stages may be |
| 23 |
executed at different times and places, it is sometimes necessary to |
| 24 |
verify certain invariants. One such invariant is that if a script |
| 25 |
was informed by translate-time analysis of executables, then those |
| 26 |
same executables need to be used at run time. This checking |
| 27 |
is done based upon the build-id, a binary hash that modern (post-2007) |
| 28 |
compilers/toolchains add as an |
| 29 |
.IR NT_GNU_BUILD_ID |
| 30 |
ELF note to object files and executables. |
| 31 |
Use the |
| 32 |
.IR "readelf -n" |
| 33 |
command to examine the build-ids of binaries, if you are interested. |
| 34 |
|
| 35 |
.PP |
| 36 |
|
| 37 |
Only scripts are sensitive to executables' build-ids: generally those |
| 38 |
that perform deep analysis of the binaries or their debuginfo. For example, |
| 39 |
scripts that place |
| 40 |
.IR .function " or " .statement |
| 41 |
probes, or use stack backtrace-related tapset functions may be sensitive. |
| 42 |
Other scripts that rely only on |
| 43 |
.IR process.mark " or " kernel.trace |
| 44 |
probes do not require debuginfo. See the DWARF DEBUGINFO section in the |
| 45 |
.IR stapprobes (3stap) |
| 46 |
man page. |
| 47 |
|
| 48 |
.PP |
| 49 |
|
| 50 |
During translation, systemtap saves a copy of the relevant files' |
| 51 |
build-ids within the compiled modules. At run-time, the modules |
| 52 |
compare the saved ones to the actual run-time build-ids in memory. |
| 53 |
The warning message indicates that they did not match, so the module |
| 54 |
will decline placing a probe that was computed based upon obsolete |
| 55 |
data. This is important for safety, as placing them at an |
| 56 |
inappropriate address could crash the programs. However, this is not |
| 57 |
necessarily a fatal error, since probes unrelated to the mismatching |
| 58 |
binaries may operate. |
| 59 |
|
| 60 |
.PP |
| 61 |
|
| 62 |
A build-id mismatch could be caused by a few different situations. |
| 63 |
The main one is where the executable versions or architecture were |
| 64 |
different between the systemtap translation and execution |
| 65 |
times/places. For example, one may run a stap-server on a slightly |
| 66 |
different version of the OS distribution. Someone may have rebuilt a |
| 67 |
new kernel image, but preserved the previous version numbers. The |
| 68 |
kernel running on the workstation may be slightly different from the |
| 69 |
version being targeted - perhaps due to a pending kernel upgrade |
| 70 |
leaving different files on disk versus running in memory. If your OS |
| 71 |
distribution uses separate debuginfo packages, the split \fI.debug\fR |
| 72 |
files may not exactly match the main binaries. |
| 73 |
|
| 74 |
.PP |
| 75 |
|
| 76 |
To disable build-id verification warnings, if one is confident that they |
| 77 |
are an artefact of build accidents rather than a real mismatch, one |
| 78 |
might try the |
| 79 |
.IR -DSTP_NO_BUILDID_CHECK |
| 80 |
option. |
| 81 |
|
| 82 |
.SH SEE ALSO |
| 83 |
.nh |
| 84 |
.nf |
| 85 |
.IR http://fedoraproject.org/wiki/Releases/FeatureBuildId , |
| 86 |
.IR stap (1), |
| 87 |
.IR stapprobes (3stap), |
| 88 |
.IR warning::debuginfo (7stap), |
| 89 |
.IR error::reporting (7stap) |