diff options
Diffstat (limited to 'man')
205 files changed, 8128 insertions, 2539 deletions
diff --git a/man/.dir-locals.el b/man/.dir-locals.el index 1c2512052d..c252bd3703 100644 --- a/man/.dir-locals.el +++ b/man/.dir-locals.el @@ -1,8 +1,5 @@ ; special .c mode with reduced indentation for man pages -((nil . ((indent-tabs-mode . nil) - (tab-width . 8) - (fill-column . 79))) - (c-mode . ((fill-column . 80) +((c-mode . ((fill-column . 80) (c-basic-offset . 2) (eval . (c-set-offset 'substatement-open 0)) (eval . (c-set-offset 'statement-case-open 0)) @@ -10,5 +7,8 @@ (eval . (c-set-offset 'arglist-intro '++)) (eval . (c-set-offset 'arglist-close 0)))) (nxml-mode . ((nxml-child-indent . 2) - (fill-column . 119))) - (meson-mode . ((meson-indent-basic . 8)))) + (fill-column . 109))) + (meson-mode . ((meson-indent-basic . 8))) + (nil . ((indent-tabs-mode . nil) + (tab-width . 8) + (fill-column . 79)))) diff --git a/man/bootctl.xml b/man/bootctl.xml index 9521dc9d98..9cfa9cccdf 100644 --- a/man/bootctl.xml +++ b/man/bootctl.xml @@ -34,10 +34,10 @@ <refsect1> <title>Description</title> - <para><command>bootctl</command> can check the EFI boot loader status, list - available entries, and install, update, or remove the - <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> - boot loader on the current system.</para> + <para><command>bootctl</command> can check the EFI boot loader status, list available boot loaders and boot loader + entries, and install, update, or remove the + <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> boot loader on the + current system.</para> </refsect1> <refsect1> @@ -45,8 +45,6 @@ <para>The following options are understood:</para> <variablelist> - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> <varlistentry> <term><option>--path=</option></term> <listitem><para>Path to the EFI System Partition (ESP). If not specified, <filename>/efi</filename>, @@ -64,8 +62,12 @@ <varlistentry> <term><option>--no-variables</option></term> - <listitem><para>Do not touch the EFI boot variables.</para></listitem> + <listitem><para>Do not touch the firmware's boot loader list stored in EFI variables.</para></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"/> </variablelist> </refsect1> @@ -76,42 +78,54 @@ <varlistentry> <term><option>status</option></term> - <listitem><para>Shows the currently installed versions of the boot loader binaries and all current - EFI boot variables. If no command is specified, this is the implied default.</para></listitem> + <listitem><para>Shows brief information about the system firmware, the boot loader that was used to boot the + system, the boot loaders currently available in the ESP, the boot loaders listed in the firmware's list of boot + loaders and the current default boot loader entry. If no command is specified, this is the implied + default.</para></listitem> </varlistentry> <varlistentry> - <term><option>list</option></term> + <term><option>install</option></term> - <listitem><para>Shows all configured boot loader entries.</para></listitem> + <listitem><para>Installs systemd-boot into the EFI system partition. A copy of <command>systemd-boot</command> + will be stored as the EFI default/fallback loader at + <filename><replaceable>ESP</replaceable>/EFI/BOOT/BOOT*.EFI</filename>. The boot loader is then added to the + top of the firmware's boot loader list.</para></listitem> </varlistentry> <varlistentry> <term><option>update</option></term> <listitem><para>Updates all installed versions of - <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - if the current version is newer than the version installed in the EFI system - partition. This also includes the EFI default/fallback loader at - <filename><replaceable>ESP</replaceable>/EFI/BOOT/BOOT*.EFI</filename>. A - systemd-boot entry in the EFI boot variables is created if there is no current - entry. The created entry will be added to the end of the boot order list.</para></listitem> + <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>, if the + available version is newer than the version installed in the EFI system partition. This also includes the EFI + default/fallback loader at <filename><replaceable>ESP</replaceable>/EFI/BOOT/BOOT*.EFI</filename>. The boot + loader is then added to end of the firmware's boot loader list if missing.</para></listitem> </varlistentry> <varlistentry> - <term><option>install</option></term> + <term><option>remove</option></term> - <listitem><para>Installs systemd-boot into the EFI system partition. A copy of systemd-boot will - be stored as the EFI default/fallback loader at - <filename><replaceable>ESP</replaceable>/EFI/BOOT/BOOT*.EFI</filename>. A systemd-boot entry in - the EFI boot variables is created and added to the top of the boot order list.</para></listitem> + <listitem><para>Removes all installed versions of <command>systemd-boot</command> from the EFI system partition + and the firmware's boot loader list.</para></listitem> </varlistentry> <varlistentry> - <term><option>remove</option></term> + <term><option>list</option></term> - <listitem><para>Removes all installed versions of systemd-boot from the EFI system partition, - and removes systemd-boot from the EFI boot variables.</para></listitem> + <listitem><para>Shows all available boot loader entries implementing the <ulink + url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader + Specification</ulink>, as well as any other entries discovered or automatically generated by the boot + loader.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>set-default</option> <replaceable>ID</replaceable></term> + <term><option>set-oneshot</option> <replaceable>ID</replaceable></term> + + <listitem><para>Sets the default boot loader entry. Takes a single boot loader entry ID string as argument. The + <option>set-oneshot</option> command will set the default entry only for the next boot, the + <option>set-default</option> will set it persistently for all future boots.</para></listitem> </varlistentry> </variablelist> @@ -123,11 +137,18 @@ </refsect1> <refsect1> + <title>Environment</title> + <para>If <varname>$SYSTEMD_RELAX_ESP_CHECKS=1</varname> is set the validation checks for the ESP are relaxed, and + the path specified with <option>--path=</option> may refer to any kind of file system on any kind of + partition.</para> + </refsect1> + + <refsect1> <title>See Also</title> <para> <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <ulink url="https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md">Boot Loader Specification</ulink>, - <ulink url="https://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface">Boot Loader Interface</ulink> + <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>, + <ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink> </para> </refsect1> </refentry> diff --git a/man/busctl.xml b/man/busctl.xml index c0bbed1c87..a5e3d92cf0 100644 --- a/man/busctl.xml +++ b/man/busctl.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -144,6 +144,28 @@ </varlistentry> <varlistentry> + <term><option>--json=</option><replaceable>MODE</replaceable></term> + + <listitem> + <para>When used with the <command>call</command> or <command>get-property</command> command, shows output + formatted as JSON. Expects one of <literal>short</literal> (for the shortest possible output without any + redundant whitespace or line breaks) or <literal>pretty</literal> (for a pretty version of the same, with + indentation and line breaks). Note that transformation from D-Bus marshalling to JSON is done in a loss-less + way, which means type information is embedded into the JSON object tree.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-j</option></term> + + <listitem> + <para>Equivalent to <option>--json=pretty</option> when invoked interactively from a terminal. Otherwise + equivalent to <option>--json=short</option>, in particular when the output is piped to some other + program.</para> + </listitem> + </varlistentry> + + <varlistentry> <term><option>--expect-reply=</option><replaceable>BOOL</replaceable></term> <listitem> @@ -269,8 +291,9 @@ <listitem><para>Dump messages being exchanged. If <replaceable>SERVICE</replaceable> is specified, show messages to or from this peer, identified by its well-known or unique - name. Otherwise, show all messages on the bus. Use Ctrl-C to - terminate the dump.</para></listitem> + name. Otherwise, show all messages on the bus. Use + <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo> + to terminate the dump.</para></listitem> </varlistentry> <varlistentry> diff --git a/man/coredump.conf.xml b/man/coredump.conf.xml index 43a3679130..ee3c1b6919 100644 --- a/man/coredump.conf.xml +++ b/man/coredump.conf.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/coredumpctl.xml b/man/coredumpctl.xml index caa1bb1c0f..94d5626fb5 100644 --- a/man/coredumpctl.xml +++ b/man/coredumpctl.xml @@ -210,7 +210,8 @@ <varlistentry> <term><command>info</command></term> - <listitem><para>Show detailed information about core dumps + <listitem><para>Show detailed information about the last core dump + or core dumps matching specified characteristics captured in the journal.</para></listitem> </varlistentry> diff --git a/man/crypttab.xml b/man/crypttab.xml index dcaf03d2ca..3574ce00da 100644 --- a/man/crypttab.xml +++ b/man/crypttab.xml @@ -251,6 +251,15 @@ </varlistentry> <varlistentry> + <term><option>sector-size=</option></term> + + <listitem><para>Specifies the sector size in bytes. See + <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for possible values and the default value of this + option.</para></listitem> + </varlistentry> + + <varlistentry> <term><option>swap</option></term> <listitem><para>The encrypted block device will be used as a diff --git a/man/daemon.xml b/man/daemon.xml index 36c7c09db1..7724bb4e08 100644 --- a/man/daemon.xml +++ b/man/daemon.xml @@ -593,7 +593,7 @@ AM_CONDITIONAL([HAVE_SYSTEMD], [test "x$with_systemdsystemunitdir" != "xno"])</p <citerefentry project='die-net'><refentrytitle>automake</refentrytitle><manvolnum>1</manvolnum></citerefentry>-based projects:</para> - <programlisting>DISTCHECK_CONFIGURE_FLAGS = \ + <programlisting>AM_DISTCHECK_CONFIGURE_FLAGS = \ --with-systemdsystemunitdir=$$dc_install_base/$(systemdsystemunitdir)</programlisting> <para>Finally, unit files should be installed in the system with an automake excerpt like the following:</para> diff --git a/man/dnssec-trust-anchors.d.xml b/man/dnssec-trust-anchors.d.xml index 541febc38b..d5faee2918 100644 --- a/man/dnssec-trust-anchors.d.xml +++ b/man/dnssec-trust-anchors.d.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/hwdb.xml b/man/hwdb.xml index e77776f35f..7d550c6d7e 100644 --- a/man/hwdb.xml +++ b/man/hwdb.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/id128-app-specific.c b/man/id128-app-specific.c new file mode 100644 index 0000000000..b81e50ff32 --- /dev/null +++ b/man/id128-app-specific.c @@ -0,0 +1,11 @@ +#include <stdio.h> +#include <systemd/sd-id128.h> + +#define OUR_APPLICATION_ID SD_ID128_MAKE(c2,73,27,73,23,db,45,4e,a6,3b,b9,6e,79,b5,3e,97) + +int main(int argc, char *argv[]) { + sd_id128_t id; + sd_id128_get_machine_app_specific(OUR_APPLICATION_ID, &id); + printf("Our application ID: " SD_ID128_FORMAT_STR "\n", SD_ID128_FORMAT_VAL(id)); + return 0; +} diff --git a/man/journal-iterate-unique.c b/man/journal-iterate-unique.c new file mode 100644 index 0000000000..fcf92e7b3f --- /dev/null +++ b/man/journal-iterate-unique.c @@ -0,0 +1,25 @@ +#include <stdio.h> +#include <string.h> +#include <systemd/sd-journal.h> + +int main(int argc, char *argv[]) { + sd_journal *j; + const void *d; + size_t l; + int r; + + r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY); + if (r < 0) { + fprintf(stderr, "Failed to open journal: %s\n", strerror(-r)); + return 1; + } + r = sd_journal_query_unique(j, "_SYSTEMD_UNIT"); + if (r < 0) { + fprintf(stderr, "Failed to query journal: %s\n", strerror(-r)); + return 1; + } + SD_JOURNAL_FOREACH_UNIQUE(j, d, l) + printf("%.*s\n", (int) l, (const char*) d); + sd_journal_close(j); + return 0; +} diff --git a/man/journalctl.xml b/man/journalctl.xml index a4f9e2d7ee..58f3aa205a 100644 --- a/man/journalctl.xml +++ b/man/journalctl.xml @@ -148,9 +148,9 @@ <term><option>-a</option></term> <term><option>--all</option></term> - <listitem><para>Show all fields in full, even if they - include unprintable characters or are very - long.</para></listitem> + <listitem><para>Show all fields in full, even if they include unprintable characters or are very long. By + default, fields with unprintable characters are abbreviated as "blob data". (Note that the pager may escape + unprintable characters again.)</para></listitem> </varlistentry> <varlistentry> @@ -316,10 +316,23 @@ <option>json</option> </term> <listitem> - <para>formats entries as JSON data structures, one per - line (see - <ulink url="https://www.freedesktop.org/wiki/Software/systemd/json">Journal JSON Format</ulink> - for more information).</para> + <para>formats entries as JSON objects, separated by newline characters (see <ulink + url="https://www.freedesktop.org/wiki/Software/systemd/json">Journal JSON Format</ulink> for more + information). Field values are generally encoded as JSON strings, with three exceptions: + <orderedlist> + <listitem><para>Fields larger than 4096 bytes are encoded as <constant>null</constant> values. (This + may be turned off by passing <option>--all</option>, but be aware that this may allocate overly long + JSON objects.) </para></listitem> + + <listitem><para>Journal entries permit non-unique fields within the same log entry. JSON does not allow + non-unique fields within objects. Due to this, if a non-unique field is encountered a JSON array is + used as field value, listing all field values as elements.</para></listitem> + + <listitem><para>Fields containing non-printable or non-UTF8 bytes are encoded as arrays containing + the raw bytes individually formatted as unsigned numbers.</para></listitem> + </orderedlist> + + Note that this encoding is reversible (with the exception of the size limit).</para> </listitem> </varlistentry> @@ -348,6 +361,19 @@ <varlistentry> <term> + <option>json-seq</option> + </term> + <listitem> + <para>formats entries as JSON data structures, but prefixes them with an ASCII Record Separator + character (0x1E) and suffixes them with an ASCII Line Feed character (0x0A), in accordance with <ulink + url="https://tools.ietf.org/html/rfc7464">JavaScript Object Notation (JSON) Text Sequences </ulink> + (<literal>application/json-seq</literal>). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> <option>cat</option> </term> <listitem> @@ -375,14 +401,11 @@ <varlistentry> <term><option>--output-fields=</option></term> - <listitem><para>A comma separated list of the fields which should - be included in the output. This only has an effect for the output modes - which would normally show all fields (<option>verbose</option>, - <option>export</option>, <option>json</option>, - <option>json-pretty</option>, and <option>json-sse</option>). The - <literal>__CURSOR</literal>, <literal>__REALTIME_TIMESTAMP</literal>, - <literal>__MONOTONIC_TIMESTAMP</literal>, and - <literal>_BOOT_ID</literal> fields are always + <listitem><para>A comma separated list of the fields which should be included in the output. This only has an + effect for the output modes which would normally show all fields (<option>verbose</option>, + <option>export</option>, <option>json</option>, <option>json-pretty</option>, <option>json-sse</option> and + <option>json-seq</option>). The <literal>__CURSOR</literal>, <literal>__REALTIME_TIMESTAMP</literal>, + <literal>__MONOTONIC_TIMESTAMP</literal>, and <literal>_BOOT_ID</literal> fields are always printed.</para></listitem> </varlistentry> @@ -706,18 +729,6 @@ </varlistentry> <varlistentry> - <term><option>--new-id128</option></term> - - <listitem><para>Instead of showing journal contents, generate - a new 128-bit ID suitable for identifying messages. This is - intended for usage by developers who need a new identifier for - a new message they introduce and want to make - recognizable. This will print the new ID in four different - formats which can be copied into source code or similar. - </para></listitem> - </varlistentry> - - <varlistentry> <term><option>--header</option></term> <listitem><para>Instead of showing journal contents, show @@ -738,32 +749,28 @@ <term><option>--vacuum-time=</option></term> <term><option>--vacuum-files=</option></term> - <listitem><para>Removes the oldest archived journal files until the disk - space they use falls below the specified size (specified with - the usual <literal>K</literal>, <literal>M</literal>, - <literal>G</literal> and <literal>T</literal> suffixes), or all - archived journal files contain no data older than the specified - timespan (specified with the usual <literal>s</literal>, - <literal>m</literal>, <literal>h</literal>, - <literal>days</literal>, <literal>months</literal>, - <literal>weeks</literal> and <literal>years</literal> suffixes), - or no more than the specified number of separate journal files - remain. Note that running <option>--vacuum-size=</option> has - only an indirect effect on the output shown by - <option>--disk-usage</option>, as the latter includes active - journal files, while the vacuuming operation only operates - on archived journal files. Similarly, - <option>--vacuum-files=</option> might not actually reduce the - number of journal files to below the specified number, as it - will not remove active journal - files. <option>--vacuum-size=</option>, - <option>--vacuum-time=</option> and - <option>--vacuum-files=</option> may be combined in a single - invocation to enforce any combination of a size, a time and a - number of files limit on the archived journal - files. Specifying any of these three parameters as zero is - equivalent to not enforcing the specific limit, and is thus - redundant.</para></listitem> + <listitem><para>Removes the oldest archived journal files until the disk space they use falls below the + specified size (specified with the usual <literal>K</literal>, <literal>M</literal>, <literal>G</literal> and + <literal>T</literal> suffixes), or all archived journal files contain no data older than the specified timespan + (specified with the usual <literal>s</literal>, <literal>m</literal>, <literal>h</literal>, + <literal>days</literal>, <literal>months</literal>, <literal>weeks</literal> and <literal>years</literal> + suffixes), or no more than the specified number of separate journal files remain. Note that running + <option>--vacuum-size=</option> has only an indirect effect on the output shown by + <option>--disk-usage</option>, as the latter includes active journal files, while the vacuuming operation only + operates on archived journal files. Similarly, <option>--vacuum-files=</option> might not actually reduce the + number of journal files to below the specified number, as it will not remove active journal + files.</para> + + <para><option>--vacuum-size=</option>, <option>--vacuum-time=</option> and <option>--vacuum-files=</option> + may be combined in a single invocation to enforce any combination of a size, a time and a number of files limit + on the archived journal files. Specifying any of these three parameters as zero is equivalent to not enforcing + the specific limit, and is thus redundant.</para> + + <para>These three switches may also be combined with <option>--rotate</option> into one command. If so, all + active files are rotated first, and the requested vacuuming operation is executed right after. The rotation has + the effect that all currently active files are archived (and potentially new, empty journal files opened as + replacement), and hence the vacuuming operation has the greatest effect as it can take all log data written so + far into account.</para></listitem> </varlistentry> <varlistentry> @@ -885,9 +892,12 @@ <varlistentry> <term><option>--rotate</option></term> - <listitem><para>Asks the journal daemon to rotate journal - files. This call does not return until the rotation operation - is complete.</para></listitem> + <listitem><para>Asks the journal daemon to rotate journal files. This call does not return until the rotation + operation is complete. Journal file rotation has the effect that all currently active journal files are marked + as archived and renamed, so that they are never written to in future. New (empty) journal files are then + created in their place. This operation may be combined with <option>--vacuum-size=</option>, + <option>--vacuum-time=</option> and <option>--vacuum-file=</option> into a single command, see + above.</para></listitem> </varlistentry> <xi:include href="standard-options.xml" xpointer="help" /> diff --git a/man/journald.conf.xml b/man/journald.conf.xml index ee8e8b7faf..ed874aace9 100644 --- a/man/journald.conf.xml +++ b/man/journald.conf.xml @@ -140,7 +140,13 @@ following units: <literal>s</literal>, <literal>min</literal>, <literal>h</literal>, <literal>ms</literal>, <literal>us</literal>. To turn off any kind of rate limiting, - set either value to 0.</para></listitem> + set either value to 0.</para> + + <para>If a service provides rate limits for itself through + <varname>LogRateLimitIntervalSec=</varname> and/or <varname>LogRateLimitBurst=</varname> + in <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + those values will override the settings specified here.</para> + </listitem> </varlistentry> <varlistentry> @@ -195,7 +201,11 @@ subsequently something else causes the file system to fill up, journald will stop using more space, but it will not be removing existing files to reduce the footprint again, - either.</para> + either. Also note that only archived files are deleted to reduce the + space occupied by journal files. This means that, in effect, there might + still be more space used than <varname>SystemMaxUse=</varname> or + <varname>RuntimeMaxUse=</varname> limit after a vacuuming operation is + complete.</para> <para><varname>SystemMaxFileSize=</varname> and <varname>RuntimeMaxFileSize=</varname> control how large diff --git a/man/kernel-command-line.xml b/man/kernel-command-line.xml index 0545f9d84b..9d86bdf203 100644 --- a/man/kernel-command-line.xml +++ b/man/kernel-command-line.xml @@ -55,6 +55,7 @@ <term><varname>systemd.unit=</varname></term> <term><varname>rd.systemd.unit=</varname></term> <term><varname>systemd.dump_core</varname></term> + <term><varname>systemd.early_core_pattern=</varname></term> <term><varname>systemd.crash_chvt</varname></term> <term><varname>systemd.crash_shell</varname></term> <term><varname>systemd.crash_reboot</varname></term> @@ -91,6 +92,27 @@ </varlistentry> <varlistentry> + <term><varname>systemd.run=</varname></term> + <term><varname>systemd.run_success_action=</varname></term> + <term><varname>systemd.run_failure_action=</varname></term> + <listitem> + <para>Additional parameters understood by + <citerefentry><refentrytitle>systemd-run-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, to + run a command line specified on the kernel command line as system service after booting up.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.early_core_pattern=</varname></term> + <listitem> + <para>During early boot, the generation of core dump files is disabled until a core dump handler (if any) + takes over. This parameter allows to specifies an absolute path where core dump files should be stored until + a handler is installed. The path should be absolute and may contain specifiers, see + <citerefentry><refentrytitle>core</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.</para> + </listitem> + </varlistentry> + + <varlistentry> <term><varname>systemd.restore_state=</varname></term> <listitem> <para>This parameter is understood by several system tools @@ -246,6 +268,7 @@ <term><varname>udev.event_timeout=</varname></term> <term><varname>rd.udev.event_timeout=</varname></term> <term><varname>net.ifnames=</varname></term> + <term><varname>net.naming-scheme=</varname></term> <listitem> <para>Parameters understood by the device event managing diff --git a/man/kernel-install.xml b/man/kernel-install.xml index cd9756662a..83e50c8d70 100644 --- a/man/kernel-install.xml +++ b/man/kernel-install.xml @@ -1,11 +1,9 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- SPDX-License-Identifier: LGPL-2.1+ - - Copyright © 2013 Harald Hoyer --> <refentry id="kernel-install"> @@ -65,49 +63,61 @@ <varlistentry> <term><command>add <replaceable>KERNEL-VERSION</replaceable> <replaceable>KERNEL-IMAGE</replaceable></command></term> <listitem> - <para><command>kernel-install</command> creates the directory + <para>This command expects a kernel version string and a path to a kernel image file as + arguments. <command>kernel-install</command> creates the directory <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename> - and calls executables from - <filename>/usr/lib/kernel/install.d/*.install</filename> and - <filename>/etc/kernel/install.d/*.install</filename> with - the arguments - <programlisting>add <replaceable>KERNEL-VERSION</replaceable> \ - <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename> <replaceable>KERNEL-IMAGE</replaceable></programlisting> + and calls the executables from <filename>/usr/lib/kernel/install.d/*.install</filename> and + <filename>/etc/kernel/install.d/*.install</filename> with the following arguments: + + <programlisting>add <replaceable>KERNEL-VERSION</replaceable> <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename> <replaceable>KERNEL-IMAGE</replaceable></programlisting> </para> - <para>The kernel-install plugin <filename>50-depmod.install</filename> runs depmod for the <replaceable>KERNEL-VERSION</replaceable>.</para> - - <para>The kernel-install plugin - <filename>90-loaderentry.install</filename> copies - <replaceable>KERNEL-IMAGE</replaceable> to - <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/linux</filename>. - It also creates a boot loader entry according to the boot - loader specification in - <filename>/boot/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>. - The title of the entry is the - <replaceable>PRETTY_NAME</replaceable> parameter specified - in <filename>/etc/os-release</filename> or - <filename>/usr/lib/os-release</filename> (if the former is - missing), or "Linux - <replaceable>KERNEL-VERSION</replaceable>", if unset. If - the file <filename>initrd</filename> is found next to the - <filename>linux</filename> file, the initrd will be added to - the configuration.</para> + <para>Two default plugins execute the following operations in this case:</para> + + <itemizedlist> + + <listitem><para><filename>50-depmod.install</filename> runs + <citerefentry><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum></citerefentry> for the + <replaceable>KERNEL-VERSION</replaceable>.</para></listitem> + + <listitem><para><filename>90-loaderentry.install</filename> copies <replaceable>KERNEL-IMAGE</replaceable> + to + <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/linux</filename>. + It also creates a boot loader entry according to the <ulink + url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink> in + <filename>/boot/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>. + The title of the entry is the <replaceable>PRETTY_NAME</replaceable> parameter specified in + <filename>/etc/os-release</filename> or <filename>/usr/lib/os-release</filename> (if the former is + missing), or "Linux <replaceable>KERNEL-VERSION</replaceable>", if unset. If the file + <filename>initrd</filename> is found next to the kernel image file, the initrd will be added to the + configuration.</para></listitem> + </itemizedlist> </listitem> </varlistentry> <varlistentry> <term><command>remove <replaceable>KERNEL-VERSION</replaceable></command></term> <listitem> - <para>Calls executables from <filename>/usr/lib/kernel/install.d/*.install</filename> - and <filename>/etc/kernel/install.d/*.install</filename> with the arguments + <para>This command expects a kernel version string as single argument. This calls executables from + <filename>/usr/lib/kernel/install.d/*.install</filename> and + <filename>/etc/kernel/install.d/*.install</filename> with the following arguments: + <programlisting>remove <replaceable>KERNEL-VERSION</replaceable> <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename></programlisting> </para> - <para><command>kernel-install</command> removes the entire directory - <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename> afterwards.</para> + <para>Afterwards, <command>kernel-install</command> removes the directory + <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename> + and its contents.</para> + + <para>Two default plugins execute the following operations in this case:</para> + + <itemizedlist> + + <listitem><para><filename>50-depmod.install</filename> removes the files generated by <command>depmod</command> for this kernel again.</para></listitem> + + <listitem><para><filename>90-loaderentry.install</filename> removes the file + <filename>/boot/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.</para></listitem> + </itemizedlist> - <para>The kernel-install plugin <filename>90-loaderentry.install</filename> removes the file - <filename>/boot/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.</para> </listitem> </varlistentry> @@ -138,8 +148,22 @@ <filename>/proc/cmdline</filename> </term> <listitem> - <para>The content of the file <filename>/etc/kernel/cmdline</filename> specifies the kernel command line to use. - If that file does not exist, <filename>/proc/cmdline</filename> is used.</para> + <para>Read by <filename>90-loaderentry.install</filename>. The content of the file + <filename>/etc/kernel/cmdline</filename> specifies the kernel command line to use. If that file does not + exist, <filename>/proc/cmdline</filename> is used.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <filename>/etc/kernel/tries</filename> + </term> + <listitem> + <para>Read by <filename>90-loaderentry.install</filename>. If this file exists a numeric value is read from + it and the naming of the generated entry file is slightly altered to include it as + <filename>/boot/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>+<replaceable>TRIES</replaceable>.conf</filename>. This + is useful for boot loaders such as + <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> which + implement boot attempt counting with a counter embedded in the entry file name.</para> </listitem> </varlistentry> <varlistentry> @@ -167,7 +191,9 @@ <para> <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <ulink url="https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md">Boot Loader Specification</ulink> + <citerefentry><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink> </para> </refsect1> diff --git a/man/less-variables.xml b/man/less-variables.xml index a3faa38997..eb332b56b0 100644 --- a/man/less-variables.xml +++ b/man/less-variables.xml @@ -26,7 +26,13 @@ <term><varname>$SYSTEMD_LESS</varname></term> <listitem><para>Override the options passed to <command>less</command> (by default - <literal>FRSXMK</literal>).</para></listitem> + <literal>FRSXMK</literal>).</para> + + <para>If the value of <varname>$SYSTEMD_LESS</varname> does not include <literal>K</literal>, + and the pager that is invoked is <command>less</command>, + <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo> will be ignored by the + executable. This allows <command>less</command> to handle + <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo> itself.</para></listitem> </varlistentry> <varlistentry id='lesscharset'> diff --git a/man/libudev.xml b/man/libudev.xml index 8cb4ba59fc..382c1aa25c 100644 --- a/man/libudev.xml +++ b/man/libudev.xml @@ -48,11 +48,9 @@ <citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>. It is used to track library state and link objects together. No global state is used by libudev, everything is always linked to - a udev context. Furthermore, multiple different udev contexts can - be used in parallel by multiple threads. However, a single context - must not be accessed by multiple threads in parallel. The caller - is responsible for providing suitable locking if they intend to use - it from multiple threads.</para> + a udev context.</para> + + <xi:include href="threads-aware.xml" xpointer="strict"/> <para>To introspect a local device on a system, a udev device object can be created via diff --git a/man/loader.conf.xml b/man/loader.conf.xml index 6f8d0489d2..f9d98dd4d9 100644 --- a/man/loader.conf.xml +++ b/man/loader.conf.xml @@ -23,7 +23,7 @@ <refsynopsisdiv> <para><filename><replaceable>ESP</replaceable>/loader/loader.conf</filename>, - <filename><replaceable>ESP</replaceable>/loader/loader.conf.d/*.conf</filename> + <filename><replaceable>ESP</replaceable>/loader/entries/*.conf</filename> </para> </refsynopsisdiv> @@ -32,9 +32,9 @@ <para> <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> - will read <filename>/loader/loader.conf</filename> and any files with the + will read <filename><replaceable>ESP</replaceable>/loader/loader.conf</filename> and any files with the <literal>.conf</literal> extension under - <filename>/loader/loader.conf.d/</filename> on the EFI system partition (ESP). + <filename><replaceable>ESP</replaceable>/loader/entries/</filename> on the EFI system partition (ESP). </para> <para>Each configuration file must consist of an option name, followed by @@ -50,7 +50,7 @@ <refsect1> <title>Options</title> - <para>The following configuration options are understood:</para> + <para>The following configuration options in <filename>loader.conf</filename> are understood:</para> <variablelist> <varlistentry> diff --git a/man/locale.conf.xml b/man/locale.conf.xml index e89d0bead5..2f463de6b6 100644 --- a/man/locale.conf.xml +++ b/man/locale.conf.xml @@ -67,7 +67,7 @@ might be checked for locale configuration as well, however only as fallback.</para> - <para><filename>/etc/vconsole.conf</filename> is usually created and updated + <para><filename>/etc/locale.conf</filename> is usually created and updated using <citerefentry><refentrytitle>systemd-localed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. <citerefentry project='man-pages'><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> diff --git a/man/logind.conf.xml b/man/logind.conf.xml index 9e88764c6f..a407858957 100644 --- a/man/logind.conf.xml +++ b/man/logind.conf.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ <!ENTITY % entities SYSTEM "custom-entities.ent" > @@ -185,6 +185,17 @@ </varlistentry> <varlistentry> + <term><varname>UserStopDelaySec=</varname></term> + + <listitem><para>Specifies how long to keep the user record and per-user service + <filename>user@.service</filename> around for a user after they logged out fully. If set to zero, the per-user + service is terminated immediately when the last session of the user has ended. If this option is configured to + non-zero rapid logout/login cycles are sped up, as the user's service manager is not constantly restarted. If + set to <literal>infinity</literal> the per-user service for a user is never terminated again after first login, + and continues to run until system shutdown. Defaults to 10s.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>HandlePowerKey=</varname></term> <term><varname>HandleSuspendKey=</varname></term> <term><varname>HandleHibernateKey=</varname></term> diff --git a/man/machinectl.xml b/man/machinectl.xml index affca1dec1..95823eb413 100644 --- a/man/machinectl.xml +++ b/man/machinectl.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -70,11 +70,12 @@ top-level directories <filename>/usr</filename>, <filename>/etc</filename>, and so on.</para></listitem> - <listitem><para>btrfs subvolumes containing OS trees, similar to - normal directory trees.</para></listitem> + <listitem><para>btrfs subvolumes containing OS trees, similar to regular directory trees.</para></listitem> - <listitem><para>Binary "raw" disk images containing MBR or GPT - partition tables and Linux file system partitions.</para></listitem> + <listitem><para>Binary "raw" disk image files containing MBR or GPT partition tables and Linux file + systems.</para></listitem> + + <listitem><para>Similarly, block devices containing MBR or GPT partition tables and file systems.</para></listitem> <listitem><para>The file system tree of the host OS itself.</para></listitem> </itemizedlist> @@ -649,22 +650,7 @@ units. If the size limit shall be disabled, specify <literal>-</literal> as size.</para> - <para>Note that per-container size limits are only supported - on btrfs file systems. Also note that, if - <command>set-limit</command> is invoked without an image - parameter, and <filename>/var/lib/machines</filename> is - empty, and the directory is not located on btrfs, a btrfs - loopback file is implicitly created as - <filename>/var/lib/machines.raw</filename> with the given - size, and mounted to - <filename>/var/lib/machines</filename>. The size of the - loopback may later be readjusted with - <command>set-limit</command>, as well. If such a - loopback-mounted <filename>/var/lib/machines</filename> - directory is used, <command>set-limit</command> without an image - name alters both the quota setting within the file system as - well as the loopback file and file system size - itself.</para></listitem> + <para>Note that per-container size limits are only supported on btrfs file systems.</para></listitem> </varlistentry> <varlistentry> @@ -802,12 +788,8 @@ image is read from standard input, in which case the second argument is mandatory.</para> - <para>Both <command>pull-tar</command> and <command>pull-raw</command> - will resize <filename>/var/lib/machines.raw</filename> and the - filesystem therein as necessary. Optionally, the - <option>--read-only</option> switch may be used to create a - read-only container or VM image. No cryptographic validation - is done when importing the images.</para> + <para>Optionally, the <option>--read-only</option> switch may be used to create a read-only container or VM + image. No cryptographic validation is done when importing the images.</para> <para>Much like image downloads, ongoing imports may be listed with <command>list-transfers</command> and aborted with @@ -815,6 +797,15 @@ </varlistentry> <varlistentry> + <term><command>import-fs</command> <replaceable>DIRECTORY</replaceable> [<replaceable>NAME</replaceable>]</term> + + <listitem><para>Imports a container image stored in a local directory into + <filename>/var/lib/machines/</filename>, operates similar to <command>import-tar</command> or + <command>import-raw</command>, but the first argument is the source directory. If supported, this command will + create btrfs snapshot or subvolume for the new image.</para></listitem> + </varlistentry> + + <varlistentry> <term><command>export-tar</command> <replaceable>NAME</replaceable> [<replaceable>FILE</replaceable>]</term> <term><command>export-raw</command> <replaceable>NAME</replaceable> [<replaceable>FILE</replaceable>]</term> <listitem><para>Exports a TAR or RAW container or VM image and @@ -910,18 +901,7 @@ <filename>/var/lib/machines/</filename> to make them available for control with <command>machinectl</command>.</para> - <para>Note that some image operations are only supported, - efficient or atomic on btrfs file systems. Due to this, if the - <command>pull-tar</command>, <command>pull-raw</command>, - <command>import-tar</command>, <command>import-raw</command> and - <command>set-limit</command> commands notice that - <filename>/var/lib/machines</filename> is empty and not located on - btrfs, they will implicitly set up a loopback file - <filename>/var/lib/machines.raw</filename> containing a btrfs file - system that is mounted to - <filename>/var/lib/machines</filename>. The size of this loopback - file may be controlled dynamically with - <command>set-limit</command>.</para> + <para>Note that some image operations are only supported, efficient or atomic on btrfs file systems.</para> <para>Disk images are understood by <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> diff --git a/man/meson.build b/man/meson.build index ec05d73bc6..05197d6ef4 100644 --- a/man/meson.build +++ b/man/meson.build @@ -47,8 +47,8 @@ foreach tuple : xsltproc.found() ? manpages : [] manaliases = [] htmlaliases = [] foreach alias : aliases - manaliases += [alias + '.' + section] - htmlaliases += [alias + '.html'] + manaliases += alias + '.' + section + htmlaliases += alias + '.html' endforeach mandirn = join_paths(get_option('mandir'), 'man' + section) @@ -62,7 +62,7 @@ foreach tuple : xsltproc.found() ? manpages : [] depend_files : custom_entities_ent, install : want_man, install_dir : mandirn) - man_pages += [p1] + man_pages += p1 p2 = [] foreach htmlalias : htmlaliases @@ -75,9 +75,9 @@ foreach tuple : xsltproc.found() ? manpages : [] dst = join_paths(docdir, 'html', htmlalias) cmd = 'ln -fs @0@ $DESTDIR@1@'.format(html, dst) meson.add_install_script('sh', '-c', cmd) - p2 += [link] + p2 += link endif - html_pages += [link] + html_pages += link endforeach p3 = custom_target( @@ -89,7 +89,7 @@ foreach tuple : xsltproc.found() ? manpages : [] depends : p2, install : want_html, install_dir : join_paths(docdir, 'html')) - html_pages += [p3] + html_pages += p3 source_xml_files += files(tuple[0] + '.xml') else @@ -117,8 +117,8 @@ systemd_index_xml = custom_target( output : 'systemd.index.xml', command : [make_man_index_py, '@OUTPUT@'] + nonindex_xml_files) -foreach tuple : want_man or want_html ? [['systemd.directives', '7', systemd_directives_xml], - ['systemd.index', '7', systemd_index_xml]] : [] +foreach tuple : xsltproc.found() ? [['systemd.directives', '7', systemd_directives_xml], + ['systemd.index', '7', systemd_index_xml]] : [] stem = tuple[0] section = tuple[1] xml = tuple[2] @@ -135,7 +135,7 @@ foreach tuple : want_man or want_html ? [['systemd.directives', '7', systemd_dir command : xslt_cmd + [custom_man_xsl, '@INPUT@'], install : want_man and have_lxml, install_dir : mandirn) - man_pages += [p1] + man_pages += p1 p2 = [] if html == 'systemd.index.html' @@ -149,9 +149,9 @@ foreach tuple : want_man or want_html ? [['systemd.directives', '7', systemd_dir dst = join_paths(docdir, 'html', htmlalias) cmd = 'ln -fs @0@ $DESTDIR@1@'.format(html, dst) meson.add_install_script('sh', '-c', cmd) - p2 += [link] + p2 += link endif - html_pages += [link] + html_pages += link endif p3 = custom_target( @@ -163,10 +163,11 @@ foreach tuple : want_man or want_html ? [['systemd.directives', '7', systemd_dir depends : p2, install : want_html and have_lxml, install_dir : join_paths(docdir, 'html')) - html_pages += [p3] + html_pages += p3 endforeach -# cannot use run_target until https://github.com/mesonbuild/meson/issues/1644 is resolved +# Cannot use run_target because those targets are used in depends +# Also see https://github.com/mesonbuild/meson/issues/368. man = custom_target( 'man', output : 'man', diff --git a/man/networkctl.xml b/man/networkctl.xml index 8c750cc1b1..7877755edf 100644 --- a/man/networkctl.xml +++ b/man/networkctl.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -92,6 +92,88 @@ 4 virbr0-nic ether off unmanaged 4 links listed.</programlisting></para> + + <para>The operational status is one of the following: + <variablelist> + <varlistentry> + <term>off</term> + <listitem> + <para>the device is powered down</para> + </listitem> + </varlistentry> + <varlistentry> + <term>no-carrier</term> + <listitem> + <para>the device is powered up, but it does not yet have a carrier</para> + </listitem> + </varlistentry> + <varlistentry> + <term>dormant</term> + <listitem> + <para>the device has a carrier, but is not yet ready for normal traffic</para> + </listitem> + </varlistentry> + <varlistentry> + <term>carrier</term> + <listitem> + <para>the link has a carrier</para> + </listitem> + </varlistentry> + <varlistentry> + <term>degraded</term> + <listitem> + <para>the link has carrier and addresses valid on the local link configured</para> + </listitem> + </varlistentry> + <varlistentry> + <term>routable</term> + <listitem> + <para>the link has carrier and routable address configured</para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para>The setup status is one of the following: + <variablelist> + <varlistentry> + <term>pending</term> + <listitem> + <para>udev is still processing the link, we don't yet know if we will manage it</para> + </listitem> + </varlistentry> + <varlistentry> + <term>failed</term> + <listitem> + <para>networkd failed to manage the link</para> + </listitem> + </varlistentry> + <varlistentry> + <term>configuring</term> + <listitem> + <para>in the process of retrieving configuration or configuring the link</para> + </listitem> + </varlistentry> + <varlistentry> + <term>configured</term> + <listitem> + <para>link configured successfully</para> + </listitem> + </varlistentry> + <varlistentry> + <term>unmanaged</term> + <listitem> + <para>networkd is not handling the link</para> + </listitem> + </varlistentry> + <varlistentry> + <term>linger</term> + <listitem> + <para>the link is gone, but has not yet been dropped by networkd</para> + </listitem> + </varlistentry> + </variablelist> + </para> </listitem> </varlistentry> diff --git a/man/networkd.conf.xml b/man/networkd.conf.xml index b34ce1d3e0..c624d4de43 100644 --- a/man/networkd.conf.xml +++ b/man/networkd.conf.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -67,7 +67,7 @@ <para>The following values are understood: <variablelist> <varlistentry> - <term><option>vendor</option> </term> + <term><option>vendor</option></term> <listitem><para>If <literal>DUIDType=vendor</literal>, then the DUID value will be generated using <literal>43793</literal> as the vendor identifier (systemd) and hashed contents of <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>. @@ -76,11 +76,23 @@ </varlistentry> <varlistentry> - <term><option>link-layer-time</option> </term> - <term><option>link-layer</option> </term> - <term><option>uuid</option> </term> - <listitem><para>Those values are parsed and can be used to set the DUID type - field, but DUID contents must be provided using <varname>DUIDRawData=</varname>. + <term><option>uuid</option></term> + <listitem><para>If <literal>DUIDType=uuid</literal>, and <varname>DUIDRawData=</varname> is not set, + then the product UUID is used as a DUID value. If a system does not have valid product UUID, then + an application-specific + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> + is used as a DUID value. About the application-specific machine ID, see + <citerefentry><refentrytitle>sd_id128_get_machine_app_specific</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>link-layer-time[:<replaceable>TIME</replaceable>]</option></term> + <term><option>link-layer</option></term> + <listitem><para>If <literal>link-layer-time</literal> or <literal>link-layer</literal> is specified, + then the MAC address of the interface is used as a DUID value. The value <literal>link-layer-time</literal> + can take additional time value after a colon, e.g. <literal>link-layer-time:2018-01-23 12:34:56 UTC</literal>. + The default time value is <literal>2000-01-01 00:00:00 UTC</literal>. </para></listitem> </varlistentry> </variablelist> @@ -96,8 +108,9 @@ byte separated by <literal>:</literal>. The DUID that is sent is composed of the DUID type specified by <varname>DUIDType=</varname> and the value configured here.</para> - <para>The DUID value specified here overrides the DUID that systemd-networkd generates using the machine-id - from the <filename>/etc/machine-id</filename> file. To configure DUID per-network, see + <para>The DUID value specified here overrides the DUID that + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + generates from the machine ID. To configure DUID per-network, see <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The configured DHCP DUID should conform to the specification in <ulink url="http://tools.ietf.org/html/rfc3315#section-9">RFC 3315</ulink>, @@ -125,7 +138,9 @@ DUIDRawData=00:00:ab:11:f9:2a:c2:77:29:f9:5c:00</programlisting> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>1</manvolnum></citerefentry> + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_id128_get_machine_app_specific</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/nss-myhostname.xml b/man/nss-myhostname.xml index e1aabacad2..e447420f53 100644 --- a/man/nss-myhostname.xml +++ b/man/nss-myhostname.xml @@ -6,7 +6,7 @@ SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="nss-myhostname" conditional='ENABLE_MYHOSTNAME'> +<refentry id="nss-myhostname" conditional='ENABLE_NSS_MYHOSTNAME'> <refentryinfo> <title>nss-myhostname</title> @@ -81,6 +81,7 @@ <para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables <command>nss-myhostname</command> correctly:</para> + <!-- synchronize with other nss-* man pages and factory/etc/nsswitch.conf --> <programlisting>passwd: compat mymachines systemd group: compat mymachines systemd shadow: compat diff --git a/man/nss-mymachines.xml b/man/nss-mymachines.xml index 394a905665..5742d89779 100644 --- a/man/nss-mymachines.xml +++ b/man/nss-mymachines.xml @@ -6,7 +6,7 @@ SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="nss-mymachines" conditional='ENABLE_MACHINED'> +<refentry id="nss-mymachines" conditional='ENABLE_NSS_MYMACHINES'> <refentryinfo> <title>nss-mymachines</title> @@ -35,12 +35,21 @@ <para><command>nss-mymachines</command> is a plug-in module for the GNU Name Service Switch (NSS) functionality of the GNU C Library (<command>glibc</command>), providing hostname resolution for the names of containers running locally that are registered with - <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. The + <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. The container names are resolved to the IP addresses of the specific container, ordered by their scope. This - functionality only applies to containers using network namespacing.</para> - - <para>The module also resolves user and group IDs used by containers to user and group names indicating the - container name, and back. This functionality only applies to containers using user namespacing.</para> + functionality only applies to containers using network namespacing (see the description of + <option>--private-network</option> in + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>). + Note that the name that is resolved is the one registered with <command>systemd-machined</command>, which + may be different than the hostname configured inside of the container.</para> + + <para>The module also provides name resolution for user and group identifiers mapped to containers. All names from + the range allocated to a given container <replaceable>container</replaceable> are exposed on the host as + <literal>vu-<replaceable>container</replaceable>-<replaceable>uid</replaceable></literal> and + <literal>vg-<replaceable>container</replaceable>-<replaceable>gid</replaceable></literal> (see example below). This + functionality only applies to containers using user namespacing (see the description of + <option>--private-users</option> in + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para> <para>To activate the NSS module, add <literal>mymachines</literal> to the lines starting with <literal>hosts:</literal>, <literal>passwd:</literal> and <literal>group:</literal> in @@ -53,11 +62,12 @@ </refsect1> <refsect1> - <title>Example</title> + <title>Configuration in <filename>/etc/nsswitch.conf</filename></title> <para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables <command>nss-mymachines</command> correctly:</para> + <!-- synchronize with other nss-* man pages and factory/etc/nsswitch.conf --> <programlisting>passwd: compat <command>mymachines</command> systemd group: compat <command>mymachines</command> systemd shadow: compat @@ -75,10 +85,73 @@ netgroup: nis</programlisting> </refsect1> <refsect1> + <title>Mappings provided by <filename>nss-mymachines</filename></title> + + <para>The container <literal>rawhide</literal> is spawned using + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>: + </para> + + <programlisting># systemd-nspawn -M rawhide --boot --network-veth --private-users=pick +Spawning container rawhide on /var/lib/machines/rawhide. +Selected user namespace base 20119552 and range 65536. +... + +$ machinectl --max-addresses=3 +MACHINE CLASS SERVICE OS VERSION ADDRESSES +rawhide container systemd-nspawn fedora 30 169.254.40.164 fe80::94aa:3aff:fe7b:d4b9 + +$ getent passwd vu-rawhide-0 vu-rawhide-81 +vu-rawhide-0:*:20119552:65534:vu-rawhide-0:/:/sbin/nologin +vu-rawhide-81:*:20119633:65534:vu-rawhide-81:/:/sbin/nologin + +$ getent group vg-rawhide-0 vg-rawhide-81 +vg-rawhide-0:*:20119552: +vg-rawhide-81:*:20119633: + +$ ps -o user:15,pid,tty,command -e|grep '^vu-rawhide' +vu-rawhide-0 692 ? /usr/lib/systemd/systemd +vu-rawhide-0 731 ? /usr/lib/systemd/systemd-journald +vu-rawhide-192 734 ? /usr/lib/systemd/systemd-networkd +vu-rawhide-193 738 ? /usr/lib/systemd/systemd-resolved +vu-rawhide-0 742 ? /usr/lib/systemd/systemd-logind +vu-rawhide-81 744 ? /usr/bin/dbus-daemon --system --address=systemd: --nofork --nopidfile --systemd-activation --syslog-only +vu-rawhide-0 746 ? /usr/sbin/sshd -D ... +vu-rawhide-0 752 ? /usr/lib/systemd/systemd --user +vu-rawhide-0 753 ? (sd-pam) +vu-rawhide-0 1628 ? login -- zbyszek +vu-rawhide-1000 1630 ? /usr/lib/systemd/systemd --user +vu-rawhide-1000 1631 ? (sd-pam) +vu-rawhide-1000 1637 pts/8 -zsh + +$ ping -c1 rawhide +PING rawhide(fe80::94aa:3aff:fe7b:d4b9%ve-rawhide (fe80::94aa:3aff:fe7b:d4b9%ve-rawhide)) 56 data bytes +64 bytes from fe80::94aa:3aff:fe7b:d4b9%ve-rawhide (fe80::94aa:3aff:fe7b:d4b9%ve-rawhide): icmp_seq=1 ttl=64 time=0.045 ms +... +$ ping -c1 -4 rawhide +PING rawhide (169.254.40.164) 56(84) bytes of data. +64 bytes from 169.254.40.164 (169.254.40.164): icmp_seq=1 ttl=64 time=0.064 ms +... + +# machinectl shell rawhide /sbin/ip a +Connected to machine rawhide. Press ^] three times within 1s to exit session. +1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000 + ... +2: host0@if21: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 + link/ether 96:aa:3a:7b:d4:b9 brd ff:ff:ff:ff:ff:ff link-netnsid 0 + inet 169.254.40.164/16 brd 169.254.255.255 scope link host0 + valid_lft forever preferred_lft forever + inet6 fe80::94aa:3aff:fe7b:d4b9/64 scope link + valid_lft forever preferred_lft forever +Connection to machine rawhide terminated. +</programlisting> + </refsect1> + + <refsect1> <title>See Also</title> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>nss-systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>8</manvolnum></citerefentry>, diff --git a/man/nss-resolve.xml b/man/nss-resolve.xml index 588bc04976..960d580003 100644 --- a/man/nss-resolve.xml +++ b/man/nss-resolve.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -6,7 +6,7 @@ SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="nss-resolve" conditional='ENABLE_RESOLVE'> +<refentry id="nss-resolve" conditional='ENABLE_NSS_RESOLVE'> <refentryinfo> <title>nss-resolve</title> @@ -64,6 +64,7 @@ <para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables <command>nss-resolve</command> correctly:</para> + <!-- synchronize with other nss-* man pages and factory/etc/nsswitch.conf --> <programlisting>passwd: compat mymachines systemd group: compat mymachines systemd shadow: compat diff --git a/man/nss-systemd.xml b/man/nss-systemd.xml index 323f9ab868..d3d68437de 100644 --- a/man/nss-systemd.xml +++ b/man/nss-systemd.xml @@ -55,6 +55,7 @@ <para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables <command>nss-systemd</command> correctly:</para> + <!-- synchronize with other nss-* man pages and factory/etc/nsswitch.conf --> <programlisting>passwd: compat mymachines <command>systemd</command> group: compat mymachines <command>systemd</command> shadow: compat diff --git a/man/os-release.xml b/man/os-release.xml index a51edf3b8a..ea71b36c1e 100644 --- a/man/os-release.xml +++ b/man/os-release.xml @@ -218,14 +218,18 @@ <varlistentry> <term><varname>HOME_URL=</varname></term> + <term><varname>DOCUMENTATION_URL=</varname></term> <term><varname>SUPPORT_URL=</varname></term> <term><varname>BUG_REPORT_URL=</varname></term> <term><varname>PRIVACY_POLICY_URL=</varname></term> - <listitem><para>Links to resources on the Internet related the - operating system. <varname>HOME_URL=</varname> should refer to - the homepage of the operating system, or alternatively some - homepage of the specific version of the operating system. + <listitem><para>Links to resources on the Internet related to + the operating system. + <varname>HOME_URL=</varname> should refer to the homepage of + the operating system, or alternatively some homepage of the + specific version of the operating system. + <varname>DOCUMENTATION_URL=</varname> should refer to the main + documentation page for this operating system. <varname>SUPPORT_URL=</varname> should refer to the main support page for the operating system, if there is any. This is primarily intended for operating systems which vendors @@ -234,7 +238,7 @@ if there is any. This is primarily intended for operating systems that rely on community QA. <varname>PRIVACY_POLICY_URL=</varname> should refer to the - main privacy policy page for the operation system, if there is + main privacy policy page for the operating system, if there is any. These settings are optional, and providing only some of these settings is common. These URLs are intended to be exposed in "About this system" UIs behind links with captions @@ -302,6 +306,22 @@ </para></listitem> </varlistentry> + <varlistentry> + <term><varname>LOGO=</varname></term> + + <listitem><para> + A string, specifying the name of an icon as defined by <ulink + url="http://standards.freedesktop.org/icon-theme-spec/latest"> + freedesktop.org Icon Theme Specification</ulink>. This can be + used by graphical applications to display an operating + system's or distributor's logo. This field is optional and + may not necessarily be implemented on all systems. + Examples: + <literal>LOGO=fedora-logo</literal>, + <literal>LOGO=distributor-logo-opensuse</literal> + </para></listitem> + </varlistentry> + </variablelist> <para>If you are reading this file from C code or a shell script diff --git a/man/pam_systemd.xml b/man/pam_systemd.xml index 5eab995a52..3ce3b282bd 100644 --- a/man/pam_systemd.xml +++ b/man/pam_systemd.xml @@ -84,40 +84,43 @@ <varlistentry> <term><option>class=</option></term> - <listitem><para>Takes a string argument which sets the session - class. The XDG_SESSION_CLASS environmental variable takes - precedence. One of - <literal>user</literal>, - <literal>greeter</literal>, - <literal>lock-screen</literal> or - <literal>background</literal>. See - <citerefentry><refentrytitle>sd_session_get_class</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for details about the session class.</para></listitem> + <listitem><para>Takes a string argument which sets the session class. The <varname>XDG_SESSION_CLASS</varname> + environment variable (see below) takes precedence. One of <literal>user</literal>, <literal>greeter</literal>, + <literal>lock-screen</literal> or <literal>background</literal>. See + <citerefentry><refentrytitle>sd_session_get_class</refentrytitle><manvolnum>3</manvolnum></citerefentry> for + details about the session class.</para></listitem> </varlistentry> <varlistentry> <term><option>type=</option></term> - <listitem><para>Takes a string argument which sets the session - type. The XDG_SESSION_TYPE environmental variable takes - precedence. One of - <literal>unspecified</literal>, - <literal>tty</literal>, - <literal>x11</literal>, - <literal>wayland</literal> or - <literal>mir</literal>. See - <citerefentry><refentrytitle>sd_session_get_type</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for details about the session type.</para></listitem> + <listitem><para>Takes a string argument which sets the session type. The <varname>XDG_SESSION_TYPE</varname> + environment variable (see below) takes precedence. One of <literal>unspecified</literal>, + <literal>tty</literal>, <literal>x11</literal>, <literal>wayland</literal> or <literal>mir</literal>. See + <citerefentry><refentrytitle>sd_session_get_type</refentrytitle><manvolnum>3</manvolnum></citerefentry> for + details about the session type.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>desktop=</option></term> + + <listitem><para>Takes a single, short identifier string for the desktop environment. The + <varname>XDG_SESSION_DESKTOP</varname> environment variable (see below) takes precedence. This may be used to + indicate the session desktop used, where this applies and if this information is available. For example: + <literal>GNOME</literal>, or <literal>KDE</literal>. It is recommended to use the same identifiers and + capitalization as for <varname>$XDG_CURRENT_DESKTOP</varname>, as defined by the <ulink + url="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop Entry + Specification</ulink>. (However, note that the option only takes a single item, and not a colon-separated list + like <varname>$XDG_CURRENT_DESKTOP</varname>.) See + <citerefentry><refentrytitle>sd_session_get_desktop</refentrytitle><manvolnum>3</manvolnum></citerefentry> for + further details.</para></listitem> </varlistentry> <varlistentry> <term><option>debug<optional>=</optional></option></term> - <listitem><para>Takes an optional - boolean argument. If yes or without - the argument, the module will log - debugging information as it - operates.</para></listitem> + <listitem><para>Takes an optional boolean argument. If yes or without the argument, the module will log + debugging information as it operates.</para></listitem> </varlistentry> </variablelist> </refsect1> @@ -131,20 +134,20 @@ <refsect1> <title>Environment</title> - <para>The following environment variables are set for the - processes of the user's session:</para> + <para>The following environment variables are initialized by the module and available to the processes of the + user's session:</para> <variablelist class='environment-variables'> <varlistentry> <term><varname>$XDG_SESSION_ID</varname></term> - <listitem><para>A session identifier, suitable to be used in - filenames. The string itself should be considered opaque, - although often it is just the audit session ID as reported by - <filename>/proc/self/sessionid</filename>. Each ID will be - assigned only once during machine uptime. It may hence be used - to uniquely label files or other resources of this - session.</para></listitem> + <listitem><para>A short session identifier, suitable to be used in filenames. The string itself should be + considered opaque, although often it is just the audit session ID as reported by + <filename>/proc/self/sessionid</filename>. Each ID will be assigned only once during machine uptime. It may + hence be used to uniquely label files or other resources of this session. Combine this ID with the boot + identifier, as returned by + <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>, for a + globally unique identifier for the current session.</para></listitem> </varlistentry> <varlistentry> @@ -174,45 +177,31 @@ </variablelist> - <para>The following environment variables are read by the module - and may be used by the PAM service to pass metadata to the - module:</para> + <para>The following environment variables are read by the module and may be used by the PAM service to pass + metadata to the module. If these variables are not set when the PAM module is invoked but can be determined + otherwise they are set by the module, so that these variables are initialized for the session and applications if + known at all.</para> <variablelist class='environment-variables'> <varlistentry> <term><varname>$XDG_SESSION_TYPE</varname></term> - <listitem><para>The session type. This may be used instead of - <option>session=</option> on the module parameter line, and is - usually preferred.</para></listitem> + <listitem><para>The session type. This may be used instead of <option>session=</option> on the module parameter + line, and is usually preferred.</para></listitem> </varlistentry> <varlistentry> <term><varname>$XDG_SESSION_CLASS</varname></term> - <listitem><para>The session class. This may be used instead of - <option>class=</option> on the module parameter line, and is - usually preferred.</para></listitem> + <listitem><para>The session class. This may be used instead of <option>class=</option> on the module parameter + line, and is usually preferred.</para></listitem> </varlistentry> <varlistentry> <term><varname>$XDG_SESSION_DESKTOP</varname></term> - <listitem><para>A single, short identifier string for the - desktop environment. This may be used to indicate the session - desktop used, where this applies and if this information is - available. For example: <literal>GNOME</literal>, or - <literal>KDE</literal>. It is recommended to use the same - identifiers and capitalization as for - <varname>$XDG_CURRENT_DESKTOP</varname>, as defined by the - <ulink - url="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop - Entry Specification</ulink>. (However, note that - <varname>$XDG_SESSION_DESKTOP</varname> only takes a single - item, and not a colon-separated list like - <varname>$XDG_CURRENT_DESKTOP</varname>.) See - <citerefentry><refentrytitle>sd_session_get_desktop</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for more details.</para></listitem> + <listitem><para>The desktop identifier. This may be used instead of <option>desktop=</option> on the module + parameter line, and is usually preferred.</para></listitem> </varlistentry> <varlistentry> @@ -231,9 +220,9 @@ </varlistentry> </variablelist> - <para>If not set, <command>pam_systemd</command> will determine the - values for <varname>$XDG_SEAT</varname> and <varname>$XDG_VTNR</varname> - based on the <varname>$DISPLAY</varname> variable.</para> + <para>If not set, <command>pam_systemd</command> will initialize + <varname>$XDG_SEAT</varname> and <varname>$XDG_VTNR</varname> + based on the <varname>$DISPLAY</varname> variable (if the latter is set).</para> </refsect1> <refsect1> diff --git a/man/portablectl.xml b/man/portablectl.xml index 0926991cbe..3a5517a4ad 100644 --- a/man/portablectl.xml +++ b/man/portablectl.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -59,7 +59,7 @@ <listitem><para>btrfs subvolumes containing OS trees, similar to normal directory trees.</para></listitem> <listitem><para>Binary "raw" disk images containing MBR or GPT partition tables and Linux file system - partitions.</para></listitem> + partitions. (These must be regular files, with the <filename>.raw</filename> suffix.)</para></listitem> </itemizedlist> </refsect1> @@ -101,9 +101,9 @@ <term><option>--runtime</option></term> <listitem><para>When specified the unit and drop-in files are placed in - <filename>/run/systemd/system/</filename> instead of <filename>/etc/systemd/system/</filename>. Images attached - with this option set hence remain attached only until the next reboot, while they are normally attached - persistently.</para></listitem> + <filename>/run/systemd/system.attached/</filename> instead of + <filename>/etc/systemd/system.attached/</filename>. Images attached with this option set hence remain attached + only until the next reboot, while they are normally attached persistently.</para></listitem> </varlistentry> <varlistentry> @@ -167,8 +167,10 @@ <listitem><para>All unit files of types <filename>.service</filename>, <filename>.socket</filename>, <filename>.target</filename>, <filename>.timer</filename> and <filename>.path</filename> which match the indicated unit file name prefix are copied from the image to the host's - <filename>/etc/systemd/system/</filename> directory (or <filename>/run/systemd/system/</filename> — depending - whether <option>--runtime</option> is specified, see above).</para></listitem> + <filename>/etc/systemd/system.attached/</filename> directory (or + <filename>/run/systemd/system.attached/</filename> — depending whether <option>--runtime</option> is + specified, see above), which is included in the built-in unit search path of the system service + manager.</para></listitem> <listitem><para>For unit files of type <filename>.service</filename> a drop-in is added to these copies that adds <varname>RootDirectory=</varname> or <varname>RootImage=</varname> settings (see @@ -330,6 +332,10 @@ to place image files directly in <filename>/etc/portables/</filename> or <filename>/run/systemd/portables/</filename> (as these are generally not suitable for storing large or non-textual data), but use these directories only for linking images located elsewhere into the image search path.</para> + + <para>When a portable service image is attached, matching unit files are copied onto the host into the + <filename>/etc/systemd/system.attached/</filename> and <filename>/run/systemd/system.attached/</filename> + directories. When an image is detached, the unit files are removed again from these directories.</para> </refsect1> <refsect1> diff --git a/man/print-unit-path.c b/man/print-unit-path.c new file mode 100644 index 0000000000..23b58a26e2 --- /dev/null +++ b/man/print-unit-path.c @@ -0,0 +1,64 @@ +#include <stdio.h> +#include <string.h> +#include <unistd.h> +#include <sys/types.h> + +#include <systemd/sd-bus.h> +#define _cleanup_(f) __attribute__((cleanup(f))) + +/* This is equivalent to: + * busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 \ + * org.freedesktop.systemd1.Manager GetUnitByPID $$ + * + * Compile with 'cc -lsystemd print-unit-path.c' + */ + +#define DESTINATION "org.freedesktop.systemd1" +#define PATH "/org/freedesktop/systemd1" +#define INTERFACE "org.freedesktop.systemd1.Manager" +#define MEMBER "GetUnitByPID" + +static int log_error(int error, const char *message) { + fprintf(stderr, "%s: %s\n", message, strerror(-error)); + return error; +} + +static int print_unit_path(sd_bus *bus) { + _cleanup_(sd_bus_message_unrefp) sd_bus_message *m = NULL; + _cleanup_(sd_bus_error_free) sd_bus_error error = SD_BUS_ERROR_NULL; + _cleanup_(sd_bus_message_unrefp) sd_bus_message *reply = NULL; + int r; + + r = sd_bus_message_new_method_call(bus, &m, + DESTINATION, PATH, INTERFACE, MEMBER); + if (r < 0) + return log_error(r, "Failed to create bus message"); + + r = sd_bus_message_append(m, "u", (unsigned) getpid()); + if (r < 0) + return log_error(r, "Failed to append to bus message"); + + r = sd_bus_call(bus, m, -1, &error, &reply); + if (r < 0) + return log_error(r, "Call failed"); + + const char *ans; + r = sd_bus_message_read(reply, "o", &ans); + if (r < 0) + return log_error(r, "Failed to read reply"); + + printf("Unit path is \"%s\".\n", ans); + + return 0; +} + +int main(int argc, char **argv) { + _cleanup_(sd_bus_flush_close_unrefp) sd_bus *bus = NULL; + int r; + + r = sd_bus_open_system(&bus); + if (r < 0) + return log_error(r, "Failed to acquire bus"); + + print_unit_path(bus); +} diff --git a/man/resolvectl.xml b/man/resolvectl.xml index ff5b8ad101..defd592aa9 100644 --- a/man/resolvectl.xml +++ b/man/resolvectl.xml @@ -241,26 +241,35 @@ <varlistentry> <term><option>dns [<replaceable>LINK</replaceable> [<replaceable>SERVER</replaceable>…]]</option></term> <term><option>domain [<replaceable>LINK</replaceable> [<replaceable>DOMAIN</replaceable>…]]</option></term> + <term><option>default-route [<replaceable>LINK</replaceable> [<replaceable>BOOL</replaceable>…]]</option></term> <term><option>llmnr [<replaceable>LINK</replaceable> [<replaceable>MODE</replaceable>]]</option></term> <term><option>mdns [<replaceable>LINK</replaceable> [<replaceable>MODE</replaceable>]]</option></term> <term><option>dnssec [<replaceable>LINK</replaceable> [<replaceable>MODE</replaceable>]]</option></term> <term><option>dnsovertls [<replaceable>LINK</replaceable> [<replaceable>MODE</replaceable>]]</option></term> <term><option>nta [<replaceable>LINK</replaceable> [<replaceable>DOMAIN</replaceable>…]]</option></term> - <listitem><para>Get/set per-interface DNS configuration. These commands may be used to configure various DNS - settings for network interfaces that aren't managed by - <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. (These - commands will fail when used on interfaces that are managed by <command>systemd-networkd</command>, please - configure their DNS settings directly inside the <filename>.network</filename> files instead.) These commands - may be used to inform <command>systemd-resolved</command> about per-interface DNS configuration determined - through external means. The <option>dns</option> command expects IPv4 or IPv6 address specifications of DNS - servers to use. The <option>domain</option> command expects valid DNS domains, possibly prefixed with - <literal>~</literal>, and configures a per-interface search or route-only domain. The <option>llmnr</option>, - <option>mdns</option>, <option>dnssec</option> and <option>dnsovertls</option> commands may be used to configure - the per-interface LLMNR, MulticastDNS, DNSSEC and DNSOverTLS settings. Finally, <option>nta</option> command - may be used to configure additional per-interface DNSSEC NTA domains. For details about these settings, their - possible values and their effect, see the corresponding options in - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + <listitem> + <para>Get/set per-interface DNS configuration. These commands may be used to configure various DNS settings + for network interfaces that aren't managed by + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. (These + commands will fail when used on interfaces that are managed by <command>systemd-networkd</command>, please + configure their DNS settings directly inside the <filename>.network</filename> files instead.) These commands + may be used to inform <command>systemd-resolved</command> about per-interface DNS configuration determined + through external means. The <option>dns</option> command expects IPv4 or IPv6 address specifications of DNS + servers to use. The <option>domain</option> command expects valid DNS domains, possibly prefixed with + <literal>~</literal>, and configures a per-interface search or route-only domain. The + <option>default-route</option> command expects a boolean paremeter, and configures whether the link may be + used as default route for DNS lookups, i.e. if it is suitable for lookups on domains no other link explicitly + is configured for. The <option>llmnr</option>, <option>mdns</option>, <option>dnssec</option> and + <option>dnsovertls</option> commands may be used to configure the per-interface LLMNR, MulticastDNS, DNSSEC + and DNSOverTLS settings. Finally, <option>nta</option> command may be used to configure additional + per-interface DNSSEC NTA domains.</para> + + <para>Options <option>dns</option>, <option>domain</option> and <option>nta</option> can take + a single empty string argument to clear their respective value lists.</para> + + <para>For details about these settings, their possible values and their effect, see the corresponding options in + <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> </listitem> </varlistentry> @@ -269,9 +278,10 @@ <listitem><para>Revert the per-interface DNS configuration. If the DNS configuration is reverted all per-interface DNS setting are reset to their defaults, undoing all effects of <option>dns</option>, - <option>domain</option>, <option>llmnr</option>, <option>mdns</option>, <option>dnssec</option>, - <option>dnsovertls</option>, <option>nta</option>. Note that when a network interface disappears all - configuration is lost automatically, an explicit reverting is not necessary in that case.</para></listitem> + <option>domain</option>, <option>default-route</option>, <option>llmnr</option>, <option>mdns</option>, + <option>dnssec</option>, <option>dnsovertls</option>, <option>nta</option>. Note that when a network interface + disappears all configuration is lost automatically, an explicit reverting is not necessary in that + case.</para></listitem> </varlistentry> </variablelist> diff --git a/man/resolved.conf.xml b/man/resolved.conf.xml index c36c303abc..d37bf0d3ad 100644 --- a/man/resolved.conf.xml +++ b/man/resolved.conf.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -91,7 +91,7 @@ <listitem><para>Takes a boolean argument or <literal>resolve</literal>. Controls Link-Local Multicast Name Resolution support (<ulink - url="https://tools.ietf.org/html/rfc4795">RFC 4794</ulink>) on + url="https://tools.ietf.org/html/rfc4795">RFC 4795</ulink>) on the local host. If true, enables full LLMNR responder and resolver support. If false, disables both. If set to <literal>resolve</literal>, only resolution support is enabled, @@ -189,7 +189,7 @@ domains (TLDs) that are not known by the DNS root server. This logic does not work in all private zone setups.</para> - <para>Defaults to off.</para> + <para>Defaults to <literal>allow-downgrade</literal></para> </listitem> </varlistentry> @@ -227,10 +227,10 @@ <varlistentry> <term><varname>Cache=</varname></term> - <listitem><para>Takes a boolean argument. If "yes" (the default), resolving a domain name which already got - queried earlier will return the previous result as long as it is still valid, and thus does not result in a new - network request. Be aware that turning off caching comes at a performance penalty, which is particularly - high when DNSSEC is used.</para> + <listitem><para>Takes a boolean argument. If <literal>yes</literal> (the default), resolving a domain name + which already got queried earlier will return the previous result as long as it is still valid, and thus does + not result in a new network request. Be aware that turning off caching comes at a performance penalty, which + is particularly high when DNSSEC is used.</para> <para>Note that caching is turned off implicitly if the configured DNS server is on a host-local IP address (such as 127.0.0.1 or ::1), in order to avoid duplicate local caching.</para></listitem> @@ -239,15 +239,22 @@ <varlistentry> <term><varname>DNSStubListener=</varname></term> <listitem><para>Takes a boolean argument or one of <literal>udp</literal> and <literal>tcp</literal>. If - <literal>udp</literal> (the default), a DNS stub resolver will listen for UDP requests on address 127.0.0.53 + <literal>udp</literal>, a DNS stub resolver will listen for UDP requests on address 127.0.0.53 port 53. If <literal>tcp</literal>, the stub will listen for TCP requests on the same address and port. If - <literal>yes</literal>, the stub listens for both UDP and TCP requests. If <literal>no</literal>, the stub + <literal>yes</literal> (the default), the stub listens for both UDP and TCP requests. If <literal>no</literal>, the stub listener is disabled.</para> <para>Note that the DNS stub listener is turned off implicitly when its listening address and port are already in use.</para></listitem> </varlistentry> + <varlistentry> + <term><varname>ReadEtcHosts=</varname></term> + <listitem><para>Takes a boolean argument. If <literal>yes</literal> (the default), the DNS stub resolver will read + <filename>/etc/hosts</filename>, and try to resolve hosts or address by using the entries in the file before + sending query to DNS servers.</para></listitem> + </varlistentry> + </variablelist> </refsect1> diff --git a/man/rules/meson.build b/man/rules/meson.build index 9458a4012d..0c990a0c5d 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -37,9 +37,9 @@ manpages = [ ['modules-load.d', '5', [], 'HAVE_KMOD'], ['networkctl', '1', [], 'ENABLE_NETWORKD'], ['networkd.conf', '5', ['networkd.conf.d'], 'ENABLE_NETWORKD'], - ['nss-myhostname', '8', ['libnss_myhostname.so.2'], 'ENABLE_MYHOSTNAME'], - ['nss-mymachines', '8', ['libnss_mymachines.so.2'], 'ENABLE_MACHINED'], - ['nss-resolve', '8', ['libnss_resolve.so.2'], 'ENABLE_RESOLVE'], + ['nss-myhostname', '8', ['libnss_myhostname.so.2'], 'ENABLE_NSS_MYHOSTNAME'], + ['nss-mymachines', '8', ['libnss_mymachines.so.2'], 'ENABLE_NSS_MYMACHINES'], + ['nss-resolve', '8', ['libnss_resolve.so.2'], 'ENABLE_NSS_RESOLVE'], ['nss-systemd', '8', ['libnss_systemd.so.2'], 'ENABLE_NSS_SYSTEMD'], ['os-release', '5', [], ''], ['pam_systemd', '8', [], 'HAVE_PAM'], @@ -114,6 +114,8 @@ manpages = [ 'sd_bus_match_signal', 'sd_bus_match_signal_async'], ''], + ['sd_bus_attach_event', '3', ['sd_bus_detach_event', 'sd_bus_get_event'], ''], + ['sd_bus_close', '3', ['sd_bus_flush'], ''], ['sd_bus_creds_get_pid', '3', ['sd_bus_creds_get_audit_login_uid', @@ -166,7 +168,10 @@ manpages = [ 'sd_bus_open_system', 'sd_bus_open_system_machine', 'sd_bus_open_system_remote', - 'sd_bus_open_user'], + 'sd_bus_open_system_with_description', + 'sd_bus_open_user', + 'sd_bus_open_user_with_description', + 'sd_bus_open_with_description'], ''], ['sd_bus_error', '3', @@ -177,6 +182,7 @@ manpages = [ 'sd_bus_error_get_errno', 'sd_bus_error_has_name', 'sd_bus_error_is_set', + 'sd_bus_error_move', 'sd_bus_error_set', 'sd_bus_error_set_const', 'sd_bus_error_set_errno', @@ -188,7 +194,7 @@ manpages = [ '3', ['SD_BUS_ERROR_END', 'SD_BUS_ERROR_MAP', 'sd_bus_error_map'], ''], - ['sd_bus_get_fd', '3', [], ''], + ['sd_bus_get_fd', '3', ['sd_bus_get_events', 'sd_bus_get_timeout'], ''], ['sd_bus_get_n_queued_read', '3', ['sd_bus_get_n_queued_write'], ''], ['sd_bus_is_open', '3', ['sd_bus_is_ready'], ''], ['sd_bus_message_append', '3', ['sd_bus_message_appendv'], ''], @@ -204,32 +210,111 @@ manpages = [ ['sd_bus_message_append_string_iovec', 'sd_bus_message_append_string_space'], ''], ['sd_bus_message_append_strv', '3', [], ''], + ['sd_bus_message_copy', '3', [], ''], ['sd_bus_message_get_cookie', '3', ['sd_bus_message_get_reply_cookie'], ''], ['sd_bus_message_get_monotonic_usec', '3', ['sd_bus_message_get_realtime_usec', 'sd_bus_message_get_seqnum'], ''], + ['sd_bus_message_get_signature', + '3', + ['sd_bus_message_has_signature', 'sd_bus_message_is_empty'], + ''], + ['sd_bus_message_get_type', + '3', + ['sd_bus_message_is_method_call', + 'sd_bus_message_is_method_error', + 'sd_bus_message_is_signal'], + ''], + ['sd_bus_message_new', + '3', + ['SD_BUS_MESSAGE_METHOD_CALL', + 'SD_BUS_MESSAGE_METHOD_ERROR', + 'SD_BUS_MESSAGE_METHOD_RETURN', + 'SD_BUS_MESSAGE_SIGNAL', + 'sd_bus_message_get_bus', + 'sd_bus_message_ref', + 'sd_bus_message_unref', + 'sd_bus_message_unrefp'], + ''], + ['sd_bus_message_new_method_call', + '3', + ['sd_bus_message_new_method_return'], + ''], + ['sd_bus_message_new_method_error', + '3', + ['sd_bus_message_new_method_errno', + 'sd_bus_message_new_method_errnof', + 'sd_bus_message_new_method_errorf'], + ''], + ['sd_bus_message_new_signal', '3', [], ''], + ['sd_bus_message_read', '3', ['sd_bus_message_readv'], ''], + ['sd_bus_message_read_array', '3', [], ''], ['sd_bus_message_read_basic', '3', [], ''], - ['sd_bus_message_set_destination', '3', ['sd_bus_message_set_sender'], ''], + ['sd_bus_message_rewind', '3', [], ''], + ['sd_bus_message_set_destination', + '3', + ['sd_bus_message_get_destination', + 'sd_bus_message_get_interface', + 'sd_bus_message_get_member', + 'sd_bus_message_get_path', + 'sd_bus_message_get_sender', + 'sd_bus_message_set_sender'], + ''], + ['sd_bus_message_set_expect_reply', + '3', + ['sd_bus_message_get_auto_start', + 'sd_bus_message_get_expect_reply', + 'sd_bus_message_set_auto_start'], + ''], + ['sd_bus_message_skip', '3', [], ''], + ['sd_bus_message_verify_type', '3', [], ''], ['sd_bus_negotiate_fds', '3', ['sd_bus_negotiate_creds', 'sd_bus_negotiate_timestamp'], ''], - ['sd_bus_new', '3', ['sd_bus_ref', 'sd_bus_unref', 'sd_bus_unrefp'], ''], + ['sd_bus_new', + '3', + ['sd_bus_flush_close_unref', + 'sd_bus_flush_close_unrefp', + 'sd_bus_ref', + 'sd_bus_unref', + 'sd_bus_unrefp'], + ''], ['sd_bus_path_encode', '3', ['sd_bus_path_decode', 'sd_bus_path_decode_many', 'sd_bus_path_encode_many'], ''], ['sd_bus_process', '3', [], ''], + ['sd_bus_reply_method_error', + '3', + ['sd_bus_reply_method_errno', + 'sd_bus_reply_method_errnof', + 'sd_bus_reply_method_errorf'], + ''], ['sd_bus_request_name', '3', ['sd_bus_release_name', 'sd_bus_release_name_async', 'sd_bus_request_name_async'], ''], + ['sd_bus_set_close_on_exit', '3', ['sd_bus_get_close_on_exit'], ''], ['sd_bus_set_connected_signal', '3', ['sd_bus_get_connected_signal'], ''], + ['sd_bus_set_description', + '3', + ['sd_bus_get_allow_interactive_authorization', + 'sd_bus_get_description', + 'sd_bus_set_allow_interactive_authorization', + 'sd_bus_set_anonymous', + 'sd_bus_set_trusted'], + ''], ['sd_bus_set_sender', '3', ['sd_bus_get_sender'], ''], ['sd_bus_set_watch_bind', '3', ['sd_bus_get_watch_bind'], ''], + ['sd_bus_slot_ref', + '3', + ['sd_bus_slot_get_bus', 'sd_bus_slot_unref', 'sd_bus_slot_unrefp'], + ''], + ['sd_bus_slot_set_description', '3', ['sd_bus_slot_get_description'], ''], ['sd_bus_slot_set_destroy_callback', '3', ['sd_bus_destroy_t', @@ -238,6 +323,7 @@ manpages = [ 'sd_bus_track_set_destroy_callback'], ''], ['sd_bus_slot_set_floating', '3', ['sd_bus_slot_get_floating'], ''], + ['sd_bus_slot_set_userdata', '3', ['sd_bus_slot_get_userdata'], ''], ['sd_bus_track_add_name', '3', ['sd_bus_track_add_sender', @@ -261,6 +347,7 @@ manpages = [ 'sd_bus_track_unref', 'sd_bus_track_unrefp'], ''], + ['sd_bus_wait', '3', [], ''], ['sd_event_add_child', '3', ['sd_event_child_handler_t', 'sd_event_source_get_child_pid'], @@ -363,6 +450,7 @@ manpages = [ ['sd_id128_get_machine', '3', ['sd_id128_get_boot', + 'sd_id128_get_boot_app_specific', 'sd_id128_get_invocation', 'sd_id128_get_machine_app_specific'], ''], @@ -540,6 +628,9 @@ manpages = [ ['systemd-ask-password', '1', [], ''], ['systemd-backlight@.service', '8', ['systemd-backlight'], 'ENABLE_BACKLIGHT'], ['systemd-binfmt.service', '8', ['systemd-binfmt'], 'ENABLE_BINFMT'], + ['systemd-bless-boot-generator', '8', [], 'ENABLE_EFI'], + ['systemd-bless-boot.service', '8', [], 'ENABLE_EFI'], + ['systemd-boot-check-no-failures.service', '8', [], ''], ['systemd-boot', '7', ['sd-boot'], 'ENABLE_EFI'], ['systemd-cat', '1', [], ''], ['systemd-cgls', '1', [], ''], @@ -583,6 +674,7 @@ manpages = [ 'ENABLE_HIBERNATE'], ['systemd-hostnamed.service', '8', ['systemd-hostnamed'], 'ENABLE_HOSTNAMED'], ['systemd-hwdb', '8', [], 'ENABLE_HWDB'], + ['systemd-id128', '1', [], ''], ['systemd-importd.service', '8', ['systemd-importd'], 'ENABLE_IMPORTD'], ['systemd-inhibit', '1', [], ''], ['systemd-initctl.service', @@ -646,6 +738,7 @@ manpages = [ '8', ['systemd-rfkill', 'systemd-rfkill.socket'], 'ENABLE_RFKILL'], + ['systemd-run-generator', '8', [], ''], ['systemd-run', '1', [], ''], ['systemd-sleep.conf', '5', ['sleep.conf.d'], ''], ['systemd-socket-activate', '1', [], ''], @@ -820,6 +913,7 @@ manpages = [ ''], ['udev_new', '3', ['udev_ref', 'udev_unref'], ''], ['udevadm', '8', [], ''], + ['user@.service', '5', ['user-runtime-dir@.service'], ''], ['vconsole.conf', '5', [], 'ENABLE_VCONSOLE'] ] # Really, do not edit. diff --git a/man/sd-bus-errors.xml b/man/sd-bus-errors.xml index c834bde292..c896511541 100644 --- a/man/sd-bus-errors.xml +++ b/man/sd-bus-errors.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -6,7 +6,8 @@ SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="sd-bus-errors"> +<refentry id="sd-bus-errors" + xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd-bus-errors</title> @@ -259,15 +260,7 @@ </variablelist> </refsect1> - <refsect1> - <title>Notes</title> - - <para>The various error definitions described here are available - as a shared library, which can be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry - project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> + <xi:include href="libsystemd-pkgconfig.xml" /> <refsect1> <title>See Also</title> diff --git a/man/sd-bus.xml b/man/sd-bus.xml index 1f3d037c10..4620590be4 100644 --- a/man/sd-bus.xml +++ b/man/sd-bus.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -43,34 +43,57 @@ </para> <para>See - <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_default</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_append_array</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_append_string_memfd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_append_strv</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_can_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_get_cookie</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_negotiate_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_path_encode</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_request_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_set_allow_interactive_authorization</refentrytitle><manvolnum>3</manvolnum></citerefentry> - <citerefentry><refentrytitle>sd_bus_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_track_add_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_track_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <literallayout><citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_attach_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_close</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_default</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_get_n_queued_read</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_message_append_array</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_message_append_string_memfd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_message_append_strv</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_message_copy</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_message_get_cookie</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_message_get_signature</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_message_get_type</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_message_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_message_new_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_message_new_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_message_read</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_message_read_array</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_message_read_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_message_rewind</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_message_set_destination</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_message_set_expect_reply</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_message_skip</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_message_verify_type</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_negotiate_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_path_encode</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_process</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_reply_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_request_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_set_connected_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_set_sender</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_set_watch_bind</refentrytitle><manvolnum>3</manvolnum></citerefentry> +<citerefentry><refentrytitle>sd_bus_set_close_on_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry> +<citerefentry><refentrytitle>sd_bus_slot_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_slot_set_destroy_callback</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_slot_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_slot_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_track_add_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_track_new</refentrytitle><manvolnum>3</manvolnum></citerefentry> +</literallayout> for more information about the functions available.</para> </refsect1> diff --git a/man/sd-event.xml b/man/sd-event.xml index 65bc3f8891..2e6ab69f82 100644 --- a/man/sd-event.xml +++ b/man/sd-event.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/sd-id128.xml b/man/sd-id128.xml index fbcf4bf367..4425c45d1e 100644 --- a/man/sd-id128.xml +++ b/man/sd-id128.xml @@ -141,8 +141,8 @@ int main(int argc, char **argv) { }</programlisting> <para>Note that new, randomized IDs may be generated with - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s - <option>--new-id128</option> option.</para> + <citerefentry><refentrytitle>systemd-id128</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s + <command>new</command> command.</para> </refsect1> <xi:include href="libsystemd-pkgconfig.xml" /> diff --git a/man/sd-journal.xml b/man/sd-journal.xml index 8bfcb90ca0..3fa6c75b7e 100644 --- a/man/sd-journal.xml +++ b/man/sd-journal.xml @@ -77,16 +77,15 @@ <refsect1> <title>Thread safety</title> - <para>Functions that operate on the <structname>sd_journal</structname> object are thread - agnostic — given <structname>sd_journal</structname> pointer may only be used from one thread at - a time, but multiple threads may use multiple such objects safely. Other functions — - those that are used to send entries to the journal, like - <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry> - and similar, or those that are used to retrieve global information like - <citerefentry><refentrytitle>sd_journal_stream_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry> - and + <para>Functions that operate on <structname>sd_journal</structname> objects are thread agnostic — given + <structname>sd_journal</structname> pointer may only be used from one specific thread at all times (and it has to + be the very same one during the entire lifetime of the object), but multiple, independent threads may use multiple, + independent objects safely. Other functions — those that are used to send entries to the journal, like + <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry> and similar, + or those that are used to retrieve global information like + <citerefentry><refentrytitle>sd_journal_stream_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry> and <citerefentry><refentrytitle>sd_journal_get_catalog_for_message_id</refentrytitle><manvolnum>3</manvolnum></citerefentry> - — are thread-safe and may be called from multiple threads in parallel.</para> + — are fully thread-safe and may be called from multiple threads in parallel.</para> </refsect1> <xi:include href="libsystemd-pkgconfig.xml" /> diff --git a/man/sd_bus_add_match.xml b/man/sd_bus_add_match.xml index 9137ef977c..c4f24aed3e 100644 --- a/man/sd_bus_add_match.xml +++ b/man/sd_bus_add_match.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -8,7 +8,7 @@ Copyright © 2016 Julian Orth --> -<refentry id="sd_bus_add_match"> +<refentry id="sd_bus_add_match" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_bus_add_match</title> @@ -154,9 +154,7 @@ <refsect1> <title>Notes</title> - <para><function>sd_bus_add_match()</function> and the other functions described here are available as a shared - library, which can be compiled and linked to with the <constant>libsystemd</constant> <citerefentry - project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para> + <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> </refsect1> <refsect1> diff --git a/man/sd_bus_attach_event.xml b/man/sd_bus_attach_event.xml new file mode 100644 index 0000000000..a2f7297f21 --- /dev/null +++ b/man/sd_bus_attach_event.xml @@ -0,0 +1,122 @@ +<?xml version='1.0'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + SPDX-License-Identifier: LGPL-2.1+ +--> + +<refentry id="sd_bus_attach_event" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_bus_attach_event</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_attach_event</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_attach_event</refname> + <refname>sd_bus_detach_event</refname> + <refname>sd_bus_get_event</refname> + + <refpurpose>Attach a bus connection object to an event loop</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_attach_event</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>sd_event *<parameter>e</parameter></paramdef> + <paramdef>int <parameter>priority</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_detach_event</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_event *<function>sd_bus_get_event</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_attach_event()</function> attaches the specified bus connection object to an + <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry> event loop object at + the specified priority (see + <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for details on event loop priorities). When a bus connection object is attached to an event loop incoming messages + will be automatically read and processed, and outgoing messages written, whenever the event loop is run. When the + event loop is about to terminate, the bus connection is automatically flushed and closed (see + <citerefentry><refentrytitle>sd_bus_set_close_on_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry> for + details on this). By default bus connection objects are not attached to any event loop. When a bus connection + object is attached to one it is not necessary to invoke + <citerefentry><refentrytitle>sd_bus_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry> or + <citerefentry><refentrytitle>sd_bus_process</refentrytitle><manvolnum>3</manvolnum></citerefentry> as this + functionality is handled automatically by the event loop.</para> + + <para><function>sd_bus_detach_event()</function> detaches a bus object from its event loop.</para> + + <para>The <function>sd_bus_get_event()</function> returns the event loop object the specified bus object is + currently attached to, or <constant>NULL</constant> if it is currently not attached to any.</para> + + <para>Note that <function>sd_bus_attach_event()</function> is only one of three supported ways to implement I/O + event handling for bus connections. Alternatively use + <citerefentry><refentrytitle>sd_bus_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry> for hooking up a + bus connection object with external or manual event loops. Or use + <citerefentry><refentrytitle>sd_bus_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry> as a simple + synchronous, blocking I/O waiting call.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>sd_bus_attach_event()</function> and <function>sd_bus_detach_event()</function> return + 0 or a positive integer. On failure, they return a negative errno-style error code.</para> + + <para><function>sd_bus_get_event()</function> returns an event loop object or <constant>NULL</constant>.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-ECHILD</constant></term> + + <listitem><para>The bus connection has been created in a different process.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_set_close_on_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_close.xml b/man/sd_bus_close.xml new file mode 100644 index 0000000000..369afd8747 --- /dev/null +++ b/man/sd_bus_close.xml @@ -0,0 +1,101 @@ +<?xml version='1.0'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + SPDX-License-Identifier: LGPL-2.1+ +--> + +<refentry id="sd_bus_close" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_bus_close</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_close</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_close</refname> + <refname>sd_bus_flush</refname> + + <refpurpose>Close and flush a bus connection</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>void <function>sd_bus_close</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_flush</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_close()</function> disconnects the specified bus connection. When this call is invoked and + the specified bus object refers to an active connection it is immediately terminated. No further messages may be + sent or receieved on it. Any messages queued in the bus object (both incoming and outgoing) are released. If + invoked on <constant>NULL</constant> bus object or when the bus connection is already closed this function executes + no operation. This call does not free or unreference the bus object itself. Use + <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> for that.</para> + + <para><function>sd_bus_flush()</function> synchronously writes out all outgoing queued message on a bus connection + if there are any. This function call may block if the peer is not processing bus messages quickly.</para> + + <para>Before a program exits it is usually a good idea to flush any pending messages with + <function>sd_bus_flush()</function> and then close connections with <function>sd_bus_close()</function> to ensure + that no unwritten messages are lost, no further messages may be queued and all incoming but unprocessed messages + are released. After both operations have been done, it is a good idea to also drop any remaining references to the + bus object so that it may be freed. Since these three operations are frequently done together a helper call + <citerefentry><refentrytitle>sd_bus_flush_close_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> is + provided that combines them into one.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>sd_bus_flush()</function> returns 0 or a positive integer. On failure, it returns a + negative errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-ECHILD</constant></term> + + <listitem><para>The bus connection has been created in a different process.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_set_close_on_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_creds_get_pid.xml b/man/sd_bus_creds_get_pid.xml index 1ca28e7a19..c068fbfb2e 100644 --- a/man/sd_bus_creds_get_pid.xml +++ b/man/sd_bus_creds_get_pid.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/sd_bus_creds_new_from_pid.xml b/man/sd_bus_creds_new_from_pid.xml index 2fc7a62c6b..eda5d17d8a 100644 --- a/man/sd_bus_creds_new_from_pid.xml +++ b/man/sd_bus_creds_new_from_pid.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/sd_bus_default.xml b/man/sd_bus_default.xml index 53cc9d7768..dfb32b9b4f 100644 --- a/man/sd_bus_default.xml +++ b/man/sd_bus_default.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -24,8 +24,11 @@ <refname>sd_bus_default_system</refname> <refname>sd_bus_open</refname> + <refname>sd_bus_open_with_description</refname> <refname>sd_bus_open_user</refname> + <refname>sd_bus_open_user_with_description</refname> <refname>sd_bus_open_system</refname> + <refname>sd_bus_open_system_with_description</refname> <refname>sd_bus_open_system_remote</refname> <refname>sd_bus_open_system_machine</refname> @@ -57,16 +60,34 @@ </funcprototype> <funcprototype> + <funcdef>int <function>sd_bus_open_with_description</function></funcdef> + <paramdef>sd_bus **<parameter>bus</parameter></paramdef> + <paramdef>const char *<parameter>description</parameter></paramdef> + </funcprototype> + + <funcprototype> <funcdef>int <function>sd_bus_open_user</function></funcdef> <paramdef>sd_bus **<parameter>bus</parameter></paramdef> </funcprototype> <funcprototype> + <funcdef>int <function>sd_bus_open_user_with_description</function></funcdef> + <paramdef>sd_bus **<parameter>bus</parameter></paramdef> + <paramdef>const char *<parameter>description</parameter></paramdef> + </funcprototype> + + <funcprototype> <funcdef>int <function>sd_bus_open_system</function></funcdef> <paramdef>sd_bus **<parameter>bus</parameter></paramdef> </funcprototype> <funcprototype> + <funcdef>int <function>sd_bus_open_system_with_description</function></funcdef> + <paramdef>sd_bus **<parameter>bus</parameter></paramdef> + <paramdef>const char *<parameter>description</parameter></paramdef> + </funcprototype> + + <funcprototype> <funcdef>int <function>sd_bus_open_system_remote</function></funcdef> <paramdef>sd_bus **<parameter>bus</parameter></paramdef> <paramdef>const char *<parameter>host</parameter></paramdef> @@ -126,6 +147,20 @@ <function>sd_bus_default_system()</function> to connect to the user or system buses.</para> + <para><function>sd_bus_open_with_description()</function>, + <function>sd_bus_open_user_with_description()</function>, and + <function>sd_bus_open_system_with_description()</function> are similar to + <function>sd_bus_open()</function>, <function>sd_bus_open_user()</function>, and + <function>sd_bus_open_system()</function>, but allow a description string to be set, see + <citerefentry><refentrytitle>sd_bus_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + <parameter>description</parameter> may be <constant>NULL</constant>, in which case this function + is equivalent to <function>sd_bus_open()</function>. This description string is used in log + messages about the bus object, and including a "name" for the bus makes them easier to + understand. Some messages are emitted during bus initialization, hence using this function is + prefereable to setting the description later with + <function>sd_bus_open_with_description()</function>. The argument is copied internally and will + not be referenced after the function returns.</para> + <para>If the <varname>$DBUS_SESSION_BUS_ADDRESS</varname> environment variable is set (cf. <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>), @@ -146,7 +181,8 @@ <citerefentry project='die-net'><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>. <parameter>host</parameter> consists of an optional user name followed by the <literal>@</literal> symbol, and the hostname, optionally followed by a - <literal>:</literal> and a machine name. If the machine name is given, a connection + <literal>:</literal> and a port, optionally followed by a + <literal>/</literal> and a machine name. If the machine name is given, a connection is created to the system bus in the specified container on the remote machine, and otherwise a connection to the system bus on the specified host is created.</para> diff --git a/man/sd_bus_error.xml b/man/sd_bus_error.xml index 77cb16e143..36cdf4c338 100644 --- a/man/sd_bus_error.xml +++ b/man/sd_bus_error.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -31,6 +31,7 @@ <refname>sd_bus_error_set_errnofv</refname> <refname>sd_bus_error_get_errno</refname> <refname>sd_bus_error_copy</refname> + <refname>sd_bus_error_move</refname> <refname>sd_bus_error_is_set</refname> <refname>sd_bus_error_has_name</refname> @@ -100,7 +101,7 @@ <paramdef>sd_bus_error *<parameter>e</parameter></paramdef> <paramdef>int <parameter>error</parameter></paramdef> <paramdef>const char *<parameter>format</parameter></paramdef> - <paramdef>va_list ap</paramdef> + <paramdef>va_list <parameter>ap</parameter></paramdef> </funcprototype> <funcprototype> @@ -115,6 +116,12 @@ </funcprototype> <funcprototype> + <funcdef>int <function>sd_bus_error_move</function></funcdef> + <paramdef>sd_bus_error *<parameter>dst</parameter></paramdef> + <paramdef>sd_bus_error *<parameter>e</parameter></paramdef> + </funcprototype> + + <funcprototype> <funcdef>int <function>sd_bus_error_is_set</function></funcdef> <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef> </funcprototype> @@ -148,7 +155,7 @@ should have both fields initialized to NULL. Set an error structure to <constant>SD_BUS_ERROR_NULL</constant> in order to reset both fields to NULL. When no longer necessary, resources - held by the <structname>sd_bus_error</structname>structure should + held by the <structname>sd_bus_error</structname> structure should be destroyed with <function>sd_bus_error_free()</function>.</para> <para><function>sd_bus_error_set()</function> sets an error @@ -245,6 +252,14 @@ Otherwise, they will be copied. Returns a converted <varname>errno</varname>-like, negative error code.</para> + <para><function>sd_bus_error_move()</function> is similar to <function>sd_bus_error_copy()</function>, but will + move any error information from <parameter>e</parameter> into <parameter>dst</parameter>, resetting the + former. This function cannot fail, as no new memory is allocated. Note that if <parameter>e</parameter> is not set + (or <constant>NULL</constant>) <parameter>dst</parameter> is initializated to + <constant>SD_BUS_ERROR_NULL</constant>. Moreover, if <parameter>dst</parameter> is <constant>NULL</constant> no + operation is executed on it and and resources held by <parameter>e</parameter> are freed and reset. Returns a + converted <varname>errno</varname>-like, negative error code.</para> + <para><function>sd_bus_error_is_set()</function> will return a non-zero value if <parameter>e</parameter> is non-<constant>NULL</constant> and an error has been set, @@ -287,9 +302,8 @@ <constant>NULL</constant>, and a positive errno value mapped from <parameter>e->name</parameter> otherwise.</para> - <para><function>sd_bus_error_copy()</function> returns 0 or a - positive integer on success, and a negative error value converted - from the error name otherwise.</para> + <para><function>sd_bus_error_copy()</function> and <function>sd_bus_error_move()</function> return 0 or a positive + integer on success, and a negative error value converted from the error name otherwise.</para> <para><function>sd_bus_error_is_set()</function> returns a non-zero value when <parameter>e</parameter> and the diff --git a/man/sd_bus_error_add_map.xml b/man/sd_bus_error_add_map.xml index 3eacbab660..dbe05a1892 100644 --- a/man/sd_bus_error_add_map.xml +++ b/man/sd_bus_error_add_map.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -6,7 +6,8 @@ SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="sd_bus_error_add_map"> +<refentry id="sd_bus_error_add_map" + xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_bus_error_add_map</title> @@ -123,15 +124,7 @@ </variablelist> </refsect1> - <refsect1> - <title>Notes</title> - - <para>The various error definitions described here are available - as a shared library, which can be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry - project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> + <xi:include href="libsystemd-pkgconfig.xml" /> <refsect1> <title>See Also</title> diff --git a/man/sd_bus_get_fd.xml b/man/sd_bus_get_fd.xml index a5d49074b3..2a81bddaa0 100644 --- a/man/sd_bus_get_fd.xml +++ b/man/sd_bus_get_fd.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -8,7 +8,7 @@ Copyright © 2016 Julian Orth --> -<refentry id="sd_bus_get_fd"> +<refentry id="sd_bus_get_fd" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_bus_get_fd</title> @@ -22,8 +22,10 @@ <refnamediv> <refname>sd_bus_get_fd</refname> + <refname>sd_bus_get_events</refname> + <refname>sd_bus_get_timeout</refname> - <refpurpose>Get the file descriptor connected to the message bus</refpurpose> + <refpurpose>Get the file descriptor, I/O events and time-out to wait for from a message bus object</refpurpose> </refnamediv> <refsynopsisdiv> @@ -34,46 +36,124 @@ <funcdef>int <function>sd_bus_get_fd</function></funcdef> <paramdef>sd_bus *<parameter>bus</parameter></paramdef> </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_get_events</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_get_timeout</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>uint64_t *<parameter>timeout_usec</parameter></paramdef> + </funcprototype> </funcsynopsis> </refsynopsisdiv> <refsect1> <title>Description</title> - <para> - <function>sd_bus_get_fd()</function> returns the file descriptor used to - communicate with the message bus. This descriptor can be used with - <citerefentry - project='die-net'><refentrytitle>select</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry - project='die-net'><refentrytitle>poll</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - or similar functions to wait for incoming messages. - </para> - - <para> - If the bus was created with the - <citerefentry><refentrytitle>sd_bus_set_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry> - function, then the <parameter>input_fd</parameter> used in that call is - returned. - </para> + <para><function>sd_bus_get_fd()</function> returns the file descriptor used to communicate from a message bus + object. This descriptor can be used with <citerefentry + project='man-pages'><refentrytitle>poll</refentrytitle><manvolnum>3</manvolnum></citerefentry> or a similar + function to wait for I/O events on the specified bus connection object. If the bus object was configured with the + <citerefentry><refentrytitle>sd_bus_set_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry> function, then + the <parameter>input_fd</parameter> file descriptor used in that call is returned.</para> + + <para><function>sd_bus_get_events()</function> returns the I/O events to wait for, suitable for passing to + <function>poll()</function> or a similar call. Returns a combination of <constant>POLLIN</constant>, + <constant>POLLOUT</constant>, … events, or negative on error.</para> + + <para><function>sd_bus_get_timeout()</function> returns the time-out in µs to pass to to + <function>poll()</function> or a similar call when waiting for events on the specified bus connection. The returned + time-out may be zero, in which case a subsequent I/O polling call should be invoked in non-blocking mode. The + returned timeout may be <constant>UINT64_MAX</constant> in which case the I/O polling call may block indefinitely, + without any applied time-out. Note that the returned time-out should be considered only a maximum sleeping time. It + is permissible (and even expected) that shorter time-outs are used by the calling program, in case other event + sources are polled in the same event loop. Note that the returned time-value is relative and specified in + microseconds. When converting this value in order to pass it as third argument to <function>poll()</function> + (which expects milliseconds), care should be taken to use a division that rounds up to ensure the I/O polling + operation doesn't sleep for shorter than necessary, which might result in unintended busy looping (alternatively, + use <citerefentry project='man-pages'><refentrytitle>ppoll</refentrytitle><manvolnum>3</manvolnum></citerefentry> + instead of plain <function>poll()</function>, which understands time-outs with nano-second granularity).</para> + + <para>These three functions are useful to hook up a bus connection object with an external or manual event loop + involving <function>poll()</function> or a similar I/O polling call. Before each invocation of the I/O polling + call, all three functions should be invoked: the file descriptor returned by <function>sd_bus_get_fd()</function> + should be polled for the events indicated by <function>sd_bus_get_events()</function>, and the I/O call should + block for that up to the time-out returned by <function>sd_bus_get_timeout()</function>. After each I/O polling + call the bus connection needs to process incoming or outgoing data, by invoking + <citerefentry><refentrytitle>sd_bus_process</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + + <para>Note that these function are only one of three supported ways to implement I/O event handling for bus + connections. Alternatively use + <citerefentry><refentrytitle>sd_bus_attach_event</refentrytitle><manvolnum>3</manvolnum></citerefentry> to attach a + bus connection to an <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry> + event loop. Or use <citerefentry><refentrytitle>sd_bus_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry> + as a simple synchronous, blocking I/O waiting call.</para> </refsect1> <refsect1> <title>Return Value</title> - <para> - Returns the file descriptor used for incoming messages from the message - bus. - </para> + <para><function>sd_bus_get_fd()</function> returns the file descriptor used for communication, or a negative + <varname>errno</varname>-style error code on error.</para> + + <para><function>sd_bus_get_events()</function> returns the I/O event mask to use for I/O event watching, or a + negative <varname>errno</varname>-style error code on error.</para> + + <para><function>sd_bus_get_timeout()</function> returns zero or positive on success, or a negative + <varname>errno</varname>-style error code on error.</para> </refsect1> <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>An invalid bus object was passed.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ECHILD</constant></term> + + <listitem><para>The bus connection was allocated in a parent process and is being reused in a child process + after <function>fork()</function>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOTCONN</constant></term> + + <listitem><para>The bus connection has been terminated.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EPERM</constant></term> + + <listitem><para>Two distinct file descriptors were passed for input and output using + <function>sd_bus_set_fd()</function>, which <function>sd_bus_get_fd()</function> cannot + return.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> <title>See Also</title> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_set_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_process</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_attach_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>poll</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/sd_bus_get_n_queued_read.xml b/man/sd_bus_get_n_queued_read.xml index b8788769ec..76ad659681 100644 --- a/man/sd_bus_get_n_queued_read.xml +++ b/man/sd_bus_get_n_queued_read.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/sd_bus_is_open.xml b/man/sd_bus_is_open.xml index 69cbb29284..0388db82a6 100644 --- a/man/sd_bus_is_open.xml +++ b/man/sd_bus_is_open.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -6,7 +6,8 @@ SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="sd_bus_is_open"> +<refentry id="sd_bus_is_open" + xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_bus_is_open</title> @@ -88,13 +89,7 @@ </variablelist> </refsect1> - <refsect1> - <title>Notes</title> - - <para><function>sd_bus_is_open()</function> and <function>sd_bus_is_ready()</function> are available as - a shared library, which can be compiled and linked to with the <constant>libsystemd</constant> <citerefentry - project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para> - </refsect1> + <xi:include href="libsystemd-pkgconfig.xml" /> <refsect1> <title>See Also</title> diff --git a/man/sd_bus_message_append.xml b/man/sd_bus_message_append.xml index b70ec8309c..1fdda51dcc 100644 --- a/man/sd_bus_message_append.xml +++ b/man/sd_bus_message_append.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -94,13 +94,12 @@ values for each entry matching the element type of the dictionary entries.</para> - <para>The <function>sd_bus_message_appendv()</function> is equivalent to - the function <function>sd_bus_message_append()</function>, - except that it is called with a <literal>va_list</literal> instead of - a variable number of arguments. This function does not call the - <function>va_end()</function> macro. Because it invokes the - <function>va_arg()</function> macro, the value of ap - is undefined after the call.</para> + <para>The <function>sd_bus_message_appendv()</function> is equivalent to the + <function>sd_bus_message_append()</function>, except that it is called with + a <literal>va_list</literal> instead of a variable number of arguments. This + function does not call the <function>va_end()</function> macro. Because it + invokes the <function>va_arg()</function> macro, the value of + <parameter>ap</parameter> is undefined after the call.</para> <para>For further details on the D-Bus type system, please consult the <ulink diff --git a/man/sd_bus_message_append_array.xml b/man/sd_bus_message_append_array.xml index 4c1142eeb0..746f9e3cc8 100644 --- a/man/sd_bus_message_append_array.xml +++ b/man/sd_bus_message_append_array.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/sd_bus_message_append_basic.xml b/man/sd_bus_message_append_basic.xml index 6c76569012..abd3baef36 100644 --- a/man/sd_bus_message_append_basic.xml +++ b/man/sd_bus_message_append_basic.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -255,6 +255,7 @@ <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_read_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html">The D-Bus specification</ulink> </para> diff --git a/man/sd_bus_message_append_string_memfd.xml b/man/sd_bus_message_append_string_memfd.xml index 37be79c976..4224af0a2e 100644 --- a/man/sd_bus_message_append_string_memfd.xml +++ b/man/sd_bus_message_append_string_memfd.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/sd_bus_message_append_strv.xml b/man/sd_bus_message_append_strv.xml index 9cd4513ab1..5f1a4f567f 100644 --- a/man/sd_bus_message_append_strv.xml +++ b/man/sd_bus_message_append_strv.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/sd_bus_message_copy.xml b/man/sd_bus_message_copy.xml new file mode 100644 index 0000000000..ac2a4f32b9 --- /dev/null +++ b/man/sd_bus_message_copy.xml @@ -0,0 +1,115 @@ +<?xml version='1.0'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + SPDX-License-Identifier: LGPL-2.1+ +--> + +<refentry id="sd_bus_message_copy" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_bus_message_copy</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_message_copy</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_message_copy</refname> + + <refpurpose>Copy the contents of one message to another</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int sd_bus_message_copy</funcdef> + <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> + <paramdef>sd_bus_message *<parameter>source</parameter></paramdef> + <paramdef>int <parameter>all</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_message_copy()</function> copies the contents from + message <parameter>source</parameter> to <parameter>m</parameter>. If + <parameter>all</parameter> is false, a single complete type is copied + (basic or container). If <parameter>all</parameter> is true, the contents + are copied until the end of the currently open container or the end + of <parameter>source</parameter>.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, this call returns true if anything was copied, and false if + there was nothing to copy. On failure, it returns a negative errno-style error + code.</para> + </refsect1> + + <refsect1 id='errors'> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para><parameter>source</parameter> or <parameter>m</parameter> are + <constant>NULL</constant>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EPERM</constant></term> + + <listitem><para>Message <parameter>m</parameter> has been sealed or + <parameter>source</parameter> has <emphasis>not</emphasis> been sealed. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ESTALE</constant></term> + + <listitem><para>Destination message is in invalid state. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENXIO</constant></term> + + <listitem><para>Destination message cannot be appended to. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_message_get_signature.xml b/man/sd_bus_message_get_signature.xml new file mode 100644 index 0000000000..bee6778190 --- /dev/null +++ b/man/sd_bus_message_get_signature.xml @@ -0,0 +1,111 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1+ --> + +<refentry id="sd_bus_message_get_signature" xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>sd_bus_message_get_signature</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_message_get_signature</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_message_get_signature</refname> + <refname>sd_bus_message_is_empty</refname> + <refname>sd_bus_message_has_signature</refname> + + <refpurpose>Query bus message signature</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>const char* <function>sd_bus_message_get_signature</function></funcdef> + <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> + <paramdef>int <parameter>complete</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_message_is_empty</function></funcdef> + <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_message_has_signature</function></funcdef> + <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> + <paramdef>const char *<parameter>signature</parameter></paramdef> + </funcprototype> + </funcsynopsis> + + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_message_get_signature()</function> returns the signature of message + <parameter>message</parameter>. If <parameter>complete</parameter> is true, the signature of the + whole message is returned, and just the signature of the currently open container otherwise. + </para> + + <para><function>sd_bus_message_is_empty()</function> returns true if the message is empty, + i.e. when its signature is empty.</para> + + <para><function>sd_bus_message_has_signature()</function> returns true if the signature of the + message <parameter>message</parameter> matches given <parameter>signature</parameter>. Parameter + <parameter>signature</parameter> may be <constant>NULL</constant>, this is treated the same as + an empty string, which is equivalent to calling <function>sd_bus_message_is_empty()</function>. + </para> +</refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>sd_bus_message_get_signature()</function> returns + the signature, and <constant>NULL</constant> on error.</para> + + <para>The other functions return 0 or a positive integer on success. On failure, they return a + negative errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>The <parameter>message</parameter> parameter is <constant>NULL</constant>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>NULL</constant></term> + + <listitem><para>The <parameter>message</parameter> parameter is <constant>NULL</constant>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_new</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_message_get_type.xml b/man/sd_bus_message_get_type.xml new file mode 100644 index 0000000000..6f6b7d0ba3 --- /dev/null +++ b/man/sd_bus_message_get_type.xml @@ -0,0 +1,129 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1+ --> + +<refentry id="sd_bus_message_get_type" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_bus_message_get_type</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_message_get_type</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_message_get_type</refname> + <refname>sd_bus_message_is_signal</refname> + <refname>sd_bus_message_is_method_call</refname> + <refname>sd_bus_message_is_method_error</refname> + + <refpurpose>Query bus message addressing metadata</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_message_get_type</function></funcdef> + <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> + <paramdef>uint8_t *<parameter>type</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_message_is_signal</function></funcdef> + <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> + <paramdef>const char *<parameter>interface</parameter></paramdef> + <paramdef>const char *<parameter>member</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_message_is_method_call</function></funcdef> + <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> + <paramdef>const char *<parameter>interface</parameter></paramdef> + <paramdef>const char *<parameter>member</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_message_is_method_error</function></funcdef> + <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> + <paramdef>const char *<parameter>name</parameter></paramdef> + </funcprototype> + </funcsynopsis> + + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_message_get_type()</function> returns the type of a message in the output + parameter <parameter>type</parameter>, one of <constant>SD_BUS_MESSAGE_METHOD_CALL</constant>, + <constant>SD_BUS_MESSAGE_METHOD_RETURN</constant>, + <constant>SD_BUS_MESSAGE_METHOD_ERROR</constant>, <constant>SD_BUS_MESSAGE_SIGNAL</constant>. + This type is either specified as a parameter when the message is created using + <citerefentry><refentrytitle>sd_bus_set_message_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + or is set automatically when the message is created using + <citerefentry><refentrytitle>sd_bus_set_message_new_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_set_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_set_message_new_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and similar functions. + </para> + + <para><function>sd_bus_message_is_signal()</function> checks if message <parameter>m</parameter> + is a signal message. If <parameter>interface</parameter> is non-null, it also checks if the + message has the same interface set. If <parameter>member</parameter> is non-null, it also checks + if the message has the same member set. Also see + <citerefentry><refentrytitle>sd_bus_set_message_new_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>. It returns true when all checks pass.</para> + + <para><function>sd_bus_message_is_method_call()</function> checks if message <parameter>m</parameter> + is a method call message. If <parameter>interface</parameter> is non-null, it also checks if the + message has the same interface set. If <parameter>member</parameter> is non-null, it also checks + if the message has the same member set. Also see + <citerefentry><refentrytitle>sd_bus_set_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>. It returns true when all checks pass.</para> + + <para><function>sd_bus_message_is_method_error()</function> checks if message <parameter>m</parameter> + is an error reply message. If <parameter>name</parameter> is non-null, it also checks if the + message has the same error identifier set. Also see + <citerefentry><refentrytitle>sd_bus_set_message_new_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>. It returns true when all checks pass.</para> +</refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, those functions return 0 or a positive + integer. On failure, it returns a negative errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>The <parameter>message</parameter> parameter or the output parameter are + <constant>NULL</constant>.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_set_destination</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_message_new.xml b/man/sd_bus_message_new.xml new file mode 100644 index 0000000000..78bca8a89c --- /dev/null +++ b/man/sd_bus_message_new.xml @@ -0,0 +1,189 @@ +<?xml version='1.0'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1+ --> + +<refentry id="sd_bus_message_new" xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>sd_bus_message_new</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_message_new</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_message_new</refname> + <refname>sd_bus_message_ref</refname> + <refname>sd_bus_message_unref</refname> + <refname>sd_bus_message_unrefp</refname> + <refname>SD_BUS_MESSAGE_METHOD_CALL</refname> + <refname>SD_BUS_MESSAGE_METHOD_RETURN</refname> + <refname>SD_BUS_MESSAGE_METHOD_ERROR</refname> + <refname>SD_BUS_MESSAGE_SIGNAL</refname> + <refname>sd_bus_message_get_bus</refname> + + <refpurpose>Create a new bus message object and create or destroy references to it</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcsynopsisinfo><token>enum</token> { + <constant>SD_BUS_MESSAGE_METHOD_CALL</constant>, + <constant>SD_BUS_MESSAGE_METHOD_RETURN</constant>, + <constant>SD_BUS_MESSAGE_METHOD_ERROR</constant>, + <constant>SD_BUS_MESSAGE_SIGNAL</constant>, +};</funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_message_new</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>sd_bus_message **<parameter>m</parameter></paramdef> + <paramdef>uint8_t <parameter>type</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_bus_message *<function>sd_bus_message_ref</function></funcdef> + <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_bus_message *<function>sd_bus_message_unref</function></funcdef> + <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void <function>sd_bus_message_unrefp</function></funcdef> + <paramdef>sd_bus_message **<parameter>mp</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_bus *<function>sd_bus_message_get_bus</function></funcdef> + <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_message_new()</function> creates a new bus message object attached to the + bus <parameter>bus</parameter> and returns it in the output parameter <parameter>m</parameter>. + This object is reference-counted, and will be destroyed when all references are gone. Initially, + the caller of this function owns the sole reference to the message object. Note that the message + object holds a reference to the bus object, so the bus object will not be destroyed as long as + the message exists.</para> + + <para>Note: this is a low-level call. In most cases functions like + <citerefentry><refentrytitle>sd_bus_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_new_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_new_method_return</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + and <citerefentry><refentrytitle>sd_bus_message_new_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry> + that create a message of a certain type and initialize various fields are easier to use.</para> + + <para>The <parameter>type</parameter> parameter specifies the type of the message. It must be + one of <constant>SD_BUS_MESSAGE_METHOD_CALL</constant> — a method call, + <constant>SD_BUS_MESSAGE_METHOD_RETURN</constant> — a method call reply, + <constant>SD_BUS_MESSAGE_METHOD_ERROR</constant> — an error reply to a method call, + <constant>SD_BUS_MESSAGE_SIGNAL</constant> — a broadcast message with no reply. + </para> + + <para>The flag to allow interactive authorization is initialized based on the current value set + in the bus object, see + <citerefentry><refentrytitle>sd_bus_set_allow_interactive_authorization</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + This may be changed using + <citerefentry><refentrytitle>sd_bus_message_set_allow_interactive_authorization</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + </para> + + <para><function>sd_bus_message_ref()</function> increases the reference counter of + <parameter>m</parameter> by one.</para> + + <para><function>sd_bus_message_unref()</function> decreases the reference counter of + <parameter>m</parameter> by one. Once the reference count has dropped to zero, message object is + destroyed and cannot be used anymore, so further calls to + <function>sd_bus_message_ref()</function> or <function>sd_bus_message_unref()</function> are + illegal.</para> + + <para><function>sd_bus_message_unrefp()</function> is similar to + <function>sd_bus_message_unref()</function> but takes a pointer to a + pointer to an <type>sd_bus_message</type> object. This call is useful in + conjunction with GCC's and LLVM's <ulink + url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up + Variable Attribute</ulink>. See + <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for an example how to use the cleanup attribute.</para> + + <para><function>sd_bus_message_ref()</function> and <function>sd_bus_message_unref()</function> + execute no operation if the passed in bus object address is + <constant>NULL</constant>. <function>sd_bus_message_unrefp()</function> will first dereference + its argument, which must not be <constant>NULL</constant>, and will execute no operation if + <emphasis>that</emphasis> is <constant>NULL</constant>. + </para> + + <para><function>sd_bus_message_get_bus()</function> returns the bus object that message + <parameter>m</parameter> is attached to.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>sd_bus_message_new()</function> returns 0 or a positive integer. On + failure, it returns a negative errno-style error code.</para> + + <para><function>sd_bus_message_ref()</function> always returns the argument. + </para> + + <para><function>sd_bus_message_unref()</function> always returns + <constant>NULL</constant>.</para> + + <para><function>sd_bus_message_get_bus()</function> always returns the bus object.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>Specified <parameter>type</parameter> is invalid.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOTCONN</constant></term> + + <listitem><para>The bus parameter <parameter>bus</parameter> is <constant>NULL</constant> or + the bus is not connected.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_new_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_new_method_return</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_new_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_message_new_method_call.xml b/man/sd_bus_message_new_method_call.xml new file mode 100644 index 0000000000..c643177ba4 --- /dev/null +++ b/man/sd_bus_message_new_method_call.xml @@ -0,0 +1,166 @@ +<?xml version='1.0'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1+ --> + +<refentry id="sd_bus_message_new_method_call" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_bus_message_new_method_call</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_message_new_method_call</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_message_new_method_call</refname> + <refname>sd_bus_message_new_method_return</refname> + + <refpurpose>Create a method call message</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int sd_bus_message_new_method_call</funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>sd_bus_message **<parameter>m</parameter></paramdef> + <paramdef>const char *<parameter>destination</parameter></paramdef> + <paramdef>const char *<parameter>path</parameter></paramdef> + <paramdef>const char *<parameter>interface</parameter></paramdef> + <paramdef>const char *<parameter>member</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int sd_bus_message_new_method_return</funcdef> + <paramdef>sd_bus_message *<parameter>call</parameter></paramdef> + <paramdef>sd_bus_message **<parameter>m</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <function>sd_bus_message_new_method_call()</function> function creates a new bus + message object that encapsulates a D-Bus method call, and returns it in the + <parameter>m</parameter> output parameter. The call will be made on the destination + <parameter>destination</parameter>, path <parameter>path</parameter>, on the interface + <parameter>interface</parameter>, member <parameter>member</parameter>.</para> + + <para>Briefly, the <emphasis>destination</emphasis> is a dot-separated name that identifies a + service connected to the bus. The <emphasis>path</emphasis> is a slash-separated identifier of + an object within the destination that resembles a file system path. The meaning of this path is + defined by the destination. The <emphasis>interface</emphasis> is a dot-separated name that + resembles a Java interface name that identifies a group of methods and signals supported by the + object identified by path. Methods and signals are collectively called + <emphasis>members</emphasis> and are identified by a simple name composed of ASCII letters, + numbers, and underscores. See the <ulink + url="https://dbus.freedesktop.org/doc/dbus-tutorial.html#concepts">D-Bus Tutorial</ulink> for an + in-depth explanation.</para> + + <para>The <parameter>destination</parameter> parameter may be <constant>NULL</constant>. The + <parameter>interface</parameter> parameter may be <constant>NULL</constant>, if the destination + has only a single member with the given name and there is no ambiguity if the interface name is + omitted.</para> + + <para>The <function>sd_bus_message_new_method_call()</function> function creates a new bus + message object that is a reply to the method call <parameter>call</parameter> and returns it in + the <parameter>m</parameter> output parameter. The <parameter>call</parameter> parameter must be + a method call message. The sender of <parameter>call</parameter> is used as the destination. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>This function returns 0 if the message object was successfully created, and a negative + errno-style error code otherwise.</para> + </refsect1> + + <refsect1 id='errors'> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>The output parameter <parameter>m</parameter> is + <constant>NULL</constant>.</para> + + <para>The <parameter>destination</parameter> parameter is non-null and is not a valid D-Bus + service name (<literal>org.somewhere.Something</literal>), the <parameter>path</parameter> + parameter is not a valid D-Bus path (<literal>/an/object/path</literal>), the + <parameter>interface</parameter> parameter is non-null and is not a valid D-Bus interface + name (<literal>an.interface.name</literal>), or the <parameter>member</parameter> parameter + is not a valid D-Bus member (<literal>Name</literal>).</para> + + <para>The <parameter>call</parameter> parameter is not a method call object.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOTCONN</constant></term> + + <listitem><para>The bus parameter <parameter>bus</parameter> is <constant>NULL</constant> or + the bus is not connected.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EPERM</constant></term> + + <listitem> + <para>The <parameter>call</parameter> parameter is not sealed.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EOPNOTSUPP</constant></term> + + <listitem> + <para>The <parameter>call</parameter> message does not have a cookie.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>Examples</title> + + <example> + <title>Make a call to a D-Bus method that takes a single parameter</title> + + <programlisting><xi:include href="print-unit-path.c" parse="text" /></programlisting> + <para>This defines a minimally useful program that will open a connection to the bus, create a + message object, send it, wait for the reply, and finally extract and print the answer. It does + error handling and proper memory management.</para> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_path_encode</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_message_new_method_error.xml b/man/sd_bus_message_new_method_error.xml new file mode 100644 index 0000000000..045c74f21a --- /dev/null +++ b/man/sd_bus_message_new_method_error.xml @@ -0,0 +1,190 @@ +<?xml version='1.0'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + SPDX-License-Identifier: LGPL-2.1+ +--> + +<refentry id="sd_bus_message_new_method_error" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_bus_message_new_method_error</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_message_new_method_error</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_message_new_method_error</refname> + <refname>sd_bus_message_new_method_errorf</refname> + <refname>sd_bus_message_new_method_errno</refname> + <refname>sd_bus_message_new_method_errnof</refname> + + <refpurpose>Create a an error reply for a method call</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int sd_bus_message_new_method_error</funcdef> + <paramdef>sd_bus_message *<parameter>call</parameter></paramdef> + <paramdef>sd_bus_message **<parameter>m</parameter></paramdef> + <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int sd_bus_message_new_method_errorf</funcdef> + <paramdef>sd_bus_message *<parameter>call</parameter></paramdef> + <paramdef>sd_bus_message **<parameter>m</parameter></paramdef> + <paramdef>const char *<parameter>name</parameter></paramdef> + <paramdef>const char *<parameter>format</parameter></paramdef> + <paramdef>…</paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int sd_bus_message_new_method_errno</funcdef> + <paramdef>sd_bus_message *<parameter>call</parameter></paramdef> + <paramdef>sd_bus_message **<parameter>m</parameter></paramdef> + <paramdef>int <parameter>error</parameter></paramdef> + <paramdef>const sd_bus_error *<parameter>p</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int sd_bus_message_new_method_errnof</funcdef> + <paramdef>sd_bus_message *<parameter>call</parameter></paramdef> + <paramdef>sd_bus_message **<parameter>m</parameter></paramdef> + <paramdef>int <parameter>error</parameter></paramdef> + <paramdef>const char *<parameter>format</parameter></paramdef> + <paramdef>…</paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <function>sd_bus_message_new_method_error()</function> function creates + a new bus message object that is an error reply to the + <parameter>call</parameter> message, and returns it in the + <parameter>m</parameter> output parameter. The error information from error + <parameter>e</parameter> is appended: the <parameter>name</parameter> field of + <parameter>e</parameter> is used as the error identifier in the reply header (for + example an error name such as + <literal>org.freedesktop.DBus.Error.NotSupported</literal> or the equivalent + symbolic <constant>SD_BUS_ERROR_NOT_SUPPORTED</constant>), and the + <parameter>message</parameter> field is set as the human readable error message + string if present. The error <parameter>e</parameter> must have the + <parameter>name</parameter> field set, see + <citerefentry><refentrytitle>sd_bus_error_is_set</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + </para> + + <para>The <function>sd_bus_message_new_method_errorf()</function> function + creates an error reply similarly to + <function>sd_bus_message_new_method_error()</function>, but instead of a ready + error structure, it takes an error identifier string <parameter>name</parameter>, + plus a <citerefentry + project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> + format string <parameter>format</parameter> and corresponding arguments. An error + reply is sent with the error identifier <parameter>name</parameter> and the + formatted string as the message. <parameter>name</parameter> and + <parameter>format</parameter> must not be <constant>NULL</constant>. + </para> + + <para>The <function>sd_bus_message_new_method_errno()</function> function creates + an error reply similarly to + <function>sd_bus_message_new_method_error()</function>, but in addition to the + error structure <parameter>p</parameter>, it takes an + <citerefentry><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry> + error value in parameter <parameter>error</parameter>. If the error + <parameter>p</parameter> is set (see + <citerefentry><refentrytitle>sd_bus_error_is_set</refentrytitle><manvolnum>3</manvolnum></citerefentry>), + it is used in the reply. Otherwise, <parameter>error</parameter> is translated to + an error identifier and used to create a new error structure using + <citerefentry><refentrytitle>sd_bus_error_set_errno</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and that is used in the reply. (If <parameter>error</parameter> is zero, no error + is actually set, and an error reply with no information is created.)</para> + + <para>The <function>sd_bus_message_new_method_errnof()</function> function + creates an error reply similarly to + <function>sd_bus_message_new_method_error()</function>. It takes an + <citerefentry><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry> + error value in parameter <parameter>error</parameter>, plus a <citerefentry + project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> + format string <parameter>format</parameter> and corresponding arguments. + <literal>%m</literal> may be used in the format string to refer to the error + string corresponding to the specified errno code. The error message is initalized + using the error identifier generated from <constant>error</constant> and the + formatted string. (If <parameter>error</parameter> is zero, no error is actually + set, and an error reply with no information is created.)</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>These functions return 0 if the error reply was successfully created, and a + negative errno-style error code otherwise.</para> + </refsect1> + + <refsect1 id='errors'> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>The call message <parameter>call</parameter> or the output + parameter <parameter>m</parameter> are <constant>NULL</constant>.</para> + + <para>Message <parameter>call</parameter> is not a method call + message.</para> + + <para>The error <parameter>error</parameter> parameter to + <function>sd_bus_message_new_method_error</function> is not set, see + <citerefentry><refentrytitle>sd_bus_error_is_set</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EPERM</constant></term> + + <listitem><para>Message <parameter>call</parameter> has been sealed. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOTCONN</constant></term> + + <listitem><para>The bus to which message <parameter>call</parameter> is + attached is not connected.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_message_new_signal.xml b/man/sd_bus_message_new_signal.xml new file mode 100644 index 0000000000..c9ed0bc4a4 --- /dev/null +++ b/man/sd_bus_message_new_signal.xml @@ -0,0 +1,120 @@ +<?xml version='1.0'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1+ --> + +<refentry id="sd_bus_message_new_signal" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_bus_message_new_signal</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_message_new_signal</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_message_new_signal</refname> + + <refpurpose>Create a signal message</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int sd_bus_message_new_signal</funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>sd_bus_message **<parameter>m</parameter></paramdef> + <paramdef>const char *<parameter>path</parameter></paramdef> + <paramdef>const char *<parameter>interface</parameter></paramdef> + <paramdef>const char *<parameter>member</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <function>sd_bus_message_new_signal()</function> function creates a new bus message + object that encapsulates a D-Bus signal, and returns it in the <parameter>m</parameter> output + parameter. The signal will be sent to path <parameter>path</parameter>, on the interface + <parameter>interface</parameter>, member <parameter>member</parameter>. When this message is + sent, no reply is expected. See + <citerefentry><refentrytitle>sd_bus_message_new_call</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for a short description of the meaning of the <parameter>path</parameter>, + <parameter>interface</parameter>, and <parameter>member</parameter> parameters. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>This function returns 0 if the message object was successfully created, and a negative + errno-style error code otherwise.</para> + </refsect1> + + <refsect1 id='errors'> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>The output parameter <parameter>m</parameter> is + <constant>NULL</constant>.</para> + + <para>The <parameter>path</parameter> parameter is not a valid D-Bus path + (<literal>/an/object/path</literal>), the <parameter>interface</parameter> parameter is not + a valid D-Bus interface name (<literal>an.interface.name</literal>), or the + <parameter>member</parameter> parameter is not a valid D-Bus member + (<literal>Name</literal>).</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOTCONN</constant></term> + + <listitem><para>The bus parameter <parameter>bus</parameter> is <constant>NULL</constant> or + the bus is not connected.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>Examples</title> + + <example> + <title>Send a simple signal</title> + + <programlisting><xi:include href="send-unit-files-changed.c" parse="text" /></programlisting> + + <para>This function in systemd sources is used to emit the + <literal>UnitFilesChanged</literal> signal when the unit files have been changed. + </para> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_message_read.xml b/man/sd_bus_message_read.xml new file mode 100644 index 0000000000..2815c01986 --- /dev/null +++ b/man/sd_bus_message_read.xml @@ -0,0 +1,232 @@ +<?xml version='1.0'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + SPDX-License-Identifier: LGPL-2.1+ +--> + +<refentry id="sd_bus_message_read" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_bus_message_read</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_message_read</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_message_read</refname> + <refname>sd_bus_message_readv</refname> + + <refpurpose>Read a sequence of values from a message</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_message_read</function></funcdef> + <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> + <paramdef>char char *<parameter>types</parameter></paramdef> + <paramdef>...</paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_message_readv</function></funcdef> + <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> + <paramdef>char char *<parameter>types</parameter></paramdef> + <paramdef>va_list <parameter>ap</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_message_read()</function> reads a sequence of fields from + the D-Bus message object <parameter>m</parameter> and advances the read position + in the message. The type string <parameter>types</parameter> describes the types + of items expected in the message and the field arguments that follow. The type + string may be <constant>NULL</constant> or empty, in which case nothing is + read.</para> + + <para>The type string is composed of the elements described in + <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + i.e. basic and container types. It must contain zero or more single "complete + types". The type string is <constant>NUL</constant>-terminated.</para> + + <para>For each type specified in the type string, one or more arguments need to be specified + after the <parameter>types</parameter> parameter, in the same order. The arguments must be + pointers to appropriate types (a pointer to <code>int8_t</code> for a <literal>y</literal> in + the type string, a pointer to <code>int32_t</code> for an <literal>i</literal>, a pointer to + <code>const char*</code> for an <literal>s</literal>, ...) which are set based on the values in + the message. As an exception, in case or array and variant types, the first argument is an + "input" argument that further specifies how the message should be read. See the table below for + a complete list of allowed arguments and their types. Note that, if the basic type is a pointer + (e.g., <code>const char *</code> in the case of a string), the argument is a pointer to a + pointer, and also the pointer value that is written is only borrowed and the contents must be + copied if they are to be used after the end of the messages lifetime.</para> + + <para>Each argument may also be <constant>NULL</constant>, in which case the value is read and + ignored.</para> + + <table> + <title>Item type specifiers</title> + + <tgroup cols='5'> + <colspec colname='specifier' /> + <colspec colname='constant' /> + <colspec colname='description' /> + <colspec colname='type1' /> + <colspec colname='type2' /> + <thead> + <row> + <entry>Specifier</entry> + <entry>Constant</entry> + <entry>Description</entry> + <entry>Type of the first argument</entry> + <entry>Types of the subsequent arguments, if any</entry> + </row> + </thead> + + <tbody> + <xi:include href="sd_bus_message_read_basic.xml" xpointer="xpointer(//table[@id='format-specifiers']//tbody/*)" /> + + <row> + <entry><literal>a</literal></entry> + <entry><constant>SD_BUS_TYPE_ARRAY</constant></entry> + <entry>array</entry> + <entry>int, which specifies the expected length <parameter>n</parameter> of the array</entry> + <entry><parameter>n</parameter> sets of arguments appropriate for the array element type</entry> + </row> + + <row> + <entry><literal>v</literal></entry> + <entry><constant>SD_BUS_TYPE_VARIANT</constant></entry> + <entry>variant</entry> + <entry>signature string</entry> + <entry>arguments appropriate for the types specified by the signature</entry> + </row> + + <row> + <entry><literal>(</literal></entry> + <entry><constant>SD_BUS_TYPE_STRUCT_BEGIN</constant></entry> + <entry>array start</entry> + <entry morerows="1" namest="type1" nameend="type2">arguments appropriate for the structure elements</entry> + </row> + <row> + <entry><literal>)</literal></entry> + <entry><constant>SD_BUS_TYPE_STRUCT_END</constant></entry> + <entry>array end</entry> + </row> + + <row> + <entry><literal>{</literal></entry> + <entry><constant>SD_BUS_TYPE_DICT_ENTRY_BEGIN</constant></entry> + <entry>dictionary entry start</entry> + <entry morerows="1">arguments appropriate for the first type in the pair</entry> + <entry morerows="1">arguments appropriate for the second type in the pair</entry> + </row> + <row> + <entry><literal>}</literal></entry> + <entry><constant>SD_BUS_TYPE_DICT_ENTRY_END</constant></entry> + <entry>dictionary entry end</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>If objects of the specified types are not present at the current position + in the message, an error is returned. + </para> + + <para>The <function>sd_bus_message_readv()</function> is equivalent to the + <function>sd_bus_message_read()</function>, except that it is called with a + <literal>va_list</literal> instead of a variable number of arguments. This + function does not call the <function>va_end()</function> macro. Because it + invokes the <function>va_arg()</function> macro, the value of + <parameter>ap</parameter> is undefined after the call.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para> + On success, <function>sd_bus_message_read()</function> and + <function>sd_bus_message_readv()</function> return 0 or a positive integer. On + failure, they return a negative errno-style error code. + </para> + </refsect1> + + <xi:include href="sd_bus_message_read_basic.xml" xpointer="errors" /> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>Examples</title> + + <para>Read a single basic type (a 64-bit integer): + </para> + + <programlisting>sd_bus_message *m; +int64_t x; + +sd_bus_message_read(m, "x", &x);</programlisting> + + <para>Read all types of integers:</para> + + <programlisting>uint8_t y; +int16_t n; +uint16_t q; +int32_t i; +uint32_t u; +int32_t x; +uint32_t t; +double d; + +sd_bus_message_read(m, "ynqiuxtd", &y, &n, &q, &i, &u, &x, &t, &d);</programlisting> + + <para>Read a structure composed of a string and a D-Bus path:</para> + + <programlisting>const char *s, *p; + +sd_bus_message_read(m, "(so)", &s, &p); +</programlisting> + + <para>Read a variant, with the real type "gt" (signature, unsigned integer): + </para> + + <programlisting>const char *s; +uint64_t *v; + +sd_bus_message_read(m, "v", "gt", &s, &v);</programlisting> + + <para>Read a dictionary containing three pairs of type {integer=>string}: + </para> + + <programlisting>int i, j, k; +const char *s, *t, *u; + +sd_bus_message_read(m, "a{is}", 3, &i, &s, &j, &t, &k, &u); + </programlisting> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_read_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_skip</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_message_read_array.xml b/man/sd_bus_message_read_array.xml new file mode 100644 index 0000000000..31481272bb --- /dev/null +++ b/man/sd_bus_message_read_array.xml @@ -0,0 +1,108 @@ +<?xml version='1.0'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1+ --> + +<refentry id="sd_bus_message_read_array"> + + <refentryinfo> + <title>sd_bus_message_read_array</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_message_read_array</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_message_read_array</refname> + + <refpurpose>Access an array of elements in a message</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_message_read_array</function></funcdef> + <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> + <paramdef>char <parameter>type</parameter></paramdef> + <paramdef>const void **<parameter>ptr</parameter></paramdef> + <paramdef>size_t *<parameter>size</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_message_read_array()</function> gives access to an element array in + message <parameter>m</parameter>. The "read pointer" in the message must be right before an + array of type <parameter>type</parameter>. As a special case, <parameter>type</parameter> may be + <constant>NUL</constant>, in which case any type is acceptable. A pointer to the array data is + returned in the parameter <parameter>ptr</parameter> and the size of array data (in bytes) is + returned in the parameter <parameter>size</parameter>. If <parameter>size</parameter> is 0, a + valid non-null pointer will be returned, but it may not be dereferenced. The data is aligned as + appropriate for the data type. The data is part of the message — it may not be modified and is + valid only as long as the message is referenced. After this function returns, the "read pointer" + points at the next element after the array.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para> + On success, <function>sd_bus_message_read_array()</function> returns 0 or + a positive integer. On failure, it returns a negative errno-style error + code. + </para> + </refsect1> + + <refsect1 id='errors'> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>Specified type is invalid or the message parameter or one of the output + parameters are <constant>NULL</constant>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EOPNOTSUPP</constant></term> + + <listitem><para>The byte order in the message is different than native byte + order.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EPERM</constant></term> + + <listitem><para>The message is not sealed.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EBADMSG</constant></term> + + <listitem><para>The message cannot be parsed.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_read</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_message_read_basic.xml b/man/sd_bus_message_read_basic.xml index c0e04667ca..774d3fcf87 100644 --- a/man/sd_bus_message_read_basic.xml +++ b/man/sd_bus_message_read_basic.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -52,18 +52,130 @@ </para> <para> - If <parameter>p</parameter> is not NULL, it should contain a pointer to an - appropriate object. For example, if <parameter>type</parameter> is - <constant>'y'</constant>, the object passed in <parameter>p</parameter> - should have type <code>uint8_t *</code>. If <parameter>type</parameter> - is <constant>'s'</constant>, the object passed in <parameter>p</parameter> - should have type <code>const char **</code>. Note that, if the basic type - is a pointer (e.g., <code>const char *</code> in the case of a string), - the pointer is only borrowed and the contents must be copied if they are - to be used after the end of the messages lifetime. Similarly, during the - lifetime of such a pointer, the message must not be modified. + If <parameter>p</parameter> is not <constant>NULL</constant>, it should contain + a pointer to an appropriate object. For example, if <parameter>type</parameter> + is <constant>'y'</constant>, the object passed in <parameter>p</parameter> + should have type <code>uint8_t *</code>. If <parameter>type</parameter> is + <constant>'s'</constant>, the object passed in <parameter>p</parameter> should + have type <code>const char **</code>. Note that, if the basic type is a pointer + (e.g., <code>const char *</code> in the case of a string), the pointer is only + borrowed and the contents must be copied if they are to be used after the end + of the messages lifetime. Similarly, during the lifetime of such a pointer, the + message must not be modified. See the table below for a complete list of allowed + types. </para> + <table id='format-specifiers'> + <title>Item type specifiers</title> + + <tgroup cols='4'> + <colspec colname='specifier' /> + <colspec colname='constant' /> + <colspec colname='description' /> + <colspec colname='ctype' /> + <thead> + <row> + <entry>Specifier</entry> + <entry>Constant</entry> + <entry>Description</entry> + <entry>Expected C Type</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>y</literal></entry> + <entry><constant>SD_BUS_TYPE_BYTE</constant></entry> + <entry>unsigned integer</entry> + <entry>uint8_t *</entry> + </row> + + <row> + <entry><literal>b</literal></entry> + <entry><constant>SD_BUS_TYPE_BOOLEAN</constant></entry> + <entry>boolean</entry> + <entry>int *</entry> + </row> + + <row> + <entry><literal>n</literal></entry> + <entry><constant>SD_BUS_TYPE_INT16</constant></entry> + <entry>signed integer</entry> + <entry>int16_t *</entry> + </row> + + <row> + <entry><literal>q</literal></entry> + <entry><constant>SD_BUS_TYPE_UINT16</constant></entry> + <entry>unsigned integer</entry> + <entry>uint16_t *</entry> + </row> + + <row> + <entry><literal>i</literal></entry> + <entry><constant>SD_BUS_TYPE_INT32</constant></entry> + <entry>signed integer</entry> + <entry>int32_t *</entry> + </row> + + <row> + <entry><literal>u</literal></entry> + <entry><constant>SD_BUS_TYPE_UINT32</constant></entry> + <entry>unsigned integer</entry> + <entry>uint32_t *</entry> + </row> + + <row> + <entry><literal>x</literal></entry> + <entry><constant>SD_BUS_TYPE_INT64</constant></entry> + <entry>signed integer</entry> + <entry>int64_t *</entry> + </row> + + <row> + <entry><literal>t</literal></entry> + <entry><constant>SD_BUS_TYPE_UINT64</constant></entry> + <entry>unsigned integer</entry> + <entry>uint64_t *</entry> + </row> + + <row> + <entry><literal>d</literal></entry> + <entry><constant>SD_BUS_TYPE_DOUBLE</constant></entry> + <entry>floating-point</entry> + <entry>double *</entry> + </row> + + <row> + <entry><literal>s</literal></entry> + <entry><constant>SD_BUS_TYPE_STRING</constant></entry> + <entry>Unicode string</entry> + <entry>const char **</entry> + </row> + + <row> + <entry><literal>o</literal></entry> + <entry><constant>SD_BUS_TYPE_OBJECT_PATH</constant></entry> + <entry>object path</entry> + <entry>const char **</entry> + </row> + + <row> + <entry><literal>g</literal></entry> + <entry><constant>SD_BUS_TYPE_SIGNATURE</constant></entry> + <entry>signature</entry> + <entry>const char **</entry> + </row> + + <row> + <entry><literal>h</literal></entry> + <entry><constant>SD_BUS_TYPE_UNIX_FD</constant></entry> + <entry>UNIX file descriptor</entry> + <entry>int *</entry> + </row> + </tbody> + </tgroup> + </table> + <para> If there is no object of the specified type at the current position in the message, an error is returned. @@ -80,12 +192,43 @@ </para> </refsect1> + <refsect1 id='errors'> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>Specified type string is invalid or the message parameter is + <constant>NULL</constant>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENXIO</constant></term> + + <listitem><para>The message does not contain the specified type at current + position.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EBADMSG</constant></term> + + <listitem><para>The message cannot be parsed.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + <refsect1> <title>See Also</title> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_skip</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_read</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/sd_bus_message_rewind.xml b/man/sd_bus_message_rewind.xml new file mode 100644 index 0000000000..c420c2f1d5 --- /dev/null +++ b/man/sd_bus_message_rewind.xml @@ -0,0 +1,88 @@ +<?xml version='1.0'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1+ --> + +<refentry id="sd_bus_message_rewind" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_bus_message_rewind</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_message_rewind</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_message_rewind</refname> + + <refpurpose>Return to begining of message or current container</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_message_rewind</function></funcdef> + <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> + <paramdef>int <parameter>complete</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_message_rewind()</function> moves the "read pointer" in the message + <parameter>m</parameter> to either the begining of the message (if + <parameter>complete</parameter> is true) or to the beginning of the currently open container. If + no container is open, <parameter>complete</parameter> has no effect.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para> + On success, this function returns 0 or a positive integer. The value is zero if the current + container or whole message in case no container is open is empty, and positive otherwise. On + failure, it returns a negative errno-style error code. + </para> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>The <parameter>m</parameter> parameter is <constant>NULL</constant>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EPERM</constant></term> + + <listitem><para>The message <parameter>m</parameter> has not been sealed.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_read</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_message_set_destination.xml b/man/sd_bus_message_set_destination.xml index 626272b0aa..e8a1206ae8 100644 --- a/man/sd_bus_message_set_destination.xml +++ b/man/sd_bus_message_set_destination.xml @@ -6,7 +6,6 @@ --> <refentry id="sd_bus_message_set_destination" xmlns:xi="http://www.w3.org/2001/XInclude"> - <refentryinfo> <title>sd_bus_message_set_destination</title> <productname>systemd</productname> @@ -19,8 +18,14 @@ <refnamediv> <refname>sd_bus_message_set_destination</refname> + <refname>sd_bus_message_get_destination</refname> + <refname>sd_bus_message_get_path</refname> + <refname>sd_bus_message_get_interface</refname> + <refname>sd_bus_message_get_member</refname> <refname>sd_bus_message_set_sender</refname> - <refpurpose>Set the destination or sender service name of a bus message</refpurpose> + <refname>sd_bus_message_get_sender</refname> + + <refpurpose>Set and query bus message addressing information</refpurpose> </refnamediv> <refsynopsisdiv> @@ -34,30 +39,76 @@ </funcprototype> <funcprototype> + <funcdef>const char* <function>sd_bus_message_get_destination</function></funcdef> + <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>const char* <function>sd_bus_message_get_path</function></funcdef> + <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>const char* <function>sd_bus_message_get_interface</function></funcdef> + <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>const char* <function>sd_bus_message_get_member</function></funcdef> + <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> + </funcprototype> + + <funcprototype> <funcdef>int <function>sd_bus_message_set_sender</function></funcdef> <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> <paramdef>const char *<parameter>sender</parameter></paramdef> </funcprototype> + + <funcprototype> + <funcdef>const char* <function>sd_bus_message_get_sender</function></funcdef> + <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> + </funcprototype> </funcsynopsis> </refsynopsisdiv> <refsect1> <title>Description</title> - <para><function>sd_bus_message_set_destination()</function> sets the destination service name for the specified bus - message object. The specified name must be a valid unique or well-known service name.</para> + <para><function>sd_bus_message_set_destination()</function> sets the destination service name + for the specified bus message object. The specified name must be a valid unique or well-known + service name.</para> + + <para><function>sd_bus_message_get_destination()</function>, + <function>sd_bus_message_get_path()</function>, + <function>sd_bus_message_get_interface()</function>, and + <function>sd_bus_message_get_member()</function> return the destination, path, interface, and + member fields from <parameter>message</parameter> header. The return value will be + <constant>NULL</constant> is <parameter>message</parameter> is <constant>NULL</constant> or the + message is of a type that doesn't use those fields or the message doesn't have them set. See + <citerefentry><refentrytitle>sd_bus_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>sd_bus_message_set_destination</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more discussion of those values.</para> + <para><function>sd_bus_message_set_sender()</function> sets the sender service name for the specified bus message object. The specified name must be a valid unique or well-known service name. This function is useful only for messages to send on direct connections as for connections to bus brokers the broker will fill in the destination field anyway, and the sender field set by original sender is ignored.</para> + + <para><function>sd_bus_message_get_sender()</function> returns the sender field from + <parameter>message</parameter>.</para> + + <para>When a string is returned, it is a pointer to internal storage, and may not be modified or + freed. It is only valid as long as the <parameter>message</parameter> remains referenced and + this field hasn't been changed by a different call.</para> </refsect1> <refsect1> <title>Return Value</title> - <para>On success, these calls return 0 or a positive integer. On failure, these calls return a negative errno-style - error code.</para> + <para>On success, these calls return 0 or a positive integer. On failure, these calls return a + negative errno-style error code.</para> </refsect1> <refsect1> @@ -69,13 +120,16 @@ <varlistentry> <term><constant>-EINVAL</constant></term> - <listitem><para>A specified parameter is invalid.</para></listitem> + <listitem><para>The <parameter>message</parameter> parameter or the output parameter are + <constant>NULL</constant>.</para></listitem> </varlistentry> <varlistentry> <term><constant>-EPERM</constant></term> - <listitem><para>The message is already sealed.</para></listitem> + <listitem><para>For <function>sd_bus_message_set_destination</function> or + <function>sd_bus_message_set_sender</function>, the message is already + sealed.</para></listitem> </varlistentry> <varlistentry> diff --git a/man/sd_bus_message_set_expect_reply.xml b/man/sd_bus_message_set_expect_reply.xml new file mode 100644 index 0000000000..2dfabca18f --- /dev/null +++ b/man/sd_bus_message_set_expect_reply.xml @@ -0,0 +1,127 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1+ --> + +<refentry id="sd_bus_message_set_expect_reply" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_bus_message_set_expect_reply</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_message_set_expect_reply</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_message_set_expect_reply</refname> + <refname>sd_bus_message_get_expect_reply</refname> + <refname>sd_bus_message_set_auto_start</refname> + <refname>sd_bus_message_get_auto_start</refname> + + <refpurpose>Set and query bus message metadata</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_message_set_expect_reply</function></funcdef> + <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> + <paramdef>int <parameter>b</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_message_get_expect_reply</function></funcdef> + <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_message_set_auto_start</function></funcdef> + <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> + <paramdef>int <parameter>b</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_message_get_auto_start</function></funcdef> + <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> + </funcprototype> + </funcsynopsis> + + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_message_set_expect_reply()</function> sets or clears the + <constant>NO_REPLY_EXPECTED</constant> flag on the message <parameter>m</parameter>. This flag + matters only for method call messages and is used to specify that no method return or error + reply is expected. It is ignored for other types. Thus, for a method call message, calling + <programlisting>sd_bus_message_set_expect_reply(…, 0)</programlisting> sets the flag and + suppresses the reply.</para> + + <para><function>sd_bus_message_get_expect_reply()</function> checks if the + <constant>NO_REPLY_EXPECTED</constant> flag is set on the message <parameter>m</parameter>. It + will return positive if it is not set, and zero if it is.</para> + + <para><function>sd_bus_message_set_auto_start()</function> sets or clears the + <constant>NO_AUTO_START</constant> flag on the message <parameter>m</parameter>. When the flag + is set the bus must not launch an owner for the destination name in response to this message. + Calling + <programlisting>sd_bus_message_set_auto_start(…, 0)</programlisting> sets the flag. + </para> + + <para><function>sd_bus_message_get_auto_start()</function> checks if the + <constant>NO_AUTO_START</constant> flag is set on the message <parameter>m</parameter>. It + will return positive if it is not set, and zero if it is.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, these functions return 0 or a positive integer. On failure, they return a + negative errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>The <parameter>message</parameter> parameter is + <constant>NULL</constant>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EPERM</constant></term> + + <listitem><para>The message <parameter>message</parameter> is sealed + when trying to set a flag.</para> + + <para>The message <parameter>message</parameter> has wrong + type.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_message_skip.xml b/man/sd_bus_message_skip.xml new file mode 100644 index 0000000000..384a791494 --- /dev/null +++ b/man/sd_bus_message_skip.xml @@ -0,0 +1,108 @@ +<?xml version='1.0'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1+ --> + +<refentry id="sd_bus_message_skip" xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>sd_bus_message_skip</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_message_skip</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_message_skip</refname> + + <refpurpose>Skip elements in a bus message</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_message_skip</function></funcdef> + <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> + <paramdef>const char* <parameter>types</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_message_skip()</function> is somewhat similar to + <citerefentry><refentrytitle>sd_bus_message_read</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + but instead of reading the contents of the message, it only moves the "read pointer". Subsequent + read operations will read the elements that are after the elements that were skipped.</para> + + <para>The <parameter>types</parameter> argument has the same meaning as in + <function>sd_bus_message_read()</function>. It may also be <constant>NULL</constant>, to skip a + single element of any type.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>sd_bus_message_skip()</function> returns 0 or a positive integer. On + failure, it returns a negative errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>The <parameter>m</parameter> parameter is + <constant>NULL</constant>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EBADMSG</constant></term> + + <listitem><para>The message cannot be parsed.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EPERM</constant></term> + + <listitem><para>The message is not sealed.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENXIO</constant></term> + + <listitem><para>The message end has been reached and the requested elements cannot be read. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_read</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_read_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_message_verify_type.xml b/man/sd_bus_message_verify_type.xml new file mode 100644 index 0000000000..fcb9f19e15 --- /dev/null +++ b/man/sd_bus_message_verify_type.xml @@ -0,0 +1,99 @@ +<?xml version='1.0'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1+ --> + +<refentry id="sd_bus_message_verify_type" xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>sd_bus_message_verify_type</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_message_verify_type</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_message_verify_type</refname> + + <refpurpose>Check if the message has specified type at the current location</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int sd_bus_message_verify_type</funcdef> + <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> + <paramdef>char <parameter>type</parameter></paramdef> + <paramdef>const char* <parameter>contents</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_message_verify_type()</function> checks if the complete type at the + current location in the message <parameter>m</parameter> matches the specified + <parameter>type</parameter> and <parameter>contents</parameter>. If non-zero, parameter + <parameter>type</parameter> must be one of the types specified in + <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + If non-null, parameter <parameter>contents</parameter> must be a valid sequence of complete + types. If both <parameter>type</parameter> and <parameter>contents</parameter> are specified + <parameter>type</parameter> must be a container type.</para> + + <para>If <parameter>type</parameter> is specified, the type in the message must match. If + <parameter>contents</parameter> is specified, the type in the message must be a container type + with this signature.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, this call returns true if the type matches and zero if not (the message + <parameter>m</parameter> contains different data or the end of the message has been reached). On + failure, it returns a negative errno-style error code.</para> + </refsect1> + + <refsect1 id='errors'> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para><parameter>m</parameter> or both <parameter>type</parameter> and + <parameter>contents</parameter> are <constant>NULL</constant>.</para> + + <para>Arguments do not satisfy other contraints listed above.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EPERM</constant></term> + + <listitem><para>Message <parameter>m</parameter> is not sealed. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_negotiate_fds.xml b/man/sd_bus_negotiate_fds.xml index a106bfb16e..c8d520ecd5 100644 --- a/man/sd_bus_negotiate_fds.xml +++ b/man/sd_bus_negotiate_fds.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/sd_bus_new.xml b/man/sd_bus_new.xml index 207291408e..1bc011d70a 100644 --- a/man/sd_bus_new.xml +++ b/man/sd_bus_new.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -23,6 +23,8 @@ <refname>sd_bus_ref</refname> <refname>sd_bus_unref</refname> <refname>sd_bus_unrefp</refname> + <refname>sd_bus_flush_close_unref</refname> + <refname>sd_bus_flush_close_unrefp</refname> <refpurpose>Create a new bus object and create or destroy references to it</refpurpose> </refnamediv> @@ -48,7 +50,17 @@ <funcprototype> <funcdef>void <function>sd_bus_unrefp</function></funcdef> - <paramdef>sd_bus **<parameter>bus</parameter></paramdef> + <paramdef>sd_bus **<parameter>busp</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_bus *<function>sd_bus_flush_close_unref</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void <function>sd_bus_flush_close_unrefp</function></funcdef> + <paramdef>sd_bus **<parameter>busp</parameter></paramdef> </funcprototype> </funcsynopsis> </refsynopsisdiv> @@ -96,19 +108,33 @@ block is left:</para> <programlisting>{ - __attribute__((cleanup(sd_bus_unrefp)) sd_bus *bus = NULL; - int r; - … - r = sd_bus_default(&bus); - if (r < 0) - fprintf(stderr, "Failed to allocate bus: %s\n", strerror(-r)); - … + __attribute__((cleanup(sd_bus_unrefp)) sd_bus *bus = NULL; + int r; + … + r = sd_bus_default(&bus); + if (r < 0) + fprintf(stderr, "Failed to allocate bus: %s\n", strerror(-r)); + … }</programlisting> - <para><function>sd_bus_ref()</function>, - <function>sd_bus_unref()</function> and - <function>sd_bus_unrefp()</function> execute no operation if the - passed in bus object is <constant>NULL</constant>.</para> + <para><function>sd_bus_ref()</function> and <function>sd_bus_unref()</function> + execute no operation if the passed in bus object address is + <constant>NULL</constant>. <function>sd_bus_unrefp()</function> will first + dereference its argument, which must not be <constant>NULL</constant>, and will + execute no operation if <emphasis>that</emphasis> is <constant>NULL</constant>. + </para> + + <para><function>sd_bus_flush_close_unref()</function> is similar to <function>sd_bus_unref()</function>, but first + executes <citerefentry><refentrytitle>sd_bus_flush</refentrytitle><manvolnum>3</manvolnum></citerefentry> as well + as <citerefentry><refentrytitle>sd_bus_close</refentrytitle><manvolnum>3</manvolnum></citerefentry>, ensuring that + any pending messages are properly flushed out before the reference to the connection is dropped and possibly the + object freed. This call is particularly useful immediately before exiting from a program as it ensures that any + pending outgoing messages are written out, and unprocessed but queued incoming messages released before the + connection is terminated and released.</para> + + <para><function>sd_bus_flush_close_unrefp()</function> is similar to + <function>sd_bus_flush_close_unref()</function>, but may be used in GCC's and LLVM's Clean-up Variable Attribute, + see above.</para> </refsect1> <refsect1> @@ -121,7 +147,7 @@ <para><function>sd_bus_ref()</function> always returns the argument. </para> - <para><function>sd_bus_unref()</function> always returns + <para><function>sd_bus_unref()</function> and <function>sd_bus_flush_close_unref()</function> always return <constant>NULL</constant>.</para> </refsect1> @@ -150,7 +176,8 @@ <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_open_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_open_system</refentrytitle><manvolnum>3</manvolnum></citerefentry> + <citerefentry><refentrytitle>sd_bus_open_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_close</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/sd_bus_path_encode.xml b/man/sd_bus_path_encode.xml index 86e255e573..03130a697b 100644 --- a/man/sd_bus_path_encode.xml +++ b/man/sd_bus_path_encode.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -6,7 +6,7 @@ SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="sd_bus_path_encode"> +<refentry id="sd_bus_path_encode" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_bus_path_encode</title> @@ -80,7 +80,7 @@ always be <constant>NUL</constant>-terminated. The returned string will be the concatenation of the bus path prefix plus an escaped version of the external identifier string. This operation may be - reversed with <function>sd_bus_decode()</function>. It is + reversed with <function>sd_bus_path_decode()</function>. It is recommended to only use external identifiers that generally require little escaping to be turned into valid bus path identifiers (for example, by sticking to a 7-bit ASCII character @@ -141,15 +141,7 @@ by the caller.</para> </refsect1> - <refsect1> - <title>Notes</title> - - <para><function>sd_bus_path_encode()</function> and - <function>sd_bus_path_decode()</function> are available as a - shared library, which can be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> + <xi:include href="libsystemd-pkgconfig.xml" /> <refsect1> <title>See Also</title> diff --git a/man/sd_bus_process.xml b/man/sd_bus_process.xml index 33afa0a3b5..66f22c29a6 100644 --- a/man/sd_bus_process.xml +++ b/man/sd_bus_process.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -8,7 +8,7 @@ Copyright © 2016 Julian Orth --> -<refentry id="sd_bus_process"> +<refentry id="sd_bus_process" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_bus_process</title> @@ -33,7 +33,7 @@ <funcprototype> <funcdef>int <function>sd_bus_process</function></funcdef> <paramdef>sd_bus *<parameter>bus</parameter></paramdef> - <paramdef>sd_bus_message **<parameter>r</parameter></paramdef> + <paramdef>sd_bus_message **<parameter>ret</parameter></paramdef> </funcprototype> </funcsynopsis> </refsynopsisdiv> @@ -41,49 +41,92 @@ <refsect1> <title>Description</title> - <para> - <function>sd_bus_process()</function> drives the connection between the - message bus and the client. That is, it handles connecting, - authentication, and message processing. It should be called in a loop - until no further progress can be made or an error occurs. - </para> - - <para> - Once no further progress can be made, - <citerefentry><refentrytitle>sd_bus_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry> - should be called. Alternatively the user can wait for incoming data on - the file descriptor returned by - <citerefentry><refentrytitle>sd_bus_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + <para><function>sd_bus_process()</function> drives the connection between the client and the message bus. That is, + it handles connecting, authentication, and message processing. When invoked pending I/O work is executed, and + queued incoming messages are dispatched to registered callbacks. Each time it is invoked a single operation is + executed. It returns zero when no operations were pending and positive if a message was processed. When zero is + returned the caller should synchronously poll for I/O events before calling into + <function>sd_bus_process()</function> again. For that either user the simple, synchronous + <citerefentry><refentrytitle>sd_bus_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry> call, or hook up + the bus connection object to an external or manual event loop using + <citerefentry><refentrytitle>sd_bus_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>. </para> - <para> - <function>sd_bus_process</function> processes at most one incoming - message per call. If the parameter <parameter>r</parameter> is not NULL - and the call processed a message, <code>*r</code> is set to this message. - The caller owns a reference to this message and should call - <citerefentry><refentrytitle>sd_bus_message_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> - when the message is no longer needed. If <parameter>r</parameter> is not - NULL, progress was made, but no message was processed, <code>*r</code> is - set to NULL. - </para> + <para><function>sd_bus_process()</function> processes at most one incoming message per call. If the parameter + <parameter>ret</parameter> is not <constant>NULL</constant> and the call processed a message, + <parameter>*ret</parameter> is set to this message. The caller owns a reference to this message and should call + <citerefentry><refentrytitle>sd_bus_message_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> when the + message is no longer needed. If <parameter>ret</parameter> is not NULL, progress was made, but no message was + processed, <parameter>*ret</parameter> is set to <constant>NULL</constant>.</para> + + <para>If a the bus object is connected to an + <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry> event loop (with + <citerefentry><refentrytitle>sd_bus_attach_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>), it is not + necessary to call <function>sd_bus_process()</function> directly as it is invoked automatically when + necessary.</para> </refsect1> <refsect1> <title>Return Value</title> - <para> - If progress was made, a positive integer is returned. If no progress was - made, 0 is returned. If an error occurs, a negative errno-style error code - is returned. - </para> + <para>If progress was made, a positive integer is returned. If no progress was made, 0 is returned. If an error + occurs, a negative <varname>errno</varname>-style error code is returned.</para> </refsect1> <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>An invalid bus object was passed.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ECHILD</constant></term> + + <listitem><para>The bus connection was allocated in a parent process and is being reused in a child process + after <function>fork()</function>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOTCONN</constant></term> + + <listitem><para>The bus connection has been terminated already.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ECONNRESET</constant></term> + + <listitem><para>The bus connection has been terminated just now.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EBUSY</constant></term> + + <listitem><para>This function is already being called, i.e. <function>sd_bus_process()</function> has been + called from a callback function that itself was called by + <function>sd_bus_process()</function>.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> <title>See Also</title> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_attach_event</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/sd_bus_reply_method_error.xml b/man/sd_bus_reply_method_error.xml new file mode 100644 index 0000000000..bbb916dc32 --- /dev/null +++ b/man/sd_bus_reply_method_error.xml @@ -0,0 +1,161 @@ +<?xml version='1.0'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + SPDX-License-Identifier: LGPL-2.1+ +--> + +<refentry id="sd_bus_reply_method_error" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_bus_reply_method_error</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_reply_method_error</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_reply_method_error</refname> + <refname>sd_bus_reply_method_errorf</refname> + <refname>sd_bus_reply_method_errno</refname> + <refname>sd_bus_reply_method_errnof</refname> + + <refpurpose>Reply with an error to a method call</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int sd_bus_reply_method_error</funcdef> + <paramdef>sd_bus_message *<parameter>call</parameter></paramdef> + <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int sd_bus_reply_method_errorf</funcdef> + <paramdef>sd_bus_message *<parameter>call</parameter></paramdef> + <paramdef>const char *<parameter>name</parameter></paramdef> + <paramdef>const char *<parameter>format</parameter></paramdef> + <paramdef>…</paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int sd_bus_reply_method_errno</funcdef> + <paramdef>sd_bus_message *<parameter>call</parameter></paramdef> + <paramdef>int <parameter>error</parameter></paramdef> + <paramdef>const sd_bus_error *<parameter>p</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int sd_bus_reply_method_errnof</funcdef> + <paramdef>sd_bus_message *<parameter>call</parameter></paramdef> + <paramdef>int <parameter>error</parameter></paramdef> + <paramdef>const char *<parameter>format</parameter></paramdef> + <paramdef>…</paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <function>sd_bus_reply_method_error()</function> function sends an + error reply to the <parameter>call</parameter> message. The error structure + <parameter>e</parameter> specifies the error to send, and is used as described in + <citerefentry><refentrytitle>sd_bus_message_new_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + If no reply is expected to <parameter>call</parameter>, this function returns + success without sending reply.</para> + + <para>The <function>sd_bus_reply_method_errorf()</function> is to + <function>sd_bus_reply_method_error()</function> what + <function>sd_bus_message_new_method_errorf()</function> is to + <function>sd_bus_message_new_method_error()</function>.</para> + + <para>The <function>sd_bus_reply_method_errno()</function> is to + <function>sd_bus_reply_method_error()</function> what + <function>sd_bus_message_new_method_errno()</function> is to + <function>sd_bus_message_new_method_error()</function>.</para> + + <para>The <function>sd_bus_reply_method_errnof()</function> is to + <function>sd_bus_reply_method_error()</function> what + <function>sd_bus_message_new_method_errnof()</function> is to + <function>sd_bus_message_new_method_error()</function>.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>These functions return 0 if the error reply was successfully sent or if + none was expected, and a negative errno-style error code otherwise.</para> + </refsect1> + + <refsect1 id='errors'> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>The call message <parameter>call</parameter> is + <constant>NULL</constant>.</para> + + <para>Message <parameter>call</parameter> is not a method call message. + </para> + + <para>Message <parameter>call</parameter> is not attached to a bus.</para> + + <para>The error <parameter>error</parameter> parameter to + <function>sd_bus_reply_method_error</function> is not set, see + <citerefentry><refentrytitle>sd_bus_error_is_set</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EPERM</constant></term> + + <listitem><para>Message <parameter>call</parameter> has been sealed. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOTCONN</constant></term> + + <listitem><para>The bus to which message <parameter>call</parameter> is + attached is not connected.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + + <para>In addition, any error message returned by + <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>1</manvolnum></citerefentry> + may be returned.</para> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_new_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_request_name.xml b/man/sd_bus_request_name.xml index 54a14c877c..3c98b60c6a 100644 --- a/man/sd_bus_request_name.xml +++ b/man/sd_bus_request_name.xml @@ -6,7 +6,8 @@ SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="sd_bus_request_name"> +<refentry id="sd_bus_request_name" + xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_bus_request_name</title> @@ -193,13 +194,7 @@ </variablelist> </refsect1> - <refsect1> - <title>Notes</title> - - <para>The <function>sd_bus_acquire_name()</function> and the other interfaces described here are available as a - shared library, which can be compiled and linked to with the <constant>libsystemd</constant> <citerefentry - project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para> - </refsect1> + <xi:include href="libsystemd-pkgconfig.xml" /> <refsect1> <title>See Also</title> diff --git a/man/sd_bus_set_close_on_exit.xml b/man/sd_bus_set_close_on_exit.xml new file mode 100644 index 0000000000..dc4f6a3e15 --- /dev/null +++ b/man/sd_bus_set_close_on_exit.xml @@ -0,0 +1,105 @@ +<?xml version='1.0'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + SPDX-License-Identifier: LGPL-2.1+ +--> + +<refentry id="sd_bus_set_close_on_exit" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_bus_set_close_on_exit</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_set_close_on_exit</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_set_close_on_exit</refname> + <refname>sd_bus_get_close_on_exit</refname> + + <refpurpose>Control whether to close the bus connection during the event loop exit phase</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_set_close_on_exit</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>int <parameter>b</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_get_close_on_exit</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_set_close_on_exit()</function> may be used to enable or disable whether the bus connection + is automatically flushed (as in + <citerefentry><refentrytitle>sd_bus_flush</refentrytitle><manvolnum>3</manvolnum></citerefentry>) and closed (as in + <citerefentry><refentrytitle>sd_bus_close</refentrytitle><manvolnum>3</manvolnum></citerefentry>) during the exit + phase of the event loop. This logic only applies to bus connections that are attached to an + <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry> event loop, see + <citerefentry><refentrytitle>sd_bus_attach_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>. By default + this mechanism is enabled and makes sure that any pending messages that have not been written to the bus connection + are written out when the event loop is shutting down. In some cases this behaviour is not desirable, for example + when the bus connection shall remain usable until after the event loop exited. If <parameter>b</parameter> is + true, the feature is enabled (which is the default), otherwise disabled.</para> + + <para><function>sd_bus_get_close_on_exit()</function> may be used to query the current setting of this feature. It + returns zero when the feature is disabled, and positive if enabled.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>sd_bus_set_close_on_exit()</function> returns 0 or a positive integer. On failure, it returns a negative errno-style + error code.</para> + + <para><function>sd_bus_get_close_on_exit()</function> returns 0 if the feature is currently turned off or a + positive integer if it is on. On failure, it returns a negative errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-ECHILD</constant></term> + + <listitem><para>The bus connection has been created in a different process.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_flush</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_attach_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_set_connected_signal.xml b/man/sd_bus_set_connected_signal.xml index b392e0f4c4..32fc630cfe 100644 --- a/man/sd_bus_set_connected_signal.xml +++ b/man/sd_bus_set_connected_signal.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -6,7 +6,8 @@ SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="sd_bus_set_connected_signal"> +<refentry id="sd_bus_set_connected_signal" + xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_bus_set_connected_signal</title> @@ -94,13 +95,7 @@ </variablelist> </refsect1> - <refsect1> - <title>Notes</title> - - <para><function>sd_bus_set_connected_signal()</function> and <function>sd_bus_get_connected_signal()</function> are available as - a shared library, which can be compiled and linked to with the <constant>libsystemd</constant> <citerefentry - project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para> - </refsect1> + <xi:include href="libsystemd-pkgconfig.xml" /> <refsect1> <title>See Also</title> diff --git a/man/sd_bus_set_description.xml b/man/sd_bus_set_description.xml new file mode 100644 index 0000000000..af02c20dd8 --- /dev/null +++ b/man/sd_bus_set_description.xml @@ -0,0 +1,188 @@ +<?xml version='1.0'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + SPDX-License-Identifier: LGPL-2.1+ +--> + +<refentry id="sd_bus_set_description" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_bus_set_description</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_set_description</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_set_description</refname> + <refname>sd_bus_get_description</refname> + <refname>sd_bus_set_anonymous</refname> + <refname>sd_bus_set_trusted</refname> + <refname>sd_bus_set_allow_interactive_authorization</refname> + <refname>sd_bus_get_allow_interactive_authorization</refname> + + <refpurpose>Set or query properties of a bus object</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_set_description</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>const char *<parameter>description</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_get_description</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>const char **<parameter>description</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_set_anonymous</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>int <parameter>b</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_set_trusted</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>int <parameter>b</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_set_allow_interactive_authorization</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>int <parameter>b</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_get_allow_interactive_authorization</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_set_description()</function> sets the description string + that is used in logging to the specified string. The string is copied internally + and freed when the bus object is deallocated. The + <parameter>description</parameter> argument may be <constant>NULL</constant>, in + which case the description is unset. This function must be called before the bus + has been started.</para> + + <para><function>sd_bus_get_description()</function> returns a description string + in <parameter>description</parameter>. This string may have been previously set + with <function>sd_bus_set_description()</function> or + <citerefentry><refentrytitle>sd_bus_open_with_description</refentrytitle><manvolnum>3</manvolnum></citerefentry> + or similar. If not set this way, a default string like <literal>system</literal> + or <literal>user</literal> will be returned for the system or user buses, + and <constant>NULL</constant> otherwise.</para> + + <para><function>sd_bus_set_anonymous()</function> enables or disables "anonymous + authentication", i.e. lack of authentication, of the bus peer. This function must + be called before the bus has been started. See the <ulink + url="view-source:https://dbus.freedesktop.org/doc/dbus-specification.html#auth-mechanisms">Authentication + Mechanisms</ulink> section of the D-Bus specification for details.</para> + + <para><function>sd_bus_set_trusted()</function> sets the "trusted" state on the + <parameter>bus</parameter> object. If true, all connections on the bus are + trusted and access to all privileged and unprivileged methods is granted. This + function must be called before the bus has been started.</para> + + <para><function>sd_bus_set_allow_interactive_authorization()</function> + enables or disables interactive authorization for method calls. If true, + messages are marked with the + <constant>ALLOW_INTERACTIVE_AUTHORIZATION</constant> flag specified by the + <ulink + url="view-source:https://dbus.freedesktop.org/doc/dbus-specification.html">D-Bus</ulink> + specification, informing the receiving side that the caller is prepared to + wait for interactive authorization, which might take a considerable time to + complete. If this flag is set, the user may be queried for passwords or + confirmation via <ulink + url="http://www.freedesktop.org/wiki/Software/polkit">polkit</ulink> or a + similar framework.</para> + + <para><function>sd_bus_get_allow_interactive_authorization()</function> returns + true if interactive authorization is allowed and false if not.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, these functions return 0 or a positive integer. On failure, + they return a negative errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>An argument is invalid.</para></listitem> + </varlistentry> + </variablelist> + + <variablelist> + <varlistentry> + <term><constant>-ENOPKG</constant></term> + + <listitem><para>The bus cannot be resolved.</para></listitem> + </varlistentry> + </variablelist> + + <variablelist> + <varlistentry> + <term><constant>-EPERM</constant></term> + + <listitem><para>The bus has already been started.</para></listitem> + </varlistentry> + </variablelist> + + <variablelist> + <varlistentry> + <term><constant>-ECHILD</constant></term> + + <listitem><para>The bus was created in a different process.</para></listitem> + </varlistentry> + </variablelist> + + <variablelist> + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_open_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_open_system</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_set_sender.xml b/man/sd_bus_set_sender.xml index e35af282c0..556e72cefc 100644 --- a/man/sd_bus_set_sender.xml +++ b/man/sd_bus_set_sender.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -6,7 +6,8 @@ SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="sd_bus_set_sender"> +<refentry id="sd_bus_set_sender" + xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_bus_set_sender</title> @@ -89,13 +90,7 @@ </variablelist> </refsect1> - <refsect1> - <title>Notes</title> - - <para><function>sd_bus_set_sender()</function> and <function>sd_bus_get_sender()</function> are available as - a shared library, which can be compiled and linked to with the <constant>libsystemd</constant> <citerefentry - project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para> - </refsect1> + <xi:include href="libsystemd-pkgconfig.xml" /> <refsect1> <title>See Also</title> diff --git a/man/sd_bus_set_watch_bind.xml b/man/sd_bus_set_watch_bind.xml index d19f6b9212..129b98c5f3 100644 --- a/man/sd_bus_set_watch_bind.xml +++ b/man/sd_bus_set_watch_bind.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -6,7 +6,8 @@ SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="sd_bus_set_watch_bind"> +<refentry id="sd_bus_set_watch_bind" + xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_bus_set_watch_bind</title> @@ -100,13 +101,7 @@ </variablelist> </refsect1> - <refsect1> - <title>Notes</title> - - <para><function>sd_bus_set_watch_bind()</function> and <function>sd_bus_get_watch_bind()</function> are available as - a shared library, which can be compiled and linked to with the <constant>libsystemd</constant> <citerefentry - project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para> - </refsect1> + <xi:include href="libsystemd-pkgconfig.xml" /> <refsect1> <title>See Also</title> diff --git a/man/sd_bus_slot_ref.xml b/man/sd_bus_slot_ref.xml new file mode 100644 index 0000000000..c5f050635d --- /dev/null +++ b/man/sd_bus_slot_ref.xml @@ -0,0 +1,107 @@ +<?xml version='1.0'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1+ --> + +<refentry id="sd_bus_slot_ref" xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>sd_bus_slot_ref</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_slot_ref</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_slot_ref</refname> + <refname>sd_bus_slot_unref</refname> + <refname>sd_bus_slot_unrefp</refname> + <refname>sd_bus_slot_get_bus</refname> + + <refpurpose>Create and destroy references to a bus slot object</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>sd_bus_slot *<function>sd_bus_slot_ref</function></funcdef> + <paramdef>sd_bus_slot *<parameter>slot</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_bus_slot *<function>sd_bus_slot_unref</function></funcdef> + <paramdef>sd_bus_slot *<parameter>slot</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void <function>sd_bus_slot_unrefp</function></funcdef> + <paramdef>sd_bus_slot **<parameter>slotp</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_bus *<function>sd_bus_slot_get_bus</function></funcdef> + <paramdef>sd_bus_slot *<parameter>m</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_slot_ref()</function> increases the reference counter of + <parameter>slot</parameter> by one.</para> + + <para><function>sd_bus_slot_unref()</function> decreases the reference counter of + <parameter>slot</parameter> by one. Once the reference count has dropped to zero, slot object is + destroyed and cannot be used anymore, so further calls to <function>sd_bus_slot_ref()</function> + or <function>sd_bus_slot_unref()</function> are illegal.</para> + + <para><function>sd_bus_slot_unrefp()</function> is similar to + <function>sd_bus_slot_unref()</function> but takes a pointer to a pointer to an + <type>sd_bus_slot</type> object. This call is useful in conjunction with GCC's and LLVM's <ulink + url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up Variable + Attribute</ulink>. See + <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for an example how to use the cleanup attribute.</para> + + <para><function>sd_bus_slot_ref()</function> and <function>sd_bus_slot_unref()</function> + execute no operation if the passed in bus object address is + <constant>NULL</constant>. <function>sd_bus_slot_unrefp()</function> will first dereference + its argument, which must not be <constant>NULL</constant>, and will execute no operation if + <emphasis>that</emphasis> is <constant>NULL</constant>. + </para> + + <para><function>sd_bus_slot_get_bus()</function> returns the bus object that message + <parameter>slot</parameter> is attached to.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>sd_bus_slot_ref()</function> always returns the argument.</para> + + <para><function>sd_bus_slot_unref()</function> always returns <constant>NULL</constant>.</para> + + <para><function>sd_bus_slot_get_bus()</function> always returns the bus object.</para> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_slot_new_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_call_method_async</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_slot_set_description.xml b/man/sd_bus_slot_set_description.xml new file mode 100644 index 0000000000..4bcb1e3611 --- /dev/null +++ b/man/sd_bus_slot_set_description.xml @@ -0,0 +1,109 @@ +<?xml version='1.0'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1+ --> + +<refentry id="sd_bus_slot_set_description" xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>sd_bus_slot_set_description</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_slot_set_description</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_slot_set_description</refname> + <refname>sd_bus_slot_get_description</refname> + + <refpurpose>Set or query the description of bus slot objects</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_slot_set_description</function></funcdef> + <paramdef>sd_bus_slot* <parameter>slot</parameter></paramdef> + <paramdef>const char *<parameter>description</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_slot_get_description</function></funcdef> + <paramdef>sd_bus_slot* <parameter>bus</parameter></paramdef> + <paramdef>const char **<parameter>description</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_slot_set_description()</function> sets the description string + that is used in logging to the specified string. The string is copied internally + and freed when the bus slot object is deallocated. The + <parameter>description</parameter> argument may be <constant>NULL</constant>, in + which case the description is unset.</para> + + <para><function>sd_bus_slot_get_description()</function> returns a description string in + <parameter>description</parameter>. If the string is not set, e.g. with + <function>sd_bus_slot_set_description()</function>, and the slot is a bus match callback slot, + the match string will be returned. Otherwise, <constant>-ENXIO</constant> is returned. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, these functions return 0 or a positive integer. On failure, + they return a negative errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>An required argument is <constant>NULL</constant>.</para></listitem> + </varlistentry> + </variablelist> + + <variablelist> + <varlistentry> + <term><constant>-ENXIO</constant></term> + + <listitem><para>The bus slot object has no description.</para></listitem> + </varlistentry> + </variablelist> + + <variablelist> + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry> + <citerefentry><refentrytitle>sd_bus_slot_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_slot_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_slot_set_destroy_callback.xml b/man/sd_bus_slot_set_destroy_callback.xml index a54b7e2d61..80bfd865d5 100644 --- a/man/sd_bus_slot_set_destroy_callback.xml +++ b/man/sd_bus_slot_set_destroy_callback.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -79,7 +79,7 @@ for <parameter>slot</parameter> in the <parameter>callback</parameter> parameter.</para> <para><function>sd_bus_track_set_destroy_callback()</function> and - <function>sd_bus_track_get_destroy_callback</function> provide equivalent functionality for the + <function>sd_bus_track_get_destroy_callback()</function> provide equivalent functionality for the <parameter>userdata</parameter> pointer associated with bus peer tracking objects. For details about bus peer tracking objects, see <citerefentry><refentrytitle>sd_bus_track_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> @@ -93,7 +93,7 @@ negative errno-style error code.</para> <para><function>sd_bus_slot_get_destroy_callback()</function> and - <function>sd_bus_track_get_destroy_callback</function> return positive if the destroy callback function is set, 0 + <function>sd_bus_track_get_destroy_callback()</function> return positive if the destroy callback function is set, 0 if not. On failure, they return a negative errno-style error code.</para> </refsect1> diff --git a/man/sd_bus_slot_set_floating.xml b/man/sd_bus_slot_set_floating.xml index 77057c26cd..2b8c900996 100644 --- a/man/sd_bus_slot_set_floating.xml +++ b/man/sd_bus_slot_set_floating.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/sd_bus_slot_set_userdata.xml b/man/sd_bus_slot_set_userdata.xml new file mode 100644 index 0000000000..dad708b6ab --- /dev/null +++ b/man/sd_bus_slot_set_userdata.xml @@ -0,0 +1,88 @@ +<?xml version='1.0'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1+ --> + +<refentry id="sd_bus_slot_set_userdata" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_bus_slot_set_userdata</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_slot_set_userdata</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_slot_set_userdata</refname> + <refname>sd_bus_slot_get_userdata</refname> + + <refpurpose>Set and query the value in the "userdata" field</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>void* <function>sd_bus_slot_set_userdata</function></funcdef> + <paramdef>sd_bus_slot* <parameter>slot</parameter></paramdef> + <paramdef>void* <parameter>userdata</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void* <function>sd_bus_slot_get_userdata</function></funcdef> + <paramdef>sd_bus_slot* <parameter>slot</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The userdata pointer allows data to be passed between the point where a callback is + registered, for example when a filter is added using + <citerefentry><refentrytitle>sd_bus_add_filter</refentrytitle><manvolnum>3</manvolnum></citerefentry> + or an asynchronous function call is made using + <citerefentry><refentrytitle>sd_bus_call_async</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + and the point where the callback is called, without having any global state. The pointer has + type <type>void*</type> and is not used by the sd-bus functions in any way, except to pass to + the callback function.</para> + + <para>Usually, the userdata field is set when the slot object is initially + registered. <function>sd_bus_slot_set_userdata()</function> may be used to change it later for + the bus slot object <parameter>slot</parameter>. Previous value of the field is returned. The + argument and returned value may be <constant>NULL</constant>. It will be passed as the + <parameter>userdata</parameter> argument to the callback function attached to the slot.</para> + + <para><function>sd_bus_slot_set_userdata()</function> gets the value of the userdata field in + the bus slot object <parameter>slot</parameter>.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, these functions return the value of the userdata field before the function + call. If the <parameter>slot</parameter> object is <constant>NULL</constant>, + <constant>NULL</constant> will be returned to signify an error, but this is not distinguishable + from the userdata field value being <constant>NULL</constant>.</para> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_slot_set_destroy_callback</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_slot_get_current_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_track_add_name.xml b/man/sd_bus_track_add_name.xml index 5b7f5c5b0b..ef304fc067 100644 --- a/man/sd_bus_track_add_name.xml +++ b/man/sd_bus_track_add_name.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/sd_bus_track_new.xml b/man/sd_bus_track_new.xml index 0b2273ed01..711eca3fcb 100644 --- a/man/sd_bus_track_new.xml +++ b/man/sd_bus_track_new.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/sd_bus_wait.xml b/man/sd_bus_wait.xml new file mode 100644 index 0000000000..e866eeb20b --- /dev/null +++ b/man/sd_bus_wait.xml @@ -0,0 +1,113 @@ +<?xml version='1.0'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + SPDX-License-Identifier: LGPL-2.1+ + + Copyright © 2016 Julian Orth +--> + +<refentry id="sd_bus_wait" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_bus_wait</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_wait</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_wait</refname> + + <refpurpose>Wait for I/O on a bus connection</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_wait</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>uint64_t <parameter>timeout_usec</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_wait()</function> synchronously waits for I/O on the specified bus connection object. This + function is supposed to be called whenever + <citerefentry><refentrytitle>sd_bus_process</refentrytitle><manvolnum>3</manvolnum></citerefentry> returns zero, + indicating that no work is pending on the connection. Internally, this call invokes <citerefentry + project='man-pages'><refentrytitle>ppoll</refentrytitle><manvolnum>3</manvolnum></citerefentry>, to wait for I/O on + the bus connection. If the <parameter>timeout_sec</parameter> parameter is specified, the call will block at most + for the specified amount of time in µs. Pass <constant>UINT64_MAX</constant> to permit it to sleep + indefinitely.</para> + + <para>After each invocation of <function>sd_bus_wait()</function> the <function>sd_bus_process()</function> call + should be invoked in order to process any now pending I/O work.</para> + + <para>Note that <function>sd_bus_wait()</function> is suitable only for simple programs as it does not permit + waiting for other I/O events. For more complex programs either connect the bus connection object to an external + event loop using <citerefentry><refentrytitle>sd_bus_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry> + or to an <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry> event loop + using + <citerefentry><refentrytitle>sd_bus_attach_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>If any I/O was seen, a positive value is returned, zero otherwise. If an error occurs, a negative + <varname>errno</varname>-style error code is returned.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>An invalid bus object was passed.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ECHILD</constant></term> + + <listitem><para>The bus connection was allocated in a parent process and is being reused in a child process + after <function>fork()</function>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOTCONN</constant></term> + + <listitem><para>The bus connection has been terminated already.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_process</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_attach_event</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_event_add_child.xml b/man/sd_event_add_child.xml index 770072f776..c1b38f84b8 100644 --- a/man/sd_event_add_child.xml +++ b/man/sd_event_add_child.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/sd_event_add_defer.xml b/man/sd_event_add_defer.xml index d259b2e39d..82ddce6654 100644 --- a/man/sd_event_add_defer.xml +++ b/man/sd_event_add_defer.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/sd_event_add_inotify.xml b/man/sd_event_add_inotify.xml index 605863c356..65765ea3ce 100644 --- a/man/sd_event_add_inotify.xml +++ b/man/sd_event_add_inotify.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/sd_event_add_io.xml b/man/sd_event_add_io.xml index b4104a07be..6b3da2b9bb 100644 --- a/man/sd_event_add_io.xml +++ b/man/sd_event_add_io.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -293,7 +293,7 @@ <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_source_get_pending</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/sd_event_add_signal.xml b/man/sd_event_add_signal.xml index 5bf7a28083..8f03d059f1 100644 --- a/man/sd_event_add_signal.xml +++ b/man/sd_event_add_signal.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/sd_event_add_time.xml b/man/sd_event_add_time.xml index e139195b8e..e6dbd15a68 100644 --- a/man/sd_event_add_time.xml +++ b/man/sd_event_add_time.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/sd_event_exit.xml b/man/sd_event_exit.xml index 801674c675..2af275b2be 100644 --- a/man/sd_event_exit.xml +++ b/man/sd_event_exit.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/sd_event_get_fd.xml b/man/sd_event_get_fd.xml index 890a74333f..5f66fbcff7 100644 --- a/man/sd_event_get_fd.xml +++ b/man/sd_event_get_fd.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -108,7 +108,7 @@ <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/sd_event_new.xml b/man/sd_event_new.xml index 61cf3d84bf..ddb8dac5a5 100644 --- a/man/sd_event_new.xml +++ b/man/sd_event_new.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -100,11 +100,13 @@ <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry> - or + <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry> or + <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>, and then execute the event loop using - <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + <citerefentry><refentrytitle>sd_event_loop</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> <para><function>sd_event_ref()</function> increases the reference count of the specified event loop object by one.</para> @@ -211,9 +213,8 @@ <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>gettid</refentrytitle><manvolnum>2</manvolnum></citerefentry> </para> diff --git a/man/sd_event_now.xml b/man/sd_event_now.xml index 91a5a4e7c7..1c8afb270a 100644 --- a/man/sd_event_now.xml +++ b/man/sd_event_now.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/sd_event_run.xml b/man/sd_event_run.xml index a2611f58f3..1a4467357a 100644 --- a/man/sd_event_run.xml +++ b/man/sd_event_run.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -149,17 +149,18 @@ <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <ulink url="https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html">GLib Main Event Loop</ulink>. + <ulink url="https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html">GLib Main Event Loop</ulink> </para> </refsect1> diff --git a/man/sd_event_set_watchdog.xml b/man/sd_event_set_watchdog.xml index e8229a4f96..7d7155db3b 100644 --- a/man/sd_event_set_watchdog.xml +++ b/man/sd_event_set_watchdog.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -141,9 +141,8 @@ <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> diff --git a/man/sd_event_source_get_event.xml b/man/sd_event_source_get_event.xml index 1a2792c637..36e6c1bb94 100644 --- a/man/sd_event_source_get_event.xml +++ b/man/sd_event_source_get_event.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -66,8 +66,9 @@ <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> diff --git a/man/sd_event_source_get_pending.xml b/man/sd_event_source_get_pending.xml index 500fa84d5e..75f26907d5 100644 --- a/man/sd_event_source_get_pending.xml +++ b/man/sd_event_source_get_pending.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -133,8 +133,9 @@ <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> diff --git a/man/sd_event_source_set_description.xml b/man/sd_event_source_set_description.xml index 054bf2091f..be3df3ffaa 100644 --- a/man/sd_event_source_set_description.xml +++ b/man/sd_event_source_set_description.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -136,8 +136,9 @@ <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> diff --git a/man/sd_event_source_set_destroy_callback.xml b/man/sd_event_source_set_destroy_callback.xml index 34f7652c86..d9afb4df28 100644 --- a/man/sd_event_source_set_destroy_callback.xml +++ b/man/sd_event_source_set_destroy_callback.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/sd_event_source_set_enabled.xml b/man/sd_event_source_set_enabled.xml index 0fcfefa1cc..73f01848d5 100644 --- a/man/sd_event_source_set_enabled.xml +++ b/man/sd_event_source_set_enabled.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -74,8 +74,10 @@ <para><function>sd_event_source_get_enabled()</function> may be used to query whether the event source object <parameter>source</parameter> is currently enabled or not. It - returns the enablement state in - <parameter>enabled</parameter>.</para> + returns the enablement state (one of <constant>SD_EVENT_ON</constant>, + <constant>SD_EVENT_OFF</constant>, <constant>SD_EVENT_ONESHOT</constant>) + in <parameter>enabled</parameter>, if it is not <constant>NULL</constant>. + It also returns true if the event source is not disabled.</para> <para>Event source objects are enabled when they are first created with calls such as @@ -100,10 +102,10 @@ <refsect1> <title>Return Value</title> - <para>On success, <function>sd_event_source_set_enabled()</function> and - <function>sd_event_source_get_enabled()</function> return a - non-negative integer. On failure, they return a negative - errno-style error code.</para> + <para>On success, <function>sd_event_source_set_enabled()</function> returns a non-negative + integer. <function>sd_event_source_get_enabled()</function> returns zero if the source is + disabled (<constant>SD_EVENT_OFF</constant>) and a positive integer otherwise. On failure, they + return a negative errno-style error code.</para> </refsect1> <refsect1> @@ -145,8 +147,9 @@ <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> diff --git a/man/sd_event_source_set_prepare.xml b/man/sd_event_source_set_prepare.xml index 8c7925a3c3..ae71f74f5d 100644 --- a/man/sd_event_source_set_prepare.xml +++ b/man/sd_event_source_set_prepare.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -136,8 +136,9 @@ <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>, diff --git a/man/sd_event_source_set_priority.xml b/man/sd_event_source_set_priority.xml index 5b8924a0f0..dd16628649 100644 --- a/man/sd_event_source_set_priority.xml +++ b/man/sd_event_source_set_priority.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -162,8 +162,9 @@ <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/sd_event_source_set_userdata.xml b/man/sd_event_source_set_userdata.xml index 3bc5317ae7..e013282561 100644 --- a/man/sd_event_source_set_userdata.xml +++ b/man/sd_event_source_set_userdata.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -85,8 +85,9 @@ <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> diff --git a/man/sd_event_source_unref.xml b/man/sd_event_source_unref.xml index d1b83c57aa..b11df3f7b5 100644 --- a/man/sd_event_source_unref.xml +++ b/man/sd_event_source_unref.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -108,8 +108,9 @@ <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> diff --git a/man/sd_event_wait.xml b/man/sd_event_wait.xml index 6c0dfa7440..884996291c 100644 --- a/man/sd_event_wait.xml +++ b/man/sd_event_wait.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -320,9 +320,9 @@ <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_source_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry> diff --git a/man/sd_id128_get_machine.xml b/man/sd_id128_get_machine.xml index 954fd2e6a7..0884838324 100644 --- a/man/sd_id128_get_machine.xml +++ b/man/sd_id128_get_machine.xml @@ -22,6 +22,7 @@ <refname>sd_id128_get_machine</refname> <refname>sd_id128_get_machine_app_specific</refname> <refname>sd_id128_get_boot</refname> + <refname>sd_id128_get_boot_app_specific</refname> <refname>sd_id128_get_invocation</refname> <refpurpose>Retrieve 128-bit IDs</refpurpose> </refnamediv> @@ -47,6 +48,12 @@ </funcprototype> <funcprototype> + <funcdef>int <function>sd_id128_get_boot_app_specific</function></funcdef> + <paramdef>sd_id128_t <parameter>app_id</parameter></paramdef> + <paramdef>sd_id128_t *<parameter>ret</parameter></paramdef> + </funcprototype> + + <funcprototype> <funcdef>int <function>sd_id128_get_invocation</function></funcdef> <paramdef>sd_id128_t *<parameter>ret</parameter></paramdef> </funcprototype> @@ -69,19 +76,25 @@ <function>sd_id128_get_machine()</function>, but retrieves a machine ID that is specific to the application that is identified by the indicated application ID. It is recommended to use this function instead of <function>sd_id128_get_machine()</function> when passing an ID to untrusted environments, in order to make sure - that the original machine ID may not be determined externally. The application-specific ID should be generated via - a tool like <command>journalctl --new-id128</command>, and may be compiled into the application. This function will - return the same application-specific ID for each combination of machine ID and application ID. Internally, this - function calculates HMAC-SHA256 of the application ID, keyed by the machine ID.</para> - - <para><function>sd_id128_get_boot()</function> returns the boot ID - of the executing kernel. This reads and parses the - <filename>/proc/sys/kernel/random/boot_id</filename> file exposed - by the kernel. It is randomly generated early at boot and is - unique for every running kernel instance. See - <citerefentry project='man-pages'><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> - for more information. This function also internally caches the - returned ID to make this call a cheap operation.</para> + that the original machine ID may not be determined externally. This way, the ID used by the application remains + stable on a given machine, but cannot be easily correlated with IDs used in other applications on the same + machine. The application-specific ID should be generated via a tool like <command>systemd-id128 new</command>, + and may be compiled into the application. This function will return the same application-specific ID for each + combination of machine ID and application ID. Internally, this function calculates HMAC-SHA256 of the application + ID, keyed by the machine ID.</para> + + <para><function>sd_id128_get_boot()</function> returns the boot ID of the executing kernel. This reads and parses + the <filename>/proc/sys/kernel/random/boot_id</filename> file exposed by the kernel. It is randomly generated early + at boot and is unique for every running kernel instance. See <citerefentry + project='man-pages'><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more + information. This function also internally caches the returned ID to make this call a cheap operation. It is + recommended to use this ID as-is only in trusted environments. In untrusted environments it is recommended to + derive an application specific ID using <function>sd_id128_get_machine_app_specific()</function>, see below.</para> + + <para><function>sd_id128_get_boot_app_specific()</function> is analogous to + <function>sd_id128_get_machine_app_specific()</function> but returns an ID that changes between boots. Some + machines may be used for a long time without rebooting, hence the boot ID may remain constant for a long time, and + has properties similar to the machine ID during that time.</para> <para><function>sd_id128_get_invocation()</function> returns the invocation ID of the currently executed service. In its current implementation, this reads and parses the <varname>$INVOCATION_ID</varname> environment @@ -89,10 +102,11 @@ <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. The ID is cached internally. In future a different mechanism to determine the invocation ID may be added.</para> - <para>Note that <function>sd_id128_get_machine_app_specific()</function>, <function>sd_id128_get_boot()</function> - and <function>sd_id128_get_invocation()</function> always return UUID v4 compatible IDs. - <function>sd_id128_get_machine()</function> will also return a UUID v4-compatible ID on new installations but might - not on older. It is possible to convert the machine ID into a UUID v4-compatible one. For more information, see + <para>Note that <function>sd_id128_get_machine_app_specific()</function>, <function>sd_id128_get_boot()</function>, + <function>sd_id128_get_boot_app_specific()</function>, and <function>sd_id128_get_invocation()</function> always + return UUID v4 compatible IDs. <function>sd_id128_get_machine()</function> will also return a UUID v4-compatible + ID on new installations but might not on older. It is possible to convert the machine ID into a UUID v4-compatible + one. For more information, see <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> <para>For more information about the <literal>sd_id128_t</literal> @@ -104,10 +118,12 @@ <title>Return Value</title> <para>Those calls return 0 on success (in which case <parameter>ret</parameter> is filled in), - or a negative errno-style error code. In particular, <function>sd_id128_get_machine()</function> - and <function>sd_id128_get_machine_app_specific()</function> return <constant>-ENOENT</constant> - if <filename>/etc/machine-id</filename> is missing, and <constant>-ENOMEDIUM</constant> if is - empty or all zeros.</para> + or a negative errno-style error code. In particular, + <function>sd_id128_get_machine()</function>, + <function>sd_id128_get_machine_app_specific()</function>, and + <function>sd_id128_get_boot_app_specific()</function> return <constant>-ENOENT</constant> if + <filename>/etc/machine-id</filename> is missing, and <constant>-ENOMEDIUM</constant> if is empty + or all zeros.</para> </refsect1> <xi:include href="libsystemd-pkgconfig.xml" /> @@ -118,19 +134,22 @@ <example> <title>Application-specific machine ID</title> - <para>Here's a simple example for an application specific machine ID:</para> + <para>First, generate the application ID:</para> + <programlisting>$ systemd-id128 -p new +As string: +c273277323db454ea63bb96e79b53e97 + +As UUID: +c2732773-23db-454e-a63b-b96e79b53e97 - <programlisting>#include <systemd/sd-id128.h> -#include <stdio.h> +As man:sd-id128(3) macro: +#define MESSAGE_XYZ SD_ID128_MAKE(c2,73,27,73,23,db,45,4e,a6,3b,b9,6e,79,b5,3e,97) +... +</programlisting> -#define OUR_APPLICATION_ID SD_ID128_MAKE(c2,73,27,73,23,db,45,4e,a6,3b,b9,6e,79,b5,3e,97) + <para>Then use the new identifier in an example application:</para> -int main(int argc, char *argv[]) { - sd_id128_t id; - sd_id128_get_machine_app_specific(OUR_APPLICATION_ID, &id); - printf("Our application ID: " SD_ID128_FORMAT_STR "\n", SD_ID128_FORMAT_VAL(id)); - return 0; -}</programlisting> + <programlisting><xi:include href="id128-app-specific.c" parse="text" /></programlisting> </example> </refsect1> @@ -139,6 +158,7 @@ int main(int argc, char *argv[]) { <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-id128</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, diff --git a/man/sd_id128_randomize.xml b/man/sd_id128_randomize.xml index 4f7cd71398..4f5b160bd9 100644 --- a/man/sd_id128_randomize.xml +++ b/man/sd_id128_randomize.xml @@ -52,9 +52,9 @@ type, see <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - <para><citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s - <option>--new-id128</option> option may be used as a command line - front-end for <function>sd_id128_randomize()</function>.</para> + <para><citerefentry><refentrytitle>systemd-id128</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s + <command>new</command> command may be used as a command line front-end for + <function>sd_id128_randomize()</function>.</para> </refsect1> <refsect1> diff --git a/man/sd_journal_enumerate_fields.xml b/man/sd_journal_enumerate_fields.xml index 95af2c1ee0..c5704f53ad 100644 --- a/man/sd_journal_enumerate_fields.xml +++ b/man/sd_journal_enumerate_fields.xml @@ -86,8 +86,7 @@ <refsect1> <title>Notes</title> - <para>All functions listed here are thread-agnostic and only a single thread may operate - on a given <structname>sd_journal</structname> object.</para> + <xi:include href="threads-aware.xml" xpointer="strict" /> <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> </refsect1> diff --git a/man/sd_journal_get_catalog.xml b/man/sd_journal_get_catalog.xml index ce37e177bd..80edc08c81 100644 --- a/man/sd_journal_get_catalog.xml +++ b/man/sd_journal_get_catalog.xml @@ -87,9 +87,14 @@ <refsect1> <title>Notes</title> - <para>Function <function>sd_journal_get_catalog()</function> is thread-agnostic and only a - single thread may operate on a given <structname>sd_journal</structname> object. Function - <function>sd_journal_get_catalog_for_message_id()</function> is thread-safe.</para> + <para>Function <function>sd_journal_get_catalog()</function> is thread-agnostic and only + a single specific thread may operate on a given object during its entire lifetime. It's safe to allocate multiple + independent objects and use each from a specific thread in parallel. However, it's not safe to allocate such an + object in one thread, and operate or free it from any other, even if locking is used to ensure these threads don't + operate on it at the very same time.</para> + + <para>Function <function>sd_journal_get_catalog_for_message_id()</function> is are thread-safe and may be called in + parallel from multiple threads.</para> <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> </refsect1> diff --git a/man/sd_journal_get_cursor.xml b/man/sd_journal_get_cursor.xml index 6817a3cd54..d5e465b81a 100644 --- a/man/sd_journal_get_cursor.xml +++ b/man/sd_journal_get_cursor.xml @@ -98,8 +98,7 @@ <refsect1> <title>Notes</title> - <para>All functions listed here are thread-agnostic and only a single thread may operate - on a given <structname>sd_journal</structname> object.</para> + <xi:include href="threads-aware.xml" xpointer="strict" /> <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> </refsect1> diff --git a/man/sd_journal_get_cutoff_realtime_usec.xml b/man/sd_journal_get_cutoff_realtime_usec.xml index dc8e32bf81..b2a0634f7d 100644 --- a/man/sd_journal_get_cutoff_realtime_usec.xml +++ b/man/sd_journal_get_cutoff_realtime_usec.xml @@ -96,8 +96,7 @@ <refsect1> <title>Notes</title> - <para>All functions listed here are thread-agnostic and only a single thread may operate - on a given <structname>sd_journal</structname> object.</para> + <xi:include href="threads-aware.xml" xpointer="strict" /> <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> </refsect1> diff --git a/man/sd_journal_get_data.xml b/man/sd_journal_get_data.xml index 99f9500441..464fd16ace 100644 --- a/man/sd_journal_get_data.xml +++ b/man/sd_journal_get_data.xml @@ -156,7 +156,13 @@ success or a negative errno-style error code.</para> </refsect1> - <xi:include href="libsystemd-pkgconfig.xml" /> + <refsect1> + <title>Notes</title> + + <xi:include href="threads-aware.xml" xpointer="strict"/> + + <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> + </refsect1> <refsect1> <title>Examples</title> diff --git a/man/sd_journal_get_fd.xml b/man/sd_journal_get_fd.xml index 7edbc4bc25..2186b685bf 100644 --- a/man/sd_journal_get_fd.xml +++ b/man/sd_journal_get_fd.xml @@ -226,14 +226,9 @@ else { <refsect1> <title>Notes</title> - <para>The <function>sd_journal_get_fd()</function>, - <function>sd_journal_get_events()</function>, - <function>sd_journal_reliable_fd()</function>, - <function>sd_journal_process()</function> and - <function>sd_journal_wait()</function> interfaces are available as - a shared library, which can be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> + <xi:include href="threads-aware.xml" xpointer="strict"/> + + <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> </refsect1> <refsect1> diff --git a/man/sd_journal_get_realtime_usec.xml b/man/sd_journal_get_realtime_usec.xml index 2030e8372d..e0f5c4d2e9 100644 --- a/man/sd_journal_get_realtime_usec.xml +++ b/man/sd_journal_get_realtime_usec.xml @@ -89,7 +89,13 @@ <function>sd_journal_get_monotonic_usec()</function>.</para> </refsect1> - <xi:include href="libsystemd-pkgconfig.xml" /> + <refsect1> + <title>Notes</title> + + <xi:include href="threads-aware.xml" xpointer="strict"/> + + <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> + </refsect1> <refsect1> <title>See Also</title> diff --git a/man/sd_journal_get_usage.xml b/man/sd_journal_get_usage.xml index 358a62d066..39f53dd5eb 100644 --- a/man/sd_journal_get_usage.xml +++ b/man/sd_journal_get_usage.xml @@ -56,8 +56,7 @@ <refsect1> <title>Notes</title> - <para>All functions listed here are thread-agnostic and only a single thread may operate - on a given <structname>sd_journal</structname> object.</para> + <xi:include href="threads-aware.xml" xpointer="strict"/> <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> </refsect1> diff --git a/man/sd_journal_has_runtime_files.xml b/man/sd_journal_has_runtime_files.xml index b7bbf224d4..44fdc8d186 100644 --- a/man/sd_journal_has_runtime_files.xml +++ b/man/sd_journal_has_runtime_files.xml @@ -66,8 +66,7 @@ <refsect1> <title>Notes</title> - <para>All functions listed here are thread-agnostic and only a single thread may operate - on a given <structname>sd_journal</structname> object.</para> + <xi:include href="threads-aware.xml" xpointer="strict"/> <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> </refsect1> diff --git a/man/sd_journal_next.xml b/man/sd_journal_next.xml index c0ca5a8a14..9a27d1426e 100644 --- a/man/sd_journal_next.xml +++ b/man/sd_journal_next.xml @@ -122,8 +122,7 @@ <refsect1> <title>Notes</title> - <para>All functions listed here are thread-agnostic and only a single thread may operate - on a given <structname>sd_journal</structname> object.</para> + <xi:include href="threads-aware.xml" xpointer="strict"/> <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> </refsect1> diff --git a/man/sd_journal_open.xml b/man/sd_journal_open.xml index 9f600b223f..cf787b7ea1 100644 --- a/man/sd_journal_open.xml +++ b/man/sd_journal_open.xml @@ -6,7 +6,8 @@ SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="sd_journal_open"> +<refentry id="sd_journal_open" + xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_journal_open</title> @@ -184,15 +185,9 @@ <refsect1> <title>Notes</title> - <para>All functions listed here are thread-agnostic and only a single thread may operate - on a given <structname>sd_journal</structname> object.</para> + <xi:include href="threads-aware.xml" xpointer="strict"/> - <para>The <function>sd_journal_open()</function>, - <function>sd_journal_open_directory()</function> and - <function>sd_journal_close()</function> interfaces are available - as a shared library, which can be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> + <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> </refsect1> <refsect1> diff --git a/man/sd_journal_print.xml b/man/sd_journal_print.xml index f8ff7ba093..e18cf88bbc 100644 --- a/man/sd_journal_print.xml +++ b/man/sd_journal_print.xml @@ -177,7 +177,8 @@ sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid( <refsect1> <title>Thread safety</title> - <para>All functions listed here are thread-safe and may be called in parallel from multiple threads.</para> + + <xi:include href="threads-aware.xml" xpointer="safe"/> <para><function>sd_journal_sendv()</function> is "async signal safe" in the meaning of <citerefentry project='man-pages'><refentrytitle>signal-safety</refentrytitle><manvolnum>7</manvolnum></citerefentry>. diff --git a/man/sd_journal_query_unique.xml b/man/sd_journal_query_unique.xml index 0bbc479f22..9adafa1144 100644 --- a/man/sd_journal_query_unique.xml +++ b/man/sd_journal_query_unique.xml @@ -126,8 +126,7 @@ <refsect1> <title>Notes</title> - <para>All functions listed here are thread-agnostic and only a single thread may operate - on a given <structname>sd_journal</structname> object.</para> + <xi:include href="threads-aware.xml" xpointer="strict"/> <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> </refsect1> @@ -140,32 +139,7 @@ following example lists all unit names referenced in the journal:</para> - <programlisting>#include <stdio.h> -#include <string.h> -#include <systemd/sd-journal.h> - -int main(int argc, char *argv[]) { - sd_journal *j; - const void *d; - size_t l; - int r; - - r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY); - if (r < 0) { - fprintf(stderr, "Failed to open journal: %s\n", strerror(-r)); - return 1; - } - r = sd_journal_query_unique(j, "_SYSTEMD_UNIT"); - if (r < 0) { - fprintf(stderr, "Failed to query journal: %s\n", strerror(-r)); - return 1; - } - SD_JOURNAL_FOREACH_UNIQUE(j, d, l) - printf("%.*s\n", (int) l, (const char*) d); - sd_journal_close(j); - return 0; -}</programlisting> - + <programlisting><xi:include href="journal-iterate-unique.c" parse="text" /></programlisting> </refsect1> <refsect1> diff --git a/man/sd_journal_seek_head.xml b/man/sd_journal_seek_head.xml index 86274071f5..da88d241e8 100644 --- a/man/sd_journal_seek_head.xml +++ b/man/sd_journal_seek_head.xml @@ -120,8 +120,7 @@ <refsect1> <title>Notes</title> - <para>All functions listed here are thread-agnostic and only a single thread may operate - on a given <structname>sd_journal</structname> object.</para> + <xi:include href="threads-aware.xml" xpointer="strict"/> <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> </refsect1> diff --git a/man/sd_journal_stream_fd.xml b/man/sd_journal_stream_fd.xml index de76cabb4d..a3ff908652 100644 --- a/man/sd_journal_stream_fd.xml +++ b/man/sd_journal_stream_fd.xml @@ -49,7 +49,7 @@ <para><function>sd_journal_stream_fd()</function> takes a short program identifier string as first argument, which will be written - to the journal as _SYSLOG_IDENTIFIER= field for each log entry + to the journal as SYSLOG_IDENTIFIER= field for each log entry (see <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry> for more information). The second argument shall be the default @@ -92,8 +92,7 @@ <refsect1> <title>Notes</title> - <para>Function <function>sd_journal_stream_fd()</function> is thread-safe and may be called - from multiple threads.</para> + <xi:include href="threads-aware.xml" xpointer="safe"/> <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> </refsect1> diff --git a/man/sd_listen_fds.xml b/man/sd_listen_fds.xml index 6dfe716a2d..3c3d2ff26e 100644 --- a/man/sd_listen_fds.xml +++ b/man/sd_listen_fds.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/sd_login_monitor_new.xml b/man/sd_login_monitor_new.xml index 23f685bb31..d914e51d0d 100644 --- a/man/sd_login_monitor_new.xml +++ b/man/sd_login_monitor_new.xml @@ -115,13 +115,13 @@ code block is left:</para> <programlisting>{ - __attribute__((cleanup(sd_login_monitor_unrefp)) sd_login_monitor *m = NULL; - int r; - … - r = sd_login_monitor_default(&m); - if (r < 0) - fprintf(stderr, "Failed to allocate login monitor object: %s\n", strerror(-r)); - … + __attribute__((cleanup(sd_login_monitor_unrefp)) sd_login_monitor *m = NULL; + int r; + … + r = sd_login_monitor_default(&m); + if (r < 0) + fprintf(stderr, "Failed to allocate login monitor object: %s\n", strerror(-r)); + … }</programlisting> <para><function>sd_login_monitor_flush()</function> may be used to @@ -176,13 +176,13 @@ int msec; sd_login_monitor_get_timeout(m, &t); if (t == (uint64_t) -1) - msec = -1; + msec = -1; else { - struct timespec ts; - uint64_t n; - clock_gettime(CLOCK_MONOTONIC, &ts); - n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000; - msec = t > n ? (int) ((t - n + 999) / 1000) : 0; + struct timespec ts; + uint64_t n; + clock_gettime(CLOCK_MONOTONIC, &ts); + n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000; + msec = t > n ? (int) ((t - n + 999) / 1000) : 0; }</programlisting> <para>The code above does not do any error checking for brevity's diff --git a/man/sd_notify.xml b/man/sd_notify.xml index 5d6ae65701..79ae84bb94 100644 --- a/man/sd_notify.xml +++ b/man/sd_notify.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/sd_pid_get_owner_uid.xml b/man/sd_pid_get_owner_uid.xml index 9229217b0b..f4619b6102 100644 --- a/man/sd_pid_get_owner_uid.xml +++ b/man/sd_pid_get_owner_uid.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/send-unit-files-changed.c b/man/send-unit-files-changed.c new file mode 100644 index 0000000000..aecfbcbed1 --- /dev/null +++ b/man/send-unit-files-changed.c @@ -0,0 +1,16 @@ +#include <systemd/sd-bus.h> +#define _cleanup_(f) __attribute__((cleanup(f))) + +int send_unit_files_changed(sd_bus *bus) { + _cleanup_(sd_bus_message_unrefp) sd_bus_message *message = NULL; + int r; + + r = sd_bus_message_new_signal(bus, &message, + "/org/freedesktop/systemd1", + "org.freedesktop.systemd1.Manager", + "UnitFilesChanged"); + if (r < 0) + return r; + + return sd_bus_send(bus, message, NULL); +} diff --git a/man/standard-conf.xml b/man/standard-conf.xml index e1cb7d31ed..f5c961a0c2 100644 --- a/man/standard-conf.xml +++ b/man/standard-conf.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version="1.0"?> <!DOCTYPE refsection PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> diff --git a/man/standard-options.xml b/man/standard-options.xml index bea92e89fb..51a4faf5d6 100644 --- a/man/standard-options.xml +++ b/man/standard-options.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version="1.0"?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> diff --git a/man/systemctl.xml b/man/systemctl.xml index d95d3726af..b9077c55a1 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ <!ENTITY % entities SYSTEM "custom-entities.ent" > @@ -314,18 +314,13 @@ <term><option>--ignore-inhibitors</option></term> <listitem> - <para>When system shutdown or a sleep state is requested, - ignore inhibitor locks. Applications can establish inhibitor - locks to avoid that certain important operations (such as CD - burning or suchlike) are interrupted by system shutdown or a - sleep state. Any user may take these locks and privileged - users may override these locks. If any locks are taken, - shutdown and sleep state requests will normally fail - (regardless of whether privileged or not) and a list of active locks - is printed. However, if <option>--ignore-inhibitors</option> - is specified, the locks are ignored and not printed, and the - operation attempted anyway, possibly requiring additional - privileges.</para> + <para>When system shutdown or a sleep state is requested, ignore inhibitor locks. Applications can establish + inhibitor locks to avoid that certain important operations (such as CD burning or suchlike) are interrupted + by system shutdown or a sleep state. Any user may take these locks and privileged users may override these + locks. If any locks are taken, shutdown and sleep state requests will normally fail (unless privileged) and a + list of active locks is printed. However, if <option>--ignore-inhibitors</option> is specified, the + established locks are ignored and not shown, and the operation attempted anyway, possibly requiring + additional privileges.</para> </listitem> </varlistentry> @@ -335,8 +330,8 @@ <listitem> <para>Just print what would be done. Currently supported by verbs <command>halt</command>, <command>poweroff</command>, <command>reboot</command>, - <command>kexec</command>, <command>suspend</command>, - <command>hibernate</command>, <command>hybrid-sleep</command>, + <command>kexec</command>, <command>suspend</command>, <command>hibernate</command>, + <command>hybrid-sleep</command>, <command>suspend-then-hibernate</command>, <command>default</command>, <command>rescue</command>, <command>emergency</command>, and <command>exit</command>.</para> </listitem> @@ -377,6 +372,9 @@ Note that this will wait forever if any given unit never terminates (by itself or by getting stopped explicitly); particularly services which use <literal>RemainAfterExit=yes</literal>.</para> + + <para>When used with <command>is-system-running</command>, wait + until the boot process is completed before returning.</para> </listitem> </varlistentry> @@ -557,19 +555,19 @@ <term><option>--runtime</option></term> <listitem> - <para>When used with <command>set-property</command>, make changes only - temporarily, so that they are lost on the next reboot.</para> - - <para>Similarily, when used with <command>enable</command>, <command>mask</command>, - <command>edit</command> and related commands, make temporary changes, which are lost on - the next reboot. Changes are not made in subdirectories of <filename>/etc</filename>, but - in <filename>/run</filename>. The immediate effect is identical, however since the latter + <para>When used with <command>enable</command>, + <command>disable</command>, <command>edit</command>, + (and related commands), make changes only temporarily, so + that they are lost on the next reboot. This will have the + effect that changes are not made in subdirectories of + <filename>/etc</filename> but in <filename>/run</filename>, + with identical immediate effects, however, since the latter is lost on reboot, the changes are lost too.</para> - <para>Note: this option cannot be used with <command>disable</command>, - <command>unmask</command>, <command>preset</command>, or <command>preset-all</command>, - because those operations sometimes need to remove symlinks under <filename>/etc</filename> - to have the desired effect, which would cause a persistent change.</para> + <para>Similarly, when used with + <command>set-property</command>, make changes only + temporarily, so that they are lost on the next + reboot.</para> </listitem> </varlistentry> @@ -592,9 +590,8 @@ <term><option>--lines=</option></term> <listitem> - <para>When used with <command>status</command>, controls the - number of journal lines to show, counting from the most - recent ones. Takes a positive integer argument. Defaults to + <para>When used with <command>status</command>, controls the number of journal lines to show, counting from + the most recent ones. Takes a positive integer argument, or 0 to disable journal output. Defaults to 10.</para> </listitem> </varlistentry> @@ -655,7 +652,7 @@ <variablelist> <varlistentry> - <term><command>list-units <optional><replaceable>PATTERN</replaceable>…</optional></command></term> + <term><command>list-units</command> <optional><replaceable>PATTERN</replaceable>…</optional></term> <listitem> <para>List units that <command>systemd</command> currently has in memory. This includes units that are @@ -673,8 +670,8 @@ boot-efi.mount loaded active mounted /boot/efi systemd-journald.service loaded active running Journal Service systemd-logind.service loaded active running Login Service -● user@1000.service loaded active running User Manager for UID 1000 -… +● user@1000.service loaded failed failed User Manager for UID 1000 + … systemd-tmpfiles-clean.timer loaded active waiting Daily Cleanup of Temporary Directories LOAD = Reflects whether the unit definition was properly loaded. @@ -703,7 +700,7 @@ To show all installed unit files use 'systemctl list-unit-files'. </varlistentry> <varlistentry> - <term><command>list-sockets <optional><replaceable>PATTERN</replaceable>…</optional></command></term> + <term><command>list-sockets</command> <optional><replaceable>PATTERN</replaceable>…</optional></term> <listitem> <para>List socket units currently in memory, ordered by listening address. If one or more @@ -726,7 +723,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service </varlistentry> <varlistentry> - <term><command>list-timers <optional><replaceable>PATTERN</replaceable>…</optional></command></term> + <term><command>list-timers</command> <optional><replaceable>PATTERN</replaceable>…</optional></term> <listitem> <para>List timer units currently in memory, ordered by the time they elapse next. If one or more @@ -803,7 +800,7 @@ Sun 2017-02-26 20:57:49 EST 2h 3min left Sun 2017-02-26 11:56:36 EST 6h ago <para>Note that restarting a unit with this command does not necessarily flush out all of the unit's resources before it is started again. For example, the per-service file descriptor storage facility (see - <varname>FileDescriptoreStoreMax=</varname> in + <varname>FileDescriptorStoreMax=</varname> in <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>) will remain intact as long as the unit has a job pending, and is only cleared when the unit is fully stopped and no jobs are pending anymore. If it is intended that the file descriptor store is flushed out, too, during a @@ -1061,6 +1058,12 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err terminating abnormally or timing out), it will automatically enter the <literal>failed</literal> state and its exit code and status is recorded for introspection by the administrator until the service is stopped/re-started or reset with this command.</para> + + <para>In addition to resetting the <literal>failed</literal> state of a unit it also resets various other + per-unit properties: the start rate limit counter of all unit types is reset to zero, as is the restart + counter of service units. Thus, if a unit's start limit (as configured with + <varname>StartLimitIntervalSec=</varname>/<varname>StartLimitBurst=</varname>) is hit and the unit refuses + to be started again, use this command to make it startable again.</para> </listitem> </varlistentry> @@ -1088,6 +1091,10 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err <option>--after</option>, <option>--before</option> may be used to change what types of dependencies are shown.</para> + + <para>Note that this command only lists units currently loaded into memory by the service manager. In + particular, this command is not suitable to get a comprehensive list at all reverse dependencies on a + specific unit, as it won't list the dependencies declared by units currently not loaded.</para> </listitem> </varlistentry> </variablelist> @@ -1098,7 +1105,7 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err <variablelist> <varlistentry> - <term><command>list-unit-files <optional><replaceable>PATTERN…</replaceable></optional></command></term> + <term><command>list-unit-files</command> <optional><replaceable>PATTERN…</replaceable></optional></term> <listitem> <para>List unit files installed on the system, in combination with their enablement state (as reported by @@ -1477,7 +1484,7 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err <variablelist> <varlistentry> - <term><command>list-machines <optional><replaceable>PATTERN</replaceable>…</optional></command></term> + <term><command>list-machines</command> <optional><replaceable>PATTERN</replaceable>…</optional></term> <listitem> <para>List the host and all running local containers with @@ -1641,6 +1648,15 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err output, see the table below. Use <option>--quiet</option> to suppress this output.</para> + <para>Use <option>--wait</option> to wait until the boot + process is completed before printing the current state and + returning the appropriate error status. If <option>--wait</option> + is in use, states <varname>initializing</varname> or + <varname>starting</varname> will not be reported, instead + the command will block until a later state (such as + <varname>running</varname> or <varname>degraded</varname>) + is reached.</para> + <table> <title><command>is-system-running</command> output</title> <tgroup cols='3'> @@ -1779,7 +1795,7 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err </listitem> </varlistentry> <varlistentry> - <term><command>reboot <optional><replaceable>arg</replaceable></optional></command></term> + <term><command>reboot</command> <optional><replaceable>arg</replaceable></optional></term> <listitem> <para>Shut down and reboot the system. This is mostly equivalent to <command>systemctl start reboot.target @@ -1819,7 +1835,7 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err </varlistentry> <varlistentry> - <term><command>exit <optional><replaceable>EXIT_CODE</replaceable></optional></command></term> + <term><command>exit</command> <optional><replaceable>EXIT_CODE</replaceable></optional></term> <listitem> <para>Ask the service manager to quit. This is only supported for user service managers (i.e. in @@ -1833,7 +1849,7 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err </varlistentry> <varlistentry> - <term><command>switch-root <replaceable>ROOT</replaceable> <optional><replaceable>INIT</replaceable></optional></command></term> + <term><command>switch-root</command> <replaceable>ROOT</replaceable> <optional><replaceable>INIT</replaceable></optional></term> <listitem> <para>Switches to a different root directory and executes a new system manager process below it. This is @@ -1877,6 +1893,17 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err sleep operation is successfully enqueued. It will not wait for the sleep/wake-up cycle to complete.</para> </listitem> </varlistentry> + + <varlistentry> + <term><command>suspend-then-hibernate</command></term> + + <listitem> + <para>Suspend the system and hibernate it after the delay specified in <filename>systemd-sleep.conf</filename>. + This will trigger activation of the special target unit <filename>suspend-then-hibernate.target</filename>. + This command is asynchronous, and will return after the hybrid sleep operation is successfully enqueued. + It will not wait for the sleep/wake-up or hibernate/thaw cycle to complete.</para> + </listitem> + </varlistentry> </variablelist> </refsect2> @@ -1933,8 +1960,56 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err <refsect1> <title>Exit status</title> - <para>On success, 0 is returned, a non-zero failure - code otherwise.</para> + <para>On success, 0 is returned, a non-zero failure code otherwise.</para> + + <para><command>systemctl</command> uses the return codes defined by LSB, as defined in + <ulink url="http://refspecs.linuxbase.org/LSB_3.0.0/LSB-PDA/LSB-PDA/iniscrptact.html">LSB 3.0.0</ulink>. + </para> + + <table> + <title>LSB return codes</title> + + <tgroup cols='3'> + <thead> + <row> + <entry>Value</entry> + <entry>Description in LSB</entry> + <entry>Use in systemd</entry> + </row> + </thead> + <tbody> + <row> + <entry><constant>0</constant></entry> + <entry>"program is running or service is OK"</entry> + <entry>unit is active</entry> + </row> + <row> + <entry><constant>1</constant></entry> + <entry>"program is dead and <filename>/var/run</filename> pid file exists"</entry> + <entry>unit <emphasis>not</emphasis> failed (used by <command>is-failed</command>)</entry> + </row> + <row> + <entry><constant>2</constant></entry> + <entry>"program is dead and <filename>/var/lock</filename> lock file exists"</entry> + <entry>unused</entry> + </row> + <row> + <entry><constant>3</constant></entry> + <entry>"program is not running"</entry> + <entry>unit is not active</entry> + </row> + <row> + <entry><constant>4</constant></entry> + <entry>"program or service status is unknown"</entry> + <entry>no such unit</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>The mapping of LSB service states to systemd unit states is imperfect, so it is better to + not rely on those return values but to look for specific unit states and substates instead. + </para> </refsect1> <refsect1> diff --git a/man/systemd-analyze.xml b/man/systemd-analyze.xml index 7aa10fc68e..7becf0133e 100644 --- a/man/systemd-analyze.xml +++ b/man/systemd-analyze.xml @@ -106,6 +106,18 @@ <arg choice="plain">service-watchdogs</arg> <arg choice="opt"><replaceable>BOOL</replaceable></arg> </cmdsynopsis> + <cmdsynopsis> + <command>systemd-analyze</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="plain">timespan</arg> + <arg choice="plain" rep="repeat"><replaceable>SPAN</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis> + <command>systemd-analyze</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="plain">security</arg> + <arg choice="plain" rep="repeat"><replaceable>UNIT</replaceable></arg> + </cmdsynopsis> </refsynopsisdiv> <refsect1> @@ -253,6 +265,33 @@ NAutoVTs=8 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The hardware watchdog is not affected by this setting.</para> + <para><command>systemd-analyze timespan</command> parses a time span and outputs the equivalent value in microseconds, and as a reformatted timespan. + The time span should adhere to the same syntax documented in <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + Values without associated magnitudes are parsed as seconds.</para> + + <para><command>systemd-analyze security</command> analyzes the security and sandboxing settings of one or more + specified service units. If at least one unit name is specified the security settings of the specified service + units are inspected and a detailed analysis is shown. If no unit name is specified, all currently loaded, + long-running service units are inspected and a terse table with results shown. The command checks for various + security-related service settings, assigning each a numeric "exposure level" value, depending on how important a + setting is. It then calculates an overall exposure level for the whole unit, which is an estimation in the range + 0.0…10.0 indicating how exposed a service is security-wise. High exposure levels indicate very little applied + sandboxing. Low exposure levels indicate tight sandboxing and strongest security restrictions. Note that this only + analyzes the per-service security features systemd itself implements. This means that any additional security + mechanisms applied by the service code itself are not accounted for. The exposure level determined this way should + not be misunderstood: a high exposure level neither means that there is no effective sandboxing applied by the + service code itself, nor that the service is actually vulnerable to remote or local attacks. High exposure levels + do indicate however that most likely the service might benefit from additional settings applied to them. Please + note that many of the security and sandboxing settings individually can be circumvented — unless combined with + others. For example, if a service retains the privilege to establish or undo mount points many of the sandboxing + options can be undone by the service code itself. Due to that is essential that each service uses the most + comprehensive and strict sandboxing and security settings possible. The tool will take into account some of these + combinations and relationships between the settings, but not all. Also note that the security and sandboxing + settings analyzed here only apply to the operations executed by the service code itself. If a service has access to + an IPC system (such as D-Bus) it might request operations from other services that are not subject to the same + restrictions. Any comprehensive security and sandboxing analysis is hence incomplete if the IPC access policy is + not validated too.</para> + <para>If no command is passed, <command>systemd-analyze time</command> is implied.</para> diff --git a/man/systemd-ask-password.xml b/man/systemd-ask-password.xml index 7ec76fabf0..2fe3e88d74 100644 --- a/man/systemd-ask-password.xml +++ b/man/systemd-ask-password.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/systemd-bless-boot-generator.xml b/man/systemd-bless-boot-generator.xml new file mode 100644 index 0000000000..980941469e --- /dev/null +++ b/man/systemd-bless-boot-generator.xml @@ -0,0 +1,49 @@ +<?xml version="1.0"?> +<!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- + SPDX-License-Identifier: LGPL-2.1+ +--> +<refentry id="systemd-bless-boot-generator" conditional='ENABLE_EFI'> + + <refentryinfo> + <title>systemd-bless-boot-generator</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-bless-boot-generator</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-bless-boot-generator</refname> + <refpurpose>Pull <filename>systemd-bless-boot.service</filename> into the initial boot transaction when boot counting is in effect.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/usr/lib/systemd/system-generators/systemd-bless-boot-generator</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-bless-boot-generator</filename> is a generator that pulls + <filename>systemd-bless-boot.service</filename> into the initial boot transaction when boot counting, as + implemented by <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>, is + enabled.</para> + + <para><filename>systemd-bless-boot-generator</filename> implements + <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-bless-boot.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-bless-boot.service.xml b/man/systemd-bless-boot.service.xml new file mode 100644 index 0000000000..fb362cef2d --- /dev/null +++ b/man/systemd-bless-boot.service.xml @@ -0,0 +1,115 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + SPDX-License-Identifier: LGPL-2.1+ +--> + +<refentry id="systemd-bless-boot.service" conditional='ENABLE_EFI' + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-bless-boot.service</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-bless-boot.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-bless-boot.service</refname> + <refpurpose>Mark current boot process as successful</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-bless-boot.service</filename></para> + <para><filename>/usr/lib/systemd/system-bless-boot</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-bless-boot.service</filename> is a system service that marks the current boot process as + successful. It's automatically pulled into the initial transaction when + <citerefentry><refentrytitle>systemd-bless-boot-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + detects that <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> style + boot counting is used.</para> + + <para>Internally, the service operates based on the <varname>LoaderBootCountPath</varname> EFI variable (of the + vendor UUID <constant>4a67b082-0a4c-41cf-b6c7-440b29bb8c4</constant>), which is passed from the boot loader to the + OS. It contains a file system path (relative to the EFI system partition) of the <ulink + url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink> compliant boot loader entry + file or unified kernel image file that was used to boot up the + system. <command>systemd-bless-boot.service</command> removes the two 'tries done' and 'tries left' numeric boot + counters from the filename, which indicates to future invocations of the boot loader that the entry has completed + booting successfully at least once. (This service will hence rename the boot loader entry file or unified kernel + image file on the first successful boot.)</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The <filename>/usr/lib/systemd/system-bless-boot</filename> executable may also be invoked from the + command line, taking one of the following command arguments:</para> + + <variablelist> + <varlistentry> + <term><option>status</option></term> + + <listitem><para>The current status of the boot loader entry file or unified kernel image file is shown. This + outputs one of <literal>good</literal>, <literal>bad</literal>, <literal>indeterminate</literal>, + <literal>clean</literal>, depending on the state and previous invocations of the command. The string + <literal>indeterminate</literal> is shown initially after boot, before it has been marked as "good" or + "bad". The string <literal>good</literal> is shown after the boot was marked as "good" with the + <option>good</option> command below, and "bad" conversely after the <option>bad</option> command was + invoked. The string <literal>clean</literal> is returned when boot counting is currently not in effect.</para> + + <para>This command is implied if no command argument is specified.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>good</option></term> + + <listitem><para>When invoked, the current boot loader entry file or unified kernel image file will be marked as + "good", executing the file rename operation described above. This command is intended to be invoked at the end + of a successful boot. The <filename>systemd-bless-boot.service</filename> unit invokes this + command.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>bad</option></term> + + <listitem><para>When called the 'tries left' counter in the boot loader entry file name or unified kernel image + file name is set to zero, marking the boot loader entry or kernel image as "bad", so that the boot loader won't + consider it anymore on future boots (at least as long as there are other entries available that are not marked + "bad" yet). This command is normally not executed, but can be used to instantly put an end to the boot counting + logic if a problem is detected and persistently mark the boot entry as bad.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>indeterminate</option></term> + + <listitem><para>This command undoes any marking of the current boot loader entry file or unified kernel image + file as good or bad. This is implemented by renaming the boot loader entry file or unified kernel image file + back to the path encoded in the <varname>LoaderBootCountPath</varname> EFI variable.</para></listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-boot-check-no-failures.service.xml b/man/systemd-boot-check-no-failures.service.xml new file mode 100644 index 0000000000..55c2adffdb --- /dev/null +++ b/man/systemd-boot-check-no-failures.service.xml @@ -0,0 +1,54 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + SPDX-License-Identifier: LGPL-2.1+ +--> + +<refentry id="systemd-boot-check-no-failures.service" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-boot-check-no-failures.service</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-boot-check-no-failures.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-boot-check-no-failures.service</refname> + <refpurpose>verify that the system booted up cleanly</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-boot-check-no-failures.service</filename></para> + <para><filename>/usr/lib/systemd/system-boot-check-no-failures</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-boot-check-no-failures.service</filename> is a system service that checks whether the + system booted up successfully. This service implements a very minimal test only: whether there are any failed units on + the system. This service is disabled by default. When enabled, it is ordered before + <filename>boot-complete.target</filename>, thus ensuring the target cannot be reached when the system booted up + with failed services.</para> + + <para>Note that due the simple nature of this check this service is probably not suitable for deployment in most + scenarios. It is primarily useful only as example for developing more fine-grained checks to order before + <filename>boot-complete.target</filename>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-boot.xml b/man/systemd-boot.xml index 9fadffadfe..44b0f61f22 100644 --- a/man/systemd-boot.xml +++ b/man/systemd-boot.xml @@ -38,13 +38,13 @@ <itemizedlist> <listitem><para>Boot entries defined with <ulink - url="https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md">Boot Loader + url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink> description files located in <filename>/loader/entries/</filename> on the ESP. These usually describe Linux kernel images with associated initrd images, but alternatively may also describe arbitrary other EFI executables.</para></listitem> <listitem><para>Unified kernel images following the <ulink - url="https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md">Boot Loader + url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>, as executable EFI binaries in <filename>/EFI/Linux/</filename> on the ESP. </para></listitem> @@ -63,9 +63,8 @@ used from a running system to locate the ESP, list available entries, and install systemd-boot itself.</para> <para>systemd-boot will provide information about the time spent in UEFI firmware using the <ulink - url="https://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface">Boot Loader Interface</ulink>. This - information can be displayed using - <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>. This information can be displayed + using <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>. </para> </refsect1> @@ -75,67 +74,67 @@ <variablelist> <varlistentry> - <term>↑ (Up)</term> - <term>↓ (Down)</term> - <term>j</term> - <term>k</term> - <term>PageUp</term> - <term>PageDown</term> - <term>Home</term> - <term>End</term> + <term><keycap>↑</keycap> (Up)</term> + <term><keycap>↓</keycap> (Down)</term> + <term><keycap>j</keycap></term> + <term><keycap>k</keycap></term> + <term><keycap>PageUp</keycap></term> + <term><keycap>PageDown</keycap></term> + <term><keycap>Home</keycap></term> + <term><keycap>End</keycap></term> <listitem><para>Navigate up/down in the entry list</para></listitem> </varlistentry> <varlistentry> - <term>↵ (Enter)</term> + <term><keycap>↵</keycap> (Enter)</term> <listitem><para>Boot selected entry</para></listitem> </varlistentry> <varlistentry> - <term>d</term> + <term><keycap>d</keycap></term> <listitem><para>Make selected entry the default</para></listitem> </varlistentry> <varlistentry> - <term>e</term> + <term><keycap>e</keycap></term> <listitem><para>Edit the kernel command line for selected entry</para></listitem> </varlistentry> <varlistentry> - <term>+</term> - <term>t</term> + <term><keycap>+</keycap></term> + <term><keycap>t</keycap></term> <listitem><para>Increase the timeout before default entry is booted</para></listitem> </varlistentry> <varlistentry> - <term>-</term> - <term>T</term> + <term><keycap>-</keycap></term> + <term><keycap>T</keycap></term> <listitem><para>Decrease the timeout</para></listitem> </varlistentry> <varlistentry> - <term>v</term> + <term><keycap>v</keycap></term> <listitem><para>Show systemd-boot, UEFI, and firmware versions</para></listitem> </varlistentry> <varlistentry> - <term>P</term> + <term><keycap>P</keycap></term> <listitem><para>Print status</para></listitem> </varlistentry> <varlistentry> - <term>Q</term> + <term><keycap>Q</keycap></term> <listitem><para>Quit</para></listitem> </varlistentry> <varlistentry> - <term>h</term> - <term>?</term> + <term><keycap>h</keycap></term> + <term><keycap>?</keycap></term> <listitem><para>Show a help screen</para></listitem> </varlistentry> <varlistentry> - <term>Ctrl + l</term> + <term><keycombo><keycap>Ctrl</keycap><keycap>l</keycap></keycombo></term> <listitem><para>Reprint the screen</para></listitem> </varlistentry> </variablelist> @@ -145,35 +144,35 @@ <variablelist> <varlistentry> - <term>l</term> + <term><keycap>l</keycap></term> <listitem><para>Linux</para></listitem> </varlistentry> <varlistentry> - <term>w</term> + <term><keycap>w</keycap></term> <listitem><para>Windows</para></listitem> </varlistentry> <varlistentry> - <term>a</term> + <term><keycap>a</keycap></term> <listitem><para>OS X</para></listitem> </varlistentry> <varlistentry> - <term>s</term> + <term><keycap>s</keycap></term> <listitem><para>EFI shell</para></listitem> </varlistentry> <varlistentry> - <term>1</term> - <term>2</term> - <term>3</term> - <term>4</term> - <term>5</term> - <term>6</term> - <term>7</term> - <term>8</term> - <term>9</term> + <term><keycap>1</keycap></term> + <term><keycap>2</keycap></term> + <term><keycap>3</keycap></term> + <term><keycap>4</keycap></term> + <term><keycap>5</keycap></term> + <term><keycap>6</keycap></term> + <term><keycap>7</keycap></term> + <term><keycap>8</keycap></term> + <term><keycap>9</keycap></term> <listitem><para>Boot entry number 1 … 9</para></listitem> </varlistentry> </variablelist> @@ -183,36 +182,36 @@ <variablelist> <varlistentry> - <term>← (Left)</term> - <term>→ (Right)</term> - <term>Home</term> - <term>End</term> + <term><keycap>←</keycap> (Left)</term> + <term><keycap>→</keycap> (Right)</term> + <term><keycap>Home</keycap></term> + <term><keycap>End</keycap></term> <listitem><para>Navigate left/right</para></listitem> </varlistentry> <varlistentry> - <term>Esc</term> + <term><keycap>Esc</keycap></term> <listitem><para>Abort the edit and quit the editor</para></listitem> </varlistentry> <varlistentry> - <term>Ctrl + k</term> + <term><keycombo><keycap>Ctrl</keycap><keycap>k</keycap></keycombo></term> <listitem><para>Clear the command line</para></listitem> </varlistentry> <varlistentry> - <term>Ctrl + w</term> - <term>Alt + Backspace</term> + <term><keycombo><keycap>Ctrl</keycap><keycap>w</keycap></keycombo></term> + <term><keycombo><keycap>Alt</keycap><keycap>Backspace</keycap></keycombo></term> <listitem><para>Delete word backwards</para></listitem> </varlistentry> <varlistentry> - <term>Alt + d </term> + <term><keycombo><keycap>Alt</keycap><keycap>d</keycap></keycombo></term> <listitem><para>Delete word forwards</para></listitem> </varlistentry> <varlistentry> - <term>↵ (Enter)</term> + <term><keycap>↵</keycap> (Enter)</term> <listitem><para>Boot entry with the edited command line</para></listitem> </varlistentry> </variablelist> @@ -231,19 +230,187 @@ <filename>/loader/loader.conf</filename> on the ESP (in combination with data read from EFI variables). See <citerefentry><refentrytitle>loader.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Boot entry description files following the <ulink - url="https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md">Boot Loader + url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink> are read from <filename>/loader/entries/</filename> on the ESP. Unified kernel boot entries - following the <ulink url="https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md">Boot + following the <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink> are read from <filename>/EFI/Linux/</filename> on the ESP.</para> </refsect1> <refsect1> + <title>EFI Variables</title> + + <para>The following EFI variables are defined, set and read by <command>systemd-boot</command>, under the vendor + UUID <literal>4a67b082-0a4c-41cf-b6c7-440b29bb8c4</literal>, for communication between the OS and the boot + loader:</para> + + <variablelist> + <varlistentry> + <term><varname>LoaderBootCountPath</varname></term> + <listitem><para>If boot counting is enabled, contains the path to the file in whose name the boot counters are + encoded. Set by the boot + loader. <citerefentry><refentrytitle>systemd-bless-boot.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + uses this information to mark a boot as successful as determined by the successful activation of the + <filename>boot-complete.target</filename> target unit.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>LoaderConfigTimeout</varname></term> + <term><varname>LoaderConfigTimeoutOneShot</varname></term> + <listitem><para>The menu timeout in seconds. Read by the boot loader. <varname>LoaderConfigTimeout</varname> + is maintained persistently, while <varname>LoaderConfigTimeoutOneShot</varname> is a one-time override which is + read once (in which case it takes precedence over <varname>LoaderConfigTimeout</varname>) and then + removed. <varname>LoaderConfigTimeout</varname> may be manipulated with the + <keycap>t</keycap>/<keycap>T</keycap> keys, see above.)</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>LoaderDevicePartUUID</varname></term> + + <listitem><para>Contains the partition UUID of the EFI System Partition the boot loader was run from. Set by + the boot + loader. <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + uses this information to automatically find the disk booted from, in order to discover various other partitions + on the same disk automatically.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>LoaderEntries</varname></term> + + <listitem><para>A list of the identifiers of all discovered boot loader entries. Set by the boot + loader.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>LoaderEntryDefault</varname></term> + <term><varname>LoaderEntryOneShot</varname></term> + + <listitem><para>The identifier of the default boot loader entry. Set primarily by the OS and read by the boot + loader. <varname>LoaderEntryOneShot</varname> sets the default entry for the next boot only, while + <varname>LoaderEntryDefault</varname> sets it persistently for all future + boots. <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s + <option>set-default</option> and <option>set-oneshot</option> commands make use of these variables. The boot + loader modifies <varname>LoaderEntryDefault</varname> on request, when the <keycap>d</keycap> key is used, see + above.)</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>LoaderEntrySelected</varname></term> + + <listitem><para>The identifier of the boot loader entry currently being booted. Set by the boot + loader.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>LoaderFeatures</varname></term> + + <listitem><para>A set of flags indicating the features the boot loader supports. Set by the boot loader. Use + <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> to view this + data.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>LoaderFirmwareInfo</varname></term> + <term><varname>LoaderFirmwareType</varname></term> + + <listitem><para>Brief firmware information. Set by the boot loader. Use + <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> to view this + data.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>LoaderImageIdentifier</varname></term> + + <listitem><para>The path of executable of the boot loader used for the current boot, relative to the EFI System + Partition's root directory. Set by the boot loader. Use + <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> to view this + data.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>LoaderInfo</varname></term> + + <listitem><para>Brief information about the boot loader. Set by the boot loader. Use + <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> to view this + data.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>LoaderTimeExecUSec</varname></term> + <term><varname>LoaderTimeInitUSec</varname></term> + <term><varname>LoaderTimeMenuUsec</varname></term> + + <listitem><para>Information about the time spent in various parts of the boot loader. Set by the boot + loader. Use <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to view this data. These variables are defined by the <ulink + url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Boot Counting</title> + + <para><command>systemd-boot</command> implements a simple boot counting mechanism on top of the <ulink + url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>, for automatic and unattended + fallback to older kernel versions/boot loader entries when a specific entry continously fails. Any boot loader + entry file and unified kernel image file that contains a <literal>+</literal> followed by one or two numbers (if + two they need to be separated by a <literal>-</literal>), before the <filename>.conf</filename> or + <filename>.efi</filename> suffix is subject to boot counting: the first of the two numbers ('tries left') is + decreased by one on every boot attempt, the second of the two numbers ('tries done') is increased by one (if 'tries + done' is absent it is considered equivalent to 0). Depending on the current value of these two counters the boot + entry is considered to be in one of three states:</para> + + <orderedlist> + <listitem><para>If the 'tries left' counter of an entry is greater than zero the entry is considered to be in + 'indeterminate' state. This means the entry has not completed booting successfully yet, but also hasn't been + determined not to work.</para></listitem> + + <listitem><para>If the 'tries left' counter of an entry is zero it is considered to be in 'bad' state. This means + no further attempts to boot this item will be made (that is, unless all other boot entries are also in 'bad' + state), as all attempts to boot this entry have not completed successfully.</para></listitem> + + <listitem><para>If the 'tries left' and 'tries done' counters of an entry are absent it is considered to be in + 'good' state. This means further boot counting for the entry is turned off, as it successfully booted at least + once. The + <citerefentry><refentrytitle>systemd-bless-boot.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + service moves the currently booted entry from 'indeterminate' into 'good' state when a boot attempt completed + successfully.</para></listitem> + </orderedlist> + + <para>Generally, when new entries are added to the boot loader, they first start out in 'indeterminate' state, + i.e. with a 'tries left' counter greater than zero. The boot entry remains in this state until either it managed to + complete a full boot successfully at least once (in which case it will be in 'good' state) — or the 'tries left' + counter reaches zero (in which case it will be in 'bad' state).</para> + + <para>Example: let's say a boot loader entry file <filename>foo.conf</filename> is set up for 3 boot tries. The + installer will hence create it under the name <filename>foo+3.conf</filename>. On first boot, the boot loader will + rename it to <filename>foo+2-1.conf</filename>. If that boot does not complete successfully, the boot loader will + rename it to <filename>foo+1-2.conf</filename> on the following boot. If that fails too, it will finally be renamed + <filename>foo+0-3.conf</filename> by the boot loader on next boot, after which it will be considered 'bad'. If the + boot succeeds however the entry file will be renamed to <filename>foo.conf</filename> by the OS, so that it is + considered 'good' from then on.</para> + + <para>The boot menu takes the 'tries left' counter into account when sorting the menu entries: entries in 'bad' + state are ordered at the end of the list, and entries in 'good' or 'indeterminate' at the beginning. The user can + freely choose to boot any entry of the menu, including those already marked 'bad'. If the menu entry to boot is + automatically determined, this means that 'good' or 'indeterminate' entries are generally preferred (as the top item of + the menu is the one booted by default), and 'bad' entries will only be considered if there are no 'good' or + 'indeterminate' entries left.</para> + + <para>The <citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry> kernel + install framework optionally sets the initial 'tries left' counter to the value specified in + <filename>/etc/kernel/tries</filename> when a boot loader entry is first created.</para> + </refsect1> + + <refsect1> <title>See Also</title> <para> <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>loader.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <ulink url="https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md">Boot Loader Specification</ulink>, - <ulink url="https://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface">Boot Loader Interface</ulink> + <citerefentry><refentrytitle>systemd-bless-boot.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>, + <ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink> </para> </refsect1> </refentry> diff --git a/man/systemd-cgtop.xml b/man/systemd-cgtop.xml index e5bd7a96e8..32ed66b3f5 100644 --- a/man/systemd-cgtop.xml +++ b/man/systemd-cgtop.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/systemd-coredump.xml b/man/systemd-coredump.xml index e011bf6b8b..b25f0c4f1c 100644 --- a/man/systemd-coredump.xml +++ b/man/systemd-coredump.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/systemd-cryptsetup-generator.xml b/man/systemd-cryptsetup-generator.xml index c37ee76b87..e30d69bfe7 100644 --- a/man/systemd-cryptsetup-generator.xml +++ b/man/systemd-cryptsetup-generator.xml @@ -144,6 +144,20 @@ to the one specified by <varname>rd.luks.key=</varname> or <varname>luks.key=</varname> of the corresponding UUID, or the password file that was specified without a UUID.</para> + + <para>It is also possible to specify an external device which + should be mounted before we attempt to unlock the LUKS device. + systemd-cryptsetup will use password file stored on that + device. Device containing password file is specified by + appending colon and a device identifier to the password file + path. For example, + <varname>rd.luks.uuid=</varname>b40f1abf-2a53-400a-889a-2eccc27eaa40 + <varname>rd.luks.key=</varname>b40f1abf-2a53-400a-889a-2eccc27eaa40=/keyfile:LABEL=keydev. + Hence, in this case, we will attempt to mount file system + residing on the block device with label <literal>keydev</literal>. + This syntax is for now only supported on a per-device basis, + i.e. you have to specify LUKS device UUID.</para> + <para><varname>rd.luks.key=</varname> is honored only by initial RAM disk (initrd) while diff --git a/man/systemd-debug-generator.xml b/man/systemd-debug-generator.xml index d5cf4109b0..fa88e8ac01 100644 --- a/man/systemd-debug-generator.xml +++ b/man/systemd-debug-generator.xml @@ -33,27 +33,38 @@ that reads the kernel command line and understands three options:</para> - <para>If the <option>systemd.mask=</option> option is specified - and followed by a unit name, this unit is masked for the runtime, - similar to the effect of + <para>If the <option>systemd.mask=</option> or <option>rd.systemd.mask=</option> + option is specified and followed by a unit name, this unit is + masked for the runtime, similar to the effect of <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s <command>mask</command> command. This is useful to boot with certain units removed from the initial boot transaction for - debugging system startup. May be specified more than once.</para> + debugging system startup. May be specified more than once. + <option>rd.systemd.mask=</option> is honored only by initial + RAM disk (initrd) while <option>systemd.mask=</option> is + honored only in the main system.</para> - <para>If the <option>systemd.wants=</option> option is specified + <para>If the <option>systemd.wants=</option> or + <option>rd.systemd.wants=</option> option is specified and followed by a unit name, a start job for this unit is added to the initial transaction. This is useful to start one or more - additional units at boot. May be specified more than once.</para> + additional units at boot. May be specified more than once. + <option>rd.systemd.wants=</option> is honored only by initial + RAM disk (initrd) while <option>systemd.wants=</option> is + honored only in the main system.</para> - <para>If the <option>systemd.debug_shell</option> option is + <para>If the <option>systemd.debug_shell</option> or + <option>rd.systemd.debug_shell</option> option is specified, the debug shell service <literal>debug-shell.service</literal> is pulled into the boot transaction. It will spawn a debug shell on tty9 during early system startup. Note that the shell may also be turned on persistently by enabling it with <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s - <command>enable</command> command.</para> + <command>enable</command> command. + <option>rd.systemd.debug_shell=</option> is honored only by initial + RAM disk (initrd) while <option>systemd.debug_shell</option> is + honored only in the main system.</para> <para><filename>systemd-debug-generator</filename> implements <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> diff --git a/man/systemd-escape.xml b/man/systemd-escape.xml index 41014abc73..f61c07ae9d 100644 --- a/man/systemd-escape.xml +++ b/man/systemd-escape.xml @@ -76,9 +76,12 @@ <listitem><para>Inserts the escaped strings in a unit name template. Takes a unit name template such as - <filename>foobar@.service</filename>. May not be used in - conjunction with <option>--suffix=</option>, - <option>--unescape</option> or + <filename>foobar@.service</filename>. With + <option>--unescape</option>, expects instantiated unit names + for this template and extracts and unescapes just the instance + part. May not be used in conjunction with + <option>--suffix=</option>, + <option>--instance</option> or <option>--mangle</option>.</para></listitem> </varlistentry> @@ -100,8 +103,7 @@ <listitem><para>Instead of escaping the specified strings, undo the escaping, reversing the operation. May not be used in - conjunction with <option>--suffix=</option>, - <option>--template=</option> or + conjunction with <option>--suffix=</option> or <option>--mangle</option>.</para></listitem> </varlistentry> @@ -117,6 +119,19 @@ <option>--unescape</option>.</para></listitem> </varlistentry> + <varlistentry> + <term><option>--instance</option></term> + + <listitem><para>With <option>--unescape</option>, unescape + and print only the instance part of an instantiated unit name + template. Results in an error for an uninstantiated template + like <filename>ssh@.service</filename> or a non-template name + like <filename>ssh.service</filename>. + Must be used in conjunction with <option>--unescape</option> + and may not be used in conjunction with + <option>--template</option>.</para></listitem> + </varlistentry> + <xi:include href="standard-options.xml" xpointer="help" /> <xi:include href="standard-options.xml" xpointer="version" /> </variablelist> @@ -141,6 +156,14 @@ tmp-waldi-foobar.mount</programlisting> <para>To generate instance names of three strings:</para> <programlisting>$ systemd-escape --template=systemd-nspawn@.service 'My Container 1' 'containerb' 'container/III' systemd-nspawn@My\x20Container\x201.service systemd-nspawn@containerb.service systemd-nspawn@container-III.service</programlisting> + + <para>To extract the instance part of an instantiated unit:</para> + <programlisting>$ systemd-escape -u --instance 'systemd-nspawn@My\x20Container\x201.service' +My Container 1</programlisting> + + <para>To extract the instance part of an instance of a particular template:</para> + <programlisting>$ systemd-escape -u --template=systemd-nspawn@.service 'systemd-nspawn@My\x20Container\x201.service' +My Container 1</programlisting> </refsect1> <refsect1> diff --git a/man/systemd-hibernate-resume-generator.xml b/man/systemd-hibernate-resume-generator.xml index 86d45dc4af..8f0cc5d044 100644 --- a/man/systemd-hibernate-resume-generator.xml +++ b/man/systemd-hibernate-resume-generator.xml @@ -28,11 +28,13 @@ <refsect1> <title>Description</title> - <para><filename>systemd-hibernate-resume-generator</filename> is a - generator that instantiates + <para><command>systemd-hibernate-resume-generator</command> is a + generator that initiates the procedure to resume the system from hibernation. + It instantiates the <citerefentry><refentrytitle>systemd-hibernate-resume@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> unit according to the value of <option>resume=</option> parameter - specified on the kernel command line.</para> + specified on the kernel command line, which will instruct the kernel + to resume the system from the hibernation image on that device.</para> </refsect1> <refsect1> @@ -54,6 +56,12 @@ supported.</para></listitem> </varlistentry> + <varlistentry> + <term><varname>noresume</varname></term> + + <listitem><para>Do not try to resume from hibernation. If this parameter is + present, <varname>resume=</varname> is ignored.</para></listitem> + </varlistentry> </variablelist> </refsect1> diff --git a/man/systemd-hwdb.xml b/man/systemd-hwdb.xml index 5af868d52b..6c8487a893 100644 --- a/man/systemd-hwdb.xml +++ b/man/systemd-hwdb.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/systemd-id128.xml b/man/systemd-id128.xml new file mode 100644 index 0000000000..8a76cccd86 --- /dev/null +++ b/man/systemd-id128.xml @@ -0,0 +1,122 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1+ --> + +<refentry id="systemd-id128" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-id128</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-id128</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-id128</refname> + <refpurpose>Generate and print sd-128 identifiers</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-id128</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="plain">new</arg> + </cmdsynopsis> + + <cmdsynopsis> + <command>systemd-id128</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="plain">machine-id</arg> + </cmdsynopsis> + + <cmdsynopsis> + <command>systemd-id128</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="plain">boot-id</arg> + </cmdsynopsis> + + <cmdsynopsis> + <command>systemd-id128</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="plain">invocation-id</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>id128</command> may be used to conveniently print + <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry> + UUIDs. What identifier is printed depends on the specific verb.</para> + + <para>With <command>new</command>, a new random identifier will be generated.</para> + + <para>With <command>machine-id</command>, the identifier of the current machine will be + printed. See + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para> + + <para>With <command>boot-id</command>, the identifier of the current boot will be + printed.</para> + + <para>Both <command>machine-id</command> and <command>boot-id</command> may be combined + with the <option>--app-specific=<replaceable>app-id</replaceable></option> switch to + generate application-specific IDs. See + <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for the discussion when this is useful.</para> + + <para>With <command>invocation-id</command>, the identifier of the current service invocation + will be printed. This is available in systemd services. See + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>-p</option></term> + <term><option>--pretty</option></term> + + <listitem><para>Generate output as programming language snippets.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-a <replaceable>app-id</replaceable></option></term> + <term><option>--app-specific=<replaceable>app-id</replaceable></option></term> + + <listitem><para>With this option, an identifier that is the result of hashing the + application identifier <replaceable>app-id</replaceable> and the machine identifier will be + printed. The <replaceable>app-id</replaceable> argument must be a valid sd-id128 string + identifying the application.</para> + </listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + </variablelist> + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success, 0 is returned, a non-zero failure code otherwise.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-inhibit.xml b/man/systemd-inhibit.xml index 03dc06678a..3fa5acf550 100644 --- a/man/systemd-inhibit.xml +++ b/man/systemd-inhibit.xml @@ -119,6 +119,7 @@ </varlistentry> <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" /> <xi:include href="standard-options.xml" xpointer="version" /> </variablelist> diff --git a/man/systemd-journal-gatewayd.service.xml b/man/systemd-journal-gatewayd.service.xml index 794bc10a7b..13604a041b 100644 --- a/man/systemd-journal-gatewayd.service.xml +++ b/man/systemd-journal-gatewayd.service.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/systemd-journal-remote.service.xml b/man/systemd-journal-remote.service.xml index f2bfc36668..6e6819be04 100644 --- a/man/systemd-journal-remote.service.xml +++ b/man/systemd-journal-remote.service.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ <!ENTITY % entities SYSTEM "custom-entities.ent" > diff --git a/man/systemd-journal-upload.service.xml b/man/systemd-journal-upload.service.xml index 38fc010ab6..cdeadddda8 100644 --- a/man/systemd-journal-upload.service.xml +++ b/man/systemd-journal-upload.service.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ <!ENTITY % entities SYSTEM "custom-entities.ent" > diff --git a/man/systemd-journald.service.xml b/man/systemd-journald.service.xml index 6d0aaa4587..9167993012 100644 --- a/man/systemd-journald.service.xml +++ b/man/systemd-journald.service.xml @@ -52,7 +52,7 @@ <listitem><para>Structured system log messages via the native Journal API, see - <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>4</manvolnum></citerefentry></para></listitem> + <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry></para></listitem> <listitem><para>Standard output and standard error of service units. For further details see below.</para></listitem> @@ -206,10 +206,10 @@ systemd-tmpfiles --create --prefix /var/log/journal</programlisting> <para>Journal files are, by default, owned and readable by the <literal>systemd-journal</literal> system group but are not - writable. Adding a user to this group thus enables her/him to read + writable. Adding a user to this group thus enables them to read the journal files.</para> - <para>By default, each logged in user will get her/his own set of + <para>By default, each logged in user will get their own set of journal files in <filename>/var/log/journal/</filename>. These files will not be owned by the user, however, in order to avoid that the user can write to them directly. Instead, file system @@ -303,7 +303,7 @@ systemd-tmpfiles --create --prefix /var/log/journal</programlisting> <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry project='die-net'><refentrytitle>setfacl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>4</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <command>pydoc systemd.journal</command> </para> </refsect1> diff --git a/man/systemd-logind.service.xml b/man/systemd-logind.service.xml index 33ed8f522e..1c29b33776 100644 --- a/man/systemd-logind.service.xml +++ b/man/systemd-logind.service.xml @@ -45,8 +45,10 @@ a session, then this ID is reused as the session ID. Otherwise, an independent session counter is used.</para></listitem> - <listitem><para>Providing PolicyKit-based access for users for - operations such as system shutdown or sleep</para></listitem> + <listitem><para>Providing <ulink + url="http://www.freedesktop.org/wiki/Software/polkit">polkit</ulink>-based + access for users for operations such as system shutdown or sleep</para> + </listitem> <listitem><para>Implementing a shutdown/sleep inhibition logic for applications</para></listitem> diff --git a/man/systemd-machine-id-setup.xml b/man/systemd-machine-id-setup.xml index 9e84fd8ccb..aea13caab9 100644 --- a/man/systemd-machine-id-setup.xml +++ b/man/systemd-machine-id-setup.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/systemd-mount.xml b/man/systemd-mount.xml index c75e572026..610c97f948 100644 --- a/man/systemd-mount.xml +++ b/man/systemd-mount.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -114,7 +114,7 @@ the command line. If passed, additional metadata is read from the device to enhance the unit to create. For example, a descriptive string for the transient units is generated from the file system label and device model. Moreover if a removable block device (e.g. USB stick) is detected an automount unit instead of a regular - mount unit is created, with a short idle time-out, in order to ensure the file-system is placed in a clean + mount unit is created, with a short idle timeout, in order to ensure the file-system is placed in a clean state quickly after each access.</para></listitem> </varlistentry> diff --git a/man/systemd-networkd.service.xml b/man/systemd-networkd.service.xml index bac43667b9..2127bf1814 100644 --- a/man/systemd-networkd.service.xml +++ b/man/systemd-networkd.service.xml @@ -59,7 +59,7 @@ <para>When <filename>systemd-networkd</filename> exits, it generally leaves existing network devices and configuration intact. This makes it possible to - transition from the initrams and to restart the service without breaking + transition from the initramfs and to restart the service without breaking connectivity. This also means that when configuration is updated and <filename>systemd-networkd</filename> is restarted, netdev interfaces for which configuration was removed will not be dropped, and may need to be diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml index 284c9b294b..ff6b6a9a8b 100644 --- a/man/systemd-nspawn.xml +++ b/man/systemd-nspawn.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ <!ENTITY fedora_latest_version "28"> @@ -24,7 +24,7 @@ <refnamediv> <refname>systemd-nspawn</refname> - <refpurpose>Spawn a namespace container for debugging, testing and building</refpurpose> + <refpurpose>Spawn a command or OS in a light-weight container</refpurpose> </refnamediv> <refsynopsisdiv> @@ -55,7 +55,7 @@ <para><command>systemd-nspawn</command> may be invoked on any directory tree containing an operating system tree, using the <option>--directory=</option> command line option. By using the <option>--machine=</option> option an OS tree is automatically searched for in a couple of locations, most importantly in - <filename>/var/lib/machines</filename>, the suggested directory to place container images installed on the + <filename>/var/lib/machines</filename>, the suggested directory to place OS container images installed on the system.</para> <para>In contrast to <citerefentry diff --git a/man/systemd-portabled.service.xml b/man/systemd-portabled.service.xml index a6bd6c52e7..8c5e4cc5a1 100644 --- a/man/systemd-portabled.service.xml +++ b/man/systemd-portabled.service.xml @@ -36,7 +36,7 @@ <para>Most of <command>systemd-portabled</command>'s functionality is accessible through the <citerefentry><refentrytitle>portablectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> command.</para> - <para>See the <ulink url="https://github.com/systemd/systemd/blob/master/doc/PORTABLE_SERVICES.md">Portable + <para>See the <ulink url="https://systemd.io/PORTABLE_SERVICES">Portable Services Documentation</ulink> for details about the concepts this service implements.</para> </refsect1> diff --git a/man/systemd-resolved.service.xml b/man/systemd-resolved.service.xml index c895adaaf3..d7334e01ec 100644 --- a/man/systemd-resolved.service.xml +++ b/man/systemd-resolved.service.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -66,14 +66,21 @@ <filename>/etc/systemd/resolved.conf</filename>, the per-link static settings in <filename>/etc/systemd/network/*.network</filename> files (in case <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> is - used), the per-link dynamic settings received over DHCP, and any DNS server information made available by other - system services. See + used), the per-link dynamic settings received over DHCP, user request made via + <citerefentry><refentrytitle>resolvectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, and any DNS server + information made available by other system services. See <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> and <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details about systemd's own configuration files for DNS servers. To improve compatibility, <filename>/etc/resolv.conf</filename> is read in order to discover configured system DNS servers, but only if it is - not a symlink to <filename>/run/systemd/resolve/stub-resolv.conf</filename> or - <filename>/run/systemd/resolve/resolv.conf</filename> (see below).</para> + not a symlink to <filename>/run/systemd/resolve/stub-resolv.conf</filename>, + <filename>/usr/lib/systemd/resolv.conf</filename> or <filename>/run/systemd/resolve/resolv.conf</filename> (see + below).</para> + + </refsect1> + + <refsect1> + <title>Synthetic Records</title> <para><command>systemd-resolved</command> synthesizes DNS resource records (RRs) for the following cases:</para> @@ -99,6 +106,10 @@ to their configured addresses and back, but they will not affect lookups for non-address types (like MX).</para></listitem> </itemizedlist> + </refsect1> + + <refsect1> + <title>Protocols and Routing</title> <para>Lookup requests are routed to the available DNS servers, LLMNR and MulticastDNS interfaces according to the following rules:</para> @@ -132,16 +143,45 @@ lookup zones on all matching interfaces). If the lookup failed on all interfaces, the last failing response is returned.</para> - <para>Routing of lookups may be influenced by configuring - per-interface domain names. See - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. Lookups for a hostname ending in one of the - per-interface domains are exclusively routed to the matching - interfaces.</para> + <para>Routing of lookups may be influenced by configuring per-interface domain names and other settings. See + <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> and + <citerefentry><refentrytitle>resolvectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for details. The + following query routing logic applies for unicast DNS traffic:</para> + + <itemizedlist> + <listitem><para>If a name to look up matches (that is: is equal to or has as suffix) any of the configured search + or route-only domains of any link (or the globally configured DNS settings), the "best matching" + search/route-only domain is determined: the matching one with the most labels. The query is then sent to all DNS + servers of any links or the globally configured DNS servers associated with this "best matching" + search/route-only domain. (Note that more than one link might have this same "best matching" search/route-only + domain configured, in which case the query is sent to all of them in parallel).</para></listitem> + + <listitem><para>If a query does not match any configured search/route-only domain (neither per-link nor global), + it is sent to all DNS servers that are configured on links with the "DNS default route" option set, as well as + the globally configured DNS server.</para></listitem> + + <listitem><para>If there is no link configured as "DNS default route" and no global DNS server configured, the + compiled-in fallback DNS server is used.</para></listitem> + + <listitem><para>Otherwise the query is failed as no suitable DNS servers could be determined.</para></listitem> + </itemizedlist> + + <para>The "DNS default route" option is a boolean setting configureable with <command>resolvectl</command> or in + <filename>.network</filename> files. If not set, it is implicitly determined based on the configured DNS domains + for a link: if there's any route-only domain (not matching <literal>~.</literal>) it defaults to false, otherwise + to true.</para> + + <para>Effectively this means: in order to preferably route all DNS queries not explicitly matched by + search/route-only domain configuration to a specific link, configure a <literal>~.</literal> route-only domain on + it. This will ensure that other links will not be considered for the queries (unless they too carry such a + route-only domain). In order to route all such DNS queries to a specific link only in case no other link is + preferable, then set the "DNS default route" option for the link to true, and do not configure a + <literal>~.</literal> route-only domain on it. Finally, in order to ensure that a specific link never receives any + DNS traffic not matching any of its configured search/route-only domains, set the "DNS default route" option for it + to false.</para> <para>See the <ulink url="https://www.freedesktop.org/wiki/Software/systemd/resolved"> resolved D-Bus API Documentation</ulink> for information about the APIs <filename>systemd-resolved</filename> provides.</para> - </refsect1> <refsect1> diff --git a/man/systemd-run-generator.xml b/man/systemd-run-generator.xml new file mode 100644 index 0000000000..20eb6916eb --- /dev/null +++ b/man/systemd-run-generator.xml @@ -0,0 +1,82 @@ +<?xml version="1.0"?> +<!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- + SPDX-License-Identifier: LGPL-2.1+ +--> +<refentry id="systemd-run-generator"> + + <refentryinfo> + <title>systemd-run-generator</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-run-generator</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-run-generator</refname> + <refpurpose>Generator for invoking commands specified on the kernel command line as system service</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/usr/lib/systemd/system-generators/systemd-run-generator</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-run-generator</filename> is a generator + that reads the kernel command line and understands three + options:</para> + + <para>If the <option>systemd.run=</option> option is specified and followed by a command line, a unit named + <filename>kernel-command-line.service</filename> is generated for it and booted into. The service has + <varname>Type=oneshot</varname> set, and has <varname>SuccessAction=exit</varname> and + <varname>FailureAction=exit</varname> configured by default, thus ensuring that the system is shut down as soon as + the command completes. The exit status of the command line is propagated to the invoking container manager, if + this applies (which might propagate this further, to the calling shell — e.g. + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>7</manvolnum></citerefentry> does this). If + this option is used multiple times the unit file will contain multiple <varname>ExecStart=</varname> lines, to + execute all commands in order. The command is started as regular service, i.e. with + <varname>DefaultDependencies=</varname> on. </para> + + <para>Use <option>systemd.run_success_action=</option> and <option>systemd.run_failure_action=</option> to tweak + how to react to the process completing. In particular assigning <literal>none</literal> will leave the system + running after the command completes. For further details on supported arguments, see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para><filename>systemd-run-generator</filename> implements + <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>Example</title> + + <para>Use a command like the following to add a user to the user database inside a container run with + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>7</manvolnum></citerefentry>:</para> + + <programlisting># systemd-nspawn -D mycontainer -b systemd.run='"adduser test"'</programlisting> + <para>(Note the requirement for double quoting in the command line above. The first level of quoting ('') is + processed and removed by the command shell used to invoke <command>systemd-nspawn</command>. The second level of + quoting ("") is propagated to the kernel command line of the container and processed and removed by + <command>systemd-run-generator</command>. Both together make sure both words of the specified command line + <command>adduser test</command> end up in the generated unit file together and are neither split apart by the + command shell nor by the generator.)</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-run.xml b/man/systemd-run.xml index 1c254afae3..3c60340dc1 100644 --- a/man/systemd-run.xml +++ b/man/systemd-run.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -83,6 +83,16 @@ <replaceable>COMMAND</replaceable> may be omitted. In this case, <command>systemd-run</command> creates only a <filename>.path</filename>, <filename>.socket</filename>, or <filename>.timer</filename> unit that triggers the specified unit.</para> + + <para>By default, services created with <command>systemd-run</command> default to the <option>simple</option> type, + see the description of <varname>Type=</varname> in + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> for + details. Note that when this type is used the service manager (and thus the <command>systemd-run</command> command) + considers service start-up successful as soon as the <function>fork()</function> for the main service process + succeeded, i.e. before the <function>execve()</function> is invoked, and thus even if the specified command cannot + be started. Consider using the <option>exec</option> service type (i.e. <option>--property=Type=exec</option>) to + ensure that <command>systemd-run</command> returns successfully only if the specified command line has been + successfully started.</para> </refsect1> <refsect1> @@ -198,6 +208,23 @@ </varlistentry> <varlistentry> + <term><option>--working-directory=</option></term> + + <listitem><para>Runs the service process with the specified working directory. Also see + <varname>WorkingDirectory=</varname> in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--same-dir</option></term> + <term><option>-d</option></term> + + <listitem><para>Similar to <option>--working-directory=</option> but uses the current working directory of the + caller for the service to execute.</para></listitem> + </varlistentry> + + <varlistentry> <term><option>-E <replaceable>NAME</replaceable>=<replaceable>VALUE</replaceable></option></term> <term><option>--setenv=<replaceable>NAME</replaceable>=<replaceable>VALUE</replaceable></option></term> @@ -248,6 +275,15 @@ </varlistentry> <varlistentry> + <term><option>--shell</option></term> + <term><option>-S</option></term> + + <listitem><para>A shortcut for <literal>--pty --same-dir --wait --collect --service-type=exec $SHELL</literal>, + i.e. requests an interactive shell in the current working directory, running in service context, accessible + with a single switch.</para></listitem> + </varlistentry> + + <varlistentry> <term><option>--quiet</option></term> <term><option>-q</option></term> diff --git a/man/systemd-sleep.conf.xml b/man/systemd-sleep.conf.xml index bd1f36aa62..96e6d5e452 100644 --- a/man/systemd-sleep.conf.xml +++ b/man/systemd-sleep.conf.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -114,6 +114,24 @@ <variablelist class='systemd-directives'> <varlistentry> + <term><varname>AllowSuspend=</varname></term> + <term><varname>AllowHibernation=</varname></term> + <term><varname>AllowSuspendThenHibernate=</varname></term> + <term><varname>AllowHybridSleep=</varname></term> + + <listitem><para>By default any power-saving mode is advertised if possible (i.e. + the kernel supports that mode, the necessary resources are available). Those + switches can be used to disable specific modes.</para> + + <para>If <varname>AllowHibernation=no</varname> or <varname>AllowSuspend=no</varname> is + used, this implies <varname>AllowSuspendThenHibernate=no</varname> and + <varname>AllowHybridSleep=no</varname>, since those methods use both suspend and hibernation + internally. <varname>AllowSuspendThenHibernate=yes</varname> and + <varname>AllowHybridSleep=yes</varname> can be used to override and enable those specific + modes.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>SuspendMode=</varname></term> <term><varname>HibernateMode=</varname></term> <term><varname>HybridSleepMode=</varname></term> diff --git a/man/systemd-socket-activate.xml b/man/systemd-socket-activate.xml index cb0065dfd3..c3707050df 100644 --- a/man/systemd-socket-activate.xml +++ b/man/systemd-socket-activate.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/systemd-socket-proxyd.xml b/man/systemd-socket-proxyd.xml index 34a87ac8e4..1869465a3b 100644 --- a/man/systemd-socket-proxyd.xml +++ b/man/systemd-socket-proxyd.xml @@ -4,8 +4,6 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- SPDX-License-Identifier: LGPL-2.1+ - - Copyright © 2013 David Strauss --> <refentry id="systemd-socket-proxyd" xmlns:xi="http://www.w3.org/2001/XInclude"> @@ -54,7 +52,7 @@ <citerefentry project='die-net'><refentrytitle>socat</refentrytitle><manvolnum>1</manvolnum></citerefentry>. The main differences for <command>systemd-socket-proxyd</command> are support for socket activation with - <literal>Accept=false</literal> and an event-driven + <literal>Accept=no</literal> and an event-driven design that scales better with the number of connections.</para> </refsect1> diff --git a/man/systemd-system.conf.xml b/man/systemd-system.conf.xml index a914ef2523..35da82ab1a 100644 --- a/man/systemd-system.conf.xml +++ b/man/systemd-system.conf.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ <!ENTITY % entities SYSTEM "custom-entities.ent" > @@ -99,34 +99,11 @@ <varlistentry> <term><varname>CPUAffinity=</varname></term> - <listitem><para>Configures the initial CPU affinity for the - init process. Takes a list of CPU indices or ranges separated - by either whitespace or commas. CPU ranges are specified by - the lower and upper CPU indices separated by a - dash.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>JoinControllers=cpu,cpuacct net_cls,netprio</varname></term> - - <listitem><para>Configures controllers that shall be mounted - in a single hierarchy. By default, systemd will mount all - controllers which are enabled in the kernel in individual - hierarchies, with the exception of those listed in this - setting. Takes a space-separated list of comma-separated - controller names, in order to allow multiple joined - hierarchies. Defaults to 'cpu,cpuacct'. Pass an empty string - to ensure that systemd mounts all controllers in separate - hierarchies.</para> - - <para>Note that this option is only applied once, at very - early boot. If you use an initial RAM disk (initrd) that uses - systemd, it might hence be necessary to rebuild the initrd if - this option is changed, and make sure the new configuration - file is included in it. Otherwise, the initrd might mount the - controller hierarchies in a different configuration than - intended, and the main system cannot remount them - anymore.</para></listitem> + <listitem><para>Configures the CPU affinity for the service manager as well as the default CPU affinity for all + forked off processes. Takes a list of CPU indices or ranges separated by either whitespace or commas. CPU + ranges are specified by the lower and upper CPU indices separated by a dash. Individual services may override + the CPU affinity for their processes with the <varname>CPUAffinity=</varname> setting in unit files, see + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> </varlistentry> <varlistentry> @@ -322,15 +299,17 @@ <term><varname>DefaultBlockIOAccounting=</varname></term> <term><varname>DefaultMemoryAccounting=</varname></term> <term><varname>DefaultTasksAccounting=</varname></term> + <term><varname>DefaultIOAccounting=</varname></term> <term><varname>DefaultIPAccounting=</varname></term> <listitem><para>Configure the default resource accounting settings, as configured per-unit by <varname>CPUAccounting=</varname>, <varname>BlockIOAccounting=</varname>, <varname>MemoryAccounting=</varname>, - <varname>TasksAccounting=</varname> and <varname>IPAccounting=</varname>. See + <varname>TasksAccounting=</varname>, <varname>IOAccounting=</varname> and <varname>IPAccounting=</varname>. See <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details on the per-unit settings. <varname>DefaultTasksAccounting=</varname> defaults to on, - <varname>DefaultMemoryAccounting=</varname> to &MEMORY_ACCOUNTING_DEFAULT;, - the other three settings to off.</para></listitem> + for details on the per-unit settings. <varname>DefaultTasksAccounting=</varname> defaults to yes, + <varname>DefaultMemoryAccounting=</varname> to &MEMORY_ACCOUNTING_DEFAULT;. <varname>DefaultCPUAccounting=</varname> + defaults to yes if enabling CPU accounting doesn't require the CPU controller to be enabled (Linux 4.15+ using the + unified hierarchy for resource control), otherwise it defaults to no. The other three settings default to no.</para></listitem> </varlistentry> <varlistentry> diff --git a/man/systemd-sysusers.xml b/man/systemd-sysusers.xml index 7da2c55d27..6c9b921f05 100644 --- a/man/systemd-sysusers.xml +++ b/man/systemd-sysusers.xml @@ -130,7 +130,8 @@ <title>See Also</title> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> + <citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <ulink url="https://systemd.io/UIDS-GIDS">Users, Groups, UIDs and GIDs on systemd systems</ulink> </para> </refsect1> diff --git a/man/systemd-time-wait-sync.service.xml b/man/systemd-time-wait-sync.service.xml index a967371246..5667c886ea 100644 --- a/man/systemd-time-wait-sync.service.xml +++ b/man/systemd-time-wait-sync.service.xml @@ -4,8 +4,6 @@ <!-- SPDX-License-Identifier: LGPL-2.1+ - - Copyright © 2018 Peter A. Bigot --> <refentry id="systemd-time-wait-sync.service" conditional='ENABLE_TIMESYNCD'> diff --git a/man/systemd-tmpfiles.xml b/man/systemd-tmpfiles.xml index 9ff114feef..9978d95cab 100644 --- a/man/systemd-tmpfiles.xml +++ b/man/systemd-tmpfiles.xml @@ -176,14 +176,12 @@ <xi:include href="standard-options.xml" xpointer="version" /> </variablelist> - <para>It is possible to combine <option>--create</option>, - <option>--clean</option>, and <option>--remove</option> in one - invocation. For example, during boot the following command line is - executed to ensure that all temporary and volatile directories are + <para>It is possible to combine <option>--create</option>, <option>--clean</option>, and <option>--remove</option> + in one invocation (in which case removal and clean-up are executed before creation of new files). For example, + during boot the following command line is executed to ensure that all temporary and volatile directories are removed and created according to the configuration file:</para> <programlisting>systemd-tmpfiles --remove --create</programlisting> - </refsect1> <refsect1> diff --git a/man/systemd-udevd.service.xml b/man/systemd-udevd.service.xml index 73c77ea690..330700d7dd 100644 --- a/man/systemd-udevd.service.xml +++ b/man/systemd-udevd.service.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -170,6 +170,26 @@ when possible. It is enabled by default; specifying 0 disables it.</para> </listitem> </varlistentry> + <varlistentry> + <term><varname>net.naming-scheme=</varname></term> + <listitem> + <para>Network interfaces are renamed to give them predictable names when possible (unless + <varname>net.ifnames=0</varname> is specified, see above). The names are derived from various + device metadata fields. Newer versions of <filename>systemd-udevd.service</filename> take more of + these fields into account, improving (and thus possibly changing) the names used for the same + devices. With this kernel command line option it is possible to pick a specific version of this + algorithm. It expects a naming scheme identifier as argument. Currently the following identifiers + are known: <literal>v238</literal>, <literal>v239</literal>, <literal>v240</literal> which each + implement the naming scheme that was the default in the indicated systemd version. In addition, + <literal>latest</literal> may be used to designate the latest scheme known (to this particular + version of <filename>systemd-udevd.service</filename>).</para> + + <para>Note that selecting a specific scheme is not sufficient to fully stabilize interface naming: + the naming is generally derived from driver attributes exposed by the kernel. As the kernel is + updated, previously missing attributes <filename>systemd-udevd.service</filename> is checking might + appear, which affects older name derivation algorithms, too.</para> + </listitem> + </varlistentry> </variablelist> <!-- when adding entries here, consider also adding them in kernel-command-line.xml --> diff --git a/man/systemd.dnssd.xml b/man/systemd.dnssd.xml index b3a4c68e3f..dc00591fcd 100644 --- a/man/systemd.dnssd.xml +++ b/man/systemd.dnssd.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index 3bd790b485..6419bee499 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -81,6 +81,9 @@ <refsect1> <title>Paths</title> + <para>The following settings may be used to change a service's view of the filesystem. Please note that the paths + must be absolute and must not contain a <literal>..</literal> path component.</para> + <variablelist class='unit-directives'> <varlistentry> @@ -121,7 +124,16 @@ partition table, or a file system within an MBR/MS-DOS or GPT partition table with only a single Linux-compatible partition, or a set of file systems within a GPT partition table that follows the <ulink url="https://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/">Discoverable Partitions - Specification</ulink>.</para></listitem> + Specification</ulink>.</para> + + <para>When <varname>DevicePolicy=</varname> is set to <literal>closed</literal> or <literal>strict</literal>, + or set to <literal>auto</literal> and <varname>DeviceAllow=</varname> is set, then this setting adds + <filename>/dev/loop-control</filename> with <constant>rw</constant> mode, <literal>block-loop</literal> and + <literal>block-blkext</literal> with <constant>rwm</constant> mode to <varname>DeviceAllow=</varname>. See + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the details about <varname>DevicePolicy=</varname> or <varname>DeviceAllow=</varname>. Also, see + <varname>PrivateDevices=</varname> below, as it may change the setting of <varname>DevicePolicy=</varname>. + </para></listitem> </varlistentry> <varlistentry> @@ -738,6 +750,20 @@ CapabilityBoundingSet=~CAP_B CAP_C</programlisting> <refsect1> <title>Sandboxing</title> + <para>The following sandboxing options are an effective way to limit the exposure of the system towards the unit's + processes. It is recommended to turn on as many of these options for each unit as is possible without negatively + affecting the process' ability to operate. Note that many of these sandboxing features are gracefully turned off on + systems where the underlying security mechanism is not available. For example, <varname>ProtectSystem=</varname> + has no effect if the kernel is built without file system namespacing or if the service manager runs in a container + manager that makes file system namespacing unavailable to its payload. Similar, + <varname>RestrictRealtime=</varname> has no effect on systems that lack support for SECCOMP system call filtering, + or in containers where support for this is turned off.</para> + + <para>Also note that some sandboxing functionality is generally not available in user services (i.e. services run + by the per-user service manager). Specifically, the various settings requiring file system namespacing support + (such as <varname>ProtectSystem=</varname>) are not available, as the underlying kernel functionality is only + accessible to privileged processes.</para> + <variablelist> <varlistentry> @@ -755,9 +781,9 @@ CapabilityBoundingSet=~CAP_B CAP_C</programlisting> recommended to enable this setting for all long-running services, unless they are involved with system updates or need to modify the operating system in other ways. If this option is used, <varname>ReadWritePaths=</varname> may be used to exclude specific directories from being made read-only. 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 - below. Defaults to off.</para></listitem> + setting is implied if <varname>DynamicUser=</varname> is set. This setting cannot ensure protection in all + cases. In general it has the same limitations as <varname>ReadOnlyPaths=</varname>, see below. Defaults to + off.</para></listitem> </varlistentry> <varlistentry> @@ -776,11 +802,11 @@ CapabilityBoundingSet=~CAP_B CAP_C</programlisting> <varname>ReadOnlyPaths=</varname>, and <literal>tmpfs</literal> is mostly equivalent to <varname>TemporaryFileSystem=</varname>.</para> - <para> It is recommended to enable this setting for all long-running services (in particular network-facing ones), - to ensure they cannot get access to private user data, unless the services actually require access to the user's - private data. This setting is implied if <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 below.</para></listitem> + <para> It is recommended to enable this setting for all long-running services (in particular network-facing + ones), to ensure they cannot get access to private user data, unless the services actually require access to + the user's private data. This setting is implied if <varname>DynamicUser=</varname> is set. This setting cannot + ensure protection in all cases. In general it has the same limitations as <varname>ReadOnlyPaths=</varname>, + see below.</para></listitem> </varlistentry> <varlistentry> @@ -793,15 +819,18 @@ CapabilityBoundingSet=~CAP_B CAP_C</programlisting> <listitem><para>These options take a whitespace-separated list of directory names. The specified directory names must be relative, and may not include <literal>..</literal>. If set, one or more directories by the specified names will be created (including their parents) below the locations - defined in the following table, when the unit is started.</para> + defined in the following table, when the unit is started. Also, the corresponding environment variable + is defined with the full path of directories. If multiple directories are set, then int the environment variable + the paths are concatenated with colon (<literal>:</literal>).</para> <table> - <title>Automatic directory creation</title> - <tgroup cols='3'> + <title>Automatic directory creation and environment variables</title> + <tgroup cols='4'> <thead> <row> <entry>Locations</entry> <entry>for system</entry> <entry>for users</entry> + <entry>Environment variable</entry> </row> </thead> <tbody> @@ -809,26 +838,31 @@ CapabilityBoundingSet=~CAP_B CAP_C</programlisting> <entry><varname>RuntimeDirectory=</varname></entry> <entry><filename>/run</filename></entry> <entry><varname>$XDG_RUNTIME_DIR</varname></entry> + <entry><varname>$RUNTIME_DIRECTORY</varname></entry> </row> <row> <entry><varname>StateDirectory=</varname></entry> <entry><filename>/var/lib</filename></entry> <entry><varname>$XDG_CONFIG_HOME</varname></entry> + <entry><varname>$STATE_DIRECTORY</varname></entry> </row> <row> <entry><varname>CacheDirectory=</varname></entry> <entry><filename>/var/cache</filename></entry> <entry><varname>$XDG_CACHE_HOME</varname></entry> + <entry><varname>$CACHE_DIRECTORY</varname></entry> </row> <row> <entry><varname>LogsDirectory=</varname></entry> <entry><filename>/var/log</filename></entry> <entry><varname>$XDG_CONFIG_HOME</varname><filename>/log</filename></entry> + <entry><varname>$LOGS_DIRECTORY</varname></entry> </row> <row> <entry><varname>ConfigurationDirectory=</varname></entry> <entry><filename>/etc</filename></entry> <entry><varname>$XDG_CONFIG_HOME</varname></entry> + <entry><varname>$CONFIGURATION_DIRECTORY</varname></entry> </row> </tbody> </tgroup> @@ -878,7 +912,13 @@ CapabilityBoundingSet=~CAP_B CAP_C</programlisting> <filename>/run/foo/bar</filename>, and <filename>/run/baz</filename>. The directories <filename>/run/foo/bar</filename> and <filename>/run/baz</filename> except <filename>/run/foo</filename> are owned by the user and group specified in <varname>User=</varname> and <varname>Group=</varname>, and removed - when the service is stopped.</para></listitem> + when the service is stopped.</para> + + <para>Example: if a system service unit has the following, + <programlisting>RuntimeDirectory=foo/bar +StateDirectory=aaa/bbb ccc</programlisting> + then the environment variable <literal>RUNTIME_DIRECTORY</literal> is set with <literal>/run/foo/bar</literal>, and + <literal>STATE_DIRECTORY</literal> is set with <literal>/var/lib/aaa/bbb:/var/lib/ccc</literal>.</para></listitem> </varlistentry> <varlistentry> @@ -934,8 +974,7 @@ CapabilityBoundingSet=~CAP_B CAP_C</programlisting> <varname>BindPaths=</varname>, or <varname>BindReadOnlyPaths=</varname> inside it. For a more flexible option, see <varname>TemporaryFileSystem=</varname>.</para> - <para>Note that restricting access with these options does not extend to submounts of a directory that are - created later on. Non-directory paths may be specified as well. These options may be specified more than once, + <para>Non-directory paths may be specified as well. These options may be specified more than once, in which case all paths listed will have limited access from within the namespace. If the empty string is assigned to this option, the specific list is reset, and all prior assignments have no effect.</para> @@ -947,11 +986,19 @@ CapabilityBoundingSet=~CAP_B CAP_C</programlisting> <literal>+</literal> on the same path make sure to specify <literal>-</literal> first, and <literal>+</literal> second.</para> - <para>Note that using this setting will disconnect propagation of mounts from the service to the host - (propagation in the opposite direction continues to work). This means that this setting may not be used for - services which shall be able to install mount points in the main mount namespace. Note that the effect of these - settings may be undone by privileged processes. In order to set up an effective sandboxed environment for a - unit it is thus recommended to combine these settings with either + <para>Note that these settings will disconnect propagation of mounts from the unit's processes to the + host. This means that this setting may not be used for services which shall be able to install mount points in + the main mount namespace. For <varname>ReadWritePaths=</varname> and <varname>ReadOnlyPaths=</varname> + propagation in the other direction is not affected, i.e. mounts created on the host generally appear in the + unit processes' namespace, and mounts removed on the host also disappear there too. In particular, note that + mount propagation from host to unit will result in unmodified mounts to be created in the unit's namespace, + i.e. writable mounts appearing on the host will be writable in the unit's namespace too, even when propagated + below a path marked with <varname>ReadOnlyPaths=</varname>! Restricting access with these options hence does + not extend to submounts of a directory that are created later on. This means the lock-down offered by that + setting is not complete, and does not offer full protection. </para> + + <para>Note that the effect of these settings may be undone by privileged processes. In order to set up an + effective sandboxed environment for a unit it is thus recommended to combine these settings with either <varname>CapabilityBoundingSet=~CAP_SYS_ADMIN</varname> or <varname>SystemCallFilter=~@mount</varname>.</para></listitem> </varlistentry> @@ -1043,9 +1090,13 @@ BindReadOnlyPaths=/var/lib/systemd</programlisting> Defaults to false. It is possible to run two or more units within the same private network namespace by using the <varname>JoinsNamespaceOf=</varname> directive, see <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for - details. Note that this option will disconnect all socket families from the host, this includes AF_NETLINK and - AF_UNIX. The latter has the effect that AF_UNIX sockets in the abstract socket namespace will become - unavailable to the processes (however, those located in the file system will continue to be accessible).</para> + details. Note that this option will disconnect all socket families from the host, including + <constant>AF_NETLINK</constant> and <constant>AF_UNIX</constant>. Effectively, for + <constant>AF_NETLINK</constant> this means that device configuration events received from + <citerefentry><refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> are + not delivered to the unit's processes. And for <constant>AF_UNIX</constant> this has the effect that + <constant>AF_UNIX</constant> sockets in the abstract socket namespace of the host will become unavailable to + the unit's processes (however, those located in the file system will continue to be accessible).</para> <para>Note that the implementation of this setting might be impossible (for example if network namespaces are not available), and the unit should be written in a way that does not solely rely on this setting for @@ -1311,10 +1362,7 @@ RestrictNamespaces=~cgroup net</programlisting> settings (see the discussion in <varname>PrivateMounts=</varname> above) will implicitly disable mount and unmount propagation from the unit's processes towards the host by changing the propagation setting of all mount points in the unit's file system namepace to <option>slave</option> first. Setting this option to - <option>shared</option> does not reestablish propagation in that case. Conversely, if this option is set, but - no other file system namespace setting is used, then new file system namespaces will be created for the unit's - processes and this propagation flag will be applied right away to all mounts within it, without the - intermediary application of <option>slave</option>.</para> + <option>shared</option> does not reestablish propagation in that case.</para> <para>If not set – but file system namespaces are enabled through another file system namespace unit setting – <option>shared</option> mount propagation is used, but — as mentioned — as <option>slave</option> is applied @@ -1597,7 +1645,13 @@ SystemCallErrorNumber=EPERM</programlisting> <para> See <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details - about environment variables.</para></listitem> + about environment variables.</para> + + <para>Note that environment variables are not suitable for passing secrets (such as passwords, key material, …) + to service processes. Environment variables set for a unit are exposed to unprivileged clients via D-Bus IPC, + and generally not understood as being data that requires protection. Moreover, environment variables are + propagated down the process tree, including across security boundaries (such as setuid/setgid executables), and + hence might leak to processes that should not have access to the secret data.</para></listitem> </varlistentry> <varlistentry> @@ -1739,7 +1793,13 @@ SystemCallErrorNumber=EPERM</programlisting> <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more details about named file descriptors and their ordering.</para> - <para>This setting defaults to <option>null</option>.</para></listitem> + <para>This setting defaults to <option>null</option>.</para> + + <para>Note that services which specify <option>DefaultDependencies=no</option> and use + <varname>StandardInput=</varname> or <varname>StandardOutput=</varname> with + <option>tty</option>/<option>tty-force</option>/<option>tty-fail</option>, should specify + <option>After=systemd-vconsole-setup.service</option>, to make sure that the tty intialization is + finished before they start.</para></listitem> </varlistentry> <varlistentry> @@ -1749,8 +1809,8 @@ SystemCallErrorNumber=EPERM</programlisting> of <option>inherit</option>, <option>null</option>, <option>tty</option>, <option>journal</option>, <option>syslog</option>, <option>kmsg</option>, <option>journal+console</option>, <option>syslog+console</option>, <option>kmsg+console</option>, - <option>file:<replaceable>path</replaceable></option>, <option>socket</option> or - <option>fd:<replaceable>name</replaceable></option>.</para> + <option>file:<replaceable>path</replaceable></option>, <option>append:<replaceable>path</replaceable></option>, + <option>socket</option> or<option>fd:<replaceable>name</replaceable></option>.</para> <para><option>inherit</option> duplicates the file descriptor of standard input for standard output.</para> @@ -1781,11 +1841,17 @@ SystemCallErrorNumber=EPERM</programlisting> <para>The <option>file:<replaceable>path</replaceable></option> option may be used to connect a specific file system object to standard output. The semantics are similar to the same option of - <varname>StandardInput=</varname>, see above. If standard input and output are directed to the same file path, - it is opened only once, for reading as well as writing and duplicated. This is particular useful when the - specified path refers to an <constant>AF_UNIX</constant> socket in the file system, as in that case only a + <varname>StandardInput=</varname>, see above. If <replaceable>path</replaceable> refers to a regular file + on the filesystem, it is opened (created if it doesn't exist yet) for writing at the beginning of the file, + but without truncating it. + If standard input and output are directed to the same file path, it is opened only once, for reading as well + as writing and duplicated. This is particularly useful when the specified path refers to an + <constant>AF_UNIX</constant> socket in the file system, as in that case only a single stream connection is created for both input and output.</para> + <para><option>append:<replaceable>path</replaceable></option> is similar to <option>file:<replaceable>path + </replaceable></option> above, but it opens the file in append mode.</para> + <para><option>socket</option> connects standard output to a socket acquired via socket activation. The semantics are similar to the same option of <varname>StandardInput=</varname>, see above.</para> @@ -1906,6 +1972,22 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy </varlistentry> <varlistentry> + <term><varname>LogRateLimitIntervalSec=</varname></term> + <term><varname>LogRateLimitBurst=</varname></term> + + <listitem><para>Configures the rate limiting that is applied to messages generated by this unit. If, in the + time interval defined by <varname>LogRateLimitIntervalSec=</varname>, more messages than specified in + <varname>LogRateLimitBurst=</varname> are logged by a service, all further messages within the interval are + dropped until the interval is over. A message about the number of dropped messages is generated. The time + specification for <varname>LogRateLimitIntervalSec=</varname> may be specified in the following units: "s", + "min", "h", "ms", "us" (see + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details). + The default settings are set by <varname>RateLimitIntervalSec=</varname> and <varname>RateLimitBurst=</varname> + configured in <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + + <varlistentry> <term><varname>SyslogIdentifier=</varname></term> <listitem><para>Sets the process name ("<command>syslog</command> tag") to prefix log lines sent to the logging diff --git a/man/systemd.generator.xml b/man/systemd.generator.xml index 8a7a11a862..5007563e06 100644 --- a/man/systemd.generator.xml +++ b/man/systemd.generator.xml @@ -260,7 +260,7 @@ <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> converts <filename>/etc/fstab</filename> into native mount units. It uses argv[1] as location to place the generated unit files in order to allow the - user to override <filename>/etc/fstab</filename> with her own native unit + user to override <filename>/etc/fstab</filename> with their own native unit files, but also to ensure that <filename>/etc/fstab</filename> overrides any vendor default from <filename>/usr</filename>.</para> diff --git a/man/systemd.journal-fields.xml b/man/systemd.journal-fields.xml index c079274c32..76e1de72ca 100644 --- a/man/systemd.journal-fields.xml +++ b/man/systemd.journal-fields.xml @@ -56,14 +56,10 @@ <varlistentry> <term><varname>MESSAGE_ID=</varname></term> <listitem> - <para>A 128-bit message identifier ID for recognizing - certain message types, if this is desirable. This should - contain a 128-bit ID formatted as a lower-case hexadecimal - string, without any separating dashes or suchlike. This is - recommended to be a UUID-compatible ID, but this is not - enforced, and formatted differently. Developers can generate - a new ID for this purpose with <command>journalctl - <option>--new-id128</option></command>. + <para>A 128-bit message identifier ID for recognizing certain message types, if this is desirable. This + should contain a 128-bit ID formatted as a lower-case hexadecimal string, without any separating dashes or + suchlike. This is recommended to be a UUID-compatible ID, but this is not enforced, and formatted + differently. Developers can generate a new ID for this purpose with <command>systemd-id128 new</command>. </para> </listitem> </varlistentry> @@ -103,16 +99,34 @@ <term><varname>SYSLOG_FACILITY=</varname></term> <term><varname>SYSLOG_IDENTIFIER=</varname></term> <term><varname>SYSLOG_PID=</varname></term> + <term><varname>SYSLOG_TIMESTAMP=</varname></term> <listitem> - <para>Syslog compatibility fields containing the facility - (formatted as decimal string), the identifier string (i.e. - "tag"), and the client PID. (Note that the tag is usually - derived from glibc's - <varname>program_invocation_short_name</varname> variable, - see + <para>Syslog compatibility fields containing the facility (formatted as + decimal string), the identifier string (i.e. "tag"), the client PID, and + the timestamp as specified in the original datagram. (Note that the tag is + usually derived from glibc's + <varname>program_invocation_short_name</varname> variable, see <citerefentry project='die-net'><refentrytitle>program_invocation_short_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>.)</para> </listitem> + </varlistentry> + <varlistentry> + <term><varname>SYSLOG_RAW=</varname></term> + <listitem> + <para>The original contents of the syslog line as received in the syslog + datagram. This field is only included if the <varname>MESSAGE=</varname> + field was modified compared to the original payload or the timestamp could + not be located properly and is not included in + <varname>SYSLOG_TIMESTAMP=</varname>. Message truncation occurs when when + the message contains leading or trailing whitespace (trailing and leading + whitespace is stripped), or it contains an embedded + <constant>NUL</constant> byte (the <constant>NUL</constant> byte and + anything after it is not included). Thus, the original syslog line is + either stored as <varname>SYSLOG_RAW=</varname> or it can be recreated + based on the stored priority and facility, timestamp, identifier, and the + message payload in <varname>MESSAGE=</varname>. + </para> + </listitem> </varlistentry> </variablelist> </refsect1> diff --git a/man/systemd.kill.xml b/man/systemd.kill.xml index 2112dea31a..9b264ecbf5 100644 --- a/man/systemd.kill.xml +++ b/man/systemd.kill.xml @@ -94,7 +94,8 @@ enabled with <varname>SendSIGHUP=</varname>). If then, after a delay (configured via the <varname>TimeoutStopSec=</varname> option), processes still remain, the termination request is - repeated with the <constant>SIGKILL</constant> signal (unless + repeated with the <constant>SIGKILL</constant> signal or the + signal specified via <varname>FinalKillSignal=</varname> (unless this is disabled via the <varname>SendSIGKILL=</varname> option). See <citerefentry><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry> @@ -135,9 +136,35 @@ <varlistentry> <term><varname>SendSIGKILL=</varname></term> <listitem><para>Specifies whether to send - <constant>SIGKILL</constant> to remaining processes after a - timeout, if the normal shutdown procedure left processes of - the service around. Takes a boolean value. Defaults to "yes". + <constant>SIGKILL</constant> (or the signal specified by + <varname>FinalKillSignal=</varname>) to remaining processes + after a timeout, if the normal shutdown procedure left + processes of the service around. Takes a boolean value. + Defaults to "yes". + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>FinalKillSignal=</varname></term> + <listitem><para>Specifies which signal to send to remaining + processes after a timeout if <varname>SendSIGKILL=</varname> + is enabled. The signal configured here should be one that is + not typically caught and processed by services (<constant>SIGTERM</constant> + is not suitable). Developers can find it useful to use this to + generate a coredump to troubleshoot why a service did not + terminate upon receiving the initial <constant>SIGTERM</constant> + signal. This can be achieved by configuring <varname>LimitCORE=</varname> + and setting <varname>FinalKillSignal=</varname> to either + <constant>SIGQUIT</constant> or <constant>SIGABRT</constant> + Defaults to <constant>SIGKILL</constant>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>WatchdogSignal=</varname></term> + <listitem><para>Specifies which signal to use to terminate the + service when the watchdog timeout expires (enabled through + <varname>WatchdogSec=</varname>). Defaults to <constant>SIGABRT</constant>. </para></listitem> </varlistentry> diff --git a/man/systemd.link.xml b/man/systemd.link.xml index 6708753e82..f74edd0186 100644 --- a/man/systemd.link.xml +++ b/man/systemd.link.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -364,14 +364,13 @@ <varlistentry> <term><varname>AutoNegotiation=</varname></term> <listitem> - <para>Enables or disables automatic negotiation of transmission parameters. + <para>Takes a boolean. If set to yes, automatic negotiation of transmission parameters is enabled. Autonegotiation is a procedure by which two connected ethernet devices choose common transmission parameters, such as speed, duplex mode, and flow control. - Takes a boolean value. Unset by default, which means that the kernel default - will be used.</para> + When unset, the kernel's default will be used.</para> - <para>Note that if autonegotiation is enabled, speed and duplex settings are - read-only. If autonegotation is disabled, speed and duplex settings are writable + <para>Note that if autonegotiation is enabled, speed, duplex and advertise settings are + read-only. If autonegotation is disabled, speed, duplex and advertise settings are writable if the driver supports multiple link modes.</para> </listitem> </varlistentry> @@ -479,43 +478,109 @@ </listitem> </varlistentry> <varlistentry> + <term><varname>Advertise=</varname></term> + <listitem> + <para>This sets what speeds and duplex modes of operation are advertised for auto-negotiation. + The supported values are: + + <table> + <title>Supported advertise values</title> + <tgroup cols='3'> + <colspec colname='Advertise' /> + <colspec colname='Speed' /> + <colspec colname='Duplex Mode' /> + + <thead><row> + <entry>Advertise</entry> + <entry>Speed (Mbps)</entry> + <entry>Duplex Mode</entry> + </row></thead> + <tbody> + + <row><entry><literal>10baset-half</literal></entry> + <entry>10</entry><entry>half</entry></row> + + <row><entry><literal>10baset-full</literal></entry> + <entry>10</entry><entry>full</entry></row> + + <row><entry><literal>100baset-half</literal></entry> + <entry>100</entry><entry>half</entry></row> + + <row><entry><literal>100baset-full</literal></entry> + <entry>100</entry><entry>full</entry></row> + + <row><entry><literal>1000baset-half</literal></entry> + <entry>1000</entry><entry>half</entry></row> + + <row><entry><literal>1000baset-full</literal></entry> + <entry>1000</entry><entry>full</entry></row> + + <row><entry><literal>10000baset-full</literal></entry> + <entry>10000</entry><entry>full</entry></row> + + <row><entry><literal>2500basex-full</literal></entry> + <entry>2500</entry><entry>full</entry></row> + + <row><entry><literal>1000basekx-full</literal></entry> + <entry>1000</entry><entry>full</entry></row> + + <row><entry><literal>10000basekx4-full</literal></entry> + <entry>10000</entry><entry>full</entry></row> + + <row><entry><literal>10000basekr-full</literal></entry> + <entry>10000</entry><entry>full</entry></row> + + <row><entry><literal>10000baser-fec</literal></entry> + <entry>10000</entry><entry>full</entry></row> + + <row><entry><literal>20000basemld2-full</literal></entry> + <entry>20000</entry><entry>full</entry></row> + + <row><entry><literal>20000basekr2-full</literal></entry> + <entry>20000</entry><entry>full</entry></row> + </tbody> + </tgroup> + </table> + + By default this is unset, i.e. all possible modes will be advertised. + This option may be specified more than once, in which case all specified speeds and modes are advertised. + If the empty string is assigned to this option, the list is reset, and all prior assignments have no effect. + </para> + </listitem> + </varlistentry> + <varlistentry> <term><varname>TCPSegmentationOffload=</varname></term> <listitem> - <para>The TCP Segmentation Offload (TSO) when true enables - TCP segmentation offload. Takes a boolean value. - Defaults to "unset".</para> + <para>Takes a boolean. If set to true, the TCP Segmentation Offload (TSO) is enabled. + When unset, the kernel's default will be used.</para> </listitem> </varlistentry> <varlistentry> <term><varname>TCP6SegmentationOffload=</varname></term> <listitem> - <para>The TCP6 Segmentation Offload (tx-tcp6-segmentation) when true enables - TCP6 segmentation offload. Takes a boolean value. - Defaults to "unset".</para> + <para>Takes a boolean. If set to true, the TCP6 Segmentation Offload (tx-tcp6-segmentation) is enabled. + When unset, the kernel's default will be used.</para> </listitem> </varlistentry> <varlistentry> <term><varname>GenericSegmentationOffload=</varname></term> <listitem> - <para>The Generic Segmentation Offload (GSO) when true enables - generic segmentation offload. Takes a boolean value. - Defaults to "unset".</para> + <para>Takes a boolean. If set to true, the Generic Segmentation Offload (GSO) is enabled. + When unset, the kernel's default will be used.</para> </listitem> </varlistentry> <varlistentry> <term><varname>GenericReceiveOffload=</varname></term> <listitem> - <para>The Generic Receive Offload (GRO) when true enables - generic receive offload. Takes a boolean value. - Defaults to "unset".</para> + <para>Takes a boolean. If set to true, the Generic Receive Offload (GRO) is enabled. + When unset, the kernel's default will be used.</para> </listitem> </varlistentry> <varlistentry> <term><varname>LargeReceiveOffload=</varname></term> <listitem> - <para>The Large Receive Offload (LRO) when true enables - large receive offload. Takes a boolean value. - Defaults to "unset".</para> + <para>Takes a boolean. If set to true, the Large Receive Offload (LRO) is enabled. + When unset, the kernel's default will be used.</para> </listitem> </varlistentry> <varlistentry> diff --git a/man/systemd.mount.xml b/man/systemd.mount.xml index 1eb06b0ea8..6d8c873ca5 100644 --- a/man/systemd.mount.xml +++ b/man/systemd.mount.xml @@ -165,7 +165,7 @@ is detected by <command>systemd-fstab-generator</command> and the options are transformed so that systemd fulfills the job-control implications of that option. Specifically <command>systemd-fstab-generator</command> acts - as though <literal>x-systemd.mount-timout=infinity,retry=10000</literal> was + as though <literal>x-systemd.mount-timeout=infinity,retry=10000</literal> was prepended to the option list, and <literal>fg,nofail</literal> was appended. Depending on specific requirements, it may be appropriate to provide some of these options explicitly, or to make use of the @@ -263,7 +263,7 @@ for details.</para></listitem> </varlistentry> - <varlistentry> + <varlistentry id='device-timeout'> <term><option>x-systemd.device-timeout=</option></term> <listitem><para>Configure how long systemd should wait for a @@ -303,7 +303,7 @@ <varlistentry> <term><option>x-systemd.makefs</option></term> - <listitem><para>The file system or swap structure will be initialized + <listitem><para>The file system will be initialized on the device. If the device is not "empty", i.e. it contains any signature, the operation will be skipped. It is hence expected that this option remains set even after the device has been initalized.</para> @@ -370,12 +370,10 @@ <varlistentry> <term><option>nofail</option></term> - <listitem><para>With <option>nofail</option>, this mount will - be only wanted, not required, by - <filename>local-fs.target</filename> or - <filename>remote-fs.target</filename>. This means that the - boot will continue even if this mount point is not mounted - successfully.</para> + <listitem><para>With <option>nofail</option>, this mount will be only wanted, not required, by + <filename>local-fs.target</filename> or <filename>remote-fs.target</filename>. Moreover the mount unit is not + ordered before these target units. This means that the boot will continue without waiting for the mount unit + and regardless whether the mount point can be mounted successfully.</para> </listitem> </varlistentry> diff --git a/man/systemd.netdev.xml b/man/systemd.netdev.xml index 5073258641..e17c1e3fbe 100644 --- a/man/systemd.netdev.xml +++ b/man/systemd.netdev.xml @@ -100,6 +100,11 @@ <row><entry><varname>gretap</varname></entry> <entry>A Level 2 GRE tunnel over IPv4.</entry></row> + <row><entry><varname>erspan</varname></entry> + <entry>ERSPAN mirrors traffic on one or more source ports and delivers the mirrored traffic to one or more destination ports on another switch. + The traffic is encapsulated in generic routing encapsulation (GRE) and is therefore routable across a layer 3 network between the source switch + and the destination switch.</entry></row> + <row><entry><varname>ip6gre</varname></entry> <entry>A Level 3 GRE tunnel over IPv6.</entry></row> @@ -163,6 +168,10 @@ <row><entry><varname>netdevsim</varname></entry> <entry> A simulator. This simulated networking device is used for testing various networking APIs and at this time is particularly focused on testing hardware offloading related interfaces.</entry></row> + + <row><entry><varname>fou</varname></entry> + <entry>Foo-over-UDP tunneling.</entry></row> + </tbody> </tgroup> </table> @@ -266,12 +275,13 @@ <varlistentry> <term><varname>MTUBytes=</varname></term> <listitem> - <para>The maximum transmission unit in bytes to set for - the device. The usual suffixes K, M, G, are supported and - are understood to the base of 1024. This key is not - currently supported for <literal>tun</literal> or - <literal>tap</literal> devices. - </para> + <para>The maximum transmission unit in bytes to set for the device. The usual suffixes K, M, G, + are supported and are understood to the base of 1024. For <literal>tun</literal> or + <literal>tap</literal> devices, <varname>MTUBytes=</varname> setting is not currently supported in + <literal>[NetDev]</literal> section. Please specify it in <literal>[Link]</literal> section of + corresponding + <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> + files.</para> </listitem> </varlistentry> <varlistentry> @@ -281,9 +291,11 @@ given, one is generated based on the interface name and the <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - This key is not currently supported for - <literal>tun</literal> or <literal>tap</literal> devices. - </para> + For <literal>tun</literal> or <literal>tap</literal> devices, <varname>MACAddress=</varname> setting + is not currently supported in <literal>[NetDev]</literal> section. Please specify it in + <literal>[Link]</literal> section of corresponding + <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> + files.</para> </listitem> </varlistentry> </variablelist> @@ -356,37 +368,36 @@ <varlistentry> <term><varname>MulticastQuerier=</varname></term> <listitem> - <para>A boolean. This setting controls the IFLA_BR_MCAST_QUERIER option in the kernel. + <para>Takes a boolean. This setting controls the IFLA_BR_MCAST_QUERIER option in the kernel. If enabled, the kernel will send general ICMP queries from a zero source address. This feature should allow faster convergence on startup, but it causes some multicast-aware switches to misbehave and disrupt forwarding of multicast packets. - When unset, the kernel's default setting applies. + When unset, the kernel's default will be used. </para> </listitem> </varlistentry> <varlistentry> <term><varname>MulticastSnooping=</varname></term> <listitem> - <para>A boolean. This setting controls the IFLA_BR_MCAST_SNOOPING option in the kernel. + <para>Takes a boolean. This setting controls the IFLA_BR_MCAST_SNOOPING option in the kernel. If enabled, IGMP snooping monitors the Internet Group Management Protocol (IGMP) traffic - between hosts and multicast routers. When unset, the kernel's default setting applies. + between hosts and multicast routers. When unset, the kernel's default will be used. </para> </listitem> </varlistentry> <varlistentry> <term><varname>VLANFiltering=</varname></term> <listitem> - <para>A boolean. This setting controls the IFLA_BR_VLAN_FILTERING option in the kernel. - If enabled, the bridge will be started in VLAN-filtering mode. When unset, the kernel's - default setting applies. + <para>Takes a boolean. This setting controls the IFLA_BR_VLAN_FILTERING option in the kernel. + If enabled, the bridge will be started in VLAN-filtering mode. When unset, the kernel's default will be used. </para> </listitem> </varlistentry> <varlistentry> <term><varname>STP=</varname></term> <listitem> - <para>A boolean. This enables the bridge's Spanning Tree Protocol (STP). When unset, - the kernel's default setting applies. + <para>Takes a boolean. This enables the bridge's Spanning Tree Protocol (STP). + When unset, the kernel's default will be used. </para> </listitem> </varlistentry> @@ -411,34 +422,35 @@ <varlistentry> <term><varname>GVRP=</varname></term> <listitem> - <para>The Generic VLAN Registration Protocol (GVRP) is a protocol that - allows automatic learning of VLANs on a network. A boolean. When unset, - the kernel's default setting applies.</para> + <para>Takes a boolean. The Generic VLAN Registration Protocol (GVRP) is a protocol that + allows automatic learning of VLANs on a network. + When unset, the kernel's default will be used. + </para> </listitem> </varlistentry> <varlistentry> <term><varname>MVRP=</varname></term> <listitem> - <para>Multiple VLAN Registration Protocol (MVRP) formerly known as GARP VLAN + <para>Takes a boolean. Multiple VLAN Registration Protocol (MVRP) formerly known as GARP VLAN Registration Protocol (GVRP) is a standards-based Layer 2 network protocol, for automatic configuration of VLAN information on switches. It was defined - in the 802.1ak amendment to 802.1Q-2005. A boolean. When unset, the kernel's - default setting applies.</para> + in the 802.1ak amendment to 802.1Q-2005. When unset, the kernel's default will be used. + </para> </listitem> </varlistentry> <varlistentry> <term><varname>LooseBinding=</varname></term> <listitem> - <para>The VLAN loose binding mode, in which only the operational state is passed + <para>Takes a boolean. The VLAN loose binding mode, in which only the operational state is passed from the parent to the associated VLANs, but the VLAN device state is not changed. - A boolean. When unset, the kernel's default setting applies.</para> + When unset, the kernel's default will be used.</para> </listitem> </varlistentry> <varlistentry> <term><varname>ReorderHeader=</varname></term> <listitem> - <para>The VLAN reorder header is set VLAN interfaces behave like physical interfaces. - A boolean. When unset, the kernel's default setting applies.</para> + <para>Takes a boolean. The VLAN reorder header is set VLAN interfaces behave like physical interfaces. + When unset, the kernel's default will be used.</para> </listitem> </varlistentry> </variablelist> @@ -547,7 +559,7 @@ <varlistentry> <term><varname>MacLearning=</varname></term> <listitem> - <para>A boolean. When true, enables dynamic MAC learning + <para>Takes a boolean. When true, enables dynamic MAC learning to discover remote MAC addresses.</para> </listitem> </varlistentry> @@ -567,7 +579,7 @@ <varlistentry> <term><varname>ReduceARPProxy=</varname></term> <listitem> - <para>A boolean. When true, bridge-connected VXLAN tunnel + <para>Takes a boolean. When true, bridge-connected VXLAN tunnel endpoint answers ARP requests from the local bridge on behalf of remote Distributed Overlay Virtual Ethernet <ulink url="https://en.wikipedia.org/wiki/Distributed_Overlay_Virtual_Ethernet"> @@ -577,58 +589,58 @@ <varlistentry> <term><varname>L2MissNotification=</varname></term> <listitem> - <para>A boolean. When true, enables netlink LLADDR miss + <para>Takes a boolean. When true, enables netlink LLADDR miss notifications.</para> </listitem> </varlistentry> <varlistentry> <term><varname>L3MissNotification=</varname></term> <listitem> - <para>A boolean. When true, enables netlink IP address miss + <para>Takes a boolean. When true, enables netlink IP address miss notifications.</para> </listitem> </varlistentry> <varlistentry> <term><varname>RouteShortCircuit=</varname></term> <listitem> - <para>A boolean. When true, route short circuiting is turned + <para>Takes a boolean. When true, route short circuiting is turned on.</para> </listitem> </varlistentry> <varlistentry> <term><varname>UDPChecksum=</varname></term> <listitem> - <para>A boolean. When true, transmitting UDP checksums when doing VXLAN/IPv4 is turned on.</para> + <para>Takes a boolean. When true, transmitting UDP checksums when doing VXLAN/IPv4 is turned on.</para> </listitem> </varlistentry> <varlistentry> <term><varname>UDP6ZeroChecksumTx=</varname></term> <listitem> - <para>A boolean. When true, sending zero checksums in VXLAN/IPv6 is turned on.</para> + <para>Takes a boolean. When true, sending zero checksums in VXLAN/IPv6 is turned on.</para> </listitem> </varlistentry> <varlistentry> <term><varname>UDP6ZeroChecksumRx=</varname></term> <listitem> - <para>A boolean. When true, receiving zero checksums in VXLAN/IPv6 is turned on.</para> + <para>Takes a boolean. When true, receiving zero checksums in VXLAN/IPv6 is turned on.</para> </listitem> </varlistentry> <varlistentry> <term><varname>RemoteChecksumTx=</varname></term> <listitem> - <para>A boolean. When true, remote transmit checksum offload of VXLAN is turned on.</para> + <para>Takes a boolean. When true, remote transmit checksum offload of VXLAN is turned on.</para> </listitem> </varlistentry> <varlistentry> <term><varname>RemoteChecksumRx=</varname></term> <listitem> - <para>A boolean. When true, remote receive checksum offload in VXLAN is turned on.</para> + <para>Takes a boolean. When true, remote receive checksum offload in VXLAN is turned on.</para> </listitem> </varlistentry> <varlistentry> <term><varname>GroupPolicyExtension=</varname></term> <listitem> - <para>A boolean. When true, it enables Group Policy VXLAN extension security label mechanism + <para>Takes a boolean. When true, it enables Group Policy VXLAN extension security label mechanism across network peers based on VXLAN. For details about the Group Policy VXLAN, see the <ulink url="https://tools.ietf.org/html/draft-smith-vxlan-group-policy"> VXLAN Group Policy </ulink> document. Defaults to false.</para> @@ -697,19 +709,19 @@ <varlistentry> <term><varname>UDPChecksum=</varname></term> <listitem> - <para>A boolean. When true, specifies if UDP checksum is calculated for transmitted packets over IPv4.</para> + <para>Takes a boolean. When true, specifies if UDP checksum is calculated for transmitted packets over IPv4.</para> </listitem> </varlistentry> <varlistentry> <term><varname>UDP6ZeroChecksumTx=</varname></term> <listitem> - <para>A boolean. When true, skip UDP checksum calculation for transmitted packets over IPv6.</para> + <para>Takes a boolean. When true, skip UDP checksum calculation for transmitted packets over IPv6.</para> </listitem> </varlistentry> <varlistentry> <term><varname>UDP6ZeroChecksumRx=</varname></term> <listitem> - <para>A boolean. When true, allows incoming UDP packets over IPv6 with zero checksum field.</para> + <para>Takes a boolean. When true, allows incoming UDP packets over IPv6 with zero checksum field.</para> </listitem> </varlistentry> <varlistentry> @@ -780,7 +792,7 @@ <varlistentry> <term><varname>DiscoverPathMTU=</varname></term> <listitem> - <para>A boolean. When true, enables Path MTU Discovery on + <para>Takes a boolean. When true, enables Path MTU Discovery on the tunnel.</para> </listitem> </varlistentry> @@ -800,7 +812,7 @@ <varlistentry> <term><varname>CopyDSCP=</varname></term> <listitem> - <para>A boolean. When true, the Differentiated Service Code + <para>Takes a boolean. When true, the Differentiated Service Code Point (DSCP) field will be copied to the inner header from outer header during the decapsulation of an IPv6 tunnel packet. DSCP is a field in an IP packet that enables different @@ -863,7 +875,7 @@ <varlistentry> <term><varname>Independent=</varname></term> <listitem> - <para>A boolean. When true tunnel does not require .network file. Created as "tunnel@NONE". + <para>Takes a boolean. When true tunnel does not require .network file. Created as "tunnel@NONE". Defaults to <literal>false</literal>. </para> </listitem> @@ -871,13 +883,112 @@ <varlistentry> <term><varname>AllowLocalRemote=</varname></term> <listitem> - <para>A boolean. When true allows tunnel traffic on <varname>ip6tnl</varname> devices where the remote endpoint is a local host address. - Defaults to unset. + <para>Takes a boolean. When true allows tunnel traffic on <varname>ip6tnl</varname> devices where the remote endpoint is a local host address. + When unset, the kernel's default will be used. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>FooOverUDP=</varname></term> + <listitem> + <para>Takes a boolean. Specifies whether <varname>FooOverUDP=</varname> tunnel is to be configured. + Defaults to false. For more detail information see + <ulink url="https://lwn.net/Articles/614348">Foo over UDP</ulink></para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>FOUDestinationPort=</varname></term> + <listitem> + <para>The <varname>FOUDestinationPort=</varname> specifies the UDP destination port for encapsulation. + This field is mandatory and is not set by default.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>FOUSourcePort=</varname></term> + <listitem> + <para>The <constant>FOUSourcePort=</constant> specifies the UDP source port for encapsulation. Defaults to <varname>0</varname>, + that is, the source port for packets is left to the network stack to decide.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Encapsulation=</varname></term> + <listitem> + <para>Accepts the same key as <literal>[FooOverUDP]</literal></para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>IPv6RapidDeploymentPrefix=</varname></term> + <listitem> + <para>Reconfigure the tunnel for <ulink url="https://tools.ietf.org/html/rfc5569">IPv6 Rapid + Deployment</ulink>, also known as 6rd. The value is an ISP-specific IPv6 prefix with a non-zero length. Only + applicable to SIT tunnels.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>ISATAP=</varname></term> + <listitem> + <para>Takes a boolean. If set, configures the tunnel as Intra-Site Automatic Tunnel Addressing Protocol (ISATAP) tunnel. + Only applicable to SIT tunnels. When unset, the kernel's default will be used.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>SerializeTunneledPackets=</varname></term> + <listitem> + <para>Takes a boolean. If set to yes, then packets are serialized. Only applies for ERSPAN tunnel. + When unset, the kernel's default will be used. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>ERSPANIndex=</varname></term> + <listitem> + <para>Specifies the ERSPAN index field for the interface, an integer in the range 1-1048575 associated with + the ERSPAN traffic's source port and direction. This field is mandatory. </para> </listitem> </varlistentry> </variablelist> </refsect1> + + <refsect1> + <title>[FooOverUDP] Section Options</title> + + <para>The <literal>[FooOverUDP]</literal> section only applies for + netdevs of kind <literal>fou</literal> and accepts the + following keys:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>Protocol=</varname></term> + <listitem> + <para>The <varname>Protocol=</varname> specifies the protocol number of the + packets arriving at the UDP port. This field is mandatory and is not set by default. Valid range is 1-255.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Encapsulation=</varname></term> + <listitem> + <para>Specifies the encapsulation mechanism used to store networking packets of various protocols inside the UDP packets. Supports the following values: + + <literal>FooOverUDP</literal> provides the simplest no frills model of UDP encapsulation, it simply encapsulates + packets directly in the UDP payload. + <literal>GenericUDPEncapsulation</literal> is a generic and extensible encapsulation, it allows encapsulation of packets for any IP + protocol and optional data as part of the encapsulation. + For more detailed information see <ulink url="https://lwn.net/Articles/615044">Generic UDP Encapsulation</ulink>. + Defaults to <literal>FooOverUDP</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Port=</varname></term> + <listitem> + <para>Specifies the port number, where the IP encapsulation packets will arrive. Please take note that the packets + will arrive with the encapsulation will be removed. Then they will be manually fed back into the network stack, and sent ahead + for delivery to the real destination. This option is mandatory.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> <refsect1> <title>[Peer] Section Options</title> @@ -929,7 +1040,7 @@ <variablelist class='network-directives'> <varlistentry> <term><varname>OneQueue=</varname></term> - <listitem><para>Takes a boolean argument. Configures whether + <listitem><para>Takes a boolean. Configures whether all packets are queued at the device (enabled), or a fixed number of packets are queued at the device and the rest at the <literal>qdisc</literal>. Defaults to @@ -938,7 +1049,7 @@ </varlistentry> <varlistentry> <term><varname>MultiQueue=</varname></term> - <listitem><para>Takes a boolean argument. Configures whether + <listitem><para>Takes a boolean. Configures whether to use multiple file descriptors (queues) to parallelize packets sending and receiving. Defaults to <literal>no</literal>.</para> @@ -946,7 +1057,7 @@ </varlistentry> <varlistentry> <term><varname>PacketInfo=</varname></term> - <listitem><para>Takes a boolean argument. Configures whether + <listitem><para>Takes a boolean. Configures whether packets should be prepended with four extra bytes (two flag bytes and two protocol bytes). If disabled, it indicates that the packets will be pure IP packets. Defaults to @@ -955,7 +1066,7 @@ </varlistentry> <varlistentry> <term><varname>VNetHeader=</varname></term> - <listitem><para>Takes a boolean argument. Configures + <listitem><para>Takes a boolean. Configures IFF_VNET_HDR flag for a tap device. It allows sending and receiving larger Generic Segmentation Offload (GSO) packets. This may increase throughput significantly. @@ -1003,7 +1114,7 @@ (see <citerefentry project="wireguard"><refentrytitle>wg</refentrytitle><manvolnum>8</manvolnum></citerefentry>). This option is mandatory to use WireGuard. Note that because this information is secret, you may want to set - the permissions of the .netdev file to be owned by <literal>root:systemd-networkd</literal> + the permissions of the .netdev file to be owned by <literal>root:systemd-network</literal> with a <literal>0640</literal> file mode.</para> </listitem> </varlistentry> @@ -1194,6 +1305,27 @@ </varlistentry> <varlistentry> + <term><varname>AdActorSystemPriority=</varname></term> + <listitem> + <para>Specifies the 802.3ad actor system priority. Ranges [1-65535].</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>AdUserPortKey=</varname></term> + <listitem> + <para>Specifies the 802.3ad user defined portion of the port key. Ranges [0-1023].</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>AdActorSystem=</varname></term> + <listitem> + <para>Specifies the 802.3ad system mac address. This can not be either NULL or Multicast.</para> + </listitem> + </varlistentry> + + <varlistentry> <term><varname>FailOverMACPolicy=</varname></term> <listitem> <para>Specifies whether the active-backup mode should set all slaves to @@ -1315,7 +1447,7 @@ <varlistentry> <term><varname>AllSlavesActive=</varname></term> <listitem> - <para>A boolean. Specifies that duplicate frames (received on inactive ports) + <para>Takes a boolean. Specifies that duplicate frames (received on inactive ports) should be dropped when false, or delivered when true. Normally, bonding will drop duplicate frames (received on inactive ports), which is desirable for most users. But there are some times it is nice to allow duplicate @@ -1326,6 +1458,15 @@ </varlistentry> <varlistentry> + <term><varname>DynamicTransmitLoadBalancing=</varname></term> + <listitem> + <para>Takes a boolean. Specifies if dynamic shuffling of flows is enabled. Applies only + for balance-tlb mode. Defaults to unset. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><varname>MinLinks=</varname></term> <listitem> <para>Specifies the minimum number of links that must be active before @@ -1342,7 +1483,7 @@ </refsect1> <refsect1> - <title>Example</title> + <title>Examples</title> <example> <title>/etc/systemd/network/25-bridge.netdev</title> @@ -1377,14 +1518,39 @@ Remote=192.169.224.239 TTL=64</programlisting> </example> <example> + <title>/etc/systemd/network/1-fou-tunnel.netdev</title> + <programlisting>[NetDev] +Name=fou-tun +Kind=fou + +[FooOverUDP] +Port=5555 +Protocol=4 + </programlisting> + </example> + <example> + <title>/etc/systemd/network/25-fou-ipip.netdev</title> + <programlisting>[NetDev] +Name=ipip-tun +Kind=ipip + +[Tunnel] +Independent=yes +Local=10.65.208.212 +Remote=10.65.208.211 +FooOverUDP=yes +FOUDestinationPort=5555 + </programlisting> + </example> + <example> <title>/etc/systemd/network/25-tap.netdev</title> <programlisting>[NetDev] Name=tap-test Kind=tap [Tap] -MultiQueue=true -PacketInfo=true</programlisting> </example> +MultiQueue=yes +PacketInfo=yes</programlisting> </example> <example> <title>/etc/systemd/network/25-sit.netdev</title> @@ -1399,6 +1565,18 @@ Remote=10.65.223.239</programlisting> </example> <example> + <title>/etc/systemd/network/25-6rd.netdev</title> + <programlisting>[NetDev] +Name=6rd-tun +Kind=sit +MTUBytes=1480 + +[Tunnel] +Local=10.65.223.238 +IPv6RapidDeploymentPrefix=2602::/24</programlisting> + </example> + + <example> <title>/etc/systemd/network/25-gre.netdev</title> <programlisting>[NetDev] Name=gre-tun diff --git a/man/systemd.network.xml b/man/systemd.network.xml index fc8e0aea68..ee464ffff4 100644 --- a/man/systemd.network.xml +++ b/man/systemd.network.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -221,8 +221,8 @@ <varlistentry> <term><varname>ARP=</varname></term> <listitem> - <para>A boolean. Enables or disables the ARP (low-level Address Resolution Protocol) - for this interface. Defaults to unset, which means that the kernel default will be used.</para> + <para>Takes a boolean. If set to true, the ARP (low-level Address Resolution Protocol) + for this interface is enabled. When unset, the kernel's default will be used.</para> <para> For example, disabling ARP is useful when creating multiple MACVLAN or VLAN virtual interfaces atop a single lower-level physical interface, which will then only serve as a link/"bridge" device aggregating traffic to the same physical link and not participate in @@ -232,20 +232,20 @@ <varlistentry> <term><varname>Multicast=</varname></term> <listitem> - <para>A boolean. Enables or disables the multicast flag on the device.</para> + <para>Takes a boolean. If set to true, the multicast flag on the device is enabled.</para> </listitem> </varlistentry> <varlistentry> <term><varname>AllMulticast=</varname></term> <listitem> - <para>A boolean. When this flag is set the driver retrieves all multicast packets from the network. + <para>Takes a boolean. If set to true, the driver retrieves all multicast packets from the network. This happens when multicast routing is enabled.</para> </listitem> </varlistentry> <varlistentry> <term><varname>Unmanaged=</varname></term> <listitem> - <para>A boolean. When <literal>yes</literal>, no attempts are + <para>Takes a boolean. When <literal>yes</literal>, no attempts are made to bring up or configure matching links, equivalent to when there are no matching network files. Defaults to <literal>no</literal>.</para> @@ -257,7 +257,7 @@ <varlistentry> <term><varname>RequiredForOnline=</varname></term> <listitem> - <para>A boolean. When <literal>yes</literal>, the network is deemed + <para>Takes a boolean. When <literal>yes</literal>, the network is deemed required when determining whether the system is online when running <literal>systemd-networkd-wait-online</literal>. When <literal>no</literal>, the network is ignored when checking for @@ -266,7 +266,7 @@ the event that there is no address being assigned by DHCP or the cable is not plugged in, the link will simply remain offline and be skipped automatically by <literal>systemd-networkd-wait-online</literal> - if <literal>RequiredForOnline=true</literal>.</para> + if <literal>RequiredForOnline=no</literal>.</para> </listitem> </varlistentry> </variablelist> @@ -311,7 +311,7 @@ <varlistentry> <term><varname>DHCPServer=</varname></term> <listitem> - <para>A boolean. Enables DHCPv4 server support. Defaults + <para>Takes a boolean. If set to <literal>yes</literal>, DHCPv4 server will be start. Defaults to <literal>no</literal>. Further settings for the DHCP server may be set in the <literal>[DHCPServer]</literal> section described below.</para> @@ -329,7 +329,7 @@ <varlistentry> <term><varname>IPv4LLRoute=</varname></term> <listitem> - <para>A boolean. When true, sets up the route needed for + <para>Takes a boolean. If set to true, sets up the route needed for non-IPv4LL hosts to communicate with IPv4LL-only hosts. Defaults to false. </para> @@ -348,7 +348,7 @@ <varlistentry> <term><varname>LLMNR=</varname></term> <listitem> - <para>A boolean or <literal>resolve</literal>. When true, + <para>Takes a boolean or <literal>resolve</literal>. When true, enables <ulink url="https://tools.ietf.org/html/rfc4795">Link-Local Multicast Name Resolution</ulink> on the link. When set to @@ -361,7 +361,7 @@ <varlistentry> <term><varname>MulticastDNS=</varname></term> <listitem> - <para>A boolean or <literal>resolve</literal>. When true, + <para>Takes a boolean or <literal>resolve</literal>. When true, enables <ulink url="https://tools.ietf.org/html/rfc6762">Multicast DNS</ulink> support on the link. When set to @@ -389,7 +389,7 @@ <varlistentry> <term><varname>DNSSEC=</varname></term> <listitem> - <para>A boolean or + <para>Takes a boolean. or <literal>allow-downgrade</literal>. When true, enables <ulink url="https://tools.ietf.org/html/rfc4033">DNSSEC</ulink> @@ -548,6 +548,17 @@ </listitem> </varlistentry> <varlistentry> + <term><varname>DNSDefaultRoute=</varname></term> + <listitem> + <para>Takes a boolean argument. If true, this link's configured DNS servers are used for resolving domain + names that do not match any link's configured <varname>Domains=</varname> setting. If false, this link's + configured DNS servers are never used for such domains, and are exclusively used for resolving names that + match at least one of the domains configured on this link. If not specified defaults to an automatic mode: + queries not matching any link's configured domains will be routed to this link if it has no routing-only + domains configured.</para> + </listitem> + </varlistentry> + <varlistentry> <term><varname>NTP=</varname></term> <listitem> <para>An NTP server address. This option may be specified more than once. This setting is read by @@ -559,8 +570,8 @@ <listitem><para>Configures IP packet forwarding for the system. If enabled, incoming packets on any network interface will be forwarded to any other interfaces - according to the routing table. Takes either a boolean - argument, or the values <literal>ipv4</literal> or + according to the routing table. Takes a boolean, + or the values <literal>ipv4</literal> or <literal>ipv6</literal>, which only enable IP packet forwarding for the specified address family. This controls the <filename>net.ipv4.ip_forward</filename> and @@ -608,9 +619,9 @@ </varlistentry> <varlistentry> <term><varname>IPv6AcceptRA=</varname></term> - <listitem><para>Enable or disable IPv6 Router Advertisement (RA) reception support for the interface. Takes - a boolean parameter. If true, RAs are accepted; if false, RAs are ignored, independently of the local - forwarding state. When not set, the kernel default is used, and RAs are accepted only when local forwarding + <listitem><para>Takes a boolean. Controls IPv6 Router Advertisement (RA) reception support for the interface. + If true, RAs are accepted; if false, RAs are ignored, independently of the local forwarding state. + If unset, the kernel's default is used, and RAs are accepted only when local forwarding is disabled for that interface. When RAs are accepted, they may trigger the start of the DHCPv6 client if the relevant flags are set in the RA data, or if no routers are found on the link.</para> @@ -626,7 +637,7 @@ <varlistentry> <term><varname>IPv6DuplicateAddressDetection=</varname></term> <listitem><para>Configures the amount of IPv6 Duplicate - Address Detection (DAD) probes to send. Defaults to unset. + Address Detection (DAD) probes to send. When unset, the kernel's default will be used. </para></listitem> </varlistentry> <varlistentry> @@ -634,21 +645,21 @@ <listitem><para>Configures IPv6 Hop Limit. For each router that forwards the packet, the hop limit is decremented by 1. When the hop limit field reaches zero, the packet is discarded. - Defaults to unset. + When unset, the kernel's default will be used. </para></listitem> </varlistentry> <varlistentry> <term><varname>IPv4ProxyARP=</varname></term> - <listitem><para>A boolean. Configures proxy ARP for IPv4. Proxy ARP is the technique in which one host, + <listitem><para>Takes a boolean. Configures proxy ARP for IPv4. Proxy ARP is the technique in which one host, usually a router, answers ARP requests intended for another machine. By "faking" its identity, the router accepts responsibility for routing packets to the "real" destination. (see <ulink url="https://tools.ietf.org/html/rfc1027">RFC 1027</ulink>. - Defaults to unset. + When unset, the kernel's default will be used. </para></listitem> </varlistentry> <varlistentry> <term><varname>IPv6ProxyNDP=</varname></term> - <listitem><para>A boolean. Configures proxy NDP for IPv6. Proxy NDP (Neighbor Discovery + <listitem><para>Takes a boolean. Configures proxy NDP for IPv6. Proxy NDP (Neighbor Discovery Protocol) is a technique for IPv6 to allow routing of addresses to a different destination when peers expect them to be present on a certain physical link. In this case a router answers Neighbour Advertisement messages intended for @@ -658,7 +669,7 @@ which can also be shown by <command>ip -6 neighbour show proxy</command>. systemd-networkd will control the per-interface `proxy_ndp` switch for each configured interface depending on this option. - Defautls to unset. + When unset, the kernel's default will be used. </para></listitem> </varlistentry> <varlistentry> @@ -666,8 +677,8 @@ <listitem><para>An IPv6 address, for which Neighbour Advertisement messages will be proxied. This option may be specified more than once. systemd-networkd will add the <option>IPv6ProxyNDPAddress=</option> entries to the kernel's IPv6 neighbor proxy table. - This option implies <option>IPv6ProxyNDP=true</option> but has no effect if - <option>IPv6ProxyNDP</option> has been set to false. Defaults to unset. + This option implies <option>IPv6ProxyNDP=yes</option> but has no effect if + <option>IPv6ProxyNDP</option> has been set to false. When unset, the kernel's default will be used. </para></listitem> </varlistentry> <varlistentry> @@ -688,7 +699,7 @@ <varlistentry> <term><varname>IPv6MTUBytes=</varname></term> <listitem><para>Configures IPv6 maximum transmission unit (MTU). - An integer greater than or equal to 1280 bytes. Defaults to unset. + An integer greater than or equal to 1280 bytes. When unset, the kernel's default will be used. </para></listitem> </varlistentry> <varlistentry> @@ -724,6 +735,14 @@ </listitem> </varlistentry> <varlistentry> + <term><varname>IPVLAN=</varname></term> + <listitem> + <para>The name of a IPVLAN to create on the link. See + <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + This option may be specified more than once.</para> + </listitem> + </varlistentry> + <varlistentry> <term><varname>MACVLAN=</varname></term> <listitem> <para>The name of a MACVLAN to create on the link. See @@ -750,7 +769,7 @@ <varlistentry> <term><varname>ActiveSlave=</varname></term> <listitem> - <para>A boolean. Specifies the new active slave. The <literal>ActiveSlave=</literal> + <para>Takes a boolean. Specifies the new active slave. The <literal>ActiveSlave=</literal> option is only valid for following modes: <literal>active-backup</literal>, <literal>balance-alb</literal> and @@ -761,7 +780,7 @@ <varlistentry> <term><varname>PrimarySlave=</varname></term> <listitem> - <para>A boolean. Specifies which slave is the primary device. The specified + <para>Takes a boolean. Specifies which slave is the primary device. The specified device will always be the active slave while it is available. Only when the primary is off-line will alternate devices be used. This is useful when one slave is preferred over another, e.g. when one slave has higher throughput @@ -776,7 +795,7 @@ <varlistentry> <term><varname>ConfigureWithoutCarrier=</varname></term> <listitem> - <para>A boolean. Allows networkd to configure a specific link even if it has no carrier. + <para>Takes a boolean. Allows networkd to configure a specific link even if it has no carrier. Defaults to false. </para> </listitem> @@ -848,7 +867,7 @@ <varlistentry> <term><varname>HomeAddress=</varname></term> <listitem> - <para>Takes a boolean argument. Designates this address the "home address" as defined in + <para>Takes a boolean. Designates this address the "home address" as defined in <ulink url="https://tools.ietf.org/html/rfc6275">RFC 6275</ulink>. Supported only on IPv6. Defaults to false.</para> </listitem> @@ -856,7 +875,7 @@ <varlistentry> <term><varname>DuplicateAddressDetection=</varname></term> <listitem> - <para>Takes a boolean argument. Do not perform Duplicate Address Detection + <para>Takes a boolean. Do not perform Duplicate Address Detection <ulink url="https://tools.ietf.org/html/rfc4862">RFC 4862</ulink> when adding this address. Supported only on IPv6. Defaults to false.</para> </listitem> @@ -864,7 +883,7 @@ <varlistentry> <term><varname>ManageTemporaryAddress=</varname></term> <listitem> - <para>Takes a boolean argument. If true the kernel manage temporary addresses created + <para>Takes a boolean. If true the kernel manage temporary addresses created from this one as template on behalf of Privacy Extensions <ulink url="https://tools.ietf.org/html/rfc3041">RFC 3041</ulink>. For this to become active, the use_tempaddr sysctl setting has to be set to a value greater than zero. @@ -876,7 +895,7 @@ <varlistentry> <term><varname>PrefixRoute=</varname></term> <listitem> - <para>Takes a boolean argument. When adding or modifying an IPv6 address, the userspace + <para>Takes a boolean. When adding or modifying an IPv6 address, the userspace application needs a way to suppress adding a prefix route. This is for example relevant together with IFA_F_MANAGERTEMPADDR, where userspace creates autoconf generated addresses, but depending on on-link, no route for the prefix should be added. Defaults to false.</para> @@ -885,7 +904,7 @@ <varlistentry> <term><varname>AutoJoin=</varname></term> <listitem> - <para>Takes a boolean argument. Joining multicast group on ethernet level via + <para>Takes a boolean. Joining multicast group on ethernet level via <command>ip maddr</command> command would not work if we have an Ethernet switch that does IGMP snooping since the switch would not replicate multicast packets on ports that did not have IGMP reports for the multicast addresses. Linux vxlan interfaces created via @@ -899,6 +918,31 @@ </variablelist> </refsect1> + <refsect1> + <title>[Neighbor] Section Options</title> + <para>A <literal>[Neighbor]</literal> section accepts the + following keys. The neighbor section adds a permanent, static + entry to the neighbor table (IPv6) or ARP table (IPv4) for + the given hardware address on the links matched for the network. + Specify several <literal>[Neighbor]</literal> sections to configure + several static neighbors.</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>Address=</varname></term> + <listitem> + <para>The IP address of the neighbor.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MACAddress=</varname></term> + <listitem> + <para>The hardware address of the neighbor.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + <refsect1> <title>[IPv6AddressLabel] Section Options</title> @@ -984,6 +1028,35 @@ <para>Specifies the outgoing device to match. The outgoing interface is only available for packets originating from local sockets that are bound to a device.</para> </listitem> </varlistentry> + <varlistentry> + <term><varname>SourcePort=</varname></term> + <listitem> + <para>Specifies the source IP port or IP port range match in forwarding information base (FIB) rules. + A port range is specified by the lower and upper port separated by a dash. Defaults to unset.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>DestinationPort=</varname></term> + <listitem> + <para>Specifies the destination IP port or IP port range match in forwarding information base (FIB) rules. + A port range is specified by the lower and upper port separated by a dash. Defaults to unset.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>IPProtocol=</varname></term> + <listitem> + <para>Specifies the IP protocol to match in forwarding information base (FIB) rules. Takes IP protocol name such as <literal>tcp</literal>, + <literal>udp</literal> or <literal>sctp</literal>, or IP protocol number such as <literal>6</literal> for <literal>tcp</literal> or + <literal>17</literal> for <literal>udp</literal>. + Defaults to unset.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>InvertRule=</varname></term> + <listitem> + <para>A boolean. Specifies wheather the rule to be inverted. Defaults to false.</para> + </listitem> + </varlistentry> </variablelist> </refsect1> @@ -1003,10 +1076,10 @@ <varlistentry> <term><varname>GatewayOnlink=</varname></term> <listitem> - <para>The <literal>GatewayOnlink</literal> option tells the kernel that it does not have + <para>Takes a boolean. If set to true, the kernel does not have to check if the gateway is reachable directly by the current machine (i.e., the kernel does not need to check if the gateway is attached to the local network), so that we can insert the - route in the kernel table without it being complained about. A boolean, defaults to <literal>no</literal>. + route in the kernel table without it being complained about. Defaults to <literal>no</literal>. </para> </listitem> </varlistentry> @@ -1069,7 +1142,7 @@ <varlistentry> <term><varname>Protocol=</varname></term> <listitem> - <para>The Protocol identifier for the route. Takes a number between 0 and 255 or the special values + <para>The protocol identifier for the route. Takes a number between 0 and 255 or the special values <literal>kernel</literal>, <literal>boot</literal> and <literal>static</literal>. Defaults to <literal>static</literal>. </para> @@ -1078,12 +1151,13 @@ <varlistentry> <term><varname>Type=</varname></term> <listitem> - <para>The Type identifier for special route types, which can be - <literal>unicast</literal> route to a destination network address which describes the path to the destination, - <literal>blackhole</literal> packets are discarded silently, - <literal>unreachable</literal> packets are discarded and the ICMP message host unreachable is generated, - <literal>prohibit</literal> packets are discarded and the ICMP message communication administratively - prohibited is generated. Defaults to <literal>unicast</literal>. + <para>Specifies the type for the route. If <literal>unicast</literal>, a regular route is defined, i.e. a + route indicating the path to take to a destination network address. If <literal>blackhole</literal>, packets + to the defined route are discarded silently. If <literal>unreachable</literal>, packets to the defined route + are discarded and the ICMP message "Host Unreachable" is generated. If <literal>prohibit</literal>, packets + to the defined route are discarded and the ICMP message "Communication Administratively Prohibited" is + generated. If <literal>throw</literal>, route lookup in the current routing table will fail and the route + selection process will return to Routing Policy Database (RPDB). Defaults to <literal>unicast</literal>. </para> </listitem> </varlistentry> @@ -1093,7 +1167,7 @@ <para>The TCP initial congestion window is used during the start of a TCP connection. During the start of a TCP session, when a client requests a resource, the server's initial congestion window determines how many data bytes will be sent during the initial burst of data. Takes a size in bytes between 1 and 4294967295 (2^32 - 1). The usual - suffixes K, M, G are supported and are understood to the base of 1024. Defaults to unset. + suffixes K, M, G are supported and are understood to the base of 1024. When unset, the kernel's default will be used. </para> </listitem> </varlistentry> @@ -1103,14 +1177,14 @@ <para>The TCP initial advertised receive window is the amount of receive data (in bytes) that can initally be buffered at one time on a connection. The sending host can send only that amount of data before waiting for an acknowledgment and window update from the receiving host. Takes a size in bytes between 1 and 4294967295 (2^32 - 1). The usual suffixes K, M, G are supported - and are understood to the base of 1024. Defaults to unset. + and are understood to the base of 1024. When unset, the kernel's default will be used. </para> </listitem> </varlistentry> <varlistentry> <term><varname>QuickAck=</varname></term> <listitem> - <para>Takes a boolean argument. When true enables TCP quick ack mode for the route. Defaults to unset. + <para>Takes a boolean. When true enables TCP quick ack mode for the route. When unset, the kernel's default will be used. </para> </listitem> </varlistentry> @@ -1159,13 +1233,14 @@ <listitem> <para>When true, the interface maximum transmission unit from the DHCP server will be used on the current link. + If <varname>MTUBytes=</varname> is set, then this setting is ignored. Defaults to false.</para> </listitem> </varlistentry> <varlistentry> <term><varname>Anonymize=</varname></term> <listitem> - <para>Takes a boolean argument. When true, the options sent to the DHCP server will + <para>Takes a boolean. When true, the options sent to the DHCP server will follow the <ulink url="https://tools.ietf.org/html/rfc7844">RFC 7844</ulink> (Anonymity Profiles for DHCP Clients) to minimize disclosure of identifying information. Defaults to false.</para> @@ -1186,29 +1261,32 @@ <varlistentry> <term><varname>SendHostname=</varname></term> <listitem> - <para>When true (the default), the machine's hostname will - be sent to the DHCP server.</para> + <para>When true (the default), the machine's hostname will be sent to the DHCP server. + Note that the machine's hostname must consist only of 7-bit ASCII lower-case characters and + no spaces or dots, and be formatted as a valid DNS domain name. Otherwise, the hostname is not + sent even if this is set to true.</para> </listitem> </varlistentry> <varlistentry> <term><varname>UseHostname=</varname></term> <listitem> <para>When true (the default), the hostname received from - the DHCP server will be set as the transient hostname of the system + the DHCP server will be set as the transient hostname of the system. </para> </listitem> </varlistentry> <varlistentry> - <term><varname>Hostname=</varname></term> - <listitem> - <para>Use this value for the hostname which is sent to the - DHCP server, instead of machine's hostname.</para> - </listitem> - </varlistentry> + <term><varname>Hostname=</varname></term> + <listitem> + <para>Use this value for the hostname which is sent to the DHCP server, instead of machine's hostname. + Note that the specified hostname must consist only of 7-bit ASCII lower-case characters and + no spaces or dots, and be formatted as a valid DNS domain name.</para> + </listitem> + </varlistentry> <varlistentry> <term><varname>UseDomains=</varname></term> <listitem> - <para>Takes a boolean argument, or the special value <literal>route</literal>. When true, the domain name + <para>Takes a boolean, or the special value <literal>route</literal>. When true, the domain name received from the DHCP server will be used as DNS search domain over this link, similar to the effect of the <option>Domains=</option> setting. If set to <literal>route</literal>, the domain name received from the DHCP server will be used for routing DNS queries only, but not for searching, similar to the effect of @@ -1350,7 +1428,7 @@ <varlistentry> <term><varname>RapidCommit=</varname></term> <listitem> - <para>A boolean. The DHCPv6 client can obtain configuration parameters from a DHCPv6 server through + <para>Takes a boolean. The DHCPv6 client can obtain configuration parameters from a DHCPv6 server through a rapid two-message exchange (solicit and reply). When the rapid commit option is enabled by both the DHCPv6 client and the DHCPv6 server, the two-message exchange is used, rather than the default four-method exchange (solicit, advertise, request, and reply). The two-message exchange provides @@ -1360,6 +1438,22 @@ </listitem> </varlistentry> + <varlistentry> + <term><varname>ForceDHCPv6PDOtherInformation=</varname></term> + <listitem> + <para>Takes a boolean that enforces DHCPv6 stateful mode when the 'Other information' bit is set in + Router Advertisement messages. By default setting only the 'O' bit in Router Advertisements + makes DHCPv6 request network information in a stateless manner using a two-message Information + Request and Information Reply message exchange. + <ulink url="https://tools.ietf.org/html/rfc7084">RFC 7084</ulink>, requirement WPD-4, updates + this behavior for a Customer Edge router so that stateful DHCPv6 Prefix Delegation is also + requested when only the 'O' bit is set in Router Advertisements. This option enables such a CE + behavior as it is impossible to automatically distinguish the intention of the 'O' bit otherwise. + By default this option is set to 'false', enable it if no prefixes are delegated when the device + should be acting as a CE router.</para> + </listitem> + </varlistentry> + </variablelist> </refsect1> @@ -1384,7 +1478,7 @@ <varlistentry> <term><varname>UseDomains=</varname></term> <listitem> - <para>Takes a boolean argument, or the special value <literal>route</literal>. When true, the domain name + <para>Takes a boolean, or the special value <literal>route</literal>. When true, the domain name received via IPv6 Router Advertisement (RA) will be used as DNS search domain over this link, similar to the effect of the <option>Domains=</option> setting. If set to <literal>route</literal>, the domain name received via IPv6 RA will be used for routing DNS queries only, but not for searching, similar to the @@ -1460,11 +1554,9 @@ <term><varname>EmitDNS=</varname></term> <term><varname>DNS=</varname></term> - <listitem><para>Configures whether the DHCP leases handed out - to clients shall contain DNS server information. The - <varname>EmitDNS=</varname> setting takes a boolean argument - and defaults to <literal>yes</literal>. The DNS servers to - pass to clients may be configured with the + <listitem><para>Takes a boolean. Configures whether the DHCP leases handed out + to clients shall contain DNS server information. Defaults to <literal>yes</literal>. + The DNS servers to pass to clients may be configured with the <varname>DNS=</varname> option, which takes a list of IPv4 addresses. If the <varname>EmitDNS=</varname> option is enabled but no servers configured, the servers are @@ -1511,10 +1603,8 @@ <term><varname>EmitTimezone=</varname></term> <term><varname>Timezone=</varname></term> - <listitem><para>Configures whether the DHCP leases handed out - to clients shall contain timezone information. The - <varname>EmitTimezone=</varname> setting takes a boolean - argument and defaults to <literal>yes</literal>. The + <listitem><para>Takes a boolean. Configures whether the DHCP leases handed out + to clients shall contain timezone information. Defaults to <literal>yes</literal>. The <varname>Timezone=</varname> setting takes a timezone string (such as <literal>Europe/Berlin</literal> or <literal>UTC</literal>) to pass to clients. If no explicit @@ -1540,11 +1630,11 @@ <term><varname>Managed=</varname></term> <term><varname>OtherInformation=</varname></term> - <listitem><para>Controls whether a DHCPv6 server is used to acquire IPv6 - addresses on the network link when <varname>Managed=</varname> boolean + <listitem><para>Takes a boolean. Controls whether a DHCPv6 server is used to acquire IPv6 + addresses on the network link when <varname>Managed=</varname> is set to <literal>true</literal> or if only additional network information can be obtained via DHCPv6 for the network link when - <varname>OtherInformation=</varname> boolean is set to + <varname>OtherInformation=</varname> is set to <literal>true</literal>. Both settings default to <literal>false</literal>, which means that a DHCPv6 server is not being used.</para></listitem> @@ -1553,10 +1643,9 @@ <varlistentry> <term><varname>RouterLifetimeSec=</varname></term> - <listitem><para>Configures the IPv6 router lifetime in seconds. If set, + <listitem><para>Takes a timespan. Configures the IPv6 router lifetime in seconds. If set, this host also announces itself in Router Advertisements as an IPv6 - router for the network link. Defaults to unset, which means the host is - not acting as a router.</para> + router for the network link. When unset, the host is not acting as a router.</para> </listitem> </varlistentry> @@ -1630,7 +1719,7 @@ <term><varname>AddressAutoconfiguration=</varname></term> <term><varname>OnLink=</varname></term> - <listitem><para>Boolean values to specify whether IPv6 addresses can be + <listitem><para>Takes a boolean to specify whether IPv6 addresses can be autoconfigured with this prefix and whether the prefix can be used for onlink determination. Both settings default to <literal>true</literal> in order to ease configuration. @@ -1670,42 +1759,51 @@ <varlistentry> <term><varname>UnicastFlood=</varname></term> <listitem> - <para>A boolean. Controls whether the bridge should flood + <para>Takes a boolean. Controls whether the bridge should flood traffic for which an FDB entry is missing and the destination - is unknown through this port. Defaults to unset. + is unknown through this port. When unset, the kernel's default will be used. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MulticastToUnicast=</varname></term> + <listitem> + <para>Takes a boolean. Multicast to unicast works on top of the multicast snooping feature of + the bridge. Which means unicast copies are only delivered to hosts which are interested in it. + When unset, the kernel's default will be used. </para> </listitem> </varlistentry> <varlistentry> <term><varname>HairPin=</varname></term> <listitem> - <para>A boolean. Configures whether traffic may be sent back - out of the port on which it was received. Defaults to unset. When this - flag is false, and the bridge will not forward traffic back - out of the receiving port.</para> + <para>Takes a boolean. Configures whether traffic may be sent back + out of the port on which it was received. When this flag is false, and the bridge + will not forward traffic back out of the receiving port. + When unset, the kernel's default will be used.</para> </listitem> </varlistentry> <varlistentry> <term><varname>UseBPDU=</varname></term> <listitem> - <para>A boolean. Configures whether STP Bridge Protocol Data Units will be - processed by the bridge port. Defaults to unset.</para> + <para>Takes a boolean. Configures whether STP Bridge Protocol Data Units will be + processed by the bridge port. When unset, the kernel's default will be used.</para> </listitem> </varlistentry> <varlistentry> <term><varname>FastLeave=</varname></term> <listitem> - <para>A boolean. This flag allows the bridge to immediately stop multicast + <para>Takes a boolean. This flag allows the bridge to immediately stop multicast traffic on a port that receives an IGMP Leave message. It is only used with - IGMP snooping if enabled on the bridge. Defaults to unset.</para> + IGMP snooping if enabled on the bridge. When unset, the kernel's default will be used.</para> </listitem> </varlistentry> <varlistentry> <term><varname>AllowPortToBeRoot=</varname></term> <listitem> - <para>A boolean. Configures whether a given port is allowed to + <para>Takes a boolean. Configures whether a given port is allowed to become a root port. Only used when STP is enabled on the bridge. - Defaults to unset.</para> + When unset, the kernel's default will be used.</para> </listitem> </varlistentry> <varlistentry> diff --git a/man/systemd.nspawn.xml b/man/systemd.nspawn.xml index 4a263d376d..f978fef235 100644 --- a/man/systemd.nspawn.xml +++ b/man/systemd.nspawn.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ <!ENTITY % entities SYSTEM "custom-entities.ent" > @@ -127,6 +127,16 @@ </varlistentry> <varlistentry> + <term><varname>Ephemeral=</varname></term> + + <listitem><para>Takes a boolean argument, which defaults to off, If enabled, the container is run with + a temporary snapshot of its file system that is removed immediately when the container terminates. + This is equivalent to the <option>--ephemeral</option> command line switch. See + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> for details + about the specific options supported.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>ProcessTwo=</varname></term> <listitem><para>Takes a boolean argument, which defaults to off. If enabled, the specified program is run as @@ -340,7 +350,7 @@ <term><varname>Timezone=</varname></term> <listitem><para>Configures how <filename>/etc/localtime</filename> in the container shall be handled. This is - equivalent to the <option>--localtime=</option> command line switch, and takes the same argument. See + equivalent to the <option>--timezone=</option> command line switch, and takes the same argument. See <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> for details.</para></listitem> </varlistentry> diff --git a/man/systemd.offline-updates.xml b/man/systemd.offline-updates.xml index 113d74a220..13fdfc28de 100644 --- a/man/systemd.offline-updates.xml +++ b/man/systemd.offline-updates.xml @@ -134,7 +134,7 @@ </listitem> <listitem> - <para>The update service should declare <varname>DefaultDependencies=false</varname>, + <para>The update service should declare <varname>DefaultDependencies=no</varname>, <varname>Requires=sysinit.target</varname>, <varname>After=sysinit.target</varname>, <varname>After=system-update-pre.target</varname> and explicitly pull in any other services it requires.</para> diff --git a/man/systemd.resource-control.xml b/man/systemd.resource-control.xml index 370c110592..aa7d9bcd59 100644 --- a/man/systemd.resource-control.xml +++ b/man/systemd.resource-control.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -176,8 +176,6 @@ the startup phase. Using <varname>StartupCPUWeight=</varname> allows prioritizing specific services at boot-up differently than during normal runtime.</para> - <para>Implies <literal>CPUAccounting=true</literal>.</para> - <para>These settings replace <varname>CPUShares=</varname> and <varname>StartupCPUShares=</varname>.</para> </listitem> </varlistentry> @@ -192,12 +190,11 @@ <literal>cpu.max</literal> attribute on the unified control group hierarchy and <literal>cpu.cfs_quota_us</literal> on legacy. For details about these control group attributes, see <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink> and <ulink - url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>.</para> + url="https://www.kernel.org/doc/Documentation/scheduler/sched-bwc.txt">sched-bwc.txt</ulink>.</para> <para>Example: <varname>CPUQuota=20%</varname> ensures that the executed processes will never get more than 20% CPU time on one CPU.</para> - <para>Implies <literal>CPUAccounting=true</literal>.</para> </listitem> </varlistentry> @@ -217,6 +214,25 @@ </varlistentry> <varlistentry> + <term><varname>MemoryMin=<replaceable>bytes</replaceable></varname></term> + + <listitem> + <para>Specify the memory usage protection of the executed processes in this unit. If the memory usages of + this unit and all its ancestors are below their minimum boundaries, this unit's memory won't be reclaimed.</para> + + <para>Takes a memory size in bytes. If the value is suffixed with K, M, G or T, the specified memory size is + parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. Alternatively, a + percentage value may be specified, which is taken relative to the installed physical memory on the + system. This controls the <literal>memory.min</literal> control group attribute. For details about this + control group attribute, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para> + + <para>This setting is supported only if the unified control group hierarchy is used and disables + <varname>MemoryLimit=</varname>.</para> + </listitem> + </varlistentry> + + <varlistentry> <term><varname>MemoryLow=<replaceable>bytes</replaceable></varname></term> <listitem> @@ -231,8 +247,6 @@ control group attribute, see <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para> - <para>Implies <literal>MemoryAccounting=true</literal>.</para> - <para>This setting is supported only if the unified control group hierarchy is used and disables <varname>MemoryLimit=</varname>.</para> </listitem> @@ -254,8 +268,6 @@ <literal>memory.high</literal> control group attribute. For details about this control group attribute, see <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para> - <para>Implies <literal>MemoryAccounting=true</literal>.</para> - <para>This setting is supported only if the unified control group hierarchy is used and disables <varname>MemoryLimit=</varname>.</para> </listitem> @@ -277,8 +289,6 @@ <literal>memory.max</literal> control group attribute. For details about this control group attribute, see <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para> - <para>Implies <literal>MemoryAccounting=true</literal>.</para> - <para>This setting replaces <varname>MemoryLimit=</varname>.</para> </listitem> </varlistentry> @@ -295,8 +305,6 @@ <literal>memory.swap.max</literal> control group attribute. For details about this control group attribute, see <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para> - <para>Implies <literal>MemoryAccounting=true</literal>.</para> - <para>This setting is supported only if the unified control group hierarchy is used and disables <varname>MemoryLimit=</varname>.</para> </listitem> @@ -332,7 +340,7 @@ the <literal>pids.max</literal> control group attribute. For details about this control group attribute, see <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/pids.txt">pids.txt</ulink>.</para> - <para>Implies <literal>TasksAccounting=true</literal>. The + <para>The system default for this setting may be controlled with <varname>DefaultTasksMax=</varname> in <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> @@ -374,8 +382,6 @@ phase. This allows prioritizing specific services at boot-up differently than during runtime.</para> - <para>Implies <literal>IOAccounting=true</literal>.</para> - <para>These settings replace <varname>BlockIOWeight=</varname> and <varname>StartupBlockIOWeight=</varname> and disable settings prefixed with <varname>BlockIO</varname> or <varname>StartupBlockIO</varname>.</para> </listitem> @@ -387,15 +393,13 @@ <listitem> <para>Set the per-device overall block I/O weight for the executed processes, if the unified control group hierarchy is used on the system. Takes a space-separated pair of a file path and a weight value to specify - the device specific weight value, between 1 and 10000. (Example: "/dev/sda 1000"). The file path may be - specified as path to a block device node or as any other file, in which case the backing block device of the - file system of the file is determined. This controls the <literal>io.weight</literal> control group - attribute, which defaults to 100. Use this option multiple times to set weights for multiple devices. For - details about this control group attribute, see <ulink + the device specific weight value, between 1 and 10000. (Example: <literal>/dev/sda 1000</literal>). The file + path may be specified as path to a block device node or as any other file, in which case the backing block + device of the file system of the file is determined. This controls the <literal>io.weight</literal> control + group attribute, which defaults to 100. Use this option multiple times to set weights for multiple devices. + For details about this control group attribute, see <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para> - <para>Implies <literal>IOAccounting=true</literal>.</para> - <para>This setting replaces <varname>BlockIODeviceWeight=</varname> and disables settings prefixed with <varname>BlockIO</varname> or <varname>StartupBlockIO</varname>.</para> </listitem> @@ -419,8 +423,6 @@ url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>. </para> - <para>Implies <literal>IOAccounting=true</literal>.</para> - <para>These settings replace <varname>BlockIOReadBandwidth=</varname> and <varname>BlockIOWriteBandwidth=</varname> and disable settings prefixed with <varname>BlockIO</varname> or <varname>StartupBlockIO</varname>.</para> @@ -445,14 +447,31 @@ url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>. </para> - <para>Implies <literal>IOAccounting=true</literal>.</para> - <para>These settings are supported only if the unified control group hierarchy is used and disable settings prefixed with <varname>BlockIO</varname> or <varname>StartupBlockIO</varname>.</para> </listitem> </varlistentry> <varlistentry> + <term><varname>IODeviceLatencyTargetSec=<replaceable>device</replaceable> <replaceable>target</replaceable></varname></term> + + <listitem> + <para>Set the per-device average target I/O latency for the executed processes, if the unified control group + hierarchy is used on the system. Takes a file path and a timespan separated by a space to specify + the device specific latency target. (Example: "/dev/sda 25ms"). The file path may be specified + as path to a block device node or as any other file, in which case the backing block device of the file + system of the file is determined. This controls the <literal>io.latency</literal> control group + attribute. Use this option multiple times to set latency target for multiple devices. For details about this + control group attribute, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para> + + <para>Implies <literal>IOAccounting=yes</literal>.</para> + + <para>These settings are supported only if the unified control group hierarchy is used.</para> + </listitem> + </varlistentry> + + <varlistentry> <term><varname>IPAccounting=</varname></term> <listitem> @@ -711,9 +730,33 @@ specific to the unified hierarchy while others are specific to the legacy hierarchy. Also note that the kernel might support further controllers, which aren't covered here yet as delegation is either not supported at all for them or not defined cleanly.</para> + + <para>For further details on the delegation model consult <ulink + url="https://systemd.io/CGROUP_DELEGATION">Control Group APIs and Delegation</ulink>.</para> </listitem> </varlistentry> + <varlistentry> + <term><varname>DisableControllers=</varname></term> + + <listitem> + <para>Disables controllers from being enabled for a unit's children. If a controller listed is already in use + in its subtree, the controller will be removed from the subtree. This can be used to avoid child units being + able to implicitly or explicitly enable a controller. Defaults to not disabling any controllers.</para> + + <para>It may not be possible to successfully disable a controller if the unit or any child of the unit in + question delegates controllers to its children, as any delegated subtree of the cgroup hierarchy is unmanaged + by systemd.</para> + + <para>Multiple controllers may be specified, separated by spaces. You may also pass + <varname>DisableControllers=</varname> multiple times, in which case each new instance adds another controller + to disable. Passing <varname>DisableControllers=</varname> by itself with no controller name present resets + the disabled controller list.</para> + + <para>Valid controllers are <option>cpu</option>, <option>cpuacct</option>, <option>io</option>, + <option>blkio</option>, <option>memory</option>, <option>devices</option>, and <option>pids</option>.</para> + </listitem> + </varlistentry> </variablelist> </refsect1> @@ -741,7 +784,7 @@ the startup phase. Using <varname>StartupCPUShares=</varname> allows prioritizing specific services at boot-up differently than during normal runtime.</para> - <para>Implies <literal>CPUAccounting=true</literal>.</para> + <para>Implies <literal>CPUAccounting=yes</literal>.</para> <para>These settings are deprecated. Use <varname>CPUWeight=</varname> and <varname>StartupCPUWeight=</varname> instead.</para> @@ -762,7 +805,7 @@ attribute, see <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt">memory.txt</ulink>.</para> - <para>Implies <literal>MemoryAccounting=true</literal>.</para> + <para>Implies <literal>MemoryAccounting=yes</literal>.</para> <para>This setting is deprecated. Use <varname>MemoryMax=</varname> instead.</para> </listitem> @@ -803,7 +846,7 @@ boot-up differently than during runtime.</para> <para>Implies - <literal>BlockIOAccounting=true</literal>.</para> + <literal>BlockIOAccounting=yes</literal>.</para> <para>These settings are deprecated. Use <varname>IOWeight=</varname> and <varname>StartupIOWeight=</varname> instead.</para> @@ -825,7 +868,7 @@ url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>.</para> <para>Implies - <literal>BlockIOAccounting=true</literal>.</para> + <literal>BlockIOAccounting=yes</literal>.</para> <para>This setting is deprecated. Use <varname>IODeviceWeight=</varname> instead.</para> </listitem> @@ -850,7 +893,7 @@ </para> <para>Implies - <literal>BlockIOAccounting=true</literal>.</para> + <literal>BlockIOAccounting=yes</literal>.</para> <para>These settings are deprecated. Use <varname>IOReadBandwidthMax=</varname> and <varname>IOWriteBandwidthMax=</varname> instead.</para> @@ -879,6 +922,7 @@ <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/cpuacct.txt">cpuacct.txt</ulink>, <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt">memory.txt</ulink>, <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>. + <ulink url="https://www.kernel.org/doc/Documentation/scheduler/sched-bwc.txt">sched-bwc.txt</ulink>. </para> </refsect1> </refentry> diff --git a/man/systemd.scope.xml b/man/systemd.scope.xml index cc0345abac..18560fb7ee 100644 --- a/man/systemd.scope.xml +++ b/man/systemd.scope.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/systemd.service.xml b/man/systemd.service.xml index add54524ce..ad04efeb34 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -153,77 +153,93 @@ <varlistentry> <term><varname>Type=</varname></term> - <listitem><para>Configures the process start-up type for this - service unit. One of - <option>simple</option>, - <option>forking</option>, - <option>oneshot</option>, - <option>dbus</option>, - <option>notify</option> or - <option>idle</option>.</para> - - <para>If set to <option>simple</option> (the default if - neither <varname>Type=</varname> nor - <varname>BusName=</varname>, but <varname>ExecStart=</varname> - are specified), it is expected that the process configured - with <varname>ExecStart=</varname> is the main process of the - service. In this mode, if the process offers functionality to - other processes on the system, its communication channels - should be installed before the daemon is started up (e.g. - sockets set up by systemd, via socket activation), as systemd - will immediately proceed starting follow-up units.</para> - - <para>If set to <option>forking</option>, it is expected that - the process configured with <varname>ExecStart=</varname> will - call <function>fork()</function> as part of its start-up. The - parent process is expected to exit when start-up is complete - and all communication channels are set up. The child continues - to run as the main daemon process. This is the behavior of - traditional UNIX daemons. If this setting is used, it is - recommended to also use the <varname>PIDFile=</varname> - option, so that systemd can identify the main process of the - daemon. systemd will proceed with starting follow-up units as - soon as the parent process exits.</para> - - <para>Behavior of <option>oneshot</option> is similar to - <option>simple</option>; however, it is expected that the - process has to exit before systemd starts follow-up units. - <varname>RemainAfterExit=</varname> is particularly useful for - this type of service. This is the implied default if neither - <varname>Type=</varname> nor <varname>ExecStart=</varname> are - specified.</para> - - <para>Behavior of <option>dbus</option> is similar to - <option>simple</option>; however, it is expected that the - daemon acquires a name on the D-Bus bus, as configured by - <varname>BusName=</varname>. systemd will proceed with - starting follow-up units after the D-Bus bus name has been - acquired. Service units with this option configured implicitly - gain dependencies on the <filename>dbus.socket</filename> - unit. This type is the default if <varname>BusName=</varname> - is specified.</para> - - <para>Behavior of <option>notify</option> is similar to - <option>simple</option>; however, it is expected that the - daemon sends a notification message via - <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> - or an equivalent call when it has finished starting up. - systemd will proceed with starting follow-up units after this - notification message has been sent. If this option is used, - <varname>NotifyAccess=</varname> (see below) should be set to - open access to the notification socket provided by systemd. If - <varname>NotifyAccess=</varname> is missing or set to - <option>none</option>, it will be forcibly set to - <option>main</option>. Note that currently - <varname>Type=</varname><option>notify</option> will not work - if used in combination with - <varname>PrivateNetwork=</varname><option>yes</option>.</para> - - <para>Behavior of <option>idle</option> is very similar to <option>simple</option>; however, actual execution - of the service program is delayed until all active jobs are dispatched. This may be used to avoid interleaving - of output of shell services with the status output on the console. Note that this type is useful only to - improve console output, it is not useful as a general unit ordering tool, and the effect of this service type - is subject to a 5s time-out, after which the service program is invoked anyway.</para> + <listitem> + <para>Configures the process start-up type for this service unit. One of <option>simple</option>, + <option>exec</option>, <option>forking</option>, <option>oneshot</option>, <option>dbus</option>, + <option>notify</option> or <option>idle</option>:</para> + + <itemizedlist> + <listitem><para>If set to <option>simple</option> (the default if <varname>ExecStart=</varname> is + specified but neither <varname>Type=</varname> nor <varname>BusName=</varname> are), the service manager + will consider the unit started immediately after the main service process has been forked off. It is + expected that the process configured with <varname>ExecStart=</varname> is the main process of the + service. In this mode, if the process offers functionality to other processes on the system, its + communication channels should be installed before the service is started up (e.g. sockets set up by + systemd, via socket activation), as the service manager will immediately proceed starting follow-up units, + right after creating the main service process, and before executing the service's binary. Note that this + means <command>systemctl start</command> command lines for <option>simple</option> services will report + success even if the service's binary cannot be invoked successfully (for example because the selected + <varname>User=</varname> doesn't exist, or the service binary is missing).</para></listitem> + + <listitem><para>The <option>exec</option> type is similar to <option>simple</option>, but the service + manager will consider the unit started immediately after the main service binary has been executed. The service + manager will delay starting of follow-up units until that point. (Or in other words: + <option>simple</option> proceeds with further jobs right after <function>fork()</function> returns, while + <option>exec</option> will not proceed before both <function>fork()</function> and + <function>execve()</function> in the service process succeeded.) Note that this means <command>systemctl + start</command> command lines for <option>exec</option> services will report failure when the service's + binary cannot be invoked successfully (for example because the selected <varname>User=</varname> doesn't + exist, or the service binary is missing).</para></listitem> + + <listitem><para>If set to <option>forking</option>, it is expected that the process configured with + <varname>ExecStart=</varname> will call <function>fork()</function> as part of its start-up. The parent + process is expected to exit when start-up is complete and all communication channels are set up. The child + continues to run as the main service process, and the service manager will consider the unit started when + the parent process exits. This is the behavior of traditional UNIX services. If this setting is used, it is + recommended to also use the <varname>PIDFile=</varname> option, so that systemd can reliably identify the + main process of the service. systemd will proceed with starting follow-up units as soon as the parent + process exits.</para></listitem> + + <listitem><para>Behavior of <option>oneshot</option> is similar to <option>simple</option>; however, the + service manager will consider the unit started after the main process exits. It will then start follow-up + units. <varname>RemainAfterExit=</varname> is particularly useful for this type of + service. <varname>Type=</varname><option>oneshot</option> is the implied default if neither + <varname>Type=</varname> nor <varname>ExecStart=</varname> are specified.</para></listitem> + + <listitem><para>Behavior of <option>dbus</option> is similar to <option>simple</option>; however, it is + expected that the service acquires a name on the D-Bus bus, as configured by + <varname>BusName=</varname>. systemd will proceed with starting follow-up units after the D-Bus bus name + has been acquired. Service units with this option configured implicitly gain dependencies on the + <filename>dbus.socket</filename> unit. This type is the default if <varname>BusName=</varname> is + specified.</para></listitem> + + <listitem><para>Behavior of <option>notify</option> is similar to <option>exec</option>; however, it is + expected that the service sends a notification message via + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> or an + equivalent call when it has finished starting up. systemd will proceed with starting follow-up units after + this notification message has been sent. If this option is used, <varname>NotifyAccess=</varname> (see + below) should be set to open access to the notification socket provided by systemd. If + <varname>NotifyAccess=</varname> is missing or set to <option>none</option>, it will be forcibly set to + <option>main</option>. Note that currently <varname>Type=</varname><option>notify</option> will not work if + used in combination with <varname>PrivateNetwork=</varname><option>yes</option>.</para></listitem> + + <listitem><para>Behavior of <option>idle</option> is very similar to <option>simple</option>; however, + actual execution of the service program is delayed until all active jobs are dispatched. This may be used + to avoid interleaving of output of shell services with the status output on the console. Note that this + type is useful only to improve console output, it is not useful as a general unit ordering tool, and the + effect of this service type is subject to a 5s timeout, after which the service program is invoked + anyway.</para></listitem> + </itemizedlist> + + <para>It is generally recommended to use <varname>Type=</varname><option>simple</option> for long-running + services whenever possible, as it is the simplest and fastest option. However, as this service type won't + propagate service start-up failures and doesn't allow ordering of other units against completion of + initialization of the service (which for example is useful if clients need to connect to the service through + some form of IPC, and the IPC channel is only established by the service itself — in contrast to doing this + ahead of time through socket or bus activation or similar), it might not be sufficient for many cases. If so, + <option>notify</option> or <option>dbus</option> (the latter only in case the service provides a D-Bus + interface) are the preferred options as they allow service program code to precisely schedule when to + consider the service started up successfully and when to proceed with follow-up units. The + <option>notify</option> service type requires explicit support in the service codebase (as + <function>sd_notify()</function> or an equivalent API needs to be invoked by the service at the appropriate + time) — if it's not supported, then <option>forking</option> is an alternative: it supports the traditional + UNIX service start-up protocol. Finally, <option>exec</option> might be an option for cases where it is + enough to ensure the service binary is invoked, and where the service binary itself executes no or little + initialization on its own (and its initialization is unlikely to fail). Note that using any type other than + <option>simple</option> possibly delays the boot process, as the service manager needs to wait for service + initialization to complete. It is hence recommended not to needlessly use any types other than + <option>simple</option>. (Also note it is generally not recommended to use <option>idle</option> or + <option>oneshot</option> for long-running services.)</para> </listitem> </varlistentry> @@ -256,14 +272,15 @@ <varlistentry> <term><varname>PIDFile=</varname></term> - <listitem><para>Takes an absolute path referring to the PID file of the service. Usage of this option is - recommended for services where <varname>Type=</varname> is set to <option>forking</option>. The service manager - will read the PID of the main process of the service from this file after start-up of the service. The service - manager will not write to the file configured here, although it will remove the file after the service has shut - down if it still exists. The PID file does not need to be owned by a privileged user, but if it is owned by an - unprivileged user additional safety restrictions are enforced: the file may not be a symlink to a file owned by - a different user (neither directly nor indirectly), and the PID file must refer to a process already belonging - to the service.</para></listitem> + <listitem><para>Takes a path referring to the PID file of the service. Usage of this option is recommended for + services where <varname>Type=</varname> is set to <option>forking</option>. The path specified typically points + to a file below <filename>/run/</filename>. If a relative path is specified it is hence prefixed with + <filename>/run/</filename>. The service manager will read the PID of the main process of the service from this + file after start-up of the service. The service manager will not write to the file configured here, although it + will remove the file after the service has shut down if it still exists. The PID file does not need to be owned + by a privileged user, but if it is owned by an unprivileged user additional safety restrictions are enforced: + the file may not be a symlink to a file owned by a different user (neither directly nor indirectly), and the + PID file must refer to a process already belonging to the service.</para></listitem> </varlistentry> <varlistentry> @@ -318,7 +335,7 @@ <row> <entry><literal>-</literal></entry> - <entry>If the executable path is prefixed with <literal>-</literal>, an exit code of the command normally considered a failure (i.e. non-zero exit status or abnormal exit due to signal) is ignored and considered success.</entry> + <entry>If the executable path is prefixed with <literal>-</literal>, an exit code of the command normally considered a failure (i.e. non-zero exit status or abnormal exit due to signal) is recorded, but has no further effect and is considered equivalent to success.</entry> </row> <row> @@ -583,7 +600,8 @@ "keep-alive ping"). If the time between two such calls is larger than the configured time, then the service is placed in a failed state and it will be terminated with - <constant>SIGABRT</constant>. By setting + <constant>SIGABRT</constant> (or the signal specified by + <varname>WatchdogSignal=</varname>). By setting <varname>Restart=</varname> to <option>on-failure</option>, <option>on-watchdog</option>, <option>on-abnormal</option> or <option>always</option>, the service will be automatically @@ -815,24 +833,6 @@ </varlistentry> <varlistentry> - <term><varname>PermissionsStartOnly=</varname></term> - <listitem><para>Takes a boolean argument. If true, the - permission-related execution options, as configured with - <varname>User=</varname> and similar options (see - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more information), are only applied to the process started - with - <varname>ExecStart=</varname>, and not to the various other - <varname>ExecStartPre=</varname>, - <varname>ExecStartPost=</varname>, - <varname>ExecReload=</varname>, - <varname>ExecStop=</varname>, and - <varname>ExecStopPost=</varname> - commands. If false, the setting is applied to all configured - commands the same way. Defaults to false.</para></listitem> - </varlistentry> - - <varlistentry> <term><varname>RootDirectoryStartOnly=</varname></term> <listitem><para>Takes a boolean argument. If true, the root directory, as configured with the diff --git a/man/systemd.slice.xml b/man/systemd.slice.xml index 37bee0ea4c..43e7c6a73a 100644 --- a/man/systemd.slice.xml +++ b/man/systemd.slice.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml index 19c2ca9907..fb51ef6658 100644 --- a/man/systemd.socket.xml +++ b/man/systemd.socket.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -68,8 +68,8 @@ or it must be a template unit named the same way. Example: a socket file <filename>foo.socket</filename> needs a matching service <filename>foo.service</filename> if - <option>Accept=false</option> is set. If - <option>Accept=true</option> is set, a service template file + <option>Accept=no</option> is set. If + <option>Accept=yes</option> is set, a service template file <filename>foo@.service</filename> must exist from which services are instantiated for each incoming connection.</para> @@ -94,6 +94,18 @@ socket passing (i.e. sockets passed in via standard input and output, using <varname>StandardInput=socket</varname> in the service file).</para> + + <para>All network sockets allocated through <filename>.socket</filename> units are allocated in the host's network + namespace (see <citerefentry + project='man-pages'><refentrytitle>network_namespaces</refentrytitle><manvolnum>7</manvolnum></citerefentry>). This + does not mean however that the service activated by a configured socket unit has to be part of the host's network + namespace as well. It is supported and even good practice to run services in their own network namespace (for + example through <varname>PrivateNetwork=</varname>, see + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>), receiving only + the sockets configured through socket-activation from the host's namespace. In such a set-up communication within + the host's network namespace is only permitted through the activation sockets passed in while all sockets allocated + from the service code itself will be associated with the service's own namespace, and thus possibly subject to a a + much more restrictive configuration.</para> </refsect1> <refsect1> @@ -303,7 +315,7 @@ <varlistentry> <term><varname>SocketProtocol=</varname></term> - <listitem><para>Takes a one of <option>udplite</option> + <listitem><para>Takes one of <option>udplite</option> or <option>sctp</option>. Specifies a socket protocol (<constant>IPPROTO_UDPLITE</constant>) UDP-Lite (<constant>IPPROTO_SCTP</constant>) SCTP socket respectively. </para> @@ -312,7 +324,7 @@ <varlistentry> <term><varname>BindIPv6Only=</varname></term> - <listitem><para>Takes a one of <option>default</option>, + <listitem><para>Takes one of <option>default</option>, <option>both</option> or <option>ipv6-only</option>. Controls the IPV6_V6ONLY socket option (see <citerefentry project='die-net'><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry> @@ -395,17 +407,17 @@ incoming traffic. Defaults to <option>false</option>. For performance reasons, it is recommended to write new daemons only in a way that is suitable for - <option>Accept=false</option>. A daemon listening on an + <option>Accept=no</option>. A daemon listening on an <constant>AF_UNIX</constant> socket may, but does not need to, call <citerefentry><refentrytitle>close</refentrytitle><manvolnum>2</manvolnum></citerefentry> on the received socket before exiting. However, it must not unlink the socket from a file system. It should not invoke <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>2</manvolnum></citerefentry> - on sockets it got with <varname>Accept=false</varname>, but it + on sockets it got with <varname>Accept=no</varname>, but it may do so for sockets it got with - <varname>Accept=true</varname> set. Setting - <varname>Accept=true</varname> is mostly useful to allow + <varname>Accept=yes</varname> set. Setting + <varname>Accept=yes</varname> is mostly useful to allow daemons designed for usage with <citerefentry project='freebsd'><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry> to work unmodified with systemd socket @@ -429,11 +441,11 @@ <term><varname>MaxConnections=</varname></term> <listitem><para>The maximum number of connections to simultaneously run services instances for, when - <option>Accept=true</option> is set. If more concurrent + <option>Accept=yes</option> is set. If more concurrent connections are coming in, they will be refused until at least one existing connection is terminated. This setting has no effect on sockets configured with - <option>Accept=false</option> or datagram sockets. Defaults to + <option>Accept=no</option> or datagram sockets. Defaults to 64.</para></listitem> </varlistentry> diff --git a/man/systemd.special.xml b/man/systemd.special.xml index fb12805fff..fd5639ba03 100644 --- a/man/systemd.special.xml +++ b/man/systemd.special.xml @@ -29,6 +29,7 @@ <filename>cryptsetup-pre.target</filename>, <filename>cryptsetup.target</filename>, <filename>ctrl-alt-del.target</filename>, + <filename>boot-complete.target</filename>, <filename>default.target</filename>, <filename>emergency.target</filename>, <filename>exit.target</filename>, @@ -104,942 +105,990 @@ </refsect1> <refsect1> - <title>Special System Units</title> - - <variablelist> - <varlistentry> - <term><filename>-.mount</filename></term> - <listitem> - <para>The root mount point, i.e. the mount unit for the <filename>/</filename> path. This unit is - unconditionally active, during the entire time the system is up, as this mount point is where the basic - userspace is running from.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>basic.target</filename></term> - <listitem> - <para>A special target unit covering basic boot-up.</para> - - <para>systemd automatically adds dependency of the type - <varname>After=</varname> for this target unit to all - services (except for those with - <varname>DefaultDependencies=no</varname>).</para> - - <para>Usually, this should pull-in all local mount points plus - <filename>/var</filename>, <filename>/tmp</filename> and - <filename>/var/tmp</filename>, swap devices, sockets, timers, - path units and other basic initialization necessary for general - purpose daemons. The mentioned mount points are special cased - to allow them to be remote. - </para> - - <para>This target usually does not pull in any non-target units - directly, but rather does so indirectly via other early boot targets. - It is instead meant as a synchronization point for late boot - services. Refer to - <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details on the targets involved. - </para> - - </listitem> - </varlistentry> - <varlistentry> - <term><filename>ctrl-alt-del.target</filename></term> - <listitem> - <para>systemd starts this target whenever Control+Alt+Del is - pressed on the console. Usually, this should be aliased - (symlinked) to <filename>reboot.target</filename>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>cryptsetup.target</filename></term> - <listitem> - <para>A target that pulls in setup services for all - encrypted block devices.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>dbus.service</filename></term> - <listitem> - <para>A special unit for the D-Bus bus daemon. As soon as - this service is fully started up systemd will connect to it - and register its service.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>dbus.socket</filename></term> - <listitem> - <para>A special unit for the D-Bus system bus socket. All - units with <varname>Type=dbus</varname> automatically gain a - dependency on this unit.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>default.target</filename></term> - <listitem> - <para>The default unit systemd starts at bootup. Usually, - this should be aliased (symlinked) to - <filename>multi-user.target</filename> or - <filename>graphical.target</filename>.</para> - - <para>The default unit systemd starts at bootup can be - overridden with the <varname>systemd.unit=</varname> kernel - command line option.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>display-manager.service</filename></term> - <listitem> - <para>The display manager service. Usually, this should be - aliased (symlinked) to <filename>gdm.service</filename> or a - similar display manager service.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>emergency.target</filename></term> - <listitem> - <para>A special target unit that starts an emergency shell on the main console. This target does not pull in - any services or mounts. It is the most minimal version of starting the system in order to acquire an - interactive shell; the only processes running are usually just the system manager (PID 1) and the shell - process. This unit is supposed to be used with the kernel command line option - <varname>systemd.unit=</varname>; it is also used when a file system check on a required file system fails, - and boot-up cannot continue. Compare with <filename>rescue.target</filename>, which serves a similar purpose, - but also starts the most basic services and mounts all file systems.</para> - - <para>Use the <literal>systemd.unit=emergency.target</literal> kernel command line option to boot into this - mode. A short alias for this kernel command line option is <literal>emergency</literal>, for compatibility - with SysV.</para> - - <para>In many ways booting into <filename>emergency.target</filename> is similar to the effect of booting - with <literal>init=/bin/sh</literal> on the kernel command line, except that emergency mode provides you with - the full system and service manager, and allows starting individual units in order to continue the boot - process in steps.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>exit.target</filename></term> - <listitem> - <para>A special service unit for shutting down the system or - user service manager. It is equivalent to - <filename>poweroff.target</filename> on non-container - systems, and also works in containers.</para> - - <para>systemd will start this unit when it receives the - <constant>SIGTERM</constant> or <constant>SIGINT</constant> - signal when running as user service daemon.</para> - - <para>Normally, this (indirectly) pulls in - <filename>shutdown.target</filename>, which in turn should be - conflicted by all units that want to be scheduled for - shutdown when the service manager starts to exit.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>final.target</filename></term> - <listitem> - <para>A special target unit that is used during the shutdown - logic and may be used to pull in late services after all - normal services are already terminated and all mounts - unmounted. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>getty.target</filename></term> - <listitem> - <para>A special target unit that pulls in statically - configured local TTY <filename>getty</filename> instances. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>graphical.target</filename></term> - <listitem> - <para>A special target unit for setting up a graphical login - screen. This pulls in - <filename>multi-user.target</filename>.</para> - - <para>Units that are needed for graphical logins shall add - <varname>Wants=</varname> dependencies for their unit to - this unit (or <filename>multi-user.target</filename>) during - installation. This is best configured via - <varname>WantedBy=graphical.target</varname> in the unit's - <literal>[Install]</literal> section.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>hibernate.target</filename></term> - <listitem> - <para>A special target unit for hibernating the system. This - pulls in <filename>sleep.target</filename>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>hybrid-sleep.target</filename></term> - <listitem> - <para>A special target unit for hibernating and suspending - the system at the same time. This pulls in - <filename>sleep.target</filename>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>suspend-then-hibernate.target</filename></term> - <listitem> - <para>A special target unit for suspending the system for a period - of time, waking it and putting it into hibernate. This pulls in - <filename>sleep.target</filename>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>halt.target</filename></term> - <listitem> - <para>A special target unit for shutting down and halting - the system. Note that this target is distinct from - <filename>poweroff.target</filename> in that it generally - really just halts the system rather than powering it - down.</para> - - <para>Applications wanting to halt the system should not start this unit - directly, but should instead execute <command>systemctl halt</command> - (possibly with the <option>--no-block</option> option) or call - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s - <command>org.freedesktop.systemd1.Manager.Halt</command> D-Bus method - directly.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>init.scope</filename></term> - <listitem> - <para>This scope unit is where the system and service manager (PID 1) itself resides. It is active as long as - the system is running.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>initrd-fs.target</filename></term> - <listitem> - <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry> - automatically adds dependencies of type - <varname>Before=</varname> to - <filename>sysroot-usr.mount</filename> and all mount points - found in <filename>/etc/fstab</filename> that have - <option>x-initrd.mount</option> and not have - <option>noauto</option> mount options set.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>initrd-root-device.target</filename></term> - <listitem> - <para>A special initrd target unit that is reached when the root filesystem device is available, but before - it has been mounted. - <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry> - automatically setup the appropriate dependencies to make this happen. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>initrd-root-fs.target</filename></term> - <listitem> - <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry> - automatically adds dependencies of type - <varname>Before=</varname> to the - <filename>sysroot.mount</filename> unit, which is generated - from the kernel command line. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>kbrequest.target</filename></term> - <listitem> - <para>systemd starts this target whenever Alt+ArrowUp is - pressed on the console. Note that any user with physical access - to the machine will be able to do this, without authentication, - so this should be used carefully.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>kexec.target</filename></term> - <listitem> - <para>A special target unit for shutting down and rebooting - the system via kexec.</para> - - <para>Applications wanting to reboot the system should not start this unit - directly, but should instead execute <command>systemctl kexec</command> - (possibly with the <option>--no-block</option> option) or call - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s - <command>org.freedesktop.systemd1.Manager.KExec</command> D-Bus method - directly.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>local-fs.target</filename></term> - <listitem> - <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry> - automatically adds dependencies of type - <varname>Before=</varname> to all mount units that refer to - local mount points for this target unit. In addition, it - adds dependencies of type <varname>Wants=</varname> to this - target unit for those mounts listed in - <filename>/etc/fstab</filename> that have the - <option>auto</option> mount option set.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>machines.target</filename></term> - <listitem> - <para>A standard target unit for starting all the containers - and other virtual machines. See <filename>systemd-nspawn@.service</filename> - for an example.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>multi-user.target</filename></term> - <listitem> - <para>A special target unit for setting up a multi-user - system (non-graphical). This is pulled in by - <filename>graphical.target</filename>.</para> - - <para>Units that are needed for a multi-user system shall - add <varname>Wants=</varname> dependencies for their unit to - this unit during installation. This is best configured via - <varname>WantedBy=multi-user.target</varname> in the unit's - <literal>[Install]</literal> section.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>network-online.target</filename></term> - <listitem> - <para>Units that strictly require a configured network - connection should pull in - <filename>network-online.target</filename> (via a - <varname>Wants=</varname> type dependency) and order - themselves after it. This target unit is intended to pull in - a service that delays further execution until the network is - sufficiently set up. What precisely this requires is left to - the implementation of the network managing service.</para> - - <para>Note the distinction between this unit and - <filename>network.target</filename>. This unit is an active - unit (i.e. pulled in by the consumer rather than the - provider of this functionality) and pulls in a service which - possibly adds substantial delays to further execution. In - contrast, <filename>network.target</filename> is a passive - unit (i.e. pulled in by the provider of the functionality, - rather than the consumer) that usually does not delay - execution much. Usually, <filename>network.target</filename> - is part of the boot of most systems, while - <filename>network-online.target</filename> is not, except - when at least one unit requires it. Also see <ulink - url="https://www.freedesktop.org/wiki/Software/systemd/NetworkTarget">Running - Services After the Network is up</ulink> for more - information.</para> - - <para>All mount units for remote network file systems - automatically pull in this unit, and order themselves after - it. Note that networking daemons that simply provide - functionality to other hosts generally do not need to pull - this in.</para> - - <para>systemd automatically adds dependencies of type <varname>Wants=</varname> and <varname>After=</varname> - for this target unit to all SysV init script service units with an LSB header referring to the - <literal>$network</literal> facility.</para> - - <para>Note that this unit is only useful during the original system start-up logic. After the system has - completed booting up, it will not track the online state of the system anymore. Due to this it cannot be used - as a network connection monitor concept, it is purely a one-time system start-up concept.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>paths.target</filename></term> - <listitem> - <para>A special target unit that sets up all path units (see - <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details) that shall be active after boot.</para> - - <para>It is recommended that path units installed by - applications get pulled in via <varname>Wants=</varname> - dependencies from this unit. This is best configured via a - <varname>WantedBy=paths.target</varname> in the path unit's - <literal>[Install]</literal> section.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>poweroff.target</filename></term> - <listitem> - <para>A special target unit for shutting down and powering - off the system.</para> - - <para>Applications wanting to power off the system should not start this unit - directly, but should instead execute <command>systemctl poweroff</command> - (possibly with the <option>--no-block</option> option) or call - <citerefentry><refentrytitle>systemd-logind</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s - <command>org.freedesktop.login1.Manager.PowerOff</command> D-Bus method - directly.</para> - - <para><filename>runlevel0.target</filename> is an alias for - this target unit, for compatibility with SysV.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>reboot.target</filename></term> - <listitem> - <para>A special target unit for shutting down and rebooting - the system.</para> - - <para>Applications wanting to reboot the system should not start this unit - directly, but should instead execute <command>systemctl reboot</command> - (possibly with the <option>--no-block</option> option) or call - <citerefentry><refentrytitle>systemd-logind</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s - <command>org.freedesktop.login1.Manager.Reboot</command> D-Bus method - directly.</para> - - <para><filename>runlevel6.target</filename> is an alias for - this target unit, for compatibility with SysV.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>remote-cryptsetup.target</filename></term> - <listitem> - <para>Similar to <filename>cryptsetup.target</filename>, but for encrypted - devices which are accessed over the network. It is used for - <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>8</manvolnum></citerefentry> - entries marked with <option>_netdev</option>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>remote-fs.target</filename></term> - <listitem> - <para>Similar to <filename>local-fs.target</filename>, but - for remote mount points.</para> - - <para>systemd automatically adds dependencies of type - <varname>After=</varname> for this target unit to all SysV - init script service units with an LSB header referring to - the <literal>$remote_fs</literal> facility.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>rescue.target</filename></term> - <listitem> - <para>A special target unit that pulls in the base system (including system mounts) and spawns a rescue - shell. Isolate to this target in order to administer the system in single-user mode with all file systems - mounted but with no services running, except for the most basic. Compare with - <filename>emergency.target</filename>, which is much more reduced and does not provide the file systems or - most basic services. Compare with <filename>multi-user.target</filename>, this target could be seen as - <filename>single-user.target</filename>.</para> - - <para><filename>runlevel1.target</filename> is an alias for this target unit, for compatibility with - SysV.</para> - - <para>Use the <literal>systemd.unit=rescue.target</literal> kernel command line option to boot into this - mode. A short alias for this kernel command line option is <literal>1</literal>, for compatibility with - SysV.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>runlevel2.target</filename></term> - <term><filename>runlevel3.target</filename></term> - <term><filename>runlevel4.target</filename></term> - <term><filename>runlevel5.target</filename></term> - <listitem> - <para>These are targets that are called whenever the SysV - compatibility code asks for runlevel 2, 3, 4, 5, - respectively. It is a good idea to make this an alias for - (i.e. symlink to) <filename>graphical.target</filename> - (for runlevel 5) or <filename>multi-user.target</filename> - (the others).</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>shutdown.target</filename></term> - <listitem> - <para>A special target unit that terminates the services on - system shutdown.</para> - - <para>Services that shall be terminated on system shutdown - shall add <varname>Conflicts=</varname> and - <varname>Before=</varname> dependencies to this unit for - their service unit, which is implicitly done when - <varname>DefaultDependencies=yes</varname> is set (the - default).</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>sigpwr.target</filename></term> - <listitem> - <para>A special target that is started when systemd receives - the SIGPWR process signal, which is normally sent by the - kernel or UPS daemons when power fails.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>sleep.target</filename></term> - <listitem> - <para>A special target unit that is pulled in by - <filename>suspend.target</filename>, - <filename>hibernate.target</filename> and - <filename>hybrid-sleep.target</filename> and may be used to - hook units into the sleep state logic.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>slices.target</filename></term> - <listitem> - <para>A special target unit that sets up all slice units (see - <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry> for - details) that shall be active after boot. By default the generic <filename>system.slice</filename> - slice unit, as well as the root slice unit <filename>-.slice</filename>, is pulled in and ordered before - this unit (see below).</para> - - <para>It's a good idea to add <varname>WantedBy=slices.target</varname> lines to the <literal>[Install]</literal> - section of all slices units that may be installed dynamically.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>sockets.target</filename></term> - <listitem> - <para>A special target unit that sets up all socket - units (see - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details) that shall be active after boot.</para> - - <para>Services that can be socket-activated shall add - <varname>Wants=</varname> dependencies to this unit for - their socket unit during installation. This is best - configured via a <varname>WantedBy=sockets.target</varname> - in the socket unit's <literal>[Install]</literal> - section.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>suspend.target</filename></term> - <listitem> - <para>A special target unit for suspending the system. This - pulls in <filename>sleep.target</filename>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>swap.target</filename></term> - <listitem> - <para>Similar to <filename>local-fs.target</filename>, but - for swap partitions and swap files.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>sysinit.target</filename></term> - <listitem> - <para>systemd automatically adds dependencies of the types - <varname>Requires=</varname> and <varname>After=</varname> - for this target unit to all services (except for those with - <varname>DefaultDependencies=no</varname>).</para> - - <para>This target pulls in the services required for system - initialization. System services pulled in by this target should - declare <varname>DefaultDependencies=no</varname> and specify - all their dependencies manually, including access to anything - more than a read only root filesystem. For details on the - dependencies of this target, refer to - <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>syslog.socket</filename></term> - <listitem> - <para>The socket unit syslog implementations should listen - on. All userspace log messages will be made available on - this socket. For more information about syslog integration, - please consult the <ulink - url="https://www.freedesktop.org/wiki/Software/systemd/syslog">Syslog - Interface</ulink> document.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>system-update.target</filename></term> - <term><filename>system-update-pre.target</filename></term> - <term><filename>system-update-cleanup.service</filename></term> - <listitem> - <para>A special target unit that is used for offline system updates. - <citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> - will redirect the boot process to this target if <filename>/system-update</filename> - exists. For more information see - <citerefentry><refentrytitle>systemd.offline-updates</refentrytitle><manvolnum>7</manvolnum></citerefentry>. - </para> - - <para>Updates should happen before the <filename>system-update.target</filename> is reached, and the services - which implement them should cause the machine to reboot. The main units executing the update should order - themselves after <filename>system-update-pre.target</filename> but not pull it in. Services which want to run - during system updates only, but before the actual system update is executed should order themselves before - this unit and pull it in. As a safety measure, if this does not happen, and - <filename>/system-update</filename> still exists after <filename>system-update.target</filename> is reached, - <filename>system-update-cleanup.service</filename> will remove this symlink and reboot the machine.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>timers.target</filename></term> - <listitem> - <para>A special target unit that sets up all timer units - (see - <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details) that shall be active after boot.</para> - - <para>It is recommended that timer units installed by - applications get pulled in via <varname>Wants=</varname> - dependencies from this unit. This is best configured via - <varname>WantedBy=timers.target</varname> in the timer - unit's <literal>[Install]</literal> section.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>umount.target</filename></term> - <listitem> - <para>A special target unit that unmounts all mount and - automount points on system shutdown.</para> - - <para>Mounts that shall be unmounted on system shutdown - shall add Conflicts dependencies to this unit for their - mount unit, which is implicitly done when - <varname>DefaultDependencies=yes</varname> is set (the - default).</para> - </listitem> - </varlistentry> - - </variablelist> - </refsect1> + <title>Units managed by the system's service manager</title> + + <refsect2> + <title>Special System Units</title> + + <variablelist> + <varlistentry> + <term><filename>-.mount</filename></term> + <listitem> + <para>The root mount point, i.e. the mount unit for the <filename>/</filename> + path. This unit is unconditionally active, during the entire time the system is up, as + this mount point is where the basic userspace is running from.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename>basic.target</filename></term> + <listitem> + <para>A special target unit covering basic boot-up.</para> + + <para>systemd automatically adds dependency of the type + <varname>After=</varname> for this target unit to all + services (except for those with + <varname>DefaultDependencies=no</varname>).</para> + + <para>Usually, this should pull-in all local mount points plus + <filename>/var</filename>, <filename>/tmp</filename> and + <filename>/var/tmp</filename>, swap devices, sockets, timers, + path units and other basic initialization necessary for general + purpose daemons. The mentioned mount points are special cased + to allow them to be remote. + </para> + + <para>This target usually does not pull in any non-target units + directly, but rather does so indirectly via other early boot targets. + It is instead meant as a synchronization point for late boot + services. Refer to + <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details on the targets involved. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>boot-complete.target</filename></term> + <listitem> + <para>This target is intended as generic synchronization point for services that shall determine or act on + whether the boot process completed successfully. Order units that are required to succeed for a boot process + to be considered successful before this unit, and add a <varname>Requires=</varname> dependency from the + target unit to them. Order units that shall only run when the boot process is considered successful after the + target unit and pull in the target from it, also with <varname>Requires=</varname>. Note that by default this + target unit is not part of the initial boot transaction, but is supposed to be pulled in only if required by + units that want to run only on successful boots.</para> + + <para>See + <citerefentry><refentrytitle>systemd-boot-check-no-failures.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for a service that implements a generic system health check and orders itself before + <filename>boot-complete.target</filename>.</para> + + <para>See + <citerefentry><refentrytitle>systemd-bless-boot.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for a service that propagates boot success information to the boot loader, and orders itself after + <filename>boot-complete.target</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>ctrl-alt-del.target</filename></term> + <listitem> + <para>systemd starts this target whenever Control+Alt+Del is + pressed on the console. Usually, this should be aliased + (symlinked) to <filename>reboot.target</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>cryptsetup.target</filename></term> + <listitem> + <para>A target that pulls in setup services for all + encrypted block devices.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>dbus.service</filename></term> + <listitem> + <para>A special unit for the D-Bus bus daemon. As soon as + this service is fully started up systemd will connect to it + and register its service.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>dbus.socket</filename></term> + <listitem> + <para>A special unit for the D-Bus system bus socket. All + units with <varname>Type=dbus</varname> automatically gain a + dependency on this unit.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>default.target</filename></term> + <listitem> + <para>The default unit systemd starts at bootup. Usually, + this should be aliased (symlinked) to + <filename>multi-user.target</filename> or + <filename>graphical.target</filename>.</para> + + <para>The default unit systemd starts at bootup can be + overridden with the <varname>systemd.unit=</varname> kernel + command line option.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>display-manager.service</filename></term> + <listitem> + <para>The display manager service. Usually, this should be + aliased (symlinked) to <filename>gdm.service</filename> or a + similar display manager service.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>emergency.target</filename></term> + <listitem> + <para>A special target unit that starts an emergency shell on the main console. This + target does not pull in any services or mounts. It is the most minimal version of + starting the system in order to acquire an interactive shell; the only processes running + are usually just the system manager (PID 1) and the shell process. This unit is supposed + to be used with the kernel command line option <varname>systemd.unit=</varname>; it is + also used when a file system check on a required file system fails, and boot-up cannot + continue. Compare with <filename>rescue.target</filename>, which serves a similar + purpose, but also starts the most basic services and mounts all file systems.</para> + + <para>Use the <literal>systemd.unit=emergency.target</literal> kernel command line + option to boot into this mode. A short alias for this kernel command line option is + <literal>emergency</literal>, for compatibility with SysV.</para> + + <para>In many ways booting into <filename>emergency.target</filename> is similar to the + effect of booting with <literal>init=/bin/sh</literal> on the kernel command line, + except that emergency mode provides you with the full system and service manager, and + allows starting individual units in order to continue the boot process in steps.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>exit.target</filename></term> + <listitem> + <para>A special service unit for shutting down the system or + user service manager. It is equivalent to + <filename>poweroff.target</filename> on non-container + systems, and also works in containers.</para> + + <para>systemd will start this unit when it receives the + <constant>SIGTERM</constant> or <constant>SIGINT</constant> + signal when running as user service daemon.</para> + + <para>Normally, this (indirectly) pulls in + <filename>shutdown.target</filename>, which in turn should be + conflicted by all units that want to be scheduled for + shutdown when the service manager starts to exit.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>final.target</filename></term> + <listitem> + <para>A special target unit that is used during the shutdown + logic and may be used to pull in late services after all + normal services are already terminated and all mounts + unmounted. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>getty.target</filename></term> + <listitem> + <para>A special target unit that pulls in statically + configured local TTY <filename>getty</filename> instances. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>graphical.target</filename></term> + <listitem> + <para>A special target unit for setting up a graphical login + screen. This pulls in + <filename>multi-user.target</filename>.</para> + + <para>Units that are needed for graphical logins shall add + <varname>Wants=</varname> dependencies for their unit to + this unit (or <filename>multi-user.target</filename>) during + installation. This is best configured via + <varname>WantedBy=graphical.target</varname> in the unit's + <literal>[Install]</literal> section.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>hibernate.target</filename></term> + <listitem> + <para>A special target unit for hibernating the system. This + pulls in <filename>sleep.target</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>hybrid-sleep.target</filename></term> + <listitem> + <para>A special target unit for hibernating and suspending + the system at the same time. This pulls in + <filename>sleep.target</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>suspend-then-hibernate.target</filename></term> + <listitem> + <para>A special target unit for suspending the system for a period + of time, waking it and putting it into hibernate. This pulls in + <filename>sleep.target</filename>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename>halt.target</filename></term> + <listitem> + <para>A special target unit for shutting down and halting + the system. Note that this target is distinct from + <filename>poweroff.target</filename> in that it generally + really just halts the system rather than powering it + down.</para> + + <para>Applications wanting to halt the system should not start this unit + directly, but should instead execute <command>systemctl halt</command> + (possibly with the <option>--no-block</option> option) or call + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s + <command>org.freedesktop.systemd1.Manager.Halt</command> D-Bus method + directly.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>init.scope</filename></term> + <listitem> + <para>This scope unit is where the system and service manager (PID 1) itself resides. It + is active as long as the system is running.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>initrd-fs.target</filename></term> + <listitem> + <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry> + automatically adds dependencies of type + <varname>Before=</varname> to + <filename>sysroot-usr.mount</filename> and all mount points + found in <filename>/etc/fstab</filename> that have + <option>x-initrd.mount</option> and not have + <option>noauto</option> mount options set.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>initrd-root-device.target</filename></term> + <listitem> + <para>A special initrd target unit that is reached when the root filesystem device is available, but before + it has been mounted. + <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry> + automatically setup the appropriate dependencies to make this happen. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>initrd-root-fs.target</filename></term> + <listitem> + <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry> + automatically adds dependencies of type + <varname>Before=</varname> to the + <filename>sysroot.mount</filename> unit, which is generated + from the kernel command line. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>kbrequest.target</filename></term> + <listitem> + <para>systemd starts this target whenever Alt+ArrowUp is + pressed on the console. Note that any user with physical access + to the machine will be able to do this, without authentication, + so this should be used carefully.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>kexec.target</filename></term> + <listitem> + <para>A special target unit for shutting down and rebooting + the system via kexec.</para> + + <para>Applications wanting to reboot the system should not start this unit + directly, but should instead execute <command>systemctl kexec</command> + (possibly with the <option>--no-block</option> option) or call + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s + <command>org.freedesktop.systemd1.Manager.KExec</command> D-Bus method + directly.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>local-fs.target</filename></term> + <listitem> + <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry> + automatically adds dependencies of type + <varname>Before=</varname> to all mount units that refer to + local mount points for this target unit. In addition, it + adds dependencies of type <varname>Wants=</varname> to this + target unit for those mounts listed in + <filename>/etc/fstab</filename> that have the + <option>auto</option> mount option set.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>machines.target</filename></term> + <listitem> + <para>A standard target unit for starting all the containers + and other virtual machines. See <filename>systemd-nspawn@.service</filename> + for an example.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>multi-user.target</filename></term> + <listitem> + <para>A special target unit for setting up a multi-user + system (non-graphical). This is pulled in by + <filename>graphical.target</filename>.</para> + + <para>Units that are needed for a multi-user system shall + add <varname>Wants=</varname> dependencies for their unit to + this unit during installation. This is best configured via + <varname>WantedBy=multi-user.target</varname> in the unit's + <literal>[Install]</literal> section.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>network-online.target</filename></term> + <listitem> + <para>Units that strictly require a configured network + connection should pull in + <filename>network-online.target</filename> (via a + <varname>Wants=</varname> type dependency) and order + themselves after it. This target unit is intended to pull in + a service that delays further execution until the network is + sufficiently set up. What precisely this requires is left to + the implementation of the network managing service.</para> + + <para>Note the distinction between this unit and + <filename>network.target</filename>. This unit is an active + unit (i.e. pulled in by the consumer rather than the + provider of this functionality) and pulls in a service which + possibly adds substantial delays to further execution. In + contrast, <filename>network.target</filename> is a passive + unit (i.e. pulled in by the provider of the functionality, + rather than the consumer) that usually does not delay + execution much. Usually, <filename>network.target</filename> + is part of the boot of most systems, while + <filename>network-online.target</filename> is not, except + when at least one unit requires it. Also see <ulink + url="https://www.freedesktop.org/wiki/Software/systemd/NetworkTarget">Running + Services After the Network is up</ulink> for more + information.</para> + + <para>All mount units for remote network file systems + automatically pull in this unit, and order themselves after + it. Note that networking daemons that simply provide + functionality to other hosts generally do not need to pull + this in.</para> + + <para>systemd automatically adds dependencies of type <varname>Wants=</varname> and + <varname>After=</varname> for this target unit to all SysV init script service units + with an LSB header referring to the <literal>$network</literal> facility.</para> + + <para>Note that this unit is only useful during the original system start-up + logic. After the system has completed booting up, it will not track the online state of + the system anymore. Due to this it cannot be used as a network connection monitor + concept, it is purely a one-time system start-up concept.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>paths.target</filename></term> + <listitem> + <para>A special target unit that sets up all path units (see + <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details) that shall be active after boot.</para> + + <para>It is recommended that path units installed by + applications get pulled in via <varname>Wants=</varname> + dependencies from this unit. This is best configured via a + <varname>WantedBy=paths.target</varname> in the path unit's + <literal>[Install]</literal> section.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>poweroff.target</filename></term> + <listitem> + <para>A special target unit for shutting down and powering + off the system.</para> + + <para>Applications wanting to power off the system should not start this unit + directly, but should instead execute <command>systemctl poweroff</command> + (possibly with the <option>--no-block</option> option) or call + <citerefentry><refentrytitle>systemd-logind</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s + <command>org.freedesktop.login1.Manager.PowerOff</command> D-Bus method + directly.</para> + + <para><filename>runlevel0.target</filename> is an alias for + this target unit, for compatibility with SysV.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>reboot.target</filename></term> + <listitem> + <para>A special target unit for shutting down and rebooting + the system.</para> + + <para>Applications wanting to reboot the system should not start this unit + directly, but should instead execute <command>systemctl reboot</command> + (possibly with the <option>--no-block</option> option) or call + <citerefentry><refentrytitle>systemd-logind</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s + <command>org.freedesktop.login1.Manager.Reboot</command> D-Bus method + directly.</para> + + <para><filename>runlevel6.target</filename> is an alias for + this target unit, for compatibility with SysV.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>remote-cryptsetup.target</filename></term> + <listitem> + <para>Similar to <filename>cryptsetup.target</filename>, but for encrypted + devices which are accessed over the network. It is used for + <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>8</manvolnum></citerefentry> + entries marked with <option>_netdev</option>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>remote-fs.target</filename></term> + <listitem> + <para>Similar to <filename>local-fs.target</filename>, but + for remote mount points.</para> + + <para>systemd automatically adds dependencies of type + <varname>After=</varname> for this target unit to all SysV + init script service units with an LSB header referring to + the <literal>$remote_fs</literal> facility.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>rescue.target</filename></term> + <listitem> + <para>A special target unit that pulls in the base system (including system mounts) and + spawns a rescue shell. Isolate to this target in order to administer the system in + single-user mode with all file systems mounted but with no services running, except for + the most basic. Compare with <filename>emergency.target</filename>, which is much more + reduced and does not provide the file systems or most basic services. Compare with + <filename>multi-user.target</filename>, this target could be seen as + <filename>single-user.target</filename>.</para> + + <para><filename>runlevel1.target</filename> is an alias for this target unit, for + compatibility with SysV.</para> + + <para>Use the <literal>systemd.unit=rescue.target</literal> kernel command line option + to boot into this mode. A short alias for this kernel command line option is + <literal>1</literal>, for compatibility with SysV.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>runlevel2.target</filename></term> + <term><filename>runlevel3.target</filename></term> + <term><filename>runlevel4.target</filename></term> + <term><filename>runlevel5.target</filename></term> + <listitem> + <para>These are targets that are called whenever the SysV + compatibility code asks for runlevel 2, 3, 4, 5, + respectively. It is a good idea to make this an alias for + (i.e. symlink to) <filename>graphical.target</filename> + (for runlevel 5) or <filename>multi-user.target</filename> + (the others).</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>shutdown.target</filename></term> + <listitem> + <para>A special target unit that terminates the services on + system shutdown.</para> + + <para>Services that shall be terminated on system shutdown + shall add <varname>Conflicts=</varname> and + <varname>Before=</varname> dependencies to this unit for + their service unit, which is implicitly done when + <varname>DefaultDependencies=yes</varname> is set (the + default).</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>sigpwr.target</filename></term> + <listitem> + <para>A special target that is started when systemd receives + the SIGPWR process signal, which is normally sent by the + kernel or UPS daemons when power fails.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>sleep.target</filename></term> + <listitem> + <para>A special target unit that is pulled in by + <filename>suspend.target</filename>, + <filename>hibernate.target</filename> and + <filename>hybrid-sleep.target</filename> and may be used to + hook units into the sleep state logic.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>slices.target</filename></term> + <listitem> + <para>A special target unit that sets up all slice units (see + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details) that shall always be active after boot. By default the generic + <filename>system.slice</filename> slice unit as well as the root slice unit + <filename>-.slice</filename> are pulled in and ordered before this unit (see + below).</para> + + <para>Adding slice units to <filename>slices.target</filename> is generally not + necessary. Instead, when some unit that uses <varname>Slice=</varname> is started, the + specified slice will be started automatically. Adding + <varname>WantedBy=slices.target</varname> lines to the <literal>[Install]</literal> + section should only be done for units that need to be always active. In that case care + needs to be taken to avoid creating a loop through the automatic dependencies on + "parent" slices.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>sockets.target</filename></term> + <listitem> + <para>A special target unit that sets up all socket + units (see + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details) that shall be active after boot.</para> + + <para>Services that can be socket-activated shall add + <varname>Wants=</varname> dependencies to this unit for + their socket unit during installation. This is best + configured via a <varname>WantedBy=sockets.target</varname> + in the socket unit's <literal>[Install]</literal> + section.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>suspend.target</filename></term> + <listitem> + <para>A special target unit for suspending the system. This + pulls in <filename>sleep.target</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>swap.target</filename></term> + <listitem> + <para>Similar to <filename>local-fs.target</filename>, but + for swap partitions and swap files.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>sysinit.target</filename></term> + <listitem> + <para>systemd automatically adds dependencies of the types + <varname>Requires=</varname> and <varname>After=</varname> + for this target unit to all services (except for those with + <varname>DefaultDependencies=no</varname>).</para> + + <para>This target pulls in the services required for system + initialization. System services pulled in by this target should + declare <varname>DefaultDependencies=no</varname> and specify + all their dependencies manually, including access to anything + more than a read only root filesystem. For details on the + dependencies of this target, refer to + <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>syslog.socket</filename></term> + <listitem> + <para>The socket unit syslog implementations should listen + on. All userspace log messages will be made available on + this socket. For more information about syslog integration, + please consult the <ulink + url="https://www.freedesktop.org/wiki/Software/systemd/syslog">Syslog + Interface</ulink> document.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>system-update.target</filename></term> + <term><filename>system-update-pre.target</filename></term> + <term><filename>system-update-cleanup.service</filename></term> + <listitem> + <para>A special target unit that is used for offline system updates. + <citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + will redirect the boot process to this target if <filename>/system-update</filename> + exists. For more information see + <citerefentry><refentrytitle>systemd.offline-updates</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + </para> + + <para>Updates should happen before the <filename>system-update.target</filename> is + reached, and the services which implement them should cause the machine to reboot. The + main units executing the update should order themselves after + <filename>system-update-pre.target</filename> but not pull it in. Services which want to + run during system updates only, but before the actual system update is executed should + order themselves before this unit and pull it in. As a safety measure, if this does not + happen, and <filename>/system-update</filename> still exists after + <filename>system-update.target</filename> is reached, + <filename>system-update-cleanup.service</filename> will remove this symlink and reboot + the machine.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>timers.target</filename></term> + <listitem> + <para>A special target unit that sets up all timer units + (see + <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details) that shall be active after boot.</para> + + <para>It is recommended that timer units installed by + applications get pulled in via <varname>Wants=</varname> + dependencies from this unit. This is best configured via + <varname>WantedBy=timers.target</varname> in the timer + unit's <literal>[Install]</literal> section.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>umount.target</filename></term> + <listitem> + <para>A special target unit that unmounts all mount and + automount points on system shutdown.</para> + + <para>Mounts that shall be unmounted on system shutdown + shall add Conflicts dependencies to this unit for their + mount unit, which is implicitly done when + <varname>DefaultDependencies=yes</varname> is set (the + default).</para> + </listitem> + </varlistentry> - <refsect1> - <title>Special System Units for Devices</title> - - <para>Some target units are automatically pulled in as devices of - certain kinds show up in the system. These may be used to - automatically activate various services based on the specific type - of the available hardware.</para> - - <variablelist> - <varlistentry> - <term><filename>bluetooth.target</filename></term> - <listitem> - <para>This target is started automatically as soon as a - Bluetooth controller is plugged in or becomes available at - boot.</para> - - <para>This may be used to pull in Bluetooth management - daemons dynamically when Bluetooth hardware is found.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>printer.target</filename></term> - <listitem> - <para>This target is started automatically as soon as a - printer is plugged in or becomes available at boot.</para> - - <para>This may be used to pull in printer management daemons - dynamically when printer hardware is found.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>smartcard.target</filename></term> - <listitem> - <para>This target is started automatically as soon as a - smartcard controller is plugged in or becomes available at - boot.</para> - - <para>This may be used to pull in smartcard management - daemons dynamically when smartcard hardware is found.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>sound.target</filename></term> - <listitem> - <para>This target is started automatically as soon as a - sound card is plugged in or becomes available at - boot.</para> - - <para>This may be used to pull in audio management daemons - dynamically when audio hardware is found.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> + </variablelist> + </refsect2> - <refsect1> - <title>Special Passive System Units </title> - - <para>A number of special system targets are defined that can be - used to properly order boot-up of optional services. These targets - are generally not part of the initial boot transaction, unless - they are explicitly pulled in by one of the implementing services. - Note specifically that these <emphasis>passive</emphasis> target - units are generally not pulled in by the consumer of a service, - but by the provider of the service. This means: a consuming - service should order itself after these targets (as appropriate), - but not pull it in. A providing service should order itself before - these targets (as appropriate) and pull it in (via a - <varname>Wants=</varname> type dependency).</para> - - <para>Note that these passive units cannot be started manually, - i.e. <literal>systemctl start time-sync.target</literal> will fail - with an error. They can only be pulled in by dependency. This is - enforced since they exist for ordering purposes only and thus are - not useful as only unit within a transaction.</para> - - <variablelist> - <varlistentry> - <term><filename>cryptsetup-pre.target</filename></term> - <listitem> - <para>This passive target unit may be pulled in by services - that want to run before any encrypted block device is set - up. All encrypted block devices are set up after this target - has been reached. Since the shutdown order is implicitly the - reverse start-up order between units, this target is - particularly useful to ensure that a service is shut down - only after all encrypted block devices are fully - stopped.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>getty-pre.target</filename></term> - <listitem> - <para>A special passive target unit. Users of this target - are expected to pull it in the boot transaction via - a dependency (e.g. <varname>Wants=</varname>). Order your - unit before this unit if you want to make use of the console - just before <filename>getty</filename> is started. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>local-fs-pre.target</filename></term> - <listitem> - <para>This target unit is - automatically ordered before - all local mount points marked - with <option>auto</option> - (see above). It can be used to - execute certain units before - all local mounts.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>network.target</filename></term> - <listitem> - <para>This unit is supposed to indicate when network - functionality is available, but it is only very weakly - defined what that is supposed to mean, with one exception: - at shutdown, a unit that is ordered after - <filename>network.target</filename> will be stopped before - the network — to whatever level it might be set up then — - is shut down. It is hence useful when writing service files - that require network access on shutdown, which should order - themselves after this target, but not pull it in. Also see - <ulink url="https://www.freedesktop.org/wiki/Software/systemd/NetworkTarget">Running - Services After the Network is up</ulink> for more - information. Also see - <filename>network-online.target</filename> described - above.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>network-pre.target</filename></term> - <listitem> - <para>This passive target unit may be pulled in by services - that want to run before any network is set up, for example - for the purpose of setting up a firewall. All network - management software orders itself after this target, but - does not pull it in.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>nss-lookup.target</filename></term> - <listitem> - <para>A target that should be used as synchronization point for all host/network name service lookups. Note - that this is independent of UNIX user/group name lookups for which <filename>nss-user-lookup.target</filename> - should be used. All services for which the availability of full host/network name resolution is essential - should be ordered after this target, but not pull it in. systemd automatically adds dependencies of type - <varname>After=</varname> for this target unit to all SysV init script service units with an LSB header - referring to the <literal>$named</literal> facility.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>nss-user-lookup.target</filename></term> - <listitem> - <para>A target that should be used as synchronization point for all regular UNIX user/group name service - lookups. Note that this is independent of host/network name lookups for which - <filename>nss-lookup.target</filename> should be used. All services for which the availability of the full - user/group database is essential should be ordered after this target, but not pull it in. All services which - provide parts of the user/group database should be ordered before this target, and pull it in. Note that this - unit is only relevant for regular users and groups — system users and groups are required to be resolvable - during earliest boot already, and hence do not need any special ordering against this target.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>remote-fs-pre.target</filename></term> - <listitem> - <para>This target unit is automatically ordered before all - mount point units (see above) and cryptsetup devices - marked with the <option>_netdev</option>. It can be used to run - certain units before remote encrypted devices and mounts are established. - Note that this unit is generally not part of the initial - transaction, unless the unit that wants to be ordered before - all remote mounts pulls it in via a - <varname>Wants=</varname> type dependency. If the unit wants - to be pulled in by the first remote mount showing up, it - should use <filename>network-online.target</filename> (see - above).</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>rpcbind.target</filename></term> - <listitem> - <para>The portmapper/rpcbind pulls in this target and orders - itself before it, to indicate its availability. systemd - automatically adds dependencies of type - <varname>After=</varname> for this target unit to all SysV - init script service units with an LSB header referring to - the <literal>$portmap</literal> facility.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>time-sync.target</filename></term> - <listitem> - <para>Services responsible for synchronizing the system - clock from a remote source (such as NTP client - implementations) should pull in this target and order - themselves before it. All services where correct time is - essential should be ordered after this unit, but not pull it - in. systemd automatically adds dependencies of type - <varname>After=</varname> for this target unit to all SysV - init script service units with an LSB header referring to - the <literal>$time</literal> facility. </para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> + <refsect2> + <title>Special System Units for Devices</title> - <refsect1> - <title>Special User Units</title> + <para>Some target units are automatically pulled in as devices of + certain kinds show up in the system. These may be used to + automatically activate various services based on the specific type + of the available hardware.</para> - <para>When systemd runs as a user instance, the following special - units are available, which have similar definitions as their - system counterparts: - <filename>exit.target</filename>, - <filename>default.target</filename>, - <filename>shutdown.target</filename>, - <filename>sockets.target</filename>, - <filename>timers.target</filename>, - <filename>paths.target</filename>, - <filename>bluetooth.target</filename>, - <filename>printer.target</filename>, - <filename>smartcard.target</filename>, - <filename>sound.target</filename>.</para> - </refsect1> + <variablelist> + <varlistentry> + <term><filename>bluetooth.target</filename></term> + <listitem> + <para>This target is started automatically as soon as a + Bluetooth controller is plugged in or becomes available at + boot.</para> - <refsect1> - <title>Special Passive User Units</title> - - <variablelist> - <varlistentry> - <term><filename>graphical-session.target</filename></term> - <listitem> - <para>This target is active whenever any graphical session is running. It is used to stop user services which - only apply to a graphical (X, Wayland, etc.) session when the session is terminated. Such services should - have <literal>PartOf=graphical-session.target</literal> in their <literal>[Unit]</literal> section. A target - for a particular session (e. g. <filename>gnome-session.target</filename>) starts and stops - <literal>graphical-session.target</literal> with <literal>BindsTo=graphical-session.target</literal>.</para> - - <para>Which services are started by a session target is determined by the <literal>Wants=</literal> and - <literal>Requires=</literal> dependencies. For services that can be enabled independently, symlinks in - <literal>.wants/</literal> and <literal>.requires/</literal> should be used, see - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Those - symlinks should either be shipped in packages, or should be added dynamically after installation, for example - using <literal>systemctl add-wants</literal>, see - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. - </para> - - <example> - <title>Nautilus as part of a GNOME session</title> - - <para><literal>gnome-session.target</literal> pulls in Nautilus as top-level service:</para> - - <programlisting>[Unit] -Description=User systemd services for GNOME graphical session -Wants=nautilus.service -BindsTo=graphical-session.target</programlisting> - - <para><literal>nautilus.service</literal> gets stopped when the session stops:</para> - - <programlisting>[Unit] -Description=Render the desktop icons with Nautilus -PartOf=graphical-session.target - -[Service] -…</programlisting> - </example> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>graphical-session-pre.target</filename></term> - <listitem> - <para>This target contains services which set up the environment or global configuration of a graphical - session, such as SSH/GPG agents (which need to export an environment variable into all desktop processes) or - migration of obsolete d-conf keys after an OS upgrade (which needs to happen before starting any process that - might use them). This target must be started before starting a graphical session like - <filename>gnome-session.target</filename>.</para> - </listitem> - </varlistentry> - </variablelist> + <para>This may be used to pull in Bluetooth management + daemons dynamically when Bluetooth hardware is found.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>printer.target</filename></term> + <listitem> + <para>This target is started automatically as soon as a + printer is plugged in or becomes available at boot.</para> + + <para>This may be used to pull in printer management daemons + dynamically when printer hardware is found.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>smartcard.target</filename></term> + <listitem> + <para>This target is started automatically as soon as a + smartcard controller is plugged in or becomes available at + boot.</para> + + <para>This may be used to pull in smartcard management + daemons dynamically when smartcard hardware is found.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>sound.target</filename></term> + <listitem> + <para>This target is started automatically as soon as a + sound card is plugged in or becomes available at + boot.</para> + + <para>This may be used to pull in audio management daemons + dynamically when audio hardware is found.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2> + <title>Special Passive System Units </title> + + <para>A number of special system targets are defined that can be + used to properly order boot-up of optional services. These targets + are generally not part of the initial boot transaction, unless + they are explicitly pulled in by one of the implementing services. + Note specifically that these <emphasis>passive</emphasis> target + units are generally not pulled in by the consumer of a service, + but by the provider of the service. This means: a consuming + service should order itself after these targets (as appropriate), + but not pull it in. A providing service should order itself before + these targets (as appropriate) and pull it in (via a + <varname>Wants=</varname> type dependency).</para> + + <para>Note that these passive units cannot be started manually, + i.e. <literal>systemctl start time-sync.target</literal> will fail + with an error. They can only be pulled in by dependency. This is + enforced since they exist for ordering purposes only and thus are + not useful as only unit within a transaction.</para> + + <variablelist> + <varlistentry> + <term><filename>cryptsetup-pre.target</filename></term> + <listitem> + <para>This passive target unit may be pulled in by services + that want to run before any encrypted block device is set + up. All encrypted block devices are set up after this target + has been reached. Since the shutdown order is implicitly the + reverse start-up order between units, this target is + particularly useful to ensure that a service is shut down + only after all encrypted block devices are fully + stopped.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>getty-pre.target</filename></term> + <listitem> + <para>A special passive target unit. Users of this target + are expected to pull it in the boot transaction via + a dependency (e.g. <varname>Wants=</varname>). Order your + unit before this unit if you want to make use of the console + just before <filename>getty</filename> is started. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>local-fs-pre.target</filename></term> + <listitem> + <para>This target unit is + automatically ordered before + all local mount points marked + with <option>auto</option> + (see above). It can be used to + execute certain units before + all local mounts.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>network.target</filename></term> + <listitem> + <para>This unit is supposed to indicate when network + functionality is available, but it is only very weakly + defined what that is supposed to mean, with one exception: + at shutdown, a unit that is ordered after + <filename>network.target</filename> will be stopped before + the network — to whatever level it might be set up then — + is shut down. It is hence useful when writing service files + that require network access on shutdown, which should order + themselves after this target, but not pull it in. Also see + <ulink url="https://www.freedesktop.org/wiki/Software/systemd/NetworkTarget">Running + Services After the Network is up</ulink> for more + information. Also see + <filename>network-online.target</filename> described + above.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>network-pre.target</filename></term> + <listitem> + <para>This passive target unit may be pulled in by services + that want to run before any network is set up, for example + for the purpose of setting up a firewall. All network + management software orders itself after this target, but + does not pull it in.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>nss-lookup.target</filename></term> + <listitem> + <para>A target that should be used as synchronization point for all host/network name + service lookups. Note that this is independent of UNIX user/group name lookups for which + <filename>nss-user-lookup.target</filename> should be used. All services for which the + availability of full host/network name resolution is essential should be ordered after + this target, but not pull it in. systemd automatically adds dependencies of type + <varname>After=</varname> for this target unit to all SysV init script service units + with an LSB header referring to the <literal>$named</literal> facility.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>nss-user-lookup.target</filename></term> + <listitem> + <para>A target that should be used as synchronization point for all regular UNIX + user/group name service lookups. Note that this is independent of host/network name + lookups for which <filename>nss-lookup.target</filename> should be used. All services + for which the availability of the full user/group database is essential should be + ordered after this target, but not pull it in. All services which provide parts of the + user/group database should be ordered before this target, and pull it in. Note that this + unit is only relevant for regular users and groups — system users and groups are + required to be resolvable during earliest boot already, and hence do not need any + special ordering against this target.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>remote-fs-pre.target</filename></term> + <listitem> + <para>This target unit is automatically ordered before all + mount point units (see above) and cryptsetup devices + marked with the <option>_netdev</option>. It can be used to run + certain units before remote encrypted devices and mounts are established. + Note that this unit is generally not part of the initial + transaction, unless the unit that wants to be ordered before + all remote mounts pulls it in via a + <varname>Wants=</varname> type dependency. If the unit wants + to be pulled in by the first remote mount showing up, it + should use <filename>network-online.target</filename> (see + above).</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>rpcbind.target</filename></term> + <listitem> + <para>The portmapper/rpcbind pulls in this target and orders + itself before it, to indicate its availability. systemd + automatically adds dependencies of type + <varname>After=</varname> for this target unit to all SysV + init script service units with an LSB header referring to + the <literal>$portmap</literal> facility.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>time-sync.target</filename></term> + <listitem> + <para>Services responsible for synchronizing the system + clock from a remote source (such as NTP client + implementations) should pull in this target and order + themselves before it. All services where correct time is + essential should be ordered after this unit, but not pull it + in. systemd automatically adds dependencies of type + <varname>After=</varname> for this target unit to all SysV + init script service units with an LSB header referring to + the <literal>$time</literal> facility. </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2> + <title>Special Slice Units</title> + + <para>There are four <literal>.slice</literal> units which form the basis of the hierarchy for + assignment of resources for services, users, and virtual machines or containers. See + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details about slice units.</para> + + <variablelist> + <varlistentry> + <term><filename>-.slice</filename></term> + <listitem> + <para>The root slice is the root of the slice hierarchy. It usually does not contain + units directly, but may be used to set defaults for the whole tree.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>system.slice</filename></term> + <listitem> + <para>By default, all system services started by + <command>systemd</command> are found in this slice.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename>user.slice</filename></term> + <listitem> + <para>By default, all user processes and services started on + behalf of the user, including the per-user systemd instance + are found in this slice. This is pulled in by + <filename>systemd-logind.service</filename></para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename>machine.slice</filename></term> + <listitem> + <para>By default, all virtual machines and containers + registered with <command>systemd-machined</command> are + found in this slice. This is pulled in by + <filename>systemd-machined.service</filename></para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> </refsect1> <refsect1> - <title>Special Slice Units</title> - - <para>There are four <literal>.slice</literal> units which form the basis of the hierarchy for assignment of - resources for services, users, and virtual machines or containers. See - <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details about slice - units.</para> - - <variablelist> - <varlistentry> - <term><filename>-.slice</filename></term> - <listitem> - <para>The root slice is the root of the slice hierarchy. It usually does not contain units directly, but may - be used to set defaults for the whole tree.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>system.slice</filename></term> - <listitem> - <para>By default, all system services started by - <command>systemd</command> are found in this slice.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>user.slice</filename></term> - <listitem> - <para>By default, all user processes and services started on - behalf of the user, including the per-user systemd instance - are found in this slice. This is pulled in by - <filename>systemd-logind.service</filename></para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>machine.slice</filename></term> - <listitem> - <para>By default, all virtual machines and containers - registered with <command>systemd-machined</command> are - found in this slice. This is pulled in by - <filename>systemd-machined.service</filename></para> - </listitem> - </varlistentry> - </variablelist> + <title>Units managed by the user's service manager</title> + + <refsect2> + <title>Special User Units</title> + + <para>When systemd runs as a user instance, the following special + units are available, which have similar definitions as their + system counterparts: + <filename>exit.target</filename>, + <filename>default.target</filename>, + <filename>shutdown.target</filename>, + <filename>sockets.target</filename>, + <filename>timers.target</filename>, + <filename>paths.target</filename>, + <filename>bluetooth.target</filename>, + <filename>printer.target</filename>, + <filename>smartcard.target</filename>, + <filename>sound.target</filename>.</para> + </refsect2> + + <refsect2> + <title>Special Passive User Units</title> + + <variablelist> + <varlistentry> + <term><filename>graphical-session.target</filename></term> + <listitem> + <para>This target is active whenever any graphical session is running. It is used to + stop user services which only apply to a graphical (X, Wayland, etc.) session when the + session is terminated. Such services should have + <literal>PartOf=graphical-session.target</literal> in their <literal>[Unit]</literal> + section. A target for a particular session (e. g. + <filename>gnome-session.target</filename>) starts and stops + <literal>graphical-session.target</literal> with + <literal>BindsTo=graphical-session.target</literal>.</para> + + <para>Which services are started by a session target is determined by the + <literal>Wants=</literal> and <literal>Requires=</literal> dependencies. For services + that can be enabled independently, symlinks in <literal>.wants/</literal> and + <literal>.requires/</literal> should be used, see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + Those symlinks should either be shipped in packages, or should be added dynamically + after installation, for example using <literal>systemctl add-wants</literal>, see + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + </para> + + <example> + <title>Nautilus as part of a GNOME session</title> + + <para><literal>gnome-session.target</literal> pulls in Nautilus as top-level service:</para> + + <programlisting>[Unit] + Description=User systemd services for GNOME graphical session + Wants=nautilus.service + BindsTo=graphical-session.target</programlisting> + + <para><literal>nautilus.service</literal> gets stopped when the session stops:</para> + + <programlisting>[Unit] + Description=Render the desktop icons with Nautilus + PartOf=graphical-session.target + + [Service] + …</programlisting> + </example> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename>graphical-session-pre.target</filename></term> + <listitem> + <para>This target contains services which set up the environment or global configuration + of a graphical session, such as SSH/GPG agents (which need to export an environment + variable into all desktop processes) or migration of obsolete d-conf keys after an OS + upgrade (which needs to happen before starting any process that might use them). This + target must be started before starting a graphical session like + <filename>gnome-session.target</filename>.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> </refsect1> <refsect1> @@ -1052,7 +1101,8 @@ PartOf=graphical-session.target <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>user@.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/systemd.swap.xml b/man/systemd.swap.xml index 998a047ec5..073c2b3a27 100644 --- a/man/systemd.swap.xml +++ b/man/systemd.swap.xml @@ -6,7 +6,9 @@ SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="systemd.swap"> +<refentry id="systemd.swap" + xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> <title>systemd.swap</title> <productname>systemd</productname> @@ -141,6 +143,26 @@ successfully.</para> </listitem> </varlistentry> + + <xi:include href="systemd.mount.xml" xpointer="device-timeout" /> + + <varlistentry> + <term><option>x-systemd.makefs</option></term> + + <listitem><para>The swap structure will be initialized on the device. If the device is not + "empty", i.e. it contains any signature, the operation will be skipped. It is hence expected + that this option remains set even after the device has been initalized.</para> + + <para>Note that this option can only be used in <filename>/etc/fstab</filename>, and will be + ignored when part of the <varname>Options=</varname> setting in a unit file.</para> + + <para>See + <citerefentry><refentrytitle>systemd-mkswap@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + and the discussion of + <citerefentry project='man-pages'><refentrytitle>wipefs</refentrytitle><manvolnum>8</manvolnum></citerefentry> + in <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> </variablelist> </refsect1> diff --git a/man/systemd.syntax.xml b/man/systemd.syntax.xml index 448ae174cb..67cd640eea 100644 --- a/man/systemd.syntax.xml +++ b/man/systemd.syntax.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ <!ENTITY % entities SYSTEM "custom-entities.ent" > @@ -73,7 +73,8 @@ backslash is replaced by a space character. This may be used to wrap long lines. The limit on line length is very large (currently 1 MB), but it is recommended to avoid such long lines and use multiple directives, variable substitution, or other mechanism as appropriate for the given - file type.</para> + file type. When a comment line or lines follow a line ending with a backslash, the comment block + is ignored, so the continued line is concatenated with whatever follows the comment block.</para> <example><programlisting>[Section A] KeyOne=value 1 @@ -85,8 +86,31 @@ KeyTwo=value 2 Setting="something" "some thing" "…" KeyTwo=value 2 \ value 2 continued + +[Section C] +KeyThree=value 2\ +# this line is ignored +; this line is ignored too + value 2 continued </programlisting></example> + <para>Boolean arguments used in configuration files can be written in + various formats. For positive settings the strings + <option>1</option>, <option>yes</option>, <option>true</option> + and <option>on</option> are equivalent. For negative settings, the + strings <option>0</option>, <option>no</option>, + <option>false</option> and <option>off</option> are + equivalent.</para> + + <para>Time span values encoded in configuration files can be written in various formats. A stand-alone + number specifies a time in seconds. If suffixed with a time unit, the unit is honored. A + concatenation of multiple values with units is supported, in which case the values are added + up. Example: <literal>50</literal> refers to 50 seconds; <literal>2min 200ms</literal> refers to + 2 minutes and 200 milliseconds, i.e. 120200 ms. The following time units are understood: + <literal>s</literal>, <literal>min</literal>, <literal>h</literal>, <literal>d</literal>, + <literal>w</literal>, <literal>ms</literal>, <literal>us</literal>. For details see + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + <para>Various settings are allowed to be specified more than once, in which case the interpretation depends on the setting. Often, multiple settings form a list, and setting to an empty value "resets", which means that previous assignments are ignored. When this is allowed, @@ -95,4 +119,11 @@ KeyTwo=value 2 \ file format.</para> </refsect1> + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + </refentry> diff --git a/man/systemd.target.xml b/man/systemd.target.xml index 51c5ea9af9..10aa91a2ee 100644 --- a/man/systemd.target.xml +++ b/man/systemd.target.xml @@ -81,7 +81,8 @@ some.service, the automatic ordering will not be added.</para></listitem> <listitem><para>Target units automatically gain <varname>Conflicts=</varname> - dependency against <filename>shutdown.target</filename>.</para></listitem> + and <varname>Before=</varname> dependencies against + <filename>shutdown.target</filename>.</para></listitem> </itemizedlist> </refsect2> </refsect1> diff --git a/man/systemd.time.xml b/man/systemd.time.xml index ad78b611a1..24df5ab942 100644 --- a/man/systemd.time.xml +++ b/man/systemd.time.xml @@ -50,7 +50,7 @@ understood:</para> <itemizedlist> - <listitem><para>usec, us</para></listitem> + <listitem><para>usec, us, µs</para></listitem> <listitem><para>msec, ms</para></listitem> <listitem><para>seconds, second, sec, s</para></listitem> <listitem><para>minutes, minute, min, m</para></listitem> @@ -74,6 +74,10 @@ 1y 12month 55s500ms 300ms20s 5day</programlisting> + + <para>One can use the <command>timespan</command> command of + <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to normalise a textual time span for testing and validation purposes.</para> </refsect1> <refsect1> diff --git a/man/systemd.timer.xml b/man/systemd.timer.xml index 44b257c745..d254c776bf 100644 --- a/man/systemd.timer.xml +++ b/man/systemd.timer.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -58,23 +58,17 @@ </refsect1> <refsect1> - <title>Implicit Dependencies</title> - - <para>The following dependencies are implicitly added:</para> - - <itemizedlist> - <listitem><para>Timer units automatically gain a <varname>Before=</varname> - dependency on the service they are supposed to activate.</para></listitem> - </itemizedlist> - </refsect1> - - <refsect1> <title>Automatic Dependencies</title> <refsect2> <title>Implicit Dependencies</title> - <para>There are no implicit dependencies for timer units.</para> + <para>The following dependencies are implicitly added:</para> + + <itemizedlist> + <listitem><para>Timer units automatically gain a <varname>Before=</varname> + dependency on the service they are supposed to activate.</para></listitem> + </itemizedlist> </refsect2> <refsect2> @@ -213,7 +207,7 @@ distributed amount of time between 0 and the specified time value. Defaults to 0, indicating that no randomized delay shall be applied. Each timer unit will determine this delay - randomly each time it is started, and the delay will simply be + randomly before each iteration, and the delay will simply be added on top of the next determined elapsing time. This is useful to stretch dispatching of similarly configured timer events over a certain amount time, to avoid that they all fire diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 7605c43375..7e1b3cb7eb 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ <!ENTITY % entities SYSTEM "custom-entities.ent" > @@ -39,19 +39,26 @@ <filename><replaceable>slice</replaceable>.slice</filename>, <filename><replaceable>scope</replaceable>.scope</filename></para> - <para><literallayout><filename>/etc/systemd/system.control/*</filename> + <refsect2> + <title>System Unit Search Path</title> + + <para><literallayout><filename>/etc/systemd/system.control/*</filename> <filename>/run/systemd/system.control/*</filename> <filename>/run/systemd/transient/*</filename> <filename>/run/systemd/generator.early/*</filename> <filename>/etc/systemd/system/*</filename> +<filename>/etc/systemd/systemd.attached/*</filename> <filename>/run/systemd/system/*</filename> +<filename>/run/systemd/systemd.attached/*</filename> <filename>/run/systemd/generator/*</filename> <filename>…</filename> <filename>/usr/lib/systemd/system/*</filename> -<filename>/run/systemd/generator.late/*</filename> - </literallayout></para> +<filename>/run/systemd/generator.late/*</filename></literallayout></para> + </refsect2> - <para><literallayout><filename>~/.config/systemd/user.control/*</filename> + <refsect2> + <title>User Unit Search Path</title> + <para><literallayout><filename>~/.config/systemd/user.control/*</filename> <filename>$XDG_RUNTIME_DIR/systemd/user.control/*</filename> <filename>$XDG_RUNTIME_DIR/systemd/transient/*</filename> <filename>$XDG_RUNTIME_DIR/systemd/generator.early/*</filename> @@ -63,8 +70,9 @@ <filename>~/.local/share/systemd/user/*</filename> <filename>…</filename> <filename>/usr/lib/systemd/user/*</filename> -<filename>$XDG_RUNTIME_DIR/systemd/generator.late/*</filename> - </literallayout></para> +<filename>$XDG_RUNTIME_DIR/systemd/generator.late/*</filename></literallayout></para> + </refsect2> + </refsynopsisdiv> <refsect1> @@ -118,23 +126,6 @@ do not need the prefix. Applications may use this to include additional information in the unit files.</para> - <para>Boolean arguments used in unit files can be written in - various formats. For positive settings the strings - <option>1</option>, <option>yes</option>, <option>true</option> - and <option>on</option> are equivalent. For negative settings, the - strings <option>0</option>, <option>no</option>, - <option>false</option> and <option>off</option> are - equivalent.</para> - - <para>Time span values encoded in unit files can be written in various formats. A stand-alone - number specifies a time in seconds. If suffixed with a time unit, the unit is honored. A - concatenation of multiple values with units is supported, in which case the values are added - up. Example: <literal>50</literal> refers to 50 seconds; <literal>2min 200ms</literal> refers to - 2 minutes and 200 milliseconds, i.e. 120200 ms. The following time units are understood: - <literal>s</literal>, <literal>min</literal>, <literal>h</literal>, <literal>d</literal>, - <literal>w</literal>, <literal>ms</literal>, <literal>us</literal>. For details see - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> - <para>Units can be aliased (have an alternative name), by creating a symlink from the new name to the existing name in one of the unit search paths. For example, <filename>systemd-networkd.service</filename> has the alias @@ -334,7 +325,7 @@ <row> <entry><filename>/run/systemd/generator.early</filename></entry> <entry>Generated units with high priority (see <replaceable>early-dir</replaceable> in <citerefentry - ><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> + ><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> </row> <row> <entry><filename>/etc/systemd/system</filename></entry> @@ -347,7 +338,7 @@ <row> <entry><filename>/run/systemd/generator</filename></entry> <entry>Generated units with medium priority (see <replaceable>normal-dir</replaceable> in <citerefentry - ><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> + ><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> </row> <row> <entry><filename>/usr/local/lib/systemd/system</filename></entry> @@ -359,7 +350,7 @@ <row> <entry><filename>/run/systemd/generator.late</filename></entry> <entry>Generated units with low priority (see <replaceable>late-dir</replaceable> in <citerefentry - ><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> + ><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> </row> </tbody> </tgroup> @@ -395,7 +386,7 @@ <row> <entry><filename>/run/systemd/generator.early</filename></entry> <entry>Generated units with high priority (see <replaceable>early-dir</replaceable> in <citerefentry - ><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> + ><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> </row> <row> <entry><filename>$XDG_CONFIG_HOME/systemd/user</filename> or <filename>$HOME/.config/systemd/user</filename></entry> @@ -416,7 +407,7 @@ <row> <entry><filename>$XDG_RUNTIME_DIR/systemd/generator</filename></entry> <entry>Generated units with medium priority (see <replaceable>normal-dir</replaceable> in <citerefentry - ><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> + ><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> </row> <row> <entry><filename>$XDG_DATA_HOME/systemd/user</filename> or <filename>$HOME/.local/share/systemd/user</filename></entry> @@ -436,7 +427,7 @@ <row> <entry><filename>$XDG_RUNTIME_DIR/systemd/generator.late</filename></entry> <entry>Generated units with low priority (see <replaceable>late-dir</replaceable> in <citerefentry - ><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> + ><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> </row> </tbody> </tgroup> @@ -511,15 +502,21 @@ <varlistentry> <term><varname>Description=</varname></term> - <listitem><para>A free-form string describing the unit. This - is intended for use in UIs to show descriptive information - along with the unit name. The description should contain a - name that means something to the end user. <literal>Apache2 - Web Server</literal> is a good example. Bad examples are - <literal>high-performance light-weight HTTP server</literal> - (too generic) or <literal>Apache2</literal> (too specific and - meaningless for people who do not know - Apache).</para></listitem> + <listitem><para>A human readable name for the unit. This is used by + <command>systemd</command> (and other UIs) as the label for the unit, so this string should + identify the unit rather than describe it, despite the name. <literal>Apache2 Web + Server</literal> is a good example. Bad examples are <literal>high-performance light-weight + HTTP server</literal> (too generic) or <literal>Apache2</literal> (too specific and + meaningless for people who do not know Apache). <command>systemd</command> will use this + string as a noun in status messages (<literal>Starting + <replaceable>description</replaceable>...</literal>, <literal>Started + <replaceable>description</replaceable>.</literal>, <literal>Reached target + <replaceable>description</replaceable>.</literal>, <literal>Failed to start + <replaceable>description</replaceable>.</literal>), so it should be capitalized, and should + not be a full sentence or a phrase with a continous verb. Bad examples include + <literal>exiting the container</literal> or <literal>updating the database once per + day.</literal>.</para> + </listitem> </varlistentry> <varlistentry> @@ -668,10 +665,10 @@ <para>If a unit A that conflicts with a unit B is scheduled to be started at the same time as B, the transaction will either - fail (in case both are required part of the transaction) or be + fail (in case both are required parts of the transaction) or be modified to be fixed (in case one or both jobs are not a required part of the transaction). In the latter case, the job - that is not the required will be removed, or in case both are + that is not required will be removed, or in case both are not required, the unit that conflicts will be started and the unit that is conflicted is stopped.</para></listitem> </varlistentry> @@ -874,12 +871,49 @@ </varlistentry> <varlistentry> + <term><varname>FailureAction=</varname></term> + <term><varname>SuccessAction=</varname></term> + + <listitem><para>Configure the action to take when the unit stops and enters a failed state or inactive state. + Takes one of <option>none</option>, <option>reboot</option>, <option>reboot-force</option>, + <option>reboot-immediate</option>, <option>poweroff</option>, <option>poweroff-force</option>, + <option>poweroff-immediate</option>, <option>exit</option>, and <option>exit-force</option>. In system mode, + all options are allowed. In user mode, only <option>none</option>, <option>exit</option>, and + <option>exit-force</option> are allowed. Both options default to <option>none</option>.</para> + + <para>If <option>none</option> is set, no action will be triggered. <option>reboot</option> causes a reboot + following the normal shutdown procedure (i.e. equivalent to <command>systemctl reboot</command>). + <option>reboot-force</option> causes a forced reboot which will terminate all processes forcibly but should + cause no dirty file systems on reboot (i.e. equivalent to <command>systemctl reboot -f</command>) and + <option>reboot-immediate</option> causes immediate execution of the + <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call, which + might result in data loss (i.e. equivalent to <command>systemctl reboot -ff</command>). Similarly, + <option>poweroff</option>, <option>poweroff-force</option>, <option>poweroff-immediate</option> have the effect + of powering down the system with similar semantics. <option>exit</option> causes the manager to exit following + the normal shutdown procedure, and <option>exit-force</option> causes it terminate without shutting down + services. When <option>exit</option> or <option>exit-force</option> 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 overriden + with <varname>FailureActionExitStatus=</varname>/<varname>SuccessActionExitStatus=</varname>, see + below.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>FailureActionExitStatus=</varname></term> + <term><varname>SuccessActionExitStatus=</varname></term> + + <listitem><para>Controls the exit status to propagate back to an invoking container manager (in case of a + system service) or service manager (in case of a user manager) when the + <varname>FailureAction=</varname>/<varname>SuccessAction=</varname> are set to <option>exit</option> or + <option>exit-force</option> and the action is triggered. By default the exit status of the main process of the + triggering unit (if this applies) is propagated. Takes a value in the range 0…255 or the empty string to + request default behaviour.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>JobTimeoutSec=</varname></term> <term><varname>JobRunningTimeoutSec=</varname></term> - <term><varname>JobTimeoutAction=</varname></term> - <term><varname>JobTimeoutRebootArgument=</varname></term> - <listitem><para>When a job for this unit is queued, a time-out <varname>JobTimeoutSec=</varname> may be + <listitem><para>When a job for this unit is queued, a timeout <varname>JobTimeoutSec=</varname> may be configured. Similarly, <varname>JobRunningTimeoutSec=</varname> starts counting when the queued job is actually started. If either time limit is reached, the job will be cancelled, the unit however will not change state or even enter the <literal>failed</literal> mode. This value defaults to <literal>infinity</literal> (job timeouts @@ -889,12 +923,20 @@ no effect on the unit itself, only on the job that might be pending for it. Or in other words: unit-specific timeouts are useful to abort unit state changes, and revert them. The job timeout set with this option however is useful to abort only the job waiting for the unit state to change.</para> + </listitem> + </varlistentry> - <para><varname>JobTimeoutAction=</varname> optionally configures an additional action to take when the time-out - is hit. It takes the same values as <varname>StartLimitAction=</varname>. Defaults to <option>none</option>. + <varlistentry> + <term><varname>JobTimeoutAction=</varname></term> + <term><varname>JobTimeoutRebootArgument=</varname></term> + + <listitem><para><varname>JobTimeoutAction=</varname> optionally configures an additional action to take when + the timeout is hit, see description of <varname>JobTimeoutSec=</varname> and + <varname>JobRunningTimeoutSec=</varname> above. It takes the same values as + <varname>StartLimitAction=</varname>. Defaults to <option>none</option>. <varname>JobTimeoutRebootArgument=</varname> configures an optional reboot string to pass to the - <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> - system call.</para></listitem> + <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call. + </para></listitem> </varlistentry> <varlistentry> @@ -929,29 +971,13 @@ <varlistentry> <term><varname>StartLimitAction=</varname></term> - <listitem><para>Configure the action to take if the rate limit configured with - <varname>StartLimitIntervalSec=</varname> and <varname>StartLimitBurst=</varname> is hit. Takes one of - <option>none</option>, <option>reboot</option>, <option>reboot-force</option>, - <option>reboot-immediate</option>, <option>poweroff</option>, <option>poweroff-force</option> or - <option>poweroff-immediate</option>. If <option>none</option> is set, hitting the rate limit will trigger no - action besides that the start will not be permitted. <option>reboot</option> causes a reboot following the - normal shutdown procedure (i.e. equivalent to <command>systemctl reboot</command>). - <option>reboot-force</option> causes a forced reboot which will terminate all processes forcibly but should - cause no dirty file systems on reboot (i.e. equivalent to <command>systemctl reboot -f</command>) and - <option>reboot-immediate</option> causes immediate execution of the - <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call, which - might result in data loss. Similarly, <option>poweroff</option>, <option>poweroff-force</option>, - <option>poweroff-immediate</option> have the effect of powering down the system with similar - semantics. Defaults to <option>none</option>.</para></listitem> + <listitem><para>Configure an additional action to take if the rate limit configured with + <varname>StartLimitIntervalSec=</varname> and <varname>StartLimitBurst=</varname> is hit. Takes the same + values as the setting <varname>FailureAction=</varname>/<varname>SuccessAction=</varname> settings and executes + the same actions. If <option>none</option> is set, hitting the rate limit will trigger no action besides that + the start will not be permitted. Defaults to <option>none</option>.</para></listitem> </varlistentry> - <varlistentry> - <term><varname>FailureAction=</varname></term> - <term><varname>SuccessAction=</varname></term> - <listitem><para>Configure the action to take when the unit stops and enters a failed state or inactive - state. Takes the same values as the setting <varname>StartLimitAction=</varname> setting and executes the same - actions. Both options default to <option>none</option>.</para></listitem> - </varlistentry> <varlistentry> <term><varname>RebootArgument=</varname></term> @@ -992,12 +1018,13 @@ <listitem><para>Before starting a unit, verify that the specified condition is true. If it is not true, the starting of the unit will be (mostly silently) skipped, however all ordering dependencies of it are still - respected. A failing condition will not result in the unit being moved into a failure state. The condition is - checked at the time the queued start job is to be executed. Use condition expressions in order to silently skip - units that do not apply to the local running system, for example because the kernel or runtime environment - doesn't require its functionality. Use the various <varname>AssertArchitecture=</varname>, - <varname>AssertVirtualization=</varname>, … options for a similar mechanism that puts the unit in a failure - state and logs about the failed check (see below).</para> + respected. A failing condition will not result in the unit being moved into the <literal>failed</literal> + state. The condition is checked at the time the queued start job is to be executed. Use condition expressions + in order to silently skip units that do not apply to the local running system, for example because the kernel + or runtime environment doesn't require their functionality. Use the various + <varname>AssertArchitecture=</varname>, <varname>AssertVirtualization=</varname>, … options for a similar + mechanism that causes the job to fail (instead of being skipped) and results in logging about the failed check + (instead of being silently processed). For details about assertion conditions see below.</para> <para><varname>ConditionArchitecture=</varname> may be used to check whether the system is running on a specific @@ -1226,12 +1253,12 @@ cgroup controller name (eg. <option>cpu</option>), verifying that it is available for use on the system. For example, a particular controller may not be available if it was disabled on the kernel command line with - <literal>cgroup_disable=</literal><replaceable>controller</replaceable>. - Multiple controllers may be passed with a space separating them; in - this case the condition will only pass if all listed controllers are - available for use. Controllers unknown to systemd are ignored. Valid - controllers are <option>cpu</option>, <option>cpuacct</option>, - <option>io</option>, <option>blkio</option>, <option>memory</option>, + <varname>cgroup_disable=controller</varname>. Multiple controllers may + be passed with a space separating them; in this case the condition will + only pass if all listed controllers are available for use. Controllers + unknown to systemd are ignored. Valid controllers are + <option>cpu</option>, <option>cpuacct</option>, <option>io</option>, + <option>blkio</option>, <option>memory</option>, <option>devices</option>, and <option>pids</option>.</para> <para>If multiple conditions are specified, the unit will be @@ -1278,9 +1305,16 @@ <listitem><para>Similar to the <varname>ConditionArchitecture=</varname>, <varname>ConditionVirtualization=</varname>, …, condition settings described above, these settings add assertion checks to the start-up of the unit. However, unlike the conditions settings, any assertion setting - that is not met results in failure of the start job (which means this is logged loudly). Use assertion - expressions for units that cannot operate when specific requirements are not met, and when this is something - the administrator or user should look into.</para></listitem> + that is not met results in failure of the start job (which means this is logged loudly). Note that hitting a + configured assertion does not cause the unit to enter the <literal>failed</literal> state (or in fact result in + any state change of the unit), it affects only the job queued for it. Use assertion expressions for units that + cannot operate when specific requirements are not met, and when this is something the administrator or user + should look into.</para> + + <para>Note that neither assertion nor condition expressions result in unit state changes. Also note that both + are checked at the time the job is to be executed, i.e. long after depending jobs and it itself were + queued. Thus, neither condition nor assertion expressions are suitable for conditionalizing unit + dependencies.</para></listitem> </varlistentry> <varlistentry> @@ -1495,8 +1529,8 @@ </variablelist> <para>The following specifiers are interpreted in the Install - section: %n, %N, %p, %i, %j, %U, %u, %m, %H, %b, %v. For their meaning - see the next section. + section: %n, %N, %p, %i, %j, %g, %G, %U, %u, %m, %H, %b, %v. For their + meaning see the next section. </para> </refsect1> @@ -1624,6 +1658,16 @@ <entry>This is either <filename>/tmp</filename> or the path <literal>$TMPDIR</literal>, <literal>$TEMP</literal> or <literal>$TMP</literal> are set to.</entry> </row> <row> + <entry><literal>%g</literal></entry> + <entry>User group</entry> + <entry>This is the name of the group running the service manager instance. In case of the system manager this resolves to <literal>root</literal>.</entry> + </row> + <row> + <entry><literal>%G</literal></entry> + <entry>User GID</entry> + <entry>This is the numeric GID of the user running the service manager instance. In case of the system manager this resolves to <literal>0</literal>.</entry> + </row> + <row> <entry><literal>%u</literal></entry> <entry>User name</entry> <entry>This is the name of the user running the service manager instance. In case of the system manager this resolves to <literal>root</literal>.</entry> diff --git a/man/systemd.xml b/man/systemd.xml index 17ab59beb5..49a29f9651 100644 --- a/man/systemd.xml +++ b/man/systemd.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -392,6 +392,25 @@ <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details about these target units.</para> + <para>systemd only keeps a minimal set of units loaded into memory. Specifically, the only units that are kept + loaded into memory are those for which at least one of the following conditions is true:</para> + + <orderedlist> + <listitem><para>It is in an active, activating, deactivating or failed state (i.e. in any unit state except for <literal>dead</literal>)</para></listitem> + <listitem><para>It has a job queued for it</para></listitem> + <listitem><para>It is a dependency of some sort of at least one other unit that is loaded into memory</para></listitem> + <listitem><para>It has some form of resource still allocated (e.g. a service unit that is inactive but for which + a process is still lingering that ignored the request to be terminated)</para></listitem> + <listitem><para>It has been pinned into memory programmatically by a D-Bus call</para></listitem> + </orderedlist> + + <para>systemd will automatically and implicitly load units from disk — if they are not loaded yet — as soon as + operations are requested for them. Thus, in many respects, the fact whether a unit is loaded or not is invisible to + clients. Use <command>systemctl list-units --all</command> to comprehensively list all units currently loaded. Any + unit for which none of the conditions above applies is promptly unloaded. Note that when a unit is unloaded from + memory its accounting data is flushed out too. However, this data is generally not lost, as a journal log record + is generated declaring the consumed resources whenever a unit shuts down.</para> + <para>Processes systemd spawns are placed in individual Linux control groups named after the unit which they belong to in the private systemd hierarchy. (see <ulink @@ -561,16 +580,15 @@ <varlistentry> <term><constant>SIGINT</constant></term> - <listitem><para>Upon receiving this signal the systemd system - manager will start the - <filename>ctrl-alt-del.target</filename> unit. This is mostly - equivalent to <command>systemctl start ctrl-alt-del.target - --job-mode=replace-irreversible</command>. If this signal is - received more than 7 times per 2s, an immediate reboot is - triggered. Note that pressing Ctrl-Alt-Del on the console - will trigger this signal. Hence, if a reboot is hanging, - pressing Ctrl-Alt-Del more than 7 times in 2s is a relatively - safe way to trigger an immediate reboot.</para> + <listitem><para>Upon receiving this signal the systemd system manager will start the + <filename>ctrl-alt-del.target</filename> unit. This is mostly equivalent to + <command>systemctl start ctrl-alt-del.target --job-mode=replace-irreversible</command>. If + this signal is received more than 7 times per 2s, an immediate reboot is triggered. Note + that pressing + <keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>Del</keycap></keycombo> on the + console will trigger this signal. Hence, if a reboot is hanging, pressing + <keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>Del</keycap></keycombo> more than + 7 times in 2 seconds is a relatively safe way to trigger an immediate reboot.</para> <para>systemd user managers treat this signal the same way as <constant>SIGTERM</constant>.</para></listitem> @@ -882,6 +900,9 @@ for more information.</para></listitem> </varlistentry> </variablelist> + + <para>For further environment variables understood by systemd and its various components, see <ulink + url="https://systemd.io/ENVIRONMENT">Known Environment Variables</ulink>.</para> </refsect1> <refsect1> @@ -1051,7 +1072,7 @@ hybrid or full legacy cgroup hierarchy.</para> <para>If this option is not specified, the default behaviour is determined - during compilation (the <option>--with-default-hierarchy=</option> + during compilation (the <option>-Ddefault-hierarchy=</option> meson option). If the kernel does not support unified cgroup hierarchy, the legacy hierarchy will be used even if this option is specified.</para> </listitem> @@ -1070,7 +1091,7 @@ the use of "hybrid" hierarchy.</para> <para>If this option is not specified, the default behaviour is determined - during compilation (the <option>--with-default-hierarchy=</option> + during compilation (the <option>-Ddefault-hierarchy=</option> meson option). If the kernel does not support unified cgroup hierarchy, the legacy hierarchy will be used even if this option is specified.</para> </listitem> @@ -1080,7 +1101,7 @@ <term><varname>quiet</varname></term> <listitem><para>Turn off status output at boot, much like - <varname>systemd.show_status=false</varname> would. Note that + <varname>systemd.show_status=no</varname> would. Note that this option is also read by the kernel itself and disables kernel log output. Passing this option hence turns off the usual output from both the system manager and the kernel. diff --git a/man/threads-aware.xml b/man/threads-aware.xml new file mode 100644 index 0000000000..7985f4acd1 --- /dev/null +++ b/man/threads-aware.xml @@ -0,0 +1,17 @@ +<?xml version="1.0"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> + +<!-- + SPDX-License-Identifier: LGPL-2.1+ +--> + +<refsect1> + +<para id="strict">All functions listed here are thread-agnostic and only a single specific thread may operate on a +given object during its entire lifetime. It's safe to allocate multiple independent objects and use each from a +specific thread in parallel. However, it's not safe to allocate such an object in one thread, and operate or free it +from any other, even if locking is used to ensure these threads don't operate on it at the very same time.</para> + +<para id="safe">All functions listed here are thread-safe and may be called in parallel from multiple threads.</para> + +</refsect1> diff --git a/man/timedatectl.xml b/man/timedatectl.xml index 39cd78666e..a62902423a 100644 --- a/man/timedatectl.xml +++ b/man/timedatectl.xml @@ -73,10 +73,11 @@ <varlistentry> <term><option>--monitor</option></term> - <listitem><para>If <command>timesync-status</command> is invoked and this option is passed, - then <command>timedatectl</command> monitors the status of + <listitem><para>If <command>timesync-status</command> is invoked and this option is passed, then + <command>timedatectl</command> monitors the status of <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - and updates the outputs. Use Ctrl-C to terminate the monitoring.</para></listitem> + and updates the outputs. Use <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo> to terminate the + monitoring.</para></listitem> </varlistentry> <varlistentry> diff --git a/man/tmpfiles.d.xml b/man/tmpfiles.d.xml index e2e2eac228..5d393f3984 100644 --- a/man/tmpfiles.d.xml +++ b/man/tmpfiles.d.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- SPDX-License-Identifier: LGPL-2.1+ @@ -40,25 +40,33 @@ <refsect1> <title>Description</title> - <para><command>systemd-tmpfiles</command> uses the configuration - files from the above directories to describe the creation, - cleaning and removal of volatile and temporary files and - directories which usually reside in directories such as - <filename>/run</filename> or <filename>/tmp</filename>.</para> - - <para>Volatile and temporary files and directories are those - located in <filename>/run</filename> (and its alias - <filename>/var/run</filename>), <filename>/tmp</filename>, - <filename>/var/tmp</filename>, the API file systems such as - <filename>/sys</filename> or <filename>/proc</filename>, as well - as some other directories below <filename>/var</filename>.</para> - - <para>System daemons frequently require private runtime - directories below <filename>/run</filename> to place communication - sockets and similar in. For these, consider declaring them in - their unit files using <varname>RuntimeDirectory=</varname> (see - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details), if this is feasible.</para> + <para><filename>tmpfiles.d</filename> configuration files provide a generic mechanism to define the + <emphasis>creation</emphasis> of regular files, directories, pipes, and device nodes, adjustments to + their <emphasis>access mode, ownership, attributes, quota assignments, and contents</emphasis>, and + finally their time-based <emphasis>removal</emphasis>. It is mostly commonly used for volatile and + temporary files and directories (such as those located under <filename>/run</filename>, + <filename>/tmp</filename>, <filename>/var/tmp</filename>, the API file systems such as + <filename>/sys</filename> or <filename>/proc</filename>, as well as some other directories below + <filename>/var</filename>).</para> + + <para><command>systemd-tmpfiles</command> uses this configuration to create volatile files and + directories during boot and to do periodic cleanup afterwards. See + <citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>5</manvolnum></citerefentry> for + the description of <filename>systemd-tmpfiles-setup.service</filename>, + <filename>systemd-tmpfiles-cleanup.service</filename>, and associated units.</para> + + <para>System daemons frequently require private runtime directories below <filename>/run</filename> to + store communication sockets and similar. For these, is is better to use + <varname>RuntimeDirectory=</varname> in their unit files (see + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for + details), if the flexibility provided by <filename>tmpfiles.d</filename> is not required. The advantages + are that the configuration required by the unit is centralized in one place, and that the lifetime of the + directory is tied to the lifetime of the service itself. Similarly, <varname>StateDirectory=</varname>, + <varname>CacheDirectory=</varname>, <varname>LogsDirectory=</varname>, and + <varname>ConfigurationDirectory=</varname> should be used to create directories under + <filename>/var/lib/</filename>, <filename>/var/cache/</filename>, <filename>/var/log/</filename>, and + <filename>/etc/</filename>. <filename>tmpfiles.d</filename> should be used for files whose lifetime is + independent of any service or requires more complicated configuration.</para> </refsect1> <refsect1> @@ -70,28 +78,20 @@ The second variant should be used when it is desirable to make it easy to override just this part of configuration.</para> - <para>Files in <filename>/etc/tmpfiles.d</filename> override files - with the same name in <filename>/usr/lib/tmpfiles.d</filename> and - <filename>/run/tmpfiles.d</filename>. Files in - <filename>/run/tmpfiles.d</filename> override files with the same - name in <filename>/usr/lib/tmpfiles.d</filename>. Packages should - install their configuration files in - <filename>/usr/lib/tmpfiles.d</filename>. Files in - <filename>/etc/tmpfiles.d</filename> are reserved for the local - administrator, who may use this logic to override the - configuration files installed by vendor packages. All - configuration files are sorted by their filename in lexicographic - order, regardless of which of the directories they reside in. If - multiple files specify the same path, the entry in the file with - the lexicographically earliest name will be applied. All other - conflicting entries will be logged as errors. When two lines are - prefix and suffix of each other, then the prefix is always - processed first, the suffix later. Lines that take globs are - applied after those accepting no globs. If multiple operations - shall be applied on the same file, (such as ACL, xattr, file - attribute adjustments), these are always done in the same fixed - order. Otherwise, the files/directories are processed in the order - they are listed.</para> + <para>Files in <filename>/etc/tmpfiles.d</filename> override files with the same name in + <filename>/usr/lib/tmpfiles.d</filename> and <filename>/run/tmpfiles.d</filename>. Files in + <filename>/run/tmpfiles.d</filename> override files with the same name in + <filename>/usr/lib/tmpfiles.d</filename>. Packages should install their configuration files in + <filename>/usr/lib/tmpfiles.d</filename>. Files in <filename>/etc/tmpfiles.d</filename> are reserved for the local + administrator, who may use this logic to override the configuration files installed by vendor packages. All + configuration files are sorted by their filename in lexicographic order, regardless of which of the directories + they reside in. If multiple files specify the same path, the entry in the file with the lexicographically earliest + name will be applied. All other conflicting entries will be logged as errors. When two lines are prefix path and + suffix path of each other, then the prefix line is always created first, the suffix later (and if removal applies + to the line, the order is reversed: the suffix is removed first, the prefix later). Lines that take globs are + applied after those accepting no globs. If multiple operations shall be applied on the same file (such as ACL, + xattr, file attribute adjustments), these are always done in the same fixed order. Except for those cases, the + files/directories are processed in the order they are listed.</para> <para>If the administrator wants to disable a configuration file supplied by the vendor, the recommended way is to place a symlink @@ -106,9 +106,9 @@ <para>The configuration format is one line per path containing type, path, mode, ownership, age, and argument fields:</para> - <programlisting>#Type Path Mode UID GID Age Argument -d /run/user 0755 root root 10d - -L /tmp/foobar - - - - /dev/null</programlisting> + <programlisting>#Type Path Mode User Group Age Argument +d /run/user 0755 root root 10d - +L /tmp/foobar - - - - /dev/null</programlisting> <para>Fields may be enclosed within quotes and contain C-style escapes.</para> @@ -116,7 +116,7 @@ L /tmp/foobar - - - - /dev/null</programlisting> <title>Type</title> <para>The type consists of a single letter and optionally an - exclamation mark.</para> + exclamation mark and/or minus sign.</para> <para>The following line types are understood:</para> @@ -146,107 +146,88 @@ L /tmp/foobar - - - - /dev/null</programlisting> <varlistentry> <term><varname>d</varname></term> - <listitem><para>Create a directory. The mode and ownership will be adjusted if - specified and the directory already exists. Contents of this directory are subject - to time based cleanup if the age argument is specified.</para></listitem> + <listitem><para>Create a directory. The mode and ownership will be adjusted if specified. Contents + of this directory are subject to time based cleanup if the age argument is specified. + </para></listitem> </varlistentry> <varlistentry> <term><varname>D</varname></term> - <listitem><para>Similar to <varname>d</varname>, but in addition the contents - of the directory will be removed when <option>--remove</option> is used. - </para></listitem> + <listitem><para>Similar to <varname>d</varname>, but in addition the contents of the directory will + be removed when <option>--remove</option> is used.</para></listitem> </varlistentry> <varlistentry> <term><varname>e</varname></term> - <listitem><para>Similar to <varname>d</varname>, but the directory will not be created if - it does not exist. Lines of this type accept shell-style globs in place of normal path - names. For this entry to be useful, at least one of the mode, uid, gid, or age arguments - must be specified, since otherwise this entry has no effect. If the age argument is - <literal>0</literal>, contents of the directory will be unconditionally deleted every time - <command>systemd-tmpfiles --clean</command> is run. This can be useful when combined with - <varname>!</varname>, see the examples.</para></listitem> + <listitem><para>Adjust the mode and ownership of existing directories and remove their contents + based on age. + Lines of this type accept shell-style globs in place of normal path names. Contents of the + directories are subject to time based cleanup if the age argument is specified. If the age argument + is <literal>0</literal>, contents will be unconditionally deleted every time + <command>systemd-tmpfiles --clean</command> is run.</para> + + <para>For this entry to be useful, at least one of the mode, user, group, or age arguments must be + specified, since otherwise this entry has no effect. As an exception, an entry with no effect may + be useful when combined with <varname>!</varname>, see the examples.</para></listitem> </varlistentry> <varlistentry> <term><varname>v</varname></term> - <listitem><para>Create a subvolume if the path does not - exist yet, the file system supports subvolumes (btrfs), and - the system itself is installed into a subvolume - (specifically: the root directory <filename>/</filename> is - itself a subvolume). Otherwise, create a normal directory, in - the same way as <varname>d</varname>. A subvolume created - with this line type is not assigned to any higher-level - quota group. For that, use <varname>q</varname> or - <varname>Q</varname>, which allow creating simple quota - group hierarchies, see below.</para></listitem> + <listitem><para>Create a subvolume if the path does not exist yet, the file system supports + subvolumes (btrfs), and the system itself is installed into a subvolume (specifically: the root + directory <filename>/</filename> is itself a subvolume). Otherwise, create a normal directory, in + the same way as <varname>d</varname>.</para> + + <para>A subvolume created with this line type is not assigned to any higher-level quota group. For + that, use <varname>q</varname> or <varname>Q</varname>, which allow creating simple quota group + hierarchies, see below.</para></listitem> </varlistentry> <varlistentry> <term><varname>q</varname></term> - <listitem><para>Similar to <varname>v</varname>. However, - makes sure that the subvolume will be assigned to the same - higher-level quota groups as the subvolume it has been - created in. This ensures that higher-level limits and - accounting applied to the parent subvolume also include the - specified subvolume. On non-btrfs file systems, this line - type is identical to <varname>d</varname>. If the subvolume - already exists and is already assigned to one or more higher - level quota groups, no change to the quota hierarchy is - made. Also see <varname>Q</varname> below. See <citerefentry - project='die-net'><refentrytitle>btrfs-qgroup</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for details about the btrfs quota group - concept.</para></listitem> + <listitem><para>Create a subvolume or directory the same as <varname>v</varname>, but assign the + subvolume to the same higher-level quota groups as the parent. This ensures that higher-level + limits and accounting applied to the parent subvolume also include the specified subvolume. On + non-btrfs file systems, this line type is identical to <varname>d</varname>.</para> + + <para>If the subvolume already exists, no change to the quota hierarchy is made, regardless of whether the + subvolume is already attached to a quota group or not. Also see <varname>Q</varname> below. See <citerefentry + project='die-net'><refentrytitle>btrfs-qgroup</refentrytitle><manvolnum>8</manvolnum></citerefentry> for + details about the btrfs quota group concept.</para></listitem> </varlistentry> <varlistentry> <term><varname>Q</varname></term> - <listitem><para>Similar to <varname>q</varname>. However, - instead of copying the higher-level quota group assignments - from the parent as-is, the lowest quota group of the parent - subvolume is determined that is not the leaf quota - group. Then, an "intermediary" quota group is inserted that - is one level below this level, and shares the same ID part - as the specified subvolume. If no higher-level quota group - exists for the parent subvolume, a new quota group at level - 255 sharing the same ID as the specified subvolume is - inserted instead. This new intermediary quota group is then - assigned to the parent subvolume's higher-level quota - groups, and the specified subvolume's leaf quota group is - assigned to it.</para> - - <para>Effectively, this has a similar effect as - <varname>q</varname>, however introduces a new higher-level - quota group for the specified subvolume that may be used to - enforce limits and accounting to the specified subvolume and - children subvolume created within it. Thus, by creating - subvolumes only via <varname>q</varname> and - <varname>Q</varname>, a concept of "subtree quotas" is - implemented. Each subvolume for which <varname>Q</varname> - is set will get a "subtree" quota group created, and all - child subvolumes created within it will be assigned to - it. Each subvolume for which <varname>q</varname> is set - will not get such a "subtree" quota group, but it is ensured - that they are added to the same "subtree" quota group as their - immediate parents.</para> - - <para>It is recommended to use - <varname>Q</varname> for subvolumes that typically contain - further subvolumes, and where it is desirable to have - accounting and quota limits on all child subvolumes - together. Examples for <varname>Q</varname> are typically - <filename>/home</filename> or - <filename>/var/lib/machines</filename>. In contrast, - <varname>q</varname> should be used for subvolumes that - either usually do not include further subvolumes or where no - accounting and quota limits are needed that apply to all - child subvolumes together. Examples for <varname>q</varname> - are typically <filename>/var</filename> or - <filename>/var/tmp</filename>. As with <varname>Q</varname>, - <varname>q</varname> has no effect on the quota group - hierarchy if the subvolume exists and already has at least - one higher-level quota group assigned.</para></listitem> + <listitem><para>Create the subvolume or directory the same as <varname>v</varname>, but assign the + new subvolume to a new leaf quota group. Instead of copying the higher-level quota group + assignments from the parent as is done with <varname>q</varname>, the lowest quota group of the + parent subvolume is determined that is not the leaf quota group. Then, an "intermediary" quota + group is inserted that is one level below this level, and shares the same ID part as the specified + subvolume. If no higher-level quota group exists for the parent subvolume, a new quota group at + level 255 sharing the same ID as the specified subvolume is inserted instead. This new intermediary + quota group is then assigned to the parent subvolume's higher-level quota groups, and the specified + subvolume's leaf quota group is assigned to it.</para> + + <para>Effectively, this has a similar effect as <varname>q</varname>, however introduces a new higher-level + quota group for the specified subvolume that may be used to enforce limits and accounting to the specified + subvolume and children subvolume created within it. Thus, by creating subvolumes only via + <varname>q</varname> and <varname>Q</varname>, a concept of "subtree quotas" is implemented. Each subvolume + for which <varname>Q</varname> is set will get a "subtree" quota group created, and all child subvolumes + created within it will be assigned to it. Each subvolume for which <varname>q</varname> is set will not get + such a "subtree" quota group, but it is ensured that they are added to the same "subtree" quota group as + their immediate parents.</para> + + <para>It is recommended to use <varname>Q</varname> for subvolumes that typically contain further subvolumes, + and where it is desirable to have accounting and quota limits on all child subvolumes together. Examples for + <varname>Q</varname> are typically <filename>/home</filename> or <filename>/var/lib/machines</filename>. In + contrast, <varname>q</varname> should be used for subvolumes that either usually do not include further + subvolumes or where no accounting and quota limits are needed that apply to all child subvolumes + together. Examples for <varname>q</varname> are typically <filename>/var</filename> or + <filename>/var/tmp</filename>. </para> + + <para>As with <varname>q</varname>, <varname>Q</varname> has no effect on the quota group hierarchy if the + subvolume already exists, regardless of whether the subvolume already belong to a quota group or not. + </para></listitem> </varlistentry> <varlistentry> @@ -352,20 +333,17 @@ L /tmp/foobar - - - - /dev/null</programlisting> <varlistentry> <term><varname>z</varname></term> - <listitem><para>Adjust the access mode, group and user, and - restore the SELinux security context of a file or directory, - if it exists. Lines of this type accept shell-style globs in - place of normal path names. Does not follow symlinks.</para></listitem> + <listitem><para>Adjust the access mode, user and group ownership, and restore the SELinux security + context of a file or directory, if it exists. Lines of this type accept shell-style globs in place + of normal path names. Does not follow symlinks.</para></listitem> </varlistentry> <varlistentry> <term><varname>Z</varname></term> - <listitem><para>Recursively set the access mode, group and - user, and restore the SELinux security context of a file or - directory if it exists, as well as of its subdirectories and - the files contained therein (if applicable). Lines of this - type accept shell-style globs in place of normal path - names. Does not follow symlinks. </para></listitem> + <listitem><para>Recursively set the access mode, user and group ownership, and restore the SELinux + security context of a file or directory if it exists, as well as of its subdirectories and the + files contained therein (if applicable). Lines of this type accept shell-style globs in place of + normal path names. Does not follow symlinks.</para></listitem> </varlistentry> <varlistentry> @@ -460,6 +438,15 @@ r! /tmp/.X[0-9]*-lock</programlisting> running system, and will only be executed with <option>--boot</option>.</para> + <para>If the minus sign is used, this line failing to run + successfully during create (and only create) will not cause + the execution of <command>systemd-tmpfiles</command> to return + an error.</para> + + <para>For example: + <programlisting># Modify sysfs but don't fail if we are in a container with a read-only /proc +w- /proc/sys/vm/swappiness - - - - 10</programlisting></para> + <para>Note that for all line types that result in creation of any kind of file node (i.e. <varname>f</varname>/<varname>F</varname>, <varname>d</varname>/<varname>D</varname>/<varname>v</varname>/<varname>q</varname>/<varname>Q</varname>, @@ -503,18 +490,14 @@ r! /tmp/.X[0-9]*-lock</programlisting> </refsect2> <refsect2> - <title>UID, GID</title> - - <para>The user and group to use for this file or directory. This - may either be a numeric user/group ID or a user or group - name. If omitted or when set to <literal>-</literal>, the - default 0 (root) 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> + <title>User, Group</title> + + <para>The user and group to use for this file or directory. This may either be a numeric ID or a + user/group name. If omitted or when set to <literal>-</literal>, the user and group of the user who + invokes <command>systemd-tmpfiles</command> 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> </refsect2> <refsect2> @@ -638,7 +621,7 @@ r! /tmp/.X[0-9]*-lock</programlisting> <row> <entry><literal>%t</literal></entry> <entry>System or user runtime directory</entry> - <entry>In --user mode, this is the same <varname>$XDG_RUNTIME_DIR</varname>, and <filename>/run</filename> otherwise.</entry> + <entry>In <option>--user</option> mode, this is the same <varname>$XDG_RUNTIME_DIR</varname>, and <filename>/run</filename> otherwise.</entry> </row> <row> <entry><literal>%T</literal></entry> @@ -646,6 +629,16 @@ r! /tmp/.X[0-9]*-lock</programlisting> <entry>This is either <filename>/tmp</filename> or the path <literal>$TMPDIR</literal>, <literal>$TEMP</literal> or <literal>$TMP</literal> are set to.</entry> </row> <row> + <entry><literal>%g</literal></entry> + <entry>User group</entry> + <entry>This is the name of the group running the command. In case of the system instance this resolves to <literal>root</literal>.</entry> + </row> + <row> + <entry><literal>%G</literal></entry> + <entry>User GID</entry> + <entry>This is the numeric GID of the group running the command. In case of the system instance this resolves to <constant>0</constant>.</entry> + </row> + <row> <entry><literal>%u</literal></entry> <entry>User name</entry> <entry>This is the name of the user running the command. In case of the system instance this resolves to <literal>root</literal>.</entry> @@ -749,6 +742,13 @@ e! /var/cache/krb5rcache - - - 0 </refsect1> <refsect1> + <title><filename>/run/</filename> and <filename>/var/run/</filename></title> + <para><filename>/var/run/</filename> is a deprecated symlink to <filename>/run/</filename>, and + applications should use the latter. <command>systemd-tmpfiles</command> will warn if + <filename>/var/run/</filename> is used.</para> + </refsect1> + + <refsect1> <title>See Also</title> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, diff --git a/man/udev.conf.xml b/man/udev.conf.xml index 29c9743d1d..23a4595fa9 100644 --- a/man/udev.conf.xml +++ b/man/udev.conf.xml @@ -42,7 +42,7 @@ <variablelist> <varlistentry> - <term><varname>udev_log</varname></term> + <term><varname>udev_log=</varname></term> <listitem> <para>The log level. Valid values are the numerical @@ -51,6 +51,55 @@ <option>debug</option>.</para> </listitem> </varlistentry> + + <varlistentry> + <term><varname>children_max=</varname></term> + + <listitem> + <para>An integer. The maximum number of events executed in parallel.</para> + + <para>This is the same as the <option>--children-max=</option> option.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>exec_delay=</varname></term> + + <listitem> + <para>An integer. Delay the execution of <varname>RUN</varname> + instructions by the given number of seconds. This option + might be useful when debugging system crashes during + coldplug caused by loading non-working kernel + modules.</para> + + <para>This is the same as the <option>--exec-delay=</option> option.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>event_timeout=</varname></term> + + <listitem> + <para>An integer. The number of seconds to wait for events to finish. After + this time, the event will be terminated. The default is 180 seconds.</para> + + <para>This is the same as the <option>--event-timeout=</option> option.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>resolve_names=</varname></term> + + <listitem> + <para>Specifes when systemd-udevd should resolve names of users and groups. When set to + <option>early</option> (the default), names will be resolved when the rules are parsed. + When set to <option>late</option>, names will be resolved for every event. When set to + <option>never</option>, names will never be resolved and all devices will be owned by + root.</para> + + <para>This is the same as the <option>--resolve-names=</option> option.</para> + </listitem> + </varlistentry> </variablelist> <para> diff --git a/man/udev.xml b/man/udev.xml index 15e6d8eae1..08fedfc86c 100644 --- a/man/udev.xml +++ b/man/udev.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -184,6 +184,8 @@ value itself contains trailing whitespace. </para> </listitem> + </varlistentry> + <varlistentry> <term><varname>SYSCTL{<replaceable>kernel parameter</replaceable>}</varname></term> <listitem> <para>Match a kernel parameter value. diff --git a/man/udevadm.xml b/man/udevadm.xml index f292be4887..44be7b3f89 100644 --- a/man/udevadm.xml +++ b/man/udevadm.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -76,39 +76,40 @@ <refsect2><title>udevadm info <arg choice="opt"><replaceable>options</replaceable></arg> - <arg choice="opt"><replaceable>devpath</replaceable>|<replaceable>file</replaceable></arg> + <arg choice="opt" rep="repeat"><replaceable>devpath</replaceable>|<replaceable>file</replaceable>|<replaceable>unit</replaceable></arg> </title> - <para>Queries the udev database for device information - stored in the udev database. It can also query the properties - of a device from its sysfs representation to help creating udev - rules that match this device.</para> + <para>Query the udev database for device information.</para> + + <para>Positional arguments should be used to specify one or more devices. Each one may be a device name + (in which case it must start with <filename>/dev/</filename>), a sys path (in which case it must start + with <filename>/sys/</filename>), or a systemd device unit name (in which case it must end with + <literal>.device</literal>, see + <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + </para> + <variablelist> <varlistentry> <term><option>-q</option></term> <term><option>--query=<replaceable>TYPE</replaceable></option></term> <listitem> - <para>Query the database for the specified type of device - data. It needs the <option>--path</option> or - <option>--name</option> to identify the specified device. + <para>Query the database for the specified type of device data. Valid <replaceable>TYPE</replaceable>s are: <constant>name</constant>, <constant>symlink</constant>, <constant>path</constant>, <constant>property</constant>, <constant>all</constant>.</para> </listitem> </varlistentry> + <varlistentry> <term><option>-p</option></term> <term><option>--path=<replaceable>DEVPATH</replaceable></option></term> <listitem> - <para>The <filename>/sys</filename> path of the device to - query, e.g. - <filename><optional>/sys</optional>/class/block/sda</filename>. - Note that this option usually is not very useful, since - <command>udev</command> can guess the type of the - argument, so <command>udevadm info - --path=/class/block/sda</command> is equivalent to - <command>udevadm info /sys/class/block/sda</command>.</para> + <para>The <filename>/sys</filename> path of the device to query, e.g. + <filename><optional>/sys</optional>/class/block/sda</filename>. This option is an alternative to + the positional argument with a <filename>/sys/</filename> prefix. <command>udevadm info + --path=/class/block/sda</command> is equivalent to <command>udevadm info + /sys/class/block/sda</command>.</para> </listitem> </varlistentry> <varlistentry> @@ -116,11 +117,9 @@ <term><option>--name=<replaceable>FILE</replaceable></option></term> <listitem> <para>The name of the device node or a symlink to query, - e.g. <filename><optional>/dev</optional>/sda</filename>. - Note that this option usually is not very useful, since - <command>udev</command> can guess the type of the - argument, so <command>udevadm info --name=sda</command> is - equivalent to <command>udevadm info /dev/sda</command>.</para> + e.g. <filename><optional>/dev</optional>/sda</filename>. This option is an alternative to the + positional argument with a <filename>/dev/</filename> prefix. <command>udevadm info + --name=sda</command> is equivalent to <command>udevadm info /dev/sda</command>.</para> </listitem> </varlistentry> <varlistentry> @@ -179,17 +178,17 @@ <xi:include href="standard-options.xml" xpointer="help" /> </variablelist> - - <para>In addition, an optional positional argument can be used - to specify a device name or a sys path. It must start with - <filename>/dev</filename> or <filename>/sys</filename> - respectively.</para> </refsect2> <refsect2><title>udevadm trigger <arg choice="opt"><replaceable>options</replaceable></arg> - <arg choice="opt" rep="repeat"><replaceable>devpath</replaceable>|<replaceable>file</replaceable></arg></title> + <arg choice="opt" rep="repeat"><replaceable>devpath</replaceable>|<replaceable>file</replaceable>|<replaceable>unit</replaceable></arg> + </title> <para>Request device events from the kernel. Primarily used to replay events at system coldplug time.</para> + + <para>Takes one or more device specifications as arguments. See the description of <command>info</command> + above.</para> + <variablelist> <varlistentry> <term><option>-v</option></term> diff --git a/man/user-system-options.xml b/man/user-system-options.xml index eb875661de..4ad2d3b16d 100644 --- a/man/user-system-options.xml +++ b/man/user-system-options.xml @@ -33,12 +33,13 @@ <para>Execute the operation remotely. Specify a hostname, or a username and hostname separated by <literal>@</literal>, to connect to. The hostname may optionally be suffixed by a - container name, separated by <literal>:</literal>, which + port ssh is listening on, seperated by <literal>:</literal>, and then a + container name, separated by <literal>/</literal>, which connects directly to a specific container on the specified host. This will use SSH to talk to the remote machine manager instance. Container names may be enumerated with <command>machinectl -H - <replaceable>HOST</replaceable></command>.</para> + <replaceable>HOST</replaceable></command>. Put IPv6 addresses in brackets.</para> </listitem> </varlistentry> diff --git a/man/user@.service.xml b/man/user@.service.xml new file mode 100644 index 0000000000..30af3c8bf8 --- /dev/null +++ b/man/user@.service.xml @@ -0,0 +1,190 @@ +<?xml version="1.0"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1+ --> + +<refentry id="user@.service"> + <refentryinfo> + <title>user@.service</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>user@.service</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>user@.service</refname> + <refname>user-runtime-dir@.service</refname> + <refpurpose>System units to manage user processes</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>user@<replaceable>UID</replaceable>.service</filename></para> + <para><filename>user-runtime-dir@<replaceable>UID</replaceable>.service</filename></para> + <para><filename>user-<replaceable>UID</replaceable>.slice</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + system manager (PID 1) starts user manager instances as + <filename>user@<replaceable>UID</replaceable>.service</filename>, where the user's numerical UID + is used as the instance identifier. Each <command>systemd --user</command> instance manages a + hierarchy of its own units. See + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> for + a discussion of systemd units and + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for a list of units that form the basis of the unit hierarchies of system and user units.</para> + + <para><filename>user@<replaceable>UID</replaceable>.service</filename> is accompanied by the + system unit <filename>user-runtime-dir@<replaceable>UID</replaceable>.service</filename>, which + creates the user's runtime directory + <filename>/run/user/<replaceable>UID</replaceable></filename>, and then removes it when this + unit is stopped.</para> + + <para>User processes may be started by the <filename>user@.service</filename> instance, in which + case they will be part of that unit in the system hierarchy. They may also be started elsewhere, + for example by + <citerefentry><refentrytitle>sshd</refentrytitle><manvolnum>8</manvolnum></citerefentry> or a + display manager like <command>gdm</command>, in which case they form a .scope unit (see + <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + Both <filename>user@<replaceable>UID</replaceable>.service</filename> and the scope units are + collected under a <filename>user-<replaceable>UID</replaceable>.slice</filename>.</para> + + <para>Individual <filename>user-<replaceable>UID</replaceable>.slice</filename> slices are + collected under <filename>user.slice</filename>, see + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + </para> + </refsect1> + + <refsect1> + <title>Controlling resources for logged-in users</title> + + <para>Options that control resources available to logged-in users can be configured at a few + different levels. As described in the previous section, <filename>user.slice</filename> contains + processes of all users, so any resource limits on that slice apply to all users together. The + usual way to configure them would be through drop-ins, e.g. <filename + noindex='true'>/etc/systemd/system/user.slice.d/resources.conf</filename>. + </para> + + <para>The processes of a single user are collected under + <filename>user-<replaceable>UID</replaceable>.slice</filename>. Resource limits for that user + can be configured through drop-ins for that unit, e.g. <filename + noindex='true'>/etc/systemd/system/user-1000.slice.d/resources.conf</filename>. If the limits + should apply to all users instead, they may be configured through drop-ins for the truncated + unit name, <filename>user-.slice</filename>. For example, configuration in <filename + noindex='true'>/etc/systemd/system/user-.slice.d/resources.conf</filename> is included in all + <filename>user-<replaceable>UID</replaceable>.slice</filename> units, see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for a discussion of the drop-in mechanism.</para> + + <para>When a user logs in and a .scope unit is created for the session (see previous section), + the creation of the scope may be managed through + <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + This PAM module communicates with + <citerefentry><refentrytitle>systemd-logind</refentrytitle><manvolnum>8</manvolnum></citerefentry> + to create the session scope and provide access to hardware resources. Resource limits for the + scope may be configured through the PAM module configuration, see + <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + Configuring them through the normal unit configuration is also possible, but since + the name of the slice unit is generally unpredictable, this is less useful.</para> + + <para>In general any resources that apply to units may be set for + <filename>user@<replaceable>UID</replaceable>.service</filename> and the slice + units discussed above, see + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for an overview.</para> + </refsect1> + + <refsect1> + <title>Examples</title> + <example> + <title>Hierarchy of control groups with two logged in users</title> + + <programlisting>$ systemd-cgls +Control group /: +-.slice +├─user.slice +│ ├─user-1000.slice +│ │ ├─user@1000.service +│ │ │ ├─pulseaudio.service +│ │ │ │ └─2386 /usr/bin/pulseaudio --daemonize=no +│ │ │ └─gnome-terminal-server.service +│ │ │ └─init.scope +│ │ │ ├─ 4127 /usr/libexec/gnome-terminal-server +│ │ │ └─ 4198 zsh +│ │ … +│ │ └─session-4.scope +│ │ ├─ 1264 gdm-session-worker [pam/gdm-password] +│ │ ├─ 2339 /usr/bin/gnome-shell +│ │ … +│ │ ├─session-19.scope +│ │ ├─6497 sshd: zbyszek [priv] +│ │ ├─6502 sshd: zbyszek@pts/6 +│ │ ├─6509 -zsh +│ │ └─6602 systemd-cgls --no-pager +│ … +│ └─user-1001.slice +│ ├─session-20.scope +│ │ ├─6675 sshd: guest [priv] +│ │ ├─6708 sshd: guest@pts/6 +│ │ └─6717 -bash +│ └─user@1001.service +│ ├─init.scope +│ │ ├─6680 /usr/lib/systemd/systemd --user +│ │ └─6688 (sd-pam) +│ └─sleep.service +│ └─6706 /usr/bin/sleep 30 +…</programlisting> + <para>User with UID 1000 is logged in using <command>gdm</command> (<filename + noindex='true'>session-4.scope</filename>) and + <citerefentry><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry> + (<filename noindex='true'>session-19.scope</filename>), and also has a user manager instance + running (<filename noindex='true'>user@1000.service</filename>). User with UID 1001 is logged + in using <command>ssh</command> (<filename noindex='true'>session-20.scope</filename>) and + also has a user manager instance running (<filename + noindex='true'>user@1001.service</filename>). Those are all (leaf) system units, and form + part of the slice hierarchy, with <filename noindex='true'>user-1000.slice</filename> and + <filename noindex='true'>user-1001.slice</filename> below <filename + noindex='true'>user.slice</filename>. User units are visible below the + <filename>user@.service</filename> instances (<filename + noindex='true'>pulseaudio.service</filename>, <filename + noindex='true'>gnome-terminal-server.service</filename>, <filename + noindex='true'>init.scope</filename>, <filename noindex='true'>sleep.service</filename>). + </para> + </example> + + <example> + <title>Default user resource limits</title> + + <programlisting>$ systemctl cat user-1000.slice +# /usr/lib/systemd/system/user-.slice.d/10-defaults.conf +# … +[Unit] +Description=User Slice of UID %j +After=systemd-user-sessions.service + +[Slice] +TasksMax=33%</programlisting> + <para>The <filename>user-<replaceable>UID</replaceable>.slice</filename> units by default don't + have a unit file. The resource limits are set through a drop-in, which can be easily replaced + or extended following standard drop-in mechanisms discussed in the first section.</para> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> +</refentry> |