diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/capsule@.service.xml | 2 | ||||
| -rw-r--r-- | man/crypttab.xml | 38 | ||||
| -rw-r--r-- | man/logind.conf.xml | 22 | ||||
| -rw-r--r-- | man/org.freedesktop.login1.xml | 31 | ||||
| -rw-r--r-- | man/org.freedesktop.systemd1.xml | 50 | ||||
| -rw-r--r-- | man/repart.d.xml | 15 | ||||
| -rw-r--r-- | man/rules/meson.build | 1 | ||||
| -rw-r--r-- | man/sd_notify.xml | 12 | ||||
| -rw-r--r-- | man/systemctl.xml | 4 | ||||
| -rw-r--r-- | man/systemd-cryptenroll.xml | 28 | ||||
| -rw-r--r-- | man/systemd-cryptsetup.xml | 5 | ||||
| -rw-r--r-- | man/systemd-import-generator.xml | 194 | ||||
| -rw-r--r-- | man/systemd-inhibit.xml | 1 | ||||
| -rw-r--r-- | man/systemd-tmpfiles.xml | 2 | ||||
| -rw-r--r-- | man/systemd.exec.xml | 39 | ||||
| -rw-r--r-- | man/systemd.journal-fields.xml | 7 | ||||
| -rw-r--r-- | man/systemd.system-credentials.xml | 10 | ||||
| -rw-r--r-- | man/sysusers.d.xml | 1 | ||||
| -rw-r--r-- | man/tmpfiles.d.xml | 7 | ||||
| -rw-r--r-- | man/varlinkctl.xml | 45 |
20 files changed, 451 insertions, 63 deletions
diff --git a/man/capsule@.service.xml b/man/capsule@.service.xml index aa5b1bbae3..f9c5455f3b 100644 --- a/man/capsule@.service.xml +++ b/man/capsule@.service.xml @@ -41,7 +41,7 @@ <listitem><para>The capsule service manager utilizes <varname>DynamicUser=</varname> (see <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>) to allocate a new UID dynamically on invocation. The user name is automatically generated from the capsule - name, by prefixng <literal>p_</literal>. The UID is released when the service is terminated. The user + name, by prefixing <literal>c-</literal>. The UID is released when the service is terminated. The user service manager on the other hand operates under a statically allocated user ID that must be pre-existing, before the user service manager is invoked.</para></listitem> diff --git a/man/crypttab.xml b/man/crypttab.xml index 3aa809e667..8ffeaf7fcb 100644 --- a/man/crypttab.xml +++ b/man/crypttab.xml @@ -215,8 +215,11 @@ from the key file. See <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> for possible values and the default value of this option. This - option is ignored in plain encryption mode, as the key file - size is then given by the key size.</para> + option is ignored in plain encryption mode, where the key file + size is determined by the key size. It is also ignored when + the key file is used as a salt file for a FIDO2 token, as the + salt size in that case is defined by the FIDO2 specification + to be exactly 32 bytes.</para> <xi:include href="version-info.xml" xpointer="v188"/></listitem> </varlistentry> @@ -671,6 +674,26 @@ </varlistentry> <varlistentry> + <term><option>password-cache=yes|no|read-only</option></term> + + <listitem><para>Controls whether to use cache for passwords or security token PINs. + Takes a boolean or the special string <literal>read-only</literal>. Defaults to + <literal>yes</literal>.</para> + + <para>If set to <literal>read-only</literal>, the kernel keyring is checked for a + password/PIN before requesting one interactively. If set to <literal>yes</literal>, + in addition to checking the keyring, any password/PIN entered interactively is cached + in the keyring with a 2.5-minute timeout before being purged.</para> + + <para>Note that this option is not permitted for PKCS#11 security tokens. The reasoning + behind this is that PKCS#11 security tokens are usually configured to lock after being + supplied an invalid PIN multiple times, so using the cache might inadvertently lock the + token.</para> + + <xi:include href="version-info.xml" xpointer="v257"/></listitem> + </varlistentry> + + <varlistentry> <term><option>pkcs11-uri=</option></term> <listitem><para>Takes either the special value <literal>auto</literal> or an <ulink @@ -724,8 +747,7 @@ (configured in the line's third column) to operate. If not configured and the volume is of type LUKS2, the CID and the key are read from LUKS2 JSON token metadata instead. Use <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry> - as simple tool for enrolling FIDO2 security tokens, compatible with this automatic mode, which is - only available for LUKS2 volumes.</para> + as simple tool for enrolling FIDO2 security tokens for LUKS2 volumes.</para> <para>Use <command>systemd-cryptenroll --fido2-device=list</command> to list all suitable FIDO2 security tokens currently plugged in, along with their device nodes.</para> @@ -1008,10 +1030,10 @@ and use this to determine which key to send, allowing a single listening socket to serve keys for multiple volumes. If the PKCS#11 logic is used (see above), the socket source name is picked in similar fashion, except that the literal string <literal>/cryptsetup-pkcs11/</literal> is used. And similarly for - FIDO2 (<literal>/cryptsetup-fido2/</literal>) and TPM2 (<literal>/cryptsetup-tpm2/</literal>). A different - path component is used so that services providing key material know that the secret key was not requested - directly, but instead an encrypted key that will be decrypted via the PKCS#11/FIDO2/TPM2 logic to acquire - the final secret key.</para> + FIDO2 (<literal>/cryptsetup-fido2-salt/</literal>) and TPM2 (<literal>/cryptsetup-tpm2/</literal>). + A different path component is used so that services providing key material know that the secret key was + not requested directly, but instead an encrypted key that will be decrypted via the PKCS#11/FIDO2/TPM2 + logic to acquire the final secret key.</para> </refsect1> <refsect1> diff --git a/man/logind.conf.xml b/man/logind.conf.xml index c52431fd41..66240b58fe 100644 --- a/man/logind.conf.xml +++ b/man/logind.conf.xml @@ -224,13 +224,14 @@ <term><varname>HandleLidSwitch=</varname></term> <term><varname>HandleLidSwitchExternalPower=</varname></term> <term><varname>HandleLidSwitchDocked=</varname></term> + <term><varname>HandleSecureAttentionKey=</varname></term> <listitem><para>Controls how logind shall handle the system power, reboot and sleep keys and the lid switch to trigger actions such as system power-off, reboot or suspend. Can be one of <literal>ignore</literal>, <literal>poweroff</literal>, <literal>reboot</literal>, <literal>halt</literal>, <literal>kexec</literal>, <literal>suspend</literal>, <literal>hibernate</literal>, <literal>hybrid-sleep</literal>, <literal>suspend-then-hibernate</literal>, <literal>sleep</literal>, <literal>lock</literal>, and - <literal>factory-reset</literal>. If <literal>ignore</literal>, <command>systemd-logind</command> + <literal>factory-reset</literal>, <literal>secure-attention-key</literal>. If <literal>ignore</literal>, <command>systemd-logind</command> will never handle these keys. If <literal>lock</literal>, all running sessions will be screen-locked; otherwise, the specified action will be taken in the respective event. Only input devices with the <literal>power-switch</literal> udev tag will be watched for key/lid switch @@ -251,7 +252,8 @@ system is inserted in a docking station, or if more than one display is connected, the action specified by <varname>HandleLidSwitchDocked=</varname> occurs; if the system is on external power the action (if any) specified by <varname>HandleLidSwitchExternalPower=</varname> occurs; otherwise the - <varname>HandleLidSwitch=</varname> action occurs.</para> + <varname>HandleLidSwitch=</varname> action occurs. + <varname>HandleSecureAttentionKey=</varname> defaults to <literal>secure-attention-key</literal></para> <para>A different application may disable logind's handling of system power and sleep keys and the lid switch by taking a low-level inhibitor lock @@ -262,7 +264,7 @@ to take over suspend and hibernation handling, and to use their own configuration mechanisms. If a low-level inhibitor lock is taken, logind will not take any action when that key or switch is triggered and the <varname>Handle*=</varname> - settings are irrelevant.</para> + settings are irrelevant, except for <varname>HandleSecureAttentionKey=</varname>, which is always handled since its addition in v257.</para> <xi:include href="version-info.xml" xpointer="v184"/></listitem> </varlistentry> @@ -393,6 +395,20 @@ <xi:include href="version-info.xml" xpointer="v252"/></listitem> </varlistentry> + + <varlistentry> + <term><varname>DesignatedMaintenanceTime=</varname></term> + + <listitem> + <para> + Specifies a default calendar event for scheduled shutdowns. So when using e.g. the command + <command>shutdown -r</command> to reboot the system without specifying a timeout, logind would + use the configured calendar event instead. For details about the syntax of calendar events, see + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + </para> + + <xi:include href="version-info.xml" xpointer="v257"/></listitem> + </varlistentry> </variablelist> </refsect1> diff --git a/man/org.freedesktop.login1.xml b/man/org.freedesktop.login1.xml index d9b9b0e1b3..cba371ca9e 100644 --- a/man/org.freedesktop.login1.xml +++ b/man/org.freedesktop.login1.xml @@ -169,6 +169,8 @@ node /org/freedesktop/login1 { SetWallMessage(in s wall_message, in b enable); signals: + SecureAttentionKey(s seat_id, + o object_path); SessionNew(s session_id, o object_path); SessionRemoved(s session_id, @@ -244,6 +246,8 @@ node /org/freedesktop/login1 { @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s HandleLidSwitchDocked = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s HandleSecureAttentionKey = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t HoldoffTimeoutUSec = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly s IdleAction = '...'; @@ -253,9 +257,10 @@ node /org/freedesktop/login1 { readonly b PreparingForShutdown = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b PreparingForSleep = ...; - @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly (st) ScheduledShutdown = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") + readonly s DesignatedMaintenanceTime = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b Docked = ...; readonly b LidClosed = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") @@ -295,6 +300,10 @@ node /org/freedesktop/login1 { <!--property HandleHibernateKeyLongPress is not documented!--> + <!--property HandleSecureAttentionKey is not documented!--> + + <!--property DesignatedMaintenanceTime is not documented!--> + <!--property StopIdleSessionUSec is not documented!--> <!--Autogenerated cross-references for systemd.directives, do not edit--> @@ -427,6 +436,8 @@ node /org/freedesktop/login1 { <variablelist class="dbus-method" generated="True" extra-ref="SetWallMessage()"/> + <variablelist class="dbus-signal" generated="True" extra-ref="SecureAttentionKey()"/> + <variablelist class="dbus-signal" generated="True" extra-ref="SessionNew()"/> <variablelist class="dbus-signal" generated="True" extra-ref="SessionRemoved()"/> @@ -505,6 +516,8 @@ node /org/freedesktop/login1 { <variablelist class="dbus-property" generated="True" extra-ref="HandleLidSwitchDocked"/> + <variablelist class="dbus-property" generated="True" extra-ref="HandleSecureAttentionKey"/> + <variablelist class="dbus-property" generated="True" extra-ref="HoldoffTimeoutUSec"/> <variablelist class="dbus-property" generated="True" extra-ref="IdleAction"/> @@ -517,6 +530,8 @@ node /org/freedesktop/login1 { <variablelist class="dbus-property" generated="True" extra-ref="ScheduledShutdown"/> + <variablelist class="dbus-property" generated="True" extra-ref="DesignatedMaintenanceTime"/> + <variablelist class="dbus-property" generated="True" extra-ref="Docked"/> <variablelist class="dbus-property" generated="True" extra-ref="LidClosed"/> @@ -688,7 +703,10 @@ node /org/freedesktop/login1 { <literal>challenge</literal> is returned, the operation is available but only after authorization.</para> <para><function>ScheduleShutdown()</function> schedules a shutdown operation <varname>type</varname> at - time <varname>usec</varname> in microseconds since the UNIX epoch. <varname>type</varname> can be one + time <varname>usec</varname> in microseconds since the UNIX epoch. Alternatively, if + <varname>usec</varname> <literal>UINT64_MAX</literal> and a maintenance window is + configured, <filename>systemd-logind</filename> will use the next time of the maintenance window + instead. <varname>type</varname> can be one of <literal>poweroff</literal>, <literal>dry-poweroff</literal>, <literal>reboot</literal>, <literal>dry-reboot</literal>, <literal>halt</literal>, and <literal>dry-halt</literal>. (The <literal>dry-</literal> variants do not actually execute the shutdown action.) @@ -725,6 +743,10 @@ node /org/freedesktop/login1 { <para>Whenever the inhibition state or idle hint changes, <function>PropertyChanged</function> signals are sent out to which clients can subscribe.</para> + <para>The <function>SecureAttentionKey()</function> signal is sent when the user presses Ctrl+Alt+Shift+Esc to + request the login manager to display the greeter, for instance in the case of a deadlocked compositor. + </para> + <para>The <function>SessionNew()</function>, <function>SessionRemoved()</function>, <function>UserNew()</function>, <function>UserRemoved()</function>, <function>SeatNew()</function>, and <function>SeatRemoved()</function> signals are sent each time a session is created or removed, a user @@ -1579,8 +1601,11 @@ node /org/freedesktop/login1/session/1 { <function>CreateSessionWithPIDFD()</function> were added in version 255.</para> <para><function>Sleep()</function>, <function>CanSleep()</function>, - <varname>SleepOperation</varname>, and + <varname>SleepOperation</varname>, + <varname>DesignatedMaintenanceTime</varname>, and <function>ListSessionsEx()</function> were added in version 256.</para> + <para><varname>HandleSecureAttentionKey</varname>, and + <function>SecureAttentionKey()</function> were added in version 257.</para> </refsect2> <refsect2> <title>Session Objects</title> diff --git a/man/org.freedesktop.systemd1.xml b/man/org.freedesktop.systemd1.xml index b0b45097e3..31e6194bec 100644 --- a/man/org.freedesktop.systemd1.xml +++ b/man/org.freedesktop.systemd1.xml @@ -2745,6 +2745,8 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice { readonly s FileDescriptorStorePreserve = '...'; readonly s StatusText = '...'; readonly i StatusErrno = ...; + readonly s StatusBusError = '...'; + readonly s StatusVarlinkError = '...'; readonly s Result = '...'; readonly s ReloadResult = '...'; readonly s CleanResult = '...'; @@ -3205,6 +3207,8 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice { @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateTmp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s PrivateTmpEx = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateDevices = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ProtectClock = ...; @@ -3404,8 +3408,6 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice { <!--property FileDescriptorStorePreserve is not documented!--> - <!--property StatusErrno is not documented!--> - <!--property ReloadResult is not documented!--> <!--property CleanResult is not documented!--> @@ -3816,6 +3818,8 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice { <!--property PrivateTmp is not documented!--> + <!--property PrivateTmpEx is not documented!--> + <!--property PrivateDevices is not documented!--> <!--property ProtectClock is not documented!--> @@ -4026,6 +4030,10 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice { <variablelist class="dbus-property" generated="True" extra-ref="StatusErrno"/> + <variablelist class="dbus-property" generated="True" extra-ref="StatusBusError"/> + + <variablelist class="dbus-property" generated="True" extra-ref="StatusVarlinkError"/> + <variablelist class="dbus-property" generated="True" extra-ref="Result"/> <variablelist class="dbus-property" generated="True" extra-ref="ReloadResult"/> @@ -4500,6 +4508,8 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice { <variablelist class="dbus-property" generated="True" extra-ref="PrivateTmp"/> + <variablelist class="dbus-property" generated="True" extra-ref="PrivateTmpEx"/> + <variablelist class="dbus-property" generated="True" extra-ref="PrivateDevices"/> <variablelist class="dbus-property" generated="True" extra-ref="ProtectClock"/> @@ -4732,11 +4742,11 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice { process is currently running while the latter possible contains information collected from the last run even if the process is no longer around.</para> - <para><varname>StatusText</varname> contains the status text passed to the service manager via a call - to - <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - This may be used by services to inform the service manager about its internal state with a nice - explanatory string.</para> + <para><varname>StatusText</varname>, <varname>StatusErrno</varname>, <varname>StatusBusError</varname>, + and <varname>StatusVarlinkError</varname> contain the status text, the error number, + and the D-Bus/Varlink error name passed to the service manager via + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + respectively. They may be used by services to inform the service manager about its internal state.</para> <para><varname>Result</varname> encodes the execution result of the last run of the service. It is useful to determine the reason a service failed if it is in the <literal>failed</literal> state (see @@ -5322,6 +5332,8 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2esocket { @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateTmp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s PrivateTmpEx = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateDevices = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ProtectClock = ...; @@ -5945,6 +5957,8 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2esocket { <!--property PrivateTmp is not documented!--> + <!--property PrivateTmpEx is not documented!--> + <!--property PrivateDevices is not documented!--> <!--property ProtectClock is not documented!--> @@ -6609,6 +6623,8 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2esocket { <variablelist class="dbus-property" generated="True" extra-ref="PrivateTmp"/> + <variablelist class="dbus-property" generated="True" extra-ref="PrivateTmpEx"/> + <variablelist class="dbus-property" generated="True" extra-ref="PrivateDevices"/> <variablelist class="dbus-property" generated="True" extra-ref="ProtectClock"/> @@ -7295,6 +7311,8 @@ node /org/freedesktop/systemd1/unit/home_2emount { @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateTmp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s PrivateTmpEx = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateDevices = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ProtectClock = ...; @@ -7844,6 +7862,8 @@ node /org/freedesktop/systemd1/unit/home_2emount { <!--property PrivateTmp is not documented!--> + <!--property PrivateTmpEx is not documented!--> + <!--property PrivateDevices is not documented!--> <!--property ProtectClock is not documented!--> @@ -8420,6 +8440,8 @@ node /org/freedesktop/systemd1/unit/home_2emount { <variablelist class="dbus-property" generated="True" extra-ref="PrivateTmp"/> + <variablelist class="dbus-property" generated="True" extra-ref="PrivateTmpEx"/> + <variablelist class="dbus-property" generated="True" extra-ref="PrivateDevices"/> <variablelist class="dbus-property" generated="True" extra-ref="ProtectClock"/> @@ -9229,6 +9251,8 @@ node /org/freedesktop/systemd1/unit/dev_2dsda3_2eswap { @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateTmp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") + readonly s PrivateTmpEx = '...'; + @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b PrivateDevices = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly b ProtectClock = ...; @@ -9764,6 +9788,8 @@ node /org/freedesktop/systemd1/unit/dev_2dsda3_2eswap { <!--property PrivateTmp is not documented!--> + <!--property PrivateTmpEx is not documented!--> + <!--property PrivateDevices is not documented!--> <!--property ProtectClock is not documented!--> @@ -10326,6 +10352,8 @@ node /org/freedesktop/systemd1/unit/dev_2dsda3_2eswap { <variablelist class="dbus-property" generated="True" extra-ref="PrivateTmp"/> + <variablelist class="dbus-property" generated="True" extra-ref="PrivateTmpEx"/> + <variablelist class="dbus-property" generated="True" extra-ref="PrivateDevices"/> <variablelist class="dbus-property" generated="True" extra-ref="ProtectClock"/> @@ -12015,7 +12043,7 @@ $ gdbus introspect --system --dest org.freedesktop.systemd1 \ <function>DumpUnitFileDescriptorStore()</function> were added in version 254.</para> <para><function>StartAuxiliaryScope()</function>, <varname>ShutdownStartTimestamp</varname>, - <varname>ShutdownStartTimestampMonotonic</varname> and + <varname>ShutdownStartTimestampMonotonic</varname>, and <varname>SoftRebootsCount</varname> were added in version 256.</para> </refsect2> <refsect2> @@ -12070,6 +12098,9 @@ $ gdbus introspect --system --dest org.freedesktop.systemd1 \ <varname>MemoryZSwapWriteback</varname>, <varname>ExecMainHandoffTimestampMonotonic</varname>, and <varname>ExecMainHandoffTimestamp</varname> were added in version 256.</para> + <para><varname>StatusBusError</varname>, + <varname>StatusVarlinkError</varname>, and + <varname>PrivateTmpEx</varname> were added in version 257.</para> </refsect2> <refsect2> <title>Socket Unit Objects</title> @@ -12106,6 +12137,7 @@ $ gdbus introspect --system --dest org.freedesktop.systemd1 \ <varname>EffectiveTasksMax</varname>, <varname>MemoryZSwapWriteback</varname>, and <varname>PassFileDescriptorsToExec</varname> were added in version 256.</para> + <para><varname>PrivateTmpEx</varname> was added in version 257.</para> </refsect2> <refsect2> <title>Mount Unit Objects</title> @@ -12139,6 +12171,7 @@ $ gdbus introspect --system --dest org.freedesktop.systemd1 \ <varname>EffectiveMemoryMax</varname>, <varname>EffectiveTasksMax</varname>, and <varname>MemoryZSwapWriteback</varname> were added in version 256.</para> + <para><varname>PrivateTmpEx</varname> was added in version 257.</para> </refsect2> <refsect2> <title>Swap Unit Objects</title> @@ -12172,6 +12205,7 @@ $ gdbus introspect --system --dest org.freedesktop.systemd1 \ <varname>EffectiveMemoryMax</varname>, <varname>EffectiveTasksMax</varname>, and <varname>MemoryZSwapWriteback</varname> were added in version 256.</para> + <para><varname>PrivateTmpEx</varname> was added in version 257.</para> </refsect2> <refsect2> <title>Slice Unit Objects</title> diff --git a/man/repart.d.xml b/man/repart.d.xml index 52e6b97240..804cb804b2 100644 --- a/man/repart.d.xml +++ b/man/repart.d.xml @@ -362,12 +362,14 @@ <varlistentry> <term><varname>CopyBlocks=</varname></term> - <listitem><para>Takes a path to a regular file, block device node or directory, or the special value - <literal>auto</literal>. If specified and the partition is newly created, the data from the specified - path is written to the newly created partition, on the block level. If a directory is specified, the - backing block device of the file system the directory is on is determined, and the data read directly - from that. This option is useful to efficiently replicate existing file systems onto new partitions - on the block level — for example to build a simple OS installer or an OS image builder.</para> + <listitem><para>Takes a path to a regular file, block device node, char device node or directory, or + the special value <literal>auto</literal>. If specified and the partition is newly created, the data + from the specified path is written to the newly created partition, on the block level. If a directory + is specified, the backing block device of the file system the directory is on is determined, and the + data read directly from that. This option is useful to efficiently replicate existing file systems + onto new partitions on the block level — for example to build a simple OS installer or an OS image + builder. Specify <filename>/dev/urandom</filename> as value to initialize a partition with random + data.</para> <para>If the special value <literal>auto</literal> is specified, the source to copy from is automatically picked up from the running system (or the image specified with @@ -819,6 +821,7 @@ <xi:include href="standard-specifiers.xml" xpointer="m"/> <xi:include href="standard-specifiers.xml" xpointer="M"/> <xi:include href="standard-specifiers.xml" xpointer="o"/> + <xi:include href="standard-specifiers.xml" xpointer="q"/> <xi:include href="standard-specifiers.xml" xpointer="v"/> <xi:include href="standard-specifiers.xml" xpointer="w"/> <xi:include href="standard-specifiers.xml" xpointer="W"/> diff --git a/man/rules/meson.build b/man/rules/meson.build index 9b8a29c564..fda14d55bd 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -953,6 +953,7 @@ manpages = [ ['systemd-hostnamed.service', '8', ['systemd-hostnamed'], 'ENABLE_HOSTNAMED'], ['systemd-hwdb', '8', [], 'ENABLE_HWDB'], ['systemd-id128', '1', [], ''], + ['systemd-import-generator', '8', [], ''], ['systemd-importd.service', '8', ['systemd-importd'], 'ENABLE_IMPORTD'], ['systemd-inhibit', '1', [], ''], ['systemd-initctl.service', diff --git a/man/sd_notify.xml b/man/sd_notify.xml index 35c450b128..f04251bd19 100644 --- a/man/sd_notify.xml +++ b/man/sd_notify.xml @@ -258,13 +258,21 @@ <term>BUSERROR=…</term> <listitem><para>If a service fails, the D-Bus error-style error code. Example: - <literal>BUSERROR=org.freedesktop.DBus.Error.TimedOut</literal>. Note that this assignment is - currently not used by <command>systemd</command>.</para> + <literal>BUSERROR=org.freedesktop.DBus.Error.TimedOut</literal>.</para> <xi:include href="version-info.xml" xpointer="v233"/></listitem> </varlistentry> <varlistentry> + <term>VARLINKERROR=…</term> + + <listitem><para>If a service fails, the Varlink error-style error code. Example: + <literal>VARLINKERROR=org.varlink.service.InvalidParameter</literal>.</para> + + <xi:include href="version-info.xml" xpointer="v257"/></listitem> + </varlistentry> + + <varlistentry> <term>EXIT_STATUS=…</term> <listitem><para>The exit status of a service or the manager itself. Note that diff --git a/man/systemctl.xml b/man/systemctl.xml index 70fd91f45a..768a30627f 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -2862,7 +2862,9 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err which should adhere to the syntax documented in <citerefentry project='man-pages'><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> section "PARSING TIMESTAMPS". Specially, if <literal>show</literal> is given, the currently scheduled - action will be shown, which can be canceled by passing an empty string or <literal>cancel</literal>.</para> + action will be shown, which can be canceled by passing an empty string or <literal>cancel</literal>. + <literal>auto</literal> will schedule the action according to maintenance window or one minute in + the future.</para> <xi:include href="version-info.xml" xpointer="v254"/> </listitem> diff --git a/man/systemd-cryptenroll.xml b/man/systemd-cryptenroll.xml index a47866ba61..eadf5a4ace 100644 --- a/man/systemd-cryptenroll.xml +++ b/man/systemd-cryptenroll.xml @@ -310,7 +310,9 @@ <filename>/dev/hidraw1</filename>). Alternatively the special value <literal>auto</literal> may be specified, in order to automatically determine the device node of a currently plugged in security token (of which there must be exactly one). This automatic discovery is unsupported if - <option>--fido2-device=</option> option is also specified.</para> + <option>--fido2-device=</option> option is also specified. Note that currently FIDO2 devices + enrolled without an accompanying LUKS2 token (i.e. <option>--fido2-parameters-in-header=no</option>) + cannot be used for unlocking.</para> <xi:include href="version-info.xml" xpointer="v253"/></listitem> </varlistentry> @@ -402,6 +404,30 @@ </varlistentry> <varlistentry> + <term><option>--fido2-salt-file=<replaceable>PATH</replaceable></option></term> + + <listitem><para>When enrolling a FIDO2 security token, specifies the path to a file or an + <constant>AF_UNIX</constant> socket from which we should read the salt value to be used in the + HMAC operation performed by the FIDO2 security token. If this option is not specified, the salt + will be randomly generated.</para> + + <xi:include href="version-info.xml" xpointer="v257"/></listitem> + </varlistentry> + + <varlistentry> + <term><option>--fido2-parameters-in-header=<replaceable>BOOL</replaceable></option></term> + + <listitem><para>When enrolling a FIDO2 security token, controls whether to store FIDO2 + parameters in a token in the LUKS2 superblock. Defaults to <literal>yes</literal>. + If set to <literal>no</literal>, the <option>fido2-cid=</option> option has to be specified manually + in the respective <filename>/etc/crypttab</filename> line along with a key file. See + <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para> + + <xi:include href="version-info.xml" xpointer="v257"/></listitem> + </varlistentry> + + <varlistentry> <term><option>--fido2-with-client-pin=<replaceable>BOOL</replaceable></option></term> <listitem><para>When enrolling a FIDO2 security token, controls whether to require the user to enter diff --git a/man/systemd-cryptsetup.xml b/man/systemd-cryptsetup.xml index 676a38a763..1c2db11a45 100644 --- a/man/systemd-cryptsetup.xml +++ b/man/systemd-cryptsetup.xml @@ -94,8 +94,9 @@ <listitem><para>If the <varname>try-empty-password</varname> option is specified then unlocking the volume with an empty password is attempted.</para></listitem> - <listitem><para>The kernel keyring is then checked for a suitable cached password from previous - attempts.</para></listitem> + <listitem><para>If the <varname>password-cache=</varname> option is set to <literal>yes</literal> or + <literal>read-only</literal>, the kernel keyring is then checked for a suitable cached password from + previous attempts.</para></listitem> <listitem><para>Finally, the user is queried for a password, possibly multiple times, unless the <varname>headless</varname> option is set.</para></listitem> diff --git a/man/systemd-import-generator.xml b/man/systemd-import-generator.xml new file mode 100644 index 0000000000..108509d7d4 --- /dev/null +++ b/man/systemd-import-generator.xml @@ -0,0 +1,194 @@ +<?xml version="1.0"?> +<!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ +<!ENTITY % entities SYSTEM "custom-entities.ent" > +%entities; +]> +<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> +<refentry id="systemd-import-generator" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-import-generator</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-import-generator</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-import-generator</refname> + <refpurpose>Generator for automatically downloading disk images at boot</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/usr/lib/systemd/system-generators/systemd-import-generator</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-import-generator</command> may be used to automatically download disk images + (tarballs or DDIs) via + <citerefentry><refentrytitle>systemd-importd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + at boot, based on parameters on the kernel command line or via system credentials. This is useful for + automatically deploying an + <citerefentry><refentrytitle>systemd-confext</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>/ + <citerefentry><refentrytitle>systemd-vmspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> or + <citerefentry><refentrytitle>systemd-portabled.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + image at boot. This provides functionality equivalent to + <citerefentry><refentrytitle>importctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, but + accessible via the kernel command line and system credentials.</para> + + <para><filename>systemd-import-generator</filename> implements + <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>Kernel Command Line</title> + + <para><filename>systemd-import-generator</filename> understands the following + <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry> + parameters:</para> + + <variablelist class='kernel-commandline-options'> + <varlistentry> + <term><varname>systemd.pull=</varname></term> + + <listitem><para>This option takes a colon separate triplet of option string, local target image name + and remote URL. The local target image name can be specified as an empty string, in which case the + name is derived from the specified remote URL. The remote URL must using the + <literal>http://</literal>, <literal>https://</literal>, <literal>file://</literal> schemes. The + option string itself is a comma separated list of options:</para> + + <variablelist> + <varlistentry> + <term>rw</term> + <term>ro</term> + + <listitem><para>Controls whether to mark the local image as read-only. If not + specified read-only defaults to off.</para> + + <xi:include href="version-info.xml" xpointer="v257"/></listitem> + </varlistentry> + + <varlistentry> + <term>verify=</term> + + <listitem><para>Controls whether to cryptographically validate the download before installing it + in place. Takes one of <literal>no</literal>, <literal>checksum</literal> or + <literal>signature</literal> (the latter being the default if not specified). For details see the + <option>--verify=</option> of + <citerefentry><refentrytitle>importctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></para> + + <xi:include href="version-info.xml" xpointer="v257"/></listitem> + </varlistentry> + + <varlistentry> + <term>sysext</term> + <term>confext</term> + <term>machine</term> + <term>portable</term> + + <listitem><para>Controls the image class to download, and thus ultimately the target directory + for the image, depending on this choice the target directory + <filename>/var/lib/extensions/</filename>, <filename>/var/lib/confexts/</filename>, + <filename>/var/lib/machines/</filename> or <filename>/var/lib/portables/</filename> is + selected.</para> + + <para>Specification of exactly one of these options is mandatory.</para> + + <xi:include href="version-info.xml" xpointer="v257"/></listitem> + </varlistentry> + + <varlistentry> + <term>tar</term> + <term>raw</term> + + <listitem><para>Controls the type of resource to download, i.e. a (possibly compressed) tarball + that needs to be unpacked into a file system tree, or (possibly compressed) raw disk image (DDI).</para> + + <para>Specification of exactly one of these options is mandatory.</para> + + <xi:include href="version-info.xml" xpointer="v257"/></listitem> + </varlistentry> + </variablelist> + + <xi:include href="version-info.xml" xpointer="v257"/></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.pull.success_action=</varname></term> + <term><varname>systemd.pull.failure_action=</varname></term> + + <listitem><para>Controls whether to execute an action such as reboot, power-off and similar after + completing the download successfully, or unsuccessfully. See + <varname>SuccessAction=</varname>/<varname>FailureAction=</varname> on + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for + details about the available actions. If not specified no action is taken, and the system will + continue to boot normally.</para> + + <xi:include href="version-info.xml" xpointer="v257"/></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Credentials</title> + + <para><command>systemd-import-generator</command> supports the system credentials logic. The following + credentials are used when passed in:</para> + + <variablelist class='system-credentials'> + <varlistentry> + <term><varname>import.pull</varname></term> + + <listitem><para>This credential should be a text file, with each line referencing one download + operation. Each line should follow the same format as the value of the + <varname>systemd.pull=</varname> kernel command line option described above.</para> + + <xi:include href="version-info.xml" xpointer="v257"/></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + + <example> + <title>Download Configuration Extension</title> + + <programlisting>systemd.pull=raw,confext::https://example.com/myconfext.raw.gz</programlisting> + + <para>With a kernel command line option like the above a configuration extension DDI is downloaded + automatically at boot from the specified URL, validated cryptographically, uncompressed and installed.</para> + </example> + + <example> + <title>Download System Extension (Without Validation)</title> + + <programlisting>systemd.pull=tar,sysext,verify=no::https://example.com/mysysext.tar.gz</programlisting> + + <para>With a kernel command line option like the above a system extension tarball is downloaded + automatically at boot from the specified URL, uncompressed and installed – without any cryptographic + validation. This is useful for development purposes in virtual machines and containers. Warning: do not + deploy a system with validation disabled like this!</para> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + <para><simplelist type="inline"> + <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>systemd-importd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>systemd.system-credentials</refentrytitle><manvolnum>7</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>importctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> + </simplelist></para> + </refsect1> +</refentry> diff --git a/man/systemd-inhibit.xml b/man/systemd-inhibit.xml index a6dbb06c36..5299719525 100644 --- a/man/systemd-inhibit.xml +++ b/man/systemd-inhibit.xml @@ -114,6 +114,7 @@ acquiring one.</para></listitem> </varlistentry> + <xi:include href="standard-options.xml" xpointer="no-ask-password" /> <xi:include href="standard-options.xml" xpointer="no-pager" /> <xi:include href="standard-options.xml" xpointer="no-legend" /> <xi:include href="standard-options.xml" xpointer="help" /> diff --git a/man/systemd-tmpfiles.xml b/man/systemd-tmpfiles.xml index 5c68aa51d5..408b7d0577 100644 --- a/man/systemd-tmpfiles.xml +++ b/man/systemd-tmpfiles.xml @@ -169,7 +169,7 @@ <para>It is recommended to first run this command in combination with <option>--dry-run</option> (see below) to verify which files and directories will be deleted.</para> - <para><emphasis>Warning!</emphasis> This is is usually not the command you want! In most cases + <para><emphasis>Warning!</emphasis> This is usually not the command you want! In most cases <option>--remove</option> is what you are looking for.</para> <xi:include href="version-info.xml" xpointer="v256"/></listitem> diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index 9e621b9aa3..7a2fc76b65 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -675,8 +675,8 @@ of IPC objects and temporary files created by the executed processes is bound to the runtime of the service, and hence the lifetime of the dynamic user/group. Since <filename>/tmp/</filename> and <filename>/var/tmp/</filename> are usually the only world-writable directories on a system, unless - <varname>PrivateTmp=</varname> is manually enabled, those directories will be placed on a private - tmpfs filesystem, as this ensures that a unit making use of dynamic user/group allocation cannot + <varname>PrivateTmp=</varname> is manually set to <literal>true</literal>, <literal>disconnected</literal> + would be implied. This ensures that a unit making use of dynamic user/group allocation cannot leave files around after unit termination. Furthermore <varname>NoNewPrivileges=</varname> and <varname>RestrictSUIDSGID=</varname> are implicitly enabled (and cannot be disabled), to ensure that processes invoked cannot take benefit or create SUID/SGID @@ -1748,20 +1748,27 @@ BindReadOnlyPaths=/var/lib/systemd</programlisting> <varlistentry> <term><varname>PrivateTmp=</varname></term> - <listitem><para>Takes a boolean argument. If true, sets up a new file system namespace for the - executed processes and mounts private <filename>/tmp/</filename> and <filename>/var/tmp/</filename> - directories inside it that are not shared by processes outside of the namespace. This is useful to - secure access to temporary files of the process, but makes sharing between processes via - <filename>/tmp/</filename> or <filename>/var/tmp/</filename> impossible. If true, all temporary files - created by a service in these directories will be removed after the service is stopped. Defaults to - false. It is possible to run two or more units within the same private <filename>/tmp/</filename> and - <filename>/var/tmp/</filename> namespace by using the <varname>JoinsNamespaceOf=</varname> directive, - see <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. This setting is implied if <varname>DynamicUser=</varname> is set. For this setting, the - same restrictions regarding mount propagation and privileges apply as for - <varname>ReadOnlyPaths=</varname> and related calls, see above. Enabling this setting has the side - effect of adding <varname>Requires=</varname> and <varname>After=</varname> dependencies on all mount - units necessary to access <filename>/tmp/</filename> and <filename>/var/tmp/</filename>. Moreover an + <listitem><para>Takes a boolean argument, or <literal>disconnected</literal>. If enabled, a new + file system namespace will be set up for the executed processes, and <filename>/tmp/</filename> + and <filename>/var/tmp/</filename> directories inside it are not shared with processes outside of + the namespace, plus all temporary files created by a service in these directories will be removed after + the service is stopped. If <literal>true</literal>, the backing storage of the private temporary directories + will remain on the host's <filename>/tmp/</filename> and <filename>/var/tmp/</filename> directories. + If <literal>disconnected</literal>, the directories will be backed by a completely new tmpfs instance, + meaning that the storage is fully disconnected from the host namespace. Defaults to false.</para> + + <para>This setting is useful to secure access to temporary files of the process, but makes sharing + between processes via <filename>/tmp/</filename> or <filename>/var/tmp/</filename> impossible. + If not set to <literal>disconnected</literal>, it is possible to run two or more units within + the same private <filename>/tmp/</filename> and <filename>/var/tmp/</filename> namespace by using + the <varname>JoinsNamespaceOf=</varname> directive, see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. This setting is implied if <varname>DynamicUser=</varname> is set. For this setting, + the same restrictions regarding mount propagation and privileges apply as for + <varname>ReadOnlyPaths=</varname> and related calls, see above. If set to <literal>true</literal> + (as opposed to <literal>disconnected</literal>), this has the side effect of adding + <varname>Requires=</varname> and <varname>After=</varname> dependencies on all mount units necessary + to access <filename>/tmp/</filename> and <filename>/var/tmp/</filename> on the host. Moreover an implicitly <varname>After=</varname> ordering on <citerefentry><refentrytitle>systemd-tmpfiles-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> is added.</para> diff --git a/man/systemd.journal-fields.xml b/man/systemd.journal-fields.xml index bf5ac09cf6..b7a72af08b 100644 --- a/man/systemd.journal-fields.xml +++ b/man/systemd.journal-fields.xml @@ -272,11 +272,10 @@ <varlistentry> <term><varname>_SOURCE_REALTIME_TIMESTAMP=</varname></term> - <term><varname>_SOURCE_MONOTONIC_TIMESTAMP=</varname></term> <listitem> <para>The earliest trusted timestamp of the message, if any is known that is different from - the reception time of the journal. These are the <constant>CLOCK_REALTIME</constant> and - <constant>CLOCK_MONOTONIC</constant> clocks in microseconds, formatted as decimal strings.</para> + the reception time of the journal. The timestamp is in the <constant>CLOCK_REALTIME</constant> + clock in microseconds, formatted as decimal strings.</para> </listitem> </varlistentry> @@ -284,7 +283,7 @@ <term><varname>_SOURCE_BOOTTIME_TIMESTAMP=</varname></term> <listitem> <para>The earliest trusted timestamp of the message in <constant>CLOCK_BOOTTIME</constant> clock. - For details, refer to <varname>_SOURCE_MONOTONIC_TIMESTAMP=</varname>.</para> + For details, refer to <varname>_SOURCE_REALTIME_TIMESTAMP=</varname>.</para> <xi:include href="version-info.xml" xpointer="v257"/> </listitem> diff --git a/man/systemd.system-credentials.xml b/man/systemd.system-credentials.xml index d9fbae25ee..f8c27d04ac 100644 --- a/man/systemd.system-credentials.xml +++ b/man/systemd.system-credentials.xml @@ -415,6 +415,16 @@ <xi:include href="version-info.xml" xpointer="v256"/> </listitem> </varlistentry> + + <varlistentry> + <term><varname>import.pull</varname></term> + <listitem> + <para>Specified disk images (tarballs and DDIs) to automatically download and install at boot. For details see + <citerefentry><refentrytitle>systemd-import-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + + <xi:include href="version-info.xml" xpointer="v257"/> + </listitem> + </varlistentry> </variablelist> </refsect1> diff --git a/man/sysusers.d.xml b/man/sysusers.d.xml index 9d5a03e7ee..f5f12381d6 100644 --- a/man/sysusers.d.xml +++ b/man/sysusers.d.xml @@ -278,6 +278,7 @@ r - 500-900 <xi:include href="standard-specifiers.xml" xpointer="m"/> <xi:include href="standard-specifiers.xml" xpointer="M"/> <xi:include href="standard-specifiers.xml" xpointer="o"/> + <xi:include href="standard-specifiers.xml" xpointer="q"/> <xi:include href="standard-specifiers.xml" xpointer="T"/> <xi:include href="standard-specifiers.xml" xpointer="v"/> <xi:include href="standard-specifiers.xml" xpointer="V"/> diff --git a/man/tmpfiles.d.xml b/man/tmpfiles.d.xml index c89706862f..15027def60 100644 --- a/man/tmpfiles.d.xml +++ b/man/tmpfiles.d.xml @@ -306,7 +306,7 @@ L /tmp/foobar - - - - /dev/null</programlisting> argument is omitted, symlinks to files with the same name residing in the directory <filename>/usr/share/factory/</filename> are created. Note - that permissions and ownership on symlinks are ignored. + that permissions on symlinks are ignored. </para></listitem> </varlistentry> @@ -588,8 +588,8 @@ w- /proc/sys/vm/swappiness - - - - 10</programlisting></para> <citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry> is used. For <varname>z</varname> and <varname>Z</varname> lines, when omitted or when set to <literal>-</literal>, the file ownership will not be modified. These parameters are ignored for - <varname>x</varname>, <varname>r</varname>, <varname>R</varname>, <varname>L</varname>, - <varname>t</varname>, and <varname>a</varname> lines.</para> + <varname>x</varname>, <varname>r</varname>, <varname>R</varname>, <varname>t</varname>, + and <varname>a</varname> lines.</para> <para>This field should generally only reference system users/groups, i.e. users/groups that are guaranteed to be resolvable during early boot. If this field references users/groups that only become @@ -764,6 +764,7 @@ d /tmp/foo/bar - - - bmA:1h -</programlisting></para> <xi:include href="standard-specifiers.xml" xpointer="m"/> <xi:include href="standard-specifiers.xml" xpointer="M"/> <xi:include href="standard-specifiers.xml" xpointer="o"/> + <xi:include href="standard-specifiers.xml" xpointer="q"/> <row> <entry><literal>%S</literal></entry> <entry>System or user state directory</entry> diff --git a/man/varlinkctl.xml b/man/varlinkctl.xml index f21e513cb0..0ecd168c33 100644 --- a/man/varlinkctl.xml +++ b/man/varlinkctl.xml @@ -71,16 +71,23 @@ <itemizedlist> <listitem><para>A Varlink service reference starting with the <literal>unix:</literal> string, followed - by an absolute <constant>AF_UNIX</constant> socket path, or by <literal>@</literal> and an arbitrary string - (the latter for referencing sockets in the abstract namespace).</para></listitem> + by an absolute <constant>AF_UNIX</constant> socket path, or by <literal>@</literal> and an arbitrary + string (the latter for referencing sockets in the abstract namespace). In this case a stream socket + connection is made to the specified socket.</para></listitem> <listitem><para>A Varlink service reference starting with the <literal>exec:</literal> string, followed - by an absolute path of a binary to execute.</para></listitem> + by an absolute path of a binary to execute. In this case the specified process is forked off locally, + with a connected stream socket passed in.</para></listitem> - <listitem><para>A Varlink service reference starting with the <literal>ssh:</literal> string, followed + <listitem><para>A Varlink service reference starting with the <literal>ssh-unix:</literal> string, followed by an SSH host specification, followed by <literal>:</literal>, followed by an absolute <constant>AF_UNIX</constant> socket path. (This requires OpenSSH 9.4 or newer on the server side, abstract namespace sockets are not supported.)</para></listitem> + + <listitem><para>A Varlink service reference starting with the <literal>ssh-exec:</literal> string, + followed by an SSH host specification, followed by <literal>:</literal>, followed by a command line. In + this case the command is invoked and the Varlink protocol is spoken on the standard input and output of + the invoked command.</para></listitem> </itemizedlist> <para>For convenience these two simpler (redundant) service address syntaxes are also supported:</para> @@ -250,6 +257,20 @@ </listitem> </varlistentry> + <varlistentry> + <term><option>--graceful=</option></term> + + <listitem> + <para>Takes a qualified Varlink error name (i.e. an interface name, suffixed by an error name, + separated by a dot; e.g. <literal>org.varlink.service.InvalidParameter</literal>). Ensures that if + a method call fails with the specified error this will be treated as success, i.e. will cause the + <command>varlinkctl</command> invocation to exit with a zero exit status. This option may be used more + than once in order to treat multiple different errors as successes.</para> + + <xi:include href="version-info.xml" xpointer="v257"/> + </listitem> + </varlistentry> + <xi:include href="standard-options.xml" xpointer="no-pager" /> <xi:include href="standard-options.xml" xpointer="help" /> <xi:include href="standard-options.xml" xpointer="version" /> @@ -339,6 +360,22 @@ method Extend( {}</programlisting> </example> + <example> + <title>Invoking a method remotely via SSH</title> + + <para>The following command acquires a report about the identity of a remote host + <literal>somehost</literal> from + <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + by connecting via SSH to the <constant>AF_UNIX</constant> socket the service listens on:</para> + + <programlisting># varlinkctl call ssh-unix:somehost:/run/systemd/io.systemd.Hostname io.systemd.Hostname.Describe '{}'</programlisting> + + <para>To invoke a Varlink service binary directly on the remote host, rather than talking to a service + via <constant>AF_UNIX</constant> can be done like this:</para> + + <programlisting># varlinkctl call ssh-exec:somehost:/usr/bin/systemd-creds org.varlink.service.GetInfo '{}'</programlisting> + </example> + </refsect1> <refsect1> |