From 2cb7e0aaedad73b076ea18c6900b0e86c5760d79 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 27 Apr 2024 15:00:47 +0200 Subject: Adding upstream version 247.3. Signed-off-by: Daniel Baumann --- README | 340 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 340 insertions(+) create mode 100644 README (limited to 'README') diff --git a/README b/README new file mode 100644 index 0000000..7b11572 --- /dev/null +++ b/README @@ -0,0 +1,340 @@ +systemd System and Service Manager + +DETAILS: + http://0pointer.de/blog/projects/systemd.html + +WEB SITE: + https://www.freedesktop.org/wiki/Software/systemd + +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.freenode.org + +BUG REPORTS: + https://github.com/systemd/systemd/issues + +AUTHOR: + Lennart Poettering + Kay Sievers + ...and many others + +LICENSE: + LGPLv2.1+ for all code + - except src/basic/MurmurHash2.c which is Public Domain + - except src/basic/siphash24.c which is CC0 Public Domain + - except src/journal/lookup3.c which is Public Domain + - except src/udev/* which is (currently still) GPLv2, GPLv2+ + - except tools/chromiumos/* which is BSD-style + +REQUIREMENTS: + Linux kernel >= 3.13 + Linux kernel >= 4.2 for unified cgroup hierarchy support + Linux kernel >= 5.4 for signed Verity images support + + Kernel Config Options: + CONFIG_DEVTMPFS + CONFIG_CGROUPS (it is OK to disable all controllers) + CONFIG_INOTIFY_USER + CONFIG_SIGNALFD + CONFIG_TIMERFD + CONFIG_EPOLL + CONFIG_NET + CONFIG_SYSFS + CONFIG_PROC_FS + CONFIG_FHANDLE (libudev, mount and bind mount handling) + + Kernel crypto/hash API + CONFIG_CRYPTO_USER_API_HASH + CONFIG_CRYPTO_HMAC + CONFIG_CRYPTO_SHA256 + + 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_AUTOFS4_FS + CONFIG_TMPFS_XATTR + CONFIG_{TMPFS,EXT4_FS,XFS,BTRFS_FS,...}_POSIX_ACL + CONFIG_SECCOMP + CONFIG_SECCOMP_FILTER (required for seccomp support) + CONFIG_CHECKPOINT_RESTORE (for the kcmp() syscall) + + 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= and IPAddressAllow= in resource control + unit settings + CONFIG_CGROUP_BPF + + For UEFI systems: + CONFIG_EFIVAR_FS + CONFIG_EFI_PARTITION + + Required for signed Verity images support: + CONFIG_DM_VERITY_VERIFY_ROOTHASH_SIG + + 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 + + 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) + libfdisk >= 2.33 (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-lxml (optional, required to build the indices) + python >= 3.5 + meson >= 0.46 (>= 0.49 is required to build position-independent executables) + ninja + gcc, awk, sed, grep, m4, and similar tools + + During runtime, you need the following additional + dependencies: + + util-linux >= v2.27.1 required + 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 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 -v some/target + ninja test + sudo ninja install + DESTDIR=... ninja install + + A tarball can be created with: + git archive --format=tar --prefix=systemd-222/ v222 | xz > systemd-222.tar.xz + + 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, + and -Dsplit-usr=true should be used on systems which have /usr on a + separate partition. + + 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) + +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.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. + +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: + 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, since this kind of file system setup is + not really supported anymore by the basic set of Linux OS components. + + systemd requires that the /run mount point exists. systemd also + requires that /var/run is a symlink to /run. + + For more information on this issue consult + https://www.freedesktop.org/wiki/Software/systemd/separate-usr-is-broken + + 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. + +ENGINEERING AND CONSULTING SERVICES: + Kinvolk (https://kinvolk.io) offers professional engineering + and consulting services for systemd. Please contact Chris Kühl + for more information. -- cgit v1.2.3