diff options
| -rw-r--r-- | docs/COREDUMP_PACKAGE_METADATA.md | 149 | ||||
| -rw-r--r-- | docs/ELF_PACKAGE_METADATA.md | 149 | ||||
| -rw-r--r-- | docs/_layouts/forward.html | 14 |
3 files changed, 165 insertions, 147 deletions
diff --git a/docs/COREDUMP_PACKAGE_METADATA.md b/docs/COREDUMP_PACKAGE_METADATA.md index 8dac5c61bf..d84e269404 100644 --- a/docs/COREDUMP_PACKAGE_METADATA.md +++ b/docs/COREDUMP_PACKAGE_METADATA.md @@ -1,149 +1,4 @@ --- -title: Package Metadata for Core Files -category: Interfaces -layout: default -SPDX-License-Identifier: LGPL-2.1-or-later +layout: forward +target: /ELF_PACKAGE_METADATA --- - -# Package Metadata for Core Files - -*Intended audience: hackers working on userspace subsystems that create ELF binaries -or parse ELF core files.* - -## Motivation - -ELF binaries get stamped with a unique, build-time generated hex string identifier called -`build-id`, [which gets embedded as an ELF note called `.note.gnu.build-id`](https://fedoraproject.org/wiki/Releases/FeatureBuildId). -In most cases, this allows to associate a stripped binary with its debugging information. -It is used, for example, to dynamically fetch DWARF symbols from a debuginfo server, or -to query the local package manager and find out the package metadata or, again, the DWARF -symbols or program sources. - -However, this usage of the `build-id` requires either local metadata, usually set up by -the package manager, or access to a remote server over the network. Both of those might -be unavailable or forbidden. - -Thus it becomes desirable to add additional metadata to a binary at build time, so that -`systemd-coredump` and other services analyzing core files are able to extract said -metadata simply from the core file itself, without external dependencies. - -## Implementation - -This document will attempt to define a common metadata format specification, so that -multiple implementers might use it when building packages, or core file analyzers, and -so on. - -The metadata will be embedded in a single, new, 4-bytes-aligned, allocated, 0-padded, -read-only ELF header section, in a name-value JSON object format. Implementers working on parsing -core files should not assume a specific list of names, but parse anything that is included -in the section, and should look for the note using the `note type`. Implementers working on -build tools should strive to use the same names, for consistency. The most common will be -listed here. When corresponding to the content of os-release, the values should match, again for consistency. - -If available, the metadata should also include the debuginfod server URL that can provide -the original executable, debuginfo and sources, to further facilitate debugging. - -* Section header - -``` -SECTION: `.note.package` -note type: `0xcafe1a7e` -Owner: `FDO` (FreeDesktop.org) -Value: a single JSON object encoded as a zero-terminated UTF-8 string -``` - -* JSON payload - -```json -{ - "type":"rpm", # this provides a namespace for the package+package-version fields - "os":"fedora", - "osVersion":"33", - "name":"coreutils", - "version":"4711.0815.fc13", - "architecture":"arm32", - "osCpe": "cpe:/o:fedoraproject:fedora:33", # A CPE name for the operating system, `CPE_NAME` from os-release is a good default - "debugInfoUrl": "https://debuginfod.fedoraproject.org/" -} -``` - -The format is a single JSON object, encoded as a zero-terminated `UTF-8` string. -Each name in the object shall be unique as per recommendations of -[RFC8259](https://datatracker.ietf.org/doc/html/rfc8259#section-4). Strings shall -not contain any control character, nor use `\uXXX` escaping. - -When it comes to JSON numbers, this specification assumes that JSON parsers -processing this information are capable of reproducing the full signed 53bit -integer range (i.e. -2⁵³+1…+2⁵³-1) as well as the full 64bit IEEE floating -point number range losslessly (with the exception of NaN/-inf/+inf, since JSON -cannot encode that), as per recommendations of -[RFC8259](https://datatracker.ietf.org/doc/html/rfc8259#page-8). Fields in -these JSON objects are thus permitted to encode numeric values from these -ranges as JSON numbers, and should not use numeric values not covered by these -types and ranges. - -A reference implementations of a [build-time tool is provided](https://github.com/systemd/package-notes) -and can be used to generate a linker script, which can then be used at build time via -```LDFLAGS="-Wl,-T,/path/to/generated/script"``` to include the note in the binary. - -Generator: -```console -$ ./generate-package-notes.py --rpm systemd-248~rc2-1.fc33.arm32 --cpe cpe:/o:fedoraproject:fedora:33 -SECTIONS -{ - .note.package (READONLY) : ALIGN(4) { - LONG(0x0004) /* Length of Owner including NUL */ - LONG(0x007b) /* Length of Value including NUL */ - LONG(0xcafe1a7e) /* Note ID */ - BYTE(0x46) BYTE(0x44) BYTE(0x4f) BYTE(0x00) /* Owner: 'FDO\x00' */ - BYTE(0x7b) BYTE(0x22) BYTE(0x74) BYTE(0x79) /* Value: '{"type":"rpm","name":"systemd","version":"248~rc2-1.fc33","architecture":"arm32","osCpe":"cpe:/o:fedoraproject:fedora:33"}\x00\x00' */ - BYTE(0x70) BYTE(0x65) BYTE(0x22) BYTE(0x3a) - BYTE(0x22) BYTE(0x72) BYTE(0x70) BYTE(0x6d) - BYTE(0x22) BYTE(0x2c) BYTE(0x22) BYTE(0x6e) - BYTE(0x61) BYTE(0x6d) BYTE(0x65) BYTE(0x22) - BYTE(0x3a) BYTE(0x22) BYTE(0x73) BYTE(0x79) - BYTE(0x73) BYTE(0x74) BYTE(0x65) BYTE(0x6d) - BYTE(0x64) BYTE(0x22) BYTE(0x2c) BYTE(0x22) - BYTE(0x76) BYTE(0x65) BYTE(0x72) BYTE(0x73) - BYTE(0x69) BYTE(0x6f) BYTE(0x6e) BYTE(0x22) - BYTE(0x3a) BYTE(0x22) BYTE(0x32) BYTE(0x34) - BYTE(0x38) BYTE(0x7e) BYTE(0x72) BYTE(0x63) - BYTE(0x32) BYTE(0x2d) BYTE(0x31) BYTE(0x2e) - BYTE(0x66) BYTE(0x63) BYTE(0x33) BYTE(0x33) - BYTE(0x22) BYTE(0x2c) BYTE(0x22) BYTE(0x61) - BYTE(0x72) BYTE(0x63) BYTE(0x68) BYTE(0x69) - BYTE(0x74) BYTE(0x65) BYTE(0x63) BYTE(0x74) - BYTE(0x75) BYTE(0x72) BYTE(0x65) BYTE(0x22) - BYTE(0x3a) BYTE(0x22) BYTE(0x61) BYTE(0x72) - BYTE(0x6d) BYTE(0x33) BYTE(0x32) BYTE(0x22) - BYTE(0x2c) BYTE(0x22) BYTE(0x6f) BYTE(0x73) - BYTE(0x43) BYTE(0x70) BYTE(0x65) BYTE(0x22) - BYTE(0x3a) BYTE(0x22) BYTE(0x63) BYTE(0x70) - BYTE(0x65) BYTE(0x3a) BYTE(0x2f) BYTE(0x6f) - BYTE(0x3a) BYTE(0x66) BYTE(0x65) BYTE(0x64) - BYTE(0x6f) BYTE(0x72) BYTE(0x61) BYTE(0x70) - BYTE(0x72) BYTE(0x6f) BYTE(0x6a) BYTE(0x65) - BYTE(0x63) BYTE(0x74) BYTE(0x3a) BYTE(0x66) - BYTE(0x65) BYTE(0x64) BYTE(0x6f) BYTE(0x72) - BYTE(0x61) BYTE(0x3a) BYTE(0x33) BYTE(0x33) - BYTE(0x22) BYTE(0x7d) BYTE(0x00) BYTE(0x00) - } -} -INSERT AFTER .note.gnu.build-id; -``` - -## Well-known keys - -The metadata format is intentionally left open, so that vendors can add their own information. -A set of well-known keys is defined here, and hopefully shared among all vendors. - -| Key name | Key description | Example value | -|--------------|--------------------------------------------------------------------------|---------------------------------------| -| type | The packaging type | rpm | -| os | The OS name, typically corresponding to ID in os-release | fedora | -| osVersion | The OS version, typically corresponding to VERSION_ID in os-release | 33 | -| name | The source package name | coreutils | -| version | The source package version | 4711.0815.fc13 | -| architecture | The binary package architecture | arm32 | -| osCpe | A CPE name for the OS, typically corresponding to CPE_NAME in os-release | cpe:/o:fedoraproject:fedora:33 | -| debugInfoUrl | The debuginfod server url, if available | https://debuginfod.fedoraproject.org/ | diff --git a/docs/ELF_PACKAGE_METADATA.md b/docs/ELF_PACKAGE_METADATA.md new file mode 100644 index 0000000000..fd2099f8e0 --- /dev/null +++ b/docs/ELF_PACKAGE_METADATA.md @@ -0,0 +1,149 @@ +--- +title: Package Metadata for ELF Files +category: Interfaces +layout: default +SPDX-License-Identifier: LGPL-2.1-or-later +--- + +# Package Metadata for Core Files + +*Intended audience: hackers working on userspace subsystems that create ELF binaries +or parse ELF core files.* + +## Motivation + +ELF binaries get stamped with a unique, build-time generated hex string identifier called +`build-id`, [which gets embedded as an ELF note called `.note.gnu.build-id`](https://fedoraproject.org/wiki/Releases/FeatureBuildId). +In most cases, this allows to associate a stripped binary with its debugging information. +It is used, for example, to dynamically fetch DWARF symbols from a debuginfo server, or +to query the local package manager and find out the package metadata or, again, the DWARF +symbols or program sources. + +However, this usage of the `build-id` requires either local metadata, usually set up by +the package manager, or access to a remote server over the network. Both of those might +be unavailable or forbidden. + +Thus it becomes desirable to add additional metadata to a binary at build time, so that +`systemd-coredump` and other services analyzing core files are able to extract said +metadata simply from the core file itself, without external dependencies. + +## Implementation + +This document will attempt to define a common metadata format specification, so that +multiple implementers might use it when building packages, or core file analyzers, and +so on. + +The metadata will be embedded in a single, new, 4-bytes-aligned, allocated, 0-padded, +read-only ELF header section, in a name-value JSON object format. Implementers working on parsing +core files should not assume a specific list of names, but parse anything that is included +in the section, and should look for the note using the `note type`. Implementers working on +build tools should strive to use the same names, for consistency. The most common will be +listed here. When corresponding to the content of os-release, the values should match, again for consistency. + +If available, the metadata should also include the debuginfod server URL that can provide +the original executable, debuginfo and sources, to further facilitate debugging. + +* Section header + +``` +SECTION: `.note.package` +note type: `0xcafe1a7e` +Owner: `FDO` (FreeDesktop.org) +Value: a single JSON object encoded as a zero-terminated UTF-8 string +``` + +* JSON payload + +```json +{ + "type":"rpm", # this provides a namespace for the package+package-version fields + "os":"fedora", + "osVersion":"33", + "name":"coreutils", + "version":"4711.0815.fc13", + "architecture":"arm32", + "osCpe": "cpe:/o:fedoraproject:fedora:33", # A CPE name for the operating system, `CPE_NAME` from os-release is a good default + "debugInfoUrl": "https://debuginfod.fedoraproject.org/" +} +``` + +The format is a single JSON object, encoded as a zero-terminated `UTF-8` string. +Each name in the object shall be unique as per recommendations of +[RFC8259](https://datatracker.ietf.org/doc/html/rfc8259#section-4). Strings shall +not contain any control character, nor use `\uXXX` escaping. + +When it comes to JSON numbers, this specification assumes that JSON parsers +processing this information are capable of reproducing the full signed 53bit +integer range (i.e. -2⁵³+1…+2⁵³-1) as well as the full 64bit IEEE floating +point number range losslessly (with the exception of NaN/-inf/+inf, since JSON +cannot encode that), as per recommendations of +[RFC8259](https://datatracker.ietf.org/doc/html/rfc8259#page-8). Fields in +these JSON objects are thus permitted to encode numeric values from these +ranges as JSON numbers, and should not use numeric values not covered by these +types and ranges. + +A reference implementations of a [build-time tool is provided](https://github.com/systemd/package-notes) +and can be used to generate a linker script, which can then be used at build time via +```LDFLAGS="-Wl,-T,/path/to/generated/script"``` to include the note in the binary. + +Generator: +```console +$ ./generate-package-notes.py --rpm systemd-248~rc2-1.fc33.arm32 --cpe cpe:/o:fedoraproject:fedora:33 +SECTIONS +{ + .note.package (READONLY) : ALIGN(4) { + LONG(0x0004) /* Length of Owner including NUL */ + LONG(0x007b) /* Length of Value including NUL */ + LONG(0xcafe1a7e) /* Note ID */ + BYTE(0x46) BYTE(0x44) BYTE(0x4f) BYTE(0x00) /* Owner: 'FDO\x00' */ + BYTE(0x7b) BYTE(0x22) BYTE(0x74) BYTE(0x79) /* Value: '{"type":"rpm","name":"systemd","version":"248~rc2-1.fc33","architecture":"arm32","osCpe":"cpe:/o:fedoraproject:fedora:33"}\x00\x00' */ + BYTE(0x70) BYTE(0x65) BYTE(0x22) BYTE(0x3a) + BYTE(0x22) BYTE(0x72) BYTE(0x70) BYTE(0x6d) + BYTE(0x22) BYTE(0x2c) BYTE(0x22) BYTE(0x6e) + BYTE(0x61) BYTE(0x6d) BYTE(0x65) BYTE(0x22) + BYTE(0x3a) BYTE(0x22) BYTE(0x73) BYTE(0x79) + BYTE(0x73) BYTE(0x74) BYTE(0x65) BYTE(0x6d) + BYTE(0x64) BYTE(0x22) BYTE(0x2c) BYTE(0x22) + BYTE(0x76) BYTE(0x65) BYTE(0x72) BYTE(0x73) + BYTE(0x69) BYTE(0x6f) BYTE(0x6e) BYTE(0x22) + BYTE(0x3a) BYTE(0x22) BYTE(0x32) BYTE(0x34) + BYTE(0x38) BYTE(0x7e) BYTE(0x72) BYTE(0x63) + BYTE(0x32) BYTE(0x2d) BYTE(0x31) BYTE(0x2e) + BYTE(0x66) BYTE(0x63) BYTE(0x33) BYTE(0x33) + BYTE(0x22) BYTE(0x2c) BYTE(0x22) BYTE(0x61) + BYTE(0x72) BYTE(0x63) BYTE(0x68) BYTE(0x69) + BYTE(0x74) BYTE(0x65) BYTE(0x63) BYTE(0x74) + BYTE(0x75) BYTE(0x72) BYTE(0x65) BYTE(0x22) + BYTE(0x3a) BYTE(0x22) BYTE(0x61) BYTE(0x72) + BYTE(0x6d) BYTE(0x33) BYTE(0x32) BYTE(0x22) + BYTE(0x2c) BYTE(0x22) BYTE(0x6f) BYTE(0x73) + BYTE(0x43) BYTE(0x70) BYTE(0x65) BYTE(0x22) + BYTE(0x3a) BYTE(0x22) BYTE(0x63) BYTE(0x70) + BYTE(0x65) BYTE(0x3a) BYTE(0x2f) BYTE(0x6f) + BYTE(0x3a) BYTE(0x66) BYTE(0x65) BYTE(0x64) + BYTE(0x6f) BYTE(0x72) BYTE(0x61) BYTE(0x70) + BYTE(0x72) BYTE(0x6f) BYTE(0x6a) BYTE(0x65) + BYTE(0x63) BYTE(0x74) BYTE(0x3a) BYTE(0x66) + BYTE(0x65) BYTE(0x64) BYTE(0x6f) BYTE(0x72) + BYTE(0x61) BYTE(0x3a) BYTE(0x33) BYTE(0x33) + BYTE(0x22) BYTE(0x7d) BYTE(0x00) BYTE(0x00) + } +} +INSERT AFTER .note.gnu.build-id; +``` + +## Well-known keys + +The metadata format is intentionally left open, so that vendors can add their own information. +A set of well-known keys is defined here, and hopefully shared among all vendors. + +| Key name | Key description | Example value | +|--------------|--------------------------------------------------------------------------|---------------------------------------| +| type | The packaging type | rpm | +| os | The OS name, typically corresponding to ID in os-release | fedora | +| osVersion | The OS version, typically corresponding to VERSION_ID in os-release | 33 | +| name | The source package name | coreutils | +| version | The source package version | 4711.0815.fc13 | +| architecture | The binary package architecture | arm32 | +| osCpe | A CPE name for the OS, typically corresponding to CPE_NAME in os-release | cpe:/o:fedoraproject:fedora:33 | +| debugInfoUrl | The debuginfod server url, if available | https://debuginfod.fedoraproject.org/ | diff --git a/docs/_layouts/forward.html b/docs/_layouts/forward.html new file mode 100644 index 0000000000..499b41852a --- /dev/null +++ b/docs/_layouts/forward.html @@ -0,0 +1,14 @@ +<html lang="en"> + <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> + <head> + <meta http-equiv="refresh" content="0;url={{ page.target }}"/> + <link rel="canonical" href="{{ page.target }}"/> + <title>Redirecting to {{ page.target }}</title> + </head> + <body> + <p> + This document has moved.<br> + Redirecting to <a href="{{ page.target }}">{{ page.target }}</a>. + </p> + </body> +</html> |