docs/COREDUMP_PACKAGE_METADATA.md

   1 ---
   2 title: Package Metadata for Core Files
   3 category: Interfaces
   4 layout: default
   5 ---
   6
   7 # Package Metadata for Core Files
   8
   9 *Intended audience: hackers working on userspace subsystems that create ELF binaries
  10 or parse ELF core files.*
  11
  12 ## Motivation
  13
  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.
  20
  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.
  24
  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.
  28
  29 ## Implementation
  30
  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
  33 so on.
  34
  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.
  41
  42 * Section header
  43
  44 ```
  45 SECTION: `.note.package`
  46 node-id: `0xcafe1a7e`
  47 Owner: `FDO` (FreeDesktop.org)
  48 Value: a JSON string with the structure described below
  49 ```
  50
  51 * JSON payload
  52
  53 ```json
  54 {
  55      "type":"rpm",          # this provides a namespace for the package+package-version fields
  56      "os":"fedora",
  57      "osVersion":"33",
  58      "name":"coreutils",
  59      "version": "4711.0815.fc13.arm32",
  60      "osCpe":               # A CPE name for the operating system, `CPE_NAME` from os-release is a good default
  61 }
  62 ```
  63
  64 A reference implementations of a [build-time tool is provided](https://github.com/keszybz/rpm-version-note/)
  65 and can be used to generate a linker script, which can then be used at build time via
  66 ```LDFLAGS="-Wl,-T,/path/to/generated/script"``` to include the note in the binary.
  67
  68 Generator:
  69 ```console
  70 $ ./generate-package-notes.py --rpm systemd-248~rc2-1.fc34
  71 SECTIONS
  72 {
  73     .note.package : ALIGN(4) {
  74         BYTE(0x04) BYTE(0x00) BYTE(0x00) BYTE(0x00) /* Length of Owner including NUL */
  75         BYTE(0x64) BYTE(0x00) BYTE(0x00) BYTE(0x00) /* Length of Value including NUL */
  76         BYTE(0x7e) BYTE(0x1a) BYTE(0xfe) BYTE(0xca) /* Note ID */
  77         BYTE(0x46) BYTE(0x44) BYTE(0x4f) BYTE(0x00) /* Owner: 'FDO\x00' */
  78         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' */
  79         BYTE(0x70) BYTE(0x65) BYTE(0x22) BYTE(0x3a)
  80         BYTE(0x22) BYTE(0x72) BYTE(0x70) BYTE(0x6d)
  81         BYTE(0x22) BYTE(0x2c) BYTE(0x22) BYTE(0x6e)
  82         BYTE(0x61) BYTE(0x6d) BYTE(0x65) BYTE(0x22)
  83         BYTE(0x3a) BYTE(0x22) BYTE(0x73) BYTE(0x79)
  84         BYTE(0x73) BYTE(0x74) BYTE(0x65) BYTE(0x6d)
  85         BYTE(0x64) BYTE(0x22) BYTE(0x2c) BYTE(0x22)
  86         BYTE(0x76) BYTE(0x65) BYTE(0x72) BYTE(0x73)
  87         BYTE(0x69) BYTE(0x6f) BYTE(0x6e) BYTE(0x22)
  88         BYTE(0x3a) BYTE(0x22) BYTE(0x32) BYTE(0x34)
  89         BYTE(0x38) BYTE(0x7e) BYTE(0x72) BYTE(0x63)
  90         BYTE(0x32) BYTE(0x2d) BYTE(0x31) BYTE(0x2e)
  91         BYTE(0x66) BYTE(0x63) BYTE(0x33) BYTE(0x34)
  92         BYTE(0x22) BYTE(0x2c) BYTE(0x22) BYTE(0x6f)
  93         BYTE(0x73) BYTE(0x43) BYTE(0x70) BYTE(0x65)
  94         BYTE(0x22) BYTE(0x3a) BYTE(0x22) BYTE(0x63)
  95         BYTE(0x70) BYTE(0x65) BYTE(0x3a) BYTE(0x2f)
  96         BYTE(0x6f) BYTE(0x3a) BYTE(0x66) BYTE(0x65)
  97         BYTE(0x64) BYTE(0x6f) BYTE(0x72) BYTE(0x61)
  98         BYTE(0x70) BYTE(0x72) BYTE(0x6f) BYTE(0x6a)
  99         BYTE(0x65) BYTE(0x63) BYTE(0x74) BYTE(0x3a)
 100         BYTE(0x66) BYTE(0x65) BYTE(0x64) BYTE(0x6f)
 101         BYTE(0x72) BYTE(0x61) BYTE(0x3a) BYTE(0x33)
 102         BYTE(0x33) BYTE(0x22) BYTE(0x7d) BYTE(0x00)
 103     }
 104 }
 105 INSERT AFTER .note.gnu.build-id;
 106 ```