]>
Commit | Line | Data |
---|---|---|
d657c51f | 1 | systemd System and Service Manager |
31cee6f6 | 2 | |
31cee6f6 | 3 | WEB SITE: |
2777a4a3 | 4 | https://systemd.io |
31cee6f6 LP |
5 | |
6 | GIT: | |
eb0914fc | 7 | git@github.com:systemd/systemd.git |
eb0914fc | 8 | https://github.com/systemd/systemd |
31cee6f6 LP |
9 | |
10 | MAILING LIST: | |
19d9372b | 11 | https://lists.freedesktop.org/mailman/listinfo/systemd-devel |
31cee6f6 LP |
12 | |
13 | IRC: | |
fb906b00 | 14 | #systemd on irc.libera.chat |
31cee6f6 LP |
15 | |
16 | BUG REPORTS: | |
eb0914fc | 17 | https://github.com/systemd/systemd/issues |
31cee6f6 | 18 | |
2777a4a3 ZJS |
19 | OLDER DOCUMENTATION: |
20 | ||
21 | http://0pointer.de/blog/projects/systemd.html | |
22 | https://www.freedesktop.org/wiki/Software/systemd | |
23 | ||
31cee6f6 | 24 | AUTHOR: |
5430f7f2 LP |
25 | Lennart Poettering |
26 | Kay Sievers | |
27 | ...and many others | |
31cee6f6 | 28 | |
673eab9b | 29 | LICENSE: |
7fe57498 | 30 | LGPL-2.1-or-later for all code, exceptions noted in LICENSES/README.md |
673eab9b | 31 | |
31cee6f6 | 32 | REQUIREMENTS: |
277f0587 ZJS |
33 | Linux kernel ≥ 3.15 |
34 | ≥ 4.5 for pids controller in cgroup v2 | |
35 | ≥ 4.6 for cgroup namespaces | |
36 | ≥ 4.9 for RENAME_NOREPLACE support in vfat | |
37 | ≥ 4.10 for cgroup-bpf egress and ingress hooks | |
38 | ≥ 4.15 for cgroup-bpf device hook and cpu controller in cgroup v2 | |
39 | ≥ 4.17 for cgroup-bpf socket address hooks | |
40 | ≥ 5.3 for bounded loops in BPF program | |
41 | ≥ 5.4 for signed Verity images | |
42 | ≥ 5.7 for BPF links and the BPF LSM hook | |
43 | ||
44 | Kernel versions below 4.15 have significant gaps in functionality and | |
45 | are not recommended for use with this version of systemd. Taint flag | |
46 | 'old-kernel' will be set. Systemd will most likely still function, but | |
47 | upstream support and testing are limited. | |
23aedd02 KS |
48 | |
49 | Kernel Config Options: | |
713bc0cf | 50 | CONFIG_DEVTMPFS |
d28315e4 | 51 | CONFIG_CGROUPS (it is OK to disable all controllers) |
713bc0cf KS |
52 | CONFIG_INOTIFY_USER |
53 | CONFIG_SIGNALFD | |
54 | CONFIG_TIMERFD | |
55 | CONFIG_EPOLL | |
8d186a35 | 56 | CONFIG_UNIX (it requires CONFIG_NET, but every other flag in it is not necessary) |
713bc0cf | 57 | CONFIG_SYSFS |
06d461ee | 58 | CONFIG_PROC_FS |
5d31974e | 59 | CONFIG_FHANDLE (libudev, mount and bind mount handling) |
713bc0cf | 60 | |
9c7f7d86 MG |
61 | Kernel crypto/hash API |
62 | CONFIG_CRYPTO_USER_API_HASH | |
63 | CONFIG_CRYPTO_HMAC | |
64 | CONFIG_CRYPTO_SHA256 | |
65 | ||
be2ea723 | 66 | udev will fail to work with the legacy sysfs layout: |
f28cbd03 | 67 | CONFIG_SYSFS_DEPRECATED=n |
713bc0cf KS |
68 | |
69 | Legacy hotplug slows down the system and confuses udev: | |
70 | CONFIG_UEVENT_HELPER_PATH="" | |
71 | ||
be2ea723 KS |
72 | Userspace firmware loading is not supported and should |
73 | be disabled in the kernel: | |
713bc0cf KS |
74 | CONFIG_FW_LOADER_USER_HELPER=n |
75 | ||
76 | Some udev rules and virtualization detection relies on it: | |
77 | CONFIG_DMIID | |
78 | ||
a5c724b2 KS |
79 | Support for some SCSI devices serial number retrieval, to |
80 | create additional symlinks in /dev/disk/ and /dev/tape: | |
81 | CONFIG_BLK_DEV_BSG | |
82 | ||
45a582d5 | 83 | Required for PrivateNetwork= in service units: |
13468826 | 84 | CONFIG_NET_NS |
b52a4a3b | 85 | Note that systemd-localed.service and other systemd units use |
45a582d5 | 86 | PrivateNetwork so this is effectively required. |
13468826 | 87 | |
0ca48bb0 | 88 | Required for PrivateUsers= in service units: |
87fe1707 LW |
89 | CONFIG_USER_NS |
90 | ||
713bc0cf KS |
91 | Optional but strongly recommended: |
92 | CONFIG_IPV6 | |
0c651d32 | 93 | CONFIG_AUTOFS_FS |
713bc0cf | 94 | CONFIG_TMPFS_XATTR |
0ceced3d | 95 | CONFIG_{TMPFS,EXT4_FS,XFS,BTRFS_FS,...}_POSIX_ACL |
f28cbd03 | 96 | CONFIG_SECCOMP |
fd74fa79 | 97 | CONFIG_SECCOMP_FILTER (required for seccomp support) |
560ace5d | 98 | CONFIG_KCMP (for the kcmp() syscall, used to be under CONFIG_CHECKPOINT_RESTORE before ~5.12) |
713bc0cf | 99 | |
f4e74be1 | 100 | Required for CPUShares= in resource control unit settings |
a21b4670 UTL |
101 | CONFIG_CGROUP_SCHED |
102 | CONFIG_FAIR_GROUP_SCHED | |
103 | ||
f4e74be1 | 104 | Required for CPUQuota= in resource control unit settings |
0acd5a08 WC |
105 | CONFIG_CFS_BANDWIDTH |
106 | ||
c3080258 JK |
107 | Required for IPAddressDeny=, IPAddressAllow=, IPIngressFilterPath=, |
108 | IPEgressFilterPath= in resource control unit settings | |
b1b96380 | 109 | unit settings |
c3080258 JK |
110 | CONFIG_BPF |
111 | CONFIG_BPF_SYSCALL | |
112 | CONFIG_BPF_JIT | |
113 | CONFIG_HAVE_EBPF_JIT | |
114 | CONFIG_CGROUP_BPF | |
115 | ||
43689840 MV |
116 | Required for SocketBind{Allow|Deny}=, RestrictNetworkInterfaces= in |
117 | resource control unit settings | |
c3080258 JK |
118 | CONFIG_BPF |
119 | CONFIG_BPF_SYSCALL | |
120 | CONFIG_BPF_JIT | |
121 | CONFIG_HAVE_EBPF_JIT | |
b1b96380 AJ |
122 | CONFIG_CGROUP_BPF |
123 | ||
f28cbd03 | 124 | For UEFI systems: |
f33016ff | 125 | CONFIG_EFIVAR_FS |
f28cbd03 KS |
126 | CONFIG_EFI_PARTITION |
127 | ||
c2923fdc LB |
128 | Required for signed Verity images support: |
129 | CONFIG_DM_VERITY_VERIFY_ROOTHASH_SIG | |
130 | ||
ec31dd5a ILG |
131 | Required for RestrictFileSystems= in service units: |
132 | CONFIG_BPF | |
133 | CONFIG_BPF_SYSCALL | |
134 | CONFIG_BPF_LSM | |
135 | CONFIG_DEBUG_INFO_BTF | |
136 | CONFIG_LSM="...,bpf" or kernel booted with lsm="...,bpf". | |
137 | ||
f4e74be1 LP |
138 | We recommend to turn off Real-Time group scheduling in the |
139 | kernel when using systemd. RT group scheduling effectively | |
140 | makes RT scheduling unavailable for most userspace, since it | |
141 | requires explicit assignment of RT budgets to each unit whose | |
142 | processes making use of RT. As there's no sensible way to | |
143 | assign these budgets automatically this cannot really be | |
144 | fixed, and it's best to disable group scheduling hence. | |
145 | CONFIG_RT_GROUP_SCHED=n | |
146 | ||
f5a93d5d LP |
147 | It's a good idea to disable the implicit creation of networking bonding |
148 | devices by the kernel networking bonding module, so that the | |
149 | automatically created "bond0" interface doesn't conflict with any such | |
582faeb4 DJL |
150 | device created by systemd-networkd (or other tools). Ideally there |
151 | would be a kernel compile-time option for this, but there currently | |
152 | isn't. The next best thing is to make this change through a modprobe.d | |
153 | drop-in. This is shipped by default, see modprobe.d/systemd.conf. | |
f5a93d5d | 154 | |
45a582d5 AJ |
155 | Required for systemd-nspawn: |
156 | CONFIG_DEVPTS_MULTIPLE_INSTANCES or Linux kernel >= 4.7 | |
157 | ||
e7b3f1a6 AZ |
158 | Required for systemd-oomd: |
159 | CONFIG_PSI | |
160 | ||
77b6e194 LP |
161 | Note that kernel auditing is broken when used with systemd's |
162 | container code. When using systemd in conjunction with | |
19aadacf | 163 | containers, please make sure to either turn off auditing at |
77b6e194 LP |
164 | runtime using the kernel command line option "audit=0", or |
165 | turn it off at kernel compile time using: | |
166 | CONFIG_AUDIT=n | |
a7b1c397 LP |
167 | If systemd is compiled with libseccomp support on |
168 | architectures which do not use socketcall() and where seccomp | |
169 | is supported (this effectively means x86-64 and ARM, but | |
70a44afe | 170 | excludes 32-bit x86!), then nspawn will now install a |
a7b1c397 LP |
171 | work-around seccomp filter that makes containers boot even |
172 | with audit being enabled. This works correctly only on kernels | |
173 | 3.14 and newer though. TL;DR: turn audit off, still. | |
77b6e194 | 174 | |
3dd26f3e | 175 | glibc >= 2.16 |
3ede835a | 176 | libcap |
d6e80966 ZJS |
177 | libmount >= 2.30 (from util-linux) |
178 | (util-linux *must* be built without --enable-libmount-support-mtab) | |
6abfd303 | 179 | libseccomp >= 2.3.1 (optional) |
d47f6ca5 | 180 | libblkid >= 2.24 (from util-linux) (optional) |
a18535d9 | 181 | libkmod >= 15 (optional) |
3ede835a | 182 | PAM >= 1.1.2 (optional) |
c2923fdc | 183 | libcryptsetup (optional), >= 2.3.0 required for signed Verity images support |
3ede835a | 184 | libaudit (optional) |
19d5d4cb | 185 | libacl (optional) |
c3080258 | 186 | libbpf >= 0.2.0 (optional) |
baec7d78 | 187 | libfdisk >= 2.32 (from util-linux) (optional) |
3ede835a | 188 | libselinux (optional) |
19d5d4cb | 189 | liblzma (optional) |
e0a1d4b0 | 190 | liblz4 >= 1.3.0 / 130 (optional) |
ef5924aa | 191 | libzstd >= 1.4.0 (optional) |
7b17a7d7 LP |
192 | libgcrypt (optional) |
193 | libqrencode (optional) | |
194 | libmicrohttpd (optional) | |
2cc86f09 | 195 | libpython (optional) |
87057e24 | 196 | libidn2 or libidn (optional) |
38e053c5 | 197 | gnutls >= 3.1.4 (optional, >= 3.6.0 is required to support DNS-over-TLS with gnutls) |
096cbdce | 198 | openssl >= 1.1.0 (optional, required to support DNS-over-TLS with openssl) |
5b244719 | 199 | elfutils >= 158 (optional) |
d79a2f5f | 200 | polkit (optional) |
781748af | 201 | tzdata >= 2014f (optional) |
72cdb3e7 | 202 | pkg-config |
8f968c73 | 203 | gperf |
72cdb3e7 ZJS |
204 | docbook-xsl (optional, required for documentation) |
205 | xsltproc (optional, required for documentation) | |
e0698c66 | 206 | python-jinja2 |
72cdb3e7 | 207 | python-lxml (optional, required to build the indices) |
40f116f5 | 208 | python >= 3.5 |
48538c19 | 209 | meson >= 0.53.2 (>= 0.54.0 is required to build with 'meson compile') |
40f116f5 | 210 | ninja |
44ff8df7 | 211 | gcc, awk, sed, grep, and similar tools |
c3080258 JK |
212 | clang >= 10.0, llvm >= 10.0 (optional, required to build BPF programs |
213 | from source code in C) | |
53f69d67 | 214 | gnu-efi >= 3.0.5 (optional, required for systemd-boot) |
2cc86f09 | 215 | |
19aadacf JE |
216 | During runtime, you need the following additional |
217 | dependencies: | |
2cc86f09 | 218 | |
1d40ddbf | 219 | util-linux >= v2.27.1 required |
b895fa08 LP |
220 | dbus >= 1.4.0 (strictly speaking optional, but recommended) |
221 | NOTE: If using dbus < 1.9.18, you should override the default | |
222 | policy directory (--with-dbuspolicydir=/etc/dbus-1/system.d). | |
2cc86f09 | 223 | dracut (optional) |
d35f51ea | 224 | polkit (optional) |
3ede835a | 225 | |
3e609a8a | 226 | To build in directory build/: |
8b08be40 | 227 | meson setup build/ && meson compile -C build/ |
3e609a8a | 228 | |
5238e957 | 229 | Any configuration options can be specified as -Darg=value... arguments |
3e609a8a ZJS |
230 | to meson. After the build directory is initially configured, meson will |
231 | refuse to run again, and options must be changed with: | |
5adfb06d | 232 | meson configure -Darg=value build/ |
233 | meson configure without any arguments will print out available options and | |
3e609a8a ZJS |
234 | their current values. |
235 | ||
236 | Useful commands: | |
8b08be40 LP |
237 | meson compile -v -C build/ some/target |
238 | meson test -C build/ | |
239 | sudo meson install -C build/ | |
240 | DESTDIR=... meson install -C build/ | |
3e609a8a | 241 | |
72cdb3e7 | 242 | A tarball can be created with: |
82627069 KS |
243 | git archive --format=tar --prefix=systemd-222/ v222 | xz > systemd-222.tar.xz |
244 | ||
19aadacf JE |
245 | When systemd-hostnamed is used, it is strongly recommended to |
246 | install nss-myhostname to ensure that, in a world of | |
247 | dynamically changing hostnames, the hostname stays resolvable | |
fff2e5b5 | 248 | under all circumstances. In fact, systemd-hostnamed will warn |
bf9e477c | 249 | if nss-myhostname is not installed. |
fff2e5b5 | 250 | |
01c8938e LP |
251 | nss-systemd must be enabled on systemd systems, as that's required for |
252 | DynamicUser= to work. Note that we ship services out-of-the-box that | |
253 | make use of DynamicUser= now, hence enabling nss-systemd is not | |
254 | optional. | |
255 | ||
1815dfbb LP |
256 | Note that the build prefix for systemd must be /usr. (Moreover, |
257 | packages systemd relies on — such as D-Bus — really should use the same | |
258 | prefix, otherwise you are on your own.) -Dsplit-usr=false (which is the | |
9afd5e7b ZJS |
259 | default and does not need to be specified) is the recommended setting. |
260 | -Dsplit-usr=true can be used to give a semblance of support for systems | |
261 | with programs installed split between / and /usr. Moving everything | |
262 | under /usr is strongly encouraged. | |
01c8938e | 263 | |
a2fc3d87 ZJS |
264 | Additional packages are necessary to run some tests: |
265 | - busybox (used by test/TEST-13-NSPAWN-SMOKE) | |
266 | - nc (used by test/TEST-12-ISSUE-3171) | |
267 | - python3-pyparsing | |
268 | - python3-evdev (used by hwdb parsing tests) | |
269 | - strace (used by test/test-functions) | |
e94681ad | 270 | - capsh (optional, used by test-execute) |
a2fc3d87 | 271 | |
a24c64f0 | 272 | USERS AND GROUPS: |
37495eed LP |
273 | Default udev rules use the following standard system group |
274 | names, which need to be resolvable by getgrnam() at any time, | |
275 | even in the very early boot stages, where no other databases | |
276 | and network are available: | |
277 | ||
2422bd21 | 278 | audio, cdrom, dialout, disk, input, kmem, kvm, lp, render, tape, tty, video |
37c0e8f3 | 279 | |
19aadacf | 280 | During runtime, the journal daemon requires the |
1a9ce3f7 | 281 | "systemd-journal" system group to exist. New journal files will |
19aadacf | 282 | be readable by this group (but not writable), which may be used |
a48a62a1 ZJS |
283 | to grant specific users read access. In addition, system |
284 | groups "wheel" and "adm" will be given read-only access to | |
285 | journal files using systemd-tmpfiles.service. | |
a24c64f0 | 286 | |
f959c5c6 YW |
287 | The journal remote daemon requires the |
288 | "systemd-journal-remote" system user and group to | |
37495eed LP |
289 | exist. During execution this network facing service will drop |
290 | privileges and assume this uid/gid for security reasons. | |
291 | ||
8d0e0ddd | 292 | Similarly, the network management daemon requires the |
323a2f0b LP |
293 | "systemd-network" system user and group to exist. |
294 | ||
8d0e0ddd | 295 | Similarly, the name resolution daemon requires the |
323a2f0b LP |
296 | "systemd-resolve" system user and group to exist. |
297 | ||
888e378d LP |
298 | Similarly, the coredump support requires the |
299 | "systemd-coredump" system user and group to exist. | |
300 | ||
a4a79605 | 301 | NSS: |
409093fe | 302 | systemd ships with four glibc NSS modules: |
a4a79605 | 303 | |
38ccb557 LP |
304 | nss-myhostname resolves the local hostname to locally configured IP |
305 | addresses, as well as "localhost" to 127.0.0.1/::1. | |
a4a79605 | 306 | |
38ccb557 LP |
307 | nss-resolve enables DNS resolution via the systemd-resolved DNS/LLMNR |
308 | caching stub resolver "systemd-resolved". | |
a4a79605 | 309 | |
409093fe | 310 | nss-mymachines enables resolution of all local containers registered |
38ccb557 | 311 | with machined to their respective IP addresses. |
a4a79605 | 312 | |
38ccb557 | 313 | nss-systemd enables resolution of users/group registered via the |
1d10005b | 314 | User/Group Record Lookup API (https://systemd.io/USER_GROUP_API), |
38ccb557 LP |
315 | including all dynamically allocated service users. (See the |
316 | DynamicUser= setting in unit files.) | |
a4a79605 | 317 | |
409093fe LP |
318 | To make use of these NSS modules, please add them to the "hosts:", |
319 | "passwd:" and "group:" lines in /etc/nsswitch.conf. The "resolve" | |
320 | module should replace the glibc "dns" module in this file (and don't | |
321 | worry, it chain-loads the "dns" module if it can't talk to resolved). | |
a4a79605 | 322 | |
409093fe LP |
323 | The four modules should be used in the following order: |
324 | ||
38ccb557 LP |
325 | passwd: compat systemd |
326 | group: compat systemd | |
a42d4f57 | 327 | hosts: files mymachines resolve [!UNAVAIL=return] dns myhostname |
a4a79605 | 328 | |
0f0467e6 MP |
329 | SYSV INIT.D SCRIPTS: |
330 | When calling "systemctl enable/disable/is-enabled" on a unit which is a | |
331 | SysV init.d script, it calls /usr/lib/systemd/systemd-sysv-install; | |
332 | this needs to translate the action into the distribution specific | |
333 | mechanism such as chkconfig or update-rc.d. Packagers need to provide | |
334 | this script if you need this functionality (you don't if you disabled | |
335 | SysV init support). | |
336 | ||
337 | Please see src/systemctl/systemd-sysv-install.SKELETON for how this | |
338 | needs to look like, and provide an implementation at the marked places. | |
339 | ||
88a3af94 | 340 | WARNINGS and TAINT FLAGS: |
9e93f6f0 LP |
341 | systemd will warn during early boot if /usr is not already mounted at |
342 | this point (that means: either located on the same file system as / or | |
343 | already mounted in the initrd). While in systemd itself very little | |
88a3af94 ZJS |
344 | will break if /usr is on a separate late-mounted partition, many of its |
345 | dependencies very likely will break sooner or later in one form or | |
9e93f6f0 LP |
346 | another. For example, udev rules tend to refer to binaries in /usr, |
347 | binaries that link to libraries in /usr or binaries that refer to data | |
348 | files in /usr. Since these breakages are not always directly visible, | |
88a3af94 ZJS |
349 | systemd will warn about this. Such setups are not really supported by |
350 | the basic set of Linux OS components. Taint flag 'split-usr' will be | |
351 | set when this condition is detected. | |
47bc23c1 | 352 | |
aa167132 | 353 | For more information on this issue consult |
c6749ba5 | 354 | https://www.freedesktop.org/wiki/Software/systemd/separate-usr-is-broken |
aa167132 | 355 | |
88a3af94 ZJS |
356 | systemd requires that the /run mount point exists. systemd also |
357 | requires that /var/run is a symlink to /run. Taint flag 'var-run-bad' | |
358 | will be set when this condition is detected. | |
359 | ||
360 | Systemd will also warn when the cgroup support is unavailable in the | |
361 | kernel (taint flag 'cgroups-missing'), the system is using the old | |
362 | cgroup hierarchy (taint flag 'cgroupsv1'), the hardware clock is | |
363 | running in non-UTC mode (taint flag 'local-hwclock'), the kernel | |
364 | overflow UID or GID are not 65534 (taint flags 'overflowuid-not-65534' | |
365 | and 'overflowgid-not-65534'), the UID or GID range assigned to the | |
366 | running systemd instance covers less than 0…65534 (taint flags | |
367 | 'short-uid-range' and 'short-gid-range'). | |
368 | ||
369 | Taint conditions are logged during boot, but may also be checked at any | |
370 | time with: | |
371 | ||
372 | busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Tainted | |
373 | ||
374 | VALGRIND: | |
d18cb393 ZJS |
375 | To run systemd under valgrind, compile with meson option |
376 | -Dvalgrind=true and have valgrind development headers installed | |
377 | (i.e. valgrind-devel or equivalent). Otherwise, false positives will be | |
378 | triggered by code which violates some rules but is actually safe. Note | |
379 | that valgrind generates nice output only on exit(), hence on shutdown | |
380 | we don't execve() systemd-shutdown. | |
2b671e95 | 381 | |
ba9e3fc4 | 382 | STABLE BRANCHES AND BACKPORTS: |
bfeb370a LP |
383 | Stable branches with backported patches are available in the |
384 | systemd-stable repo at https://github.com/systemd/systemd-stable. | |
385 | ||
386 | Stable branches are started for certain releases of systemd and named | |
387 | after them, e.g. v238-stable. Stable branches are managed by | |
388 | distribution maintainers on an as needed basis. See | |
389 | https://www.freedesktop.org/wiki/Software/systemd/Backports/ for some | |
390 | more information and examples. |