2 title: Package Metadata for Core Files
7 # Package Metadata for Core Files
9 *Intended audience: hackers working on userspace subsystems that create ELF binaries
10 or parse ELF core files.*
14 ELF binaries get stamped with a unique, build-time generated hex string identifier called
15 `build-id`, [which gets embedded as an ELF note called `.note.gnu.build-id`](https://fedoraproject.org/wiki/Releases/FeatureBuildId).
16 In most cases, this allows to associate a stripped binary with its debugging information.
17 It is used, for example, to dynamically fetch DWARF symbols from a debuginfo server, or
18 to query the local package manager and find out the package metadata or, again, the DWARF
19 symbols or program sources.
21 However, this usage of the `build-id` requires either local metadata, usually set up by
22 the package manager, or access to a remote server over the network. Both of those might
23 be unavailable or forbidden.
25 Thus it becomes desirable to add additional metadata to a binary at build time, so that
26 `systemd-coredump` and other services analyzing core files are able to extract said
27 metadata simply from the core file itself, without external dependencies.
31 This document will attempt to define a common metadata format specification, so that
32 multiple implementers might use it when building packages, or core file analyzers, and
35 The metadata will be embedded in a single, new ELF header section, in a key-value JSON
36 format. Implementers working on parsing core files should not assume a specific list of
37 keys, but parse anything that is included in the section.
38 Implementers working on build tools should strive to use the same key names, for
39 consistency. The most common will be listed here. When corresponding to the content of
40 os-release, the values should match, again for consistency.
42 If available, the metadata should also include the debuginfod server URL that can provide
43 the original executable, debuginfo and sources, to further facilitate debugging.
48 SECTION: `.note.package`
50 Owner: `FDO` (FreeDesktop.org)
51 Value: a JSON string with the structure described below
58 "type":"rpm", # this provides a namespace for the package+package-version fields
62 "version": "4711.0815.fc13.arm32",
63 "osCpe": "cpe:/o:fedoraproject:fedora:33", # A CPE name for the operating system, `CPE_NAME` from os-release is a good default
64 "debugInfoUrl": "https://debuginfod.fedoraproject.org/"
68 A reference implementations of a [build-time tool is provided](https://github.com/systemd/package-notes)
69 and can be used to generate a linker script, which can then be used at build time via
70 ```LDFLAGS="-Wl,-T,/path/to/generated/script"``` to include the note in the binary.
74 $ ./generate-package-notes.py --rpm systemd-248~rc2-1.fc34
77 .note.package : ALIGN(4) {
78 BYTE(0x04) BYTE(0x00) BYTE(0x00) BYTE(0x00) /* Length of Owner including NUL */
79 BYTE(0x64) BYTE(0x00) BYTE(0x00) BYTE(0x00) /* Length of Value including NUL */
80 BYTE(0x7e) BYTE(0x1a) BYTE(0xfe) BYTE(0xca) /* Note ID */
81 BYTE(0x46) BYTE(0x44) BYTE(0x4f) BYTE(0x00) /* Owner: 'FDO\x00' */
82 BYTE(0x7b) BYTE(0x22) BYTE(0x74) BYTE(0x79) /* Value: '{"type":"rpm","name":"systemd","version":"248~rc2-1.fc34","osCpe":"cpe:/o:fedoraproject:fedora:33"}\x00' */
83 BYTE(0x70) BYTE(0x65) BYTE(0x22) BYTE(0x3a)
84 BYTE(0x22) BYTE(0x72) BYTE(0x70) BYTE(0x6d)
85 BYTE(0x22) BYTE(0x2c) BYTE(0x22) BYTE(0x6e)
86 BYTE(0x61) BYTE(0x6d) BYTE(0x65) BYTE(0x22)
87 BYTE(0x3a) BYTE(0x22) BYTE(0x73) BYTE(0x79)
88 BYTE(0x73) BYTE(0x74) BYTE(0x65) BYTE(0x6d)
89 BYTE(0x64) BYTE(0x22) BYTE(0x2c) BYTE(0x22)
90 BYTE(0x76) BYTE(0x65) BYTE(0x72) BYTE(0x73)
91 BYTE(0x69) BYTE(0x6f) BYTE(0x6e) BYTE(0x22)
92 BYTE(0x3a) BYTE(0x22) BYTE(0x32) BYTE(0x34)
93 BYTE(0x38) BYTE(0x7e) BYTE(0x72) BYTE(0x63)
94 BYTE(0x32) BYTE(0x2d) BYTE(0x31) BYTE(0x2e)
95 BYTE(0x66) BYTE(0x63) BYTE(0x33) BYTE(0x34)
96 BYTE(0x22) BYTE(0x2c) BYTE(0x22) BYTE(0x6f)
97 BYTE(0x73) BYTE(0x43) BYTE(0x70) BYTE(0x65)
98 BYTE(0x22) BYTE(0x3a) BYTE(0x22) BYTE(0x63)
99 BYTE(0x70) BYTE(0x65) BYTE(0x3a) BYTE(0x2f)
100 BYTE(0x6f) BYTE(0x3a) BYTE(0x66) BYTE(0x65)
101 BYTE(0x64) BYTE(0x6f) BYTE(0x72) BYTE(0x61)
102 BYTE(0x70) BYTE(0x72) BYTE(0x6f) BYTE(0x6a)
103 BYTE(0x65) BYTE(0x63) BYTE(0x74) BYTE(0x3a)
104 BYTE(0x66) BYTE(0x65) BYTE(0x64) BYTE(0x6f)
105 BYTE(0x72) BYTE(0x61) BYTE(0x3a) BYTE(0x33)
106 BYTE(0x33) BYTE(0x22) BYTE(0x7d) BYTE(0x00)
109 INSERT AFTER .note.gnu.build-id;
114 The metadata format is intentionally left open, so that vendors can add their own information.
115 A set of well-known keys is defined here, and hopefully shared among all vendors.
117 | Key name | Key description | Example value |
118 |--------------|--------------------------------------------------------------------------|---------------------------------------|
119 | type | The packaging type | rpm |
120 | os | The OS name, typically corresponding to ID in os-release | fedora |
121 | osVersion | The OS version, typically corresponding to VERSION_ID in os-release | 33 |
122 | name | The source package name | coreutils |
123 | version | The source package version | 4711.0815.fc13.arm32 |
124 | osCpe | A CPE name for the OS, typically corresponding to CPE_NAME in os-release | cpe:/o:fedoraproject:fedora:33 |
125 | debugInfoUrl | The debuginfod server url, if available | https://debuginfod.fedoraproject.org/ |