mirrors/systemd
0
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-11-23 02:03:37 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: rename COREDUMP_PACKAGE_METADATA → ELF_PACKAGE_METADATA

Browse Source 
The format described by this document is used not only for coredumps,
but also for other purposes, so we've outgrown the old title.

A redirect was added based on https://codepo8.github.io/github-redirection-demo/.
I tried to use a relative link, but it's hard to test if it works
before merging.

Co-authored-by: Benjamin Franzke <benjaminfranzke@googlemail.com>
This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2022-05-21 18:07:38 +02:00
parent 30e29edf4c
commit d4224b9cc7
3 changed files with 165 additions and 147 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

149
docs/COREDUMP_PACKAGE_METADATA.md
View File

@ -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/ |

149
docs/ELF_PACKAGE_METADATA.md Normal file
View File

@ -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/ |

14
docs/_layouts/forward.html Normal file
View File

@ -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>