diff --git a/man/org.freedesktop.login1.xml b/man/org.freedesktop.login1.xml index 034fd1078f..867662e057 100644 --- a/man/org.freedesktop.login1.xml +++ b/man/org.freedesktop.login1.xml @@ -576,16 +576,15 @@ node /org/freedesktop/login1 { PowerOff(), Reboot(), Halt(), Suspend(), and Hibernate() result in the system being powered - off, rebooted, halted (shut down without turning off power), suspended (the system state is - saved to RAM and the CPU is turned off), or hibernated (the system state is saved to disk and - the machine is powered down). HybridSleep() results in the system entering a - hybrid-sleep mode, i.e. the system is both hibernated and suspended. - SuspendThenHibernate() results in the system being suspended, then later woken - using an RTC timer and hibernated. The only argument is the polkit interactivity boolean - interactive (see below). The main purpose of these calls is that they enforce - polkit policy and hence allow powering off/rebooting/suspending/hibernating even by unprivileged - users. They also enforce inhibition locks for non-privileged users. UIs should expose these calls - as the primary mechanism to poweroff/reboot/suspend/hibernate the machine. Methods + off, rebooted, halted (shut down without turning off power), suspended (the system state is saved to + RAM and the CPU is turned off), or hibernated (the system state is saved to disk and the machine is + powered down). HybridSleep() results in the system entering a hybrid-sleep mode, + i.e. the system is both hibernated and suspended. SuspendThenHibernate() results + in the system being suspended, then later woken using an RTC timer and hibernated. The only argument is + the polkit interactivity boolean interactive (see below). The main purpose of these + calls is that they enforce polkit policy and hence allow powering off/rebooting/suspending/hibernating + even by unprivileged users. They also enforce inhibition locks for non-privileged users. UIs should + expose these calls as the primary mechanism to poweroff/reboot/suspend/hibernate the machine. Methods PowerOffWithFlags(), RebootWithFlags(), HaltWithFlags(), SuspendWithFlags(), HibernateWithFlags(), HybridSleepWithFlags() and @@ -594,12 +593,14 @@ node /org/freedesktop/login1 { #define SD_LOGIND_ROOT_CHECK_INHIBITORS (UINT64_C(1) << 0) #define SD_LOGIND_KEXEC_REBOOT (UINT64_C(1) << 1) +#define SD_LOGIND_SOFT_REBOOT (UINT64_C(1) << 2) - When the flags is 0 then these methods behave just like the versions - without flags. When SD_LOGIND_ROOT_CHECK_INHIBITORS (0x01) is set, active - inhibitors are honoured for privileged users too. When SD_LOGIND_KEXEC_REBOOT - (0x02) is set, then RebootWithFlags() perform kexec reboot if kexec - kernel is loaded. + When the flags is 0 then these methods behave just like the versions without + flags. When SD_LOGIND_ROOT_CHECK_INHIBITORS (0x01) is set, active inhibitors are + honoured for privileged users too. When SD_LOGIND_KEXEC_REBOOT (0x02) is set, then + RebootWithFlags() performs a kexec reboot if kexec kernel is loaded. When + SD_LOGIND_SOFT_REBOOT (0x04) is set, then RebootWithFlags() + performs a userspace reboot only. SetRebootParameter() sets a parameter for a subsequent reboot operation. See the description of reboot in diff --git a/man/org.freedesktop.systemd1.xml b/man/org.freedesktop.systemd1.xml index 0835481f37..a08108dd88 100644 --- a/man/org.freedesktop.systemd1.xml +++ b/man/org.freedesktop.systemd1.xml @@ -183,6 +183,8 @@ node /org/freedesktop/systemd1 { @org.freedesktop.systemd1.Privileged("true") Reboot(); @org.freedesktop.systemd1.Privileged("true") + SoftReboot(in s new_root); + @org.freedesktop.systemd1.Privileged("true") PowerOff(); @org.freedesktop.systemd1.Privileged("true") Halt(); @@ -912,6 +914,8 @@ node /org/freedesktop/systemd1 { + + @@ -1415,15 +1419,18 @@ node /org/freedesktop/systemd1 { Exit() may be invoked to ask the manager to exit. This is not available for the system manager and is useful only for user session managers. - Reboot(), PowerOff(), Halt(), or - KExec() may be used to ask for immediate reboot, powering down, halt or kexec - based reboot of the system. Note that this does not shut down any services and immediately transitions - into the reboot process. These functions are normally only called as the last step of shutdown and should - not be called directly. To shut down the machine, it is generally a better idea to invoke - Reboot() or PowerOff() on the + Reboot(), PowerOff(), Halt(), + KExec() and SoftReboot() may be used to ask for immediate + reboot, powering down, halt, kexec based reboot, or soft reboot of the system. Note that this does not + shut down any services and immediately transitions into the later shutdown operation. These functions + are normally only called as the last step of shutdown and should not be called directly. To shut down + the machine, it is generally a better idea to invoke Reboot(), + RebootWithFlags() or PowerOff() on the systemd-logind manager object; see org.freedesktop.login15 - for more information. + for more information. SoftReboot() accepts an argument indicating the path for the + root file system to activate for the next boot cycle. If an empty string is specified the + /run/nextroot/ path is used if it exists. SwitchRoot() may be used to transition to a new root directory. This is intended to be used in the initrd, and also to transition from the host system into a shutdown initrd. diff --git a/man/rules/meson.build b/man/rules/meson.build index 4658ef99f0..166d8a5e22 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -1036,6 +1036,7 @@ manpages = [ ['systemd-sleep.conf', '5', ['sleep.conf.d'], ''], ['systemd-socket-activate', '1', [], ''], ['systemd-socket-proxyd', '8', [], ''], + ['systemd-soft-reboot.service', '8', [], ''], ['systemd-stdio-bridge', '1', [], ''], ['systemd-stub', '7', diff --git a/man/systemctl.xml b/man/systemctl.xml index e54dd22aae..29e5fc65c2 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -1559,6 +1559,24 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err + + soft-reboot + + + Shut down and reboot userspace. This is equivalent to systemctl start + soft-reboot.target --job-mode=replace-irreversibly --no-block. This command is + asynchronous; it will return after the reboot operation is enqueued, without waiting for it to + complete. + + This command honors and in a similar way + as halt. + + This operation only reboots userspace, leaving the kernel running. See + systemd-soft-reboot.service8 + for details. + + + exit EXIT_CODE diff --git a/man/systemd-poweroff.service.xml b/man/systemd-poweroff.service.xml index 98c20471da..b430170bec 100644 --- a/man/systemd-poweroff.service.xml +++ b/man/systemd-poweroff.service.xml @@ -68,6 +68,10 @@ Note that systemd-poweroff.service (and the related units) should never be executed directly. Instead, trigger system shutdown with a command such as systemctl poweroff. + + Another form of shutdown is provided by the + systemd-soft-reboot.service8 + functionality. It reboots only the OS userspace, leaving the kernel, firmware, and hardware as it is. @@ -78,6 +82,7 @@ systemd.special7, reboot2, systemd-suspend.service8, + systemd-soft-reboot.service8, bootup7 diff --git a/man/systemd-soft-reboot.service.xml b/man/systemd-soft-reboot.service.xml new file mode 100644 index 0000000000..0e95cba3be --- /dev/null +++ b/man/systemd-soft-reboot.service.xml @@ -0,0 +1,158 @@ + + + + + + + + systemd-soft-reboot.service + systemd + + + + systemd-soft-reboot.service + 8 + + + + systemd-soft-reboot.service + Userspace reboot operation + + + + systemd-soft-reboot.service + + + + Description + + systemd-soft-reboot.service is a system service that is pulled in by + soft-reboot.target and is responsible for performing a userspace-only reboot + operation. When invoked, it will send the SIGTERM signal to any processes left + running (but does not follow up with SIGKILL, and does not wait for the processes to + exit). If the /run/nextroot/ directory exists (which may be a regular directory, a + directory mount point or a symlink to either) then it will switch the file system root to it. It then + reexecutes the service manager off the (possibly now new) root file system, which will enqueue a new boot + transaction as in a normal reboot. + + Such a userspace-only reboot operation permits updating or resetting the entirety of userspace with + minimal downtime, as the reboot operation does not transition through: + + + The second phase of regular shutdown, as implemented by + systemd-shutdown8. + + The third phase of regular shutdown, i.e. the return to the initrd + context + + The hardware reboot operation + + The firmware initialization + + The boot loader initialization + + The kernel initialization + + The initrd initialization + + + However this form of reboot comes with drawbacks as well: + + + The OS update remains incomplete, as the kernel is not reset and continues + running. + + Kernel settings (such as /proc/sys/ settings, a.k.a. "sysctl", or + /sys/ settings) are not reset. + + + These limitations may be addressed by various means, which are outside of the scope of this + documentation, such as kernel live-patching and sufficiently comprehensive + /etc/sysctl.d/ files. + + + + Resource Pass-Through + + Various runtime OS resources can passed from a system runtime to the next, through the userspace + reboot operation. Specificially: + + + File descriptors placed in the file descriptor store of services that remain active + until the very end are passed to the next boot, where they are placed in the file descriptor store of + the same unit. For this to work, units must declare DefaultDependencies=no (and + avoid a manual Conflicts=shutdown.target or similar) to ensure they are not + terminated as usual during the system shutdown operation. Alternatively, use + FileDescriptorStorePreserve= to allow the file descriptor store to remain pinned + even when the unit is down. See + systemd.service5 for + details about the file descriptor store. + + Similar to this, file descriptors associated with .socket units + remain open (and connectible) if the units are not stopped during the transition. (Achieved by + DefaultDependencies=no.) + + The /run/ file system remains mounted and populated and may be + used to pass state information between such userspace reboot cycles. + + Service processes may continue to run over the transition, if they are placed in + services that remain active until the very end of shutdown (which again is achieved via + DefaultDependencies=no). They must also be set up to avoid being killed by the + aforementioned SIGTERM spree (as per systemd and Storage Daemons for the Root File + System). + + File system mounts may remain mounted during the transition, and complex storage + attached, if configured to remain until the very end of the shutdown process. (Also achieved via + DefaultDependencies=no, and by avoiding + Conflicts=umount.target) + + + Even though passing resources from one soft reboot cycle to the next is possible this way, we + strongly suggest to use this functionality sparingly only, as it creates a more fragile system as + resources from different versions of the OS and applications might be mixed with unforeseen + consequences. In particular it's recommended to avoid allowing processes to survive + the soft reboot operation, as this means code updates will necessarily be incomplete, and processes + typically pin various other resources (such as the file system they are backed by), thus increasing + memory usage (as two versions of the OS/application/file system might be kept in memory). Leaving + processes running during a soft-reboot operation requires disconnecting the service comprehensively from + the rest of the OS, i.e. minimizing IPC and reducing sharing of resources with the rest of the OS. A + possible mechanism to achieve this is the concept of Portable Services. + + If units shall be left running until the very end of shutdown during a soft reboot operation, but + shall be terminated regularly during other forms of shutdown, it's recommended to set + DefaultDependencies=no and then place + Conflicts=/Before= onto reboot.target, + kexec.target, poweroff.target and + halt.target (but not onto + soft-reboot.target). + + + + Notes + + Note that because + systemd-shutdown8 is + not executed, the executables in /usr/lib/systemd/system-shutdown/ are not executed + either. + + Note that systemd-soft-reboot.service (and related units) should never be + executed directly. Instead, trigger system shutdown with a command such as systemctl + soft-reboot. + + + + See Also + + systemd1, + systemctl1, + systemd.special7, + systemd-poweroff.service8, + systemd-suspend.service8, + bootup7 + + + + diff --git a/man/systemd.mount.xml b/man/systemd.mount.xml index 550f006601..0d14d702a8 100644 --- a/man/systemd.mount.xml +++ b/man/systemd.mount.xml @@ -437,8 +437,12 @@ An additional filesystem to be mounted in the initrd. See initrd-fs.target description in - systemd.special7. - + systemd.special7. This + is both an indicator to the initrd to mount this partition early and an indicator to the host to + leave the partition mounted until final shutdown. Or in other words, if this flag is set it is + assumed the mount shall be active during the entire regular runtime of the system, i.e. established + before the initrd transitions into the host all the way until the host transitions to the final + shutdown phase. diff --git a/man/systemd.special.xml b/man/systemd.special.xml index 1620895511..c90e7156ed 100644 --- a/man/systemd.special.xml +++ b/man/systemd.special.xml @@ -81,6 +81,7 @@ slices.target, smartcard.target, sockets.target, + soft-reboot.target, sound.target, suspend.target, swap.target, @@ -442,15 +443,18 @@ kexec.target - A special target unit for shutting down and rebooting - the system via kexec. + A special target unit for shutting down and rebooting the system via kexec. - Applications wanting to reboot the system should not start this unit - directly, but should instead execute systemctl kexec - (possibly with the option) or call - systemd1's - org.freedesktop.systemd1.Manager.KExec D-Bus method + Applications wanting to reboot the system should not start this unit directly, but should + instead execute systemctl kexec (possibly with the + option) or call + systemd-logind8's + org.freedesktop.login1.Manager.RebootWithFlags() D-Bus method directly. + + See + systemd-kexec.service8 + for further details of the operation this target pulls in. @@ -559,18 +563,20 @@ reboot.target - A special target unit for shutting down and rebooting - the system. + A special target unit for shutting down and rebooting the system. - Applications wanting to reboot the system should not start this unit - directly, but should instead execute systemctl reboot - (possibly with the option) or call + Applications wanting to reboot the system should not start this unit directly, but should + instead execute systemctl reboot (possibly with the + option) or call systemd-logind8's - org.freedesktop.login1.Manager.Reboot D-Bus method - directly. + org.freedesktop.login1.Manager.Reboot() D-Bus method directly. - runlevel6.target is an alias for - this target unit, for compatibility with SysV. + See + systemd-reboot.service8 + for further details of the operation this target pulls in. + + runlevel6.target is an alias for this target unit, for compatibility + with SysV. @@ -703,6 +709,24 @@ section. + + soft-reboot.target + + A special target unit for shutting down and rebooting the userspace of the system (leaving + the kernel running). + + Applications wanting to reboot the system should not start this unit directly, but should + instead execute systemctl soft-reboot (possibly with the + option) or call + systemd-logind8's + org.freedesktop.login1.Manager.RebootWithFlags() D-Bus method + directly. + + See + systemd-soft-reboot.service8 + for further details of the operation this target pulls in. + + suspend.target diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index fcd1f914a8..77c3cd24f8 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -999,27 +999,34 @@ FailureAction= SuccessAction= - Configure the action to take when the unit stops and enters a failed state or inactive state. - Takes one of , , , - , , , - , , and . In system mode, - all options are allowed. In user mode, only , , and - are allowed. Both options default to . + Configure the action to take when the unit stops and enters a failed state or + inactive state. Takes one of , , + , , , + , , , + , and . In + system mode, all options are allowed. In user mode, only , + , , and + are allowed. Both options default to . - If is set, no action will be triggered. causes a reboot - following the normal shutdown procedure (i.e. equivalent to systemctl reboot). - causes a forced reboot which will terminate all processes forcibly but should - cause no dirty file systems on reboot (i.e. equivalent to systemctl reboot -f) and - causes immediate execution of the - reboot2 system call, which - might result in data loss (i.e. equivalent to systemctl reboot -ff). Similarly, - , , have the effect - of powering down the system with similar semantics. causes the manager to exit following - the normal shutdown procedure, and causes it terminate without shutting down - services. When or is used by default the exit status of the - main process of the unit (if this applies) is returned from the service manager. However, this may be overridden - with FailureActionExitStatus=/SuccessActionExitStatus=, see - below. + If is set, no action will be triggered. causes a + reboot following the normal shutdown procedure (i.e. equivalent to systemctl + reboot). causes a forced reboot which will terminate all + processes forcibly but should cause no dirty file systems on reboot (i.e. equivalent to + systemctl reboot -f) and causes immediate + execution of the + reboot2 system + call, which might result in data loss (i.e. equivalent to systemctl reboot + -ff). Similarly, , , + have the effect of powering down the system with similar + semantics. causes the manager to exit following the normal shutdown procedure, + and causes it terminate without shutting down services. When + or is used by default the exit status of the main + process of the unit (if this applies) is returned from the service manager. However, this may be + overridden with + FailureActionExitStatus=/SuccessActionExitStatus=, see + below. will trigger a userspace reboot + operation. does that too, but does not go through the shutdown + transaction beforehand. diff --git a/man/systemd.xml b/man/systemd.xml index ca9e4e9988..95dc1fef83 100644 --- a/man/systemd.xml +++ b/man/systemd.xml @@ -519,6 +519,15 @@ + + SIGRTMIN+7 + + Reboots userspace, starts the soft-reboot.target unit. This is + mostly equivalent to systemctl start soft-reboot.target + --job-mode=replace-irreversibly. + + + SIGRTMIN+13 @@ -543,6 +552,12 @@ Immediately reboots the machine with kexec. + + SIGRTMIN+17 + + Immediately reboots the userspace. + + SIGRTMIN+20