]>
Commit | Line | Data |
---|---|---|
d4224b9c ZJS |
1 | --- |
2 | title: Package Metadata for ELF Files | |
3 | category: Interfaces | |
4 | layout: default | |
5 | SPDX-License-Identifier: LGPL-2.1-or-later | |
6 | --- | |
7 | ||
8 | # Package Metadata for Core Files | |
9 | ||
10 | *Intended audience: hackers working on userspace subsystems that create ELF binaries | |
11 | or parse ELF core files.* | |
12 | ||
13 | ## Motivation | |
14 | ||
15 | ELF binaries get stamped with a unique, build-time generated hex string identifier called | |
16 | `build-id`, [which gets embedded as an ELF note called `.note.gnu.build-id`](https://fedoraproject.org/wiki/Releases/FeatureBuildId). | |
17 | In most cases, this allows to associate a stripped binary with its debugging information. | |
18 | It is used, for example, to dynamically fetch DWARF symbols from a debuginfo server, or | |
19 | to query the local package manager and find out the package metadata or, again, the DWARF | |
20 | symbols or program sources. | |
21 | ||
22 | However, this usage of the `build-id` requires either local metadata, usually set up by | |
23 | the package manager, or access to a remote server over the network. Both of those might | |
24 | be unavailable or forbidden. | |
25 | ||
26 | Thus it becomes desirable to add additional metadata to a binary at build time, so that | |
27 | `systemd-coredump` and other services analyzing core files are able to extract said | |
28 | metadata simply from the core file itself, without external dependencies. | |
29 | ||
30 | ## Implementation | |
31 | ||
32 | This document will attempt to define a common metadata format specification, so that | |
33 | multiple implementers might use it when building packages, or core file analyzers, and | |
34 | so on. | |
35 | ||
36 | The metadata will be embedded in a single, new, 4-bytes-aligned, allocated, 0-padded, | |
37 | read-only ELF header section, in a name-value JSON object format. Implementers working on parsing | |
38 | core files should not assume a specific list of names, but parse anything that is included | |
39 | in the section, and should look for the note using the `note type`. Implementers working on | |
40 | build tools should strive to use the same names, for consistency. The most common will be | |
41 | listed here. When corresponding to the content of os-release, the values should match, again for consistency. | |
42 | ||
43 | If available, the metadata should also include the debuginfod server URL that can provide | |
44 | the original executable, debuginfo and sources, to further facilitate debugging. | |
45 | ||
46 | * Section header | |
47 | ||
48 | ``` | |
49 | SECTION: `.note.package` | |
50 | note type: `0xcafe1a7e` | |
51 | Owner: `FDO` (FreeDesktop.org) | |
52 | Value: a single JSON object encoded as a zero-terminated UTF-8 string | |
53 | ``` | |
54 | ||
55 | * JSON payload | |
56 | ||
57 | ```json | |
58 | { | |
59 | "type":"rpm", # this provides a namespace for the package+package-version fields | |
60 | "os":"fedora", | |
61 | "osVersion":"33", | |
62 | "name":"coreutils", | |
63 | "version":"4711.0815.fc13", | |
64 | "architecture":"arm32", | |
65 | "osCpe": "cpe:/o:fedoraproject:fedora:33", # A CPE name for the operating system, `CPE_NAME` from os-release is a good default | |
66 | "debugInfoUrl": "https://debuginfod.fedoraproject.org/" | |
67 | } | |
68 | ``` | |
69 | ||
70 | The format is a single JSON object, encoded as a zero-terminated `UTF-8` string. | |
71 | Each name in the object shall be unique as per recommendations of | |
72 | [RFC8259](https://datatracker.ietf.org/doc/html/rfc8259#section-4). Strings shall | |
73 | not contain any control character, nor use `\uXXX` escaping. | |
74 | ||
75 | When it comes to JSON numbers, this specification assumes that JSON parsers | |
76 | processing this information are capable of reproducing the full signed 53bit | |
da890466 | 77 | integer range (i.e. -2⁵³+1…+2⁵³-1) as well as the full 64-bit IEEE floating |
d4224b9c ZJS |
78 | point number range losslessly (with the exception of NaN/-inf/+inf, since JSON |
79 | cannot encode that), as per recommendations of | |
80 | [RFC8259](https://datatracker.ietf.org/doc/html/rfc8259#page-8). Fields in | |
81 | these JSON objects are thus permitted to encode numeric values from these | |
82 | ranges as JSON numbers, and should not use numeric values not covered by these | |
83 | types and ranges. | |
84 | ||
e0b8bbbd LB |
85 | Reference implementations of [packaging tools for .deb and .rpm](https://github.com/systemd/package-notes) |
86 | are available, and provide macros/helpers to include the note in binaries built | |
87 | by the package build system. They make use of the new `--package-metadata` flag that | |
88 | is available in the bfd, gold, mold and lld linkers (versions 2.39, 1.3.0 and 15.0 | |
89 | respectively). This linker flag takes a JSON payload as parameter. | |
d4224b9c ZJS |
90 | |
91 | ## Well-known keys | |
92 | ||
93 | The metadata format is intentionally left open, so that vendors can add their own information. | |
94 | A set of well-known keys is defined here, and hopefully shared among all vendors. | |
95 | ||
96 | | Key name | Key description | Example value | | |
97 | |--------------|--------------------------------------------------------------------------|---------------------------------------| | |
98 | | type | The packaging type | rpm | | |
99 | | os | The OS name, typically corresponding to ID in os-release | fedora | | |
100 | | osVersion | The OS version, typically corresponding to VERSION_ID in os-release | 33 | | |
101 | | name | The source package name | coreutils | | |
102 | | version | The source package version | 4711.0815.fc13 | | |
103 | | architecture | The binary package architecture | arm32 | | |
104 | | osCpe | A CPE name for the OS, typically corresponding to CPE_NAME in os-release | cpe:/o:fedoraproject:fedora:33 | | |
105 | | debugInfoUrl | The debuginfod server url, if available | https://debuginfod.fedoraproject.org/ | |