diff --git a/docs/BOOT_LOADER_SPECIFICATION.md b/docs/BOOT_LOADER_SPECIFICATION.md index 3d40df760b..6df522c9e7 100644 --- a/docs/BOOT_LOADER_SPECIFICATION.md +++ b/docs/BOOT_LOADER_SPECIFICATION.md @@ -91,6 +91,20 @@ from the user. Only entries matching the feature set of boot loader and system shall be considered and displayed. This allows image builders to put together images that transparently support multiple different architectures. +Note that the `$BOOT` partition is not supposed to be exclusive territory of +this specification. This specification only defines semantics of the `/loader/` +directory inside the file system (see below), but it doesn't intend to define +ownership of the whole file system exclusively. Boot loaders, firmware, and +other software implementating this specification may choose to place other +files and directories in the same file system. For example, boot loaders that +implement this specification might install their own boot code into the `$BOOT` +partition. On systems where `$BOOT` is the ESP this is a particularly common +setup. Implementations of this specification must be able to operate correctly +if files or directories other than `/loader/` are found in the top level +directory. Implementations that add their own files or directories to the file +systems should use well-named directories, to make name collisions between +multiple users of the file system unlikely. + ### Type #1 Boot Loader Specification Entries We define two directories below `$BOOT`: diff --git a/docs/PORTABILITY_AND_STABILITY.md b/docs/PORTABILITY_AND_STABILITY.md index e1aa656b0f..c9cf9f68d3 100644 --- a/docs/PORTABILITY_AND_STABILITY.md +++ b/docs/PORTABILITY_AND_STABILITY.md @@ -4,7 +4,7 @@ category: Interfaces layout: default --- -# Interface Stability Promise +# Interface Portability and Stability Promise systemd provides various interfaces developers and programs might rely on. Starting with version 26 (the first version released with Fedora 15) we promise to keep a number of them stable and compatible for the future. @@ -41,7 +41,7 @@ What does this mean for you? When developing with systemd, don't use any of the Note that this is a promise, not an eternal guarantee. These are our intentions, but if in the future there are very good reasons to change or get rid of an interface we have listed above as stable, then we might take the liberty to do so, despite this promise. However, if we do this, then we'll do our best to provide a smooth and reasonably long transition phase. -# Interface Portability And Stability Chart +## Interface Portability And Stability Chart systemd provides a number of APIs to applications. Below you'll find a table detailing which APIs are considered stable and how portable they are. @@ -72,11 +72,9 @@ A number of systemd's APIs expose Linux or systemd-specific features that cannot Note that not all of these interfaces are our invention (but most), we just adopted them in systemd to make them more prominently implemented. For example, we adopted many Debian facilities in systemd to push it into the other distributions as well. - --- - And now, here's the list of (hopefully) all APIs that we have introduced with systemd: | API | Type | Covered by Interface Stability Promise | Fully documented | Known External Consumers | Reimplementable Independently | Known Other Implementations | systemd Implementation portable to other OSes or non-systemd distributions | @@ -136,7 +134,7 @@ This is not an attempt to comprehensively list all users of these APIs. We are j Of course, one last thing I can't make myself not ask you before we finish here, and before you start reimplementing these APIs in your distribution: are you sure it's time well spent if you work on reimplementing all this code instead of just spending it on adopting systemd on your distro as well? -## Independent operation of systemd programs +## Independent Operation of systemd Programs Some programs in the systemd suite are indended to operate independently of the running init process (or even without an init process, for example when diff --git a/man/halt.xml b/man/halt.xml index 75604b8342..f811b10348 100644 --- a/man/halt.xml +++ b/man/halt.xml @@ -41,9 +41,8 @@ Description - halt, poweroff, - reboot may be used to halt, power-off or reboot - the machine. + halt, poweroff, reboot may be used to + halt, power-off, or reboot the machine. All three commands take the same options. @@ -137,12 +136,15 @@ Notes - These commands are implemented in a way that preserves compatibility with - the original SysV commands. - systemctl1 - verbs halt, poweroff, - reboot provide the same functionality with some additional - features. + These commands are implemented in a way that preserves basic compatibility with the original SysV + commands. systemctl1 + verbs halt, poweroff, reboot provide the same + functionality with some additional features. + + Note that on many SysV systems halt used to be synonymous to + poweroff, i.e. both commands would equally result in powering the machine off. systemd + is more accurate here, and halt results in halting the machine only (leaving power + on), and poweroff is required to actually power it off. diff --git a/man/systemd-fstab-generator.xml b/man/systemd-fstab-generator.xml index 82321c44bf..ab33258858 100644 --- a/man/systemd-fstab-generator.xml +++ b/man/systemd-fstab-generator.xml @@ -98,9 +98,13 @@ rootflags= - Takes the root filesystem mount options to - use. rootflags= is honored by the - initrd. + Takes the root filesystem mount options to use. rootflags= is + honored by the initrd. + + Note that unlike most kernel command line options this setting does not override settings made + in configuration files (specifically: the mount option string in + /etc/fstab). See + systemd-remount-fs.service8. diff --git a/man/systemd-system.conf.xml b/man/systemd-system.conf.xml index e403fa5308..e22b335d30 100644 --- a/man/systemd-system.conf.xml +++ b/man/systemd-system.conf.xml @@ -382,30 +382,14 @@ DefaultLimitRTPRIO= DefaultLimitRTTIME= - These settings control various default - resource limits for units. See - setrlimit2 - for details. The resource limit is possible to specify in two formats, - to set soft and hard limits to the same value, - or to set both limits individually (e.g. DefaultLimitAS=4G:16G). - Use the string infinity to - configure no limit on a specific resource. The multiplicative - suffixes K (=1024), M (=1024*1024) and so on for G, T, P and E - may be used for resource limits measured in bytes - (e.g. DefaultLimitAS=16G). For the limits referring to time values, - the usual time units ms, s, min, h and so on may be used (see - systemd.time7 - for details). Note that if no time unit is specified for - DefaultLimitCPU= the default unit of seconds is - implied, while for DefaultLimitRTTIME= the default - unit of microseconds is implied. Also, note that the effective - granularity of the limits might influence their - enforcement. For example, time limits specified for - DefaultLimitCPU= will be rounded up implicitly to - multiples of 1s. These settings may be overridden in individual units - using the corresponding LimitXXX= directives. Note that these resource - limits are only defaults for units, they are not applied to PID 1 - itself. + These settings control various default resource limits for processes executed by + units. See + setrlimit2 for + details. These settings may be overridden in individual units using the corresponding + LimitXXX= directives, see + systemd.exec5, for + details, and they accept the same parameter syntax. Note that these resource limits are only defaults + for units, they are not applied to the service manager process (i.e. PID 1) itself. diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index 9d98b2b411..c4cada2f27 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -221,12 +221,13 @@ Linux systems. When used in conjunction with DynamicUser= the user/group name specified is - dynamically allocated at the time the service is started, and released at the time the service is stopped — - unless it is already allocated statically (see below). If DynamicUser= is not used the - specified user and group must have been created statically in the user database no later than the moment the - service is started, for example using the - sysusers.d5 facility, which - is applied at boot or package install time. + dynamically allocated at the time the service is started, and released at the time the service is + stopped — unless it is already allocated statically (see below). If DynamicUser= + is not used the specified user and group must have been created statically in the user database no + later than the moment the service is started, for example using the + sysusers.d5 + facility, which is applied at boot or package install time. If the user does not exist by then + program invocation will fail. If the User= setting is used the supplementary group list is initialized from the specified user's default group list, as defined in the system's user and group @@ -497,42 +498,51 @@ CapabilityBoundingSet=~CAP_B CAP_C LimitRTTIME= Set soft and hard limits on various resources for executed processes. See - setrlimit2 for details on - the resource limit concept. Resource limits may be specified in two formats: either as single value to set a - specific soft and hard limit to the same value, or as colon-separated pair to set - both limits individually (e.g. LimitAS=4G:16G). Use the string to - configure no limit on a specific resource. The multiplicative suffixes K, M, G, T, P and E (to the base 1024) - may be used for resource limits measured in bytes (e.g. LimitAS=16G). For the limits referring to time values, - the usual time units ms, s, min, h and so on may be used (see + setrlimit2 for + details on the resource limit concept. Resource limits may be specified in two formats: either as + single value to set a specific soft and hard limit to the same value, or as colon-separated pair + to set both limits individually (e.g. LimitAS=4G:16G). + Use the string to configure no limit on a specific resource. The + multiplicative suffixes K, M, G, T, P and E (to the base 1024) may be used for resource limits + measured in bytes (e.g. LimitAS=16G). For the limits referring to time values, the + usual time units ms, s, min, h and so on may be used (see systemd.time7 for - details). Note that if no time unit is specified for LimitCPU= the default unit of seconds - is implied, while for LimitRTTIME= the default unit of microseconds is implied. Also, note - that the effective granularity of the limits might influence their enforcement. For example, time limits - specified for LimitCPU= will be rounded up implicitly to multiples of 1s. For - LimitNICE= the value may be specified in two syntaxes: if prefixed with + - or -, the value is understood as regular Linux nice value in the range -20..19. If not - prefixed like this the value is understood as raw resource limit parameter in the range 0..40 (with 0 being - equivalent to 1). + details). Note that if no time unit is specified for LimitCPU= the default unit of + seconds is implied, while for LimitRTTIME= the default unit of microseconds is + implied. Also, note that the effective granularity of the limits might influence their + enforcement. For example, time limits specified for LimitCPU= will be rounded up + implicitly to multiples of 1s. For LimitNICE= the value may be specified in two + syntaxes: if prefixed with + or -, the value is understood as + regular Linux nice value in the range -20..19. If not prefixed like this the value is understood as + raw resource limit parameter in the range 0..40 (with 0 being equivalent to 1). - Note that most process resource limits configured with these options are per-process, and processes may - fork in order to acquire a new set of resources that are accounted independently of the original process, and - may thus escape limits set. Also note that LimitRSS= is not implemented on Linux, and - setting it has no effect. Often it is advisable to prefer the resource controls listed in + Note that most process resource limits configured with these options are per-process, and + processes may fork in order to acquire a new set of resources that are accounted independently of the + original process, and may thus escape limits set. Also note that LimitRSS= is not + implemented on Linux, and setting it has no effect. Often it is advisable to prefer the resource + controls listed in systemd.resource-control5 - over these per-process limits, as they apply to services as a whole, may be altered dynamically at runtime, and - are generally more expressive. For example, MemoryLimit= is a more powerful (and working) - replacement for LimitRSS=. - - For system units these resource limits may be chosen freely. For user units however (i.e. units run by a - per-user instance of - systemd1), these limits are - bound by (possibly more restrictive) per-user limits enforced by the OS. + over these per-process limits, as they apply to services as a whole, may be altered dynamically at + runtime, and are generally more expressive. For example, MemoryMax= is a more + powerful (and working) replacement for LimitRSS=. Resource limits not configured explicitly for a unit default to the value configured in the various DefaultLimitCPU=, DefaultLimitFSIZE=, … options available in systemd-system.conf5, and – if not configured there – the kernel or per-user defaults, as defined by the OS (the latter only for user - services, see above). + services, see below). + + For system units these resource limits may be chosen freely. When these settings are configured + in a user service (i.e. a service run by the per-user instance of the service manager) they cannot be + used to raise the limits above those set for the user manager itself when it was first invoked, as + the user's service manager generally lacks the privileges to do so. In user context these + configuration options are hence only useful to lower the limits passed in or to raise the soft limit + to the maximum of the hard limit as configured for the user. To raise the user's limits further, the + available configuration mechanisms differ between operating systems, but typically require + privileges. In most cases it is possible to configure higher per-user resource limits via PAM or by + setting limits on the system service encapsulating the user's service manager, i.e. the user's + instance of user@.service. After making such changes, make sure to restart the + user's service manager. Resource limit directives, their equivalent <command>ulimit</command> shell commands and the unit used diff --git a/man/systemd.path.xml b/man/systemd.path.xml index 39cca8cf51..f6fe3d8388 100644 --- a/man/systemd.path.xml +++ b/man/systemd.path.xml @@ -52,6 +52,15 @@ limitations as inotify, and for example cannot be used to monitor files or directories changed by other machines on remote NFS file systems. + + When a service unit triggered by a path unit terminates (regardless whether it exited successfully + or failed), monitored paths are checked immediately again, and the service accordingly restarted + instantly. As protection against busy looping in this trigger/start cycle, a start rate limit is enforced + on the service unit, see StartLimitIntervalSec= and + StartLimitBurst= in + systemd.unit5. Unlike + other service failures, the error condition that the start rate limit is hit is propagated from the + service unit to the path unit and causes the path unit to fail as well, thus ending the loop. diff --git a/man/systemd.resource-control.xml b/man/systemd.resource-control.xml index ec3f6acbd5..fce7dc7505 100644 --- a/man/systemd.resource-control.xml +++ b/man/systemd.resource-control.xml @@ -462,6 +462,14 @@ This setting replaces BlockIODeviceWeight= and disables settings prefixed with BlockIO or StartupBlockIO. + + The specified device node should reference a block device that has an I/O scheduler + associated, i.e. should not refer to partition or loopback block devices, but to the originating, + physical device. When a path to a regular file or directory is specified it is attempted to + discover the correct originating device backing the file system of the specified path. This works + correctly only for simpler cases, where the file system is directly placed on a partition or + physical block device, or where simple 1:1 encryption using dm-crypt/LUKS is used. This discovery + does not cover complex storage and in particular RAID and volume management storage devices. @@ -486,6 +494,8 @@ These settings replace BlockIOReadBandwidth= and BlockIOWriteBandwidth= and disable settings prefixed with BlockIO or StartupBlockIO. + + Similar restrictions on block device discovery as for IODeviceWeight= apply, see above. @@ -509,6 +519,8 @@ These settings are supported only if the unified control group hierarchy is used and disable settings prefixed with BlockIO or StartupBlockIO. + + Similar restrictions on block device discovery as for IODeviceWeight= apply, see above. @@ -528,6 +540,8 @@ Implies IOAccounting=yes. These settings are supported only if the unified control group hierarchy is used. + + Similar restrictions on block device discovery as for IODeviceWeight= apply, see above. diff --git a/man/systemd.timer.xml b/man/systemd.timer.xml index ebf6de4eb2..040b8e2893 100644 --- a/man/systemd.timer.xml +++ b/man/systemd.timer.xml @@ -163,7 +163,10 @@ timers defined in the other directives. These are monotonic timers, independent of wall-clock time and timezones. If the computer is - temporarily suspended, the monotonic clock pauses, too. + temporarily suspended, the monotonic clock generally pauses, too. Note that if + WakeSystem= is used, a different monotonic clock is selected that continues to + advance while the system is suspended and thus can be used as the trigger to resume the + system. If the empty string is assigned to any of these options, the list of timers is reset (both monotonic timers and OnCalendar= timers, see below), and all prior assignments @@ -225,7 +228,13 @@ prctl2 for details. To optimize power consumption, make sure to set this value as high as possible and as low as - necessary. + necessary. + + Note that this setting is primarily a power saving option that allows coalescing CPU + wake-ups. It should not be confused with RandomizedDelaySec= (see below) which + adds a random value to the time the timer shall elapse next and whose purpose is the opposite: to + stretch elapsing of timer events over a longer period to reduce workload spikes. For further details + and explanations and how both settings play together, see below. @@ -310,7 +319,16 @@ false. Note that this functionality requires privileges and is thus generally only available in the - system service manager. + system service manager. + + Note that behaviour of monotonic clock timers (as configured with + OnActiveSec=, OnBootSec=, OnStartupSec=, + OnUnitActiveSec=, OnUnitInactiveSec=, see above) is altered + depending on this option. If false, a monotonic clock is used that is paused during system suspend + (CLOCK_MONOTONIC), if true a different monotonic clock is used that continues + advancing during system suspend (CLOCK_BOOTTIME), see + clock_getres2 for + details. diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index debb0c0d6c..64830ae723 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -756,7 +756,11 @@ configured by Requires=, Wants=, Requisite=, or BindsTo=. It is a common pattern to include a unit name in both the After= and Wants= options, in which case the unit listed will - be started before the unit that is configured with these options. + be started before the unit that is configured with these options. + + Note that Before= dependencies on device units have no effect and are not + supported. Devices generally become available as a result of an external hotplug event, and systemd + creates the corresponding device unit without delay. diff --git a/man/udev.xml b/man/udev.xml index 09254f818e..9b97ee63d9 100644 --- a/man/udev.xml +++ b/man/udev.xml @@ -465,6 +465,10 @@ that is enforced on systemd-udevd.service. Please also note that := and = are clearing both, program and builtin commands. + In order to activate long-running processes from udev rules, provide a service unit, and + pull it in from a udev device using the SYSTEMD_WANTS device property. See + systemd.device5 + for details.