From b750101eb236130cf056c675997decbac904cc49 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 17:35:18 +0200 Subject: Adding upstream version 252.22. Signed-off-by: Daniel Baumann --- README | 415 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 415 insertions(+) create mode 100644 README (limited to 'README') diff --git a/README b/README new file mode 100644 index 0000000..8e7e8b5 --- /dev/null +++ b/README @@ -0,0 +1,415 @@ +systemd System and Service Manager + +WEB SITE: + https://systemd.io + +GIT: + git@github.com:systemd/systemd.git + https://github.com/systemd/systemd + +MAILING LIST: + https://lists.freedesktop.org/mailman/listinfo/systemd-devel + +IRC: + #systemd on irc.libera.chat + +BUG REPORTS: + https://github.com/systemd/systemd/issues + +OLDER DOCUMENTATION: + http://0pointer.de/blog/projects/systemd.html + https://www.freedesktop.org/wiki/Software/systemd + +AUTHOR: + Lennart Poettering + Kay Sievers + ...and many others + +LICENSE: + LGPL-2.1-or-later for all code, exceptions noted in LICENSES/README.md + +REQUIREMENTS: + Linux kernel ≥ 3.15 + ≥ 4.3 for ambient capabilities + ≥ 4.5 for pids controller in cgroup v2 + ≥ 4.6 for cgroup namespaces + ≥ 4.9 for RENAME_NOREPLACE support in vfat + ≥ 4.10 for cgroup-bpf egress and ingress hooks + ≥ 4.15 for cgroup-bpf device hook and cpu controller in cgroup v2 + ≥ 4.17 for cgroup-bpf socket address hooks + ≥ 4.20 for PSI (used by systemd-oomd) + ≥ 5.3 for bounded loops in BPF program + ≥ 5.4 for signed Verity images + ≥ 5.7 for BPF links and the BPF LSM hook + + ⛔ Kernel versions below 3.15 ("minimum baseline") are not supported at + all, and are missing required functionality (e.g. CLOCK_BOOTTIME + support for timerfd_create()). + + ⚠️ Kernel versions below 4.15 ("recommended baseline") have significant + gaps in functionality and are not recommended for use with this version + of systemd (e.g. lack sufficiently comprehensive and working cgroupv2 + support). Taint flag 'old-kernel' will be set. systemd will most likely + still function, but upstream support and testing are limited. + + Kernel Config Options: + CONFIG_DEVTMPFS + CONFIG_CGROUPS (it is OK to disable all controllers) + CONFIG_INOTIFY_USER + CONFIG_SIGNALFD + CONFIG_TIMERFD + CONFIG_EPOLL + CONFIG_UNIX (it requires CONFIG_NET, but every other flag in it is not necessary) + CONFIG_SYSFS + CONFIG_PROC_FS + CONFIG_FHANDLE (libudev, mount and bind mount handling) + + udev will fail to work with the legacy sysfs layout: + CONFIG_SYSFS_DEPRECATED=n + + Legacy hotplug slows down the system and confuses udev: + CONFIG_UEVENT_HELPER_PATH="" + + Userspace firmware loading is not supported and should be disabled in + the kernel: + CONFIG_FW_LOADER_USER_HELPER=n + + Some udev rules and virtualization detection relies on it: + CONFIG_DMIID + + Support for some SCSI devices serial number retrieval, to create + additional symlinks in /dev/disk/ and /dev/tape: + CONFIG_BLK_DEV_BSG + + Required for PrivateNetwork= in service units: + CONFIG_NET_NS + Note that systemd-localed.service and other systemd units use + PrivateNetwork so this is effectively required. + + Required for PrivateUsers= in service units: + CONFIG_USER_NS + + Optional but strongly recommended: + CONFIG_IPV6 + CONFIG_AUTOFS_FS + CONFIG_TMPFS_XATTR + CONFIG_{TMPFS,EXT4_FS,XFS,BTRFS_FS,...}_POSIX_ACL + CONFIG_SECCOMP + CONFIG_SECCOMP_FILTER (required for seccomp support) + CONFIG_KCMP (for the kcmp() syscall, used to be under + CONFIG_CHECKPOINT_RESTORE before ~5.12) + + Required for CPUShares= in resource control unit settings: + CONFIG_CGROUP_SCHED + CONFIG_FAIR_GROUP_SCHED + + Required for CPUQuota= in resource control unit settings: + CONFIG_CFS_BANDWIDTH + + Required for IPAddressDeny=, IPAddressAllow=, IPIngressFilterPath=, + IPEgressFilterPath= in resource control unit settings unit settings: + CONFIG_BPF + CONFIG_BPF_SYSCALL + CONFIG_BPF_JIT + CONFIG_HAVE_EBPF_JIT + CONFIG_CGROUP_BPF + + Required for SocketBind{Allow|Deny}=, RestrictNetworkInterfaces= in + resource control unit settings: + CONFIG_BPF + CONFIG_BPF_SYSCALL + CONFIG_BPF_JIT + CONFIG_HAVE_EBPF_JIT + CONFIG_CGROUP_BPF + + For UEFI systems: + CONFIG_EFIVAR_FS + CONFIG_EFI_PARTITION + + Required for signed Verity images support: + CONFIG_DM_VERITY_VERIFY_ROOTHASH_SIG + + Required for RestrictFileSystems= in service units: + CONFIG_BPF + CONFIG_BPF_SYSCALL + CONFIG_BPF_LSM + CONFIG_DEBUG_INFO_BTF + CONFIG_LSM="...,bpf" or kernel booted with lsm="...,bpf". + + We recommend to turn off Real-Time group scheduling in the kernel when + using systemd. RT group scheduling effectively makes RT scheduling + unavailable for most userspace, since it requires explicit assignment of + RT budgets to each unit whose processes making use of RT. As there's no + sensible way to assign these budgets automatically this cannot really be + fixed, and it's best to disable group scheduling hence: + CONFIG_RT_GROUP_SCHED=n + + It's a good idea to disable the implicit creation of networking bonding + devices by the kernel networking bonding module, so that the + automatically created "bond0" interface doesn't conflict with any such + device created by systemd-networkd (or other tools). Ideally there would + be a kernel compile-time option for this, but there currently isn't. The + next best thing is to make this change through a modprobe.d drop-in. + This is shipped by default, see modprobe.d/systemd.conf. + + Required for systemd-nspawn: + CONFIG_DEVPTS_MULTIPLE_INSTANCES or Linux kernel >= 4.7 + + Required for systemd-oomd: + CONFIG_PSI + + Note that kernel auditing is broken when used with systemd's container + code. When using systemd in conjunction with containers, please make + sure to either turn off auditing at runtime using the kernel command + line option "audit=0", or turn it off at kernel compile time using: + CONFIG_AUDIT=n + If systemd is compiled with libseccomp support on architectures which do + not use socketcall() and where seccomp is supported (this effectively + means x86-64 and ARM, but excludes 32-bit x86!), then nspawn will now + install a work-around seccomp filter that makes containers boot even + with audit being enabled. This works correctly only on kernels 3.14 and + newer though. TL;DR: turn audit off, still. + + glibc >= 2.16 + libcap + libmount >= 2.30 (from util-linux) + (util-linux *must* be built without --enable-libmount-support-mtab) + libseccomp >= 2.3.1 (optional) + libblkid >= 2.24 (from util-linux) (optional) + libkmod >= 15 (optional) + PAM >= 1.1.2 (optional) + libcryptsetup (optional), >= 2.3.0 required for signed Verity images support + libaudit (optional) + libacl (optional) + libbpf >= 0.1.0 (optional) + libfdisk >= 2.32 (from util-linux) (optional) + libselinux (optional) + liblzma (optional) + liblz4 >= 1.3.0 / 130 (optional) + libzstd >= 1.4.0 (optional) + libgcrypt (optional) + libqrencode (optional) + libmicrohttpd (optional) + libpython (optional) + libidn2 or libidn (optional) + gnutls >= 3.1.4 (optional, >= 3.6.0 is required to support DNS-over-TLS with gnutls) + openssl >= 1.1.0 (optional, required to support DNS-over-TLS with openssl) + elfutils >= 158 (optional) + polkit (optional) + tzdata >= 2014f (optional) + pkg-config + gperf + docbook-xsl (optional, required for documentation) + xsltproc (optional, required for documentation) + python-jinja2 + python-lxml (optional, required to build the indices) + python >= 3.5 + meson >= 0.53.2 + ninja + gcc >= 4.7 + awk, sed, grep, and similar tools + clang >= 10.0, llvm >= 10.0 (optional, required to build BPF programs + from source code in C) + gnu-efi >= 3.0.5 (optional, required for systemd-boot) + + During runtime, you need the following additional + dependencies: + + util-linux >= v2.27.1 required (including but not limited to: mount, + umount, swapon, swapoff, sulogin, + agetty, fsck) + dbus >= 1.4.0 (strictly speaking optional, but recommended) + NOTE: If using dbus < 1.9.18, you should override the default + policy directory (--with-dbuspolicydir=/etc/dbus-1/system.d). + dracut (optional) + polkit (optional) + + To build in directory build/: + meson setup build/ && ninja -C build/ + + Any configuration options can be specified as -Darg=value... arguments + to meson. After the build directory is initially configured, meson will + refuse to run again, and options must be changed with: + meson configure -Darg=value build/ + meson configure without any arguments will print out available options and + their current values. + + Useful commands: + ninja -C build -v some/target + meson test -C build/ + sudo meson install -C build/ --no-rebuild + DESTDIR=... meson install -C build/ + + A tarball can be created with: + v=250 && git archive --prefix=systemd-$v/ v$v | zstd >systemd-$v.tar.zstd + + When systemd-hostnamed is used, it is strongly recommended to install + nss-myhostname to ensure that, in a world of dynamically changing + hostnames, the hostname stays resolvable under all circumstances. In + fact, systemd-hostnamed will warn if nss-myhostname is not installed. + + nss-systemd must be enabled on systemd systems, as that's required for + DynamicUser= to work. Note that we ship services out-of-the-box that + make use of DynamicUser= now, hence enabling nss-systemd is not + optional. + + Note that the build prefix for systemd must be /usr. (Moreover, packages + systemd relies on — such as D-Bus — really should use the same prefix, + otherwise you are on your own.) -Dsplit-usr=false (which is the default + and does not need to be specified) is the recommended setting. + -Dsplit-usr=true can be used to give a semblance of support for systems + with programs installed split between / and /usr. Moving everything + under /usr is strongly encouraged. + + Additional packages are necessary to run some tests: + - busybox (used by test/TEST-13-NSPAWN-SMOKE) + - nc (used by test/TEST-12-ISSUE-3171) + - python3-pyparsing + - python3-evdev (used by hwdb parsing tests) + - strace (used by test/test-functions) + - capsh (optional, used by test-execute) + +POLICY FOR SUPPORT OF DISTRIBUTIONS AND ARCHITECTURES: + systemd main branch and latest major or stable releases are generally + expected to compile on current versions of popular distributions (at + least all non-EOL versions of Fedora, Debian unstable/testing/stable, + latest Ubuntu LTS and non-LTS releases, openSUSE Tumbleweed/Leap, + CentOS Stream 8 and 9, up-to-date Arch, etc.) We will generally + attempt to support also other non-EOL versions of various distros. + Features which would break compilation on slightly-older distributions + will only be introduced if there are significant reasons for this + (i.e. supporting them interferes with development or requires too many + resources to support). In some cases backports of specific libraries or + tools might be required. + + The policy is similar wrt. architecture support. systemd is regularly + tested on popular architectures (currently amd64, i386, arm64, ppc64el, + and s390x), but should compile and work also on other architectures, for + which support has been added. systemd will emit warnings when + architecture-specific constants are not defined. + +USERS AND GROUPS: + Default udev rules use the following standard system group names, which + need to be resolvable by getgrnam() at any time, even in the very early + boot stages, where no other databases and network are available: + + audio, cdrom, dialout, disk, input, kmem, kvm, lp, render, tape, tty, video + + During runtime, the journal daemon requires the "systemd-journal" system + group to exist. New journal files will be readable by this group (but + not writable), which may be used to grant specific users read access. In + addition, system groups "wheel" and "adm" will be given read-only access + to journal files using systemd-tmpfiles-setup.service. + + The journal remote daemon requires the "systemd-journal-remote" system + user and group to exist. During execution this network facing service + will drop privileges and assume this uid/gid for security reasons. + + Similarly, the network management daemon requires the "systemd-network" + system user and group to exist. + + Similarly, the name resolution daemon requires the "systemd-resolve" + system user and group to exist. + + Similarly, the coredump support requires the "systemd-coredump" system + user and group to exist. + +GLIBC NSS: + systemd ships with four glibc NSS modules: + + nss-myhostname resolves the local hostname to locally configured IP + addresses, as well as "localhost" to 127.0.0.1/::1. + + nss-resolve enables DNS resolution via the systemd-resolved DNS/LLMNR + caching stub resolver "systemd-resolved". + + nss-mymachines enables resolution of all local containers registered + with machined to their respective IP addresses. + + nss-systemd enables resolution of users/group registered via the + User/Group Record Lookup API (https://systemd.io/USER_GROUP_API), + including all dynamically allocated service users. (See the + DynamicUser= setting in unit files.) + + To make use of these NSS modules, please add them to the "hosts:", + "passwd:" and "group:" lines in /etc/nsswitch.conf. The "resolve" module + should replace the glibc "dns" module in this file (and don't worry, it + chain-loads the "dns" module if it can't talk to resolved). + + The four modules should be used in the following order: + + passwd: compat systemd + group: compat systemd + hosts: files mymachines resolve [!UNAVAIL=return] dns myhostname + +SYSV INIT.D SCRIPTS: + When calling "systemctl enable/disable/is-enabled" on a unit which is a + SysV init.d script, it calls /usr/lib/systemd/systemd-sysv-install; + this needs to translate the action into the distribution specific + mechanism such as chkconfig or update-rc.d. Packagers need to provide + this script if you need this functionality (you don't if you disabled + SysV init support). + + Please see src/systemctl/systemd-sysv-install.SKELETON for how this + needs to look like, and provide an implementation at the marked places. + +WARNINGS and TAINT FLAGS: + systemd will warn during early boot if /usr is not already mounted at + this point (that means: either located on the same file system as / or + already mounted in the initrd). While in systemd itself very little + will break if /usr is on a separate late-mounted partition, many of its + dependencies very likely will break sooner or later in one form or + another. For example, udev rules tend to refer to binaries in /usr, + binaries that link to libraries in /usr, or binaries that refer to data + files in /usr. Since these breakages are not always directly visible, + systemd will warn about this. Such setups are not really supported by + the basic set of Linux OS components. Taint flag 'split-usr' will be + set when this condition is detected. + + For more information on this issue consult + https://www.freedesktop.org/wiki/Software/systemd/separate-usr-is-broken + + systemd will warn if the filesystem is not usr-merged (i.e.: /bin, /sbin + and /lib* are not symlinks to their counterparts under /usr). Taint flag + 'unmerged-usr' will be set when this condition is detected. + + For more information on this issue consult + https://www.freedesktop.org/wiki/Software/systemd/TheCaseForTheUsrMerge + + systemd requires that the /run mount point exists. systemd also + requires that /var/run is a symlink to /run. Taint flag 'var-run-bad' + will be set when this condition is detected. + + Systemd will also warn when the cgroup support is unavailable in the + kernel (taint flag 'cgroups-missing'), the system is using the old + cgroup hierarchy (taint flag 'cgroupsv1'), the hardware clock is + running in non-UTC mode (taint flag 'local-hwclock'), the kernel + overflow UID or GID are not 65534 (taint flags 'overflowuid-not-65534' + and 'overflowgid-not-65534'), the UID or GID range assigned to the + running systemd instance covers less than 0…65534 (taint flags + 'short-uid-range' and 'short-gid-range'). + + Taint conditions are logged during boot, but may also be checked at any + time with: + + busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Tainted + + See org.freedesktop.systemd1(5) for more information. + +VALGRIND: + To run systemd under valgrind, compile with meson option + -Dvalgrind=true and have valgrind development headers installed + (i.e. valgrind-devel or equivalent). Otherwise, false positives will be + triggered by code which violates some rules but is actually safe. Note + that valgrind generates nice output only on exit(), hence on shutdown + we don't execve() systemd-shutdown. + +STABLE BRANCHES AND BACKPORTS: + Stable branches with backported patches are available in the + systemd-stable repo at https://github.com/systemd/systemd-stable. + + Stable branches are started for certain releases of systemd and named + after them, e.g. v238-stable. Stable branches are managed by + distribution maintainers on an as needed basis. See + https://www.freedesktop.org/wiki/Software/systemd/Backports for some + more information and examples. -- cgit v1.2.3