]>
Commit | Line | Data |
---|---|---|
d657c51f | 1 | systemd System and Service Manager |
31cee6f6 LP |
2 | |
3 | DETAILS: | |
4 | http://0pointer.de/blog/projects/systemd.html | |
5 | ||
6 | WEB SITE: | |
19d9372b | 7 | https://www.freedesktop.org/wiki/Software/systemd |
31cee6f6 LP |
8 | |
9 | GIT: | |
eb0914fc | 10 | git@github.com:systemd/systemd.git |
eb0914fc | 11 | https://github.com/systemd/systemd |
31cee6f6 LP |
12 | |
13 | MAILING LIST: | |
19d9372b | 14 | https://lists.freedesktop.org/mailman/listinfo/systemd-devel |
31cee6f6 LP |
15 | |
16 | IRC: | |
17 | #systemd on irc.freenode.org | |
18 | ||
19 | BUG REPORTS: | |
eb0914fc | 20 | https://github.com/systemd/systemd/issues |
31cee6f6 LP |
21 | |
22 | AUTHOR: | |
5430f7f2 LP |
23 | Lennart Poettering |
24 | Kay Sievers | |
25 | ...and many others | |
31cee6f6 | 26 | |
673eab9b | 27 | LICENSE: |
5430f7f2 | 28 | LGPLv2.1+ for all code |
a095315b KS |
29 | - except src/basic/MurmurHash2.c which is Public Domain |
30 | - except src/basic/siphash24.c which is CC0 Public Domain | |
85424725 KS |
31 | - except src/journal/lookup3.c which is Public Domain |
32 | - except src/udev/* which is (currently still) GPLv2, GPLv2+ | |
673eab9b | 33 | |
31cee6f6 | 34 | REQUIREMENTS: |
dcce98a4 | 35 | Linux kernel >= 3.13 |
a0c3e16b | 36 | Linux kernel >= 4.2 for unified cgroup hierarchy support |
23aedd02 KS |
37 | |
38 | Kernel Config Options: | |
713bc0cf | 39 | CONFIG_DEVTMPFS |
d28315e4 | 40 | CONFIG_CGROUPS (it is OK to disable all controllers) |
713bc0cf KS |
41 | CONFIG_INOTIFY_USER |
42 | CONFIG_SIGNALFD | |
43 | CONFIG_TIMERFD | |
44 | CONFIG_EPOLL | |
41938693 | 45 | CONFIG_NET |
713bc0cf | 46 | CONFIG_SYSFS |
06d461ee | 47 | CONFIG_PROC_FS |
5d31974e | 48 | CONFIG_FHANDLE (libudev, mount and bind mount handling) |
713bc0cf | 49 | |
9c7f7d86 MG |
50 | Kernel crypto/hash API |
51 | CONFIG_CRYPTO_USER_API_HASH | |
52 | CONFIG_CRYPTO_HMAC | |
53 | CONFIG_CRYPTO_SHA256 | |
54 | ||
be2ea723 | 55 | udev will fail to work with the legacy sysfs layout: |
f28cbd03 | 56 | CONFIG_SYSFS_DEPRECATED=n |
713bc0cf KS |
57 | |
58 | Legacy hotplug slows down the system and confuses udev: | |
59 | CONFIG_UEVENT_HELPER_PATH="" | |
60 | ||
be2ea723 KS |
61 | Userspace firmware loading is not supported and should |
62 | be disabled in the kernel: | |
713bc0cf KS |
63 | CONFIG_FW_LOADER_USER_HELPER=n |
64 | ||
65 | Some udev rules and virtualization detection relies on it: | |
66 | CONFIG_DMIID | |
67 | ||
a5c724b2 KS |
68 | Support for some SCSI devices serial number retrieval, to |
69 | create additional symlinks in /dev/disk/ and /dev/tape: | |
70 | CONFIG_BLK_DEV_BSG | |
71 | ||
0ca48bb0 | 72 | Required for PrivateNetwork= and PrivateDevices= in service units: |
13468826 | 73 | CONFIG_NET_NS |
b52a4a3b ZJS |
74 | CONFIG_DEVPTS_MULTIPLE_INSTANCES |
75 | Note that systemd-localed.service and other systemd units use | |
76 | PrivateNetwork and PrivateDevices so this is effectively required. | |
13468826 | 77 | |
0ca48bb0 | 78 | Required for PrivateUsers= in service units: |
87fe1707 LW |
79 | CONFIG_USER_NS |
80 | ||
713bc0cf KS |
81 | Optional but strongly recommended: |
82 | CONFIG_IPV6 | |
83 | CONFIG_AUTOFS4_FS | |
713bc0cf | 84 | CONFIG_TMPFS_XATTR |
a6cccd8f | 85 | CONFIG_{TMPFS,EXT4,XFS,BTRFS_FS,...}_POSIX_ACL |
f28cbd03 | 86 | CONFIG_SECCOMP |
fd74fa79 | 87 | CONFIG_SECCOMP_FILTER (required for seccomp support) |
3b920d78 | 88 | CONFIG_CHECKPOINT_RESTORE (for the kcmp() syscall) |
713bc0cf | 89 | |
f4e74be1 | 90 | Required for CPUShares= in resource control unit settings |
a21b4670 UTL |
91 | CONFIG_CGROUP_SCHED |
92 | CONFIG_FAIR_GROUP_SCHED | |
93 | ||
f4e74be1 | 94 | Required for CPUQuota= in resource control unit settings |
0acd5a08 WC |
95 | CONFIG_CFS_BANDWIDTH |
96 | ||
b1b96380 AJ |
97 | Required for IPAddressDeny= and IPAddressAllow= in resource control |
98 | unit settings | |
99 | CONFIG_CGROUP_BPF | |
100 | ||
f28cbd03 | 101 | For UEFI systems: |
f33016ff | 102 | CONFIG_EFIVAR_FS |
f28cbd03 KS |
103 | CONFIG_EFI_PARTITION |
104 | ||
f4e74be1 LP |
105 | We recommend to turn off Real-Time group scheduling in the |
106 | kernel when using systemd. RT group scheduling effectively | |
107 | makes RT scheduling unavailable for most userspace, since it | |
108 | requires explicit assignment of RT budgets to each unit whose | |
109 | processes making use of RT. As there's no sensible way to | |
110 | assign these budgets automatically this cannot really be | |
111 | fixed, and it's best to disable group scheduling hence. | |
112 | CONFIG_RT_GROUP_SCHED=n | |
113 | ||
f5a93d5d LP |
114 | It's a good idea to disable the implicit creation of networking bonding |
115 | devices by the kernel networking bonding module, so that the | |
116 | automatically created "bond0" interface doesn't conflict with any such | |
582faeb4 DJL |
117 | device created by systemd-networkd (or other tools). Ideally there |
118 | would be a kernel compile-time option for this, but there currently | |
119 | isn't. The next best thing is to make this change through a modprobe.d | |
120 | drop-in. This is shipped by default, see modprobe.d/systemd.conf. | |
f5a93d5d | 121 | |
77b6e194 LP |
122 | Note that kernel auditing is broken when used with systemd's |
123 | container code. When using systemd in conjunction with | |
19aadacf | 124 | containers, please make sure to either turn off auditing at |
77b6e194 LP |
125 | runtime using the kernel command line option "audit=0", or |
126 | turn it off at kernel compile time using: | |
127 | CONFIG_AUDIT=n | |
a7b1c397 LP |
128 | If systemd is compiled with libseccomp support on |
129 | architectures which do not use socketcall() and where seccomp | |
130 | is supported (this effectively means x86-64 and ARM, but | |
70a44afe | 131 | excludes 32-bit x86!), then nspawn will now install a |
a7b1c397 LP |
132 | work-around seccomp filter that makes containers boot even |
133 | with audit being enabled. This works correctly only on kernels | |
134 | 3.14 and newer though. TL;DR: turn audit off, still. | |
77b6e194 | 135 | |
3dd26f3e | 136 | glibc >= 2.16 |
3ede835a | 137 | libcap |
d6e80966 ZJS |
138 | libmount >= 2.30 (from util-linux) |
139 | (util-linux *must* be built without --enable-libmount-support-mtab) | |
6abfd303 | 140 | libseccomp >= 2.3.1 (optional) |
d47f6ca5 | 141 | libblkid >= 2.24 (from util-linux) (optional) |
a18535d9 | 142 | libkmod >= 15 (optional) |
3ede835a LP |
143 | PAM >= 1.1.2 (optional) |
144 | libcryptsetup (optional) | |
145 | libaudit (optional) | |
19d5d4cb | 146 | libacl (optional) |
3ede835a | 147 | libselinux (optional) |
19d5d4cb | 148 | liblzma (optional) |
a509e0e6 | 149 | liblz4 >= 119 (optional) |
7b17a7d7 LP |
150 | libgcrypt (optional) |
151 | libqrencode (optional) | |
152 | libmicrohttpd (optional) | |
2cc86f09 | 153 | libpython (optional) |
87057e24 | 154 | libidn2 or libidn (optional) |
5b244719 | 155 | elfutils >= 158 (optional) |
d79a2f5f | 156 | polkit (optional) |
72cdb3e7 | 157 | pkg-config |
8f968c73 | 158 | gperf |
72cdb3e7 ZJS |
159 | docbook-xsl (optional, required for documentation) |
160 | xsltproc (optional, required for documentation) | |
161 | python-lxml (optional, required to build the indices) | |
162 | python, meson, ninja | |
163 | gcc, awk, sed, grep, m4, and similar tools | |
2cc86f09 | 164 | |
19aadacf JE |
165 | During runtime, you need the following additional |
166 | dependencies: | |
2cc86f09 | 167 | |
1d40ddbf | 168 | util-linux >= v2.27.1 required |
ecf4f0a8 MG |
169 | dbus >= 1.4.0 (strictly speaking optional, but recommended) |
170 | NOTE: If using dbus < 1.9.18, you should override the default | |
171 | policy directory (--with-dbuspolicydir=/etc/dbus-1/system.d). | |
2cc86f09 | 172 | dracut (optional) |
46ba8aae | 173 | PolicyKit (optional) |
3ede835a | 174 | |
3e609a8a ZJS |
175 | To build in directory build/: |
176 | meson build/ && ninja -C build | |
177 | ||
178 | Any configuration options can be specfied as -Darg=value... arguments | |
179 | to meson. After the build directory is initially configured, meson will | |
180 | refuse to run again, and options must be changed with: | |
181 | mesonconf -Darg=value... | |
182 | mesonconf without any arguments will print out available options and | |
183 | their current values. | |
184 | ||
185 | Useful commands: | |
186 | ninja -v some/target | |
187 | ninja test | |
188 | sudo ninja install | |
189 | DESTDIR=... ninja install | |
190 | ||
72cdb3e7 | 191 | A tarball can be created with: |
82627069 KS |
192 | git archive --format=tar --prefix=systemd-222/ v222 | xz > systemd-222.tar.xz |
193 | ||
19aadacf JE |
194 | When systemd-hostnamed is used, it is strongly recommended to |
195 | install nss-myhostname to ensure that, in a world of | |
196 | dynamically changing hostnames, the hostname stays resolvable | |
fff2e5b5 | 197 | under all circumstances. In fact, systemd-hostnamed will warn |
bf9e477c | 198 | if nss-myhostname is not installed. |
fff2e5b5 | 199 | |
01c8938e LP |
200 | nss-systemd must be enabled on systemd systems, as that's required for |
201 | DynamicUser= to work. Note that we ship services out-of-the-box that | |
202 | make use of DynamicUser= now, hence enabling nss-systemd is not | |
203 | optional. | |
204 | ||
205 | Note that the build prefix for systemd must be /usr. -Dsplit-usr=false | |
206 | (which is the default and does not need to be specified) is the | |
207 | recommended setting, and -Dsplit-usr=true should be used on systems | |
208 | which have /usr on a separate partition. | |
209 | ||
a2fc3d87 ZJS |
210 | Additional packages are necessary to run some tests: |
211 | - busybox (used by test/TEST-13-NSPAWN-SMOKE) | |
212 | - nc (used by test/TEST-12-ISSUE-3171) | |
213 | - python3-pyparsing | |
214 | - python3-evdev (used by hwdb parsing tests) | |
215 | - strace (used by test/test-functions) | |
e94681ad | 216 | - capsh (optional, used by test-execute) |
a2fc3d87 | 217 | |
a24c64f0 | 218 | USERS AND GROUPS: |
37495eed LP |
219 | Default udev rules use the following standard system group |
220 | names, which need to be resolvable by getgrnam() at any time, | |
221 | even in the very early boot stages, where no other databases | |
222 | and network are available: | |
223 | ||
2422bd21 | 224 | audio, cdrom, dialout, disk, input, kmem, kvm, lp, render, tape, tty, video |
37c0e8f3 | 225 | |
19aadacf | 226 | During runtime, the journal daemon requires the |
1a9ce3f7 | 227 | "systemd-journal" system group to exist. New journal files will |
19aadacf | 228 | be readable by this group (but not writable), which may be used |
a48a62a1 ZJS |
229 | to grant specific users read access. In addition, system |
230 | groups "wheel" and "adm" will be given read-only access to | |
231 | journal files using systemd-tmpfiles.service. | |
a24c64f0 | 232 | |
37495eed | 233 | The journal gateway daemon requires the |
1a9ce3f7 | 234 | "systemd-journal-gateway" system user and group to |
37495eed LP |
235 | exist. During execution this network facing service will drop |
236 | privileges and assume this uid/gid for security reasons. | |
237 | ||
8d0e0ddd | 238 | Similarly, the NTP daemon requires the "systemd-timesync" system |
323a2f0b LP |
239 | user and group to exist. |
240 | ||
8d0e0ddd | 241 | Similarly, the network management daemon requires the |
323a2f0b LP |
242 | "systemd-network" system user and group to exist. |
243 | ||
8d0e0ddd | 244 | Similarly, the name resolution daemon requires the |
323a2f0b LP |
245 | "systemd-resolve" system user and group to exist. |
246 | ||
888e378d LP |
247 | Similarly, the coredump support requires the |
248 | "systemd-coredump" system user and group to exist. | |
249 | ||
a4a79605 | 250 | NSS: |
409093fe | 251 | systemd ships with four glibc NSS modules: |
a4a79605 LP |
252 | |
253 | nss-myhostname resolves the local hostname to locally | |
254 | configured IP addresses, as well as "localhost" to | |
255 | 127.0.0.1/::1. | |
256 | ||
257 | nss-resolve enables DNS resolution via the systemd-resolved | |
258 | DNS/LLMNR caching stub resolver "systemd-resolved". | |
259 | ||
409093fe LP |
260 | nss-mymachines enables resolution of all local containers registered |
261 | with machined to their respective IP addresses. It also maps UID/GIDs | |
262 | ranges used by containers to useful names. | |
a4a79605 | 263 | |
409093fe LP |
264 | nss-systemd enables resolution of all dynamically allocated service |
265 | users. (See the DynamicUser= setting in unit files.) | |
a4a79605 | 266 | |
409093fe LP |
267 | To make use of these NSS modules, please add them to the "hosts:", |
268 | "passwd:" and "group:" lines in /etc/nsswitch.conf. The "resolve" | |
269 | module should replace the glibc "dns" module in this file (and don't | |
270 | worry, it chain-loads the "dns" module if it can't talk to resolved). | |
a4a79605 | 271 | |
409093fe LP |
272 | The four modules should be used in the following order: |
273 | ||
274 | passwd: compat mymachines systemd | |
275 | group: compat mymachines systemd | |
a4a79605 LP |
276 | hosts: files mymachines resolve myhostname |
277 | ||
0f0467e6 MP |
278 | SYSV INIT.D SCRIPTS: |
279 | When calling "systemctl enable/disable/is-enabled" on a unit which is a | |
280 | SysV init.d script, it calls /usr/lib/systemd/systemd-sysv-install; | |
281 | this needs to translate the action into the distribution specific | |
282 | mechanism such as chkconfig or update-rc.d. Packagers need to provide | |
283 | this script if you need this functionality (you don't if you disabled | |
284 | SysV init support). | |
285 | ||
286 | Please see src/systemctl/systemd-sysv-install.SKELETON for how this | |
287 | needs to look like, and provide an implementation at the marked places. | |
288 | ||
21bc923a | 289 | WARNINGS: |
9e93f6f0 LP |
290 | systemd will warn during early boot if /usr is not already mounted at |
291 | this point (that means: either located on the same file system as / or | |
292 | already mounted in the initrd). While in systemd itself very little | |
293 | will break if /usr is on a separate, late-mounted partition, many of | |
294 | its dependencies very likely will break sooner or later in one form or | |
295 | another. For example, udev rules tend to refer to binaries in /usr, | |
296 | binaries that link to libraries in /usr or binaries that refer to data | |
297 | files in /usr. Since these breakages are not always directly visible, | |
298 | systemd will warn about this, since this kind of file system setup is | |
299 | not really supported anymore by the basic set of Linux OS components. | |
fc7a744c | 300 | |
47bc23c1 | 301 | systemd requires that the /run mount point exists. systemd also |
8f42ccd2 | 302 | requires that /var/run is a symlink to /run. |
47bc23c1 | 303 | |
aa167132 | 304 | For more information on this issue consult |
c6749ba5 | 305 | https://www.freedesktop.org/wiki/Software/systemd/separate-usr-is-broken |
aa167132 | 306 | |
1b4bb4fd | 307 | To run systemd under valgrind, compile with VALGRIND defined |
7817154d MS |
308 | (e.g. CPPFLAGS='... -DVALGRIND=1' meson <options>) and have valgrind |
309 | development headers installed (i.e. valgrind-devel or | |
310 | equivalent). Otherwise, false positives will be triggered by code which | |
311 | violates some rules but is actually safe. Note that valgrind generates | |
312 | nice output only on exit(), hence on shutdown we don't execve() | |
313 | systemd-shutdown. | |
2b671e95 | 314 | |
ada64a0c LP |
315 | ENGINEERING AND CONSULTING SERVICES: |
316 | Kinvolk (https://kinvolk.io) offers professional engineering | |
317 | and consulting services for systemd. Please contact Chris Kühl | |
318 | <chris@kinvolk.io> for more information. |