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