morgan/systemd
1
0
Fork 0
mirror of https://github.com/morgan9e/systemd synced 2026-04-14 00:14:32 +09:00
Code Issues Packages Projects Releases Wiki Activity

docs: properly document inhibitor locks

Browse Source 
I still am annoyed that this wasn't documented properly when the
inhibitor locks where modified, even though raised multiple times in PR
reviews.

Follow-up for: #30307
See: #34091
This commit is contained in:
Lennart Poettering
2025-06-26 11:17:23 +02:00
parent 76a71fb64d
commit 2cdaad5b3b
3 changed files with 22 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/INHIBITOR_LOCKS.md
View File

@@ -42,8 +42,8 @@ If such a lock is taken the operation will fail (but still may be overridden if
The InhibitDelayMaxSec= setting in [logind.conf(5)](http://www.freedesktop.org/software/systemd/man/logind.conf.html) controls the timeout for this. This is intended to be used by applications which need a synchronous way to execute actions before system suspend but shall not be allowed to block suspend indefinitely.
This mode is only available for _sleep_ and _shutdown_ locks.
3. _block-weak_ that works as its non-weak counterpart, but that in addition may be ignored
automatically and silently under certain circumstances, unlike the former which is always respected.
3. _block-weak_ is identical to _block_, but has no effect on operations
requested by root or by the user owning the inhibitor lock.
Inhibitor locks are taken via the Inhibit() D-Bus call on the logind Manager object:

24
man/org.freedesktop.login1.xml
View File

@@ -675,16 +675,20 @@ node /org/freedesktop/login1 {
#define SD_LOGIND_SKIP_INHIBITORS (UINT64_C(1) << 4)
</programlisting>
<para>When the <varname>flags</varname> is 0 then these methods behave just like the versions without
flags. Since systemd version 257 active inhibitors are honoured by default for privileged users too.
<constant>SD_LOGIND_ROOT_CHECK_INHIBITORS</constant> (0x01) now only applies to weak inhibitors, to
request that they honoured for privileged users too, since they ignore them by default. A new flag
<constant>SD_LOGIND_SKIP_INHIBITORS</constant> (0x04) can be specified to bypass all types of
inhibitors. When <constant>SD_LOGIND_KEXEC_REBOOT</constant> (0x02) is set, then
<function>RebootWithFlags()</function> performs a kexec reboot if kexec kernel is loaded. When
<constant>SD_LOGIND_SOFT_REBOOT</constant> (0x04) is set, or
<constant>SD_LOGIND_SOFT_REBOOT_IF_NEXTROOT_SET_UP</constant> (0x08) is set and a new root file system
has been set up on <literal>/run/nextroot/</literal>, then <function>RebootWithFlags()</function>
performs a userspace reboot only. <constant>SD_LOGIND_SOFT_REBOOT_IF_NEXTROOT_SET_UP</constant> and
flags. Since systemd version 257 inhibitors of type <literal>block</literal> are enforced on operations
requested by both privileged and unprivileged users. Previously they were honoured only by unprivileged
users, excluding the user owning the inhibitor. The latter behaviour is now available through the
<literal>block-weak</literal> inhibitor lock type. <constant>SD_LOGIND_ROOT_CHECK_INHIBITORS</constant>
(0x01) makes <literal>block-weak</literal> locks behave like regular <literal>block</literal> locks,
i.e. ensures they are honoured for any user. A flag <constant>SD_LOGIND_SKIP_INHIBITORS</constant>
(0x10) can be specified to bypass both <literal>block</literal> and <literal>block-weak</literal>
inhibitors (it has no effect on <literal>delay</literal> inhibitors). When
<constant>SD_LOGIND_KEXEC_REBOOT</constant> (0x02) is set, then <function>RebootWithFlags()</function>
performs a kexec reboot if kexec kernel is loaded. When <constant>SD_LOGIND_SOFT_REBOOT</constant>
(0x04) is set, or <constant>SD_LOGIND_SOFT_REBOOT_IF_NEXTROOT_SET_UP</constant> (0x08) is set and a new
root file system has been set up on <literal>/run/nextroot/</literal>, then
<function>RebootWithFlags()</function> performs a userspace reboot
only. <constant>SD_LOGIND_SOFT_REBOOT_IF_NEXTROOT_SET_UP</constant> and
<constant>SD_LOGIND_KEXEC_REBOOT</constant> can be combined, with soft-reboot having precedence.
</para>

11
man/systemd-inhibit.xml
View File

@@ -95,13 +95,14 @@
<listitem><para>Takes <literal>block</literal>, <literal>delay</literal>, or
<literal>block-weak</literal> and describes how the lock is applied. If <literal>block</literal> is
used (the default), the lock prohibits any of the requested operations without time limit, and only
privileged users may override it. If <literal>delay</literal> is used, the lock can only delay the
requested operations for a limited time. If the time elapses, the lock is ignored and the operation
executed. The time limit may be specified in
privileged users may override it. The <literal>block-weak</literal> inhibitor lock type is similar to
<literal>block</literal> but is not enforced against operations initiated by privileged clients or
those owned by the user that also owns the inhibitor lock. If <literal>delay</literal> is used, the
lock can only delay the requested operations for a limited time. If the time elapses, the lock is
ignored and the operation executed. The time limit may be specified in
<citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
Note that <literal>delay</literal> is only available for <literal>sleep</literal> and
<literal>shutdown</literal>. In addition, the weak variants will automatically and silently be
bypassed under some circumstances.</para></listitem>
<literal>shutdown</literal>.</para></listitem>
</varlistentry>
<varlistentry>