From 9a2b54d9f7c6439a89b7ad2419310ff98bb54091 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 13 Sep 2024 14:35:43 +0200 Subject: [PATCH 1/2] docs/ELF_PACKAGE_METADATA: add detailed example When the spec was initially written, we didn't add good documentation of how to display the notes, also because there was no good way to display the data except manually extracting the section to a file and running 'jq' on that. But the tools have improved, so let's show the users how easy it is to use this data. --- TODO | 2 + docs/ELF_PACKAGE_METADATA.md | 94 ++++++++++++++++++++++++++++++++++++ 2 files changed, 96 insertions(+) diff --git a/TODO b/TODO index 3a68845d6cc..ae5bda52e7c 100644 --- a/TODO +++ b/TODO @@ -1518,6 +1518,8 @@ Features: * systemd-analyze netif that explains predictable interface (or networkctl) +* systemd-analyze inspect-elf should show other notes too, at least build-id. + * Figure out naming of verbs in systemd-analyze: we have (singular) capability, exit-status, but (plural) filesystems, architectures. diff --git a/docs/ELF_PACKAGE_METADATA.md b/docs/ELF_PACKAGE_METADATA.md index 2b58cf1380a..5415441cfb3 100644 --- a/docs/ELF_PACKAGE_METADATA.md +++ b/docs/ELF_PACKAGE_METADATA.md @@ -103,3 +103,97 @@ A set of well-known keys is defined here, and hopefully shared among all vendors | 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/ | + +### Displaying package notes + +The raw ELF section can be extracted using `objdump`: +```console +$ objdump -j .note.package -s /usr/bin/ls + +/usr/bin/ls: file format elf64-x86-64 + +Contents of section .note.package: + 03cc 04000000 7c000000 7e1afeca 46444f00 ....|...~...FDO. + 03dc 7b227479 7065223a 2272706d 222c226e {"type":"rpm","n + 03ec 616d6522 3a22636f 72657574 696c7322 ame":"coreutils" + 03fc 2c227665 7273696f 6e223a22 392e342d ,"version":"9.4- + 040c 372e6663 3430222c 22617263 68697465 7.fc40","archite + 041c 63747572 65223a22 7838365f 3634222c cture":"x86_64", + 042c 226f7343 7065223a 22637065 3a2f6f3a "osCpe":"cpe:/o: + 043c 6665646f 72617072 6f6a6563 743a6665 fedoraproject:fe + 044c 646f7261 3a343022 7d000000 dora:40"}... +``` + +It is more convenient to use a higher level tool: +```console +$ readelf --notes /usr/bin/ls +... +Displaying notes found in: .note.gnu.build-id + Owner Data size Description + GNU 0x00000014 NT_GNU_BUILD_ID (unique build ID bitstring) + Build ID: 40e5a1570a9d97fc48f5c61cfb7690fec0f872b2 + +Displaying notes found in: .note.ABI-tag + Owner Data size Description + GNU 0x00000010 NT_GNU_ABI_TAG (ABI version tag) + OS: Linux, ABI: 3.2.0 + +Displaying notes found in: .note.package + Owner Data size Description + FDO 0x0000007c FDO_PACKAGING_METADATA + Packaging Metadata: {"type":"rpm","name":"coreutils","version":"9.4-7.fc40","architecture":"x86_64","osCpe":"cpe:/o:fedoraproject:fedora:40"} +... + +$ systemd-analyze inspect-elf /usr/bin/ls + path: /usr/bin/ls + elfType: executable +elfArchitecture: AMD x86-64 + + type: rpm + name: coreutils + version: 9.4-7.fc40 + architecture: x86_64 + osCpe: cpe:/o:fedoraproject:fedora:40 + buildId: 40e5a1570a9d97fc48f5c61cfb7690fec0f872b2 +``` + +If the binary crashes, `systemd-coredump` will display the combined information +from the crashing binary and any shared libraries it links to: + +```console +$ coredumpctl info + PID: 3987823 (ls) + Signal: 11 (SEGV) + Command Line: ls --color=tty -lR / + Executable: /usr/bin/ls +... + Storage: /var/lib/systemd/coredump/core.ls.1000.88dea1b9831c420dbb398f9d2ad9b41e.3987823.1726230641000000.zst (present) + Size on Disk: 194.4K + Package: coreutils/9.4-7.fc40 + build-id: 40e5a1570a9d97fc48f5c61cfb7690fec0f872b2 + Message: Process 3987823 (ls) of user 1000 dumped core. + + Module /usr/bin/ls from rpm coreutils-9.4-7.fc40.x86_64 + Module libz.so.1 from rpm zlib-ng-2.1.7-1.fc40.x86_64 + Module libcrypto.so.3 from rpm openssl-3.2.2-3.fc40.x86_64 + Module libmount.so.1 from rpm util-linux-2.40.1-1.fc40.x86_64 + Module libcrypt.so.2 from rpm libxcrypt-4.4.36-5.fc40.x86_64 + Module libblkid.so.1 from rpm util-linux-2.40.1-1.fc40.x86_64 + Module libnss_sss.so.2 from rpm sssd-2.9.5-1.fc40.x86_64 + Module libpcre2-8.so.0 from rpm pcre2-10.44-1.fc40.x86_64 + Module libcap.so.2 from rpm libcap-2.69-8.fc40.x86_64 + Module libselinux.so.1 from rpm libselinux-3.6-4.fc40.x86_64 + Stack trace of thread 3987823: + #0 0x00007f19331c3f7e lgetxattr (libc.so.6 + 0x116f7e) + #1 0x00007f19332be4c0 lgetfilecon_raw (libselinux.so.1 + 0x134c0) + #2 0x00007f19332c3bd9 lgetfilecon (libselinux.so.1 + 0x18bd9) + #3 0x000056038273ad55 gobble_file.constprop.0 (/usr/bin/ls + 0x17d55) + #4 0x0000560382733c55 print_dir (/usr/bin/ls + 0x10c55) + #5 0x0000560382727c35 main (/usr/bin/ls + 0x4c35) + #6 0x00007f19330d7088 __libc_start_call_main (libc.so.6 + 0x2a088) + #7 0x00007f19330d714b __libc_start_main@@GLIBC_2.34 (libc.so.6 + 0x2a14b) + #8 0x0000560382728f15 _start (/usr/bin/ls + 0x5f15) + ELF object binary architecture: AMD x86-64 +``` + +(This is just a simulation. `ls` is not prone to crashing with a segmentation violation.) From 2e1f83d1abce034a8aa571e808b99e4f7de16746 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 13 Sep 2024 14:51:25 +0200 Subject: [PATCH 2/2] docs/ELF_DLOPEN_METADATA: add detailed example --- docs/ELF_DLOPEN_METADATA.md | 87 +++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) diff --git a/docs/ELF_DLOPEN_METADATA.md b/docs/ELF_DLOPEN_METADATA.md index 5c3bf1eae2a..cb196d1ac73 100644 --- a/docs/ELF_DLOPEN_METADATA.md +++ b/docs/ELF_DLOPEN_METADATA.md @@ -87,3 +87,90 @@ of the libraries they specify in order to be enabled. | required | Core functionality needs the dependency, the binary will not work if it cannot be found | | recommended | Important functionality needs the dependency, the binary will work but in most cases the dependency should be provided | | suggested | Secondary functionality needs the dependency, the binary will work and the dependency is only needed for full-featured installations | + +### Displaying `dlopen()` notes + +The raw ELF section can be extracted using `objdump`: +```console +$ objdump -j .note.dlopen -s /usr/lib64/systemd/libsystemd-shared-257.so + +/usr/lib64/systemd/libsystemd-shared-257.so: file format elf64-x86-64 + +Contents of section .note.dlopen: + 0334 04000000 8e000000 0a0c7c40 46444f00 ..........|@FDO. + 0344 5b7b2266 65617475 7265223a 22627066 [{"feature":"bpf + 0354 222c2264 65736372 69707469 6f6e223a ","description": + 0364 22537570 706f7274 20666972 6577616c "Support firewal + 0374 6c696e67 20616e64 2073616e 64626f78 ling and sandbox + 0384 696e6720 77697468 20425046 222c2270 ing with BPF","p + 0394 72696f72 69747922 3a227375 67676573 riority":"sugges + 03a4 74656422 2c22736f 6e616d65 223a5b22 ted","soname":[" + 03b4 6c696262 70662e73 6f2e3122 2c226c69 libbpf.so.1","li + 03c4 62627066 2e736f2e 30225d7d 5d000000 bbpf.so.0"]}]... + 03d4 04000000 9e000000 0a0c7c40 46444f00 ..........|@FDO. +... +``` + +It is more convenient to use a higher level tool: +```console +$ dlopen-notes /usr/lib64/systemd/libsystemd-shared-257.so +# /usr/lib64/systemd/libsystemd-shared-257.so +[ + { + "feature": "archive", + "description": "Support for decompressing archive files", + "priority": "suggested", + "soname": [ + "libarchive.so.13" + ] + }, + { + "feature": "bpf", + "description": "Support firewalling and sandboxing with BPF", + "priority": "suggested", + "soname": [ + "libbpf.so.1", + "libbpf.so.0" + ] + }, +... +``` + +`dlopen-notes` can display the notes grouped in a few different ways. +One option is to filter the libraries by "feature". This answers the +question "what libraries are needed to provide specified features": + +```console +$ dlopen-notes.py -f archive,bpf /usr/lib64/systemd/libsystemd-shared-257.so +# grouped by feature +{ + "bpf": { + "description": "Support firewalling and sandboxing with BPF", + "sonames": { + "libbpf.so.1": "suggested", + "libbpf.so.0": "suggested" + } + }, + "archive": { + "description": "Support for decompressing archive files", + "sonames": { + "libarchive.so.13": "suggested" + } + } +} + +The format that is used when building `deb` packages: +```console +$ dlopen-notes -s /usr/lib64/systemd/libsystemd-shared-257.so +libarchive.so.13 suggested +libbpf.so.0 suggested +libbpf.so.1 suggested +... +``` + +The format that can be useful when building `rpm` packages: +```console +$ dlopen-notes --rpm-requires archive --rpm-recommends bpf /usr/lib64/systemd/libsystemd-shared-257.so +Requires: libarchive.so.13()(64bit) +Recommends: libbpf.so.1()(64bit) +```