diff --git a/docs/BOOT_LOADER_SPECIFICATION.md b/docs/BOOT_LOADER_SPECIFICATION.md index f4d7f211b6..55a9fef4be 100644 --- a/docs/BOOT_LOADER_SPECIFICATION.md +++ b/docs/BOOT_LOADER_SPECIFICATION.md @@ -4,20 +4,33 @@ title: The Boot Loader Specification # The Boot Loader Specification -_TL;DR: Currently there's little cooperation between multiple distributions in dual-boot (or triple, ... multi-boot) setups, and we'd like to improve this situation by getting everybody to commit to a single boot configuration format that is based on drop-in files, and thus is robust, simple, works without rewriting configuration files and is free of namespace clashes._ +_TL;DR: Currently there's no common boot scheme across architectures and +platforms for open-source operating systems. There's also little cooperation +between multiple distributions in dual-boot (or triple, … multi-boot) +setups. We'd like to improve this situation by getting everybody to commit to a +single boot configuration format that is based on drop-in files, and thus is +robust, simple, works without rewriting configuration files and is free of +namespace clashes._ -The Boot Loader Specification defines a scheme how different operating systems can cooperatively manage a boot loader configuration directory, that accepts drop-in files for boot menu items that are defined in a format that is shared between various boot loader implementations, operating systems, and userspace programs. The target audience for this specification is: +The Boot Loader Specification defines a scheme how different operating systems +can cooperatively manage a boot loader configuration directory, that accepts +drop-in files for boot menu items that are defined in a format that is shared +between various boot loader implementations, operating systems, and userspace +programs. The same scheme can be used to prepare OS media for cases where the +firmware includes a boot loader. The target audience for this specification is: * Boot loader developers, to write a boot loader that directly reads its configuration at runtime from these drop-in snippets +* Firmware developers, to add generic boot loading support directly to the firmware itself * Distribution and Core OS developers, in order to create these snippets at OS/kernel package installation time * UI developers, for implementing a user interface that discovers the available boot options -* OS Installer developers, for setting up the initial drop-in directory +* OS Installer developers, to prepare their installation media and for setting up the initial drop-in directory ## Why is there a need for this specification? Of course, without this specification things already work mostly fine. But here's why we think this specification is needed: * To make the boot more robust, as no explicit rewriting of configuration files is required any more +* To allow an out of the box boot experience on any platform without the need of traditional firmware mechanisms (e.g. BIOS calls, UEFI Boot Services) * To improve dual-boot scenarios. Currently, multiple Linux installations tend to fight over which boot loader becomes the primary one in possession of the MBR, and only that one installation can then update the boot loader configuration of it freely. Other Linux installs have to be manually configured to never touch the MBR and instead install a chain-loaded boot loader in their own partition headers. In this new scheme as all installations share a loader directory no manual configuration has to take place, and all participants implicitly cooperate due to removal of name collisions and can install/remove their own boot menu entries at free will, without interfering with the entries of other installed operating systems. * Drop-in directories are otherwise now pretty ubiquitous on Linux as an easy way to extend configuration without having to edit, regenerate or manipulate configuration files. For the sake of uniformity, we should do the same for extending the boot menu. * Userspace code can sanely parse boot loader configuration which is essential with modern BIOSes which do not necessarily initialize USB keyboards anymore during boot, which makes boot menus hard to reach for the user. If userspace code can parse the boot loader configuration, too, this allows for UIs that can select a boot menu item to boot into, before rebooting the machine, thus not requiring interactivity during early boot. @@ -26,7 +39,9 @@ Of course, without this specification things already work mostly fine. But here' ## Why not simply rely on the EFI boot menu logic? -The EFI specification provides a boot options logic that can offer similar functionality. Here's why we think that it is not enough for our uses: +EFI is not ubiquitous, especially not in embedded systems. If you have an EFI +system, it provides a boot options logic that can offer similar +functionality. Here's why we think that it is not enough for our uses: * The various EFI implementations implement the boot order/boot item logic to different levels. Some firmware implementations do not offer a boot menu at all and instead unconditionally follow the EFI boot order, booting the first item that is working. * If the firmware setup is used to reset all data usually all EFI boot entries are lost, making the system entirely unbootable, as the firmware setups generally do not offer a UI to define additional boot items. By placing the menu item information on disk, it is always available, regardless if the BIOS setup data is lost. @@ -51,7 +66,12 @@ This placeholder file system shall be determined during _installation time_, and **Note:** _`$BOOT` should be considered **shared** among all OS installations of a system. Instead of maintaining one `$BOOT` per installed OS (as `/boot/` was traditionally handled), all installed OS share the same place to drop in their boot-time configuration._ -For systems where the firmware is able to read file systems directly, `$BOOT` must be a file system readable by the firmware. For other systems, `$BOOT` must be a VFAT (16 or 32) file system. Applications accessing `$BOOT` should hence not assume that fancier file system features such as symlinks, hardlinks, access control or case sensitivity are supported. +For systems where the firmware is able to read file systems directly, `$BOOT` +must be a file system readable by the firmware. For other systems and generic +installation and live media, `$BOOT` must be a VFAT (16 or 32) file +system. Applications accessing `$BOOT` should hence not assume that fancier +file system features such as symlinks, hardlinks, access control or case +sensitivity are supported. This specification defines two types of boot loader entries. The first type is text based, very simple and suitable for a variety of firmware, architecture @@ -105,7 +125,16 @@ Each configuration drop-in snippet must include at least a `linux` or an `efi` k linux /6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.x86_64/linux initrd /6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.x86_64/initrd -On EFI systems all Linux kernel images should be EFI images. In order to increase compatibility with EFI systems it is highly recommended only to install EFI kernel images, even on non-EFI systems, if that's applicable and supported on the specific architecture. +On EFI systems all Linux kernel images should be EFI images. In order to +increase compatibility with EFI systems it is highly recommended only to +install EFI kernel images, even on non-EFI systems, if that's applicable and +supported on the specific architecture. + +Conversely, in order to increase compatibility it is recommended to install +generic kernel images that make few assumptions about the firmware they run on, +i.e. it is a good idea that both images shipped as UEFI PE images and those +which are not don't make unnecessary assumption on the underlying firmware, +i.e. don't hard depend on legacy BIOS calls or UEFI boot services. Note that these configuration snippets may only reference kernels (and EFI programs) that reside on the same file system as the configuration snippets, i.e. everything referenced must be contained in the same file system. This is by design, as referencing other partitions or devices would require a non-trivial language for denoting device paths. If kernels/initrds are to be read from other partitions/disks the boot loader can do this in its own native configuration, using its own specific device path language, and this is out of focus for this specification. More specifically, on non-EFI systems configuration snippets following this specification cannot be used to spawn other operating systems (such as Windows). diff --git a/docs/PORTABLE_SERVICES.md b/docs/PORTABLE_SERVICES.md index 5b6c085af0..631d063b01 100644 --- a/docs/PORTABLE_SERVICES.md +++ b/docs/PORTABLE_SERVICES.md @@ -153,9 +153,9 @@ images should just work the way they are. Specifically, the following requirements are made for an image that can be attached/detached with `portablectl`. -1. It must contain a binary (and its dependencies) that shall be invoked, - including all its dependencies. If binary code, the code needs to be - compiled for an architecture compatible with the host. +1. It must contain an executable that shall be invoked, along with all its + dependencies. If binary code, the code needs to be compiled for an + architecture compatible with the host. 2. The image must either be a plain sub-directory (or btrfs subvolume) containing the binaries and its dependencies in a classic Linux OS tree, or @@ -177,15 +177,35 @@ requirements are made for an image that can be attached/detached with 5. The image must contain the files `/etc/resolv.conf` and `/etc/machine-id` (empty files are ok), they will be bind mounted from the host at runtime. -Note that generally images created by tools such as `debootstrap`, `dnf ---installroot=` or `mkosi` qualify for all of the above in one way or -another. If you wonder what the most minimal image would be that complies with -the requirements above, it could consist of this: +6. The image must contain directories `/proc/`, `/sys/`, `/dev/`, `/run/`, + `/tmp/`, `/var/tmp/` that can be mounted over with the corresponding version + from the host. + +7. The OS might require other files or directories to be in place. For example, + if the image is built based on glibc, the dynamic loader needs to be + available in `/lib/ld-linux.so.2` or `/lib64/ld-linux-x86-64.so.2` (or + similar, depending on architecture), and if the distribution implements a + merged `/usr/` tree, this means `/lib` and/or `/lib64` need to be symlinks + to their respective counterparts below `/usr/`. For details see your + distribution's documentation. + +Note that images created by tools such as `debootstrap`, `dnf --installroot=` +or `mkosi` generally qualify for all of the above in one way or another. If you +wonder what the most minimal image would be that complies with the requirements +above, it could consist of this: ``` /usr/bin/minimald # a statically compiled binary /usr/lib/systemd/minimal-test.service # the unit file for the service, with ExecStart=/usr/bin/minimald /usr/lib/os-release # an os-release file explaining what this is +/etc/resolv.conf # empty file to mount over with host's version +/etc/machine-id # ditto +/proc/ # empty directory to use as mount point for host's API fs +/sys/ # ditto +/dev/ # ditto +/run/ # ditto +/tmp/ # ditto +/var/tmp/ # ditto ``` And that's it. @@ -195,6 +215,11 @@ own. If they do, it's fine, it will be ignored by the portable service logic, but they generally don't have to, and it might make sense to avoid any, to keep images minimal. +If the image is writable, and some of the files or directories that are +overmounted from the host do not exist yet they are automatically created. On +read-only, immutable images (e.g. squashfs images) all files and directories to +over-mount must exist already. + Note that as no new image format or metadata is defined, it's very straight-forward to define images than can be made use of it a number of different ways. For example, by using `mkosi -b` you can trivially build a diff --git a/man/daemon.xml b/man/daemon.xml index 7724bb4e08..41da01943c 100644 --- a/man/daemon.xml +++ b/man/daemon.xml @@ -77,9 +77,10 @@ setsid() to detach from any terminal and create an independent session. - In the child, call fork() - again, to ensure that the daemon can never re-acquire a - terminal again. + In the child, call fork() again, to ensure that the daemon can + never re-acquire a terminal again. (This relevant if the program — and all its dependencies — does + not carefully specify `O_NOCTTY` on each and every single `open()` call that might potentially open a + TTY device node.) Call exit() in the first child, so that only the second child (the actual daemon @@ -244,6 +245,10 @@ and systemd.exec5. + As new-style daemons are invoked without a controlling TTY (but as their own session + leaders) care should be taken to always specify `O_NOCTTY` on `open()` calls that possibly reference + a TTY device node, so that no controlling TTY is accidentally acquired. + These recommendations are similar but not identical to the diff --git a/man/system-only.xml b/man/system-only.xml new file mode 100644 index 0000000000..94aa08bd6d --- /dev/null +++ b/man/system-only.xml @@ -0,0 +1,16 @@ + + + + + + + +This option is only available for system services and is not supported for services +running in per-user instances of the service manager. + +These options are only available for system services and are not supported for services +running in per-user instances of the service manager. + + diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml index 00c14eafeb..e4373ba691 100644 --- a/man/systemd-nspawn.xml +++ b/man/systemd-nspawn.xml @@ -614,6 +614,16 @@ Note that is the default if the systemd-nspawn@.service template unit file is used. + + Note that on Linux network interface names may have a length of 15 characters at maximum, while + container names may have a length up to 64 characters. As this option derives the host-side interface + name from the container name the name is possibly truncated. Thus, care needs to be taken to ensure + that interface names remain unique in this case, or even better container names are generally not + chosen longer than 12 characters, to avoid the truncation. Alternatively, the + option may be used, which allows free configuration of the + host-side interface name independently of the container name — but might require a bit more + additional configuration in case bridging in a fashion similar to + is desired. @@ -635,11 +645,13 @@ - Adds the host side of the Ethernet link created with to the - specified Ethernet bridge interface. Expects a valid network interface name of a bridge device as - argument. Note that implies . If this option - is used, the host side of the Ethernet link will use the vb- prefix instead of - ve-. + Adds the host side of the Ethernet link created with + to the specified Ethernet bridge interface. Expects a valid network interface name of a bridge device + as argument. Note that implies . If + this option is used, the host side of the Ethernet link will use the vb- prefix + instead of ve-. Regardless of the used naming prefix the same network interface + name length limits imposed by Linux apply, along with the complications this creates (for details see + above). diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index 0ef2d88ea1..35df21f710 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -6,7 +6,7 @@ SPDX-License-Identifier: LGPL-2.1+ --> - + systemd.exec systemd @@ -112,7 +112,9 @@ dependencies to be added to the unit (see above). The MountAPIVFS= and PrivateUsers= settings are particularly useful - in conjunction with RootDirectory=. For details, see below. + in conjunction with RootDirectory=. For details, see below. + + @@ -126,14 +128,17 @@ url="https://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/">Discoverable Partitions Specification. - When DevicePolicy= is set to closed or strict, - or set to auto and DeviceAllow= is set, then this setting adds - /dev/loop-control with rw mode, block-loop and - block-blkext with rwm mode to DeviceAllow=. See + When DevicePolicy= is set to closed or + strict, or set to auto and DeviceAllow= is + set, then this setting adds /dev/loop-control with rw mode, + block-loop and block-blkext with rwm mode + to DeviceAllow=. See systemd.resource-control5 for the details about DevicePolicy= or DeviceAllow=. Also, see - PrivateDevices= below, as it may change the setting of DevicePolicy=. - + PrivateDevices= below, as it may change the setting of + DevicePolicy=. + + @@ -147,7 +152,9 @@ will be a 1:1 copy of the host's, and include these three mounts. Note that the /dev file system of the host is bind mounted if this option is used without PrivateDevices=. To run the service with a private, minimal version of /dev/, combine this option with - PrivateDevices=. + PrivateDevices=. + + @@ -174,7 +181,9 @@ This option is particularly useful when RootDirectory=/RootImage= is used. In this case the source path refers to a path on the host file system, while the destination path - refers to a path below the root directory of the unit. + refers to a path below the root directory of the unit. + + @@ -183,6 +192,8 @@ Credentials + + @@ -306,6 +317,8 @@ Capabilities + + @@ -402,6 +415,9 @@ CapabilityBoundingSet=~CAP_B CAP_C Mandatory Access Control + + + @@ -815,7 +831,9 @@ CapabilityBoundingSet=~CAP_B CAP_C ones), to ensure they cannot get access to private user data, unless the services actually require access to the user's private data. This setting is implied if DynamicUser= is set. This setting cannot ensure protection in all cases. In general it has the same limitations as ReadOnlyPaths=, - see below. + see below. + + @@ -1009,7 +1027,9 @@ StateDirectory=aaa/bbb ccc Note that the effect of these settings may be undone by privileged processes. In order to set up an effective sandboxed environment for a unit it is thus recommended to combine these settings with either CapabilityBoundingSet=~CAP_SYS_ADMIN or - SystemCallFilter=~@mount. + SystemCallFilter=~@mount. + + @@ -1032,7 +1052,9 @@ StateDirectory=aaa/bbb ccc TemporaryFileSystem=/var:ro BindReadOnlyPaths=/var/lib/systemd then the invoked processes by the unit cannot see any files or directories under /var except for - /var/lib/systemd or its contents. + /var/lib/systemd or its contents. + + @@ -1057,7 +1079,9 @@ BindReadOnlyPaths=/var/lib/systemd Note that the implementation of this setting might be impossible (for example if mount namespaces are not available), and the unit should be written in a way that does not solely rely on this setting for - security. + security. + + @@ -1087,7 +1111,9 @@ BindReadOnlyPaths=/var/lib/systemd Note that the implementation of this setting might be impossible (for example if mount namespaces are not available), and the unit should be written in a way that does not solely rely on this setting for - security. + security. + + @@ -1114,7 +1140,9 @@ BindReadOnlyPaths=/var/lib/systemd When this option is used on a socket unit any sockets bound on behalf of this unit will be bound within a private network namespace. This may be combined with JoinsNamespaceOf= to listen on sockets inside of network namespaces of other - services. + services. + + @@ -1131,7 +1159,9 @@ BindReadOnlyPaths=/var/lib/systemd units is reused. When this option is used on a socket unit any sockets bound on behalf of this unit will be - bound within the specified network namespace. + bound within the specified network namespace. + + @@ -1157,7 +1187,9 @@ BindReadOnlyPaths=/var/lib/systemd Note that the implementation of this setting might be impossible (for example if user namespaces are not available), and the unit should be written in a way that does not solely rely on this setting for - security. + security. + + @@ -1172,7 +1204,9 @@ BindReadOnlyPaths=/var/lib/systemd Note that when this option is enabled for a service hostname changes no longer propagate from the system into the service, it is hence not suitable for services that need to take notice of system - hostname changes dynamically. + hostname changes dynamically. + + @@ -1193,7 +1227,9 @@ BindReadOnlyPaths=/var/lib/systemd option does not prevent indirect changes to kernel tunables effected by IPC calls to other processes. However, InaccessiblePaths= may be used to make relevant IPC file system objects inaccessible. If ProtectKernelTunables= is set, MountAPIVFS=yes is - implied. + implied. + + @@ -1212,7 +1248,9 @@ BindReadOnlyPaths=/var/lib/systemd kernel.modules_disabled mechanism and /proc/sys/kernel/modules_disabled documentation. If turned on and if running in user mode, or in system mode, but without the CAP_SYS_ADMIN capability (e.g. setting - User=), NoNewPrivileges=yes is implied. + User=), NoNewPrivileges=yes is implied. + + @@ -1225,7 +1263,9 @@ BindReadOnlyPaths=/var/lib/systemd it is hence recommended to turn this on for most services. For this setting the same restrictions regarding mount propagation and privileges apply as for ReadOnlyPaths= and related calls, see above. Defaults to off. If ProtectControlGroups= is set, MountAPIVFS=yes - is implied. + is implied. + + @@ -1364,7 +1404,9 @@ RestrictNamespaces=~cgroup net DynamicUser= are used. It has no effect on IPC objects owned by the root user. Specifically, this removes System V semaphores, as well as System V and POSIX shared memory segments and message queues. If multiple units use the same user or group the IPC objects are removed when the last of these units is - stopped. This setting is implied if DynamicUser= is set. + stopped. This setting is implied if DynamicUser= is set. + + @@ -1397,7 +1439,9 @@ RestrictNamespaces=~cgroup net ProtectHome=, ReadOnlyPaths=, InaccessiblePaths=, ReadWritePaths=, … — also enable file system namespacing in a fashion equivalent to this option. Hence it is primarily useful to explicitly request this behaviour if none of the other settings are - used. + used. + + @@ -1426,7 +1470,8 @@ RestrictNamespaces=~cgroup net Usually, it is best to leave this setting unmodified, and use higher level file system namespacing options instead, in particular PrivateMounts=, see above. - + + diff --git a/man/systemd.kill.xml b/man/systemd.kill.xml index 09029c56a3..3a6d076eb1 100644 --- a/man/systemd.kill.xml +++ b/man/systemd.kill.xml @@ -87,22 +87,17 @@ group and the control group continues to exist after stop unless it is empty. - Processes will first be terminated via - SIGTERM (unless the signal to send is - changed via KillSignal=). Optionally, this - is immediately followed by a SIGHUP (if - enabled with SendSIGHUP=). If then, after a - delay (configured via the TimeoutStopSec= - option), processes still remain, the termination request is - repeated with the SIGKILL signal or the - signal specified via FinalKillSignal= (unless - this is disabled via the SendSIGKILL= - option). See - kill2 - for more information. + Processes will first be terminated via SIGTERM (unless the signal to send + is changed via KillSignal=). Optionally, this is immediately followed by a + SIGHUP (if enabled with SendSIGHUP=). If processes still + remain after the main process of a unit has exited or the delay configured via the + TimeoutStopSec= has passed, the termination request is repeated with the + SIGKILL signal or the signal specified via FinalKillSignal= + (unless this is disabled via the SendSIGKILL= option). See + kill2 for more + information. - Defaults to - . + Defaults to . diff --git a/man/systemd.network.xml b/man/systemd.network.xml index b06785046d..19e4f59edd 100644 --- a/man/systemd.network.xml +++ b/man/systemd.network.xml @@ -630,6 +630,11 @@ url="https://www.kernel.org/doc/Documentation/networking/ip-sysctl.txt">ip-sysctl.txt in the kernel documentation regarding accept_ra, but note that systemd's setting of 1 (i.e. true) corresponds to kernel's setting of 2. + + Note that if this option is enabled a userspace implementation of the IPv6 RA protocol is + used, and the kernel's own implementation remains disabled, since `networkd` needs to know all + details supplied in the advertisements, and these are not available from the kernel if the kernel's + own implemenation is used. @@ -1263,6 +1268,11 @@ UseRoutes=, SendHostname=, UseMTU=, VendorClassIdentifier=, UseTimezone=. + + With this option enabled DHCP requests will mimic those generated by Microsoft Windows, in + order to reduce the ability to fingerprint and recognize installations. This means DHCP request + sizes will grow and lease data will be more comprehensive than normally, though most of the + requested data is not actually used.