diff options
Diffstat (limited to 'man')
202 files changed, 14198 insertions, 4960 deletions
diff --git a/man/.gitignore b/man/.gitignore index bf5eeab938..d928e5a83f 100644 --- a/man/.gitignore +++ b/man/.gitignore @@ -1,4 +1,5 @@ /systemd.directives.xml /systemd.index.xml /*.[13578] +/*.html /custom-entities.ent diff --git a/man/bootchart.conf.xml b/man/bootchart.conf.xml deleted file mode 100644 index bf6ca0bf9e..0000000000 --- a/man/bootchart.conf.xml +++ /dev/null @@ -1,172 +0,0 @@ -<?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"> - -<!-- - This file is part of systemd. - - Copyright 2012 Intel Corporation - - Authors: - Auke Kok <auke-jan.h.kok@intel.com> - - systemd is free software; you can redistribute it and/or modify it - under the terms of the GNU Lesser General Public License as published by - the Free Software Foundation; either version 2.1 of the License, or - (at your option) any later version. - - systemd is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public License - along with systemd; If not, see <http://www.gnu.org/licenses/>. ---> - -<refentry id="bootchart.conf" conditional='ENABLE_BOOTCHART' - xmlns:xi="http://www.w3.org/2001/XInclude"> - <refentryinfo> - <title>bootchart.conf</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Auke</firstname> - <surname>Kok</surname> - <email>auke-jan.h.kok@intel.com</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>bootchart.conf</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>bootchart.conf</refname> - <refname>bootchart.conf.d</refname> - <refpurpose>Boot performance analysis graphing tool configuration files</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/systemd/bootchart.conf</filename></para> - <para><filename>/etc/systemd/bootchart.conf.d/*.conf</filename></para> - <para><filename>/run/systemd/bootchart.conf.d/*.conf</filename></para> - <para><filename>/usr/lib/systemd/bootchart.conf.d/*.conf</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>When starting, systemd-bootchart will read the configuration - file <filename>/etc/systemd/bootchart.conf</filename>, followed by - the files in the <filename>bootchart.conf.d</filename> - directories. These configuration files determine logging - parameters and graph output.</para> - </refsect1> - - <xi:include href="standard-conf.xml" xpointer="main-conf" /> - - <refsect1> - <title>Options</title> - - <variablelist class='bootchart-directives'> - - <varlistentry> - <term><varname>Samples=500</varname></term> - <listitem><para>Configure the amount of samples to record in - total before bootchart exits. Each sample will record at - intervals defined by Frequency=.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Frequency=25</varname></term> - <listitem><para>Configure the sample log frequency. This can - be a fractional number, but must be larger than 0.0. Most - systems can cope with values under 25-50 without impacting - boot time severely.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Relative=no</varname></term> - <listitem><para>Configures whether the left axis of the output - graph equals time=0.0 (<constant>CLOCK_MONOTONIC</constant> - start). This is useful for using bootchart at post-boot time - to profile an already booted system, otherwise the graph would - become extremely large. If set to yes, the horizontal axis - starts at the first recorded sample instead of time=0.0. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Filter=no</varname></term> - <listitem><para>Configures whether the resulting graph should - omit tasks that did not contribute significantly to the boot. - Processes that are too short-lived (only seen in one sample) - or that do not consume any significant CPU time (less than - 0.001sec) will not be displayed in the output - graph.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Output=[path]</varname></term> - <listitem><para>Configures the output directory for writing - the graphs. By default, bootchart writes the graphs to - <filename>/run/log</filename>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Init=[path]</varname></term> - <listitem><para>Configures bootchart to run a non-standard - binary instead of - <filename>/usr/lib/systemd/systemd</filename>. This option is - only relevant if bootchart was invoked from the kernel command - line with - init=/usr/lib/systemd/systemd-bootchart.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>PlotMemoryUsage=no</varname></term> - <listitem><para>If set to yes, enables logging and graphing of - processes' PSS memory consumption.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>PlotEntropyGraph=no</varname></term> - <listitem><para>If set to yes, enables logging and graphing of - the kernel random entropy pool size.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ScaleX=100</varname></term> - <listitem><para>Horizontal scaling factor for all variable - graph components.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ScaleY=20</varname></term> - <listitem><para>Vertical scaling factor for all variable graph - components.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ControlGroup=no</varname></term> - <listitem><para>Display process control group. - </para></listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd-bootchart</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/bootctl.xml b/man/bootctl.xml index 63ad9392eb..e2575a4751 100644 --- a/man/bootctl.xml +++ b/man/bootctl.xml @@ -47,16 +47,16 @@ <refsynopsisdiv> <cmdsynopsis> - <command>bootctl <arg choice="opt" rep="repeat">OPTIONS</arg>status</command> + <command>bootctl <arg choice="opt" rep="repeat">OPTIONS</arg> status</command> </cmdsynopsis> <cmdsynopsis> - <command>bootctl <arg choice="opt" rep="repeat">OPTIONS</arg>update</command> + <command>bootctl <arg choice="opt" rep="repeat">OPTIONS</arg> update</command> </cmdsynopsis> <cmdsynopsis> - <command>bootctl <arg choice="opt" rep="repeat">OPTIONS</arg>install</command> + <command>bootctl <arg choice="opt" rep="repeat">OPTIONS</arg> install</command> </cmdsynopsis> <cmdsynopsis> - <command>bootctl <arg choice="opt" rep="repeat">OPTIONS</arg>remove</command> + <command>bootctl <arg choice="opt" rep="repeat">OPTIONS</arg> remove</command> </cmdsynopsis> </refsynopsisdiv> @@ -68,28 +68,23 @@ system.</para> <para><command>bootctl status</command> checks and prints the - currently installed versions of the boot loader binaries and the + currently installed versions of the boot loader binaries and all current EFI boot variables.</para> - <para><command>bootctl update</command> updates all installed - versions of systemd-boot, if the current version is newer than the - version installed in the EFI system partition. This also includes - the EFI default/fallback loader at /EFI/Boot/boot*.efi. 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> + <para><command>bootctl update</command> updates all installed versions of systemd-boot, 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>/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> - <para><command>bootctl install</command> installs systemd-boot into - the EFI system partition. A copy of systemd-boot will be stored as - the EFI default/fallback loader at /EFI/Boot/boot*.efi. A systemd-boot - entry in the EFI boot variables is created and added to the top - of the boot order list.</para> + <para><command>bootctl install</command> installs systemd-boot into the EFI system partition. A copy of + systemd-boot will be stored as the EFI default/fallback loader at <filename>/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> <para><command>bootctl remove</command> removes all installed versions of systemd-boot from the EFI system partition, and removes systemd-boot from the EFI boot variables.</para> - <para>If no command is passed <command>status</command> is + <para>If no command is passed, <command>status</command> is implied.</para> </refsect1> @@ -101,8 +96,10 @@ <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. The default is /boot.</para></listitem> + <term><option>--path=</option></term> + <listitem><para>Path to the EFI System Partition (ESP). If not specified, <filename>/efi</filename>, + <filename>/boot</filename>, and <filename>/boot/efi</filename> are checked in turn. It is recommended to mount + the ESP to <filename>/boot</filename>, if possible.</para></listitem> </varlistentry> <varlistentry> @@ -114,7 +111,7 @@ <refsect1> <title>Exit status</title> - <para>On success 0 is returned, a non-zero failure + <para>On success, 0 is returned, a non-zero failure code otherwise.</para> </refsect1> diff --git a/man/bootup.xml b/man/bootup.xml index b92057af29..986996398c 100644 --- a/man/bootup.xml +++ b/man/bootup.xml @@ -179,6 +179,8 @@ identical to the system manager bootup (see above) until it reaches <filename>basic.target</filename>. From there, systemd approaches the special target <filename>initrd.target</filename>. + When the root device becomes available, + <filename>initd-root-device.target</filename> is reached. If the root device can be mounted at <filename>/sysroot</filename>, the <filename>sysroot.mount</filename> unit becomes active and @@ -204,7 +206,10 @@ | emergency.service ______________________/| | / | v - | sysroot.mount <emphasis>emergency.target</emphasis> + | initrd-root-device.target <emphasis>emergency.target</emphasis> + | | + | v + | sysroot.mount | | | v | initrd-root-fs.target diff --git a/man/busctl.xml b/man/busctl.xml index 4f0b2a7051..052a33097f 100644 --- a/man/busctl.xml +++ b/man/busctl.xml @@ -119,15 +119,17 @@ <term><option>--match=<replaceable>MATCH</replaceable></option></term> <listitem><para>When showing messages being exchanged, show only the - subset matching <replaceable>MATCH</replaceable>.</para></listitem> - <!-- TODO: link to sd_bus_add_match when it is written? --> + subset matching <replaceable>MATCH</replaceable>. + See + <citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + </para></listitem> </varlistentry> <varlistentry> <term><option>--size=</option></term> <listitem> - <para>When used with the <command>capture</command> command + <para>When used with the <command>capture</command> command, specifies the maximum bus message size to capture ("snaplen"). Defaults to 4096 bytes.</para> </listitem> @@ -137,7 +139,7 @@ <term><option>--list</option></term> <listitem> - <para>When used with the <command>tree</command> command shows a + <para>When used with the <command>tree</command> command, shows a flat list of object paths instead of a tree.</para> </listitem> </varlistentry> @@ -146,9 +148,9 @@ <term><option>--quiet</option></term> <listitem> - <para>When used with the <command>call</command> command + <para>When used with the <command>call</command> command, suppresses display of the response message payload. Note that even - if this option is specified errors returned will still be + if this option is specified, errors returned will still be printed and the tool will indicate success or failure with the process exit code.</para> </listitem> @@ -159,7 +161,7 @@ <listitem> <para>When used with the <command>call</command> or - <command>get-property</command> command shows output in a + <command>get-property</command> command, shows output in a more verbose format.</para> </listitem> </varlistentry> @@ -168,15 +170,15 @@ <term><option>--expect-reply=</option><replaceable>BOOL</replaceable></term> <listitem> - <para>When used with the <command>call</command> command + <para>When used with the <command>call</command> command, specifies whether <command>busctl</command> shall wait for completion of the method call, output the returned method response data, and return success or failure via the process - exit code. If this is set to <literal>no</literal> the + exit code. If this is set to <literal>no</literal>, the method call will be issued but no response is expected, the tool terminates immediately, and thus no response can be shown, and no success or failure is returned via the exit - code. To only suppress output of the reply message payload + code. To only suppress output of the reply message payload, use <option>--quiet</option> above. Defaults to <literal>yes</literal>.</para> </listitem> @@ -186,9 +188,9 @@ <term><option>--auto-start=</option><replaceable>BOOL</replaceable></term> <listitem> - <para>When used with the <command>call</command> command specifies + <para>When used with the <command>call</command> command, specifies whether the method call should implicitly activate the - called service should it not be running yet but is + called service, should it not be running yet but is configured to be auto-started. Defaults to <literal>yes</literal>.</para> </listitem> @@ -198,7 +200,7 @@ <term><option>--allow-interactive-authorization=</option><replaceable>BOOL</replaceable></term> <listitem> - <para>When used with the <command>call</command> command + <para>When used with the <command>call</command> command, specifies whether the services may enforce interactive authorization while executing the operation, if the security policy is configured for this. Defaults to @@ -210,14 +212,14 @@ <term><option>--timeout=</option><replaceable>SECS</replaceable></term> <listitem> - <para>When used with the <command>call</command> command + <para>When used with the <command>call</command> command, specifies the maximum time to wait for method call - completion. If no time unit is specified assumes + completion. If no time unit is specified, assumes seconds. The usual other units are understood, too (ms, us, s, min, h, d, w, month, y). Note that this timeout does not - apply if <option>--expect-reply=no</option> is used as the + apply if <option>--expect-reply=no</option> is used, as the tool does not wait for any reply message then. When not - specified or when set to 0 the default of + specified or when set to 0, the default of <literal>25s</literal> is assumed.</para> </listitem> </varlistentry> @@ -229,9 +231,9 @@ <para>Controls whether credential data reported by <command>list</command> or <command>status</command> shall be augmented with data from - <filename>/proc</filename>. When this is turned on the data + <filename>/proc</filename>. When this is turned on, the data shown is possibly inconsistent, as the data read from - <filename>/proc</filename> might be more recent than rest of + <filename>/proc</filename> might be more recent than the rest of the credential information. Defaults to <literal>yes</literal>.</para> </listitem> </varlistentry> @@ -258,7 +260,7 @@ <term><command>list</command></term> <listitem><para>Show all peers on the bus, by their service - names. By default shows both unique and well-known names, but + names. By default, shows both unique and well-known names, but this may be changed with the <option>--unique</option> and <option>--acquired</option> switches. This is the default operation if no command is specified.</para></listitem> @@ -281,14 +283,14 @@ <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 dump.</para></listitem> + terminate the dump.</para></listitem> </varlistentry> <varlistentry> <term><command>capture</command> <arg choice="opt" rep="repeat"><replaceable>SERVICE</replaceable></arg></term> <listitem><para>Similar to <command>monitor</command> but - writes the output in pcap format (for details see the <ulink + writes the output in pcap format (for details, see the <ulink url="http://wiki.wireshark.org/Development/LibpcapFileFormat">Libpcap File Format</ulink> description. Make sure to redirect the output to STDOUT to a file. Tools like @@ -312,7 +314,7 @@ <listitem><para>Show interfaces, methods, properties and signals of the specified object (identified by its path) on - the specified service. If the interface argument is passed the + the specified service. If the interface argument is passed, the output is limited to members of the specified interface.</para></listitem> </varlistentry> @@ -322,10 +324,10 @@ <listitem><para>Invoke a method and show the response. Takes a service name, object path, interface name and method name. If - parameters shall be passed to the method call a signature + parameters shall be passed to the method call, a signature string is required, followed by the arguments, individually formatted as strings. For details on the formatting used, see - below. To suppress output of the returned data use the + below. To suppress output of the returned data, use the <option>--quiet</option> option.</para></listitem> </varlistentry> @@ -335,16 +337,16 @@ <listitem><para>Retrieve the current value of one or more object properties. Takes a service name, object path, interface name and property name. Multiple properties may be - specified at once in which case their values will be shown one - after the other, separated by newlines. The output is by - default in terse format. Use <option>--verbose</option> for a + specified at once, in which case their values will be shown one + after the other, separated by newlines. The output is, by + default, in terse format. Use <option>--verbose</option> for a more elaborate output format.</para></listitem> </varlistentry> <varlistentry> <term><command>set-property</command> <arg choice="plain"><replaceable>SERVICE</replaceable></arg> <arg choice="plain"><replaceable>OBJECT</replaceable></arg> <arg choice="plain"><replaceable>INTERFACE</replaceable></arg> <arg choice="plain"><replaceable>PROPERTY</replaceable></arg> <arg choice="plain"><replaceable>SIGNATURE</replaceable></arg> <arg choice="plain" rep="repeat"><replaceable>ARGUMENT</replaceable></arg></term> - <listitem><para>Set the current value an object + <listitem><para>Set the current value of an object property. Takes a service name, object path, interface name, property name, property signature, followed by a list of parameters formatted as strings.</para></listitem> @@ -364,19 +366,19 @@ <para>The <command>call</command> and <command>set-property</command> commands take a signature string followed by a list of parameters formatted as string (for details - on D-Bus signature strings see the <ulink + on D-Bus signature strings, see the <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#type-system">Type system chapter of the D-Bus specification</ulink>). For simple - types each parameter following the signature should simply be the + types, each parameter following the signature should simply be the parameter's value formatted as string. Positive boolean values may be formatted as <literal>true</literal>, <literal>yes</literal>, - <literal>on</literal>, <literal>1</literal>; negative boolean + <literal>on</literal>, or <literal>1</literal>; negative boolean values may be specified as <literal>false</literal>, - <literal>no</literal>, <literal>off</literal>, + <literal>no</literal>, <literal>off</literal>, or <literal>0</literal>. For arrays, a numeric argument for the number of entries followed by the entries shall be specified. For - variants the signature of the contents shall be specified, - followed by the contents. For dictionaries and structs the + variants, the signature of the contents shall be specified, + followed by the contents. For dictionaries and structs, the contents of them shall be directly specified.</para> <para>For example, @@ -395,7 +397,7 @@ array that maps strings to variants, consisting of three entries. The string <literal>One</literal> is assigned the string <literal>Eins</literal>. The string - <literal>Two</literal> is assigned the 32bit unsigned + <literal>Two</literal> is assigned the 32-bit unsigned integer 2. The string <literal>Yes</literal> is assigned a positive boolean.</para> @@ -448,7 +450,7 @@ ARRAY "s" { <example> <title>Invoking a Method</title> - <para>The following command invokes a the + <para>The following command invokes the <literal>StartUnit</literal> method on the <literal>org.freedesktop.systemd1.Manager</literal> interface of the @@ -456,8 +458,8 @@ ARRAY "s" { of the <literal>org.freedesktop.systemd1</literal> service, and passes it two strings <literal>cups.service</literal> and - <literal>replace</literal>. As result of the method - call a single object path parameter is received and + <literal>replace</literal>. As a result of the method + call, a single object path parameter is received and shown:</para> <programlisting># busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager StartUnit ss "cups.service" "replace" @@ -473,7 +475,6 @@ o "/org/freedesktop/systemd1/job/42684"</programlisting> <ulink url="http://freedesktop.org/wiki/Software/dbus">D-Bus</ulink>, <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-bus-proxyd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry project='die-net'><refentrytitle>wireshark</refentrytitle><manvolnum>1</manvolnum></citerefentry> </para> diff --git a/man/coredump.conf.xml b/man/coredump.conf.xml index fd54c59e6b..77b4dac51c 100644 --- a/man/coredump.conf.xml +++ b/man/coredump.conf.xml @@ -45,7 +45,7 @@ <refnamediv> <refname>coredump.conf</refname> <refname>coredump.conf.d</refname> - <refpurpose>Coredump storage configuration files</refpurpose> + <refpurpose>Core dump storage configuration files</refpurpose> </refnamediv> <refsynopsisdiv> @@ -58,9 +58,16 @@ <refsect1> <title>Description</title> - <para>These files configure the behaviour of + <para>These files configure the behavior of <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - a handler for core dumps invoked by the kernel.</para> + a handler for core dumps invoked by the kernel. Whether <command>systemd-coredump</command> is used + is determined by the kernel's + <varname>kernel.core_pattern</varname> <citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> + setting. See + <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry> + and + <citerefentry project='man-pages'><refentrytitle>core</refentrytitle><manvolnum>5</manvolnum></citerefentry> + pages for the details.</para> </refsect1> <xi:include href="standard-conf.xml" xpointer="main-conf" /> @@ -76,16 +83,13 @@ <varlistentry> <term><varname>Storage=</varname></term> - <listitem><para>Controls where to store cores. One of - <literal>none</literal>, <literal>external</literal>, - <literal>journal</literal>, and <literal>both</literal>. When - <literal>none</literal>, the coredumps will be logged but not - stored permanently. When <literal>external</literal> (the - default), cores will be stored in <filename>/var/lib/systemd/coredump</filename>. - When <literal>journal</literal>, cores will be stored in - the journal and rotated following normal journal - rotation patterns. When <literal>both</literal>, cores - will be stored in both locations.</para> + <listitem><para>Controls where to store cores. One of <literal>none</literal>, + <literal>external</literal>, and <literal>journal</literal>. When + <literal>none</literal>, the core dumps will be logged (included the traceback if + possible), but not stored permanently. When <literal>external</literal> (the + default), cores will be stored in <filename>/var/lib/systemd/coredump/</filename>. + When <literal>journal</literal>, cores will be stored in the journal and rotated + following normal journal rotation patterns.</para> <para>When cores are stored in the journal, they might be compressed following journal compression settings, see @@ -98,7 +102,7 @@ <term><varname>Compress=</varname></term> <listitem><para>Controls compression for external - storage. Takes a boolean argument, defaults to + storage. Takes a boolean argument, which defaults to <literal>yes</literal>.</para> </listitem> </varlistentry> @@ -107,7 +111,7 @@ <term><varname>ProcessSizeMax=</varname></term> <listitem><para>The maximum size in bytes of a core - which will be processed. Coredumps exceeding this size + which will be processed. Core dumps exceeding this size will be logged, but the backtrace will not be generated and the core will not be stored.</para></listitem> </varlistentry> @@ -125,17 +129,17 @@ <term><varname>KeepFree=</varname></term> <listitem><para>Enforce limits on the disk space taken up by - externally stored coredumps. <option>MaxUse=</option> makes - sure that old coredumps are removed as soon as the total disk - space taken up by coredumps grows beyond this limit (defaults + externally stored core dumps. <option>MaxUse=</option> makes + sure that old core dumps are removed as soon as the total disk + space taken up by core dumps grows beyond this limit (defaults to 10% of the total disk size). <option>KeepFree=</option> controls how much disk space to keep free at least (defaults to 15% of the total disk size). Note that the disk space used - by coredumps might temporarily exceed these limits while - coredumps are processed. Note that old coredumps are also + by core dumps might temporarily exceed these limits while + core dumps are processed. Note that old core dumps are also removed based on time via <citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Set - either value to 0 to turn off size based + either value to 0 to turn off size-based clean-up.</para></listitem> </varlistentry> </variablelist> diff --git a/man/coredumpctl.xml b/man/coredumpctl.xml index efbc655a76..abc245be5e 100644 --- a/man/coredumpctl.xml +++ b/man/coredumpctl.xml @@ -45,7 +45,7 @@ <refnamediv> <refname>coredumpctl</refname> - <refpurpose>Retrieve coredumps from the journal</refpurpose> + <refpurpose>Retrieve and process saved core dumps and metadata</refpurpose> </refnamediv> <refsynopsisdiv> @@ -60,9 +60,10 @@ <refsect1> <title>Description</title> - <para><command>coredumpctl</command> may be used to - retrieve coredumps from - <citerefentry><refentrytitle>systemd-journald</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + <para><command>coredumpctl</command> is a tool that can be used to retrieve and process core + dumps and metadata which were saved by + <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + </para> </refsect1> <refsect1> @@ -71,42 +72,55 @@ <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>--no-legend</option></term> - <listitem><para>Do not print column headers. - </para></listitem> + <listitem><para>Do not print column headers.</para></listitem> </varlistentry> + <xi:include href="standard-options.xml" xpointer="no-pager" /> + <varlistentry> <term><option>-1</option></term> - <listitem><para>Show information of a single coredump only, - instead of listing all known coredumps. </para></listitem> + <listitem><para>Show information of a single core dump only, instead of listing + all known core dumps.</para></listitem> </varlistentry> <varlistentry> - <term><option>-F</option></term> - <term><option>--field=</option></term> + <term><option>-F</option> <replaceable>FIELD</replaceable></term> + <term><option>--field=</option><replaceable>FIELD</replaceable></term> <listitem><para>Print all possible data values the specified - field takes in matching coredump entries of the + field takes in matching core dump entries of the journal.</para></listitem> </varlistentry> <varlistentry> - <term><option>-o</option></term> - <term><option>--output=FILE</option></term> + <term><option>-o</option> <replaceable>FILE</replaceable></term> + <term><option>--output=</option><replaceable>FILE</replaceable></term> <listitem><para>Write the core to <option>FILE</option>. </para></listitem> </varlistentry> - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - <xi:include href="standard-options.xml" xpointer="no-pager" /> + <varlistentry> + <term><option>-D</option> <replaceable>DIR</replaceable></term> + <term><option>--directory=</option><replaceable>DIR</replaceable></term> + + <listitem><para>Use the journal files in the specified <option>DIR</option>. + </para></listitem> + </varlistentry> </variablelist> + </refsect1> + + <refsect1> + <title>Commands</title> <para>The following commands are understood:</para> @@ -114,31 +128,39 @@ <varlistentry> <term><command>list</command></term> - <listitem><para>List coredumps captured in the journal + <listitem><para>List core dumps captured in the journal matching specified characteristics. If no command is - specified, this is the implied default.</para></listitem> + specified, this is the implied default.</para> + + <para>It's worth noting that different restrictions apply to + data saved in the journal and core dump files saved in + <filename>/var/lib/systemd/coredump</filename>, see overview in + <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + Thus it may very well happen that a particular core dump is still listed + in the journal while its corresponding core dump file has already been + removed.</para></listitem> </varlistentry> <varlistentry> <term><command>info</command></term> - <listitem><para>Show detailed information about coredumps + <listitem><para>Show detailed information about core dumps captured in the journal.</para></listitem> </varlistentry> <varlistentry> <term><command>dump</command></term> - <listitem><para>Extract the last coredump matching specified - characteristics. The coredump will be written on standard + <listitem><para>Extract the last core dump matching specified + characteristics. The core dump will be written on standard output, unless an output file is specified with - <option>-o/--output</option>. </para></listitem> + <option>--output=</option>. </para></listitem> </varlistentry> <varlistentry> <term><command>gdb</command></term> - <listitem><para>Invoke the GNU debugger on the last coredump + <listitem><para>Invoke the GNU debugger on the last core dump matching specified characteristics. </para></listitem> </varlistentry> @@ -189,7 +211,7 @@ <refsect1> <title>Exit status</title> <para>On success, 0 is returned; otherwise, a non-zero failure - code is returned. Not finding any matching coredumps is treated as + code is returned. Not finding any matching core dumps is treated as failure. </para> </refsect1> @@ -198,13 +220,13 @@ <title>Examples</title> <example> - <title>List all the coredumps of a program named foo</title> + <title>List all the core dumps of a program named foo</title> <programlisting># coredumpctl list foo</programlisting> </example> <example> - <title>Invoke gdb on the last coredump</title> + <title>Invoke gdb on the last core dump</title> <programlisting># coredumpctl gdb</programlisting> </example> @@ -217,7 +239,7 @@ </example> <example> - <title>Extract the last coredump of /usr/bin/bar to a file named + <title>Extract the last core dump of /usr/bin/bar to a file named <filename noindex="true">bar.coredump</filename></title> <programlisting># coredumpctl -o bar.coredump dump /usr/bin/bar</programlisting> diff --git a/man/crypttab.xml b/man/crypttab.xml index d4ff760adc..4b8d4aa3d6 100644 --- a/man/crypttab.xml +++ b/man/crypttab.xml @@ -93,7 +93,7 @@ field is not present or the password is set to <literal>none</literal> or <literal>-</literal>, the password has to be manually entered during system boot. Otherwise, the field is - interpreted as a absolute path to a file containing the encryption + interpreted as an absolute path to a file containing the encryption password. For swap encryption, <filename>/dev/urandom</filename> or the hardware device <filename>/dev/hw_random</filename> can be used as the password file; using <filename>/dev/random</filename> @@ -160,10 +160,10 @@ at the beginning. This is different from the <option>--offset</option> option with respect to the sector numbers used in initialization vector (IV) calculation. Using <option>--offset</option> will shift the IV - calculation by the same negative amount. Hence, if <option>--offset n</option>, + calculation by the same negative amount. Hence, if <option>--offset n</option> is given, sector n will get a sector number of 0 for the IV calculation. Using <option>--skip</option> causes sector n to also be the first - sector of the mapped device, but with its number for IV generation is n.</para> + sector of the mapped device, but with its number for IV generation being n.</para> <para>This option is only relevant for plain devices.</para> </listitem> diff --git a/man/custom-html.xsl b/man/custom-html.xsl index 151276362c..e89d73e7f1 100644 --- a/man/custom-html.xsl +++ b/man/custom-html.xsl @@ -37,7 +37,8 @@ <xsl:template match="citerefentry[not(@project)]"> <a> <xsl:attribute name="href"> - <xsl:value-of select="refentrytitle"/><xsl:text>.html</xsl:text> + <xsl:value-of select="refentrytitle"/><xsl:text>.html#</xsl:text> + <xsl:value-of select="refentrytitle/@target"/> </xsl:attribute> <xsl:call-template name="inline.charseq"/> </a> @@ -125,7 +126,7 @@ <!-- - helper template to do conflict resolution between various headings with the same inferred ID attribute/tag from the headerlink template - - this conflict resolution is necessary to prevent malformed HTML ouput (multiple id attributes with the same value) + - this conflict resolution is necessary to prevent malformed HTML output (multiple ID attributes with the same value) - and it fixes xsltproc warnings during compilation of HTML man pages - - A simple top-to-bottom numbering scheme is implemented for nodes with the same ID value to derive unique ID values for HTML output. @@ -171,7 +172,7 @@ <!-- - If stable URLs with fragment markers (references to the ID) turn out not to be important: - generatedID could simply take the value of generate-id(), and various other helper templates may be dropped entirely. - - Alternatively if xsltproc is patched to generate reproducible generate-id() output the same simplifications can be + - Alternatively, if xsltproc is patched to generate reproducible generate-id() output, the same simplifications can be - applied at the cost of breaking compatibility with URLs generated from output of previous versions of this stylesheet. --> <xsl:variable name="generatedID"> diff --git a/man/daemon.xml b/man/daemon.xml index a8bbfc055b..485c66225e 100644 --- a/man/daemon.xml +++ b/man/daemon.xml @@ -180,14 +180,12 @@ functionality of the init system, it is recommended not to execute them when run as new-style service.</para> - <para>Note that new-style init systems guarantee execution of - daemon processes in a clean process context: it is guaranteed - that the environment block is sanitized, that the signal - handlers and mask is reset and that no left-over file - descriptors are passed. Daemons will be executed in their own - session, with standard input/output/error connected to - <filename>/dev/null</filename> unless otherwise configured. The - umask is reset. + <para>Note that new-style init systems guarantee execution of daemon processes in a clean process context: it is + guaranteed that the environment block is sanitized, that the signal handlers and mask is reset and that no + left-over file descriptors are passed. Daemons will be executed in their own session, with standard input + connected to <filename>/dev/null</filename> and standard output/error connected to the + <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + logging service, unless otherwise configured. The umask is reset. </para> <para>It is recommended for new-style daemons to implement the @@ -234,7 +232,7 @@ bus-activatable by supplying a D-Bus service activation configuration file. This has multiple advantages: your daemon may be started lazily on-demand; it may be started in parallel - to other daemons requiring it -- which maximizes + to other daemons requiring it — which maximizes parallelization and boot-up speed; your daemon can be restarted on failure without losing any bus requests, as the bus queues requests for activatable services. See below for @@ -490,13 +488,13 @@ configured address redundant. Another often suggested trigger for service activation is low system load. However, here too, a more convincing approach might be to make proper use of features - of the operating system, in particular, the CPU or IO scheduler + of the operating system, in particular, the CPU or I/O scheduler of Linux. Instead of scheduling jobs from userspace based on monitoring the OS scheduler, it is advisable to leave the scheduling of processes to the OS scheduler itself. systemd - provides fine-grained access to the CPU and IO schedulers. If a + provides fine-grained access to the CPU and I/O schedulers. If a process executed by the init system shall not negatively impact - the amount of CPU or IO bandwidth available to other processes, + the amount of CPU or I/O bandwidth available to other processes, it should be configured with <varname>CPUSchedulingPolicy=idle</varname> and/or <varname>IOSchedulingClass=idle</varname>. Optionally, this may diff --git a/man/dnssec-trust-anchors.d.xml b/man/dnssec-trust-anchors.d.xml new file mode 100644 index 0000000000..9a28862ceb --- /dev/null +++ b/man/dnssec-trust-anchors.d.xml @@ -0,0 +1,198 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2016 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="dnssec-trust-anchors.d" conditional='ENABLE_RESOLVED' + xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>dnssec-trust-anchors.d</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>dnssec-trust-anchors.d</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>dnssec-trust-anchors.d</refname> + <refname>systemd.positive</refname> + <refname>systemd.negative</refname> + <refpurpose>DNSSEC trust anchor configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/dnssec-trust-anchors.d/*.positive</filename></para> + <para><filename>/run/dnssec-trust-anchors.d/*.positive</filename></para> + <para><filename>/usr/lib/dnssec-trust-anchors.d/*.positive</filename></para> + <para><filename>/etc/dnssec-trust-anchors.d/*.negative</filename></para> + <para><filename>/run/dnssec-trust-anchors.d/*.negative</filename></para> + <para><filename>/usr/lib/dnssec-trust-anchors.d/*.negative</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The DNSSEC trust anchor configuration files define positive + and negative trust anchors + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + bases DNSSEC integrity proofs on.</para> + </refsect1> + + <refsect1> + <title>Positive Trust Anchors</title> + + <para>Positive trust anchor configuration files contain DNSKEY and + DS resource record definitions to use as base for DNSSEC integrity + proofs. See <ulink + url="https://tools.ietf.org/html/rfc4035#section-4.4">RFC 4035, + Section 4.4</ulink> for more information about DNSSEC trust + anchors.</para> + + <para>Positive trust anchors are read from files with the suffix + <filename>.positive</filename> located in + <filename>/etc/dnssec-trust-anchors.d/</filename>, + <filename>/run/dnssec-trust-anchors.d/</filename> and + <filename>/usr/lib/dnssec-trust-anchors.d/</filename>. These + directories are searched in the specified order, and a trust + anchor file of the same name in an earlier path overrides a trust + anchor files in a later path. To disable a trust anchor file + shipped in <filename>/usr/lib/dnssec-trust-anchors.d/</filename> + it is sufficient to provide an identically-named file in + <filename>/etc/dnssec-trust-anchors.d/</filename> or + <filename>/run/dnssec-trust-anchors.d/</filename> that is either + empty or a symlink to <filename>/dev/null</filename> ("masked").</para> + + <para>Positive trust anchor files are simple text files resembling + DNS zone files, as documented in <ulink + url="https://tools.ietf.org/html/rfc1035#section-5">RFC 1035, Section + 5</ulink>. One DS or DNSKEY resource record may be listed per + line. Empty lines and lines starting with a semicolon + (<literal>;</literal>) are ignored and considered comments. A DS + resource record is specified like in the following example:</para> + + <programlisting>. IN DS 19036 8 2 49aac11d7b6f6446702e54a1607371607a1a41855200fd2ce1cdde32f24e8fb5</programlisting> + + <para>The first word specifies the domain, use + <literal>.</literal> for the root domain. The domain may be + specified with or without trailing dot, which is considered + equivalent. The second word must be <literal>IN</literal> the + third word <literal>DS</literal>. The following words specify the + key tag, signature algorithm, digest algorithm, followed by the + hex-encoded key fingerprint. See <ulink + url="https://tools.ietf.org/html/rfc4034#section-5">RFC 4034, + Section 5</ulink> for details about the precise syntax and meaning + of these fields.</para> + + <para>Alternatively, DNSKEY resource records may be used to define + trust anchors, like in the following example:</para> + + <programlisting>. IN DNSKEY 257 3 8 AwEAAagAIKlVZrpC6Ia7gEzahOR+9W29euxhJhVVLOyQbSEW0O8gcCjFFVQUTf6v58fLjwBd0YI0EzrAcQqBGCzh/RStIoO8g0NfnfL2MTJRkxoXbfDaUeVPQuYEhg37NZWAJQ9VnMVDxP/VHL496M/QZxkjf5/Efucp2gaDX6RS6CXpoY68LsvPVjR0ZSwzz1apAzvN9dlzEheX7ICJBBtuA6G3LQpzW5hOA2hzCTMjJPJ8LbqF6dsV6DoBQzgul0sGIcGOYl7OyQdXfZ57relSQageu+ipAdTTJ25AsRTAoub8ONGcLmqrAmRLKBP1dfwhYB4N7knNnulqQxA+Uk1ihz0=</programlisting> + + <para>The first word specifies the domain again, the second word + must be <literal>IN</literal>, followed by + <literal>DNSKEY</literal>. The subsequent words encode the DNSKEY + flags, protocol and algorithm fields, followed by the key data + encoded in Base64. See <ulink + url="https://tools.ietf.org/html/rfc4034#section-2">RFC 4034, + Section 2</ulink> for details about the precise syntax and meaning + of these fields.</para> + + <para>If multiple DS or DNSKEY records are defined for the same + domain (possibly even in different trust anchor files), all keys + are used and are considered equivalent as base for DNSSEC + proofs.</para> + + <para>Note that <filename>systemd-resolved</filename> will + automatically use a built-in trust anchor key for the Internet + root domain if no positive trust anchors are defined for the root + domain. In most cases it is hence unnecessary to define an + explicit key with trust anchor files. The built-in key is disabled + as soon as at least one trust anchor key for the root domain is + defined in trust anchor files.</para> + + <para>It is generally recommended to encode trust anchors in DS + resource records, rather than DNSKEY resource records.</para> + + <para>If a trust anchor specified via a DS record is found revoked + it is automatically removed from the trust anchor database for the + runtime. See <ulink url="https://tools.ietf.org/html/rfc5011">RFC + 5011</ulink> for details about revoked trust anchors. Note that + <filename>systemd-resolved</filename> will not update its trust + anchor database from DNS servers automatically. Instead, it is + recommended to update the resolver software or update the new + trust anchor via adding in new trust anchor files.</para> + + <para>The current DNSSEC trust anchor for the Internet's root + domain is available at the <ulink + url="https://data.iana.org/root-anchors/root-anchors.xml">IANA + Trust Anchor and Keys</ulink> page.</para> + </refsect1> + + <refsect1> + <title>Negative Trust Anchors</title> + + <para>Negative trust anchors define domains where DNSSEC validation shall be turned + off. Negative trust anchor files are found at the same location as positive trust anchor files, + and follow the same overriding rules. They are text files with the + <filename>.negative</filename> suffix. Empty lines and lines whose first character is + <literal>;</literal> are ignored. Each line specifies one domain name which is the root of a DNS + subtree where validation shall be disabled.</para> + + <para>Negative trust anchors are useful to support private DNS + subtrees that are not referenced from the Internet DNS hierarchy, + and not signed.</para> + + <para><ulink url="https://tools.ietf.org/html/rfc7646">RFC + 7646</ulink> for details on negative trust anchors.</para> + + <para>If no negative trust anchor files are configured a built-in + set of well-known private DNS zone domains is used as negative + trust anchors.</para> + + <para>It is also possibly to define per-interface negative trust + anchors using the <varname>DNSSECNegativeTrustAnchors=</varname> + setting in + <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> + files.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/file-hierarchy.xml b/man/file-hierarchy.xml index 3a5627d196..538a592f8d 100644 --- a/man/file-hierarchy.xml +++ b/man/file-hierarchy.xml @@ -63,7 +63,7 @@ and restrictions systemd makes on the file system hierarchy.</para> - <para>Many of the paths described here are queriable + <para>Many of the paths described here can be queried with the <citerefentry><refentrytitle>systemd-path</refentrytitle><manvolnum>1</manvolnum></citerefentry> tool.</para> @@ -84,9 +84,9 @@ <varlistentry> <term><filename>/boot</filename></term> <listitem><para>The boot partition used for bringing up the - system. On EFI systems this is possibly the EFI System + system. On EFI systems, this is possibly the EFI System Partition, also see - <citerefentry><refentrytitle>systemd-efi-boot-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>. This directory is usually strictly local to the host, and should be considered read-only, except when a new kernel or boot loader is installed. This directory only exists on @@ -147,14 +147,14 @@ directory is usually mounted as a <literal>tmpfs</literal> instance, and should hence not be used for larger files. (Use <filename>/var/tmp</filename> for larger files.) Since the - directory is accessible to other users of the system it is + directory is accessible to other users of the system, it is essential that this directory is only written to with the <citerefentry project='man-pages'><refentrytitle>mkstemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>mkdtemp</refentrytitle><manvolnum>3</manvolnum></citerefentry> and related calls. This directory is usually flushed at boot-up. Also, files that are not accessed within a certain time are usually automatically deleted. If applications find - the environment variable <varname>$TMPDIR</varname> set they + the environment variable <varname>$TMPDIR</varname> set, they should prefer using the directory specified in it over directly referencing <filename>/tmp</filename> (see <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> @@ -217,7 +217,7 @@ <varlistentry> <term><filename>/usr/bin</filename></term> - <listitem><para>Binaries and executables for user commands, + <listitem><para>Binaries and executables for user commands that shall appear in the <varname>$PATH</varname> search path. It is recommended not to place binaries in this directory that are not useful for invocation from a shell (such as daemon @@ -245,7 +245,7 @@ <varlistentry> <term><filename>/usr/lib/<replaceable>arch-id</replaceable></filename></term> - <listitem><para>Location for placing dynamic libraries, also + <listitem><para>Location for placing dynamic libraries into, also called <varname>$libdir</varname>. The architecture identifier to use is defined on <ulink url="https://wiki.debian.org/Multiarch/Tuples">Multiarch @@ -291,7 +291,7 @@ <term><filename>/usr/share/factory/var</filename></term> <listitem><para>Similar to - <filename>/usr/share/factory/etc</filename> but for vendor + <filename>/usr/share/factory/etc</filename>, but for vendor versions of files in the variable, persistent data directory <filename>/var</filename>.</para></listitem> @@ -353,7 +353,7 @@ <varlistentry> <term><filename>/var/tmp</filename></term> <listitem><para>The place for larger and persistent temporary - files. In contrast to <filename>/tmp</filename> this directory + files. In contrast to <filename>/tmp</filename>, this directory is usually mounted from a persistent physical file system and can thus accept larger files. (Use <filename>/tmp</filename> for smaller files.) This directory is generally not flushed at @@ -365,7 +365,7 @@ <citerefentry project='man-pages'><refentrytitle>mkdtemp</refentrytitle><manvolnum>3</manvolnum></citerefentry> or similar calls should be used to make use of this directory. If applications find the environment variable - <varname>$TMPDIR</varname> set they should prefer using the + <varname>$TMPDIR</varname> set, they should prefer using the directory specified in it over directly referencing <filename>/var/tmp</filename> (see <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> @@ -381,7 +381,7 @@ <variablelist> <varlistentry> <term><filename>/dev</filename></term> - <listitem><para>The root directory for device nodes. Usually + <listitem><para>The root directory for device nodes. Usually, this directory is mounted as a <literal>devtmpfs</literal> instance, but might be of a different type in sandboxed/containerized setups. This directory is managed @@ -402,10 +402,10 @@ write access to this directory, special care should be taken to avoid name clashes and vulnerabilities. For normal users, shared memory segments in this directory are usually deleted - when the user logs out. Usually it is a better idea to use + when the user logs out. Usually, it is a better idea to use memory mapped files in <filename>/run</filename> (for system programs) or <varname>$XDG_RUNTIME_DIR</varname> (for user - programs) instead of POSIX shared memory segments, since those + programs) instead of POSIX shared memory segments, since these directories are not world-writable and hence not vulnerable to security-sensitive name clashes.</para></listitem> </varlistentry> @@ -427,7 +427,7 @@ that exposes a number of kernel tunables. The primary way to configure the settings in this API file tree is via <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> - files. In sandboxed/containerized setups this directory is + files. In sandboxed/containerized setups, this directory is generally mounted read-only.</para></listitem> </varlistentry> @@ -437,7 +437,7 @@ discovered devices and other functionality. This file system is mostly an API to interface with the kernel and not a place where normal files may be stored. In sandboxed/containerized - setups this directory is generally mounted read-only. A number + setups, this directory is generally mounted read-only. A number of special purpose virtual file systems might be mounted below this directory.</para></listitem> </varlistentry> @@ -472,7 +472,7 @@ <varlistentry> <term><filename>/lib64</filename></term> - <listitem><para>On some architecture ABIs this compatibility + <listitem><para>On some architecture ABIs, this compatibility symlink points to <varname>$libdir</varname>, ensuring that binaries referencing this legacy path correctly find their dynamic loader. This symlink only exists on architectures @@ -513,7 +513,7 @@ directory should have no effect on operation of programs, except for increased runtimes necessary to rebuild these caches. If an application finds - <varname>$XDG_CACHE_HOME</varname> set is should use the + <varname>$XDG_CACHE_HOME</varname> set, it should use the directory specified in it instead of this directory.</para></listitem> </varlistentry> @@ -522,10 +522,10 @@ <term><filename>~/.config</filename></term> <listitem><para>Application configuration and state. When a - new user is created this directory will be empty or not exist + new user is created, this directory will be empty or not exist at all. Applications should fall back to defaults should their configuration or state in this directory be missing. If an - application finds <varname>$XDG_CONFIG_HOME</varname> set is + application finds <varname>$XDG_CONFIG_HOME</varname> set, it should use the directory specified in it instead of this directory.</para></listitem> </varlistentry> @@ -539,7 +539,7 @@ invocation from a shell; these should be placed in a subdirectory of <filename>~/.local/lib</filename> instead. Care should be taken when placing architecture-dependent - binaries in this place which might be problematic if the home + binaries in this place, which might be problematic if the home directory is shared between multiple hosts with different architectures.</para></listitem> </varlistentry> @@ -555,7 +555,7 @@ <term><filename>~/.local/lib/<replaceable>arch-id</replaceable></filename></term> <listitem><para>Location for placing public dynamic libraries. - The architecture identifier to use, is defined on <ulink + The architecture identifier to use is defined on <ulink url="https://wiki.debian.org/Multiarch/Tuples">Multiarch Architecture Specifiers (Tuples)</ulink> list.</para></listitem> @@ -568,7 +568,7 @@ such as fonts or artwork. Usually, the precise location and format of files stored below this directory is subject to specifications that ensure interoperability. If an application - finds <varname>$XDG_DATA_HOME</varname> set is should use the + finds <varname>$XDG_DATA_HOME</varname> set, it should use the directory specified in it instead of this directory.</para></listitem> </varlistentry> @@ -593,11 +593,11 @@ <filename>/run/user</filename>) of the user, which are all writable.</para> - <para>For unprivileged system processes only + <para>For unprivileged system processes, only <filename>/tmp</filename>, <filename>/var/tmp</filename> and <filename>/dev/shm</filename> are writable. If an - unprivileged system process needs a private, writable directory in + unprivileged system process needs a private writable directory in <filename>/var</filename> or <filename>/run</filename>, it is recommended to either create it before dropping privileges in the daemon code, to create it via @@ -618,7 +618,7 @@ <para>It is strongly recommended that <filename>/dev</filename> is the only location below which device nodes shall be placed. - Similar, <filename>/run</filename> shall be the only location to + Similarly, <filename>/run</filename> shall be the only location to place sockets and FIFOs. Regular files, directories and symlinks may be used in all directories.</para> </refsect1> @@ -645,7 +645,7 @@ <tbody> <row> <entry><filename>/usr/bin</filename></entry> - <entry>Package executables that shall appear in the <varname>$PATH</varname> executable search path, compiled for any of the supported architectures compatible with the operating system. It is not recommended to place internal binaries or binaries that are not commonly invoked from the shell in this directory, such as daemon binaries. As this directory is shared with most other packages of the system special care should be taken to pick unique names for files placed here, that are unlikely to clash with other package's files.</entry> + <entry>Package executables that shall appear in the <varname>$PATH</varname> executable search path, compiled for any of the supported architectures compatible with the operating system. It is not recommended to place internal binaries or binaries that are not commonly invoked from the shell in this directory, such as daemon binaries. As this directory is shared with most other packages of the system, special care should be taken to pick unique names for files placed here, that are unlikely to clash with other package's files.</entry> </row> <row> <entry><filename>/usr/lib/<replaceable>arch-id</replaceable></filename></entry> @@ -653,7 +653,7 @@ </row> <row> <entry><filename>/usr/lib/<replaceable>package</replaceable></filename></entry> - <entry>Private, static vendor resources of the package, including private binaries and libraries, or any other kind of read-only vendor data.</entry> + <entry>Private static vendor resources of the package, including private binaries and libraries, or any other kind of read-only vendor data.</entry> </row> <row> <entry><filename>/usr/lib/<replaceable>arch-id</replaceable>/<replaceable>package</replaceable></filename></entry> @@ -668,10 +668,10 @@ </table> <para>Additional static vendor files may be installed in the - <filename>/usr/share</filename> hierarchy, to the locations + <filename>/usr/share</filename> hierarchy to the locations defined by the various relevant specifications.</para> - <para>During runtime and for local configuration and state + <para>During runtime, and for local configuration and state, additional directories are defined:</para> <table> @@ -700,7 +700,7 @@ </row> <row> <entry><filename>/var/cache/<replaceable>package</replaceable></filename></entry> - <entry>Persistent cache data of the package. If this directory is flushed the application should work correctly on next invocation, though possibly slowed down due to the need to rebuild any local cache files. The application must be capable of recreating this directory should it be missing and necessary.</entry> + <entry>Persistent cache data of the package. If this directory is flushed, the application should work correctly on next invocation, though possibly slowed down due to the need to rebuild any local cache files. The application must be capable of recreating this directory should it be missing and necessary.</entry> </row> <row> <entry><filename>/var/lib/<replaceable>package</replaceable></filename></entry> @@ -726,7 +726,7 @@ when placing their own files in the user's home directory. The following table lists recommended locations in the home directory for specific types of files supplied by the vendor if the - application is installed in the home directory. (Note however, + application is installed in the home directory. (Note, however, that user applications installed system-wide should follow the rules outlined above regarding placing vendor files.)</para> @@ -744,7 +744,7 @@ <tbody> <row> <entry><filename>~/.local/bin</filename></entry> - <entry>Package executables that shall appear in the <varname>$PATH</varname> executable search path. It is not recommended to place internal executables or executables that are not commonly invoked from the shell in this directory, such as daemon executables. As this directory is shared with most other packages of the user special care should be taken to pick unique names for files placed here, that are unlikely to clash with other package's files.</entry> + <entry>Package executables that shall appear in the <varname>$PATH</varname> executable search path. It is not recommended to place internal executables or executables that are not commonly invoked from the shell in this directory, such as daemon executables. As this directory is shared with most other packages of the user, special care should be taken to pick unique names for files placed here, that are unlikely to clash with other package's files.</entry> </row> <row> <entry><filename>~/.local/lib/<replaceable>arch-id</replaceable></filename></entry> @@ -763,10 +763,10 @@ </table> <para>Additional static vendor files may be installed in the - <filename>~/.local/share</filename> hierarchy, to the locations + <filename>~/.local/share</filename> hierarchy to the locations defined by the various relevant specifications.</para> - <para>During runtime and for local configuration and state + <para>During runtime, and for local configuration and state, additional directories are defined:</para> <table> @@ -791,7 +791,7 @@ </row> <row> <entry><filename>~/.cache/<replaceable>package</replaceable></filename></entry> - <entry>Persistent cache data of the package. If this directory is flushed the application should work correctly on next invocation, though possibly slowed down due to the need to rebuild any local cache files. The application must be capable of recreating this directory should it be missing and necessary.</entry> + <entry>Persistent cache data of the package. If this directory is flushed, the application should work correctly on next invocation, though possibly slowed down due to the need to rebuild any local cache files. The application must be capable of recreating this directory should it be missing and necessary.</entry> </row> </tbody> </tgroup> @@ -804,7 +804,7 @@ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-path</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-efi-boot-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>, diff --git a/man/halt.xml b/man/halt.xml index a06dbd0097..e3fa60a915 100644 --- a/man/halt.xml +++ b/man/halt.xml @@ -133,6 +133,14 @@ </varlistentry> <varlistentry> + <term><option>-n</option></term> + <term><option>--no-sync</option></term> + + <listitem><para>Don't sync hard disks/storage media before + halt, power-off, reboot.</para></listitem> + </varlistentry> + + <varlistentry> <term><option>--no-wall</option></term> <listitem><para>Do not send wall message before halt, diff --git a/man/hostname.xml b/man/hostname.xml index 9688450e1c..8a4c0d5ac0 100644 --- a/man/hostname.xml +++ b/man/hostname.xml @@ -64,10 +64,6 @@ for DNS domain name labels, even though this is not a strict requirement.</para> - <para>Depending on the operating system, other configuration files - might be checked for configuration of the hostname as well, - however only as fallback.</para> - <para>You may use <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> to change the value of this file during runtime from the command diff --git a/man/hostnamectl.xml b/man/hostnamectl.xml index b1f038156d..9e1b593e6d 100644 --- a/man/hostnamectl.xml +++ b/man/hostnamectl.xml @@ -66,15 +66,14 @@ high-level "pretty" hostname which might include all kinds of special characters (e.g. "Lennart's Laptop"), the static hostname which is used to initialize the kernel hostname at boot (e.g. - "lennarts-laptop"), and the transient hostname which is a default - received from network configuration. If a static hostname is set, - and is valid (something other than localhost), then the transient - hostname is not used.</para> + "lennarts-laptop"), and the transient hostname which is a fallback + value received from network configuration. If a static hostname is + set, and is valid (something other than localhost), then the + transient hostname is not used.</para> - <para>Note that the pretty hostname has little restrictions on the - characters used, while the static and transient hostnames are - limited to the usually accepted characters of Internet domain - names.</para> + <para>Note that the pretty hostname has little restrictions on the characters and length used, while the static and + transient hostnames are limited to the usually accepted characters of Internet domain names, and 64 characters at + maximum (the latter being a Linux limitation).</para> <para>The static hostname is stored in <filename>/etc/hostname</filename>, see @@ -107,15 +106,11 @@ <term><option>--transient</option></term> <term><option>--pretty</option></term> - <listitem><para>If <command>status</command> is used (or no - explicit command is given) and one of those fields is given, - <command>hostnamectl</command> will print out just this - selected hostname.</para> + <listitem><para>If <command>status</command> is invoked (or no explicit command is given) and one of these + switches is specified, <command>hostnamectl</command> will print out just this selected hostname.</para> - <para>If used with <command>set-hostname</command>, only the - selected hostname(s) will be updated. When more than one of - those options is used, all the specified hostnames will be - updated. </para></listitem> + <para>If used with <command>set-hostname</command>, only the selected hostname(s) will be updated. When more + than one of these switches are specified, all the specified hostnames will be updated. </para></listitem> </varlistentry> <xi:include href="user-system-options.xml" xpointer="host" /> @@ -139,22 +134,14 @@ <varlistentry> <term><command>set-hostname <replaceable>NAME</replaceable></command></term> - <listitem><para>Set the system hostname to - <replaceable>NAME</replaceable>. By default, this will alter - the pretty, the static, and the transient hostname alike; - however, if one or more of <option>--static</option>, - <option>--transient</option>, <option>--pretty</option> are - used, only the selected hostnames are changed. If the pretty - hostname is being set, and static or transient are being set - as well, the specified hostname will be simplified in regards - to the character set used before the latter are updated. This - is done by replacing spaces with <literal>-</literal> and - removing special characters. This ensures that the pretty and - the static hostname are always closely related while still - following the validity rules of the specific name. This - simplification of the hostname string is not done if only the - transient and/or static host names are set, and the pretty - host name is left untouched.</para> + <listitem><para>Set the system hostname to <replaceable>NAME</replaceable>. By default, this will alter the + pretty, the static, and the transient hostname alike; however, if one or more of <option>--static</option>, + <option>--transient</option>, <option>--pretty</option> are used, only the selected hostnames are changed. If + the pretty hostname is being set, and static or transient are being set as well, the specified hostname will be + simplified in regards to the character set used before the latter are updated. This is done by removing special + characters and spaces. This ensures that the pretty and the static hostname are always closely related while + still following the validity rules of the specific name. This simplification of the hostname string is not done + if only the transient and/or static host names are set, and the pretty host name is left untouched.</para> <para>Pass the empty string <literal></literal> as the hostname to reset the selected hostnames to their default diff --git a/man/hwdb.xml b/man/hwdb.xml index 80939dd95d..2b1e60fb22 100644 --- a/man/hwdb.xml +++ b/man/hwdb.xml @@ -34,7 +34,7 @@ <refsect1><title>Description</title> <para>The hardware database is a key-value store for associating modalias-like keys to - udev-properties-like values. It is used primarily by udev to add the relevant properties + udev-property-like values. It is used primarily by udev to add the relevant properties to matching devices, but it can also be queried directly.</para> </refsect1> @@ -55,9 +55,9 @@ <para>The hwdb file contains data records consisting of matches and associated key-value pairs. Every record in the hwdb starts with one or - more match string, specifying a shell glob to compare the database + more match strings, specifying a shell glob to compare the database lookup string against. Multiple match lines are specified in additional - consecutive lines. Every match line is compared individually, they are + consecutive lines. Every match line is compared individually, and they are combined by OR. Every match line must start at the first character of the line.</para> @@ -71,7 +71,7 @@ and compiled to a binary database located at <filename>/etc/udev/hwdb.bin</filename>, or alternatively <filename>/usr/lib/udev/hwdb.bin</filename> if you want ship the compiled database in an immutable image. - During runtime only the binary database is used.</para> + During runtime, only the binary database is used.</para> </refsect1> <refsect1> diff --git a/man/journal-remote.conf.xml b/man/journal-remote.conf.xml index fc60258d0b..2d345963d9 100644 --- a/man/journal-remote.conf.xml +++ b/man/journal-remote.conf.xml @@ -72,6 +72,13 @@ <literal>[Remote]</literal> section:</para> <variablelist> + <varlistentry> + <term><varname>Seal=</varname></term> + + <listitem><para>Periodically sign the data in the journal using Forward Secure Sealing. + </para></listitem> + </varlistentry> + <varlistentry> <term><varname>SplitMode=</varname></term> @@ -105,7 +112,7 @@ <refsect1> <title>See Also</title> <para> - <citerefentry><refentrytitle>systemd-journal-remote</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-journal-remote</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> </para> diff --git a/man/journalctl.xml b/man/journalctl.xml index ca933645a9..63b4a267b8 100644 --- a/man/journalctl.xml +++ b/man/journalctl.xml @@ -82,20 +82,34 @@ matches apply to the same field, then they are automatically matched as alternatives, i.e. the resulting output will show entries matching any of the specified matches for the same - field. Finally, the character <literal>+</literal> may appears + field. Finally, the character <literal>+</literal> may appear as a separate word between other terms on the command line. This causes all matches before and after to be combined in a disjunction (i.e. logical OR).</para> - <para>As shortcuts for a few types of field/value matches, file - paths may be specified. If a file path refers to an executable - file, this is equivalent to an <literal>_EXE=</literal> match - for the canonicalized binary path. Similarly, if a path refers - to a device node, this is equivalent to a - <literal>_KERNEL_DEVICE=</literal> match for the device.</para> + <para>It is also possible to filter the entries by specifying an + absolute file path as an argument. The file path may be a file or + a symbolic link and the file must exist at the time of the query. If a + file path refers to an executable binary, an <literal>_EXE=</literal> + match for the canonicalized binary path is added to the query. If a + file path refers to an executable script, a <literal>_COMM=</literal> + match for the script name is added to the query. If a file path + refers to a device node, <literal>_KERNEL_DEVICE=</literal> matches for + the kernel name of the device and for each of its ancestor devices is + added to the query. Symbolic links are dereferenced, kernel names are + synthesized, and parent devices are identified from the environment at + the time of the query. In general, a device node is the best proxy for + an actual device, as log entries do not usually contain fields that + identify an actual device. For the resulting log entries to be correct + for the actual device, the relevant parts of the environment at the time + the entry was logged, in particular the actual device corresponding to + the device node, must have been the same as those at the time of the + query. Because device nodes generally change their corresponding devices + across reboots, specifying a device node path causes the resulting + entries to be restricted to those from the current boot.</para> <para>Additional constraints may be added using options - <option>--boot</option>, <option>--unit=</option>, etc, to + <option>--boot</option>, <option>--unit=</option>, etc., to further limit what entries will be shown (logical AND).</para> <para>Output is interleaved from all accessible journal files, @@ -181,7 +195,7 @@ <option>-n1000</option> to guarantee that the pager will not buffer logs of unbounded size. This may be overridden with an explicit <option>-n</option> with some other numeric - value while <option>-nall</option> will disable this cap. + value, while <option>-nall</option> will disable this cap. Note that this option is only supported for the <citerefentry project='man-pages'><refentrytitle>less</refentrytitle><manvolnum>1</manvolnum></citerefentry> pager.</para></listitem> @@ -236,6 +250,18 @@ <varlistentry> <term> + <option>short-full</option> + </term> + <listitem> + <para>is very similar, but shows timestamps in the format the <option>--since=</option> and + <option>--until=</option> options accept. Unlike the timestamp information shown in + <option>short</option> output mode this mode includes weekday, year and timezone information in the + output, and is locale-independent.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> <option>short-iso</option> </term> <listitem> @@ -266,6 +292,16 @@ <varlistentry> <term> + <option>short-unix</option> + </term> + <listitem> + <para>is very similar, but shows seconds passed since January 1st 1970 UTC instead of wallclock + timestamps ("UNIX time"). The time is shown with microsecond accuracy.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> <option>verbose</option> </term> <listitem> @@ -344,6 +380,13 @@ </varlistentry> <varlistentry> + <term><option>--no-hostname</option></term> + + <listitem><para>Don't show the hostname field of log messages originating from the local host. This switch only + has an effect on the <option>short</option> family of output modes (see above).</para></listitem> + </varlistentry> + + <varlistentry> <term><option>-x</option></term> <term><option>--catalog</option></term> @@ -368,7 +411,9 @@ <term><option>-q</option></term> <term><option>--quiet</option></term> - <listitem><para>Suppresses any warning messages regarding + <listitem><para>Suppresses all info messages + (i.e. "-- Logs begin at ...", "-- Reboot --"), + any warning messages regarding inaccessible system journals when run as a normal user.</para></listitem> </varlistentry> @@ -393,7 +438,7 @@ <para>If the boot ID is omitted, a positive <replaceable>offset</replaceable> will look up the boots - starting from the beginning of the journal, and a + starting from the beginning of the journal, and an equal-or-less-than zero <replaceable>offset</replaceable> will look up boots starting from the end of the journal. Thus, <constant>1</constant> means the first boot found in the @@ -411,7 +456,7 @@ <replaceable>offset</replaceable> which identifies the boot relative to the one given by boot <replaceable>ID</replaceable>. Negative values mean earlier - boots and a positive values mean later boots. If + boots and positive values mean later boots. If <replaceable>offset</replaceable> is not specified, a value of zero is assumed, and the logs for the boot given by <replaceable>ID</replaceable> are shown.</para> @@ -437,13 +482,11 @@ <varlistentry> <term><option>-t</option></term> - <term><option>--identifier=<replaceable>SYSLOG_IDENTIFIER</replaceable>|<replaceable>PATTERN</replaceable></option></term> + <term><option>--identifier=<replaceable>SYSLOG_IDENTIFIER</replaceable></option></term> <listitem><para>Show messages for the specified syslog - identifier <replaceable>SYSLOG_IDENTIFIER</replaceable>, or - for any of the messages with a - <literal>SYSLOG_IDENTIFIER</literal> matched by - <replaceable>PATTERN</replaceable>.</para> + identifier + <replaceable>SYSLOG_IDENTIFIER</replaceable>.</para> <para>This parameter can be specified multiple times.</para></listitem> @@ -520,7 +563,7 @@ <listitem><para>Start showing entries from the location in the journal <emphasis>after</emphasis> the location specified by - the this cursor. The cursor is shown when the + the passed cursor. The cursor is shown when the <option>--show-cursor</option> option is used.</para> </listitem> </varlistentry> @@ -536,25 +579,23 @@ </varlistentry> <varlistentry> + <term><option>-S</option></term> <term><option>--since=</option></term> + <term><option>-U</option></term> <term><option>--until=</option></term> - <listitem><para>Start showing entries on or newer than the - specified date, or on or older than the specified date, - respectively. Date specifications should be of the format - <literal>2012-10-30 18:17:16</literal>. If the time part is - omitted, <literal>00:00:00</literal> is assumed. If only the - seconds component is omitted, <literal>:00</literal> is - assumed. If the date component is omitted, the current day is - assumed. Alternatively the strings - <literal>yesterday</literal>, <literal>today</literal>, - <literal>tomorrow</literal> are understood, which refer to - 00:00:00 of the day before the current day, the current day, - or the day after the current day, - respectively. <literal>now</literal> refers to the current - time. Finally, relative times may be specified, prefixed with - <literal>-</literal> or <literal>+</literal>, referring to - times before or after the current time, respectively.</para> + <listitem><para>Start showing entries on or newer than the specified date, or on or older than the specified + date, respectively. Date specifications should be of the format <literal>2012-10-30 18:17:16</literal>. If the + time part is omitted, <literal>00:00:00</literal> is assumed. If only the seconds component is omitted, + <literal>:00</literal> is assumed. If the date component is omitted, the current day is assumed. Alternatively + the strings <literal>yesterday</literal>, <literal>today</literal>, <literal>tomorrow</literal> are understood, + which refer to 00:00:00 of the day before the current day, the current day, or the day after the current day, + respectively. <literal>now</literal> refers to the current time. Finally, relative times may be specified, + prefixed with <literal>-</literal> or <literal>+</literal>, referring to times before or after the current + time, respectively. For complete time and date specification, see + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>. Note that + <option>--output=short-full</option> prints timestamps that follow precisely this format. + </para> </listitem> </varlistentry> @@ -567,6 +608,13 @@ </varlistentry> <varlistentry> + <term><option>-N</option></term> + <term><option>--fields</option></term> + + <listitem><para>Print all field names currently used in all entries of the journal.</para></listitem> + </varlistentry> + + <varlistentry> <term><option>--system</option></term> <term><option>--user</option></term> @@ -611,10 +659,12 @@ <term><option>--root=<replaceable>ROOT</replaceable></option></term> <listitem><para>Takes a directory path as an argument. If - specified, journalctl will operate on catalog file hierarchy + specified, journalctl will operate on journal directories and catalog file hierarchy underneath the specified directory instead of the root directory (e.g. <option>--update-catalog</option> will create - <filename><replaceable>ROOT</replaceable>/var/lib/systemd/catalog/database</filename>). + <filename><replaceable>ROOT</replaceable>/var/lib/systemd/catalog/database</filename>, + and journal files under <filename><replaceable>ROOT</replaceable>/run/journal</filename> + or <filename><replaceable>ROOT</replaceable>/var/log/journal</filename> will be displayed). </para></listitem> </varlistentry> @@ -649,24 +699,34 @@ <varlistentry> <term><option>--vacuum-size=</option></term> <term><option>--vacuum-time=</option></term> + <term><option>--vacuum-files=</option></term> <listitem><para>Removes 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>, <literal>T</literal> suffixes), or all - journal files contain no data older than the specified + <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>min</literal>, <literal>h</literal>, + <literal>m</literal>, <literal>h</literal>, <literal>days</literal>, <literal>months</literal>, - <literal>weeks</literal>, <literal>years</literal> - suffixes). Note that running <option>--vacuum-size=</option> - has only indirect effect on the output shown by - <option>--disk-usage</option> as the latter includes active - journal files, while the former only operates on archived - journal files. <option>--vacuum-size=</option> and - <option>--vacuum-time=</option> may be combined in a single - invocation to enforce both a size and time limit on the - archived journal files.</para></listitem> + <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> </varlistentry> <varlistentry> @@ -758,13 +818,39 @@ </varlistentry> <varlistentry> + <term><option>--sync</option></term> + + <listitem><para>Asks the journal daemon to write all yet + unwritten journal data to the backing file system and + synchronize all journals. This call does not return until the + synchronization operation is complete. This command guarantees + that any log messages written before its invocation are safely + stored on disk at the time it returns.</para></listitem> + </varlistentry> + + <varlistentry> <term><option>--flush</option></term> - <listitem><para>Asks the Journal daemon to flush any log data + <listitem><para>Asks the journal daemon to flush any log data stored in <filename>/run/log/journal</filename> into - <filename>/var/log/journal</filename>, if persistent storage is - enabled. This call does not return until the operation is - complete.</para></listitem> + <filename>/var/log/journal</filename>, if persistent storage + is enabled. This call does not return until the operation is + complete. Note that this call is idempotent: the data is only + flushed from <filename>/run/log/journal</filename> into + <filename>/var/log/journal</filename> once during system + runtime, and this command exits cleanly without executing any + operation if this has already happened. This command + effectively guarantees that all data is flushed to + <filename>/var/log/journal</filename> at the time it + returns.</para></listitem> + </varlistentry> + + <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> </varlistentry> <xi:include href="standard-options.xml" xpointer="help" /> @@ -836,7 +922,8 @@ <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> </para> </refsect1> </refentry> diff --git a/man/journald.conf.xml b/man/journald.conf.xml index d6fe45d40c..a9562c121a 100644 --- a/man/journald.conf.xml +++ b/man/journald.conf.xml @@ -129,31 +129,24 @@ <varlistentry> <term><varname>SplitMode=</varname></term> - <listitem><para>Controls whether to split up journal files per - user. One of <literal>uid</literal>, <literal>login</literal> - and <literal>none</literal>. If <literal>uid</literal>, all - users will get each their own journal files regardless of - whether they possess a login session or not, however system - users will log into the system journal. If - <literal>login</literal>, actually logged-in users will get - each their own journal files, but users without login session - and system users will log into the system journal. If - <literal>none</literal>, journal files are not split up by - user and all messages are instead stored in the single system - journal. Note that splitting up journal files by user is only - available for journals stored persistently. If journals are - stored on volatile storage (see above), only a single journal - file for all user IDs is kept. Defaults to - <literal>uid</literal>.</para></listitem> + <listitem><para>Controls whether to split up journal files per user, either <literal>uid</literal> or + <literal>none</literal>. Split journal files are primarily useful for access control: on UNIX/Linux access + control is managed per file, and the journal daemon will assign users read access to their journal files. If + <literal>uid</literal>, all regular users will each get their own journal files, and system users will log to + the system journal. If <literal>none</literal>, journal files are not split up by user and all messages are + instead stored in the single system journal. In this mode unprivileged users generally do not have access to + their own log data. Note that splitting up journal files by user is only available for journals stored + persistently. If journals are stored on volatile storage (see <varname>Storage=</varname> above), only a single + journal file is used. Defaults to <literal>uid</literal>.</para></listitem> </varlistentry> <varlistentry> - <term><varname>RateLimitInterval=</varname></term> + <term><varname>RateLimitIntervalSec=</varname></term> <term><varname>RateLimitBurst=</varname></term> <listitem><para>Configures the rate limiting that is applied to all messages generated on the system. If, in the time - interval defined by <varname>RateLimitInterval=</varname>, + interval defined by <varname>RateLimitIntervalSec=</varname>, more messages than specified in <varname>RateLimitBurst=</varname> are logged by a service, all further messages within the interval are dropped until the @@ -162,7 +155,7 @@ per-service, so that two services which log do not interfere with each other's limits. Defaults to 1000 messages in 30s. The time specification for - <varname>RateLimitInterval=</varname> may be specified in the + <varname>RateLimitIntervalSec=</varname> may be specified in the 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, @@ -173,9 +166,11 @@ <term><varname>SystemMaxUse=</varname></term> <term><varname>SystemKeepFree=</varname></term> <term><varname>SystemMaxFileSize=</varname></term> + <term><varname>SystemMaxFiles=</varname></term> <term><varname>RuntimeMaxUse=</varname></term> <term><varname>RuntimeKeepFree=</varname></term> <term><varname>RuntimeMaxFileSize=</varname></term> + <term><varname>RuntimeMaxFiles=</varname></term> <listitem><para>Enforce size limits on the journal files stored. The options prefixed with <literal>System</literal> @@ -197,12 +192,11 @@ names not ending with <literal>.journal</literal> or <literal>.journal~</literal>, so only such files, located in the appropriate directories, are taken into account when - calculating current disk usage. - </para> + calculating current disk usage.</para> <para><varname>SystemMaxUse=</varname> and <varname>RuntimeMaxUse=</varname> control how much disk space - the journal may use up at maximum. + the journal may use up at most. <varname>SystemKeepFree=</varname> and <varname>RuntimeKeepFree=</varname> control how much disk space systemd-journald shall leave free for other uses. @@ -210,31 +204,42 @@ and use the smaller of the two values.</para> <para>The first pair defaults to 10% and the second to 15% of - the size of the respective file system. If the file system is - nearly full and either <varname>SystemKeepFree=</varname> or - <varname>RuntimeKeepFree=</varname> is violated when - systemd-journald is started, the value will be raised to + the size of the respective file system, but each value is + capped to 4G. If the file system is nearly full and either + <varname>SystemKeepFree=</varname> or + <varname>RuntimeKeepFree=</varname> are violated when + systemd-journald is started, the limit will be raised to the percentage that is actually free. This means that if there was enough free space before and journal files were created, and 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 go reduce footprint either.</para> + removing existing files to reduce the footprint again, + either.</para> <para><varname>SystemMaxFileSize=</varname> and <varname>RuntimeMaxFileSize=</varname> control how large - individual journal files may grow at maximum. This influences + individual journal files may grow at most. This influences the granularity in which disk space is made available through rotation, i.e. deletion of historic data. Defaults to one eighth of the values configured with <varname>SystemMaxUse=</varname> and <varname>RuntimeMaxUse=</varname>, so that usually seven - rotated journal files are kept as history.</para></listitem> + rotated journal files are kept as history.</para> <para>Specify values in bytes or use K, M, G, T, P, E as - units for the specified sizes (equal to 1024, 1024²,... bytes). + units for the specified sizes (equal to 1024, 1024², ... bytes). Note that size limits are enforced synchronously when journal files are extended, and no explicit rotation step triggered by time is needed.</para> + + <para><varname>SystemMaxFiles=</varname> and + <varname>RuntimeMaxFiles=</varname> control how many + individual journal files to keep at most. Note that only + archived files are deleted to reduce the number of files until + this limit is reached; active files will stay around. This + means that, in effect, there might still be more journal files + around in total than this limit after a vacuuming operation is + complete. This setting defaults to 100.</para></listitem> </varlistentry> <varlistentry> @@ -333,7 +338,7 @@ <literal>notice</literal>, <literal>info</literal>, <literal>debug</literal>, - or integer values in the range of 0..7 (corresponding to the + or integer values in the range of 0–7 (corresponding to the same levels). Messages equal or below the log level specified are stored/forwarded, messages above are dropped. Defaults to <literal>debug</literal> for <varname>MaxLevelStore=</varname> @@ -363,15 +368,15 @@ <para> Journal events can be transferred to a different logging daemon - in two different ways. In the first method, messages are + in two different ways. With the first method, messages are immediately forwarded to a socket (<filename>/run/systemd/journal/syslog</filename>), where the traditional syslog daemon can read them. This method is - controlled by <varname>ForwardToSyslog=</varname> option. In a + controlled by the <varname>ForwardToSyslog=</varname> option. With a second method, a syslog daemon behaves like a normal journal client, and reads messages from the journal files, similarly to <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. - In this method, messages do not have to be read immediately, + With this, messages do not have to be read immediately, which allows a logging daemon which is only started late in boot to access all messages since the start of the system. In addition, full structured meta-data is available to it. This diff --git a/man/kernel-command-line.xml b/man/kernel-command-line.xml index eb73727027..1fa31a14b7 100644 --- a/man/kernel-command-line.xml +++ b/man/kernel-command-line.xml @@ -66,7 +66,7 @@ <para>For command line parameters understood by the initial RAM disk, please see - <citerefentry project='die-net'><refentrytitle>dracut.cmdline</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>dracut.cmdline</refentrytitle><manvolnum>7</manvolnum></citerefentry>, or the documentation of the specific initrd implementation of your installation.</para> </refsect1> @@ -79,8 +79,9 @@ <term><varname>systemd.unit=</varname></term> <term><varname>rd.systemd.unit=</varname></term> <term><varname>systemd.dump_core=</varname></term> - <term><varname>systemd.crash_shell=</varname></term> <term><varname>systemd.crash_chvt=</varname></term> + <term><varname>systemd.crash_shell=</varname></term> + <term><varname>systemd.crash_reboot=</varname></term> <term><varname>systemd.confirm_spawn=</varname></term> <term><varname>systemd.show_status=</varname></term> <term><varname>systemd.log_target=</varname></term> @@ -90,6 +91,7 @@ <term><varname>systemd.default_standard_output=</varname></term> <term><varname>systemd.default_standard_error=</varname></term> <term><varname>systemd.setenv=</varname></term> + <term><varname>systemd.machine_id=</varname></term> <listitem> <para>Parameters understood by the system and service manager to control system behavior. For details, see @@ -117,7 +119,7 @@ from the previous boot. For details, see <citerefentry><refentrytitle>systemd-backlight@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> and - <citerefentry><refentrytitle>systemd-rfkill@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + <citerefentry><refentrytitle>systemd-rfkill.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. </para> </listitem> </varlistentry> @@ -144,7 +146,9 @@ <varlistentry> <term><varname>-b</varname></term> + <term><varname>rd.emergency</varname></term> <term><varname>emergency</varname></term> + <term><varname>rd.rescue</varname></term> <term><varname>rescue</varname></term> <term><varname>single</varname></term> <term><varname>s</varname></term> @@ -156,7 +160,7 @@ <term><varname>5</varname></term> <listitem> <para>Parameters understood by the system and service - manager, as compatibility options. For details, see + manager, as compatibility and convenience options. For details, see <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> </listitem> </varlistentry> @@ -220,15 +224,14 @@ <varlistentry> <term><varname>vconsole.keymap=</varname></term> - <term><varname>vconsole.keymap.toggle=</varname></term> + <term><varname>vconsole.keymap_toggle=</varname></term> <term><varname>vconsole.font=</varname></term> - <term><varname>vconsole.font.map=</varname></term> - <term><varname>vconsole.font.unimap=</varname></term> + <term><varname>vconsole.font_map=</varname></term> + <term><varname>vconsole.font_unimap=</varname></term> <listitem> - <para>Parameters understood by the virtual console setup - logic. For details, see - <citerefentry><refentrytitle>systemd-vconsole-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + <para>Parameters understood by the virtual console setup logic. For details, see + <citerefentry><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> </listitem> </varlistentry> @@ -320,6 +323,15 @@ </varlistentry> <varlistentry> + <term><varname>systemd.default_timeout_start_sec=</varname></term> + + <listitem> + <para>Overwrites the default start job timeout <varname>DefaultTimeoutStartSec=</varname> at boot. For details, + see <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> <term><varname>modules-load=</varname></term> <term><varname>rd.modules-load=</varname></term> @@ -350,7 +362,7 @@ <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>bootparam</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>dracut.cmdline</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>dracut.cmdline</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-debug-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-fsck@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-quotacheck.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, @@ -363,7 +375,7 @@ <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-modules-load.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-backlight@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-rfkill@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-rfkill.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-hibernate-resume-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/kernel-install.xml b/man/kernel-install.xml index d7e27de758..4a8a46cef4 100644 --- a/man/kernel-install.xml +++ b/man/kernel-install.xml @@ -72,9 +72,12 @@ in <filename>/usr/lib/kernel/install.d/</filename>. This can be used to override a system-supplied executables with a local file if needed; a symbolic link in <filename>/etc/kernel/install.d/</filename> with the same name as an executable in <filename>/usr/lib/kernel/install.d/</filename>, - pointing to /dev/null, disables the executable entirely. Executables must have the + pointing to <filename>/dev/null</filename>, disables the executable entirely. Executables must have the extension <literal>.install</literal>; other extensions are ignored.</para> + <para>An executable should return <constant>0</constant> on success. It may also + return <constant>77</constant> to cause the whole operation to terminate + (executables later in lexical order will be skipped).</para> </refsect1> <refsect1> diff --git a/man/less-variables.xml b/man/less-variables.xml index 0fb4d7fbcf..1f34cbc1bf 100644 --- a/man/less-variables.xml +++ b/man/less-variables.xml @@ -3,27 +3,34 @@ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> <refsect1> - <title>Environment</title> - - <variablelist class='environment-variables'> - <varlistentry id='pager'> - <term><varname>$SYSTEMD_PAGER</varname></term> - - <listitem><para>Pager to use when - <option>--no-pager</option> is not given; - overrides <varname>$PAGER</varname>. Setting - this to an empty string or the value - <literal>cat</literal> is equivalent to passing - <option>--no-pager</option>.</para></listitem> - </varlistentry> - - <varlistentry id='less'> - <term><varname>$SYSTEMD_LESS</varname></term> - - <listitem><para>Override the default - options passed to - <command>less</command> - (<literal>FRSXMK</literal>).</para></listitem> - </varlistentry> - </variablelist> + <title>Environment</title> + + <variablelist class='environment-variables'> + <varlistentry id='pager'> + <term><varname>$SYSTEMD_PAGER</varname></term> + + <listitem><para>Pager to use when <option>--no-pager</option> is not given; overrides + <varname>$PAGER</varname>. If neither <varname>$SYSTEMD_PAGER</varname> nor <varname>$PAGER</varname> are set, a + set of well-known pager implementations are tried in turn, including + <citerefentry><refentrytitle>less</refentrytitle><manvolnum>1</manvolnum></citerefentry> and + <citerefentry><refentrytitle>more</refentrytitle><manvolnum>1</manvolnum></citerefentry>, until one is found. If + no pager implementation is discovered no pager is invoked. Setting this environment variable to an empty string + or the value <literal>cat</literal> is equivalent to passing <option>--no-pager</option>.</para></listitem> + </varlistentry> + + <varlistentry id='less'> + <term><varname>$SYSTEMD_LESS</varname></term> + + <listitem><para>Override the options passed to <command>less</command> (by default + <literal>FRSXMK</literal>).</para></listitem> + </varlistentry> + + <varlistentry id='lesscharset'> + <term><varname>$SYSTEMD_LESSCHARSET</varname></term> + + <listitem><para>Override the charset passed to <command>less</command> (by default <literal>utf-8</literal>, if + the invoking terminal is determined to be UTF-8 compatible).</para></listitem> + </varlistentry> + + </variablelist> </refsect1> diff --git a/man/libudev.xml b/man/libudev.xml index 5660b9d990..53b68dcc89 100644 --- a/man/libudev.xml +++ b/man/libudev.xml @@ -75,13 +75,13 @@ 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 of providing suitable locking if they intend to use + is responsible for providing suitable locking if they intend to use it from multiple threads.</para> <para>To introspect a local device on a system, a udev device object can be created via <citerefentry><refentrytitle>udev_device_new_from_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry> - and friends. The device object allows to query current state, + and friends. The device object allows one to query current state, read and write attributes and lookup properties of the device in question.</para> @@ -99,11 +99,11 @@ <para>Furthermore, libudev also exports legacy APIs that should not be used by new software (and as such are not documented as - part of this manual). This includes the hardware-database known + part of this manual). This includes the hardware database known as <constant>udev_hwdb</constant> (please use the new <citerefentry><refentrytitle>sd-hwdb</refentrytitle><manvolnum>3</manvolnum></citerefentry> API instead) and the <constant>udev_queue</constant> object to - query the udev-daemon (which should not be used by new software + query the udev daemon (which should not be used by new software at all).</para> </refsect1> diff --git a/man/locale.conf.xml b/man/locale.conf.xml index 2c32d16094..2fe731113a 100644 --- a/man/locale.conf.xml +++ b/man/locale.conf.xml @@ -54,7 +54,7 @@ <title>Description</title> <para>The <filename>/etc/locale.conf</filename> file configures - system-wide locale settings. It is read at early-boot by + system-wide locale settings. It is read at early boot by <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> <para>The basic file format of <filename>locale.conf</filename> is diff --git a/man/localectl.xml b/man/localectl.xml index 7def047f62..31238272f3 100644 --- a/man/localectl.xml +++ b/man/localectl.xml @@ -60,7 +60,10 @@ <title>Description</title> <para><command>localectl</command> may be used to query and change - the system locale and keyboard layout settings.</para> + the system locale and keyboard layout settings. It communicates with + <citerefentry><refentrytitle>systemd-localed</refentrytitle><manvolnum>8</manvolnum></citerefentry> + to modify files such as <filename>/etc/locale.conf</filename> and + <filename>/etc/vconsole.conf</filename>.</para> <para>The system locale controls the language settings of system services and of the UI before the user logs in, such as the @@ -72,9 +75,14 @@ such as the display manager, as well as the default for users after login.</para> - <para>Use + <para>Note that the changes performed using this tool might require + the initramfs to be rebuilt to take effect during early system boot. + The initramfs is not rebuilt automatically by <filename>localectl</filename>. + </para> + + <para>Note that <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - to initialize the system locale for mounted (but not booted) + may be used to initialize the system locale for mounted (but not booted) system images.</para> </refsect1> @@ -214,7 +222,8 @@ </ulink>, <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-localed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>mkinitrd</refentrytitle><manvolnum>8</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/loginctl.xml b/man/loginctl.xml index 9dda14d454..fb51740503 100644 --- a/man/loginctl.xml +++ b/man/loginctl.xml @@ -94,6 +94,16 @@ </varlistentry> <varlistentry> + <term><option>--value</option></term> + + <listitem> + <para>When printing properties with <command>show</command>, + only print the value, and skip the property name and + <literal>=</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> <term><option>-a</option></term> <term><option>--all</option></term> @@ -186,7 +196,7 @@ <listitem><para>Show terse runtime status information about one or more sessions, followed by the most recent log data from the journal. Takes one or more session identifiers as - parameters. If no session identifiers are passed the status of + parameters. If no session identifiers are passed, the status of the caller's session is shown. This function is intended to generate human-readable output. If you are looking for computer-parsable output, use <command>show-session</command> @@ -212,9 +222,9 @@ <term><command>activate</command> <optional><replaceable>ID</replaceable></optional></term> <listitem><para>Activate a session. This brings a session into - the foreground, if another session is currently in the + the foreground if another session is currently in the foreground on the respective seat. Takes a session identifier - as argument. If no argument is specified the session of the + as argument. If no argument is specified, the session of the caller is put into foreground.</para></listitem> </varlistentry> @@ -225,7 +235,7 @@ <listitem><para>Activates/deactivates the screen lock on one or more sessions, if the session supports it. Takes one or more session identifiers as arguments. If no argument is - specified the session of the caller is locked/unlocked. + specified, the session of the caller is locked/unlocked. </para></listitem> </varlistentry> @@ -269,7 +279,7 @@ <listitem><para>Show terse runtime status information about one or more logged in users, followed by the most recent log data from the journal. Takes one or more user names or numeric - user IDs as parameters. If no parameters are passed the status + user IDs as parameters. If no parameters are passed, the status of the caller's user is shown. This function is intended to generate human-readable output. If you are looking for computer-parsable output, use <command>show-user</command> @@ -301,8 +311,11 @@ spawned for the user at boot and kept around after logouts. This allows users who are not logged in to run long-running services. Takes one or more user names or numeric UIDs as - argument. If no argument is specified enables/disables - lingering for the user of the session of the caller. + argument. If no argument is specified, enables/disables + lingering for the user of the session of the caller.</para> + + <para>See also <varname>KillUserProcesses=</varname> setting in + <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. </para></listitem> </varlistentry> @@ -365,7 +378,7 @@ seat. The devices should be specified via device paths in the <filename>/sys</filename> file system. To create a new seat, attach at least one graphics card to a previously unused seat - name. Seat names may consist only of a-z, A-Z, 0-9, + name. Seat names may consist only of a–z, A–Z, 0–9, <literal>-</literal> and <literal>_</literal> and must be prefixed with <literal>seat</literal>. To drop assignment of a device to a specific seat, just reassign it to a different @@ -400,6 +413,37 @@ otherwise.</para> </refsect1> + <refsect1> + <title>Examples</title> + + <example> + <title>Querying user status</title> + + <programlisting>$ loginctl user-status +fatima (1005) + Since: Sat 2016-04-09 14:23:31 EDT; 54min ago + State: active + Sessions: 5 *3 + Unit: user-1005.slice + ├─user@1005.service + ... + ├─session-3.scope + ... + └─session-5.scope + ├─3473 login -- fatima + └─3515 -zsh + +Apr 09 14:40:30 laptop login[2325]: pam_unix(login:session): + session opened for user fatima by LOGIN(uid=0) +Apr 09 14:40:30 laptop login[2325]: LOGIN ON tty3 BY fatima +</programlisting> + + <para>There are two sessions, 3 and 5. Session 3 is a graphical session, + marked with a star. The tree of processing including the two corresponding + scope units and the user manager unit are shown.</para> + </example> + </refsect1> + <xi:include href="less-variables.xml" /> <refsect1> diff --git a/man/logind.conf.xml b/man/logind.conf.xml index 2b79547275..994e0e1140 100644 --- a/man/logind.conf.xml +++ b/man/logind.conf.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -119,30 +119,46 @@ <varlistentry> <term><varname>KillUserProcesses=</varname></term> - <listitem><para>Takes a boolean argument. Configures whether - the processes of a user should be killed when the user - completely logs out (i.e. after the user's last session - ended). Defaults to <literal>no</literal>.</para> - - <para>Note that setting <varname>KillUserProcesses=1</varname> + <listitem><para>Takes a boolean argument. Configures whether the processes of a + user should be killed when the user logs out. If true, the scope unit + corresponding to the session and all processes inside that scope will be + terminated. If false, the scope is "abandoned", see + <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + and processes are not killed. Defaults to <literal>yes</literal>, + but see the options <varname>KillOnlyUsers=</varname> and + <varname>KillExcludeUsers=</varname> below.</para> + + <para>In addition to session processes, user process may run under the user + manager unit <filename>user@.service</filename>. Depending on the linger + settings, this may allow users to run processes independent of their login + sessions. See the description of <command>enable-linger</command> in + <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + </para> + + <para>Note that setting <varname>KillUserProcesses=yes</varname> will break tools like - <citerefentry project='die-net'><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem> + <citerefentry project='die-net'><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry> + and + <citerefentry project='die-net'><refentrytitle>tmux</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + unless they are moved out of the session scope. See example in + <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + </para></listitem> </varlistentry> <varlistentry> <term><varname>KillOnlyUsers=</varname></term> <term><varname>KillExcludeUsers=</varname></term> - <listitem><para>These settings take space-separated lists of - usernames that influence the effect of - <varname>KillUserProcesses=</varname>. If not empty, only - processes of users listed in <varname>KillOnlyUsers=</varname> - will be killed when they log out entirely. Processes of users - listed in <varname>KillExcludeUsers=</varname> are excluded - from being killed. <varname>KillExcludeUsers=</varname> - defaults to <literal>root</literal> and takes precedence over - <varname>KillOnlyUsers=</varname>, which defaults to the empty - list.</para></listitem> + <listitem><para>These settings take space-separated lists of usernames that override + the <varname>KillUserProcesses=</varname> setting. A user name may be added to + <varname>KillExcludeUsers=</varname> to exclude the processes in the session scopes of + that user from being killed even if <varname>KillUserProcesses=yes</varname> is set. If + <varname>KillExcludeUsers=</varname> is not set, the <literal>root</literal> user is + excluded by default. <varname>KillExcludeUsers=</varname> may be set to an empty value + to override this default. If a user is not excluded, <varname>KillOnlyUsers=</varname> + is checked next. If this setting is specified, only the session scopes of those users + will be killed. Otherwise, users are subject to the + <varname>KillUserProcesses=yes</varname> setting.</para></listitem> </varlistentry> <varlistentry> @@ -195,7 +211,7 @@ <term><varname>HandleLidSwitch=</varname></term> <term><varname>HandleLidSwitchDocked=</varname></term> - <listitem><para>Controls whether logind shall handle the + <listitem><para>Controls how logind shall handle the system power and sleep keys and the lid switch to trigger actions such as system power-off or suspend. Can be one of <literal>ignore</literal>, @@ -224,7 +240,16 @@ docking station, or if more than one display is connected, the action specified by <varname>HandleLidSwitchDocked=</varname> occurs; otherwise the <varname>HandleLidSwitch=</varname> - action occurs.</para></listitem> + action occurs.</para> + + <para>A different application may disable logind's handling of system power and + sleep keys and the lid switch by taking a low-level inhibitor lock + ("handle-power-key", "handle-suspend-key", "handle-hibernate-key", + "handle-lid-switch"). This is most commonly used by graphical desktop environments + to take over suspend and hibernation handling, and to use their own configuration + mechanisms. If a low-level inhibitor lock is taken, logind will not take any + action when that key or switch is triggered and the <varname>Handle*=</varname> + settings are irrelevant.</para></listitem> </varlistentry> <varlistentry> @@ -233,21 +258,22 @@ <term><varname>HibernateKeyIgnoreInhibited=</varname></term> <term><varname>LidSwitchIgnoreInhibited=</varname></term> - <listitem><para>Controls whether actions triggered by the - power and sleep keys and the lid switch are subject to - inhibitor locks. These settings take boolean arguments. If - <literal>no</literal>, the inhibitor locks taken by - applications in order to block the requested operation are - respected. If <literal>yes</literal>, the requested operation - is executed in any case. + <listitem><para>Controls whether actions that <command>systemd-logind</command> + takes when the power and sleep keys and the lid switch are triggered are subject + to high-level inhibitor locks ("shutdown", "sleep", "idle"). Low level inhibitor + locks ("handle-*-key"), are always honored, irrespective of this setting.</para> + + <para>These settings take boolean arguments. If <literal>no</literal>, the + inhibitor locks taken by applications are respected. If <literal>yes</literal>, + "shutdown", "sleep", and "idle" inhibitor locks are ignored. <varname>PowerKeyIgnoreInhibited=</varname>, - <varname>SuspendKeyIgnoreInhibited=</varname> and - <varname>HibernateKeyIgnoreInhibited=</varname> default to - <literal>no</literal>. - <varname>LidSwitchIgnoreInhibited=</varname> defaults to - <literal>yes</literal>. This means that the lid switch does - not respect suspend blockers by default, but the power and - sleep keys do. </para></listitem> + <varname>SuspendKeyIgnoreInhibited=</varname>, and + <varname>HibernateKeyIgnoreInhibited=</varname> default to <literal>no</literal>. + <varname>LidSwitchIgnoreInhibited=</varname> defaults to <literal>yes</literal>. + This means that when <command>systemd-logind</command> is handling events by + itself (no low level inhibitor locks are taken by another application), the lid + switch does not respect suspend blockers by default, but the power and sleep keys + do.</para></listitem> </varlistentry> <varlistentry> @@ -255,8 +281,8 @@ <listitem><para>Specifies the timeout after system startup or system resume in which systemd will hold off on reacting to - LID events. This is required for the system to properly - detect any hotplugged devices so systemd can ignore LID events + lid events. This is required for the system to properly + detect any hotplugged devices so systemd can ignore lid events if external monitors, or docks, are connected. If set to 0, systemd will always react immediately, possibly before the kernel fully probed all hotplugged devices. This is safe, as @@ -277,21 +303,44 @@ limit relative to the amount of physical RAM. Defaults to 10%. Note that this size is a safety limit only. As each runtime directory is a tmpfs file system, it will only consume as much - memory as is needed. </para></listitem> + memory as is needed.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>InhibitorsMax=</varname></term> + + <listitem><para>Controls the maximum number of concurrent inhibitors to permit. Defaults to 8192 + (8K).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SessionsMax=</varname></term> + + <listitem><para>Controls the maximum number of concurrent user sessions to manage. Defaults to 8192 + (8K). Depending on how the <filename>pam_systemd.so</filename> module is included in the PAM stack + configuration, further login sessions will either be refused, or permitted but not tracked by + <filename>systemd-logind</filename>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>UserTasksMax=</varname></term> + + <listitem><para>Sets the maximum number of OS tasks each user may run concurrently. This controls the + <varname>TasksMax=</varname> setting of the per-user slice unit, see + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. If assigned the special value <literal>infinity</literal>, no tasks limit is applied. + Defaults to 33%, which equals 10813 with the kernel's defaults on the host, but might be smaller in + OS containers.</para></listitem> </varlistentry> <varlistentry> <term><varname>RemoveIPC=</varname></term> - <listitem><para>Controls whether System V and POSIX IPC - objects belonging to the user shall be removed when the user - fully logs out. Takes a boolean argument. If enabled, the user - may not consume IPC resources after the last of the user's - sessions terminated. This covers System V semaphores, shared - memory and message queues, as well as POSIX shared memory and - message queues. Note that IPC objects of the root user are - excluded from the effect of this setting. Defaults to - <literal>yes</literal>.</para></listitem> + <listitem><para>Controls whether System V and POSIX IPC objects belonging to the user shall be removed when the + user fully logs out. Takes a boolean argument. If enabled, the user may not consume IPC resources after the + last of the user's sessions terminated. This covers System V semaphores, shared memory and message queues, as + well as POSIX shared memory and message queues. Note that IPC objects of the root user and other system users + are excluded from the effect of this setting. Defaults to <literal>yes</literal>.</para></listitem> </varlistentry> </variablelist> diff --git a/man/machine-id.xml b/man/machine-id.xml index 92d67a3869..d318ec54ec 100644 --- a/man/machine-id.xml +++ b/man/machine-id.xml @@ -63,7 +63,7 @@ <para>The machine ID is usually generated from a random source during system installation and stays constant for all subsequent boots. Optionally, for stateless systems, it is generated during - runtime at boot if it is found to be empty.</para> + runtime at early boot if it is found to be empty.</para> <para>The machine ID does not change based on user configuration or when hardware is replaced.</para> @@ -84,6 +84,12 @@ at install time. Use <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> to initialize it on mounted (but not booted) system images.</para> + + <para>The machine-id may also be set, for example when network + booting, by setting the <varname>systemd.machine_id=</varname> + kernel command line parameter or passing the option + <option>--machine-id=</option> to systemd. A machine-id may not + be set to all zeros.</para> </refsect1> <refsect1> @@ -119,7 +125,7 @@ id[8] = (id[8] & 0x3F) | 0x80;</programlisting> <filename>/etc/machine-id</filename> originates in the <filename>/var/lib/dbus/machine-id</filename> file introduced by D-Bus. In fact, this latter file might be a symlink to - <varname>/etc/machine-id</varname>.</para> + <filename>/etc/machine-id</filename>.</para> </refsect1> <refsect1> diff --git a/man/machine-info.xml b/man/machine-info.xml index 916f1dab66..351133670b 100644 --- a/man/machine-info.xml +++ b/man/machine-info.xml @@ -124,7 +124,7 @@ <literal>tablet</literal>, <literal>handset</literal>, <literal>watch</literal>, and - <literal>embedded</literal> + <literal>embedded</literal>, as well as the special chassis types <literal>vm</literal> and <literal>container</literal> for diff --git a/man/machinectl.xml b/man/machinectl.xml index 4b87870853..eaa247714b 100644 --- a/man/machinectl.xml +++ b/man/machinectl.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -65,6 +65,43 @@ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> virtual machine and container registration manager <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + + <para><command>machinectl</command> may be used to execute + operations on machines and images. Machines in this sense are + considered running instances of:</para> + + <itemizedlist> + <listitem><para>Virtual Machines (VMs) that virtualize hardware + to run full operating system (OS) instances (including their kernels) + in a virtualized environment on top of the host OS.</para></listitem> + + <listitem><para>Containers that share the hardware and + OS kernel with the host OS, in order to run + OS userspace instances on top the host OS.</para></listitem> + + <listitem><para>The host system itself</para></listitem> + </itemizedlist> + + <para>Machines are identified by names that follow the same rules + as UNIX and DNS host names, for details, see below. Machines are + instantiated from disk or file system images that frequently — but not + necessarily — carry the same name as machines running from + them. Images in this sense are considered:</para> + + <itemizedlist> + <listitem><para>Directory trees containing an OS, including its + 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>Binary "raw" disk images containing MBR or GPT + partition tables and Linux file system partitions.</para></listitem> + + <listitem><para>The file system tree of the host OS itself.</para></listitem> + </itemizedlist> + </refsect1> <refsect1> @@ -96,7 +133,16 @@ <para>When listing VM or container images, do not suppress images beginning in a dot character - (<literal>.</literal>).</para></listitem> + (<literal>.</literal>).</para> + + <para>When cleaning VM or container images, remove all images, not just hidden ones.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--value</option></term> + + <listitem><para>When printing properties with <command>show</command>, only print the value, + and skip the property name and <literal>=</literal>.</para></listitem> </varlistentry> <varlistentry> @@ -138,21 +184,43 @@ </varlistentry> <varlistentry> + <term><option>--uid=</option></term> + + <listitem><para>When used with the <command>shell</command> command, chooses the user ID to + open the interactive shell session as. If the argument to the <command>shell</command> + command also specifies an user name, this option is ignored. If the name is not specified + in either way, <literal>root</literal> will be used by default. Note that this switch is + not supported for the <command>login</command> command (see below).</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> + + <listitem><para>When used with the <command>shell</command> command, sets an environment + variable to pass to the executed shell. Takes an environment variable name and value, + separated by <literal>=</literal>. This switch may be used multiple times to set multiple + environment variables. Note that this switch is not supported for the + <command>login</command> command (see below).</para></listitem> + </varlistentry> + + <varlistentry> <term><option>--mkdir</option></term> - <listitem><para>When used with <command>bind</command> creates + <listitem><para>When used with <command>bind</command>, creates the destination directory before applying the bind mount.</para></listitem> </varlistentry> - <varlistentry> <term><option>--read-only</option></term> - <listitem><para>When used with <command>bind</command> applies - a read-only bind mount.</para></listitem> - </varlistentry> + <listitem><para>When used with <command>bind</command>, applies + a read-only bind mount.</para> + <para>When used with <command>clone</command>, <command>import-raw</command> or <command>import-tar</command> a + read-only container or VM image is created.</para></listitem> + </varlistentry> <varlistentry> <term><option>-n</option></term> @@ -183,11 +251,11 @@ specify whether the image shall be verified before it is made available. Takes one of <literal>no</literal>, <literal>checksum</literal> and <literal>signature</literal>. - If <literal>no</literal> no verification is done. If - <literal>checksum</literal> is specified the download is - checked for integrity after transfer is complete, but no + If <literal>no</literal>, no verification is done. If + <literal>checksum</literal> is specified, the download is + checked for integrity after the transfer is complete, but no signatures are verified. If <literal>signature</literal> is - specified, the checksum is verified and the images's signature + specified, the checksum is verified and the image's signature is checked against a local keyring of trustable vendors. It is strongly recommended to set this option to <literal>signature</literal> if the server and protocol @@ -205,27 +273,31 @@ </varlistentry> <varlistentry> - <term><option>--dkr-index-url</option></term> - - <listitem><para>Specifies the index server to use for - downloading <literal>dkr</literal> images with the - <command>pull-dkr</command>. Takes a - <literal>http://</literal>, <literal>https://</literal> - URL.</para></listitem> - </varlistentry> - - <varlistentry> <term><option>--format=</option></term> <listitem><para>When used with the <option>export-tar</option> - or <option>export-raw</option> commands specifies the + or <option>export-raw</option> commands, specifies the compression format to use for the resulting file. Takes one of <literal>uncompressed</literal>, <literal>xz</literal>, - <literal>gzip</literal>, <literal>bzip2</literal>. By default + <literal>gzip</literal>, <literal>bzip2</literal>. By default, the format is determined automatically from the image file name passed.</para></listitem> </varlistentry> + <varlistentry> + <term><option>--max-addresses=</option></term> + + <listitem><para>When used with the <option>list-machines</option> + command, limits the number of ip addresses output for every machine. + Defaults to 1. All addresses can be requested with <literal>all</literal> + as argument to <option>--max-addresses</option> . If the argument to + <option>--max-addresses</option> is less than the actual number + of addresses,<literal>...</literal>follows the last address. + If multiple addresses are to be written for a given machine, every + address except the first one is on a new line and is followed by + <literal>,</literal> if another address will be output afterwards. </para></listitem> + </varlistentry> + <xi:include href="user-system-options.xml" xpointer="host" /> <xi:include href="user-system-options.xml" xpointer="machine" /> @@ -247,15 +319,17 @@ <term><command>list</command></term> <listitem><para>List currently running (online) virtual - machines and containers. To enumerate container images that - can be started, use <command>list-images</command> (see - below).</para></listitem> + machines and containers. To enumerate machine images that can + be started, use <command>list-images</command> (see + below). Note that this command hides the special + <literal>.host</literal> machine by default. Use the + <option>--all</option> switch to show it.</para></listitem> </varlistentry> <varlistentry> <term><command>status</command> <replaceable>NAME</replaceable>...</term> - <listitem><para>Show terse runtime status information about + <listitem><para>Show runtime status information about one or more virtual machines and containers, followed by the most recent log data from the journal. This function is intended to generate human-readable output. If you are looking @@ -267,17 +341,18 @@ </varlistentry> <varlistentry> - <term><command>show</command> <replaceable>NAME</replaceable>...</term> + <term><command>show</command> [<replaceable>NAME</replaceable>...]</term> <listitem><para>Show properties of one or more registered virtual machines or containers or the manager itself. If no argument is specified, properties of the manager will be - shown. If an NAME is specified, properties of this virtual + shown. If a NAME is specified, properties of this virtual machine or container are shown. By default, empty properties are suppressed. Use <option>--all</option> to show those too. To select specific properties to show, use <option>--property=</option>. This command is intended to be - used whenever computer-parsable output is required. Use + used whenever computer-parsable output is required, and does + not print the cgroup tree or journal entries. Use <command>status</command> if you are looking for formatted human-readable output.</para></listitem> </varlistentry> @@ -294,7 +369,7 @@ image by the specified name in <filename>/var/lib/machines/</filename> (and other search paths, see below) and runs it. Use - <command>list-images</command> (see below), for listing + <command>list-images</command> (see below) for listing available container images to start.</para> <para>Note that @@ -311,26 +386,71 @@ <para>To interactively start a container on the command line with full access to the container's console, please invoke <command>systemd-nspawn</command> directly. To stop a running - container use <command>machinectl poweroff</command>, see - below.</para></listitem> + container use <command>machinectl poweroff</command>.</para></listitem> </varlistentry> <varlistentry> - <term><command>login</command> <replaceable>NAME</replaceable></term> - - <listitem><para>Open an interactive terminal login session to - a container. This will create a TTY connection to a specific - container and asks for the execution of a getty on it. Note - that this is only supported for containers running + <term><command>login</command> [<replaceable>NAME</replaceable>]</term> + + <listitem><para>Open an interactive terminal login session in + a container or on the local host. If an argument is supplied, + it refers to the container machine to connect to. If none is + specified, or the container name is specified as the empty + string, or the special machine name <literal>.host</literal> + (see below) is specified, the connection is made to the local + host instead. This will create a TTY connection to a specific + container or the local host and asks for the execution of a + getty on it. Note that this is only supported for containers + running <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> as init system.</para> <para>This command will open a full login prompt on the - container, which then asks for username and password. Use + container or the local host, which then asks for username and + password. Use <command>shell</command> (see below) or <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry> - with the <option>--machine=</option> switch to invoke a single - command, either interactively or in the background within a - local container.</para></listitem> + with the <option>--machine=</option> switch to directly invoke + a single command, either interactively or in the + background.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>shell</command> [[<replaceable>NAME</replaceable>@]<replaceable>NAME</replaceable> [<replaceable>PATH</replaceable> [<replaceable>ARGUMENTS</replaceable>...]]] </term> + + <listitem><para>Open an interactive shell session in a + container or on the local host. The first argument refers to + the container machine to connect to. If none is specified, or + the machine name is specified as the empty string, or the + special machine name <literal>.host</literal> (see below) is + specified, the connection is made to the local host + instead. This works similar to <command>login</command> but + immediately invokes a user process. This command runs the + specified executable with the specified arguments, or + <filename>/bin/sh</filename> if none is specified. By default, + opens a <literal>root</literal> shell, but by using + <option>--uid=</option>, or by prefixing the machine name with + a username and an <literal>@</literal> character, a different + user may be selected. Use <option>--setenv=</option> to set + environment variables for the executed process.</para> + + <para>When using the <command>shell</command> command without + arguments, (thus invoking the executed shell or command on the + local host), it is in many ways similar to a <citerefentry + project='die-net'><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry> + session, but, unlike <command>su</command>, completely isolates + the new session from the originating session, so that it + shares no process or session properties, and is in a clean and + well-defined state. It will be tracked in a new utmp, login, + audit, security and keyring session, and will not inherit any + environment variables or resource limits, among other + properties.</para> + + <para>Note that + <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry> + may be used in place of the <command>shell</command> command, + and allows more detailed, low-level configuration of the + invoked unit. However, it is frequently more privileged than + the <command>shell</command> command.</para></listitem> </varlistentry> <varlistentry> @@ -353,8 +473,8 @@ <listitem><para>Power off one or more containers. This will trigger a reboot by sending SIGRTMIN+4 to the container's init process, which causes systemd-compatible init systems to shut - down cleanly. This operation does not work on containers that - do not run a + down cleanly. Use <command>stop</command> as alias for <command>poweroff</command>. + This operation does not work on containers that do not run a <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible init system, such as sysvinit. Use <command>terminate</command> (see below) to immediately @@ -401,11 +521,11 @@ specified container. The first directory argument is the source directory on the host, the second directory argument is the destination directory in the container. When the - latter is omitted the destination path in the container is + latter is omitted, the destination path in the container is the same as the source path on the host. When combined with - the <option>--read-only</option> switch a ready-only bind + the <option>--read-only</option> switch, a ready-only bind mount is created. When combined with the - <option>--mkdir</option> switch the destination path is first + <option>--mkdir</option> switch, the destination path is first created before the mount is applied. Note that this option is currently only supported for <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> @@ -418,7 +538,7 @@ <listitem><para>Copies files or directories from the host system into a running container. Takes a container name, followed by the source path on the host and the destination - path in the container. If the destination path is omitted the + path in the container. If the destination path is omitted, the same as the source path is used.</para></listitem> </varlistentry> @@ -429,7 +549,7 @@ <listitem><para>Copies files or directories from a container into the host system. Takes a container name, followed by the source path in the container the destination path on the host. - If the destination path is omitted the same as the source path + If the destination path is omitted, the same as the source path is used.</para></listitem> </varlistentry> </variablelist></refsect2> @@ -444,8 +564,8 @@ directories and subvolumes in <filename>/var/lib/machines/</filename> (and other search paths, see below). Use <command>start</command> (see above) to - run a container off one of the listed images. Note that by - default containers whose name begins with a dot + run a container off one of the listed images. Note that, by + default, containers whose name begins with a dot (<literal>.</literal>) are not shown. To show these too, specify <option>--all</option>. Note that a special image <literal>.host</literal> always implicitly exists and refers @@ -453,7 +573,7 @@ </varlistentry> <varlistentry> - <term><command>image-status</command> <replaceable>NAME</replaceable>...</term> + <term><command>image-status</command> [<replaceable>NAME</replaceable>...]</term> <listitem><para>Show terse status information about one or more container or VM images. This function is intended to @@ -463,12 +583,12 @@ </varlistentry> <varlistentry> - <term><command>show-image</command> <replaceable>NAME</replaceable>...</term> + <term><command>show-image</command> [<replaceable>NAME</replaceable>...]</term> <listitem><para>Show properties of one or more registered virtual machine or container images, or the manager itself. If no argument is specified, properties of the manager will be - shown. If an NAME is specified, properties of this virtual + shown. If a NAME is specified, properties of this virtual machine or container image are shown. By default, empty properties are suppressed. Use <option>--all</option> to show those too. To select specific properties to show, use @@ -481,19 +601,20 @@ <varlistentry> <term><command>clone</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term> - <listitem><para>Clones a container or VM image. The - arguments specify the name of the image to clone and the name - of the newly cloned image. Note that plain directory container - images are cloned into subvolume images with this command. - Note that cloning a container or VM image is optimized for - btrfs file systems, and might not be efficient on others, due - to file system limitations.</para> + <listitem><para>Clones a container or VM image. The arguments specify the name of the image to clone and the + name of the newly cloned image. Note that plain directory container images are cloned into btrfs subvolume + images with this command, if the underlying file system supports this. Note that cloning a container or VM + image is optimized for btrfs file systems, and might not be efficient on others, due to file system + limitations.</para> <para>Note that this command leaves host name, machine ID and all other settings that could identify the instance unmodified. The original image and the cloned copy will hence share these credentials, and it might be necessary to manually - change them in the copy.</para></listitem> + change them in the copy.</para> + + <para>If combined with the <option>--read-only</option> switch a read-only cloned image is + created.</para></listitem> </varlistentry> <varlistentry> @@ -518,27 +639,27 @@ <listitem><para>Removes one or more container or VM images. The special image <literal>.host</literal>, which refers to - the host's own directory tree may not be + the host's own directory tree, may not be removed.</para></listitem> </varlistentry> <varlistentry> <term><command>set-limit</command> [<replaceable>NAME</replaceable>] <replaceable>BYTES</replaceable></term> - <listitem><para>Sets the maximum size in bytes a specific - container or VM image, or all images may grow up to on disk + <listitem><para>Sets the maximum size in bytes that a specific + container or VM image, or all images, may grow up to on disk (disk quota). Takes either one or two parameters. The first, optional parameter refers to a container or VM image name. If - specified the size limit of the specified image is changed. If - omitted the overall size limit of the sum of all images stored + specified, the size limit of the specified image is changed. If + omitted, the overall size limit of the sum of all images stored locally is changed. The final argument specifies the size limit in bytes, possibly suffixed by the usual K, M, G, T 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 image + 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 @@ -548,12 +669,29 @@ 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 image + 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> </varlistentry> + <varlistentry> + <term><command>clean</command></term> + + <listitem><para>Remove hidden VM or container images (or all). This command removes all hidden machine images + from <filename>/var/lib/machines</filename>, i.e. those whose name begins with a dot. Use <command>machinectl + list-images --all</command> to see a list of all machine images, including the hidden ones.</para> + + <para>When combined with the <option>--all</option> switch removes all images, not just hidden ones. This + command effectively empties <filename>/var/lib/machines</filename>.</para> + + <para>Note that commands such as <command>machinectl pull-tar</command> or <command>machinectl + pull-raw</command> usually create hidden, read-only, unmodified machine images from the downloaded image first, + before cloning a writable working copy of it, in order to avoid duplicate downloads in case of images that are + reused multiple times. Use <command>machinectl clean</command> to remove old, hidden images created this + way.</para></listitem> + </varlistentry> + </variablelist></refsect2> <refsect2><title>Image Transfer Commands</title><variablelist> @@ -568,20 +706,20 @@ <literal>https://</literal>, and must refer to a <filename>.tar</filename>, <filename>.tar.gz</filename>, <filename>.tar.xz</filename> or <filename>.tar.bz2</filename> - archive file. If the local machine name is omitted it + archive file. If the local machine name is omitted, it is automatically derived from the last component of the URL, with its suffix removed.</para> <para>The image is verified before it is made available, unless <option>--verify=no</option> is specified. Verification - is done via SHA256SUMS and SHA256SUMS.gpg files, that need to + is done via SHA256SUMS and SHA256SUMS.gpg files that need to be made available on the same web server, under the same URL as the <filename>.tar</filename> file, but with the last component (the filename) of the URL replaced. With - <option>--verify=checksum</option> only the SHA256 checksum + <option>--verify=checksum</option>, only the SHA256 checksum for the file is verified, based on the <filename>SHA256SUMS</filename> file. With - <option>--verify=signature</option> the SHA256SUMS file is + <option>--verify=signature</option>, the SHA256SUMS file is first verified with detached GPG signature file <filename>SHA256SUMS.gpg</filename>. The public key for this verification step needs to be available in @@ -590,10 +728,10 @@ <para>The container image will be downloaded and stored in a read-only subvolume in - <filename>/var/lib/machines/</filename>, that is named after + <filename>/var/lib/machines/</filename> that is named after the specified URL and its HTTP etag. A writable snapshot is then taken from this subvolume, and named after the specified - local name. This behaviour ensures that creating multiple + local name. This behavior ensures that creating multiple container instances of the same URL is efficient, as multiple downloads are not necessary. In order to create only the read-only image, and avoid creating its writable snapshot, @@ -621,7 +759,7 @@ be a <filename>.qcow2</filename> or raw disk image, optionally compressed as <filename>.gz</filename>, <filename>.xz</filename>, or <filename>.bz2</filename>. If the - local machine name is omitted it is automatically + local machine name is omitted, it is automatically derived from the last component of the URL, with its suffix removed.</para> @@ -639,7 +777,7 @@ machine name. To omit creation of the local, writable copy pass <literal>-</literal> as local machine name.</para> - <para>Similar to the behaviour of <command>pull-tar</command>, + <para>Similar to the behavior of <command>pull-tar</command>, the read-only image is prefixed with <filename>.raw-</filename>, and thus not shown by <command>list-images</command>, unless <option>--all</option> @@ -652,63 +790,26 @@ </varlistentry> <varlistentry> - <term><command>pull-dkr</command> <replaceable>REMOTE</replaceable> [<replaceable>NAME</replaceable>]</term> - - <listitem><para>Downloads a <literal>dkr</literal> container - image and makes it available locally. The remote name refers - to a <literal>dkr</literal> container name. If omitted, the - local machine name is derived from the <literal>dkr</literal> - container name.</para> - - <para>Image verification is not available for - <literal>dkr</literal> containers, and thus - <option>--verify=no</option> must always be specified with - this command.</para> - - <para>This command downloads all (missing) layers for the - specified container and places them in read-only subvolumes in - <filename>/var/lib/machines/</filename>. A writable snapshot - of the newest layer is then created under the specified local - machine name. To omit creation of this writable snapshot, pass - <literal>-</literal> as local machine name.</para> - - <para>The read-only layer subvolumes are prefixed with - <filename>.dkr-</filename>, and thus not shown by - <command>list-images</command>, unless <option>--all</option> - is passed.</para> - - <para>To specify the <literal>dkr</literal> index server to - use for looking up the specified container, use - <option>--dkr-index-url=</option>.</para> - - <para>Note that pressing C-c during execution of this command - will not abort the download. Use - <command>cancel-transfer</command>, described - below.</para></listitem> - </varlistentry> - - <varlistentry> <term><command>import-tar</command> <replaceable>FILE</replaceable> [<replaceable>NAME</replaceable>]</term> <term><command>import-raw</command> <replaceable>FILE</replaceable> [<replaceable>NAME</replaceable>]</term> <listitem><para>Imports a TAR or RAW container or VM image, and places it under the specified name in <filename>/var/lib/machines/</filename>. When - <command>import-tar</command> is used the file specified as - first argument should be a tar archive, possibly compressed + <command>import-tar</command> is used, the file specified as + the first argument should be a tar archive, possibly compressed with xz, gzip or bzip2. It will then be unpacked into its own subvolume in <filename>/var/lib/machines</filename>. When - <command>import-raw</command> is used the file should be a + <command>import-raw</command> is used, the file should be a qcow2 or raw disk image, possibly compressed with xz, gzip or bzip2. If the second argument (the resulting image name) is - not specified it is automatically derived from the file - name. If the file name is passed as <literal>-</literal> the + not specified, it is automatically derived from the file + name. If the file name is passed as <literal>-</literal>, the image is read from standard input, in which case the second argument is mandatory.</para> - <para>Similar as with <command>pull-tar</command>, - <command>pull-raw</command> the file system - <filename>/var/lib/machines.raw</filename> is increased in - size of necessary and appropriate. Optionally the + <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> @@ -725,11 +826,11 @@ stores it in the specified file. The first parameter should be a VM or container image name. The second parameter should be a file path the TAR or RAW image is written to. If the path ends - in <literal>.gz</literal> the file is compressed with gzip, if - it ends in <literal>.xz</literal> with xz, and if it ends in - <literal>.bz2</literal> with bzip2. If the path ends in - neither the file is left uncompressed. If the second argument - is missing the image is written to standard output. The + in <literal>.gz</literal>, the file is compressed with gzip, if + it ends in <literal>.xz</literal>, with xz, and if it ends in + <literal>.bz2</literal>, with bzip2. If the path ends in + neither, the file is left uncompressed. If the second argument + is missing, the image is written to standard output. The compression may also be explicitly selected with the <option>--format=</option> switch. This is in particular useful if the second parameter is left unspecified.</para> @@ -739,7 +840,7 @@ aborted with <command>cancel-transfer</command>.</para> - <para>Note that currently only directory and subvolume images + <para>Note that, currently, only directory and subvolume images may be exported as TAR images, and only raw disk images as RAW images.</para></listitem> </varlistentry> @@ -766,12 +867,47 @@ </refsect1> <refsect1> + <title>Machine and Image Names</title> + + <para>The <command>machinectl</command> tool operates on machines + and images whose names must be chosen following strict + rules. Machine names must be suitable for use as host names + following a conservative subset of DNS and UNIX/Linux + semantics. Specifically, they must consist of one or more + non-empty label strings, separated by dots. No leading or trailing + dots are allowed. No sequences of multiple dots are allowed. The + label strings may only consist of alphanumeric characters as well + as the dash and underscore. The maximum length of a machine name + is 64 characters.</para> + + <para>A special machine with the name <literal>.host</literal> + refers to the running host system itself. This is useful for execution + operations or inspecting the host system as well. Note that + <command>machinectl list</command> will not show this special + machine unless the <option>--all</option> switch is specified.</para> + + <para>Requirements on image names are less strict, however, they must be + valid UTF-8, must be suitable as file names (hence not be the + single or double dot, and not include a slash), and may not + contain control characters. Since many operations search for an + image by the name of a requested machine, it is recommended to name + images in the same strict fashion as machines.</para> + + <para>A special image with the name <literal>.host</literal> + refers to the image of the running host system. It hence + conceptually maps to the special <literal>.host</literal> machine + name described above. Note that <command>machinectl + list-images</command> will not show this special image either, unless + <option>--all</option> is specified.</para> + </refsect1> + + <refsect1> <title>Files and Directories</title> <para>Machine images are preferably stored in <filename>/var/lib/machines/</filename>, but are also searched for in <filename>/usr/local/lib/machines/</filename> and - <filename>/usr/lib/machines/</filename>. For compatibility reasons + <filename>/usr/lib/machines/</filename>. For compatibility reasons, the directory <filename>/var/lib/container/</filename> is searched, too. Note that images stored below <filename>/usr</filename> are always considered read-only. It is @@ -782,12 +918,12 @@ <para>Note that many 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>pull-dkr</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 + <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> @@ -800,7 +936,7 @@ <listitem><para>A simple directory tree, containing the files and directories of the container to boot.</para></listitem> - <listitem><para>A subvolume (on btrfs file systems), which are + <listitem><para>Subvolumes (on btrfs file systems), which are similar to the simple directories, described above. However, they have additional benefits, such as efficient cloning and quota reporting.</para></listitem> @@ -813,7 +949,7 @@ <para>See <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> - for more information on image formats, in particular it's + for more information on image formats, in particular its <option>--directory=</option> and <option>--image=</option> options.</para> </refsect1> @@ -836,40 +972,39 @@ <title>Download a Fedora image, set a root password in it, start it as service</title> - <programlisting># machinectl pull-raw --verify=no http://ftp.halifax.rwth-aachen.de/fedora/linux/releases/21/Cloud/Images/x86_64/Fedora-Cloud-Base-20141203-21.x86_64.raw.xz -# systemd-nspawn -M Fedora-Cloud-Base-20141203-21 + <programlisting># machinectl pull-raw --verify=no https://dl.fedoraproject.org/pub/fedora/linux/releases/23/Cloud/x86_64/Images/Fedora-Cloud-Base-23-20151030.x86_64.raw.xz +# systemd-nspawn -M Fedora-Cloud-Base-23-20151030 # passwd # exit -# machinectl start Fedora-Cloud-Base-20141203-21 -# machinectl login Fedora-Cloud-Base-20141203-21</programlisting> +# machinectl start Fedora-Cloud-Base-23-20151030 +# machinectl login Fedora-Cloud-Base-23-20151030</programlisting> <para>This downloads the specified <filename>.raw</filename> - image with verification disabled. Then a shell is opened in it + image with verification disabled. Then, a shell is opened in it and a root password is set. Afterwards the shell is left, and the machine started as system service. With the last command a login prompt into the container is requested.</para> </example> <example> - <title>Download a Fedora <literal>dkr</literal> image</title> + <title>Exports a container image as tar file</title> - <programlisting># machinectl pull-dkr --verify=no mattdm/fedora -# systemd-nspawn -M fedora</programlisting> + <programlisting># machinectl export-tar fedora myfedora.tar.xz</programlisting> - <para>Downloads a <literal>dkr</literal> image and opens a shell - in it. Note that the specified download command might require an - index server to be specified with the - <literal>--dkr-index-url=</literal>.</para> + <para>Exports the container <literal>fedora</literal> as an + xz-compressed tar file <filename>myfedora.tar.xz</filename> into the + current directory.</para> </example> <example> - <title>Exports a container image as tar file</title> + <title>Create a new shell session</title> - <programlisting># machinectl export-tar fedora myfedora.tar.xz</programlisting> + <programlisting># machinectl shell --uid=lennart</programlisting> - <para>Exports the container <literal>fedora</literal> in an - xz-compress tar file <filename>myfedora.tar.xz</filename> in the - current directory.</para> + <para>This creates a new shell session on the local host for + the user ID <literal>lennart</literal>, in a <citerefentry + project='die-net'><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry>-like + fashion.</para> </example> </refsect1> diff --git a/man/networkctl.xml b/man/networkctl.xml index 388afbed93..24e1de6986 100644 --- a/man/networkctl.xml +++ b/man/networkctl.xml @@ -87,6 +87,7 @@ <xi:include href="standard-options.xml" xpointer="help" /> <xi:include href="standard-options.xml" xpointer="version" /> + <xi:include href="standard-options.xml" xpointer="no-legend" /> <xi:include href="standard-options.xml" xpointer="no-pager" /> </variablelist> @@ -101,12 +102,14 @@ <varlistentry> <term> <command>list</command> + <optional><replaceable>LINK...</replaceable></optional> </term> <listitem> - <para>Show a list of existing links and their - status. Produces output similar to <programlisting> -IDX LINK TYPE OPERATIONAL SETUP + <para>Show a list of existing links and their status. If no further arguments are specified shows all links, + otherwise just the specified links. Produces output similar to: + + <programlisting>IDX LINK TYPE OPERATIONAL SETUP 1 lo loopback carrier unmanaged 2 eth0 ether routable configured 3 virbr0 ether no-carrier unmanaged @@ -127,10 +130,10 @@ IDX LINK TYPE OPERATIONAL SETUP state, kernel module driver, hardware and IP address, configured DNS servers, etc.</para> - <para>When no links are specified, routable links are - shown. See also option <option>--all</option>.</para> + <para>When no links are specified, an overall network status is shown. Also see the option + <option>--all</option>.</para> - <para>Produces output similar to + <para>Produces output similar to: <programlisting> ● State: routable Address: 10.193.76.5 on eth0 @@ -147,11 +150,26 @@ IDX LINK TYPE OPERATIONAL SETUP <varlistentry> <term> <command>lldp</command> + <optional><replaceable>LINK...</replaceable></optional> </term> <listitem> - <para>Show LLDP (Link Layer Discovery Protocol) - status.</para> + <para>Show discovered LLDP (Link Layer Discovery Protocol) neighbors. If one or more link names are specified + only neighbors on those interfaces are shown. Otherwise shows discovered neighbors on all interfaces. Note + that for this feature to work, <varname>LLDP=</varname> must be turned on on the specific interface, see + <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for + details.</para> + + <para>Produces output similar to: + <programlisting>LINK CHASSIS ID SYSTEM NAME CAPS PORT ID PORT DESCRIPTION +enp0s25 00:e0:4c:00:00:00 GS1900 ..b........ 2 Port #2 + +Capability Flags: +o - Other; p - Repeater; b - Bridge; w - WLAN Access Point; r - Router; +t - Telephone; d - DOCSIS cable device; a - Station; c - Customer VLAN; +s - Service VLAN, m - Two-port MAC Relay (TPMR) + +1 neighbors listed.</programlisting></para> </listitem> </varlistentry> </variablelist> diff --git a/man/networkd.conf.xml b/man/networkd.conf.xml new file mode 100644 index 0000000000..57e647a31b --- /dev/null +++ b/man/networkd.conf.xml @@ -0,0 +1,154 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2014 Vinay Kulkarni + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="networkd.conf" conditional='ENABLE_NETWORKD' + xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>networkd.conf</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Vinay</firstname> + <surname>Kulkarni</surname> + <email>kulkarniv@vmware.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>networkd.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>networkd.conf</refname> + <refname>networkd.conf.d</refname> + <refpurpose>Global Network configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/systemd/networkd.conf</filename></para> + <para><filename>/etc/systemd/networkd.conf.d/*.conf</filename></para> + <para><filename>/usr/lib/systemd/networkd.conf.d/*.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>These configuration files control global network parameters. + Currently the DHCP Unique Identifier (DUID).</para> + + </refsect1> + + <xi:include href="standard-conf.xml" xpointer="main-conf" /> + + <refsect1> + <title>[DHCP] Section Options</title> + + <para>This section configures the DHCP Unique Identifier (DUID) value used by DHCP + protocol. DHCPv6 client protocol sends the DHCP Unique Identifier and the interface + Identity Association Identifier (IAID) to a DHCP server when acquiring a dynamic IPv6 + address. DHCPv4 client protocol sends IAID and DUID to the DHCP server when acquiring + a dynamic IPv4 address if <option>ClientIdentifier=duid</option>. IAID and DUID allows + a DHCP server to uniquely identify the machine and the interface requesting a DHCP IP. + To configure IAID and ClientIdentifier, see + <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para> + + <para>The following options are understood:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>DUIDType=</varname></term> + <listitem><para>Specifies how the DUID should be generated. See + <ulink url="https://tools.ietf.org/html/rfc3315#section-9">RFC 3315</ulink> + for a description of all the options.</para> + + <para>The following values are understood: + <variablelist> + <varlistentry> + <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>. + This is the default if <varname>DUIDType=</varname> is not specified. + </para></listitem> + </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>. + </para></listitem> + </varlistentry> + </variablelist> + </para> + + <para>In all cases, <varname>DUIDRawData=</varname> can be used to override the + actual DUID value that is used.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DUIDRawData=</varname></term> + <listitem><para>Specifies the DHCP DUID value as a single newline-terminated, hexadecimal string, with each + 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 + <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>, + <ulink url="http://tools.ietf.org/html/rfc6355">RFC 6355</ulink>. To configure IAID, see + <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum> + </citerefentry>.</para> + + <example> + <title>A <option>DUIDType=vendor</option> with a custom value</title> + + <programlisting>DUIDType=vendor +DUIDRawData=00:00:ab:11:f9:2a:c2:77:29:f9:5c:00</programlisting> + + <para>This specifies a 14 byte DUID, with the type DUID-EN (<literal>00:02</literal>), enterprise number + 43793 (<literal>00:00:ab:11</literal>), and identifier value <literal>f9:2a:c2:77:29:f9:5c:00</literal>. + </para> + </example> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <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> + </para> + </refsect1> + +</refentry> diff --git a/man/nss-myhostname.xml b/man/nss-myhostname.xml index 2d36df6f6f..b1daaba02b 100644 --- a/man/nss-myhostname.xml +++ b/man/nss-myhostname.xml @@ -57,12 +57,11 @@ <refsect1> <title>Description</title> - <para><command>nss-myhostname</command> is a plugin for the GNU - Name Service Switch (NSS) functionality of the GNU C Library - (<command>glibc</command>) primarily providing hostname resolution - for the locally configured system hostname as returned by - <citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>. - The precise hostnames resolved by this module are:</para> + <para><command>nss-myhostname</command> is a plug-in module for the GNU Name Service Switch (NSS) functionality of + the GNU C Library (<command>glibc</command>), primarily providing hostname resolution for the locally configured + system hostname as returned by + <citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>. The precise + hostnames resolved by this module are:</para> <itemizedlist> <listitem><para>The local, configured hostname is resolved to @@ -71,16 +70,16 @@ is on the local loopback) and the IPv6 address ::1 (which is the local host).</para></listitem> - <listitem><para>The hostname <literal>localhost</literal> is - resolved to the IP addresses 127.0.0.1 and - ::1.</para></listitem> + <listitem><para>The hostnames <literal>localhost</literal> and + <literal>localhost.localdomain</literal> (as well as any hostname + ending in <literal>.localhost</literal> or <literal>.localhost.localdomain</literal>) + are resolved to the IP addresses 127.0.0.1 and ::1.</para></listitem> <listitem><para>The hostname <literal>gateway</literal> is resolved to all current default routing gateway addresses, ordered by their metric. This assigns a stable hostname to the current gateway, useful for referencing it independently of the current network configuration state.</para></listitem> - </itemizedlist> <para>Various software relies on an always-resolvable local @@ -89,39 +88,35 @@ time as changing the hostname. This is problematic since it requires a writable <filename>/etc</filename> file system and is fragile because the file might be edited by the administrator at - the same time. With <command>nss-myhostname</command> enabled + the same time. With <command>nss-myhostname</command> enabled, changing <filename>/etc/hosts</filename> is unnecessary, and on - many systems the file becomes entirely optional.</para> - - <para>To activate the NSS modules, <literal>myhostname</literal> - has to be added to the line starting with - <literal>hosts:</literal> in - <filename>/etc/nsswitch.conf</filename>.</para> - - <para>It is recommended to place <literal>myhostname</literal> - last in the <filename>nsswitch.conf</filename> line to make sure - that this mapping is only used as fallback, and any DNS or - <filename>/etc/hosts</filename> based mapping takes - precedence.</para> + many systems, the file becomes entirely optional.</para> + + <para>To activate the NSS modules, add <literal>myhostname</literal> to the line starting with + <literal>hosts:</literal> in <filename>/etc/nsswitch.conf</filename>.</para> + + <para>It is recommended to place <literal>myhostname</literal> last in the <filename>nsswitch.conf</filename>' + <literal>hosts:</literal> line to make sure that this mapping is only used as fallback, and that any DNS or + <filename>/etc/hosts</filename> based mapping takes precedence.</para> </refsect1> <refsect1> <title>Example</title> - <para>Here's an example <filename>/etc/nsswitch.conf</filename> - file, that enables <command>myhostname</command> correctly:</para> + <para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables + <command>nss-myhostname</command> correctly:</para> -<programlisting>passwd: compat -group: compat -shadow: compat +<programlisting>passwd: compat mymachines systemd +group: compat mymachines systemd +shadow: compat -hosts: files dns mymachines <command>myhostname</command> +hosts: files mymachines resolve <command>myhostname</command> networks: files protocols: db files services: db files -ethers: db files -rpc: db files +ethers: db files +rpc: db files netgroup: nis</programlisting> @@ -135,7 +130,7 @@ netgroup: nis</programlisting> 127.0.0.2 DGRAM 127.0.0.2 RAW</programlisting> - <para>In this case the local hostname is <varname>omega</varname>.</para> + <para>In this case, the local hostname is <varname>omega</varname>.</para> </refsect1> @@ -143,6 +138,8 @@ netgroup: nis</programlisting> <title>See Also</title> <para> <citerefentry><refentrytitle>systemd</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-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>getent</refentrytitle><manvolnum>1</manvolnum></citerefentry> diff --git a/man/nss-mymachines.xml b/man/nss-mymachines.xml index eb1ed2592b..a70119e256 100644 --- a/man/nss-mymachines.xml +++ b/man/nss-mymachines.xml @@ -56,43 +56,43 @@ <refsect1> <title>Description</title> - <para><command>nss-mymachines</command> is a plugin for the GNU - Name Service Switch (NSS) functionality of the GNU C Library - (<command>glibc</command>) providing hostname resolution for - containers running locally, that are registered with - <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - The container names are resolved to IP addresses of the specific - container, ordered by their scope.</para> - - <para>To activate the NSS modules, <literal>mymachines</literal> - has to be added to the line starting with - <literal>hosts:</literal> in + <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 + 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> + + <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 <filename>/etc/nsswitch.conf</filename>.</para> - <para>It is recommended to place <literal>mymachines</literal> - near the end of the <filename>nsswitch.conf</filename> line to - make sure that this mapping is only used as fallback, and any DNS - or <filename>/etc/hosts</filename> based mapping takes - precedence.</para> + <para>It is recommended to place <literal>mymachines</literal> after the <literal>files</literal> or + <literal>compat</literal> entry of the <filename>/etc/nsswitch.conf</filename> lines to make sure that its mappings + are preferred over other resolvers such as DNS, but so that <filename>/etc/hosts</filename>, + <filename>/etc/passwd</filename> and <filename>/etc/group</filename> based mappings take precedence.</para> </refsect1> <refsect1> <title>Example</title> - <para>Here's an example <filename>/etc/nsswitch.conf</filename> - file, that enables <command>mymachines</command> correctly:</para> + <para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables + <command>nss-mymachines</command> correctly:</para> -<programlisting>passwd: compat -group: compat -shadow: compat + <programlisting>passwd: compat <command>mymachines</command> systemd +group: compat <command>mymachines</command> systemd +shadow: compat -hosts: files dns <command>mymachines</command> myhostname +hosts: files <command>mymachines</command> resolve myhostname networks: files protocols: db files services: db files -ethers: db files -rpc: db files +ethers: db files +rpc: db files netgroup: nis</programlisting> @@ -103,6 +103,8 @@ netgroup: nis</programlisting> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</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>, <citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>getent</refentrytitle><manvolnum>1</manvolnum></citerefentry> diff --git a/man/nss-resolve.xml b/man/nss-resolve.xml new file mode 100644 index 0000000000..d66e8ba521 --- /dev/null +++ b/man/nss-resolve.xml @@ -0,0 +1,114 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2011 Lennart Poettering + Copyright 2013 Tom Gundersen + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="nss-resolve" conditional='ENABLE_RESOLVED'> + + <refentryinfo> + <title>nss-resolve</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>nss-resolve</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>nss-resolve</refname> + <refname>libnss_resolve.so.2</refname> + <refpurpose>Provide hostname resolution via <filename>systemd-resolved.service</filename></refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>libnss_resolve.so.2</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>nss-resolve</command> is a plug-in module for the GNU Name Service Switch (NSS) functionality of the + GNU C Library (<command>glibc</command>) enabling it to resolve host names via the + <citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry> local network + name resolution service. It replaces the <command>nss-dns</command> plug-in module that traditionally resolves + hostnames via DNS.</para> + + <para>To activate the NSS module, add <literal>resolve</literal> to the line starting with + <literal>hosts:</literal> in <filename>/etc/nsswitch.conf</filename>.</para> + + <para>It is recommended to place <literal>resolve</literal> early in <filename>/etc/nsswitch.conf</filename>' + <literal>hosts:</literal> line (but after the <literal>files</literal> or <literal>mymachines</literal> entries), + replacing the <literal>dns</literal> entry if it exists, to ensure DNS queries are always routed via + <citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + + <para>Note that <command>nss-resolve</command> will chain-load <command>nss-dns</command> if + <filename>systemd-resolved.service</filename> is not running, ensuring that basic DNS resolution continues to work + if the service is down.</para> + </refsect1> + + <refsect1> + <title>Example</title> + + <para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables <command>nss-resolve</command> + correctly:</para> + +<programlisting>passwd: compat mymachines systemd +group: compat mymachines systemd +shadow: compat + +hosts: files mymachines <command>resolve [!UNAVAIL=return]</command> dns +networks: files + +protocols: db files +services: db files +ethers: db files +rpc: db files + +netgroup: nis</programlisting> + + <para>This keeps the <command>dns</command> module as a fallback for cases where the <command>nss-resolve</command> + module is not installed.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nss-systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/nss-systemd.xml b/man/nss-systemd.xml new file mode 100644 index 0000000000..56d26e7d1f --- /dev/null +++ b/man/nss-systemd.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"> + +<!-- + This file is part of systemd. + + Copyright 2016 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="nss-systemd"> + + <refentryinfo> + <title>nss-systemd</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>nss-systemd</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>nss-systemd</refname> + <refname>libnss_systemd.so.2</refname> + <refpurpose>Provide UNIX user and group name resolution for dynamic users and groups.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>libnss_systemd.so.2</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>nss-systemd</command> is a plug-in module for the GNU Name Service Switch (NSS) functionality of the + GNU C Library (<command>glibc</command>), providing UNIX user and group name resolution for dynamic users and + groups allocated through the <varname>DynamicUser=</varname> option in systemd unit files. See + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details on + this option.</para> + + <para>This module also ensures that the root and nobody users and groups (i.e. the users/groups with the UIDs/GIDs + 0 and 65534) remain resolvable at all times, even if they aren't listed in <filename>/etc/passwd</filename> or + <filename>/etc/group</filename>, or if these files are missing.</para> + + <para>To activate the NSS module, add <literal>systemd</literal> to the lines starting with + <literal>passwd:</literal> and <literal>group:</literal> in <filename>/etc/nsswitch.conf</filename>.</para> + + <para>It is recommended to place <literal>systemd</literal> after the <literal>files</literal> or + <literal>compat</literal> entry of the <filename>/etc/nsswitch.conf</filename> lines so that + <filename>/etc/passwd</filename> and <filename>/etc/group</filename> based mappings take precedence.</para> + </refsect1> + + <refsect1> + <title>Example</title> + + <para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables + <command>nss-systemd</command> correctly:</para> + + <programlisting>passwd: compat mymachines <command>systemd</command> +group: compat mymachines <command>systemd</command> +shadow: compat + +hosts: files mymachines resolve myhostname +networks: files + +protocols: db files +services: db files +ethers: db files +rpc: db files + +netgroup: nis</programlisting> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>getent</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/os-release.xml b/man/os-release.xml index 4ca2e59706..99bbb61004 100644 --- a/man/os-release.xml +++ b/man/os-release.xml @@ -67,7 +67,7 @@ without implementing a shell compatible execution engine. Variable assignment values must be enclosed in double or single quotes if they include spaces, semicolons or other special characters - outside of A-Z, a-z, 0-9. Shell special characters ("$", quotes, + outside of A–Z, a–z, 0–9. Shell special characters ("$", quotes, backslash, backtick) must be escaped with backslashes, following shell style. All strings should be in UTF-8 format, and non-printable characters should not be used. It is not supported @@ -141,7 +141,7 @@ <term><varname>ID=</varname></term> <listitem><para>A lower-case string (no spaces or other - characters outside of 0-9, a-z, ".", "_" and "-") identifying + characters outside of 0–9, a–z, ".", "_" and "-") identifying the operating system, excluding any version information and suitable for processing by scripts or usage in generated filenames. If not set, defaults to @@ -176,10 +176,26 @@ </varlistentry> <varlistentry> + <term><varname>VERSION_CODENAME=</varname></term> + + <listitem><para> + A lower-case string (no spaces or other characters outside of + 0–9, a–z, ".", "_" and "-") identifying the operating system + release code name, excluding any OS name information or + release version, and suitable for processing by scripts or + usage in generated filenames. This field is optional and may + not be implemented on all systems. + Examples: + <literal>VERSION_CODENAME=buster</literal>, + <literal>VERSION_CODENAME=xenial</literal> + </para></listitem> + </varlistentry> + + <varlistentry> <term><varname>VERSION_ID=</varname></term> <listitem><para>A lower-case string (mostly numeric, no spaces - or other characters outside of 0-9, a-z, ".", "_" and "-") + or other characters outside of 0–9, a–z, ".", "_" and "-") identifying the operating system version, excluding any OS name information or release code name, and suitable for processing by scripts or usage in generated filenames. This @@ -214,10 +230,11 @@ <varlistentry> <term><varname>CPE_NAME=</varname></term> - <listitem><para>A CPE name for the operating system, following - the <ulink url="https://cpe.mitre.org/specification/">Common + <listitem><para>A CPE name for the operating system, in URI + binding syntax, following the + <ulink url="http://scap.nist.gov/specifications/cpe/">Common Platform Enumeration Specification</ulink> as proposed by the - MITRE Corporation. This field is optional. Example: + NIST. This field is optional. Example: <literal>CPE_NAME="cpe:/o:fedoraproject:fedora:17"</literal> </para></listitem> </varlistentry> @@ -297,7 +314,7 @@ <listitem><para> A lower-case string (no spaces or other characters outside of - 0-9, a-z, ".", "_" and "-"), identifying a specific variant or + 0–9, a–z, ".", "_" and "-"), identifying a specific variant or edition of the operating system. This may be interpreted by other packages in order to determine a divergent default configuration. This field is optional and may not be diff --git a/man/pam_systemd.xml b/man/pam_systemd.xml index b4a3f502b4..ddda81bc90 100644 --- a/man/pam_systemd.xml +++ b/man/pam_systemd.xml @@ -197,7 +197,7 @@ as <constant>AF_UNIX</constant> sockets, FIFOs, PID files and similar. It is guaranteed that this directory is local and offers the greatest possible file system feature set the - operating system provides. For further details see the <ulink + operating system provides. For further details, see the <ulink url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG Base Directory Specification</ulink>.</para></listitem> </varlistentry> diff --git a/man/resolved.conf.xml b/man/resolved.conf.xml index 8047a4ea75..4fc1ef1b33 100644 --- a/man/resolved.conf.xml +++ b/man/resolved.conf.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!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 @@ <title>Description</title> <para>These configuration files control local DNS and LLMNR - name resolving.</para> + name resolution.</para> </refsect1> @@ -68,33 +68,46 @@ <refsect1> <title>Options</title> + <para>The following options are available in the <literal>[Resolve]</literal> section:</para> + <variablelist class='network-directives'> <varlistentry> <term><varname>DNS=</varname></term> - <listitem><para>A space separated list of IPv4 and IPv6 - addresses to be used as system DNS servers. DNS requests are - sent to one of the listed DNS servers in parallel to any - per-interface DNS servers acquired from - <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - For compatibility reasons, if set to the empty list the DNS - servers listed in <filename>/etc/resolv.conf</filename> are - used, if any are configured there. This setting defaults to - the empty list.</para></listitem> + <listitem><para>A space-separated list of IPv4 and IPv6 addresses to use as system DNS servers. DNS requests + are sent to one of the listed DNS servers in parallel to suitable per-link DNS servers acquired from + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> or + set at runtime by external applications. For compatibility reasons, if this setting is not specified, the DNS + servers listed in <filename>/etc/resolv.conf</filename> are used instead, if that file exists and any servers + are configured in it. This setting defaults to the empty list.</para></listitem> </varlistentry> <varlistentry> <term><varname>FallbackDNS=</varname></term> - <listitem><para>A space separated list of IPv4 and IPv6 - addresses to be used as the fallback DNS servers. Any - per-interface DNS servers obtained from + <listitem><para>A space-separated list of IPv4 and IPv6 addresses to use as the fallback DNS servers. Any + per-link DNS servers obtained from <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - take precedence over this setting, as do any servers set via - <varname>DNS=</varname> above or - <filename>/etc/resolv.conf</filename>. This setting is hence - only used if no other DNS server information is known. If this - option is not given, a compiled-in list of DNS servers is used - instead.</para></listitem> + take precedence over this setting, as do any servers set via <varname>DNS=</varname> above or + <filename>/etc/resolv.conf</filename>. This setting is hence only used if no other DNS server information is + known. If this option is not given, a compiled-in list of DNS servers is used instead.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Domains=</varname></term> + <listitem><para>A space-separated list of domains. These domains are used as search suffixes when resolving + single-label host names (domain names which contain no dot), in order to qualify them into fully-qualified + domain names (FQDNs). Search domains are strictly processed in the order they are specified, until the name + with the suffix appended is found. For compatibility reasons, if this setting is not specified, the search + domains listed in <filename>/etc/resolv.conf</filename> are used instead, if that file exists and any domains + are configured in it. This setting defaults to the empty list.</para> + + <para>Specified domain names may optionally be prefixed with <literal>~</literal>. In this case they do not + define a search path, but preferably direct DNS queries for the indicated domains to the DNS servers configured + with the system <varname>DNS=</varname> setting (see above), in case additional, suitable per-link DNS servers + are known. If no per-link DNS servers are known using the <literal>~</literal> syntax has no effect. Use the + construct <literal>~.</literal> (which is composed of <literal>~</literal> to indicate a routing domain and + <literal>.</literal> to indicate the DNS root domain that is the implied suffix of all DNS domains) to use the + system DNS server defined with <varname>DNS=</varname> preferably for all domains.</para></listitem> </varlistentry> <varlistentry> @@ -103,16 +116,115 @@ <literal>resolve</literal>. Controls Link-Local Multicast Name Resolution support (<ulink url="https://tools.ietf.org/html/rfc4795">RFC 4794</ulink>) on - the local host. If true enables full LLMNR responder and - resolver support. If false disable both. If set to - <literal>resolve</literal> only resolving support is enabled, + 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, but responding is disabled. Note that <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - also maintains per-interface LLMNR settings. LLMNR will be - enabled on an interface only if the per-interface and the + also maintains per-link LLMNR settings. LLMNR will be + enabled on a link only if the per-link and the global setting is on.</para></listitem> </varlistentry> + <varlistentry> + <term><varname>DNSSEC=</varname></term> + <listitem><para>Takes a boolean argument or + <literal>allow-downgrade</literal>. If true all DNS lookups are + DNSSEC-validated locally (excluding LLMNR and Multicast + DNS). If the response to a lookup request is detected to be invalid + a lookup failure is returned to applications. Note that + this mode requires a DNS server that supports DNSSEC. If the + DNS server does not properly support DNSSEC all validations + will fail. If set to <literal>allow-downgrade</literal> DNSSEC + validation is attempted, but if the server does not support + DNSSEC properly, DNSSEC mode is automatically disabled. Note + that this mode makes DNSSEC validation vulnerable to + "downgrade" attacks, where an attacker might be able to + trigger a downgrade to non-DNSSEC mode by synthesizing a DNS + response that suggests DNSSEC was not supported. If set to + false, DNS lookups are not DNSSEC validated.</para> + + <para>Note that DNSSEC validation requires retrieval of + additional DNS data, and thus results in a small DNS look-up + time penalty.</para> + + <para>DNSSEC requires knowledge of "trust anchors" to prove + data integrity. The trust anchor for the Internet root domain + is built into the resolver, additional trust anchors may be + defined with + <citerefentry><refentrytitle>dnssec-trust-anchors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + Trust anchors may change at regular intervals, and old trust + anchors may be revoked. In such a case DNSSEC validation is + not possible until new trust anchors are configured locally or + the resolver software package is updated with the new root + trust anchor. In effect, when the built-in trust anchor is + revoked and <varname>DNSSEC=</varname> is true, all further + lookups will fail, as it cannot be proved anymore whether + lookups are correctly signed, or validly unsigned. If + <varname>DNSSEC=</varname> is set to + <literal>allow-downgrade</literal> the resolver will + automatically turn off DNSSEC validation in such a case.</para> + + <para>Client programs looking up DNS data will be informed + whether lookups could be verified using DNSSEC, or whether the + returned data could not be verified (either because the data + was found unsigned in the DNS, or the DNS server did not + support DNSSEC or no appropriate trust anchors were known). In + the latter case it is assumed that client programs employ a + secondary scheme to validate the returned DNS data, should + this be required.</para> + + <para>It is recommended to set <varname>DNSSEC=</varname> to + true on systems where it is known that the DNS server supports + DNSSEC correctly, and where software or trust anchor updates + happen regularly. On other systems it is recommended to set + <varname>DNSSEC=</varname> to + <literal>allow-downgrade</literal>.</para> + + <para>In addition to this global DNSSEC setting + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + also maintains per-link DNSSEC settings. For system DNS + servers (see above), only the global DNSSEC setting is in + effect. For per-link DNS servers the per-link + setting is in effect, unless it is unset in which case the + global setting is used instead.</para> + + <para>Site-private DNS zones generally conflict with DNSSEC + operation, unless a negative (if the private zone is not + signed) or positive (if the private zone is signed) trust + anchor is configured for them. If + <literal>allow-downgrade</literal> mode is selected, it is + attempted to detect site-private DNS zones using top-level + 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> + </listitem> + </varlistentry> + + <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> + + <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> + </varlistentry> + + <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 + 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 + 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> + </variablelist> </refsect1> @@ -122,7 +234,8 @@ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>resolv.conf</refentrytitle><manvolnum>4</manvolnum></citerefentry> + <citerefentry><refentrytitle>dnssec-trust-anchors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>4</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/runlevel.xml b/man/runlevel.xml index fc1f523855..ca29c7c22c 100644 --- a/man/runlevel.xml +++ b/man/runlevel.xml @@ -51,11 +51,62 @@ <refsynopsisdiv> <cmdsynopsis> - <command>runlevel <arg choice="opt" rep="repeat">options</arg></command> + <command>runlevel</command> + <arg choice="opt" rep="repeat">options</arg> </cmdsynopsis> </refsynopsisdiv> <refsect1> + <title>Overview</title> + + <para>"Runlevels" are an obsolete way to start and stop groups of + services used in SysV init. systemd provides a compatibility layer + that maps runlevels to targets, and associated binaries like + <command>runlevel</command>. Nevertheless, only one runlevel can + be "active" at a given time, while systemd can activate multiple + targets concurrently, so the mapping to runlevels is confusing + and only approximate. Runlevels should not be used in new code, + and are mostly useful as a shorthand way to refer the matching + systemd targets in kernel boot parameters.</para> + + <table> + <title>Mapping between runlevels and systemd targets</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname="runlevel" /> + <colspec colname="target" /> + <thead> + <row> + <entry>Runlevel</entry> + <entry>Target</entry> + </row> + </thead> + <tbody> + <row> + <entry>0</entry> + <entry><filename>poweroff.target</filename></entry> + </row> + <row> + <entry>1</entry> + <entry><filename>rescue.target</filename></entry> + </row> + <row> + <entry>2, 3, 4</entry> + <entry><filename>multi-user.target</filename></entry> + </row> + <row> + <entry>5</entry> + <entry><filename>graphical.target</filename></entry> + </row> + <row> + <entry>6</entry> + <entry><filename>reboot.target</filename></entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> <title>Description</title> <para><command>runlevel</command> prints the previous and current @@ -130,17 +181,10 @@ </refsect1> <refsect1> - <title>Notes</title> - - <para>This is a legacy command available for compatibility only. - It should not be used anymore, as the concept of runlevels is - obsolete.</para> - </refsect1> - - <refsect1> <title>See Also</title> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/sd-bus-errors.xml b/man/sd-bus-errors.xml index d6bbd7fbb2..055af7a682 100644 --- a/man/sd-bus-errors.xml +++ b/man/sd-bus-errors.xml @@ -121,10 +121,10 @@ <title>Description</title> <para>In addition to the error names user programs define, D-Bus - knows a number of generic, standardized error names, that are + knows a number of generic, standardized error names that are listed below.</para> - <para>In addition to this list, in sd-bus the special error + <para>In addition to this list, in sd-bus, the special error namespace <literal>System.Error.</literal> is used to map arbitrary Linux system errors (as defined by <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>) @@ -138,7 +138,7 @@ <term><varname>SD_BUS_ERROR_FAILED</varname></term> <listitem><para>A generic error indication. See the error message for further details. This error name should be - avoided, in favour of a more expressive error + avoided, in favor of a more expressive error name.</para></listitem> </varlistentry> @@ -167,7 +167,7 @@ <varlistentry> <term><varname>SD_BUS_ERROR_IO_ERROR</varname></term> <listitem><para>Generic input/output error, for example when - accessing a socket or other IO context.</para></listitem> + accessing a socket or other I/O context.</para></listitem> </varlistentry> <varlistentry> <term><varname>SD_BUS_ERROR_BAD_ADDRESS</varname></term> @@ -186,7 +186,7 @@ </varlistentry> <varlistentry> <term><varname>SD_BUS_ERROR_ACCESS_DENIED</varname></term> - <listitem><para>Access to a resource has bee denied, due to security restrictions.</para></listitem> + <listitem><para>Access to a resource has been denied due to security restrictions.</para></listitem> </varlistentry> <varlistentry> <term><varname>SD_BUS_ERROR_AUTH_FAILED</varname></term> @@ -224,7 +224,7 @@ </varlistentry> <varlistentry> <term><varname>SD_BUS_ERROR_FILE_EXISTS</varname></term> - <listitem><para>The requested file exists already.</para></listitem> + <listitem><para>The requested file already exists.</para></listitem> </varlistentry> <varlistentry> <term><varname>SD_BUS_ERROR_UNKNOWN_METHOD</varname></term> @@ -272,7 +272,7 @@ <varlistentry> <term><varname>SD_BUS_ERROR_INTERACTIVE_AUTHORIZATION_REQUIRED</varname></term> <listitem><para>Access to the requested operation is not - permitted, however, it might be available after interactive + permitted. However, it might be available after interactive authentication. This is usually returned by method calls supporting a framework for additional interactive authorization, when interactive authorization was not enabled diff --git a/man/sd-bus.xml b/man/sd-bus.xml new file mode 100644 index 0000000000..66b1c96c15 --- /dev/null +++ b/man/sd-bus.xml @@ -0,0 +1,114 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2016 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd-bus" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd-bus</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Documentation</contrib> + <firstname>Zbigniew</firstname> + <surname>Jędrzejewski-Szmek</surname> + <email>zbyszek@in.waw.pl</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd-bus</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd-bus</refname> + <refpurpose>A lightweight D-Bus IPC client library</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + </funcsynopsis> + + <cmdsynopsis> + <command>pkg-config --cflags --libs libsystemd</command> + </cmdsynopsis> + + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>sd-bus.h</filename> provides an implementation of a D-Bus IPC client. See + <ulink url="http://www.freedesktop.org/software/dbus/" /> + for more information about D-Bus IPC. + </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>, + for more information about the functions available.</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-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>busctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>dbus-send</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd-daemon.xml b/man/sd-daemon.xml index b7ba363656..b06d99f346 100644 --- a/man/sd-daemon.xml +++ b/man/sd-daemon.xml @@ -71,10 +71,10 @@ <refsect1> <title>Description</title> - <para><filename>sd-daemon.h</filename> provide APIs for new-style + <para><filename>sd-daemon.h</filename> provides APIs for new-style daemons, as implemented by the <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> - init system.</para> + service manager.</para> <para>See <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, diff --git a/man/sd-event.xml b/man/sd-event.xml new file mode 100644 index 0000000000..24a69bb645 --- /dev/null +++ b/man/sd-event.xml @@ -0,0 +1,187 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2015 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd-event" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd-event</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd-event</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd-event</refname> + <refpurpose>A generic event loop implementation</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> + </funcsynopsis> + + <cmdsynopsis> + <command>pkg-config --cflags --libs libsystemd</command> + </cmdsynopsis> + + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>sd-event.h</filename> provides a generic event + loop implementation, based on Linux <citerefentry + project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + </para> + + <para>See + <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_run</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_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_get_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_get_pending</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more information about the functions available.</para> + + <para>The event loop design is targeted on running a separate + instance of the event loop in each thread; it has no concept of + distributing events from a single event loop instance onto + multiple worker threads. Dispatching events is strictly ordered + and subject to configurable priorities. In each event loop + iteration a single event source is dispatched. Each time an event + source is dispatched the kernel is polled for new events, before + the next event source is dispatched. The event loop is designed to + honor priorities and provide fairness within each priority. It is + not designed to provide optimal throughput, as this contradicts + these goals due the limitations of the underlying <citerefentry + project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry> + primitives.</para> + + <para>The event loop implementation provides the following features:</para> + + <orderedlist> + <listitem><para>I/O event sources, based on <citerefentry + project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>'s + file descriptor watching, including edge triggered events (<constant>EPOLLET</constant>). See <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Timer event sources, based on <citerefentry + project='man-pages'><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + supporting the <constant>CLOCK_MONOTONIC</constant>, + <constant>CLOCK_REALTIME</constant>, + <constant>CLOCK_BOOTIME</constant> clocks, as well as the + <constant>CLOCK_REALTIME_ALARM</constant> and + <constant>CLOCK_BOOTTIME_ALARM</constant> clocks that can resume + the system from suspend. When creating timer events a required + accuracy parameter may be specified which allows coalescing of + timer events to minimize power consumption. See <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>UNIX process signal events, based on + <citerefentry + project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + including full support for real-time signals, and queued parameters. See <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Child process state change events, based on + <citerefentry project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry>. See <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Static event sources, of three types: defer, + post and exit, for invoking calls in each event loop, after + other event sources or at event loop termination. See + <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Event sources may be assigned a 64bit priority + value, that controls the order in which event sources are + dispatched if multiple are pending simultaneously. See + <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>The event loop may automatically send watchdog + notification messages to the service manager. See + <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>The event loop may be integrated into foreign + event loops, such as the GLib one. See + <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for an example.</para></listitem> + </orderedlist> + + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_run</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_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_get_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_get_pending</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd-id128.xml b/man/sd-id128.xml index ea7972055d..5f24feff8e 100644 --- a/man/sd-id128.xml +++ b/man/sd-id128.xml @@ -47,10 +47,12 @@ <refname>sd-id128</refname> <refname>sd_id128_t</refname> <refname>SD_ID128_MAKE</refname> + <refname>SD_ID128_NULL</refname> <refname>SD_ID128_CONST_STR</refname> <refname>SD_ID128_FORMAT_STR</refname> <refname>SD_ID128_FORMAT_VAL</refname> <refname>sd_id128_equal</refname> + <refname>sd_id128_is_null</refname> <refpurpose>APIs for processing 128-bit IDs</refpurpose> </refnamediv> @@ -88,8 +90,8 @@ union type:</para> <programlisting>typedef union sd_id128 { - uint8_t bytes[16]; - uint64_t qwords[2]; + uint8_t bytes[16]; + uint64_t qwords[2]; } sd_id128_t;</programlisting> <para>This union type allows accessing the 128-bit ID as 16 @@ -108,37 +110,46 @@ <programlisting>#define SD_MESSAGE_COREDUMP SD_ID128_MAKE(fc,2e,22,bc,6e,e6,47,b6,b9,07,29,ab,34,a2,50,b1)</programlisting> + <para><function>SD_ID128_NULL</function> may be used to refer to the 128bit ID consisting of only NUL + bytes.</para> + <para><function>SD_ID128_CONST_STR()</function> may be used to convert constant 128-bit IDs into constant strings for output. The following example code will output the string "fc2e22bc6ee647b6b90729ab34a250b1":</para> <programlisting>int main(int argc, char *argv[]) { - puts(SD_ID128_CONST_STR(SD_MESSAGE_COREDUMP)); + puts(SD_ID128_CONST_STR(SD_MESSAGE_COREDUMP)); }</programlisting> - <para><function>SD_ID128_FORMAT_STR</function> and + <para><function>SD_ID128_FORMAT_STR()</function> and <function>SD_ID128_FORMAT_VAL()</function> may be used to format a 128-bit ID in a <citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> format string, as shown in the following example:</para> <programlisting>int main(int argc, char *argv[]) { - sd_id128_t id; - id = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07); - printf("The ID encoded in this C file is " SD_ID128_FORMAT_STR ".\n", SD_ID128_FORMAT_VAL(id)); - return 0; + sd_id128_t id; + id = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07); + printf("The ID encoded in this C file is " SD_ID128_FORMAT_STR ".\n", SD_ID128_FORMAT_VAL(id)); + return 0; }</programlisting> <para>Use <function>sd_id128_equal()</function> to compare two 128-bit IDs:</para> <programlisting>int main(int argc, char *argv[]) { - sd_id128_t a, b, c; - a = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07); - b = SD_ID128_MAKE(f2,28,88,9c,5f,09,44,15,9d,d7,04,77,58,cb,e7,3e); - c = a; - assert(sd_id128_equal(a, c)); - assert(!sd_id128_equal(a, b)); - return 0; + sd_id128_t a, b, c; + a = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07); + b = SD_ID128_MAKE(f2,28,88,9c,5f,09,44,15,9d,d7,04,77,58,cb,e7,3e); + c = a; + assert(sd_id128_equal(a, c)); + assert(!sd_id128_equal(a, b)); + return 0; +}</programlisting> + + <para>Use <function>sd_id128_is_null()</function> to check if an 128bit ID consists of only NUL bytes:</para> + + <programlisting>int main(int argc, char *argv[]) { + assert(sd_id128_is_null(SD_ID128_NULL)); }</programlisting> <para>Note that new, randomized IDs may be generated with diff --git a/man/sd-journal.xml b/man/sd-journal.xml index 9b1a52207f..936a83acf7 100644 --- a/man/sd-journal.xml +++ b/man/sd-journal.xml @@ -77,13 +77,16 @@ <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_enumerate_fields</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_get_cutoff_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_get_cutoff_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_get_usage</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_catalog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + <citerefentry><refentrytitle>sd_journal_get_catalog</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_has_runtime_files</refentrytitle><manvolnum>3</manvolnum></citerefentry> and - <citerefentry><refentrytitle>sd_journal_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry> + <citerefentry><refentrytitle>sd_journal_has_persistent_files</refentrytitle><manvolnum>3</manvolnum></citerefentry> for more information about the functions implemented.</para> <para>Command line access for submitting entries to the journal is @@ -109,6 +112,7 @@ <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_enumerate_fields</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_get_cutoff_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_get_cutoff_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, @@ -116,6 +120,8 @@ <citerefentry><refentrytitle>sd_journal_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_query_unique</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_get_catalog</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_has_runtime_files</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_has_persistent_files</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> diff --git a/man/sd_bus_add_match.xml b/man/sd_bus_add_match.xml new file mode 100644 index 0000000000..8bcf7164a0 --- /dev/null +++ b/man/sd_bus_add_match.xml @@ -0,0 +1,119 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2016 Julian Orth + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_bus_add_match"> + + <refentryinfo> + <title>sd_bus_add_match</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <firstname>Julian</firstname> + <surname>Orth</surname> + <email>ju.orth@gmail.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_add_match</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_add_match</refname> + + <refpurpose>Add a match rule for message dispatching</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_add_match</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef> + <paramdef>const char *<parameter>match</parameter></paramdef> + <paramdef>sd_bus_message_handler_t <parameter>callback</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>typedef int (*<function>sd_bus_message_handler_t</function>)</funcdef> + <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + <paramdef>sd_bus_error *<parameter>ret_error</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <function>sd_bus_add_match()</function> adds a match rule used to dispatch + incoming messages. The syntax of the rule passed in + <parameter>match</parameter> is described in the + <ulink url="https://dbus.freedesktop.org/doc/dbus-specification.html">D-Bus Specification</ulink>. + </para> + + <para> + The message <parameter>m</parameter> passed to the callback is only + borrowed, that is, the callback should not call + <citerefentry><refentrytitle>sd_bus_message_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> + on it. If the callback wants to hold on to the message beyond the lifetime + of the callback, it needs to call + <citerefentry><refentrytitle>sd_bus_message_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry> + to create a new reference. + </para> + + <para> + If an error occurs during the callback invocation, the callback should + return a negative error number. If it wants other callbacks that match the + same rule to be called, it should return 0. Otherwise it should return a + positive integer. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para> + On success, <function>sd_bus_add_match()</function> returns 0 or a + positive integer. On failure, it returns a negative errno-style error + code. + </para> + </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_creds_get_pid.xml b/man/sd_bus_creds_get_pid.xml index 4162fab065..4c05835568 100644 --- a/man/sd_bus_creds_get_pid.xml +++ b/man/sd_bus_creds_get_pid.xml @@ -317,7 +317,7 @@ to determine the mask of fields available.</para> <para><function>sd_bus_creds_get_pid()</function> will retrieve - the PID (process identifier). Similar, + the PID (process identifier). Similarly, <function>sd_bus_creds_get_ppid()</function> will retrieve the parent PID. Note that PID 1 has no parent process, in which case -ENXIO is returned.</para> @@ -326,14 +326,14 @@ TID (thread identifier).</para> <para><function>sd_bus_creds_get_uid()</function> will retrieve - the numeric UID (user identifier). Similar, + the numeric UID (user identifier). Similarly, <function>sd_bus_creds_get_euid()</function> returns the effective UID, <function>sd_bus_creds_get_suid()</function> the saved UID and <function>sd_bus_creds_get_fsuid()</function> the file system UID.</para> <para><function>sd_bus_creds_get_gid()</function> will retrieve the - numeric GID (group identifier). Similar, + numeric GID (group identifier). Similarly, <function>sd_bus_creds_get_egid()</function> returns the effective GID, <function>sd_bus_creds_get_sgid()</function> the saved GID and <function>sd_bus_creds_get_fsgid()</function> the file system @@ -355,7 +355,7 @@ <para><function>sd_bus_creds_get_exe()</function> will retrieve the path to the program executable (as stored in the <filename>/proc/<replaceable>pid</replaceable>/exe</filename> - link, but with <literal> (deleted)</literal> suffix removed). Note + link, but with the <literal> (deleted)</literal> suffix removed). Note that kernel threads do not have an executable path, in which case -ENXIO is returned.</para> @@ -372,49 +372,45 @@ <para><function>sd_bus_creds_get_unit()</function> will retrieve the systemd unit name (in the system instance of systemd) that the - process is part of. See + process is a part of. See <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. For - processes that are not part of a unit returns -ENXIO. + processes that are not part of a unit, returns -ENXIO. </para> <para><function>sd_bus_creds_get_user_unit()</function> will retrieve the systemd unit name (in the user instance of systemd) - that the process is part of. See + that the process is a part of. See <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. For - processes that are not part of a user unit returns -ENXIO. + processes that are not part of a user unit, returns -ENXIO. </para> <para><function>sd_bus_creds_get_slice()</function> will retrieve the systemd slice (a unit in the system instance of systemd) that - the process is part of. See - <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Similar, + the process is a part of. See + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Similarly, <function>sd_bus_creds_get_user_slice()</function> retrieves the systemd slice of the process, in the user instance of systemd. </para> <para><function>sd_bus_creds_get_session()</function> will retrieve the identifier of the login session that the process is - part of. See + a part of. See <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. For - processes that are not part of a session returns -ENXIO. + processes that are not part of a session, returns -ENXIO. </para> <para><function>sd_bus_creds_get_owner_uid()</function> will retrieve the numeric UID (user identifier) of the user who owns - the login session that the process is part of. See + the login session that the process is a part of. See <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - For processes that are not part of a session returns -ENXIO. + For processes that are not part of a session, returns -ENXIO. </para> - <para><function>sd_bus_creds_has_effective_cap()</function> will - check whether the capability specified by - <parameter>capability</parameter> was set in the effective - capabilities mask. A positive return value means that is was - set, zero means that it was not set, and a negative return - value indicates an error. See - <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> - and <varname>Capabilities=</varname> and - <varname>CapabilityBoundingSet=</varname> settings in + <para><function>sd_bus_creds_has_effective_cap()</function> will check whether the capability specified by + <parameter>capability</parameter> was set in the effective capabilities mask. A positive return value means that it + was set, zero means that it was not set, and a negative return value indicates an error. See <citerefentry + project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> and the + <varname>AmbientCapabilities=</varname> and <varname>CapabilityBoundingSet=</varname> settings in <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. </para> @@ -470,7 +466,7 @@ modified by the caller.</para> <para>All functions that take a <parameter>char***</parameter> - parameter will store the answer there as an address of a an array + parameter will store the answer there as an address of an array of strings. Each individual string is NUL-terminated, and the array is NULL-terminated as a whole. It will be valid as long as <parameter>c</parameter> remains valid, and should not be freed or @@ -494,7 +490,7 @@ <varlistentry> <term><constant>-ENODATA</constant></term> - <listitem><para>Given field is not available in the + <listitem><para>The given field is not available in the credentials object <parameter>c</parameter>.</para> </listitem> </varlistentry> @@ -502,7 +498,7 @@ <varlistentry> <term><constant>-ENXIO</constant></term> - <listitem><para>Given field is not specified for the described + <listitem><para>The given field is not specified for the described process or peer. This will be returned by <function>sd_bus_get_unit()</function>, <function>sd_bus_get_slice()</function>, @@ -514,8 +510,8 @@ slice, or logind session. It will also be returned by <function>sd_bus_creds_get_exe()</function> and <function>sd_bus_creds_get_cmdline()</function> for kernel - threads (since these aren't started from an executable binary - or have a command line), + threads (since these are not started from an executable binary, + nor have a command line), and by <function>sd_bus_creds_get_audit_session_id()</function> and <function>sd_bus_creds_get_audit_login_uid()</function> when the process is not part of an audit session, and diff --git a/man/sd_bus_creds_new_from_pid.xml b/man/sd_bus_creds_new_from_pid.xml index a78d3f5717..b4d7d61d0f 100644 --- a/man/sd_bus_creds_new_from_pid.xml +++ b/man/sd_bus_creds_new_from_pid.xml @@ -48,6 +48,7 @@ <refname>sd_bus_creds_get_augmented_mask</refname> <refname>sd_bus_creds_ref</refname> <refname>sd_bus_creds_unref</refname> + <refname>sd_bus_creds_unrefp</refname> <refpurpose>Retrieve credentials object for the specified PID</refpurpose> </refnamediv> @@ -65,12 +66,12 @@ <funcprototype> <funcdef>uint64_t <function>sd_bus_creds_get_mask</function></funcdef> - <paramdef>const sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> </funcprototype> <funcprototype> <funcdef>uint64_t <function>sd_bus_creds_get_augmented_mask</function></funcdef> - <paramdef>const sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> </funcprototype> <funcprototype> @@ -82,6 +83,11 @@ <funcdef>sd_bus_creds *<function>sd_bus_creds_unref</function></funcdef> <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> </funcprototype> + + <funcprototype> + <funcdef>void <function>sd_bus_creds_unrefp</function></funcdef> + <paramdef>sd_bus_creds **<parameter>c</parameter></paramdef> + </funcprototype> </funcsynopsis> <para> @@ -130,7 +136,7 @@ <para><function>sd_bus_creds_new_from_pid()</function> creates a new credentials object and fills it with information about the process <parameter>pid</parameter>. The pointer to this object - will be stored in <parameter>ret</parameter> pointer. Note that + will be stored in the <parameter>ret</parameter> pointer. Note that credential objects may also be created and retrieved via <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry> @@ -171,11 +177,11 @@ <constant>SD_BUS_CREDS_AUDIT_LOGIN_UID</constant>, <constant>SD_BUS_CREDS_TTY</constant>, <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>, - <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>, + <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>, and <constant>SD_BUS_CREDS_DESCRIPTION</constant>. Use the special value <constant>_SD_BUS_CREDS_ALL</constant> to request all supported fields. The <constant>SD_BUS_CREDS_AUGMENT</constant> - may not be ORed into the mask for invocations of + constant may not be ORed into the mask for invocations of <function>sd_bus_creds_new_from_pid()</function>.</para> <para>Fields can be retrieved from the credentials object using @@ -191,35 +197,35 @@ subset of fields requested in <parameter>creds_mask</parameter>. </para> - <para>Similar to <function>sd_bus_creds_get_mask()</function> the + <para>Similar to <function>sd_bus_creds_get_mask()</function>, the function <function>sd_bus_creds_get_augmented_mask()</function> returns a bitmask of field constants. The mask indicates which credential fields have been retrieved in a non-atomic fashion. For credential objects created via - <function>sd_bus_creds_new_from_pid()</function> this mask will be + <function>sd_bus_creds_new_from_pid()</function>, this mask will be identical to the mask returned by <function>sd_bus_creds_get_mask()</function>. However, for credential objects retrieved via - <function>sd_bus_get_name_creds()</function> this mask will be set + <function>sd_bus_get_name_creds()</function>, this mask will be set for the credential fields that could not be determined atomically at peer connection time, and which were later added by reading augmenting credential data from - <filename>/proc</filename>. Similar, for credential objects - retrieved via <function>sd_bus_get_owner_creds()</function> the + <filename>/proc</filename>. Similarly, for credential objects + retrieved via <function>sd_bus_get_owner_creds()</function>, the mask is set for the fields that could not be determined atomically - at bus creation time, but have been augmented. Similar, for + at bus creation time, but have been augmented. Similarly, for credential objects retrieved via - <function>sd_bus_message_get_creds()</function> the mask is set + <function>sd_bus_message_get_creds()</function>, the mask is set for the fields that could not be determined atomically at message - send time, but have been augmented. The mask returned by + sending time, but have been augmented. The mask returned by <function>sd_bus_creds_get_augmented_mask()</function> is always a subset of (or identical to) the mask returned by <function>sd_bus_creds_get_mask()</function> for the same object. The latter call hence returns all credential fields available in the credential object, the former then marks the subset of those that have been augmented. Note that augmented - fields are unsuitable for authorization decisions as they may be - retrieved at different times, thus being subject to races. Hence + fields are unsuitable for authorization decisions, as they may be + retrieved at different times, thus being subject to races. Hence, augmented fields should be used exclusively for informational purposes. </para> @@ -235,6 +241,21 @@ <para><function>sd_bus_creds_unref()</function> destroys a reference to <parameter>c</parameter>.</para> + + <para><function>sd_bus_creds_unrefp()</function> is similar to + <function>sd_bus_creds_unref()</function> but takes a pointer to a + pointer to an <type>sd_bus_creds</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>. Note that this function is defined as + inline function.</para> + + <para><function>sd_bus_creds_ref()</function>, + <function>sd_bus_creds_unref()</function> and + <function>sd_bus_creds_unrefp()</function> execute no operation if + the passed in bus credentials object is + <constant>NULL</constant>.</para> + </refsect1> <refsect1> diff --git a/man/sd_bus_default.xml b/man/sd_bus_default.xml index 1cf2cb8f9a..6d5a90de72 100644 --- a/man/sd_bus_default.xml +++ b/man/sd_bus_default.xml @@ -112,7 +112,7 @@ connection object to the user bus when invoked in user context, or to the system bus otherwise. The connection object is associated with the calling thread. Each time the function is invoked from - the same thread the same object is returned, but its reference + the same thread, the same object is returned, but its reference count is increased by one, as long as at least one reference is kept. When the last reference to the connection is dropped (using the @@ -120,8 +120,8 @@ call), the connection is terminated. Note that the connection is not automatically terminated when the associated thread ends. It is important to drop the last reference to the bus connection - explicitly before the thread ends or otherwise the connection will - be leaked. Also, queued but unread or unwritten messages keep the + explicitly before the thread ends, as otherwise, the connection will + leak. Also, queued but unread or unwritten messages keep the bus referenced, see below.</para> <para><function>sd_bus_default_user()</function> returns a user @@ -139,14 +139,14 @@ <function>sd_bus_open_system()</function> does the same, but connects to the system bus. In contrast to <function>sd_bus_default()</function>, - <function>sd_bus_default_user()</function>, - <function>sd_bus_default_system()</function> these calls return + <function>sd_bus_default_user()</function>, and + <function>sd_bus_default_system()</function>, these calls return new, independent connection objects that are not associated with the invoking thread and are not shared between multiple invocations. It is recommended to share connections per thread to efficiently make use the available resources. Thus, it is recommended to use <function>sd_bus_default()</function>, - <function>sd_bus_default_user()</function>, + <function>sd_bus_default_user()</function> and <function>sd_bus_default_system()</function> to connect to the user or system buses.</para> @@ -215,31 +215,31 @@ <para>Queued but unwritten/unread messages also keep a reference to their bus connection object. For this reason, even if an - application dropped all references to a bus connection it might - not get destroyed right-away. Until all incoming queued + application dropped all references to a bus connection, it might + not get destroyed right away. Until all incoming queued messages are read, and until all outgoing unwritten messages are written, the bus object will stay alive. <function>sd_bus_flush()</function> may be used to write all outgoing queued messages so they drop their references. To - flush the unread incoming messages use + flush the unread incoming messages, use <function>sd_bus_close()</function>, which will also close the bus - connection. When using the default bus logic it is a good idea to + connection. When using the default bus logic, it is a good idea to first invoke <function>sd_bus_flush()</function> followed by <function>sd_bus_close()</function> when a thread or process terminates, and thus its bus connection object should be freed.</para> - <para>The life-cycle of the default bus connection should be the + <para>The life cycle of the default bus connection should be the responsibility of the code that creates/owns the thread the default bus connection object is associated with. Library code should neither call <function>sd_bus_flush()</function> nor <function>sd_bus_close()</function> on default bus objects unless it does so in its own private, self-allocated thread. Library code should not use the default bus object in other threads unless it - is clear that the program using it will life-cycle the bus + is clear that the program using it will life cycle the bus connection object and flush and close it before exiting from the thread. In libraries where it is not clear that the calling - program will life-cycle the bus connection object it is hence + program will life cycle the bus connection object, it is hence recommended to use <function>sd_bus_open_system()</function> instead of <function>sd_bus_default_system()</function> and related calls.</para> diff --git a/man/sd_bus_error.xml b/man/sd_bus_error.xml index 6dc4541eb1..c2d7ee389b 100644 --- a/man/sd_bus_error.xml +++ b/man/sd_bus_error.xml @@ -167,7 +167,7 @@ <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>, but additional domain-specific errors may be defined by applications. The <structfield>message</structfield> field usually - contains a human readable string describing the details, but might + contains a human-readable string describing the details, but might be NULL. An unset <structname>sd_bus_error</structname> structure should have both fields initialized to NULL. Set an error structure to <constant>SD_BUS_ERROR_NULL</constant> in order to @@ -189,20 +189,20 @@ for a list of well-known error names. Additional error mappings may be defined with <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If - <parameter>e</parameter> is NULL no error structure is initialized + <parameter>e</parameter> is NULL, no error structure is initialized, but the error is still converted into an <varname>errno</varname>-style error. If <parameter>name</parameter> is <constant>NULL</constant>, it is assumed that no error occurred, and 0 is returned. This means that this function may be conveniently used in a <function>return</function> statement. If - <parameter>message</parameter> is NULL no message is set. This + <parameter>message</parameter> is NULL, no message is set. This call can fail if no memory may be allocated for the name and message strings, in which case an <constant>SD_BUS_ERROR_NO_MEMORY</constant> error might be set - instead and -ENOMEM returned. Do not use this call on error + instead and -ENOMEM be returned. Do not use this call on error structures that are already initialized. If you intend to reuse an - error structure free the old data stored in it with + error structure, free the old data stored in it with <function>sd_bus_error_free()</function> first.</para> <para><function>sd_bus_error_setf()</function> is similar to @@ -216,8 +216,8 @@ are not copied internally, and must hence remain constant and valid for the lifetime of <parameter>e</parameter>. Use this call to avoid memory allocations when setting error structures. Since - this call does not allocate memory it will not fail with an - out-of-memory condition, as + this call does not allocate memory, it will not fail with an + out-of-memory condition as <function>sd_bus_error_set()</function> can, as described above. Alternatively, the <constant>SD_BUS_ERROR_MAKE_CONST()</constant> macro may be used @@ -238,7 +238,7 @@ convenient usage in <function>return</function> statements. This call might fail due to lack of memory, in which case an <constant>SD_BUS_ERROR_NO_MEMORY</constant> error is set instead, - and -ENOMEM returned.</para> + and -ENOMEM is returned.</para> <para><function>sd_bus_error_set_errnof()</function> is similar to <function>sd_bus_error_set_errno()</function>, but in addition to @@ -249,7 +249,7 @@ <parameter>format</parameter> and the arguments.</para> <para><function>sd_bus_error_set_errnofv()</function> is similar to - <function>sd_bus_error_set_errnof()</function> but takes the + <function>sd_bus_error_set_errnof()</function>, but takes the format string parameters as <citerefentry project='man-pages'><refentrytitle>va_arg</refentrytitle><manvolnum>3</manvolnum></citerefentry> parameter list.</para> @@ -295,10 +295,10 @@ <title>Return Value</title> <para>The functions <function>sd_bus_error_set()</function>, - <function>sd_bus_error_setf()</function>, + <function>sd_bus_error_setf()</function>, and <function>sd_bus_error_set_const()</function>, when successful, return the negative errno value corresponding to the - <parameter>name</parameter> parameter. Functions + <parameter>name</parameter> parameter. The functions <function>sd_bus_error_set_errno()</function>, <function>sd_bus_error_set_errnof()</function> and <function>sd_bus_error_set_errnofv()</function>, when successful, @@ -331,7 +331,7 @@ <title>Reference ownership</title> <para><structname>sd_bus_error</structname> is not reference counted. Users should destroy resources held by it by calling - <function>sd_bus_error_free()</function>. Usually error structures + <function>sd_bus_error_free()</function>. Usually, error structures are allocated on the stack or passed in as function parameters, but they may also be allocated dynamically, in which case it is the duty of the caller to <citerefentry diff --git a/man/sd_bus_error_add_map.xml b/man/sd_bus_error_add_map.xml index 3fca63be4a..139bd77d8c 100644 --- a/man/sd_bus_error_add_map.xml +++ b/man/sd_bus_error_add_map.xml @@ -87,7 +87,7 @@ <citerefentry><refentrytitle>sd_bus_error_set</refentrytitle><manvolnum>3</manvolnum></citerefentry> or <citerefentry><refentrytitle>sd_bus_error_get_errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>. By - default a number of generic, standardized mappings are known, as + default, a number of generic, standardized mappings are known, as documented in <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Use this call to add further, application-specific mappings.</para> @@ -95,12 +95,12 @@ <para>The function takes a pointer to an array of <structname>sd_bus_error_map</structname> structures. A reference to the specified array is added to the lookup tables for error - mappings. Note that the structure is not copied, it is hence + mappings. Note that the structure is not copied, and that it is hence essential that the array stays available and constant during the entire remaining runtime of the process.</para> <para>The mapping array should be put together with a series of - <constant>SD_BUS_ERROR_MAP()</constant> macro invocations, that + <constant>SD_BUS_ERROR_MAP()</constant> macro invocations that take a literal name string and a (positive) <varname>errno</varname>-style error number. The last entry of the array should be an invocation of the diff --git a/man/sd_bus_get_fd.xml b/man/sd_bus_get_fd.xml new file mode 100644 index 0000000000..9f7019069f --- /dev/null +++ b/man/sd_bus_get_fd.xml @@ -0,0 +1,101 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2016 Julian Orth + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_bus_get_fd"> + + <refentryinfo> + <title>sd_bus_get_fd</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <firstname>Julian</firstname> + <surname>Orth</surname> + <email>ju.orth@gmail.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_get_fd</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_get_fd</refname> + + <refpurpose>Get the file descriptor connected to the message bus</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_get_fd</function></funcdef> + <paramdef>sd_bus *<parameter>bus</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> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para> + Returns the file descriptor used for incoming messages from the message + bus. + </para> + </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_set_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_message_append.xml b/man/sd_bus_message_append.xml index 0ee849dca7..77fce02eae 100644 --- a/man/sd_bus_message_append.xml +++ b/man/sd_bus_message_append.xml @@ -70,7 +70,7 @@ appends a sequence of fields to the D-Bus message object <parameter>m</parameter>. The type string <parameter>types</parameter> describes the types of the field - arguments that follow. For each type specified in the type string + arguments that follow. For each type specified in the type string, one or more arguments need to be specified, in the same order as declared in the type string.</para> diff --git a/man/sd_bus_message_append_array.xml b/man/sd_bus_message_append_array.xml index 034466bf9c..27db2a96c3 100644 --- a/man/sd_bus_message_append_array.xml +++ b/man/sd_bus_message_append_array.xml @@ -49,7 +49,7 @@ <refname>sd_bus_message_append_array_iovec</refname> <refname>sd_bus_message_append_array_space</refname> - <refpurpose>Appaned an array of fields to a D-Bus + <refpurpose>Append an array of fields to a D-Bus message</refpurpose> </refnamediv> @@ -125,14 +125,14 @@ <parameter>m</parameter>, similar to <function>sd_bus_message_append_array()</function>. The contents of the memory file descriptor <parameter>memfd</parameter> - starting at the specified offset and and of the specified size is + starting at the specified offset and of the specified size is used as the contents of the array. The offset and size must be a multiple of the size of the type <parameter>type</parameter>. However, as a special exception, if the offset is specified as zero and the size specified as UINT64_MAX the full memory file descriptor contents is used. The - memory file descriptor is sealed by this call if it hasn't been - sealed yet, and cannot be modified a after this call. See + memory file descriptor is sealed by this call if it has not been + sealed yet, and cannot be modified after this call. See <citerefentry project='man-pages'><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry> for details about memory file descriptors. Appending arrays with @@ -142,7 +142,7 @@ process. Not all protocol transports support passing memory file descriptors between participants, in which case this call will automatically fall back to copying. Also, as memory file - descriptor passing is inefficient for smaller amounts of data + descriptor passing is inefficient for smaller amounts of data, copying might still be enforced even where memory file descriptor passing is supported.</para> @@ -150,13 +150,13 @@ function appends an array of a trivial type to the message <parameter>m</parameter>, similar to <function>sd_bus_message_append_array()</function>. Contents of - the IO vector array <parameter>iov</parameter> are used as the + the I/O vector array <parameter>iov</parameter> are used as the contents of the array. The total size of <parameter>iov</parameter> payload (the sum of <structfield>iov_len</structfield> fields) must be a multiple of the size of the type <parameter>type</parameter>. The <parameter>iov</parameter> argument must point to - <parameter>n</parameter> IO vector structures. Each structure may + <parameter>n</parameter> I/O vector structures. Each structure may have the <structname>iov_base</structname> field set, in which case the memory pointed to will be copied into the message, or unset (set to zero), in which case a block of zeros of length @@ -171,9 +171,9 @@ copying items to the message, it returns a pointer to the destination area to the caller in pointer <parameter>p</parameter>. The caller should subsequently write the - array contents to this memory. Modifications of the memory + array contents to this memory. Modifications to the memory pointed to should only occur until the next operation on the bus - message is invoked, most imporantly the memory should not be + message is invoked. Most importantly, the memory should not be altered anymore when another field has been added to the message or the message has been sealed.</para> </refsect1> @@ -182,7 +182,7 @@ <title>Return Value</title> <para>On success, these calls return 0 or a positive integer. On - failure, they returns a negative errno-style error code.</para> + failure, they return a negative errno-style error code.</para> </refsect1> <xi:include href="sd_bus_message_append_basic.xml" xpointer="errors" /> diff --git a/man/sd_bus_message_get_monotonic_usec.xml b/man/sd_bus_message_get_monotonic_usec.xml index 4c2c06e903..2c0a8a5d54 100644 --- a/man/sd_bus_message_get_monotonic_usec.xml +++ b/man/sd_bus_message_get_monotonic_usec.xml @@ -83,7 +83,7 @@ <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> for details.</para> - <para>Similar, + <para>Similarly, <function>sd_bus_message_get_realtime_usec()</function> returns the realtime (wallclock) timestamp of the time the message was sent. This value is in microseconds since Jan 1st, 1970, i.e. in diff --git a/man/sd_bus_message_read_basic.xml b/man/sd_bus_message_read_basic.xml new file mode 100644 index 0000000000..6a46403159 --- /dev/null +++ b/man/sd_bus_message_read_basic.xml @@ -0,0 +1,113 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2016 Julian Orth + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_bus_message_read_basic"> + + <refentryinfo> + <title>sd_bus_message_read_basic</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <firstname>Julian</firstname> + <surname>Orth</surname> + <email>ju.orth@gmail.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_message_read_basic</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_message_read_basic</refname> + + <refpurpose>Read a basic type from a message</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_message_read_basic</function></funcdef> + <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> + <paramdef>char <parameter>type</parameter></paramdef> + <paramdef>void *<parameter>p</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <function>sd_bus_message_read_basic()</function> reads a basic type from a + message and advances the read position in the message. The set of basic + types and their ascii codes passed in <parameter>type</parameter> are + described in the <ulink + url="https://dbus.freedesktop.org/doc/dbus-specification.html">D-Bus + Specification</ulink>. + </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. + </para> + + <para> + If there is no object of the specified type at the current position in the + message, an error is returned. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para> + On success, <function>sd_bus_message_read_basic()</function> returns 0 or + a positive integer. On failure, it returns a negative errno-style error + code. + </para> + </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_negotiate_fds.xml b/man/sd_bus_negotiate_fds.xml index 1be44e2785..1501e1427d 100644 --- a/man/sd_bus_negotiate_fds.xml +++ b/man/sd_bus_negotiate_fds.xml @@ -99,51 +99,37 @@ setting as negotiated by the program ultimately activated. By default, file descriptor passing is enabled for both.</para> - <para><function>sd_bus_negotiate_timestamps()</function> controls - whether implicit sender timestamps shall be attached automatically - to all incoming messages. Takes a bus object and a boolean, which, - when true, enables timestamping, and, when false, disables it. - Use + <para><function>sd_bus_negotiate_timestamp()</function> controls whether implicit sender + timestamps shall be attached automatically to all incoming messages. Takes a bus object and a + boolean, which, when true, enables timestamping, and, when false, disables it. Use <citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_get_seqnum</refentrytitle><manvolnum>3</manvolnum></citerefentry> - to query the timestamps of incoming messages. If negotiation is - disabled or not supported these calls will fail with - <constant>-ENODATA</constant>. Note that not all transports - support timestamping of messages. Specifically, timestamping is - only available on the kdbus transport, but not on dbus1. The - timestamping is applied by the kernel and cannot be manipulated by - userspace. By default, message timestamping is not negotiated for + to query the timestamps of incoming messages. If negotiation is disabled or not supported, these + calls will fail with <constant>-ENODATA</constant>. Note that currently no transports support + timestamping of messages. By default, message timestamping is not negotiated for connections.</para> - <para><function>sd_bus_negotiate_creds()</function> controls - whether and which implicit sender credentials shall be attached - automatically to all incoming messages. Takes a bus object, a - boolean indicating whether to enable or disable the credential - parts encoded in the bit mask value argument. Note that not all - transports support attaching sender credentials to messages, or do - not support all types of sender credential parameters, or might - suppress them under certain circumstances for individual - messages. Specifically, implicit sender credentials on messages - are only fully supported on kdbus transports, and dbus1 only - supports <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>. The sender - credentials are attached by the kernel and cannot be manipulated - by userspace, and are thus suitable for authorization - decisions. By default, only - <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant> and - <constant>SD_BUS_CREDS_UNIQUE_NAME</constant> are enabled. In - fact, these two credential fields are always sent along and cannot - be turned off.</para> + <para><function>sd_bus_negotiate_creds()</function> controls whether and which implicit sender + credentials shall be attached automatically to all incoming messages. Takes a bus object and a + boolean indicating whether to enable or disable the credential parts encoded in the bit mask + value argument. Note that not all transports support attaching sender credentials to messages, + or do not support all types of sender credential parameters, or might suppress them under + certain circumstances for individual messages. Specifically, dbus1 only supports + <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>. The sender credentials are suitable for + authorization decisions. By default, only <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant> and + <constant>SD_BUS_CREDS_UNIQUE_NAME</constant> are enabled. In fact, these two credential fields + are always sent along and cannot be turned off.</para> <para>The <function>sd_bus_negotiate_fds()</function> function may be called only before the connection has been started with <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Both <function>sd_bus_negotiate_timestamp()</function> and <function>sd_bus_negotiate_creds()</function> may also be called - after a connection has been set up. Note that when operating on a + after a connection has been set up. Note that, when operating on a connection that is shared between multiple components of the same program (for example via - <citerefentry><refentrytitle>sd_bus_default</refentrytitle><manvolnum>3</manvolnum></citerefentry>) + <citerefentry><refentrytitle>sd_bus_default</refentrytitle><manvolnum>3</manvolnum></citerefentry>), it is highly recommended to only enable additional per message metadata fields, but never disable them again, in order not to disable functionality needed by other components.</para> @@ -152,7 +138,7 @@ <refsect1> <title>Return Value</title> - <para>On success, these functions returns 0 or a + <para>On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style error code.</para> </refsect1> diff --git a/man/sd_bus_new.xml b/man/sd_bus_new.xml index aff2ed2e83..d281b5dd44 100644 --- a/man/sd_bus_new.xml +++ b/man/sd_bus_new.xml @@ -46,6 +46,7 @@ <refname>sd_bus_new</refname> <refname>sd_bus_ref</refname> <refname>sd_bus_unref</refname> + <refname>sd_bus_unrefp</refname> <refpurpose>Create a new bus object and create or destroy references to it</refpurpose> </refnamediv> @@ -68,6 +69,11 @@ <funcdef>sd_bus *<function>sd_bus_unref</function></funcdef> <paramdef>sd_bus *<parameter>bus</parameter></paramdef> </funcprototype> + + <funcprototype> + <funcdef>void <function>sd_bus_unrefp</function></funcdef> + <paramdef>sd_bus **<parameter>bus</parameter></paramdef> + </funcprototype> </funcsynopsis> </refsynopsisdiv> @@ -84,7 +90,7 @@ or a related call, and then start the connection with <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - <para>In most cases it's a better idea to invoke + <para>In most cases, it is a better idea to invoke <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry> or related calls instead of the more low-level @@ -93,14 +99,40 @@ only allocate a bus object but also start the connection to a well-known bus in a single function invocation.</para> - <para><function>sd_bus_ref()</function> creates a new reference to - <parameter>bus</parameter>.</para> + <para><function>sd_bus_ref()</function> increases the reference + counter of <parameter>bus</parameter> by one.</para> - <para><function>sd_bus_unref()</function> destroys a reference to - <parameter>bus</parameter>. Once the reference count has dropped - to zero, <parameter>bus</parameter> cannot be used anymore, so - further calls to <function>sd_bus_ref()</function> or + <para><function>sd_bus_unref()</function> decreases the reference + counter of <parameter>bus</parameter> by one. Once the reference + count has dropped to zero, <parameter>bus</parameter> is destroyed + and cannot be used anymore, so further calls to + <function>sd_bus_ref()</function> or <function>sd_bus_unref()</function> are illegal.</para> + + <para><function>sd_bus_unrefp()</function> is similar to + <function>sd_bus_unref()</function> but takes a pointer to a + pointer to an <type>sd_bus</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>. Note that this function is defined as + inline function. Use a declaration like the following, in order to + allocate a bus object that is freed automatically as the code + 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)); + … +}</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> </refsect1> <refsect1> @@ -110,10 +142,10 @@ positive integer. On failure, it returns a negative errno-style error code.</para> - <para><function>sd_bus_ref</function> always returns the argument. + <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> always returns <constant>NULL</constant>.</para> </refsect1> diff --git a/man/sd_bus_path_encode.xml b/man/sd_bus_path_encode.xml index 21c22a8f7c..3088243e45 100644 --- a/man/sd_bus_path_encode.xml +++ b/man/sd_bus_path_encode.xml @@ -44,7 +44,9 @@ <refnamediv> <refname>sd_bus_path_encode</refname> + <refname>sd_bus_path_encode_many</refname> <refname>sd_bus_path_decode</refname> + <refname>sd_bus_path_decode_many</refname> <refpurpose>Convert an external identifier into an object path and back</refpurpose> </refnamediv> @@ -61,11 +63,25 @@ </funcprototype> <funcprototype> + <funcdef>int <function>sd_bus_path_encode_many</function></funcdef> + <paramdef>char **<parameter>out</parameter></paramdef> + <paramdef>const char *<parameter>path_template</parameter></paramdef> + <paramdef>...</paramdef> + </funcprototype> + + <funcprototype> <funcdef>int <function>sd_bus_path_decode</function></funcdef> <paramdef>const char *<parameter>path</parameter></paramdef> <paramdef>const char *<parameter>prefix</parameter></paramdef> <paramdef>char **<parameter>ret_external_id</parameter></paramdef> </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_path_decode_many</function></funcdef> + <paramdef>const char *<parameter>path</parameter></paramdef> + <paramdef>const char *<parameter>path_template</parameter></paramdef> + <paramdef>...</paramdef> + </funcprototype> </funcsynopsis> </refsynopsisdiv> @@ -109,6 +125,28 @@ invalid in a bus object path by <literal>_</literal>, followed by a hexadecimal value. As a special case, the empty string will be replaced by a lone <literal>_</literal>.</para> + + <para><function>sd_bus_path_encode_many()</function> works like + its counterpart <function>sd_bus_path_encode()</function>, but + takes a path template as argument and encodes multiple labels + according to its embedded directives. For each + <literal>%</literal> character found in the template, the caller + must provide a string via varargs, which will be encoded and + embedded at the position of the <literal>%</literal> character. + Any other character in the template is copied verbatim into the + encoded path.</para> + + <para><function>sd_bus_path_decode_many()</function> does the + reverse of <function>sd_bus_path_encode_many()</function>. It + decodes the passed object path according to the given + path template. For each <literal>%</literal> character in the + template, the caller must provide an output storage + (<literal>char **</literal>) via varargs. The decoded label + will be stored there. Each <literal>%</literal> character will + only match the current label. It will never match across labels. + Furthermore, only a single directive is allowed per label. + If <literal>NULL</literal> is passed as output storage, the + label is verified but not returned to the caller.</para> </refsect1> <refsect1> diff --git a/man/sd_bus_process.xml b/man/sd_bus_process.xml new file mode 100644 index 0000000000..4b9f52e52f --- /dev/null +++ b/man/sd_bus_process.xml @@ -0,0 +1,111 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2016 Julian Orth + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_bus_process"> + + <refentryinfo> + <title>sd_bus_process</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <firstname>Julian</firstname> + <surname>Orth</surname> + <email>ju.orth@gmail.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_process</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_process</refname> + + <refpurpose>Drive the connection</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_process</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>sd_bus_message **<parameter>r</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <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> + + <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> + </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> + </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_track_add_name.xml b/man/sd_bus_track_add_name.xml new file mode 100644 index 0000000000..6a5e344cb1 --- /dev/null +++ b/man/sd_bus_track_add_name.xml @@ -0,0 +1,261 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2016 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_bus_track_add_name"> + + <refentryinfo> + <title>sd_bus_track_add_name</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_track_add_name</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_track_add_name</refname> + <refname>sd_bus_track_add_sender</refname> + <refname>sd_bus_track_remove_name</refname> + <refname>sd_bus_track_remove_sender</refname> + <refname>sd_bus_track_count</refname> + <refname>sd_bus_track_count_sender</refname> + <refname>sd_bus_track_count_name</refname> + <refname>sd_bus_track_contains</refname> + <refname>sd_bus_track_first</refname> + <refname>sd_bus_track_next</refname> + + <refpurpose>Add, remove and retrieve bus peers tracked in a bus peer tracking object</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_track_add_name</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + <paramdef>const char* <parameter>name</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_add_sender</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + <paramdef>sd_bus_message* <parameter>message</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_remove_name</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + <paramdef>const char* <parameter>name</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_remove_sender</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + <paramdef>sd_bus_message* <parameter>message</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>unsigned <function>sd_bus_track_count</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_count_name</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + <paramdef>const char* <parameter>name</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_count_sender</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + <paramdef>sd_bus_message* <parameter>message</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_contains</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + <paramdef>const char* <parameter>name</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>const char* <function>sd_bus_track_first</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>const char* <function>sd_bus_track_next</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_track_add_name()</function> adds a peer to track to a bus peer tracking object. The first + argument should refer to a bus peer tracking object created with + <citerefentry><refentrytitle>sd_bus_track_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, the second + name should refer to a D-Bus peer name to track, either in unique or well-known service format. If the name is not + tracked yet it will be added to the list of names to track. If it already is being tracked and non-recursive mode + is enabled, no operation is executed by this call. If recursive mode is enabled a per-name counter is increased by + one each time this call is invoked, and <function>sd_bus_track_remove_name()</function> has to be called as many + times as <function>sd_bus_track_add_name()</function> was invoked before in order to stop tracking of the name. Use + <citerefentry><refentrytitle>sd_bus_track_set_recursive</refentrytitle><manvolnum>3</manvolnum></citerefentry> to + switch from the default non-recursive mode to recursive mode, or back. Note that the specified name is tracked as + it is, well-known names are not resolved to unique names by this call. Note that multiple bus peer tracking objects + may track the same name.</para> + + <para><function>sd_bus_track_remove_name()</function> undoes the effect of + <function>sd_bus_track_add_name()</function> and removes a bus peer name from the list of peers to watch. Depending + on whether non-recursive or recursive mode is enabled for the bus peer tracking object this call will either remove + the name fully from the tracking object, or will simply decrement the per-name counter by one, removing the name + only when the counter reaches zero (see above). Note that a bus peer disconnecting from the bus will implicitly + remove its names fully from the bus peer tracking object, regardless of the current per-name counter.</para> + + <para><function>sd_bus_track_add_sender()</function> and <function>sd_bus_track_remove_sender()</function> are + similar to <function>sd_bus_track_add_name()</function> and <function>sd_bus_track_remove_name()</function> but + take a bus message as argument. The sender of this bus message is determined and added to/removed from the bus peer + tracking object. As messages always originate from unique names, and never from well-known names this means that + this call will effectively only add unique names to the bus peer tracking object.</para> + + <para><function>sd_bus_track_count()</function> returns the number of names currently being tracked by the + specified bus peer tracking object. Note that this function always returns the actual number of names tracked, and + hence if <function>sd_bus_track_add_name()</function> has been invoked multiple times for the same name it is only + counted as one, regardless if recursive mode is used or not.</para> + + <para><function>sd_bus_track_count_name()</function> returns the current per-name counter for the specified + name. If non-recursive mode is used this returns either 1 or 0, depending on whether the specified name has been + added to the tracking object before, or not. If recursive mode has been enabled, values larger than 1 may be + returned too, in case <function>sd_bus_track_add_name()</function> has been called multiple times for the same + name.</para> + + <para><function>sd_bus_track_count_sender()</function> is similar to + <function>sd_bus_track_count_name()</function>, but takes a bus message object and returns the per-name counter + matching the sender of the message.</para> + + <para><function>sd_bus_track_contains()</function> may be used to determine whether the specified name has been + added at least once to the specified bus peer tracking object.</para> + + <para><function>sd_bus_track_first()</function> and <function>sd_bus_track_next()</function> may be used to + enumerate all names currently being tracked by the passed bus peer tracking + object. <function>sd_bus_track_first()</function> returns the first entry in the object, and resets an internally + maintained read index. Each subsequent invocation of <function>sd_bus_track_next()</function> returns the next name + contained in the bus object. If the end is reached <constant>NULL</constant> is returned. If no names have been + added to the object yet <function>sd_bus_track_first()</function> will return <constant>NULL</constant> + immediately. The order in which names are returned is undefined; in particular which name is considered the first + returned is not defined. If recursive mode is enabled and the same name has been added multiple times to the bus + peer tracking object it is only returned once by this enumeration. If new names are added to or existing names + removed from the bus peer tracking object while it is being enumerated the enumeration ends on the next invocation + of <function>sd_bus_track_next()</function> as <constant>NULL</constant> is returned.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>sd_bus_track_add_name()</function> and <function>sd_bus_track_add_sender()</function> + return 0 if the specified name has already been added to the bus peer tracking object before and positive if it + hasn't. On failure, they return a negative errno-style error code.</para> + + <para><function>sd_bus_track_remove_name()</function> and <function>sd_bus_track_remove_sender()</function> return + positive if the specified name was previously tracked by the bus peer tracking object and has now been removed. In + non-recursive mode, 0 is returned if the specified name was not being tracked yet. In recursive mode + <constant>-EUNATCH</constant> is returned in this case. On failure, they return a negative errno-style error + code.</para> + + <para><function>sd_bus_track_count()</function> returns the number of names currently being tracked, or 0 on + failure.</para> + + <para><function>sd_bus_track_count_name()</function> and <function>sd_bus_track_count_sender()</function> return + the current per-name counter for the specified name or the sender of the specified message. Zero is returned for + names that are not being tracked yet, a positive value for names added at least once. Larger values than 1 are only + returned in recursive mode. On failure, a negative errno-style error code is returned.</para> + + <para><function>sd_bus_track_contains()</function> returns the passed name if it exists in the bus peer tracking + object. On failure, and if the name has not been added yet <constant>NULL</constant> is returned.</para> + + <para><function>sd_bus_track_first()</function> and <function>sd_bus_track_next()</function> return the first/next + name contained in the bus peer tracking object, and <constant>NULL</constant> if the end of the enumeration is + reached and on error.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + + <varlistentry> + <term><constant>-EUNATCH</constant></term> + + <listitem><para><function>sd_bus_track_remove_name()</function> or + <function>sd_bus_track_remove_sender()</function> have been invoked for a name not previously added to the bus + peer object.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>Specified parameter is invalid.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para><function>sd_bus_track_add_name()</function> and the other calls 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> + + <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_track_new</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_track_new.xml b/man/sd_bus_track_new.xml new file mode 100644 index 0000000000..60e2e77f75 --- /dev/null +++ b/man/sd_bus_track_new.xml @@ -0,0 +1,263 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2016 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_bus_track_new"> + + <refentryinfo> + <title>sd_bus_track_new</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_track_new</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_track_new</refname> + <refname>sd_bus_track_ref</refname> + <refname>sd_bus_track_unref</refname> + <refname>sd_bus_track_unrefp</refname> + <refname>sd_bus_track_set_recursive</refname> + <refname>sd_bus_track_get_recursive</refname> + <refname>sd_bus_track_get_bus</refname> + <refname>sd_bus_track_get_userdata</refname> + <refname>sd_bus_track_set_userdata</refname> + + <refpurpose>Track bus peers</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_track_new</function></funcdef> + <paramdef>sd_bus* <parameter>bus</parameter></paramdef> + <paramdef>sd_bus_track** <parameter>ret</parameter></paramdef> + <paramdef>sd_bus_track_handler_t <parameter>handler</parameter></paramdef> + <paramdef>void* <parameter>userdata</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_bus_track *<function>sd_bus_track_ref</function></funcdef> + <paramdef>sd_bus_track *<parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_bus_track *<function>sd_bus_track_unref</function></funcdef> + <paramdef>sd_bus_track *<parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void <function>sd_bus_track_unrefp</function></funcdef> + <paramdef>sd_bus_track **<parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_get_recursive</function></funcdef> + <paramdef>sd_bus_track *<parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_set_recursive</function></funcdef> + <paramdef>sd_bus_track *<parameter>t</parameter></paramdef> + <paramdef>int <parameter>b</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_bus* <function>sd_bus_track_get_bus</function></funcdef> + <paramdef>sd_bus_track *<parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void* <function>sd_bus_track_get_userdata</function></funcdef> + <paramdef>sd_bus_track *<parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void* <function>sd_bus_track_set_userdata</function></funcdef> + <paramdef>sd_bus_track *<parameter>t</parameter></paramdef> + <paramdef>void *userdata</paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_track_new()</function> creates a new bus peer tracking object. The object is allocated for + the specified bus, and returned in the <parameter>*ret</parameter> parameter. After use, the object should be freed + again by dropping the acquired reference with <function>sd_bus_track_unref()</function> (see below). A bus peer + tracking object may be used to keep track of peers on a specific IPC bus, for cases where peers are making use of + one or more local objects, in order to control the lifecycle of the local objects and ensure they stay around as + long as the peers needing them are around, and unreferenced (and possibly destroyed) as soon as all relevant peers + have vanished. Each bus peer tracking object may be used to track zero, one or more peers add a time. References to + specific bus peers are added via + <citerefentry><refentrytitle>sd_bus_track_add_name</refentrytitle><manvolnum>3</manvolnum></citerefentry> or + <function>sd_bus_track_add_sender()</function>. They may be dropped again via + <function>sd_bus_track_remove_name()</function> and + <function>sd_bus_track_remove_sender()</function>. Alternatively, references on peers are removed automatically + when they disconnect from the bus. If non-NULL the <parameter>handler</parameter> may specify a function that is + invoked whenever the last reference is dropped, regardless whether the reference is dropped explicitly via + <function>sd_bus_track_remove_name()</function> or implicitly because the peer disconnected from the bus. The final + argument <parameter>userdata</parameter> may be used to attach a generic user data pointer to the object. This + pointer is passed to the handler callback when it is invoked.</para> + + <para><function>sd_bus_track_ref()</function> creates a new reference to a bus peer tracking object. This object + will not be destroyed until <function>sd_bus_track_unref()</function> has been called as many times plus once + more. Once the reference count has dropped to zero, the specified object cannot be used anymore, further calls to + <function>sd_bus_track_ref()</function> or <function>sd_bus_track_unref()</function> on the same object are + illegal.</para> + + <para><function>sd_bus_track_unref()</function> destroys a reference to a bus peer tracking object.</para> + + <para><function>sd_bus_track_unrefp()</function> is similar to <function>sd_bus_track_unref()</function> but takes + a pointer to a pointer to an <type>sd_bus_track</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>. Note that this function is defined as inline function.</para> + + <para><function>sd_bus_track_ref()</function>, <function>sd_bus_track_unref()</function> and + <function>sd_bus_track_unrefp()</function> execute no operation if the passed in bus peer tracking object is + <constant>NULL</constant>.</para> + + <para>Bus peer tracking objects may exist in two modes: by default they operate in non-recursive mode, but may + optionally be switched into recursive mode. If operating in the default non-recursive mode a peer is either tracked + or not tracked. In this mode invoking <function>sd_bus_track_add_name()</function> multiple times in a row for the + same peer is fully equivalent to calling it just once, as the call adds the peer to the set of tracked peers if + necessary, and executes no operation if the peer is already being tracked. A single invocation of + <function>sd_bus_track_remove_name()</function> removes the reference on the peer again, regardless how many times + <function>sd_bus_track_add_name()</function> was called before. If operating in recursive mode, the number of times + <function>sd_bus_track_add_name()</function> is invoked for the same peer name is counted and + <function>sd_bus_track_remove_name()</function> must be called the same number of times before the peer is not + tracked anymore, with the exception when the tracked peer vanishes from the bus, in which case the count is + irrelevant and the tracking of the specific peer is immediately + removed. <function>sd_bus_track_get_recursive()</function> may be used to determine whether the bus peer tracking + object is operating in recursive mode. <function>sd_bus_track_set_recursive()</function> may be used to enable or + disable recursive mode. By default a bus peer tracking object operates in non-recursive mode, and + <function>sd_bus_track_get_recursive()</function> for a newly allocated object hence returns a value equal to + zero. Use <function>sd_bus_track_set_recursive()</function> to enable recursive mode, right after allocation. It + takes a boolean argument to enable or disable recursive mode. Note that tracking objects for which + <function>sd_bus_track_add_name()</function> was already invoked at least once (and which hence track already one + or more peers) may not be switched from recursive to non-recursive mode anymore.</para> + + <para><function>sd_bus_track_get_bus()</function> returns the bus object the bus peer tracking object belongs + to. It returns the bus object initially passed to <function>sd_bus_track_new()</function> when the object was + allocated.</para> + + <para><function>sd_bus_track_get_userdata()</function> returns the generic user data pointer set on the bus peer + tracking object at the time of creation using <function>sd_bus_track_new()</function> or at a later time, using + <function>sd_bus_track_set_userdata()</function>.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>sd_bus_track_new()</function> and <function>sd_bus_track_set_recursive()</function> + return 0 or a positive integer. On failure, they return a negative errno-style error code.</para> + + <para><function>sd_bus_track_ref()</function> always returns the argument.</para> + + <para><function>sd_bus_track_unref()</function> always returns <constant>NULL</constant>.</para> + + <para><function>sd_bus_track_get_recursive()</function> returns 0 if non-recursive mode is selected (default), and + greater than 0 if recursive mode is selected. On failure a negative errno-style error code is returned.</para> + + <para><function>sd_bus_track_get_bus()</function> returns the bus object associated to the bus peer tracking + object.</para> + + <para><function>sd_bus_track_get_userdata()</function> returns the generic user data pointer associated with the + bus peer tracking object. <function>sd_bus_track_set_userdata()</function> returns the previous user data pointer + set.</para> + + </refsect1> + + <refsect1> + <title>Reference ownership</title> + + <para>The <function>sd_bus_track_new()</function> function creates a new object and the caller owns the sole + reference. When not needed anymore, this reference should be destroyed with + <function>sd_bus_track_unref()</function>. + </para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + + <varlistentry> + <term><constant>-EBUSY</constant></term> + + <listitem><para>Bus peers have already been added to the bus peer tracking object and + <function>sd_bus_track_set_recursive()</function> was called to change tracking mode.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>Specified parameter is invalid + (<constant>NULL</constant> in case of output + parameters).</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para><function>sd_bus_track_new()</function> and the other calls 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> + + <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_track_add_name</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 b62d1ee5e1..bc732db7fa 100644 --- a/man/sd_event_add_child.xml +++ b/man/sd_event_add_child.xml @@ -21,7 +21,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>. --> -<refentry id="sd_event_add_child"> +<refentry id="sd_event_add_child" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_event_add_child</title> @@ -45,13 +45,23 @@ <refnamediv> <refname>sd_event_add_child</refname> <refname>sd_event_source_get_child_pid</refname> + <refname>sd_event_child_handler_t</refname> - <refpurpose>Add a child state change event source to an event loop</refpurpose> + <refpurpose>Add a child process state change event source to an event loop</refpurpose> </refnamediv> <refsynopsisdiv> <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> + + <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo> + + <funcprototype> + <funcdef>typedef int (*<function>sd_event_child_handler_t</function>)</funcdef> + <paramdef>sd_event_source *<parameter>s</parameter></paramdef> + <paramdef>const siginfo_t *<parameter>si</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + </funcprototype> <funcprototype> <funcdef>int <function>sd_event_add_child</function></funcdef> @@ -64,13 +74,6 @@ </funcprototype> <funcprototype> - <funcdef>typedef int (*<function>sd_event_child_handler_t</function>)</funcdef> - <paramdef>sd_event_source *<parameter>s</parameter></paramdef> - <paramdef>const siginfo_t *<parameter>si</parameter></paramdef> - <paramdef>void *<parameter>userdata</parameter></paramdef> - </funcprototype> - - <funcprototype> <funcdef>int <function>sd_event_source_get_child_pid</function></funcdef> <paramdef>sd_event_source *<parameter>source</parameter></paramdef> <paramdef>pid_t *<parameter>pid</parameter></paramdef> @@ -83,42 +86,75 @@ <title>Description</title> <para><function>sd_event_add_child()</function> adds a new child - state change event source to an event loop object. The event loop - is specified in <parameter>event</parameter>, the event source is - returned in the <parameter>source</parameter> parameter. The - <parameter>pid</parameter> parameter specifies the process to - watch. The <parameter>handler</parameter> must reference a - function to call when the process changes state. The handler - function will be passed the <parameter>userdata</parameter> - pointer, which may be chosen freely by the caller. The handler - also receives a pointer to a <structname>const - siginfo_t</structname> structure containing the information about - the event. The <parameter>options</parameter> parameter determines - which state changes will be watched for. It must contain an OR-ed - mask of <constant>WEXITED</constant> (watch for the child + process state change event source to an event loop. The event loop + object is specified in the <parameter>event</parameter> parameter, + the event source object is returned in the + <parameter>source</parameter> parameter. The + <parameter>pid</parameter> parameter specifies the PID of the + process to watch. The <parameter>handler</parameter> must + reference a function to call when the process changes state. The + handler function will be passed the + <parameter>userdata</parameter> pointer, which may be chosen + freely by the caller. The handler also receives a pointer to a + <structname>siginfo_t</structname> structure containing + information about the child process event. The + <parameter>options</parameter> parameter determines which state + changes will be watched for. It must contain an OR-ed mask of + <constant>WEXITED</constant> (watch for the child process terminating), <constant>WSTOPPED</constant> (watch for the child - being stopped by a signal), and <constant>WCONTINUED</constant> - (watch for the child being resumed by a signal). See - <citerefentry><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry> + process being stopped by a signal), and + <constant>WCONTINUED</constant> (watch for the child process being + resumed by a signal). See <citerefentry + project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry> for further information.</para> <para>Only a single handler may be installed for a specific - child. The handler is enabled - for a single event (<constant>SD_EVENT_ONESHOT</constant>), - but this may be - changed with + child process. The handler is enabled for a single event + (<constant>SD_EVENT_ONESHOT</constant>), but this may be changed + with <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If the handler function returns a negative error code, it will be - disabled after the invocation, even if - <constant>SD_EVENT_ON</constant> mode is set. + disabled after the invocation, even if the + <constant>SD_EVENT_ON</constant> mode was requested before. </para> + <para>To destroy an event source object use + <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + but note that the event source is only removed from the event loop + when all references to the event source are dropped. To make sure + an event source does not fire anymore, even when there's still a + reference to it kept, consider setting the event source to + <constant>SD_EVENT_OFF</constant> with + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + + <para>If the second parameter of + <function>sd_event_add_child()</function> is passed as NULL no + reference to the event source object is returned. In this case the + event source is considered "floating", and will be destroyed + implicitly when the event loop itself is destroyed.</para> + + <para>Note that the <parameter>handler</parameter> function is + invoked at a time where the child process is not reaped yet (and + thus still is exposed as a zombie process by the kernel). However, + the child will be reaped automatically after the function + returns. Child processes for which no child process state change + event sources are installed will not be reaped by the event loop + implementation.</para> + + <para>If both a child process state change event source and a + <constant>SIGCHLD</constant> signal event source is installed in + the same event loop, the configured event source priorities decide + which event source is dispatched first. If the signal handler is + processed first, it should leave the child processes for which + child process state change event sources are installed unreaped.</para> + <para><function>sd_event_source_get_child_pid()</function> - retrieves the configured <parameter>pid</parameter> of a child - state change event source created previously with + retrieves the configured PID of a child process state change event + source created previously with <function>sd_event_add_child()</function>. It takes the event source object as the <parameter>source</parameter> parameter and a - pointer to <type>pid_t</type> to return the result in. + pointer to a <type>pid_t</type> variable to return the process ID + in. </para> </refsect1> @@ -157,8 +193,8 @@ <varlistentry> <term><constant>-EBUSY</constant></term> - <listitem><para>An handler is already installed for this - child.</para></listitem> + <listitem><para>A handler is already installed for this + child process.</para></listitem> </varlistentry> @@ -176,19 +212,17 @@ </varlistentry> - </variablelist> - </refsect1> + <varlistentry> + <term><constant>-EDOM</constant></term> - <refsect1> - <title>Notes</title> + <listitem><para>The passed event source is not a child process event source.</para></listitem> + </varlistentry> - <para><function>sd_event_add_child()</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> + </variablelist> </refsect1> + <xi:include href="libsystemd-pkgconfig.xml" /> + <refsect1> <title>See Also</title> @@ -196,10 +230,16 @@ <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_now</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_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_enabled</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>, + <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 project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/sd_event_add_defer.xml b/man/sd_event_add_defer.xml index 01504bf01e..d9ebd3b179 100644 --- a/man/sd_event_add_defer.xml +++ b/man/sd_event_add_defer.xml @@ -21,7 +21,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>. --> -<refentry id="sd_event_add_defer"> +<refentry id="sd_event_add_defer" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_event_add_defer</title> @@ -46,13 +46,22 @@ <refname>sd_event_add_defer</refname> <refname>sd_event_add_post</refname> <refname>sd_event_add_exit</refname> + <refname>sd_event_handler_t</refname> <refpurpose>Add static event sources to an event loop</refpurpose> </refnamediv> <refsynopsisdiv> <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> + + <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo> + + <funcprototype> + <funcdef>typedef int (*<function>sd_event_handler_t</function>)</funcdef> + <paramdef>sd_event_source *<parameter>s</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + </funcprototype> <funcprototype> <funcdef>int <function>sd_event_add_defer</function></funcdef> @@ -78,49 +87,67 @@ <paramdef>void *<parameter>userdata</parameter></paramdef> </funcprototype> - <funcprototype> - <funcdef>typedef int (*<function>sd_event_handler_t</function>)</funcdef> - <paramdef>sd_event_source *<parameter>s</parameter></paramdef> - <paramdef>void *<parameter>userdata</parameter></paramdef> - </funcprototype> - </funcsynopsis> </refsynopsisdiv> <refsect1> <title>Description</title> - <para>Those three functions add new event sources to an event loop - object. The event loop is specified in - <parameter>event</parameter>, the event source is returned in the - <parameter>source</parameter> parameter. The event sources are - enabled statically and will "fire" when the event loop is run and - the conditions described below are met. The handler function will - be passed the <parameter>userdata</parameter> pointer, which may - be chosen freely by the caller.</para> + <para>These three functions add new static event sources to an + event loop. The event loop object is specified in the + <parameter>event</parameter> parameter, the event source object is + returned in the <parameter>source</parameter> parameter. The event + sources are enabled statically and will "fire" when the event loop + is run and the conditions described below are met. The handler + function will be passed the <parameter>userdata</parameter> + pointer, which may be chosen freely by the caller.</para> <para><function>sd_event_add_defer()</function> adds a new event - source that will "fire" the next time the event loop is run. By - default, the handler will be called once - (<constant>SD_EVENT_ONESHOT</constant>).</para> + source that will be dispatched instantly, before the event loop + goes to sleep again and waits for new events. By default, the + handler will be called once + (<constant>SD_EVENT_ONESHOT</constant>). Note that if the event + source is set to <constant>SD_EVENT_ON</constant> the event loop + will never go to sleep again, but continuously call the handler, + possibly interleaved with other event sources.</para> <para><function>sd_event_add_post()</function> adds a new event - source that will "fire" if any event handlers are invoked whenever - the event loop is run. By default, the source is enabled - permanently (<constant>SD_EVENT_ON</constant>).</para> + source that is run before the event loop will sleep and wait + for new events, but only after at least one other non-post event + source was dispatched. By default, the source is enabled + permanently (<constant>SD_EVENT_ON</constant>). Note that this + event source type will still allow the event loop to go to sleep + again, even if set to <constant>SD_EVENT_ON</constant>, as long as + no other event source is ever triggered.</para> <para><function>sd_event_add_exit()</function> adds a new event - source that will "fire" when the event loop is terminated - with <function>sd_event_exit()</function>.</para> + source that will be dispatched when the event loop is terminated + with <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> <para>The <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> function may be used to enable the event source permanently (<constant>SD_EVENT_ON</constant>) or to make it fire just once - (<constant>SD_EVENT_ONESHOT</constant>). If the handler function - returns a negative error code, it will be disabled after the - invocation, even if <constant>SD_EVENT_ON</constant> mode is - set.</para> + (<constant>SD_EVENT_ONESHOT</constant>).</para> + + <para>If the handler function returns a negative error code, it + will be disabled after the invocation, even if the + <constant>SD_EVENT_ON</constant> mode was requested before.</para> + + <para>To destroy an event source object use + <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + but note that the event source is only removed from the event loop + when all references to the event source are dropped. To make sure + an event source does not fire anymore, even when there's still a + reference to it kept, consider setting the event source to + <constant>SD_EVENT_OFF</constant> with + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + + <para>If the second parameter of these functions is passed as + NULL no reference to the event source object is returned. In this + case the event source is considered "floating", and will be + destroyed implicitly when the event loop itself is + destroyed.</para> </refsect1> <refsect1> @@ -164,15 +191,7 @@ </variablelist> </refsect1> - <refsect1> - <title>Notes</title> - - <para>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> - </refsect1> + <xi:include href="libsystemd-pkgconfig.xml" /> <refsect1> <title>See Also</title> @@ -181,10 +200,16 @@ <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_now</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_source_set_enabled</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>, + <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_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/sd_event_add_io.xml b/man/sd_event_add_io.xml new file mode 100644 index 0000000000..c3749164cd --- /dev/null +++ b/man/sd_event_add_io.xml @@ -0,0 +1,300 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2015 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_event_add_io" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_event_add_io</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_event_add_io</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_event_add_io</refname> + <refname>sd_event_source_get_io_events</refname> + <refname>sd_event_source_set_io_events</refname> + <refname>sd_event_source_get_io_revents</refname> + <refname>sd_event_source_get_io_fd</refname> + <refname>sd_event_source_set_io_fd</refname> + <refname>sd_event_source</refname> + <refname>sd_event_io_handler_t</refname> + + <refpurpose>Add an I/O event source to an event loop</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> + + <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo> + + <funcprototype> + <funcdef>typedef int (*<function>sd_event_io_handler_t</function>)</funcdef> + <paramdef>sd_event_source *<parameter>s</parameter></paramdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>uint32_t <parameter>revents</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_add_io</function></funcdef> + <paramdef>sd_event *<parameter>event</parameter></paramdef> + <paramdef>sd_event_source **<parameter>source</parameter></paramdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>uint32_t <parameter>events</parameter></paramdef> + <paramdef>sd_event_io_handler_t <parameter>handler</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_source_get_io_events</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>uint32_t *<parameter>events</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_source_set_io_events</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>uint32_t <parameter>events</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_source_get_io_revents</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>uint32_t *<parameter>revents</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_source_get_io_fd</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_source_set_io_fd</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>int <parameter>fd</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_event_add_io()</function> adds a new I/O event + source to an event loop. The event loop object is specified in the + <parameter>event</parameter> parameter, the event source object is + returned in the <parameter>source</parameter> parameter. The + <parameter>fd</parameter> parameter takes the UNIX file descriptor + to watch, which may refer to a socket, a FIFO, a message queue, a + serial connection, a character device, or any other file descriptor + compatible with Linux + <citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The + <parameter>events</parameter> parameter takes a bit mask of events + to watch for, a combination of the following event flags: + <constant>EPOLLIN</constant>, <constant>EPOLLOUT</constant>, + <constant>EPOLLRDHUP</constant>, <constant>EPOLLPRI</constant>, + and <constant>EPOLLET</constant>, see + <citerefentry project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details. The <parameter>handler</parameter> shall reference a + function to call when the event source is triggered. The + <parameter>userdata</parameter> pointer will be passed to the + handler function, and may be chosen freely by the caller. The + handler will also be passed the file descriptor the event was seen + on, as well as the actual event flags. It's generally a subset of + the events watched, however may additionally include + <constant>EPOLLERR</constant> and <constant>EPOLLHUP</constant>. + </para> + + <para>By default, an event source will stay enabled + continuously (<constant>SD_EVENT_ON</constant>), but this may be + changed with + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + If the handler function returns a negative error code, it will be + disabled after the invocation, even if the + <constant>SD_EVENT_ON</constant> mode was requested before. Note + that an event source set to <constant>SD_EVENT_ON</constant> will + fire continuously unless data is read from or written to the file + descriptor to reset the mask of events seen. + </para> + + <para>Setting the I/O event mask to watch for to 0 does not mean + that the event source won't be triggered anymore, as + <constant>EPOLLHUP</constant> and <constant>EPOLLERR</constant> + may be triggered even with a zero event mask. To temporarily + disable an I/O event source use + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> + with <constant>SD_EVENT_OFF</constant> instead.</para> + + <para>To destroy an event source object use + <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + but note that the event source is only removed from the event loop + when all references to the event source are dropped. To make sure + an event source does not fire anymore, even if it is still referenced, + disable the event source using + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> + with <constant>SD_EVENT_OFF</constant>.</para> + + <para>If the second parameter of + <function>sd_event_add_io()</function> is + <constant>NULL</constant> no reference to the event source object + is returned. In this case the event source is considered + "floating", and will be destroyed implicitly when the event loop + itself is destroyed.</para> + + <para>It is recommended to use + <function>sd_event_add_io()</function> only in conjunction with + file descriptors that have <constant>O_NONBLOCK</constant> set, to + ensure that all I/O operations from invoked handlers are properly + asynchronous and non-blocking. Using file descriptors without + <constant>O_NONBLOCK</constant> might result in unexpected + starvation of other event sources. See + <citerefentry project='man-pages'><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details on enabling <constant>O_NONBLOCK</constant> mode.</para> + + <para><function>sd_event_source_get_io_events()</function> retrieves + the configured mask of watched I/O events of an event source created + previously with <function>sd_event_add_io()</function>. It takes + the event source object and a pointer to a variable to store the + mask in.</para> + + <para><function>sd_event_source_set_io_events()</function> + configures the mask of watched I/O events of an event source created + previously with <function>sd_event_add_io()</function>. It takes the + event source object and the new event mask.</para> + + <para><function>sd_event_source_get_io_revents()</function> + retrieves the I/O event mask of currently seen but undispatched + events from an event source created previously with + <function>sd_event_add_io()</function>. It takes the event source + object and a pointer to a variable to store the event mask + in. When called from a handler function on the handler's event + source object this will return the same mask as passed to the + handler's <parameter>revents</parameter> parameter. This call is + primarily useful to check for undispatched events of an event + source from the handler of an unrelated (possibly higher priority) + event source. Note the relation between + <function>sd_event_source_get_pending()</function> and + <function>sd_event_source_get_io_revents()</function>: both + functions will report non-zero results when there's an event + pending for the event source, but the former applies to all event + source types, the latter only to I/O event sources.</para> + + <para><function>sd_event_source_get_io_fd()</function> retrieves + the UNIX file descriptor of an event source created previously + with <function>sd_event_add_io()</function>. It takes the event + source object and returns the non-negative file descriptor + or a negative error number on error (see below).</para> + + <para><function>sd_event_source_set_io_fd()</function> + changes the UNIX file descriptor of an I/O event source created + previously with <function>sd_event_add_io()</function>. It takes + the event source object and the new file descriptor.</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 values may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Not enough memory to allocate an object.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>An invalid argument has been passed.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><constant>-ESTALE</constant></term> + + <listitem><para>The event loop is already terminated.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><constant>-ECHILD</constant></term> + + <listitem><para>The event loop has been created in a different process.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EDOM</constant></term> + + <listitem><para>The passed event source is not an I/O event source.</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-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_now</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_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>, + <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</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_event_add_signal.xml b/man/sd_event_add_signal.xml index 1d0942b45c..e98f1d2682 100644 --- a/man/sd_event_add_signal.xml +++ b/man/sd_event_add_signal.xml @@ -21,7 +21,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>. --> -<refentry id="sd_event_add_signal"> +<refentry id="sd_event_add_signal" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_event_add_signal</title> @@ -45,13 +45,24 @@ <refnamediv> <refname>sd_event_add_signal</refname> <refname>sd_event_source_get_signal</refname> + <refname>sd_event_signal_handler_t</refname> - <refpurpose>Add a signal event source to an event loop</refpurpose> + <refpurpose>Add a UNIX process signal event source to an event + loop</refpurpose> </refnamediv> <refsynopsisdiv> <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> + + <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo> + + <funcprototype> + <funcdef>typedef int (*<function>sd_event_signal_handler_t</function>)</funcdef> + <paramdef>sd_event_source *<parameter>s</parameter></paramdef> + <paramdef>const struct signalfd_siginfo *<parameter>si</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + </funcprototype> <funcprototype> <funcdef>int <function>sd_event_add_signal</function></funcdef> @@ -63,13 +74,6 @@ </funcprototype> <funcprototype> - <funcdef>typedef int (*<function>sd_event_signal_handler_t</function>)</funcdef> - <paramdef>sd_event_source *<parameter>s</parameter></paramdef> - <paramdef>const struct signalfd_siginfo *<parameter>si</parameter></paramdef> - <paramdef>void *<parameter>userdata</parameter></paramdef> - </funcprototype> - - <funcprototype> <funcdef>int <function>sd_event_source_get_signal</function></funcdef> <paramdef>sd_event_source *<parameter>source</parameter></paramdef> </funcprototype> @@ -80,43 +84,62 @@ <refsect1> <title>Description</title> - <para><function>sd_event_add_signal()</function> adds a new signal - event source to an event loop object. The event loop is specified - in <parameter>event</parameter>, the event source is returned in - the <parameter>source</parameter> parameter. The - <parameter>signal</parameter> parameter specifies the signal to be handled - (see - <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>). - The <parameter>handler</parameter> must reference a function to - call when the signal is delivered or be <constant>NULL</constant>. - The handler function will be passed the - <parameter>userdata</parameter> pointer, which may be chosen + <para><function>sd_event_add_signal()</function> adds a new UNIX + process signal event source to an event loop. The event loop + object is specified in the <parameter>event</parameter> parameter, + and the event source object is returned in the + <parameter>source</parameter> parameter. The + <parameter>signal</parameter> parameter specifies the numeric + signal to be handled (see <citerefentry + project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>). + The <parameter>handler</parameter> parameter must reference a + function to call when the signal is received or be + <constant>NULL</constant>. The handler function will be passed + the <parameter>userdata</parameter> pointer, which may be chosen freely by the caller. The handler also receives a pointer to a - <structname>const struct signalfd_siginfo</structname> containing - the information about the received signal. See - <citerefentry project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry> + <structname>signalfd_siginfo</structname> structure containing + information about the received signal. See <citerefentry + project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry> for further information.</para> <para>Only a single handler may be installed for a specific - signal. The signal will be unblocked, and must be - blocked when the function is called. If the handler is not - specified (<parameter>handler</parameter> is + signal. The signal will be unblocked by this call, and must be + blocked before this function is called in all threads (using + <citerefentry + project='man-pages'><refentrytitle>sigprocmask</refentrytitle><manvolnum>2</manvolnum></citerefentry>). If + the handler is not specified (<parameter>handler</parameter> is <constant>NULL</constant>), a default handler which causes the - program to exit will be used. By default, the handler is enabled - permanently (<constant>SD_EVENT_ON</constant>), but this may be - changed with + program to exit cleanly will be used.</para> + + <para>By default, the event source is enabled permanently + (<constant>SD_EVENT_ON</constant>), but this may be changed with <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If the handler function returns a negative error code, it will be - disabled after the invocation, even if - <constant>SD_EVENT_ON</constant> mode is set. + disabled after the invocation, even if the + <constant>SD_EVENT_ON</constant> mode was requested before. </para> - <para><function>sd_event_source_get_signal()</function> retrieves - the configured signal number of a signal event source created - previously with <function>sd_event_add_signal()</function>. It - takes the event source object as the <parameter>source</parameter> + <para>To destroy an event source object use + <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + but note that the event source is only removed from the event loop + when all references to the event source are dropped. To make sure + an event source does not fire anymore, even if it is still referenced, + disable the event source using + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> + with <constant>SD_EVENT_OFF</constant>.</para> + + <para>If the second parameter of + <function>sd_event_add_signal()</function> is + <constant>NULL</constant> no reference to the event source object + is returned. In this case the event source is considered + "floating", and will be destroyed implicitly when the event loop + itself is destroyed.</para> + + <para><function>sd_event_source_get_signal()</function> returns + the configured signal number of an event source created previously + with <function>sd_event_add_signal()</function>. It takes the + event source object as the <parameter>source</parameter> parameter.</para> - </refsect1> <refsect1> @@ -124,7 +147,7 @@ <para>On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style error - code. </para> + code.</para> </refsect1> <refsect1> @@ -143,43 +166,37 @@ <term><constant>-EINVAL</constant></term> <listitem><para>An invalid argument has been passed.</para></listitem> - </varlistentry> <varlistentry> <term><constant>-EBUSY</constant></term> - <listitem><para>An handler is already installed for this + <listitem><para>A handler is already installed for this signal or the signal was not blocked previously.</para></listitem> - </varlistentry> <varlistentry> <term><constant>-ESTALE</constant></term> <listitem><para>The event loop is already terminated.</para></listitem> - </varlistentry> <varlistentry> <term><constant>-ECHILD</constant></term> <listitem><para>The event loop has been created in a different process.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EDOM</constant></term> + <listitem><para>The passed event source is not a signal event source.</para></listitem> </varlistentry> </variablelist> </refsect1> - <refsect1> - <title>Notes</title> - - <para><function>sd_event_add_signal()</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> - </refsect1> + <xi:include href="libsystemd-pkgconfig.xml" /> <refsect1> <title>See Also</title> @@ -188,10 +205,16 @@ <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_now</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_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/sd_event_add_time.xml b/man/sd_event_add_time.xml index c5f7aee19d..5496b71529 100644 --- a/man/sd_event_add_time.xml +++ b/man/sd_event_add_time.xml @@ -21,7 +21,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>. --> -<refentry id="sd_event_add_time"> +<refentry id="sd_event_add_time" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_event_add_time</title> @@ -49,13 +49,23 @@ <refname>sd_event_source_get_time_accuracy</refname> <refname>sd_event_source_set_time_accuracy</refname> <refname>sd_event_source_get_time_clock</refname> + <refname>sd_event_time_handler_t</refname> <refpurpose>Add a timer event source to an event loop</refpurpose> </refnamediv> <refsynopsisdiv> <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> + + <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo> + + <funcprototype> + <funcdef>typedef int (*<function>sd_event_time_handler_t</function>)</funcdef> + <paramdef>sd_event_source *<parameter>s</parameter></paramdef> + <paramdef>uint64_t <parameter>usec</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + </funcprototype> <funcprototype> <funcdef>int <function>sd_event_add_time</function></funcdef> @@ -69,34 +79,27 @@ </funcprototype> <funcprototype> - <funcdef>typedef int (*<function>sd_event_time_handler_t</function>)</funcdef> - <paramdef>sd_event_source *<parameter>s</parameter></paramdef> - <paramdef>uint64_t <parameter>usec</parameter></paramdef> - <paramdef>void *<parameter>userdata</parameter></paramdef> - </funcprototype> - - <funcprototype> <funcdef>int <function>sd_event_source_get_time</function></funcdef> <paramdef>sd_event_source *<parameter>source</parameter></paramdef> - <paramdef>usec_t *<parameter>usec</parameter></paramdef> + <paramdef>uint64_t *<parameter>usec</parameter></paramdef> </funcprototype> <funcprototype> <funcdef>int <function>sd_event_source_set_time</function></funcdef> <paramdef>sd_event_source *<parameter>source</parameter></paramdef> - <paramdef>usec_t <parameter>usec</parameter></paramdef> + <paramdef>uint64_t <parameter>usec</parameter></paramdef> </funcprototype> <funcprototype> <funcdef>int <function>sd_event_source_get_time_accuracy</function></funcdef> <paramdef>sd_event_source *<parameter>source</parameter></paramdef> - <paramdef>usec_t *<parameter>usec</parameter></paramdef> + <paramdef>uint64_t *<parameter>usec</parameter></paramdef> </funcprototype> <funcprototype> <funcdef>int <function>sd_event_source_set_time_accuracy</function></funcdef> <paramdef>sd_event_source *<parameter>source</parameter></paramdef> - <paramdef>usec_t <parameter>usec</parameter></paramdef> + <paramdef>uint64_t <parameter>usec</parameter></paramdef> </funcprototype> <funcprototype> @@ -111,74 +114,120 @@ <refsect1> <title>Description</title> - <para><function>sd_event_add_time()</function> adds a new timer - event source to an event loop object. The event loop is specified - in <parameter>event</parameter>, the event source is returned in - the <parameter>source</parameter> parameter. The - <parameter>clock</parameter> parameter takes a clock identifier, - one of <constant>CLOCK_REALTIME</constant>, - <constant>CLOCK_MONOTONIC</constant> and - <constant>CLOCK_BOOTTIME_ALARM</constant>. See - <citerefentry><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details regarding the various types of clocks. The - <parameter>usec</parameter> parameter takes a time value in - microseconds, relative to the clock's epoch specifying when the - timer shall elapse the earliest. The - <parameter>accuracy</parameter> parameter takes an additional - accuracy value in microseconds specifying a time the timer event - may be delayed. Specify 0 for selecting the default accuracy - (250ms). Specify 1 for most accurate timers. Consider specifying - 60000000 or larger (1h) for long-running events that may be - delayed substantially. Picking higher accuracy values allows the - system to coalesce timer events more aggressively, thus improving - power efficiency. The <parameter>handler</parameter> shall - reference a function to call when the timer elapses. The handler - function will be passed the <parameter>userdata</parameter> - pointer, which may be chosen freely by the caller. The handler is - also passed the configured time it was triggered, however it might - actually have been called at a slightly later time, subject to the - specified accuracy value, the kernel timer slack (see - <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>) - and additional scheduling latencies.</para> + <para><function>sd_event_add_time()</function> adds a new timer event source to an event loop. The event loop + object is specified in the <parameter>event</parameter> parameter, the event source object is returned in the + <parameter>source</parameter> parameter. The <parameter>clock</parameter> parameter takes a clock identifier, one + of <constant>CLOCK_REALTIME</constant>, <constant>CLOCK_MONOTONIC</constant>, <constant>CLOCK_BOOTTIME</constant>, + <constant>CLOCK_REALTIME_ALARM</constant>, or <constant>CLOCK_BOOTTIME_ALARM</constant>. See + <citerefentry><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry> for details + regarding the various types of clocks. The <parameter>usec</parameter> parameter specifies the earliest time, in + microseconds (µs), relative to the clock's epoch, when the timer shall be triggered. If a time already in the past + is specified (including <constant>0</constant>), this timer source "fires" immediately and is ready to be + dispatched. If the parameter is specified as <constant>UINT64_MAX</constant> the timer event will never elapse, + which may be used as an alternative to explicitly disabling a timer event source with + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. The + <parameter>accuracy</parameter> parameter specifies an additional accuracy value in µs specifying how much the + timer event may be delayed. Use <constant>0</constant> to select the default accuracy (250ms). Use 1µs for maximum + accuracy. Consider specifying 60000000µs (1min) or larger for long-running events that may be delayed + substantially. Picking higher accuracy values allows the system to coalesce timer events more aggressively, + improving power efficiency. The <parameter>handler</parameter> parameter shall reference a function to call when + the timer elapses. The handler function will be passed the <parameter>userdata</parameter> pointer, which may be + chosen freely by the caller. The handler is also passed the configured trigger time, even if it is actually called + slightly later, subject to the specified accuracy value, the kernel timer slack (see + <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>), and additional + scheduling latencies. To query the actual time the handler was called use + <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> <para>By default, the timer will elapse once (<constant>SD_EVENT_ONESHOT</constant>), but this may be changed with <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If the handler function returns a negative error code, it will be - disabled after the invocation, even if - <constant>SD_EVENT_ON</constant> mode is set. + disabled after the invocation, even if the + <constant>SD_EVENT_ON</constant> mode was requested before. Note + that a timer event set to <constant>SD_EVENT_ON</constant> will + fire continuously unless its configured time is updated using + <function>sd_event_source_set_time()</function>. </para> + <para>To destroy an event source object use + <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + but note that the event source is only removed from the event loop + when all references to the event source are dropped. To make sure + an event source does not fire anymore, even if it is still referenced, + disable the event source using + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> + with <constant>SD_EVENT_OFF</constant>.</para> + + <para>If the second parameter of + <function>sd_event_add_time()</function> is + <constant>NULL</constant> no reference to the event source object + is returned. In this case the event source is considered + "floating", and will be destroyed implicitly when the event loop + itself is destroyed.</para> + + <para>If the <parameter>handler</parameter> to + <function>sd_event_add_time()</function> is + <constant>NULL</constant>, and the event source fires, this will + be considered a request to exit the event loop. In this case, the + <parameter>userdata</parameter> parameter, cast to an integer, is + used for the exit code passed to + <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + + <para>Use <constant>CLOCK_BOOTTIME_ALARM</constant> and + <constant>CLOCK_REALTIME_ALARM</constant> to define event sources + that may wake up the system from suspend.</para> + + <para>In order to set up relative timers (that is, relative to the + current time), retrieve the current time via + <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + add the desired timespan to it, and use the result as + the <parameter>usec</parameter> parameter to + <function>sd_event_add_time()</function>.</para> + + <para>In order to set up repetitive timers (that is, timers that + are triggered in regular intervals), set up the timer normally, + for the first invocation. Each time the event handler is invoked, + update the timer's trigger time with + <citerefentry><refentrytitle>sd_event_source_set_time</refentrytitle><manvolnum>3</manvolnum></citerefentry> for the next timer + iteration, and reenable the timer using + <function>sd_event_source_set_enabled()</function>. To calculate + the next point in time to pass to + <function>sd_event_source_set_time()</function>, either use as + base the <parameter>usec</parameter> parameter passed to the timer + callback, or the timestamp returned by + <function>sd_event_now()</function>. In the former case timer + events will be regular, while in the latter case the scheduling + latency will keep accumulating on the timer.</para> + <para><function>sd_event_source_get_time()</function> retrieves - the configured time value of a timer event source created + the configured time value of an event source created previously with <function>sd_event_add_time()</function>. It takes the event source object and a pointer to a variable to store the - time in microseconds in.</para> + time in, relative to the selected clock's epoch, in µs.</para> <para><function>sd_event_source_set_time()</function> changes the - configured time value of a timer event source created previously - with <function>sd_event_add_time()</function>. It takes the event - source object and a time relative to the selected clock's - epoch, in microseconds.</para> + time of an event source created previously with + <function>sd_event_add_time()</function>. It takes the event + source object and a time relative to the selected clock's epoch, + in µs.</para> <para><function>sd_event_source_get_time_accuracy()</function> - retrieves the configured accuracy value of a timer event source + retrieves the configured accuracy value of an event source created previously with <function>sd_event_add_time()</function>. It takes the event source object and a pointer to a variable to store - the accuracy in microseconds in.</para> + the accuracy in. The accuracy is specified in µs.</para> <para><function>sd_event_source_set_time_accuracy()</function> changes the configured accuracy of a timer event source created previously with <function>sd_event_add_time()</function>. It takes - the event source object and an accuracy, in microseconds.</para> + the event source object and accuracy, in µs.</para> <para><function>sd_event_source_get_time_clock()</function> - retrieves the configured clock of a timer event source created + retrieves the configured clock of an event source created previously with <function>sd_event_add_time()</function>. It takes the event source object and a pointer to a variable to store the clock identifier in.</para> - </refsect1> <refsect1> @@ -192,7 +241,7 @@ <refsect1> <title>Errors</title> - <para>Returned errors may indicate the following problems:</para> + <para>Returned values may indicate the following problems:</para> <variablelist> <varlistentry> @@ -228,19 +277,17 @@ <listitem><para>The selected clock is not supported by the event loop implementation.</para></listitem> </varlistentry> - </variablelist> - </refsect1> - <refsect1> - <title>Notes</title> + <varlistentry> + <term><constant>-EDOM</constant></term> - <para><function>sd_event_add_time()</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> + <listitem><para>The passed event source is not a timer event source.</para></listitem> + </varlistentry> + </variablelist> </refsect1> + <xi:include href="libsystemd-pkgconfig.xml" /> + <refsect1> <title>See Also</title> @@ -248,11 +295,18 @@ <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_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_io</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_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_enabled</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>, + <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 project='man-pages'><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/sd_event_exit.xml b/man/sd_event_exit.xml new file mode 100644 index 0000000000..9846a3eaf4 --- /dev/null +++ b/man/sd_event_exit.xml @@ -0,0 +1,163 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2015 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_event_exit" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_event_exit</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_event_exit</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_event_exit</refname> + <refname>sd_event_get_exit_code</refname> + + <refpurpose>Ask the event loop to exit</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_event_exit</function></funcdef> + <paramdef>sd_event *<parameter>event</parameter></paramdef> + <paramdef>int <parameter>code</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_get_exit_code</function></funcdef> + <paramdef>sd_event *<parameter>event</parameter></paramdef> + <paramdef>int *<parameter>code</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_event_exit()</function> requests the event loop + specified in the <parameter>event</parameter> event loop object to + exit. The <parameter>code</parameter> parameter may be any integer + value and is returned as-is by + <citerefentry><refentrytitle>sd_event_loop</refentrytitle><manvolnum>3</manvolnum></citerefentry> + after the last event loop iteration. It may also be queried + using <function>sd_event_get_exit_code()</function>, see + below. </para> + + <para>When exiting is requested the event loop will stop listening + for and dispatching regular event sources. Instead it will proceed + with executing only event sources registered with + <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry> + in the order defined by their priority. After all exit event + sources have been dispatched the event loop is terminated.</para> + + <para>If <function>sd_event_exit()</function> is invoked a second + time while the event loop is still processing exit event sources, + the exit code stored in the event loop object is updated, but + otherwise no further operation is executed.</para> + + <para><function>sd_event_get_exit_code()</function> may be used to + query the exit code passed into + <function>sd_event_exit()</function> earlier.</para> + + <para>While the full positive and negative integer ranges may be used + for the exit code, care should be taken not pick exit codes that + conflict with regular exit codes returned by + <function>sd_event_loop()</function>, if these exit codes shall be + distinguishable.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>sd_event_exit()</function> and + <function>sd_event_get_exit_code()</function> 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 event loop object or error code pointer are invalid.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><constant>-ECHILD</constant></term> + + <listitem><para>The event loop was created in a different process.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ESTALE</constant></term> + + <listitem><para>The event loop has exited already and all exit handlers are already processed.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENODATA</constant></term> + + <listitem><para>The event loop has not been requested to exit yet.</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-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_event_get_fd.xml b/man/sd_event_get_fd.xml index ecdbe76ec4..f68752dd0e 100644 --- a/man/sd_event_get_fd.xml +++ b/man/sd_event_get_fd.xml @@ -21,8 +21,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>. --> -<refentry id="sd_event_get_fd" - xmlns:xi="http://www.w3.org/2001/XInclude"> +<refentry id="sd_event_get_fd" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_event_get_fd</title> @@ -51,11 +50,11 @@ <refsynopsisdiv> <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> <funcprototype> <funcdef>int <function>sd_event_get_fd</function></funcdef> - <paramdef>sd_bus *<parameter>event</parameter></paramdef> + <paramdef>sd_event *<parameter>event</parameter></paramdef> </funcprototype> </funcsynopsis> @@ -65,19 +64,29 @@ <title>Description</title> <para><function>sd_event_get_fd()</function> returns the file - descriptor that the event loop object returned by the + descriptor that an event loop object returned by the <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry> - function uses to wait for events. This file descriptor can be - polled for events. This makes it possible to embed the + function uses to wait for events. This file descriptor may itself + be polled for + <constant>POLLIN</constant>/<constant>EPOLLIN</constant> + events. This makes it possible to embed an <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry> - event loop inside of another event loop.</para> + event loop into another, possibly foreign, event loop.</para> + + <para>The returned file descriptor refers to an <citerefentry + project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry> + object. It is recommended not to alter it by invoking + <citerefentry + project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> + on it, in order to avoid interference with the event loop's inner + logic and assumptions.</para> </refsect1> <refsect1> <title>Return Value</title> <para>On success, <function>sd_event_get_fd()</function> returns a - non-negative integer. On failure, it returns a negative + non-negative file descriptor. On failure, it returns a negative errno-style error code.</para> </refsect1> @@ -108,21 +117,13 @@ <title>Examples</title> <example> - <title>Integration in glib event loop</title> + <title>Integration in the GLib event loop</title> <programlisting><xi:include href="glib-event-glue.c" parse="text" /></programlisting> </example> </refsect1> - <refsect1> - <title>Notes</title> - - <para><function>sd_event_get_fd()</function> is 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> @@ -130,7 +131,9 @@ <para> <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_ref</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</refentrytitle><manvolnum>7</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/sd_event_new.xml b/man/sd_event_new.xml index e5a440556e..2c23b00a8c 100644 --- a/man/sd_event_new.xml +++ b/man/sd_event_new.xml @@ -21,7 +21,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>. --> -<refentry id="sd_event_new"> +<refentry id="sd_event_new" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_event_new</title> @@ -47,32 +47,48 @@ <refname>sd_event_default</refname> <refname>sd_event_ref</refname> <refname>sd_event_unref</refname> + <refname>sd_event_unrefp</refname> + <refname>sd_event_get_tid</refname> + <refname>sd_event</refname> <refpurpose>Acquire and release an event loop object</refpurpose> </refnamediv> <refsynopsisdiv> <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> + + <funcsynopsisinfo><token>typedef</token> struct sd_event sd_event;</funcsynopsisinfo> <funcprototype> <funcdef>int <function>sd_event_new</function></funcdef> - <paramdef>sd_bus **<parameter>event</parameter></paramdef> + <paramdef>sd_event **<parameter>event</parameter></paramdef> </funcprototype> <funcprototype> <funcdef>int <function>sd_event_default</function></funcdef> - <paramdef>sd_bus **<parameter>event</parameter></paramdef> + <paramdef>sd_event **<parameter>event</parameter></paramdef> </funcprototype> <funcprototype> - <funcdef>sd_bus *<function>sd_event_ref</function></funcdef> - <paramdef>sd_bus *<parameter>event</parameter></paramdef> + <funcdef>sd_event *<function>sd_event_ref</function></funcdef> + <paramdef>sd_event *<parameter>event</parameter></paramdef> </funcprototype> <funcprototype> - <funcdef>sd_bus *<function>sd_event_unref</function></funcdef> - <paramdef>sd_bus *<parameter>event</parameter></paramdef> + <funcdef>sd_event *<function>sd_event_unref</function></funcdef> + <paramdef>sd_event *<parameter>event</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void <function>sd_event_unrefp</function></funcdef> + <paramdef>sd_event **<parameter>event</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_get_tid</function></funcdef> + <paramdef>sd_event *<parameter>event</parameter></paramdef> + <paramdef>pid_t *<parameter>tid</parameter></paramdef> </funcprototype> </funcsynopsis> @@ -103,6 +119,17 @@ thread. All threads have exactly either zero or one default event loop objects associated, but never more.</para> + <para>After allocating an event loop object, add event sources to + it with + <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_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + and then execute the event loop using + <citerefentry><refentrytitle>sd_event_run</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> @@ -114,9 +141,43 @@ <function>sd_event_default()</function>, then releasing it, and then acquiring a new one with <function>sd_event_default()</function> will result in two - distinct objects. Note that in order to free an event loop object, + distinct objects. Note that, in order to free an event loop object, all remaining event sources of the event loop also need to be freed as each keeps a reference to it.</para> + + <para><function>sd_event_unrefp()</function> is similar to + <function>sd_event_unref()</function> but takes a pointer to a + pointer to an <type>sd_event</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>. Note that this function is defined as + inline function. Use a declaration like the following, + in order to allocate an event loop object that is freed + automatically as the code block is left:</para> + + <programlisting>{ + __attribute__((cleanup(sd_event_unrefp)) sd_event *event = NULL; + int r; + … + r = sd_event_default(&event); + if (r < 0) + fprintf(stderr, "Failed to allocate event loop: %s\n", strerror(-r)); + … +}</programlisting> + + <para><function>sd_event_ref()</function>, + <function>sd_event_unref()</function> and + <function>sd_event_unrefp()</function> execute no operation if the + passed in event loop object is <constant>NULL</constant>.</para> + + <para><function>sd_event_get_tid()</function> retrieves the thread + identifier ("TID") of the thread the specified event loop object + is associated with. This call is only supported for event loops + allocated with <function>sd_event_default()</function>, and + returns the identifier for the thread the event loop is the + default event loop of. See <citerefentry + project='man-pages'><refentrytitle>gettid</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for more information on thread identifiers.</para> </refsect1> <refsect1> @@ -149,19 +210,20 @@ <listitem><para>The maximum number of event loops has been allocated.</para></listitem> </varlistentry> - </variablelist> - </refsect1> - <refsect1> - <title>Notes</title> + <varlistentry> + <term><constant>-ENXIO</constant></term> - <para><function>sd_event_new()</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> + <listitem><para><function>sd_event_get_tid()</function> was + invoked on an event loop object that was not allocated with + <function>sd_event_default()</function>.</para></listitem> + </varlistentry> + + </variablelist> </refsect1> + <xi:include href="libsystemd-pkgconfig.xml" /> + <refsect1> <title>See Also</title> @@ -174,7 +236,9 @@ <citerefentry><refentrytitle>sd_event_add_child</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_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> </refsect1> diff --git a/man/sd_event_now.xml b/man/sd_event_now.xml new file mode 100644 index 0000000000..2c83b0bcb5 --- /dev/null +++ b/man/sd_event_now.xml @@ -0,0 +1,146 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2015 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_event_now" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_event_now</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_event_now</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_event_now</refname> + + <refpurpose>Retrieve current event loop iteration timestamp</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_event_now</function></funcdef> + <paramdef>sd_event *<parameter>event</parameter></paramdef> + <paramdef>clockid_t <parameter>clock</parameter></paramdef> + <paramdef>uint64_t *<parameter>usec</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_event_now()</function> returns the time when + the most recent event loop iteration began. A timestamp + is taken right after returning from the event sleep, and before + dispatching any event sources. The <parameter>event</parameter> + parameter specifies the event loop object to retrieve the timestamp + from. The <parameter>clock</parameter> parameter specifies the clock to + retrieve the timestamp for, and is one of + <constant>CLOCK_REALTIME</constant> (or equivalently + <constant>CLOCK_REALTIME_ALARM</constant>), + <constant>CLOCK_MONOTONIC</constant>, or + <constant>CLOCK_BOOTTIME</constant> (or equivalently + <constant>CLOCK_BOOTTIME_ALARM</constant>), see + <citerefentry project='man-pages'><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for more information on the various clocks. The retrieved + timestamp is stored in the <parameter>usec</parameter> parameter, + in µs since the clock's epoch. If this function is invoked before + the first event loop iteration, the current time is returned, as + reported by <function>clock_gettime()</function>. To distinguish + this case from a regular invocation the return value will be + positive, and zero when the returned timestamp refers to an actual + event loop iteration.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>If the first event loop iteration has not run yet + <function>sd_event_now()</function> writes current time to + <parameter>usec</parameter> and returns a positive return value. + Otherwise, it will write the requested timestamp to <parameter>usec</parameter> + and return 0. On failure, the call returns a negative errno-style + error code.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned values may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>An invalid parameter was + passed.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><constant>-EOPNOTSUPP</constant></term> + + <listitem><para>Unsupported clock type. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ECHILD</constant></term> + + <listitem><para>The event loop object was 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-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_event_run.xml b/man/sd_event_run.xml index 2eab5684c5..5b68959165 100644 --- a/man/sd_event_run.xml +++ b/man/sd_event_run.xml @@ -21,7 +21,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>. --> -<refentry id="sd_event_run"> +<refentry id="sd_event_run" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_event_run</title> @@ -46,7 +46,7 @@ <refname>sd_event_run</refname> <refname>sd_event_loop</refname> - <refpurpose>Run libsystemd event loop</refpurpose> + <refpurpose>Run an event loop</refpurpose> </refnamediv> <refsynopsisdiv> @@ -56,7 +56,7 @@ <funcprototype> <funcdef>int <function>sd_event_run</function></funcdef> <paramdef>sd_event *<parameter>event</parameter></paramdef> - <paramdef>uint64_t <parameter>timeout</parameter></paramdef> + <paramdef>uint64_t <parameter>usec</parameter></paramdef> </funcprototype> <funcprototype> @@ -69,47 +69,60 @@ <refsect1> <title>Description</title> - <para><function>sd_event_run()</function> can be used to run one - iteration of the event loop of libsystemd. This function waits - until an event to process is available and dispatches a handler - for it. Parameter <parameter>timeout</parameter> specifices the - maximum time (in microseconds) to wait. <constant>(uint64_t) - -1</constant> may be used to specify an infinite timeout.</para> - - <para><function>sd_event_loop</function> runs - <function>sd_event_wait</function> in a loop with a timeout of - infinity. This makes it suitable for the main event loop of a - program.</para> + <para><function>sd_event_run()</function> may be used to run a single + iteration of the event loop specified in the + <parameter>event</parameter> parameter. The function waits until an event to + process is available, and dispatches the registered handler for + it. The <parameter>usec</parameter> parameter specifies the + maximum time (in microseconds) to wait for an event. Use + <constant>(uint64_t) -1</constant> to specify an infinite + timeout.</para> + + <para><function>sd_event_loop()</function> invokes + <function>sd_event_run()</function> in a loop, thus implementing + the actual event loop. The call returns as soon as exiting was + requested using + <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> <para>The event loop object <parameter>event</parameter> is created with - <function>sd_event_new</function>. - Events to wait for and their handlers can be registered with - <function>sd_event_add_time</function>, - <function>sd_event_add_child</function>, - <function>sd_event_add_signal</function>, - <function>sd_event_add_defer</function>, - <function>sd_event_add_exit</function>, + <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + Events sources to wait for and their handlers may be registered + with + <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_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry> and - <function>sd_event_add_post</function>. + <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>. </para> - <para>For more fine-grained control, - <function>sd_event_prepare</function>, - <function>sd_event_wait</function>, and - <function>sd_event_dispatch</function> may be used. Along with - <function>sd_event_get_fd</function>, those functions make it - possible to integrate the libsystemd loop inside of another event - loop.</para> + <para>For low-level control of event loop execution, use + <citerefentry><refentrytitle>sd_event_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>sd_event_dispatch</refentrytitle><manvolnum>3</manvolnum></citerefentry> + which are wrapped by <function>sd_event_run()</function>. Along + with + <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + these functions allow integration of an + <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry> + event loop into foreign event loop implementations.</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. - <function>sd_event_run</function> returns 0 if the event loop is - finished, and a positive value if it can be continued.</para> + <para>On failure, these functions return a negative errno-style + error code. <function>sd_event_run()</function> returns a + positive, non-zero integer if an event source was dispatched, and + zero when the specified timeout hit before an event source has + seen any event, and hence no event source was + dispatched. <function>sd_event_loop()</function> returns the exit + code specified when invoking + <function>sd_event_exit()</function>.</para> </refsect1> <refsect1> @@ -121,8 +134,8 @@ <varlistentry> <term><constant>-EINVAL</constant></term> - <listitem><para>Parameter <parameter>event</parameter> is - <constant>NULL</constant>.</para></listitem> + <listitem><para>The <parameter>event</parameter> parameter is + invalid or <constant>NULL</constant>.</para></listitem> </varlistentry> <varlistentry> @@ -150,18 +163,10 @@ </variablelist> - <para>Other errors are possible too.</para> + <para>Other errors are possible, too.</para> </refsect1> - <refsect1> - <title>Notes</title> - - <para><function>sd_event_run()</function> and - <function>sd_event_loop()</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> @@ -169,14 +174,16 @@ <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_wait</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_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>, - <ulink url="https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html">GLIb Main Event Loop</ulink>. + <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>. </para> </refsect1> diff --git a/man/sd_event_set_name.xml b/man/sd_event_set_name.xml deleted file mode 100644 index 72aef897c7..0000000000 --- a/man/sd_event_set_name.xml +++ /dev/null @@ -1,151 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - -<!-- - This file is part of systemd. - - Copyright 2014 Zbigniew Jędrzejewski-Szmek - - systemd is free software; you can redistribute it and/or modify it - under the terms of the GNU Lesser General Public License as published by - the Free Software Foundation; either version 2.1 of the License, or - (at your option) any later version. - - systemd is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public License - along with systemd; If not, see <http://www.gnu.org/licenses/>. ---> - -<refentry id="sd_event_set_name" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_event_set_name</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>More text</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_event_set_name</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_event_set_name</refname> - <refname>sd_event_get_name</refname> - - <refpurpose>Set human-readable names for event sources</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_event_set_name</function></funcdef> - <paramdef>sd_event_source *<parameter>source</parameter></paramdef> - <paramdef>const char *<parameter>name</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_event_get_name</function></funcdef> - <paramdef>sd_event_source *<parameter>source</parameter></paramdef> - <paramdef>const char **<parameter>name</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_event_set_name()</function> can be used to set - an arbitrary name for the event source - <parameter>source</parameter>. This name will be used in error - messages generated by - <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for this source. Specified <parameter>name</parameter> must point - to a <constant>NUL</constant>-terminated string or be - <constant>NULL</constant>. In the latter case, the name will be - unset. The string is copied internally, so the - <parameter>name</parameter> argument is not referenced after the - function returns.</para> - - <para><function>sd_event_set_name()</function> can be used to - query the current name assigned to source - <parameter>source</parameter>. It returns a pointer to the current - name (possibly <constant>NULL</constant>) in - <parameter>name</parameter>.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, <function>sd_event_set_name()</function> and - <function>sd_event_get_name()</function> return a - non-negative 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><parameter>source</parameter> is not a valid - pointer to an <structname>sd_event_source</structname> - structure or the <parameter>name</parameter> argument for - <function>sd_event_get_name()</function> is - <constant>NULL</constant>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ENOMEM</constant></term> - - <listitem><para>Not enough memory to copy the - name.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>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> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>sd-event</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_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_event_set_watchdog.xml b/man/sd_event_set_watchdog.xml new file mode 100644 index 0000000000..cbc5bc0836 --- /dev/null +++ b/man/sd_event_set_watchdog.xml @@ -0,0 +1,177 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2015 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_event_set_watchdog" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_event_set_watchdog</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_event_set_watchdog</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_event_set_watchdog</refname> + <refname>sd_event_get_watchdog</refname> + + <refpurpose>Enable event loop watchdog support</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_event_set_watchdog</function></funcdef> + <paramdef>sd_event *<parameter>event</parameter></paramdef> + <paramdef>int b</paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_get_watchdog</function></funcdef> + <paramdef>sd_event *<parameter>event</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_event_set_watchdog()</function> may be used to + enable or disable automatic watchdog notification support in the + event loop object specified in the <parameter>event</parameter> + parameter. Specifically, depending on the <parameter>b</parameter> + boolean argument this will make sure the event loop wakes up in + regular intervals and sends watchdog notification messages to the + service manager, if this was requested by the service + manager. Watchdog support is determined with + <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + and watchdog messages are sent with + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>. See + the <varname>WatchdogSec=</varname> setting in + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details on how to enable watchdog support for a service and + the protocol used. The wake-up interval is chosen as half the + watchdog timeout declared by the service manager via the + <varname>$WATCHDOG_USEC</varname> environment variable. If the + service manager did not request watchdog notifications, or if the + process was not invoked by the service manager this call with a + true <parameter>b</parameter> parameter executes no + operation. Passing a false <parameter>b</parameter> parameter will + disable the automatic sending of watchdog notification messages if + it was enabled before. Newly allocated event loop objects have + this feature disabled.</para> + + <para>The first watchdog notification message is sent immediately + when <function>set_event_set_watchdog()</function> is invoked with + a true <parameter>b</parameter> parameter.</para> + + <para>The watchdog logic is designed to allow the service manager + to automatically detect services that ceased processing of + incoming events, and thus appear "hung". Watchdog notifications + are sent out only at the beginning of each event loop + iteration. If an event source dispatch function blocks for an + excessively long time and does not return execution to the event + loop quickly, this might hence cause the notification message to + be delayed, and possibly result in abnormal program termination, + as configured in the service unit file.</para> + + <para><function>sd_event_get_watchdog()</function> may be used to + determine whether watchdog support was previously requested by a + call to <function>sd_event_set_watchdog()</function> with a true + <parameter>b</parameter> parameter and successfully + enabled.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>sd_event_set_watchdog()</function> and + <function>sd_event_get_watchdog()</function> return a non-zero + positive integer if the service manager requested watchdog support + and watchdog support was successfully enabled. They return zero if + the service manager did not request watchdog support, or if + watchdog support was explicitly disabled with a false + <parameter>b</parameter> parameter. 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>-ECHILD</constant></term> + + <listitem><para>The event loop has been created in a different process.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>The passed event loop object was invalid.</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-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_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> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_event_source_get_event.xml b/man/sd_event_source_get_event.xml new file mode 100644 index 0000000000..2fdbd411bd --- /dev/null +++ b/man/sd_event_source_get_event.xml @@ -0,0 +1,100 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2015 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_event_source_get_event" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_event_source_get_event</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_event_source_get_event</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_event_source_get_event</refname> + + <refpurpose>Retrieve the event loop of an event source</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>sd_event* <function>sd_event_source_get_event</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_event_source_get_event()</function> may be used + to retrieve the event loop object the event source object specified + as <parameter>source</parameter> is associated with. The event + loop object is specified when creating an event source object with + calls such as + <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry> + or + <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>sd_event_source_get_event()</function> + returns the associated event loop object. On failure, it returns + NULL.</para> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <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_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_event_source_get_pending.xml b/man/sd_event_source_get_pending.xml new file mode 100644 index 0000000000..7f88bd1b87 --- /dev/null +++ b/man/sd_event_source_get_pending.xml @@ -0,0 +1,167 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2015 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_event_source_get_pending" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_event_source_get_pending</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_event_source_get_pending</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_event_source_get_pending</refname> + + <refpurpose>Determine pending state of event sources</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_event_source_get_pending</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_event_source_get_pending()</function> may be + used to determine whether the event source object specified as + <parameter>source</parameter> has seen events but has not been + dispatched yet (and thus is marked "pending").</para> + + <para>Event source objects initially are not marked pending, when + they are created with calls such as + <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + with the exception of those created with + <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry> + which are immediately marked pending, and + <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for which the "pending" concept is not defined. For details see + the respective manual pages.</para> + + <para>In each event loop iteration one event source of those + marked pending is dispatched, in the order defined by the event + source priority, as set with + <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + + <para>For I/O event sources, as created with + <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + the call + <citerefentry><refentrytitle>sd_event_source_get_io_revents</refentrytitle><manvolnum>3</manvolnum></citerefentry> + may be used to query the type of event pending in more + detail.</para> + + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, + <function>sd_event_source_get_pending()</function> returns an + integer greater than zero when the event source is marked pending, + and zero when the event source is not marked pending. 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><parameter>source</parameter> is not a valid + pointer to an <structname>sd_event_source</structname> + object.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EDOM</constant></term> + + <listitem><para><parameter>source</parameter> refers to an + event source object created with + <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Not enough memory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ESTALE</constant></term> + + <listitem><para>The event loop is already terminated.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><constant>-ECHILD</constant></term> + + <listitem><para>The event loop 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>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_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_event_source_set_description.xml b/man/sd_event_source_set_description.xml new file mode 100644 index 0000000000..b9488a622f --- /dev/null +++ b/man/sd_event_source_set_description.xml @@ -0,0 +1,170 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2014 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_event_source_set_description" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_event_source_set_description</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>More text</contrib> + <firstname>Zbigniew</firstname> + <surname>Jędrzejewski-Szmek</surname> + <email>zbyszek@in.waw.pl</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_event_source_set_description</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_event_source_set_description</refname> + <refname>sd_event_source_get_description</refname> + + <refpurpose>Set or retrieve descriptive names of event sources</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_event_source_set_description</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>const char *<parameter>description</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_source_get_description</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>const char **<parameter>description</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_event_source_set_description()</function> may + be used to set an arbitrary descriptive name for the event source + object specified as <parameter>source</parameter>. This name will + be used in debugging messages generated by + <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for this event source, and may be queried using + <function>sd_event_source_get_description()</function> for + debugging purposes. The <parameter>description</parameter> parameter shall + point to a <constant>NUL</constant>-terminated string or be + <constant>NULL</constant>. In the latter case, the descriptive + name will be unset. The string is copied internally, hence the + <parameter>description</parameter> argument is not referenced + after the function returns.</para> + + <para><function>sd_event_source_get_description()</function> may + be used to query the current descriptive name assigned to the + event source object <parameter>source</parameter>. It returns a + pointer to the current name in <parameter>description</parameter>, + stored in memory internal to the event source. The memory is + invalidated when the event source is destroyed or the descriptive + name is changed.</para> + + <para>Event source objects generally have no description set when + they are created, except for UNIX signal event sources created + with + <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + whose descriptive name is initialized to the signal's C constant + name (e.g. <literal>SIGINT</literal> or + <literal>SIGTERM</literal>).</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>sd_event_source_set_description()</function> and + <function>sd_event_source_get_description()</function> return a + non-negative 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><parameter>source</parameter> is not a valid + pointer to an <structname>sd_event_source</structname> + object or the <parameter>description</parameter> argument for + <function>sd_event_source_get_description()</function> is + <constant>NULL</constant>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Not enough memory to copy the + name.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ECHILD</constant></term> + + <listitem><para>The event loop has been created in a different process.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><constant>-ENXIO</constant></term> + + <listitem><para>No name was set for the event + source.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <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_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_event_source_set_enabled.xml b/man/sd_event_source_set_enabled.xml new file mode 100644 index 0000000000..6844f29a49 --- /dev/null +++ b/man/sd_event_source_set_enabled.xml @@ -0,0 +1,179 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2015 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_event_source_set_enabled" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_event_source_set_enabled</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_event_source_set_enabled</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_event_source_set_enabled</refname> + <refname>sd_event_source_get_enabled</refname> + <refname>SD_EVENT_ON</refname> + <refname>SD_EVENT_OFF</refname> + <refname>SD_EVENT_ONESHOT</refname> + + <refpurpose>Enable or disable event sources</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> + + <funcsynopsisinfo><token>enum</token> { + <constant>SD_EVENT_OFF</constant> = 0, + <constant>SD_EVENT_ON</constant> = 1, + <constant>SD_EVENT_ONESHOT</constant> = -1, +};</funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_event_source_set_enabled</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>int <parameter>enabled</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_source_get_enabled</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>int *<parameter>enabled</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_event_source_set_enabled()</function> may be + used to enable or disable the event source object specified as + <parameter>source</parameter>. The <parameter>enabled</parameter> + parameter takes one of <constant>SD_EVENT_ON</constant> (to + enable), <constant>SD_EVENT_OFF</constant> (to disable) or + <constant>SD_EVENT_ONESHOT</constant>. If invoked with + <constant>SD_EVENT_ONESHOT</constant> the event source will be + enabled but automatically reset to + <constant>SD_EVENT_OFF</constant> after the event source was + dispatched once.</para> + + <para>Event sources that are disabled will not result in event + loop wakeups and will not be dispatched, until they are enabled + again.</para> + + <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> + + <para>Event source objects are enabled when they are first created + with calls such as + <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>. However, + depending on the event source type they are enabled continuously + (<constant>SD_EVENT_ON</constant>) or only for a single invocation + of the event source handler + (<constant>SD_EVENT_ONESHOT</constant>). For details see the + respective manual pages.</para> + + <para>As event source objects stay active and may be dispatched as + long as there is at least one reference to them, in many cases it + is a good idea to combine a call to + <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> + with a prior call to + <function>sd_event_source_set_enabled()</function> with + <constant>SD_EVENT_OFF</constant>, to ensure the event source is + not dispatched again until all other remaining references are dropped.</para> + </refsect1> + + <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> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para><parameter>source</parameter> is not a valid + pointer to an <structname>sd_event_source</structname> + object.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Not enough memory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ECHILD</constant></term> + + <listitem><para>The event loop 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>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_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_event_source_set_prepare.xml b/man/sd_event_source_set_prepare.xml new file mode 100644 index 0000000000..24861d01d9 --- /dev/null +++ b/man/sd_event_source_set_prepare.xml @@ -0,0 +1,171 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2015 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_event_source_set_prepare" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_event_source_set_prepare</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_event_source_set_prepare</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_event_source_set_prepare</refname> + + <refpurpose>Set a preparation callback for event sources</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_event_source_set_prepare</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>sd_event_handler_t <parameter>callback</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>typedef int (*<function>sd_event_handler_t</function>)</funcdef> + <paramdef>sd_event_source *<parameter>s</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_event_source_set_prepare()</function> may be + used to set a preparation callback for the event source object + specified as <parameter>source</parameter>. The callback function + specified as <parameter>callback</parameter> will be invoked + immediately before the event loop goes to sleep to wait for + incoming events. It is invoked with the user data pointer passed + when the event source was created. The callback function may be + used to reconfigure the precise events to wait for. If the + <parameter>callback</parameter> parameter is passed as NULL the + callback function is reset. </para> + + <para>Event source objects have no preparation callback associated + when they are first created with calls such as + <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Preparation + callback functions are supported for all event source types with + the exception of those created with + <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Preparation + callback functions are dispatched in the order indicated by the + event source's priority field, as set with + <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Preparation + callbacks of disabled event sources (see + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>) + are not invoked.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, + <function>sd_event_source_set_prepare()</function> returns a + non-negative 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><parameter>source</parameter> is not a valid + pointer to an <structname>sd_event_source</structname> + object.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ESTALE</constant></term> + + <listitem><para>The event loop is already terminated.</para></listitem> + + </varlistentry> + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Not enough memory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ECHILD</constant></term> + + <listitem><para>The event loop has been created in a different process.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><constant>-EDOM</constant></term> + + <listitem><para>The specified event source has been created + with + <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> + + </varlistentry> + + </variablelist> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <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_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>, + <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_event_source_set_priority.xml b/man/sd_event_source_set_priority.xml new file mode 100644 index 0000000000..6e7032fc80 --- /dev/null +++ b/man/sd_event_source_set_priority.xml @@ -0,0 +1,189 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2015 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_event_source_set_priority" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_event_source_set_priority</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_event_source_set_priority</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_event_source_set_priority</refname> + <refname>sd_event_source_get_priority</refname> + <refname>SD_EVENT_PRIORITY_IMPORTANT</refname> + <refname>SD_EVENT_PRIORITY_NORMAL</refname> + <refname>SD_EVENT_PRIORITY_IDLE</refname> + + <refpurpose>Set or retrieve the priority of event sources</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> + + <funcsynopsisinfo><token>enum</token> { + <constant>SD_EVENT_SOURCE_IMPORTANT</constant> = -100, + <constant>SD_EVENT_SOURCE_NORMAL</constant> = 0, + <constant>SD_EVENT_SOURCE_IDLE</constant> = 100, +};</funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_event_source_set_priority</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>int64_t <parameter>priority</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_source_get_priority</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>int64_t *<parameter>priority</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_event_source_set_priority()</function> may be + used to set the priority for the event source object specified as + <parameter>source</parameter>. The priority is specified as an + arbitrary signed 64bit integer. The priority is initialized to + <constant>SD_EVENT_PRIORITY_NORMAL</constant> (0) when the event + source is allocated with a call such as + <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry> + or + <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + and may be changed with this call. If multiple event sources have seen events at the same time, they are dispatched in the order indicated by the + event sources' priorities. Event sources with smaller priority + values are dispatched first. As well-known points of reference, + the constants <constant>SD_EVENT_PRIORITY_IMPORTANT</constant> + (-100), <constant>SD_EVENT_PRIORITY_NORMAL</constant> (0) and + <constant>SD_EVENT_PRIORITY_IDLE</constant> (100) may be used to + indicate event sources that shall be dispatched early, normally or + late. It is recommended to specify priorities based on these + definitions, and relative to them — however, the full 64bit + signed integer range is available for ordering event + sources.</para> + + <para>Priorities define the order in which event sources that have + seen events are dispatched. Care should be taken to ensure that + high-priority event sources (those with negative priority values + assigned) do not cause starvation of low-priority event sources + (those with positive priority values assigned).</para> + + <para>The order in which event sources with the same priority are + dispatched is undefined, but the event loop generally tries to + dispatch them in the order it learnt about events on them. As the + backing kernel primitives do not provide accurate information + about the order in which events occurred this is not necessarily + reliable. However, it is guaranteed that if events are seen on + multiple same-priority event sources at the same time, each one is + not dispatched again until all others have been dispatched + once. This behavior guarantees that within each priority + particular event sources do not starve or dominate the event + loop.</para> + + <para><function>sd_event_source_get_priority()</function> may be + used to query the current priority assigned to the event source + object <parameter>source</parameter>.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, + <function>sd_event_source_set_priority()</function> and + <function>sd_event_source_get_priority()</function> return a + non-negative 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><parameter>source</parameter> is not a valid + pointer to an <structname>sd_event_source</structname> + object.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Not enough memory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ESTALE</constant></term> + + <listitem><para>The event loop is already terminated.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><constant>-ECHILD</constant></term> + + <listitem><para>The event loop 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>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_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_event_source_set_userdata.xml b/man/sd_event_source_set_userdata.xml new file mode 100644 index 0000000000..533d491b13 --- /dev/null +++ b/man/sd_event_source_set_userdata.xml @@ -0,0 +1,119 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2015 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_event_source_set_userdata" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_event_source_set_userdata</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_event_source_set_userdata</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_event_source_set_userdata</refname> + <refname>sd_event_source_get_userdata</refname> + + <refpurpose>Set or retrieve user data pointer of event sources</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>void* <function>sd_event_source_set_userdata</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void* <function>sd_event_source_get_userdata</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_event_source_set_userdata()</function> may be + used to set an arbitrary user data pointer for the event source + object specified as <parameter>source</parameter>. The user data + pointer is usually specified when creating an event source object + with calls such as + <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry> + or + <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + and may be updated with this call. The user data pointer is also + passed to all handler callback functions associated with the event + source. The <parameter>userdata</parameter> parameter specifies + the new user data pointer to set, the function returns the + previous user data pointer. Note that <constant>NULL</constant> is + a valid user data pointer.</para> + + <para><function>sd_event_source_get_userdata()</function> may be + used to query the current user data pointer assigned to the event + source object <parameter>source</parameter>.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, + <function>sd_event_source_set_userdata()</function> and + <function>sd_event_source_get_userdata()</function> return the + previously set user data pointer. On failure, they return + NULL.</para> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <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_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_event_source_unref.xml b/man/sd_event_source_unref.xml new file mode 100644 index 0000000000..2c4d450763 --- /dev/null +++ b/man/sd_event_source_unref.xml @@ -0,0 +1,142 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2015 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_event_source_unref" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_event_source_unref</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_event_source_unref</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_event_source_unref</refname> + <refname>sd_event_source_unrefp</refname> + <refname>sd_event_source_ref</refname> + + <refpurpose>Increase or decrease event source reference counters</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>sd_event_source* <function>sd_event_source_unref</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void <function>sd_event_source_unrefp</function></funcdef> + <paramdef>sd_event_source **<parameter>source</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_event_source* <function>sd_event_source_ref</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_event_source_unref()</function> may be used to + decrement by one the reference counter of the event source object + specified as <parameter>source</parameter>. The reference counter + is initially set to one, when the event source is created with calls + such as + <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry> + or + <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>. When + the reference counter reaches zero it is removed from its event loop + object and destroyed.</para> + + <para><function>sd_event_source_unrefp()</function> is similar to + <function>sd_event_source_unref()</function> but takes a pointer to a + pointer to an <type>sd_event_source</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>. Note that this function is defined as + inline function.</para> + + <para><function>sd_event_source_ref()</function> may be used + to increase by one the reference counter of the event source object + specified as <parameter>source</parameter>.</para> + + <para><function>sd_event_source_unref()</function>, + <function>sd_bus_creds_unrefp()</function> and + <function>sd_bus_creds_ref()</function> execute no operation if + the passed event source object is + <constant>NULL</constant>.</para> + + <para>Note that event source objects stay alive and may be + dispatched as long as they have a reference counter greater than + zero. In order to drop a reference of an event source and make + sure the associated event source handler function is not called + anymore it is recommended to combine a call of + <function>sd_event_source_unref()</function> with a prior call to + <function>sd_event_source_set_enabled()</function> with + <constant>SD_EVENT_OFF</constant>.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>sd_event_source_unref()</function> always returns + <constant>NULL</constant>. + <function>sd_event_source_ref()</function> always returns the + event source object passed in.</para> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <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_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_event_wait.xml b/man/sd_event_wait.xml index 397d52a3e4..26327dc688 100644 --- a/man/sd_event_wait.xml +++ b/man/sd_event_wait.xml @@ -21,7 +21,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>. --> -<refentry id="sd_event_wait"> +<refentry id="sd_event_wait" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_event_wait</title> @@ -46,14 +46,33 @@ <refname>sd_event_wait</refname> <refname>sd_event_prepare</refname> <refname>sd_event_dispatch</refname> - - <refpurpose>Run parts of libsystemd event loop</refpurpose> + <refname>sd_event_get_state</refname> + <refname>sd_event_get_iteration</refname> + <refname>SD_EVENT_INITIAL</refname> + <refname>SD_EVENT_PREPARING</refname> + <refname>SD_EVENT_ARMED</refname> + <refname>SD_EVENT_PENDING</refname> + <refname>SD_EVENT_RUNNING</refname> + <refname>SD_EVENT_EXITING</refname> + <refname>SD_EVENT_FINISHED</refname> + + <refpurpose>Low-level event loop operations</refpurpose> </refnamediv> <refsynopsisdiv> <funcsynopsis> <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> + <funcsynopsisinfo><token>enum</token> { + <constant>SD_EVENT_INITIAL</constant>, + <constant>SD_EVENT_PREPARING</constant>, + <constant>SD_EVENT_ARMED</constant>, + <constant>SD_EVENT_PENDING</constant>, + <constant>SD_EVENT_RUNNING</constant>, + <constant>SD_EVENT_EXITING</constant>, + <constant>SD_EVENT_FINISHED</constant>, +};</funcsynopsisinfo> + <funcprototype> <funcdef>int <function>sd_event_prepare</function></funcdef> <paramdef>sd_event *<parameter>event</parameter></paramdef> @@ -62,7 +81,7 @@ <funcprototype> <funcdef>int <function>sd_event_wait</function></funcdef> <paramdef>sd_event *<parameter>event</parameter></paramdef> - <paramdef>uint64_t <parameter>timeout</parameter></paramdef> + <paramdef>uint64_t <parameter>usec</parameter></paramdef> </funcprototype> <funcprototype> @@ -70,66 +89,193 @@ <paramdef>sd_event *<parameter>event</parameter></paramdef> </funcprototype> + <funcprototype> + <funcdef>int <function>sd_event_get_state</function></funcdef> + <paramdef>sd_event *<parameter>event</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_get_iteration</function></funcdef> + <paramdef>sd_event *<parameter>event</parameter></paramdef> + <paramdef>uint64_t *<parameter>ret</parameter></paramdef> + </funcprototype> + </funcsynopsis> </refsynopsisdiv> <refsect1> <title>Description</title> - <para>Functions described here form parts of an event loop.</para> - - <para><function>sd_event_prepare</function> checks for pending + <para>The low-level <function>sd_event_prepare()</function>, + <function>sd_event_wait()</function> and + <function>sd_event_dispatch()</function> functions may be used to + execute specific phases of an event loop. See + <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>sd_event_loop</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for higher-level functions that execute individual but complete + iterations of an event loop or run it continuously.</para> + + <para><function>sd_event_prepare()</function> checks for pending events and arms necessary timers. If any events are ready to be - processed, it returns a positive value, and the events should be - processed with <function>sd_event_dispatch</function>. - <function>sd_event_dispatch</function> runs a handler for one of - the events from the sources with the highest priority. On success, - <function>sd_event_dispatch</function> returns either 0, which - means that the loop is finished, or a positive value, which means - that the loop is again in the initial state and - <function>sd_event_prepare</function> should be called again. - </para> + processed ("pending"), it returns a positive, non-zero value, and the caller + should process these events with + <function>sd_event_dispatch()</function>.</para> + + <para><function>sd_event_dispatch()</function> dispatches the + highest priority event source that has a pending event. On + success, <function>sd_event_dispatch()</function> returns either + zero, which indicates that no further event sources may be + dispatched and exiting of the event loop was requested via + <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>; + or a positive non-zero value, which means that an event source was + dispatched and the loop returned to its initial state, and the + caller should initiate the next event loop iteration by invoking + <function>sd_event_prepare()</function> again.</para> + + <para>In case <function>sd_event_prepare()</function> returned + zero, <function>sd_event_wait()</function> should be called to + wait for further events or a timeout. If any events are ready to + be processed, it returns a positive, non-zero value, and the + events should be dispatched with + <function>sd_event_dispatch()</function>. Otherwise, the event + loop returned to its initial state and the next event loop + iteration should be initiated by invoking + <function>sd_event_prepare()</function> again.</para> + + <para><function>sd_event_get_state()</function> may be used to + determine the state the event loop is currently in. It returns one + of the states described below.</para> + + <para><function>sd_event_get_iteration()</function> may be used to determine the current iteration of the event + loop. It returns an unsigned 64bit integer containing a counter that increases monotonically with each iteration of + the event loop, starting with 0. The counter is increased at the time of the + <function>sd_event_prepare()</function> invocation.</para> + + <para>All five functions take, as the first argument, the event loop object <parameter>event</parameter> that has + been created with <function>sd_event_new()</function>. The timeout for <function>sd_event_wait()</function> is + specified in <parameter>usec</parameter> in microseconds. <constant>(uint64_t) -1</constant> may be used to + specify an infinite timeout.</para> +</refsect1> - <para>In case <function>sd_event_prepare</function> returned 0, - <function>sd_event_wait</function> should be called to wait for - events or a timeout. If any events are ready to be processed, it - returns a positive value, and the events should be processed with - <function>sd_event_dispatch</function>. Otherwise, the loop is - back in the initial state and <function>sd_event_prepare</function> - should be called again.</para> + <refsect1> + <title>State Machine</title> + + <para>The event loop knows the following states, that may be + queried with <function>sd_event_get_state()</function>.</para> + + <variablelist> + <varlistentry> + <term><constant>SD_EVENT_INITIAL</constant></term> + + <listitem><para>The initial state the event loop is in, + before each event loop iteration. Use + <function>sd_event_prepare()</function> to transition the + event loop into the <constant>SD_EVENT_ARMED</constant> or + <constant>SD_EVENT_PENDING</constant> states.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SD_EVENT_PREPARING</constant></term> + + <listitem><para>An event source is currently being prepared, + i.e. the preparation handler is currently being executed, as + set with + <citerefentry><refentrytitle>sd_event_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This + state is only seen in the event source preparation handler + that is invoked from the + <function>sd_event_prepare()</function> call and is + immediately followed by <constant>SD_EVENT_ARMED</constant> or + <constant>SD_EVENT_PENDING</constant>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SD_EVENT_ARMED</constant></term> + + <listitem><para><function>sd_event_prepare()</function> has + been called and no event sources were ready to be + dispatched. Use <function>sd_event_wait()</function> to wait + for new events, and transition into + <constant>SD_EVENT_PENDING</constant> or back into + <constant>SD_EVENT_INITIAL</constant>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SD_EVENT_PENDING</constant></term> + + <listitem><para><function>sd_event_prepare()</function> or + <function>sd_event_wait()</function> have been called and + there were event sources with events pending. Use + <function>sd_event_dispatch()</function> to dispatch the + highest priority event source and transition back to + <constant>SD_EVENT_INITIAL</constant>, or + <constant>SD_EVENT_FINISHED</constant>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SD_EVENT_RUNNING</constant></term> + + <listitem><para>A regular event source is currently being + dispatched. This state is only seen in the event source + handler that is invoked from the + <function>sd_event_dispatch()</function> call, and is + immediately followed by <constant>SD_EVENT_INITIAL</constant> + or <constant>SD_EVENT_FINISHED</constant> as soon the event + source handler returns. Note that during dispatching of exit + event sources the <constant>SD_EVENT_EXITING</constant> state + is seen instead.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SD_EVENT_EXITING</constant></term> + + <listitem><para>Similar to + <constant>SD_EVENT_RUNNING</constant> but is the state in + effect while dispatching exit event sources. It is followed by + <constant>SD_EVENT_INITIAL</constant> or + <constant>SD_EVENT_FINISHED</constant> as soon as the event + handler returns.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SD_EVENT_FINISHED</constant></term> + + <listitem><para>The event loop has exited. All exit event + sources have run. If the event loop is in this state it serves + no purpose anymore, and should be freed.</para></listitem> + </varlistentry> + + </variablelist> + + <para>A simplified flow chart of the states and the calls to + transition between them is shown below. Note that + <constant>SD_EVENT_PREPARING</constant>, + <constant>SD_EVENT_RUNNING</constant> and + <constant>SD_EVENT_EXITING</constant> are not shown here.</para> <programlisting> - ┌──────────┐ - │ initial ├──←←←←←←←←←←←←←←←←←←←─┐ - └───┬──────┘ ↑ - │ ↑ - sd_event_prepare ┌─────────┐ ↑ - ├ 0 →→→→→→→──┤ armed │ ↑ - 1 └───┬─────┘ ↑ - ↓ │ ↑ - ↓ sd_event_wait ↑ - ├───←←←←←←←─── 1 ┴─ 0 →→→→→→→─┘ - ┌───┴──────┐ ↑ - │ pending │ ↑ - └───┬──────┘ ↑ - │ ↑ - sd_event_dispatch ↑ - ↓ ↑ - ├ 1 ──────────→→→→→→→─────────┘ - 0 - ↓ - ┌───┴──────┐ - │ finished │ - └──────────┘ + INITIAL -<---<---<---<---<---<---<---<---<---<---<---<---\ + | | + | ^ + | | + v ret == 0 | + sd_event_prepare() >--->--->--->--->- ARMED | + | | ^ + | ret > 0 | | + | | | + v v ret == 0 | + PENDING <---<---<---<---<---< sd_event_wait() >--->--->--+ + | ret > 0 ^ + | | + | | + v | + sd_event_dispatch() >--->--->--->--->--->--->--->--->--->--->/ + | ret > 0 + | ret == 0 + | + v + FINISHED </programlisting> - - <para>All three functions as the first argument take the event - loop object <parameter>event</parameter> that is created with with - <function>sd_event_new</function>. The timeout for - <function>sd_event_wait</function> is specified with - <parameter>timeout</parameter> in milliseconds. - <constant>(uint64_t) -1</constant> may be used to specify an - infinite timeout.</para> </refsect1> <refsect1> @@ -137,13 +283,15 @@ <para>On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style error code. In case - of <function>sd_event_prepare</function> and - <function>sd_event_wait</function> a positive value means that - events are ready to be processed and 0 means that no events are - ready. In case of <function>sd_event_dispatch</function> a - positive value means that the loop is again in the initial state - and 0 means the loop is finished. For any of those functions, a - negative return value means the loop must be aborted.</para> + of <function>sd_event_prepare()</function> and + <function>sd_event_wait()</function>, a positive, non-zero return + code indicates that events are ready to be processed and zero + indicates that no events are ready. In case of + <function>sd_event_dispatch()</function>, a positive, non-zero + return code indicates that the event loop returned to its initial + state and zero indicates the event loop has + exited. <function>sd_event_get_state()</function> returns a + positive or zero state on success.</para> </refsect1> <refsect1> @@ -155,8 +303,8 @@ <varlistentry> <term><constant>-EINVAL</constant></term> - <listitem><para>Parameter <parameter>event</parameter> is - <constant>NULL</constant>.</para></listitem> + <listitem><para>The <parameter>event</parameter> parameter is + invalid or <constant>NULL</constant>.</para></listitem> </varlistentry> <varlistentry> @@ -182,17 +330,10 @@ </variablelist> - <para>Other errors are possible too.</para> + <para>Other errors are possible, too.</para> </refsect1> - <refsect1> - <title>Notes</title> - - <para>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> - </refsect1> + <xi:include href="libsystemd-pkgconfig.xml" /> <refsect1> <title>See Also</title> @@ -200,13 +341,15 @@ <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_run</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_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_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> </para> </refsect1> diff --git a/man/sd_get_seats.xml b/man/sd_get_seats.xml index 4390d36ebe..37eb3fc894 100644 --- a/man/sd_get_seats.xml +++ b/man/sd_get_seats.xml @@ -115,6 +115,29 @@ 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 input parameter was invalid (out of range, + or NULL, where that is not accepted).</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + <refsect1> <title>Notes</title> diff --git a/man/sd_id128_get_machine.xml b/man/sd_id128_get_machine.xml index 2ad1f8f728..9a86c24aed 100644 --- a/man/sd_id128_get_machine.xml +++ b/man/sd_id128_get_machine.xml @@ -45,6 +45,7 @@ <refnamediv> <refname>sd_id128_get_machine</refname> <refname>sd_id128_get_boot</refname> + <refname>sd_id128_get_invocation</refname> <refpurpose>Retrieve 128-bit IDs</refpurpose> </refnamediv> @@ -62,6 +63,11 @@ <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> + </funcsynopsis> </refsynopsisdiv> @@ -83,11 +89,15 @@ for more information. This function also internally caches the returned ID to make this call a cheap operation.</para> - <para>Note that <function>sd_id128_get_boot()</function> always - returns a UUID v4 compatible ID. - <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 + <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 + variable that the service manager sets when activating a service, see + <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_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 <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> @@ -107,11 +117,10 @@ <refsect1> <title>Notes</title> - <para>The <function>sd_id128_get_machine()</function> and - <function>sd_id128_get_boot()</function> interfaces are available - as a shared library, which can be compiled and linked to with the - <literal>libsystemd</literal> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> + <para>The <function>sd_id128_get_machine()</function>, <function>sd_id128_get_boot()</function> and + <function>sd_id128_get_invocation()</function> interfaces are available as a shared library, which can be compiled + and linked to with the <literal>libsystemd</literal> <citerefentry + project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para> </refsect1> <refsect1> @@ -121,8 +130,9 @@ <citerefentry><refentrytitle>systemd</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>random</refentrytitle><manvolnum>4</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_id128_randomize</refentrytitle><manvolnum>3</manvolnum></citerefentry> + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_id128_randomize</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/sd_id128_to_string.xml b/man/sd_id128_to_string.xml index e70c80892e..927d1ad5f2 100644 --- a/man/sd_id128_to_string.xml +++ b/man/sd_id128_to_string.xml @@ -74,13 +74,11 @@ lowercase hexadecimal digits and be terminated by a <constant>NUL</constant> byte.</para> - <para><function>sd_id128_from_string()</function> implements the - reverse operation: it takes a 33 character string with 32 - hexadecimal digits (either lowercase or uppercase, terminated by - <constant>NUL</constant>) and parses them back into a 128-bit ID - returned in <parameter>ret</parameter>. Alternatively, this call - can also parse a 37-character string with a 128-bit ID formatted - as RFC UUID.</para> + <para><function>sd_id128_from_string()</function> implements the reverse operation: it takes a 33 character string + with 32 hexadecimal digits (either lowercase or uppercase, terminated by <constant>NUL</constant>) and parses them + back into a 128-bit ID returned in <parameter>ret</parameter>. Alternatively, this call can also parse a + 37-character string with a 128-bit ID formatted as RFC UUID. If <parameter>ret</parameter> is passed as NULL the + function will validate the passed ID string, but not actually return it in parsed form.</para> <para>For more information about the <literal>sd_id128_t</literal> type see diff --git a/man/sd_is_fifo.xml b/man/sd_is_fifo.xml index 627cb87aaf..7ff02cbfec 100644 --- a/man/sd_is_fifo.xml +++ b/man/sd_is_fifo.xml @@ -117,10 +117,10 @@ whether the specified file descriptor refers to a socket. If the <parameter>family</parameter> parameter is not <constant>AF_UNSPEC</constant>, it is checked whether the socket - is of the specified family (AF_UNIX, <constant>AF_INET</constant>, - ...). If the <parameter>type</parameter> parameter is not 0, it is - checked whether the socket is of the specified type - (<constant>SOCK_STREAM</constant>, + is of the specified family (<constant>AF_UNIX</constant>, + <constant>AF_INET</constant>, ...). If the <parameter>type</parameter> + parameter is not 0, it is checked whether the socket is of the + specified type (<constant>SOCK_STREAM</constant>, <constant>SOCK_DGRAM</constant>, ...). If the <parameter>listening</parameter> parameter is positive, it is checked whether the socket is in accepting mode, i.e. diff --git a/man/sd_journal_add_match.xml b/man/sd_journal_add_match.xml index 420f56356a..98415d53fd 100644 --- a/man/sd_journal_add_match.xml +++ b/man/sd_journal_add_match.xml @@ -88,11 +88,19 @@ <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> and <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - Matches are of the form <literal>FIELD=value</literal>, where the - field part is a short uppercase string consisting only of 0-9, A-Z - and the underscore. It may not begin with two underscores or be - the empty string. The value part may be any value, including - binary. If a match is applied, only entries with this field set + Parameter <parameter>data</parameter> must be of the form + <literal><replaceable>FIELD</replaceable>=<replaceable>value</replaceable></literal>, + where the <replaceable>FIELD</replaceable> part is a short uppercase string consisting only + of 0–9, A–Z and the underscore; it may not begin with two underscores or be the empty + string. The <replaceable>value</replaceable> part may be anything, including binary. Parameter + <parameter>size</parameter> specifies the number of bytes in <parameter>data</parameter> + (i.e. the length of <replaceable>FIELD</replaceable>, plus one, plus the length of + <replaceable>value</replaceable>). Parameter <parameter>size</parameter> may also be + specified as <constant>0</constant>, in which case <parameter>data</parameter> + must be a <constant>NUL</constant>-terminated string, and the bytes before the terminating + zero are used as the match.</para> + + <para>If a match is applied, only entries with this field set will be iterated. Multiple matches may be active at the same time: If they apply to different fields, only entries with both fields set like this will be iterated. If they apply to the same fields, diff --git a/man/sd_journal_enumerate_fields.xml b/man/sd_journal_enumerate_fields.xml new file mode 100644 index 0000000000..fa5884106b --- /dev/null +++ b/man/sd_journal_enumerate_fields.xml @@ -0,0 +1,161 @@ +<?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"> + +<!-- + This file is part of systemd. + + Copyright 2016 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_journal_enumerate_fields"> + + <refentryinfo> + <title>sd_journal_enumerate_fields</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_journal_enumerate_fields</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_enumerate_fields</refname> + <refname>sd_journal_restart_fields</refname> + <refname>SD_JOURNAL_FOREACH_FIELD</refname> + <refpurpose>Read used field names from the journal</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_enumerate_fields</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>const char **<parameter>field</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void <function>sd_journal_restart_fields</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef><function>SD_JOURNAL_FOREACH_FIELD</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>const char *<parameter>field</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_enumerate_fields()</function> may be used to iterate through all field names used in the + opened journal files. On each invocation the next field name is returned. The order of the returned field names is + not defined. It takes two arguments: the journal context object, plus a pointer to a constant string pointer where + the field name is stored in. The returned data is in a read-only memory map and is only valid until the next + invocation of <function>sd_journal_enumerate_fields()</function>. Note that this call is subject to the data field + size threshold as controlled by <function>sd_journal_set_data_threshold()</function>.</para> + + <para><function>sd_journal_restart_fields()</function> resets the field name enumeration index to the beginning of + the list. The next invocation of <function>sd_journal_enumerate_fields()</function> will return the first field + name again.</para> + + <para>The <function>SD_JOURNAL_FOREACH_FIELD()</function> macro may be used as a handy wrapper around + <function>sd_journal_restart_fields()</function> and <function>sd_journal_enumerate_fields()</function>.</para> + + <para>These functions currently are not influenced by matches set with <function>sd_journal_add_match()</function> + but this might change in a later version of this software.</para> + + <para>To retrieve the possible values a specific field can take use + <citerefentry><refentrytitle>sd_journal_query_unique</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>sd_journal_enumerate_fields()</function> returns a + positive integer if the next field name has been read, 0 when no + more field names are known, or a negative errno-style error code. + <function>sd_journal_restart_fields()</function> returns + nothing.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_journal_enumerate_fields()</function> and <function>sd_journal_restart_fields()</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> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para>Use the <function>SD_JOURNAL_FOREACH_FIELD</function> macro to iterate through all field names in use in the + current journal.</para> + + <programlisting>#include <stdio.h> +#include <string.h> +#include <systemd/sd-journal.h> + +int main(int argc, char *argv[]) { + sd_journal *j; + const char *field; + 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; + } + SD_JOURNAL_FOREACH_FIELD(j, field) + printf("%s\n", field); + sd_journal_close(j); + return 0; +}</programlisting> + + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_query_unique</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_journal_get_data.xml b/man/sd_journal_get_data.xml index 1afbd7371c..1321114de0 100644 --- a/man/sd_journal_get_data.xml +++ b/man/sd_journal_get_data.xml @@ -113,7 +113,7 @@ <function>sd_journal_get_data()</function> or <function>sd_journal_enumerate_data()</function>, or the read pointer is altered. Note that the data returned will be prefixed - with the field name and '='. Also note that by default data fields + with the field name and '='. Also note that, by default, data fields larger than 64K might get truncated to 64K. This threshold may be changed and turned off with <function>sd_journal_set_data_threshold()</function> (see @@ -148,10 +148,10 @@ <function>sd_journal_enumerate_unique()</function>. This threshold is a hint only: it indicates that the client program is interested only in the initial parts of the data fields, up to the threshold - in size -- but the library might still return larger data objects. + in size — but the library might still return larger data objects. That means applications should not rely exclusively on this setting to limit the size of the data fields returned, but need to - apply a explicit size limit on the returned data as well. This + apply an explicit size limit on the returned data as well. This threshold defaults to 64K by default. To retrieve the complete data fields this threshold should be turned off by setting it to 0, so that the library always returns the complete data objects. diff --git a/man/sd_journal_get_fd.xml b/man/sd_journal_get_fd.xml index 3a38f733ab..61293f7f99 100644 --- a/man/sd_journal_get_fd.xml +++ b/man/sd_journal_get_fd.xml @@ -187,7 +187,7 @@ else { certain latency. This call will return a positive value if the journal changes are detected immediately and zero when they need to be polled for and hence might be noticed only with a certain - latency. Note that there's usually no need to invoke this function + latency. Note that there is usually no need to invoke this function directly as <function>sd_journal_get_timeout()</function> on these file systems will ask for timeouts explicitly anyway.</para> </refsect1> diff --git a/man/sd_journal_has_runtime_files.xml b/man/sd_journal_has_runtime_files.xml new file mode 100644 index 0000000000..237e649206 --- /dev/null +++ b/man/sd_journal_has_runtime_files.xml @@ -0,0 +1,95 @@ +<?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"> + +<!-- + This file is part of systemd. + + Copyright 2016 Jan Synáček + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_journal_has_runtime_files"> + + <refentryinfo> + <title>sd_journal_has_runtime_files</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Jan</firstname> + <surname>Synáček</surname> + <email>jan.synacek@gmail.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_journal_has_runtime_files</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_has_runtime_files</refname> + <refname>sd_journal_has_persistent_files</refname> + <refpurpose>Query availability of runtime or persistent journal files.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_has_runtime_files</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_has_persistent_files</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_has_runtime_files()</function> returns a positive value + if runtime journal files (present in /run/systemd/journal/) have been found. + Otherwise returns 0.</para> + + <para><function>sd_journal_has_persistent_files()</function> returns a positive value + if persistent journal files (present in /var/log/journal/) have been found. + Otherwise returns 0.</para> + </refsect1> + + <refsect1> + <title>Return value</title> + <para>Both <function>sd_journal_has_runtime_files()</function> + and <function>sd_journal_has_persistent_files()</function> return -EINVAL + if their argument is NULL. + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_journal_open.xml b/man/sd_journal_open.xml index fb572802a3..74e67023b5 100644 --- a/man/sd_journal_open.xml +++ b/man/sd_journal_open.xml @@ -45,14 +45,16 @@ <refnamediv> <refname>sd_journal_open</refname> <refname>sd_journal_open_directory</refname> + <refname>sd_journal_open_directory_fd</refname> <refname>sd_journal_open_files</refname> - <refname>sd_journal_open_container</refname> + <refname>sd_journal_open_files_fd</refname> <refname>sd_journal_close</refname> <refname>sd_journal</refname> <refname>SD_JOURNAL_LOCAL_ONLY</refname> <refname>SD_JOURNAL_RUNTIME_ONLY</refname> <refname>SD_JOURNAL_SYSTEM</refname> <refname>SD_JOURNAL_CURRENT_USER</refname> + <refname>SD_JOURNAL_OS_ROOT</refname> <refpurpose>Open the system journal for reading</refpurpose> </refnamediv> @@ -74,6 +76,13 @@ </funcprototype> <funcprototype> + <funcdef>int <function>sd_journal_open_directory_fd</function></funcdef> + <paramdef>sd_journal **<parameter>ret</parameter></paramdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>flags</parameter></paramdef> + </funcprototype> + + <funcprototype> <funcdef>int <function>sd_journal_open_files</function></funcdef> <paramdef>sd_journal **<parameter>ret</parameter></paramdef> <paramdef>const char **<parameter>paths</parameter></paramdef> @@ -81,9 +90,10 @@ </funcprototype> <funcprototype> - <funcdef>int <function>sd_journal_open_container</function></funcdef> + <funcdef>int <function>sd_journal_open_files_fd</function></funcdef> <paramdef>sd_journal **<parameter>ret</parameter></paramdef> - <paramdef>const char *<parameter>machine</parameter></paramdef> + <paramdef>int <parameter>fds[]</parameter></paramdef> + <paramdef>unsigned <parameter>n_fds</parameter></paramdef> <paramdef>int <parameter>flags</parameter></paramdef> </funcprototype> @@ -100,8 +110,8 @@ <para><function>sd_journal_open()</function> opens the log journal for reading. It will find all journal files automatically and interleave them automatically when reading. As first argument it - takes a pointer to a <varname>sd_journal</varname> pointer, which - on success will contain a journal context object. The second + takes a pointer to a <varname>sd_journal</varname> pointer, which, + on success, will contain a journal context object. The second argument is a flags field, which may consist of the following flags ORed together: <constant>SD_JOURNAL_LOCAL_ONLY</constant> makes sure only journal files generated on the local machine will @@ -117,29 +127,31 @@ <constant>SD_JOURNAL_CURRENT_USER</constant> are specified, all journal file types will be opened.</para> - <para><function>sd_journal_open_directory()</function> is similar - to <function>sd_journal_open()</function> but takes an absolute - directory path as argument. All journal files in this directory - will be opened and interleaved automatically. This call also takes - a flags argument, but it must be passed as 0 as no flags are - currently understood for this call.</para> - - <para><function>sd_journal_open_files()</function> is similar to - <function>sd_journal_open()</function> but takes a - <constant>NULL</constant>-terminated list of file paths to open. - All files will be opened and interleaved automatically. This call - also takes a flags argument, but it must be passed as 0 as no - flags are currently understood for this call. Please note that in - the case of a live journal, this function is only useful for - debugging, because individual journal files can be rotated at any - moment, and the opening of specific files is inherently - racy.</para> - - <para><function>sd_journal_open_container()</function> is similar - to <function>sd_journal_open()</function> but opens the journal - files of a running OS container. The specified machine name refers - to a container that is registered with - <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + <para><function>sd_journal_open_directory()</function> is similar to <function>sd_journal_open()</function> but + takes an absolute directory path as argument. All journal files in this directory will be opened and interleaved + automatically. This call also takes a flags argument. The flags parameters accepted by this call are + <constant>SD_JOURNAL_OS_ROOT</constant>, <constant>SD_JOURNAL_SYSTEM</constant>, and + <constant>SD_JOURNAL_CURRENT_USER</constant>. If <constant>SD_JOURNAL_OS_ROOT</constant> is specified, journal + files are searched for below the usual <filename>/var/log/journal</filename> and + <filename>/run/log/journal</filename> relative to the specified path, instead of directly beneath it. + The other two flags limit which files are opened, the same as for <function>sd_journal_open()</function>. + </para> + + <para><function>sd_journal_open_directory_fd()</function> is similar to + <function>sd_journal_open_directory()</function>, but takes a file descriptor referencing a directory in the file + system instead of an absolute file system path.</para> + + <para><function>sd_journal_open_files()</function> is similar to <function>sd_journal_open()</function> but takes a + <constant>NULL</constant>-terminated list of file paths to open. All files will be opened and interleaved + automatically. This call also takes a flags argument, but it must be passed as 0 as no flags are currently + understood for this call. Please note that in the case of a live journal, this function is only useful for + debugging, because individual journal files can be rotated at any moment, and the opening of specific files is + inherently racy.</para> + + <para><function>sd_journal_open_files_fd()</function> is similar to <function>sd_journal_open_files()</function> + but takes an array of open file descriptors that must reference journal files, instead of an array of file system + paths. Pass the array of file descriptors as second argument, and the number of array entries in the third. The + flags parameter must be passed as 0.</para> <para><varname>sd_journal</varname> objects cannot be used in the child after a fork. Functions which take a journal object as an @@ -205,26 +217,6 @@ </refsect1> <refsect1> - <title>History</title> - - <para><function>sd_journal_open()</function>, - <function>sd_journal_close()</function>, - <constant>SD_JOURNAL_LOCAL_ONLY</constant>, - <constant>SD_JOURNAL_RUNTIME_ONLY</constant>, - <constant>SD_JOURNAL_SYSTEM_ONLY</constant> were added in - systemd-38.</para> - - <para><function>sd_journal_open_directory()</function> was added - in systemd-187.</para> - - <para><constant>SD_JOURNAL_SYSTEM</constant>, - <constant>SD_JOURNAL_CURRENT_USER</constant>, and - <function>sd_journal_open_files()</function> were added in - systemd-205. <constant>SD_JOURNAL_SYSTEM_ONLY</constant> was - deprecated.</para> - </refsect1> - - <refsect1> <title>See Also</title> <para> diff --git a/man/sd_journal_print.xml b/man/sd_journal_print.xml index 0cd0b45b9a..76542527fc 100644 --- a/man/sd_journal_print.xml +++ b/man/sd_journal_print.xml @@ -93,27 +93,21 @@ <refsect1> <title>Description</title> - <para><function>sd_journal_print()</function> may be used to - submit simple, plain text log entries to the system journal. The - first argument is a priority value. This is followed by a format - string and its parameters, similar to - <citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> - or + <para><function>sd_journal_print()</function> may be used to submit simple, plain text log entries to the system + journal. The first argument is a priority value. This is followed by a format string and its parameters, similar to + <citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> or <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - The priority value is one of - <constant>LOG_EMERG</constant>, - <constant>LOG_ALERT</constant>, - <constant>LOG_CRIT</constant>, - <constant>LOG_ERR</constant>, - <constant>LOG_WARNING</constant>, - <constant>LOG_NOTICE</constant>, - <constant>LOG_INFO</constant>, - <constant>LOG_DEBUG</constant>, as defined in - <filename>syslog.h</filename>, see - <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for details. It is recommended to use this call to submit log - messages in the application locale or system locale and in UTF-8 - format, but no such restrictions are enforced.</para> + The priority value is one of <constant>LOG_EMERG</constant>, <constant>LOG_ALERT</constant>, + <constant>LOG_CRIT</constant>, <constant>LOG_ERR</constant>, <constant>LOG_WARNING</constant>, + <constant>LOG_NOTICE</constant>, <constant>LOG_INFO</constant>, <constant>LOG_DEBUG</constant>, as defined in + <filename>syslog.h</filename>, see <citerefentry + project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> for details. It is + recommended to use this call to submit log messages in the application locale or system locale and in UTF-8 format, + but no such restrictions are enforced. Note that log messages written using this function are generally not + expected to end in a new-line character. However, as all trailing whitespace (including spaces, new-lines, + tabulators and carriage returns) are automatically stripped from the logged string, it is acceptable to specify one + (or more). Empty lines (after trailing whitespace removal) are suppressed. On non-empty lines, leading whitespace + (as well as inner whitespace) is left unmodified. </para> <para><function>sd_journal_printv()</function> is similar to <function>sd_journal_print()</function> but takes a variable @@ -123,40 +117,31 @@ for more information) instead of the format string. It is otherwise equivalent in behavior.</para> - <para><function>sd_journal_send()</function> may be used to submit - structured log entries to the system journal. It takes a series of - format strings, each immediately followed by their associated - parameters, terminated by <constant>NULL</constant>. The strings - passed should be of the format <literal>VARIABLE=value</literal>. - The variable name must be in uppercase and consist only of - characters, numbers and underscores, and may not begin with an - underscore. (All assignments that do not follow this syntax will - be ignored.) The value can be of any size and format. It is highly - recommended to submit text strings formatted in the UTF-8 - character encoding only, and submit binary fields only when - formatting in UTF-8 strings is not sensible. A number of well - known fields are defined, see - <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details, but additional application defined fields may be - used. A variable may be assigned more than one value per - entry.</para> - - <para><function>sd_journal_sendv()</function> is similar to - <function>sd_journal_send()</function> but takes an array of - <varname>struct iovec</varname> (as defined in - <filename>uio.h</filename>, see - <citerefentry project='man-pages'><refentrytitle>readv</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for details) instead of the format string. Each structure should - reference one field of the entry to submit. The second argument - specifies the number of structures in the array. - <function>sd_journal_sendv()</function> is particularly useful to - submit binary objects to the journal where that is - necessary.</para> + <para><function>sd_journal_send()</function> may be used to submit structured log entries to the system journal. It + takes a series of format strings, each immediately followed by their associated parameters, terminated by + <constant>NULL</constant>. The strings passed should be of the format <literal>VARIABLE=value</literal>. The + variable name must be in uppercase and consist only of characters, numbers and underscores, and may not begin with + an underscore. (All assignments that do not follow this syntax will be ignored.) The value can be of any size and + format. It is highly recommended to submit text strings formatted in the UTF-8 character encoding only, and submit + binary fields only when formatting in UTF-8 strings is not sensible. A number of well-known fields are defined, see + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry> for + details, but additional application defined fields may be used. A variable may be assigned more than one value per + entry. If this function is used, trailing whitespace is automatically removed from each formatted field.</para> + + <para><function>sd_journal_sendv()</function> is similar to <function>sd_journal_send()</function> but takes an + array of <varname>struct iovec</varname> (as defined in <filename>uio.h</filename>, see <citerefentry + project='man-pages'><refentrytitle>readv</refentrytitle><manvolnum>3</manvolnum></citerefentry> for details) + instead of the format string. Each structure should reference one field of the entry to submit. The second argument + specifies the number of structures in the array. <function>sd_journal_sendv()</function> is particularly useful to + submit binary objects to the journal where that is necessary. Note that this function wil not strip trailing + whitespace of the passed fields, but passes the specified data along unmodified. This is different from both + <function>sd_journal_print()</function> and <function>sd_journal_send()</function> described above, which are based + on format strings, and do strip trailing whitespace.</para> <para><function>sd_journal_perror()</function> is a similar to <citerefentry project='die-net'><refentrytitle>perror</refentrytitle><manvolnum>3</manvolnum></citerefentry> and writes a message to the journal that consists of the passed - string, suffixed with ": " and a human readable representation of + string, suffixed with ": " and a human-readable representation of the current error code stored in <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If the message string is passed as <constant>NULL</constant> or @@ -174,8 +159,8 @@ <programlisting>sd_journal_print(LOG_INFO, "Hello World, this is PID %lu!", (unsigned long) getpid()); sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid(), - "PRIORITY=%i", LOG_INFO, - NULL);</programlisting> + "PRIORITY=%i", LOG_INFO, + NULL);</programlisting> <para>Note that these calls implicitly add fields for the source file, function name and code line where invoked. This is diff --git a/man/sd_journal_query_unique.xml b/man/sd_journal_query_unique.xml index ac0e5f633f..dbff55c105 100644 --- a/man/sd_journal_query_unique.xml +++ b/man/sd_journal_query_unique.xml @@ -128,6 +128,11 @@ <para>Note that these functions currently are not influenced by matches set with <function>sd_journal_add_match()</function> but this might change in a later version of this software.</para> + + <para>To enumerate all field names currently in use (and thus all suitable field parameters for + <function>sd_journal_query_unique()</function>), use the + <citerefentry><refentrytitle>sd_journal_enumerate_fields</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call.</para> </refsect1> <refsect1> @@ -167,25 +172,25 @@ #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; + 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> </refsect1> @@ -198,6 +203,7 @@ int main(int argc, char *argv[]) { <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_enumerate_fields</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> diff --git a/man/sd_listen_fds.xml b/man/sd_listen_fds.xml index 9b9705eb2e..93bf8d853f 100644 --- a/man/sd_listen_fds.xml +++ b/man/sd_listen_fds.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -45,6 +45,7 @@ <refnamediv> <refname>sd_listen_fds</refname> + <refname>sd_listen_fds_with_names</refname> <refname>SD_LISTEN_FDS_START</refname> <refpurpose>Check for file descriptors passed by the system manager</refpurpose> </refnamediv> @@ -59,23 +60,26 @@ <funcdef>int <function>sd_listen_fds</function></funcdef> <paramdef>int <parameter>unset_environment</parameter></paramdef> </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_listen_fds_with_names</function></funcdef> + <paramdef>int <parameter>unset_environment</parameter></paramdef> + <paramdef>char*** <parameter>names</parameter></paramdef> + </funcprototype> </funcsynopsis> </refsynopsisdiv> <refsect1> <title>Description</title> - <para><function>sd_listen_fds()</function> shall be called by a - daemon to check for file descriptors passed by the init system as - part of the socket-based activation logic.</para> - - <para>If the <parameter>unset_environment</parameter> parameter is - non-zero, <function>sd_listen_fds()</function> will unset the - <varname>$LISTEN_FDS</varname> and <varname>$LISTEN_PID</varname> - environment variables before returning (regardless of whether the - function call itself succeeded or not). Further calls to - <function>sd_listen_fds()</function> will then fail, but the - variables are no longer inherited by child processes.</para> + <para><function>sd_listen_fds()</function> may be invoked by a + daemon to check for file descriptors passed by the service manager as + part of the socket-based activation logic. It returns the number + of received file descriptors. If no file descriptors have been + received, zero is returned. The first file descriptor may be found + at file descriptor number 3 + (i.e. <constant>SD_LISTEN_FDS_START</constant>), the remaining + descriptors follow at 4, 5, 6, ..., if any.</para> <para>If a daemon receives more than one file descriptor, they will be passed in the same order as configured in the systemd @@ -100,7 +104,7 @@ passed file descriptors to avoid further inheritance to children of the calling process.</para> - <para>If multiple socket units activate the same service the order + <para>If multiple socket units activate the same service, the order of the file descriptors passed to its main process is undefined. If additional file descriptors have been passed to the service manager using @@ -108,12 +112,86 @@ <literal>FDSTORE=1</literal> messages, these file descriptors are passed last, in arbitrary order, and with duplicates removed.</para> + + <para>If the <parameter>unset_environment</parameter> parameter is + non-zero, <function>sd_listen_fds()</function> will unset the + <varname>$LISTEN_FDS</varname>, <varname>$LISTEN_PID</varname> and + <varname>$LISTEN_FDNAMES</varname> environment variables before + returning (regardless of whether the function call itself + succeeded or not). Further calls to + <function>sd_listen_fds()</function> will then return zero, but the + variables are no longer inherited by child processes.</para> + + <para><function>sd_listen_fds_with_names()</function> is like + <function>sd_listen_fds()</function>, but optionally also returns + an array of strings with identification names for the passed file + descriptors, if that is available and the + <parameter>names</parameter> parameter is non-NULL. This + information is read from the <varname>$LISTEN_FDNAMES</varname> + variable, which may contain a colon-separated list of names. For + socket-activated services, these names may be configured with the + <varname>FileDescriptorName=</varname> setting in socket unit + files, see + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. For file descriptors pushed into the file descriptor + store (see above), the name is set via the + <varname>FDNAME=</varname> field transmitted via + <function>sd_pid_notify_with_fds()</function>. The primary usecase + for these names are services which accept a variety of file + descriptors which are not recognizable with functions like + <function>sd_is_socket()</function> alone, and thus require + identification via a name. It is recommended to rely on named file + descriptors only if identification via + <function>sd_is_socket()</function> and related calls is not + sufficient. Note that the names used are not unique in any + way. The returned array of strings has as many entries as file + descriptors have been received, plus a final NULL pointer + terminating the array. The caller needs to free the array itself + and each of its elements with libc's <function>free()</function> + call after use. If the <parameter>names</parameter> parameter is + NULL, the call is entirely equivalent to + <function>sd_listen_fds()</function>.</para> + + <para>Under specific conditions, the following automatic file + descriptor names are returned: + + <table> + <title> + <command>Special names</command> + </title> + + <tgroup cols='2'> + <thead> + <row> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>unknown</literal></entry> + <entry>The process received no name for the specific file descriptor from the service manager.</entry> + </row> + + <row> + <entry><literal>stored</literal></entry> + <entry>The file descriptor originates in the service manager's per-service file descriptor store, and the <varname>FDNAME=</varname> field was absent when the file descriptor was submitted to the service manager.</entry> + </row> + + <row> + <entry><literal>connection</literal></entry> + <entry>The service was activated in per-connection style using <varname>Accept=yes</varname> in the socket unit file, and the file descriptor is the connection socket.</entry> + </row> + </tbody> + </tgroup> + </table> + </para> </refsect1> <refsect1> <title>Return Value</title> - <para>On failure, this call returns a negative errno-style error + <para>On failure, these calls returns a negative errno-style error code. If <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname> was not set or was not correctly set for this daemon and hence no file @@ -128,13 +206,16 @@ <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> - <para>Internally, this function checks whether the - <varname>$LISTEN_PID</varname> environment variable equals the - daemon PID. If not, it returns immediately. Otherwise, it parses - the number passed in the <varname>$LISTEN_FDS</varname> + <para>Internally, <function>sd_listen_fds()</function> checks + whether the <varname>$LISTEN_PID</varname> environment variable + equals the daemon PID. If not, it returns immediately. Otherwise, + it parses the number passed in the <varname>$LISTEN_FDS</varname> environment variable, then sets the FD_CLOEXEC flag for the parsed number of file descriptors starting from SD_LISTEN_FDS_START. - Finally, it returns the parsed number.</para> + Finally, it returns the parsed + number. <function>sd_listen_fds_with_names()</function> does the + same but also parses <varname>$LISTEN_FDNAMES</varname> if + set.</para> </refsect1> <refsect1> @@ -144,15 +225,14 @@ <varlistentry> <term><varname>$LISTEN_PID</varname></term> <term><varname>$LISTEN_FDS</varname></term> + <term><varname>$LISTEN_FDNAMES</varname></term> - <listitem><para>Set by the init system - for supervised processes that use - socket-based activation. This - environment variable specifies the - data - <function>sd_listen_fds()</function> - parses. See above for - details.</para></listitem> + <listitem><para>Set by the service manager for supervised + processes that use socket-based activation. This environment + variable specifies the data + <function>sd_listen_fds()</function> and + <function>sd_listen_fds_with_names()</function> parses. See + above for details.</para></listitem> </varlistentry> </variablelist> </refsect1> @@ -167,6 +247,7 @@ <citerefentry><refentrytitle>sd_is_socket</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_is_socket_inet</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_is_socket_unix</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> diff --git a/man/sd_login_monitor_new.xml b/man/sd_login_monitor_new.xml index a7b47a3207..5625ab9207 100644 --- a/man/sd_login_monitor_new.xml +++ b/man/sd_login_monitor_new.xml @@ -45,6 +45,7 @@ <refnamediv> <refname>sd_login_monitor_new</refname> <refname>sd_login_monitor_unref</refname> + <refname>sd_login_monitor_unrefp</refname> <refname>sd_login_monitor_flush</refname> <refname>sd_login_monitor_get_fd</refname> <refname>sd_login_monitor_get_events</refname> @@ -69,6 +70,11 @@ </funcprototype> <funcprototype> + <funcdef>void <function>sd_login_monitor_unrefp</function></funcdef> + <paramdef>sd_login_monitor **<parameter>m</parameter></paramdef> + </funcprototype> + + <funcprototype> <funcdef>int <function>sd_login_monitor_flush</function></funcdef> <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef> </funcprototype> @@ -121,6 +127,26 @@ descriptor returned by <function>sd_login_monitor_get_fd()</function>.</para> + <para><function>sd_login_monitor_unrefp()</function> is similar to + <function>sd_login_monitor_unref()</function> but takes a pointer + to a pointer to an <type>sd_login_monitor</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>. Note that this function is defined as + inline function. Use a declaration like the following, in order to + allocate a login monitor object that is freed automatically as the + 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)); + … +}</programlisting> + <para><function>sd_login_monitor_flush()</function> may be used to reset the wakeup state of the monitor object. Whenever an event causes the monitor to wake up the event loop via the file @@ -128,6 +154,11 @@ state. If this call is not invoked, the file descriptor will immediately wake up the event loop again.</para> + <para><function>sd_login_monitor_unref()</function> and + <function>sd_login_monitor_unrefp()</function> execute no + operation if the passed in monitor object is + <constant>NULL</constant>.</para> + <para><function>sd_login_monitor_get_fd()</function> may be used to retrieve the file descriptor of the monitor object that may be integrated in an application defined event loop, based around @@ -161,20 +192,20 @@ is no timeout to wait for this will fill in <constant>(uint64_t) -1</constant> instead. Note that <function>poll()</function> takes a relative timeout in milliseconds rather than an absolute timeout - in microseconds. To convert the absolute 'us' timeout into + in microseconds. To convert the absolute 'µs' timeout into relative 'ms', use code like the following:</para> <programlisting>uint64_t t; 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_getttime(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_getttime(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 @@ -204,6 +235,29 @@ else { </refsect1> <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>An input parameter was invalid (out of range, + or NULL, where that is not accepted). The specified category to + watch is not known.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> <title>Notes</title> <para>The <function>sd_login_monitor_new()</function>, diff --git a/man/sd_machine_get_class.xml b/man/sd_machine_get_class.xml index 5b881ccea1..ef604139da 100644 --- a/man/sd_machine_get_class.xml +++ b/man/sd_machine_get_class.xml @@ -56,7 +56,7 @@ <funcprototype> <funcdef>int <function>sd_machine_get_class</function></funcdef> <paramdef>const char* <parameter>machine</parameter></paramdef> - <paramdef>char *<parameter>class</parameter></paramdef> + <paramdef>char **<parameter>class</parameter></paramdef> </funcprototype> <funcprototype> @@ -99,6 +99,35 @@ </refsect1> <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + + <varlistentry> + <term><constant>-ENXIO</constant></term> + + <listitem><para>The specified machine does not exist or is currently not running.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>An input parameter was invalid (out of range, + or NULL, where that is not accepted).</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> <title>Notes</title> <para>The <function>sd_machine_get_class()</function> and diff --git a/man/sd_notify.xml b/man/sd_notify.xml index 14030f56b1..025fbec6c1 100644 --- a/man/sd_notify.xml +++ b/man/sd_notify.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -100,7 +100,7 @@ <para><function>sd_notify()</function> may be called by a service to notify the service manager about state changes. It can be used to send arbitrary information, encoded in an - environment-block-like string. Most importantly it can be used for + environment-block-like string. Most importantly, it can be used for start-up completion notification.</para> <para>If the <parameter>unset_environment</parameter> parameter is @@ -158,7 +158,7 @@ to the service manager that describes the service state. This is free-form and can be used for various purposes: general state feedback, fsck-like programs could pass completion - percentages and failing programs could pass a human readable + percentages and failing programs could pass a human-readable error message. Example: <literal>STATUS=Completed 66% of file system check...</literal></para></listitem> </varlistentry> @@ -229,6 +229,36 @@ below.</para></listitem> </varlistentry> + <varlistentry> + <term>FDNAME=...</term> + + <listitem><para>When used in combination with + <varname>FDSTORE=1</varname>, specifies a name for the + submitted file descriptors. This name is passed to the service + during activation, and may be queried using + <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>. File + descriptors submitted without this field set, will implicitly + get the name <literal>stored</literal> assigned. Note that, if + multiple file descriptors are submitted at once, the specified + name will be assigned to all of them. In order to assign + different names to submitted file descriptors, submit them in + separate invocations of + <function>sd_pid_notify_with_fds()</function>. The name may + consist of any ASCII character, but must not contain control + characters or <literal>:</literal>. It may not be longer than + 255 characters. If a submitted name does not follow these + restrictions, it is ignored.</para></listitem> + </varlistentry> + + <varlistentry> + <term>WATCHDOG_USEC=...</term> + + <listitem><para>Reset <varname>watchdog_usec</varname> value during runtime. + Notice that this is not available when using <function>sd_event_set_watchdog()</function> + or <function>sd_watchdog_enabled()</function>. + Example : <literal>WATCHDOG_USEC=20000000</literal></para></listitem> + </varlistentry> + </variablelist> <para>It is recommended to prefix variable names that are not @@ -253,7 +283,7 @@ use as originating PID for the message as first argument. This is useful to send notification messages on behalf of other processes, provided the appropriate privileges are available. If the PID - argument is specified as 0 the process ID of the calling process + argument is specified as 0, the process ID of the calling process is used, in which case the calls are fully equivalent to <function>sd_notify()</function> and <function>sd_notifyf()</function>.</para> @@ -290,7 +320,7 @@ <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> - <para>Internally, these functions send a single datagram with the + <para>These functions send a single datagram with the state string as payload to the <constant>AF_UNIX</constant> socket referenced in the <varname>$NOTIFY_SOCKET</varname> environment variable. If the first character of @@ -356,9 +386,9 @@ <para>To store an open file descriptor in the service manager, in order to continue operation after a service restart without - losing state use <literal>FDSTORE=1</literal>:</para> + losing state, use <literal>FDSTORE=1</literal>:</para> - <programlisting>sd_pid_notify_with_fds(0, 0, "FDSTORE=1", &fd, 1);</programlisting> + <programlisting>sd_pid_notify_with_fds(0, 0, "FDSTORE=1\nFDNAME=foobar", &fd, 1);</programlisting> </example> </refsect1> @@ -367,9 +397,11 @@ <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/sd_pid_get_session.xml b/man/sd_pid_get_session.xml index 9c6706caf8..806cff34e4 100644 --- a/man/sd_pid_get_session.xml +++ b/man/sd_pid_get_session.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -50,6 +50,7 @@ <refname>sd_pid_get_machine_name</refname> <refname>sd_pid_get_slice</refname> <refname>sd_pid_get_user_slice</refname> + <refname>sd_pid_get_cgroup</refname> <refname>sd_peer_get_session</refname> <refname>sd_peer_get_unit</refname> <refname>sd_peer_get_user_unit</refname> @@ -57,6 +58,7 @@ <refname>sd_peer_get_machine_name</refname> <refname>sd_peer_get_slice</refname> <refname>sd_peer_get_user_slice</refname> + <refname>sd_peer_get_cgroup</refname> <refpurpose>Determine session, unit, owner of a session, container/VM or slice of a specific PID or socket peer</refpurpose> @@ -109,6 +111,12 @@ </funcprototype> <funcprototype> + <funcdef>int <function>sd_pid_get_cgroup</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>char **<parameter>cgroup</parameter></paramdef> + </funcprototype> + + <funcprototype> <funcdef>int <function>sd_peer_get_session</function></funcdef> <paramdef>int <parameter>fd</parameter></paramdef> <paramdef>char **<parameter>session</parameter></paramdef> @@ -149,6 +157,12 @@ <paramdef>int <parameter>fd</parameter></paramdef> <paramdef>char **<parameter>slice</parameter></paramdef> </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_peer_get_cgroup</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>char **<parameter>cgroup</parameter></paramdef> + </funcprototype> </funcsynopsis> </refsynopsisdiv> @@ -162,8 +176,8 @@ not all processes are part of a login session (e.g. system service processes, user processes that are shared between multiple sessions of the same user, or kernel threads). For processes not - being part of a login session this function will fail with - -ENXIO. The returned string needs to be freed with the libc + being part of a login session, this function will fail with + -ENODATA. The returned string needs to be freed with the libc <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> call after use.</para> @@ -174,27 +188,27 @@ unit name is a short string, suitable for usage in file system paths. Note that not all processes are part of a system unit/service (e.g. user processes, or kernel threads). For - processes not being part of a systemd system unit this function - will fail with -ENXIO (More specifically: this call will not work - for kernel threads.) The returned string needs to be freed with - the libc <citerefentry + processes not being part of a systemd system unit, this function + will fail with -ENODATA. (More specifically, this call will not + work for kernel threads.) The returned string needs to be freed + with the libc <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> call after use.</para> <para><function>sd_pid_get_user_unit()</function> may be used to determine the systemd user unit (i.e. user service or scope unit) identifier of a process identified by the specified PID. This is - similar to <function>sd_pid_get_unit()</function> but applies to + similar to <function>sd_pid_get_unit()</function>, but applies to user units instead of system units.</para> <para><function>sd_pid_get_owner_uid()</function> may be used to determine the Unix UID (user identifier) of the owner of the session of a process identified the specified PID. Note that this function will succeed for user processes which are shared between - multiple login sessions of the same user, where + multiple login sessions of the same user, whereas <function>sd_pid_get_session()</function> will fail. For processes not being part of a login session and not being a shared process - of a user this function will fail with -ENXIO.</para> + of a user, this function will fail with -ENODATA.</para> <para><function>sd_pid_get_machine_name()</function> may be used to determine the name of the VM or container is a member of. The @@ -202,8 +216,8 @@ paths. The returned string needs to be freed with the libc <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use. For processes not part of a VM or containers this - function fails with -ENXIO.</para> + call after use. For processes not part of a VM or containers, this + function fails with -ENODATA.</para> <para><function>sd_pid_get_slice()</function> may be used to determine the slice unit the process is a member of. See @@ -213,10 +227,21 @@ <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> call after use.</para> - <para>Similar, <function>sd_pid_get_user_slice()</function> + <para>Similarly, <function>sd_pid_get_user_slice()</function> returns the user slice (as managed by the user's systemd instance) of a process.</para> + <para><function>sd_pid_get_cgroup()</function> returns the control + group path of the specified process, relative to the root of the + hierarchy. Returns the path without trailing slash, except for + processes located in the root control group, where "/" is + returned. To find the actual control group path in the file system, + the returned path needs to be prefixed with + <filename>/sys/fs/cgroup/</filename> (if the unified control group + setup is used), or + <filename>/sys/fs/cgroup/<replaceable>HIERARCHY</replaceable>/</filename> + (if the legacy multi-hierarchy control group setup is used).</para> + <para>If the <varname>pid</varname> parameter of any of these functions is passed as 0, the operation is executed for the calling process.</para> @@ -226,13 +251,14 @@ <function>sd_peer_get_user_unit()</function>, <function>sd_peer_get_owner_uid()</function>, <function>sd_peer_get_machine_name()</function>, - <function>sd_peer_get_slice()</function> and - <function>sd_peer_get_user_slice()</function> calls operate - similar to their PID counterparts, but operate on a connected - AF_UNIX socket and retrieve information about the connected peer - process. Note that these fields are retrieved via - <filename>/proc</filename>, and hence are not suitable for - authorization purposes, as they are subject to races.</para> + <function>sd_peer_get_slice()</function>, + <function>sd_peer_get_user_slice()</function> and + <function>sd_peer_get_cgroup()</function> calls operate similar to + their PID counterparts, but operate on a connected AF_UNIX socket + and retrieve information about the connected peer process. Note + that these fields are retrieved via <filename>/proc</filename>, + and hence are not suitable for authorization purposes, as they are + subject to races.</para> </refsect1> <refsect1> @@ -251,22 +277,36 @@ <variablelist> <varlistentry> - <term><constant>-ENXIO</constant></term> + <term><constant>-ESRCH</constant></term> - <listitem><para>Given field is not specified for the described - process or peer.</para> + <listitem><para>The specified PID does not refer to a running + process.</para> </listitem> </varlistentry> <varlistentry> - <term><constant>-ESRCH</constant></term> + <term><constant>-BADF</constant></term> - <listitem><para>The specified PID does not refer to a running - process.</para> + <listitem><para>The specified socket file descriptor was + invalid.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENODATA</constant></term> + + <listitem><para>The given field is not specified for the described + process or peer.</para> </listitem> </varlistentry> <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>An input parameter was invalid (out of range, + or NULL, where that is not accepted).</para></listitem> + </varlistentry> + + <varlistentry> <term><constant>-ENOMEM</constant></term> <listitem><para>Memory allocation failed.</para></listitem> diff --git a/man/sd_seat_get_active.xml b/man/sd_seat_get_active.xml index 3c57ec9ea4..c5e6ddab02 100644 --- a/man/sd_seat_get_active.xml +++ b/man/sd_seat_get_active.xml @@ -149,13 +149,50 @@ </refsect1> <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + + <varlistentry> + <term><constant>-ENODATA</constant></term> + + <listitem><para>The given field is not specified for the described + seat.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENXIO</constant></term> + + <listitem><para>The specified seat is unknown.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>An input parameter was invalid (out of range, + or NULL, where that is not accepted).</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> <title>Notes</title> <para>The <function>sd_seat_get_active()</function>, <function>sd_seat_get_sessions()</function>, <function>sd_seat_can_multi_session()</function>, <function>sd_seat_can_tty()</function> and - <function>sd_seat_can_grapical()</function> interfaces are + <function>sd_seat_can_graphical()</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> diff --git a/man/sd_session_is_active.xml b/man/sd_session_is_active.xml index 4ca3a6c150..a6076b177a 100644 --- a/man/sd_session_is_active.xml +++ b/man/sd_session_is_active.xml @@ -290,6 +290,43 @@ </refsect1> <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + + <varlistentry> + <term><constant>-ENXIO</constant></term> + + <listitem><para>The specified session does not exist.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENODATA</constant></term> + + <listitem><para>The given field is not specified for the described + session.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>An input parameter was invalid (out of range, + or NULL, where that is not accepted).</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> <title>Notes</title> <para>The <function>sd_session_is_active()</function>, diff --git a/man/sd_uid_get_state.xml b/man/sd_uid_get_state.xml index b158f3528c..130af761da 100644 --- a/man/sd_uid_get_state.xml +++ b/man/sd_uid_get_state.xml @@ -170,6 +170,45 @@ </refsect1> <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + + <varlistentry> + <term><constant>-ENODATA</constant></term> + + <listitem><para>The given field is not specified for the described + user.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENXIO</constant></term> + + <listitem><para>The specified seat is unknown.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>An input parameter was invalid (out of range, + or NULL, where that is not accepted). This is also returned if + the passed user ID is 0xFFFF or 0xFFFFFFFF, which are + undefined on Linux.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> <title>Notes</title> <para>Functions described here are available as a shared library, @@ -179,19 +218,6 @@ </refsect1> <refsect1> - <title>History</title> - - <para><function>sd_uid_get_state()</function>, - <function>sd_uid_is_on_seat()</function>, - <function>sd_uid_get_sessions()</function>, and - <function>sd_uid_get_seats()</function> functions were added in - systemd-31.</para> - - <para><function>sd_uid_get_display()</function> was added in - systemd-213.</para> - </refsect1> - - <refsect1> <title>See Also</title> <para> diff --git a/man/sd_watchdog_enabled.xml b/man/sd_watchdog_enabled.xml index 991431f33b..3de9899453 100644 --- a/man/sd_watchdog_enabled.xml +++ b/man/sd_watchdog_enabled.xml @@ -98,6 +98,11 @@ <varname>WatchdogSec=</varname> in service files. See <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.</para> + + <para>Use + <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + to enable automatic watchdog support in + <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>-based event loops.</para> </refsect1> <refsect1> @@ -150,25 +155,14 @@ </refsect1> <refsect1> - <title>History</title> - - <para>The watchdog functionality and the - <varname>$WATCHDOG_USEC</varname> variable were added in - systemd-41.</para> - - <para><function>sd_watchdog_enabled()</function> function was - added in systemd-209. Since that version the - <varname>$WATCHDOG_PID</varname> variable is also set.</para> - </refsect1> - - <refsect1> <title>See Also</title> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/standard-conf.xml b/man/standard-conf.xml index 004f53f70c..6edbb7ff83 100644 --- a/man/standard-conf.xml +++ b/man/standard-conf.xml @@ -30,15 +30,17 @@ the vendor, the recommended way is to place a symlink to <filename>/dev/null</filename> in the configuration directory in <filename>/etc/</filename>, with the same filename as the vendor - configuration file.</para> + configuration file. If the vendor configuration file is included in + the initrd image, the image has to be regenerated.</para> + </refsection> <refsection id='main-conf'> <title>Configuration Directories and Precedence</title> - <para>Default configuration is defined during compilation, so a + <para>The default configuration is defined during compilation, so a configuration file is only needed when it is necessary to deviate - from those defaults. By default the configuration file in + from those defaults. By default, the configuration file in <filename>/etc/systemd/</filename> contains commented out entries showing the defaults as a guide to the administrator. This file can be edited to create local overrides. diff --git a/man/standard-options.xml b/man/standard-options.xml index f214463392..f718451a1b 100644 --- a/man/standard-options.xml +++ b/man/standard-options.xml @@ -28,6 +28,12 @@ </listitem> </varlistentry> + <varlistentry id='no-ask-password'> + <term><option>--no-ask-password</option></term> + + <listitem><para>Do not query the user for authentication for privileged operations.</para></listitem> + </varlistentry> + <varlistentry id='no-legend'> <term><option>--no-legend</option></term> diff --git a/man/sysctl.d.xml b/man/sysctl.d.xml index e5b2bc0ac9..ccf6c8e39f 100644 --- a/man/sysctl.d.xml +++ b/man/sysctl.d.xml @@ -140,10 +140,10 @@ net.bridge.bridge-nf-call-arptables = 0 </programlisting> <para>This method applies settings when the module is - loaded. Please note that unless the <filename>br_netfilter</filename> + loaded. Please note that, unless the <filename>br_netfilter</filename> module is loaded, bridged packets will not be filtered by - netfilter (starting with kernel 3.18), so simply not loading the - module is suffient to avoid filtering.</para> + Netfilter (starting with kernel 3.18), so simply not loading the + module is sufficient to avoid filtering.</para> </example> <example> @@ -162,10 +162,10 @@ net.bridge.bridge-nf-call-arptables = 0 </programlisting> <para>This method forces the module to be always loaded. Please - note that unless the <filename>br_netfilter</filename> module is - loaded, bridged packets will not be filtered with netfilter + note that, unless the <filename>br_netfilter</filename> module is + loaded, bridged packets will not be filtered with Netfilter (starting with kernel 3.18), so simply not loading the module is - suffient to avoid filtering.</para> + sufficient to avoid filtering.</para> </example> </refsect1> diff --git a/man/systemctl.xml b/man/systemctl.xml index 66a090049d..b51badf7fe 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -101,10 +101,14 @@ <term><option>--state=</option></term> <listitem> - <para>The argument should be a comma-separated list of unit - LOAD, SUB, or ACTIVE states. When listing units, show only - those in specified states. Use <option>--state=failed</option> - to show only failed units.</para> + <para>The argument should be a comma-separated list of unit + LOAD, SUB, or ACTIVE states. When listing units, show only + those in the specified states. Use <option>--state=failed</option> + to show only failed units.</para> + + <para>As a special case, if one of the arguments is + <option>help</option>, a list of allowed values will be + printed and the program will exit.</para> </listitem> </varlistentry> @@ -130,7 +134,7 @@ <para>Properties for units vary by unit type, so showing any unit (even a non-existent one) is a way to list properties - pertaining to this type. Similarly showing any job will list + pertaining to this type. Similarly, showing any job will list properties pertaining to all jobs. Properties for units are documented in <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, @@ -146,12 +150,16 @@ <term><option>--all</option></term> <listitem> - <para>When listing units, show all loaded units, regardless - of their state, including inactive units. When showing - unit/job/manager properties, show all properties regardless - whether they are set or not.</para> - <para>To list all units installed on the system, use the + <para>When listing units with <command>list-units</command>, also show inactive units and + units which are following other units. When showing unit/job/manager properties, show all + properties regardless whether they are set or not.</para> + + <para>To list all units installed in the file system, use the <command>list-unit-files</command> command instead.</para> + + <para>When listing units with <command>list-dependencies</command>, recursively show + dependencies of all dependent units (by default only dependencies of target units are + shown).</para> </listitem> </varlistentry> @@ -175,7 +183,6 @@ <command>list-dependencies</command>, i.e. follow dependencies of type <varname>WantedBy=</varname>, <varname>RequiredBy=</varname>, - <varname>RequiredByOverridable=</varname>, <varname>PartOf=</varname>, <varname>BoundBy=</varname>, instead of <varname>Wants=</varname> and similar. </para> @@ -230,6 +237,16 @@ </varlistentry> <varlistentry> + <term><option>--value</option></term> + + <listitem> + <para>When printing properties with <command>show</command>, + only print the value, and skip the property name and + <literal>=</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> <term><option>--show-types</option></term> <listitem> @@ -289,12 +306,23 @@ <para><literal>ignore-requirements</literal> is similar to <literal>ignore-dependencies</literal>, but only causes the requirement dependencies to be ignored, the ordering - dependencies will still be honoured.</para> + dependencies will still be honored.</para> </listitem> </varlistentry> <varlistentry> + <term><option>--fail</option></term> + + <listitem> + <para>Shorthand for <option>--job-mode=</option>fail.</para> + <para>When used with the <command>kill</command> command, + if no units were killed, the operation results in an error. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><option>-i</option></term> <term><option>--ignore-inhibitors</option></term> @@ -319,14 +347,11 @@ <term><option>--quiet</option></term> <listitem> - <para>Suppress output to standard output in - <command>snapshot</command>, - <command>is-active</command>, - <command>is-failed</command>, - <command>is-enabled</command>, - <command>is-system-running</command>, - <command>enable</command> and - <command>disable</command>.</para> + <para>Suppress printing of the results of various commands + and also the hints about truncated log lines. This does not + suppress output of commands for which the printed output is + the only result (like <command>show</command>). Errors are + always printed.</para> </listitem> </varlistentry> @@ -338,7 +363,20 @@ to finish. If this is not specified, the job will be verified, enqueued and <command>systemctl</command> will wait until the unit's start-up is completed. By passing this - argument, it is only verified and enqueued.</para> + argument, it is only verified and enqueued. This option may not be + combined with <option>--wait</option>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--wait</option></term> + + <listitem> + <para>Synchronously wait for started units to terminate again. + This option may not be combined with <option>--no-block</option>. + 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> </listitem> </varlistentry> @@ -347,7 +385,7 @@ <!-- we do not document -failed here, as it has been made redundant by -state=failed, which it predates. To keep - things simple we only document the new switch, while + things simple, we only document the new switch, while keeping the old one around for compatibility only. --> <varlistentry> @@ -446,7 +484,7 @@ <listitem> <para>When used with <command>kill</command>, choose which signal to send to selected processes. Must be one of the - well known signal specifiers such as <constant>SIGTERM</constant>, <constant>SIGINT</constant> or + well-known signal specifiers such as <constant>SIGTERM</constant>, <constant>SIGINT</constant> or <constant>SIGSTOP</constant>. If omitted, defaults to <option>SIGTERM</option>.</para> </listitem> @@ -460,19 +498,31 @@ <para>When used with <command>enable</command>, overwrite any existing conflicting symlinks.</para> + <para>When used with <command>edit</command>, create all of the + specified units which do not already exist.</para> + + <para>When used with <command>halt</command>, <command>poweroff</command>, <command>reboot</command> or + <command>kexec</command>, execute the selected operation without shutting down all units. However, all + processes will be killed forcibly and all file systems are unmounted or remounted read-only. This is hence a + drastic but relatively safe option to request an immediate reboot. If <option>--force</option> is specified + twice for these operations (with the exception of <command>kexec</command>), they will be executed + immediately, without terminating any processes or unmounting any file systems. Warning: specifying + <option>--force</option> twice with any of these operations might result in data loss. Note that when + <option>--force</option> is specified twice the selected operation is executed by + <command>systemctl</command> itself, and the system manager is not contacted. This means the command should + succeed even when the system manager hangs or crashed.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--message=</option></term> + + <listitem> <para>When used with <command>halt</command>, <command>poweroff</command>, <command>reboot</command> or - <command>kexec</command>, execute the selected operation - without shutting down all units. However, all processes will - be killed forcibly and all file systems are unmounted or - remounted read-only. This is hence a drastic but relatively - safe option to request an immediate reboot. If - <option>--force</option> is specified twice for these - operations, they will be executed immediately without - terminating any processes or unmounting any file - systems. Warning: specifying <option>--force</option> twice - with any of these operations might result in data - loss.</para> + <command>kexec</command>, set a short message explaining the reason + for the operation. The message will be logged together with the + default shutdown message.</para> </listitem> </varlistentry> @@ -494,7 +544,7 @@ <listitem> <para>When used with <command>enable</command>/<command>disable</command>/<command>is-enabled</command> - (and related commands), use alternative root path when + (and related commands), use an alternate root path when looking for unit files.</para> </listitem> @@ -576,7 +626,9 @@ <listitem> <para>When used with <command>list-dependencies</command>, - the output is printed as a list instead of a tree.</para> + <command>list-units</command> or <command>list-machines</command>, + the output is printed as a list instead of a tree, and the bullet + circles are omitted.</para> </listitem> </varlistentry> @@ -603,10 +655,13 @@ <term><command>list-units <optional><replaceable>PATTERN</replaceable>...</optional></command></term> <listitem> - <para>List known units (subject to limitations specified - with <option>-t</option>). If one or more - <replaceable>PATTERN</replaceable>s are specified, only - units matching one of them are shown.</para> + <para>List units that <command>systemd</command> currently has in memory. This includes units that are + either referenced directly or through a dependency, units that are pinned by applications programmatically, + or units that were active in the past and have failed. By default only units which are active, have pending + jobs, or have failed are shown; this can be changed with option <option>--all</option>. If one or more + <replaceable>PATTERN</replaceable>s are specified, only units matching one of them are shown. The units + that are shown are additionally filtered by <option>--type=</option> and <option>--state=</option> if those + options are specified.</para> <para>This is the default command.</para> </listitem> @@ -616,9 +671,8 @@ <term><command>list-sockets <optional><replaceable>PATTERN</replaceable>...</optional></command></term> <listitem> - <para>List socket units ordered by listening address. - If one or more <replaceable>PATTERN</replaceable>s are - specified, only socket units matching one of them are + <para>List socket units currently in memory, ordered by listening address. If one or more + <replaceable>PATTERN</replaceable>s are specified, only socket units matching one of them are shown. Produces output similar to <programlisting> LISTEN UNIT ACTIVATES @@ -632,8 +686,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service is not suitable for programmatic consumption. </para> - <para>See also the options <option>--show-types</option>, - <option>--all</option>, and <option>--state=</option>.</para> + <para>Also see <option>--show-types</option>, <option>--all</option>, and <option>--state=</option>.</para> </listitem> </varlistentry> @@ -641,13 +694,11 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <term><command>list-timers <optional><replaceable>PATTERN</replaceable>...</optional></command></term> <listitem> - <para>List timer units ordered by the time they elapse - next. If one or more <replaceable>PATTERN</replaceable>s - are specified, only units matching one of them are shown. + <para>List timer units currently in memory, ordered by the time they elapse next. If one or more + <replaceable>PATTERN</replaceable>s are specified, only units matching one of them are shown. </para> - <para>See also the options <option>--all</option> and - <option>--state=</option>.</para> + <para>Also see <option>--all</option> and <option>--state=</option>.</para> </listitem> </varlistentry> @@ -658,14 +709,11 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <para>Start (activate) one or more units specified on the command line.</para> - <para>Note that glob patterns operate on a list of currently - loaded units. Units which are not active and are not in a - failed state usually are not loaded, and would not be - matched by any pattern. In addition, in case of - instantiated units, systemd is often unaware of the - instance name until the instance has been started. Therefore, - using glob patterns with <command>start</command> - has limited usefulness.</para> + <para>Note that glob patterns operate on the set of primary names of units currently in memory. Units which + are not active and are not in a failed state usually are not in memory, and will not be matched by any + pattern. In addition, in case of instantiated units, systemd is often unaware of the instance name until + the instance has been started. Therefore, using glob patterns with <command>start</command> has limited + usefulness. Also, secondary alias names of units are not considered.</para> </listitem> </varlistentry> <varlistentry> @@ -711,9 +759,9 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <listitem> <para>Restart one or more units specified on the command line if the units are running. This does nothing if units are not - running. Note that, for compatibility with Red Hat init - scripts, <command>condrestart</command> is equivalent to this - command.</para> + running.</para> + <!-- Note that we don't document condrestart here, as that is just compatibility support, and we generally + don't document that. --> </listitem> </varlistentry> <varlistentry> @@ -726,14 +774,14 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service </listitem> </varlistentry> <varlistentry> - <term><command>reload-or-try-restart <replaceable>PATTERN</replaceable>...</command></term> + <term><command>try-reload-or-restart <replaceable>PATTERN</replaceable>...</command></term> <listitem> <para>Reload one or more units if they support it. If not, restart them instead. This does nothing if the units are not - running. Note that, for compatibility with SysV init scripts, - <command>force-reload</command> is equivalent to this - command.</para> + running.</para> + <!-- Note that we don't document force-reload here, as that is just compatibility support, and we generally + don't document that. --> </listitem> </varlistentry> <varlistentry> @@ -805,9 +853,9 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <para>This function is intended to generate human-readable output. If you are looking for computer-parsable output, - use <command>show</command> instead. By default this + use <command>show</command> instead. By default, this function only shows 10 lines of output and ellipsizes - lines to fit in the terminal window. This can be changes + lines to fit in the terminal window. This can be changed with <option>--lines</option> and <option>--full</option>, see above. In addition, <command>journalctl --unit=<replaceable>NAME</replaceable></command> or @@ -825,7 +873,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <para>Show properties of one or more units, jobs, or the manager itself. If no argument is specified, properties of the manager will be shown. If a unit name is specified, - properties of the unit is shown, and if a job id is + properties of the unit is shown, and if a job ID is specified, properties of the job is shown. By default, empty properties are suppressed. Use <option>--all</option> to show those too. To select specific properties to show, use @@ -863,6 +911,11 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <para>Example: <command>systemctl set-property foobar.service CPUShares=777</command></para> + <para>If the specified unit appears to be inactive, the + changes will be only stored on disk as described + previously hence they will be effective when the unit will + be started.</para> + <para>Note that this command allows changing multiple properties at the same time, which is preferable over setting them individually. Like unit file configuration @@ -906,9 +959,8 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <para>Shows units required and wanted by the specified unit. This recursively lists units following the <varname>Requires=</varname>, - <varname>RequiresOverridable=</varname>, <varname>Requisite=</varname>, - <varname>RequisiteOverridable=</varname>, + <varname>ConsistsOf=</varname>, <varname>Wants=</varname>, <varname>BindsTo=</varname> dependencies. If no unit is specified, <filename>default.target</filename> is implied.</para> @@ -934,70 +986,61 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <term><command>list-unit-files <optional><replaceable>PATTERN...</replaceable></optional></command></term> <listitem> - <para>List installed unit files. If one or more - <replaceable>PATTERN</replaceable>s are specified, only - units whose filename (just the last component of the path) - matches one of them are shown.</para> + <para>List unit files installed on the system, in combination with their enablement state (as reported by + <command>is-enabled</command>). If one or more <replaceable>PATTERN</replaceable>s are specified, only unit + files whose name matches one of them are shown (patterns matching unit file system paths are not + supported).</para> </listitem> </varlistentry> <varlistentry> <term><command>enable <replaceable>NAME</replaceable>...</command></term> + <term><command>enable <replaceable>PATH</replaceable>...</command></term> <listitem> - <para>Enable one or more unit files or unit file instances, - as specified on the command line. This will create a number - of symlinks as encoded in the <literal>[Install]</literal> - sections of the unit files. After the symlinks have been - created, the systemd configuration is reloaded (in a way that - is equivalent to <command>daemon-reload</command>) to ensure - the changes are taken into account immediately. Note that - this does <emphasis>not</emphasis> have the effect of also - starting any of the units being enabled. If this - is desired, either <option>--now</option> should be used - together with this command, or an additional <command>start</command> - command must be invoked for the unit. Also note that in case of - instance enablement, symlinks named the same as instances - are created in the install location, however they all point to the - same template unit file.</para> - - <para>This command will print the actions executed. This - output may be suppressed by passing <option>--quiet</option>. + <para>Enable one or more units or unit instances. This will create a set of symlinks, as encoded in the + <literal>[Install]</literal> sections of the indicated unit files. After the symlinks have been created, + the system manager configuration is reloaded (in a way equivalent to <command>daemon-reload</command>), in + order to ensure the changes are taken into account immediately. Note that this does + <emphasis>not</emphasis> have the effect of also starting any of the units being enabled. If this is + desired, combine this command with the <option>--now</option> switch, or invoke <command>start</command> + with appropriate arguments later. Note that in case of unit instance enablement (i.e. enablement of units of + the form <filename>foo@bar.service</filename>), symlinks named the same as instances are created in the + unit configuration directory, however they point to the single template unit file they are instantiated + from.</para> + + <para>This command expects either valid unit names (in which case various unit file directories are + automatically searched for unit files with appropriate names), or absolute paths to unit files (in which + case these files are read directly). If a specified unit file is located outside of the usual unit file + directories, an additional symlink is created, linking it into the unit configuration path, thus ensuring + it is found when requested by commands such as <command>start</command>.</para> + + <para>This command will print the file system operations executed. This output may be suppressed by passing + <option>--quiet</option>. </para> - <para>Note that this operation creates only the suggested - symlinks for the units. While this command is the - recommended way to manipulate the unit configuration - directory, the administrator is free to make additional - changes manually by placing or removing symlinks in the - directory. This is particularly useful to create - configurations that deviate from the suggested default - installation. In this case, the administrator must make sure - to invoke <command>daemon-reload</command> manually as - necessary to ensure the changes are taken into account. + <para>Note that this operation creates only the symlinks suggested in the <literal>[Install]</literal> + section of the unit files. While this command is the recommended way to manipulate the unit configuration + directory, the administrator is free to make additional changes manually by placing or removing symlinks + below this directory. This is particularly useful to create configurations that deviate from the suggested + default installation. In this case, the administrator must make sure to invoke + <command>daemon-reload</command> manually as necessary, in order to ensure the changes are taken into + account. </para> - <para>Enabling units should not be confused with starting - (activating) units, as done by the <command>start</command> - command. Enabling and starting units is orthogonal: units - may be enabled without being started and started without - being enabled. Enabling simply hooks the unit into various - suggested places (for example, so that the unit is - automatically started on boot or when a particular kind of - hardware is plugged in). Starting actually spawns the daemon - process (in case of service units), or binds the socket (in - case of socket units), and so on.</para> - - <para>Depending on whether <option>--system</option>, - <option>--user</option>, <option>--runtime</option>, - or <option>--global</option> is specified, this enables the unit - for the system, for the calling user only, for only this boot of - the system, or for all future logins of all users, or only this - boot. Note that in the last case, no systemd daemon - configuration is reloaded.</para> - - <para>Using <command>enable</command> on masked units - results in an error.</para> + <para>Enabling units should not be confused with starting (activating) units, as done by the + <command>start</command> command. Enabling and starting units is orthogonal: units may be enabled without + being started and started without being enabled. Enabling simply hooks the unit into various suggested + places (for example, so that the unit is automatically started on boot or when a particular kind of + hardware is plugged in). Starting actually spawns the daemon process (in case of service units), or binds + the socket (in case of socket units), and so on.</para> + + <para>Depending on whether <option>--system</option>, <option>--user</option>, <option>--runtime</option>, + or <option>--global</option> is specified, this enables the unit for the system, for the calling user only, + for only this boot of the system, or for all future logins of all users, or only this boot. Note that in + the last case, no systemd daemon configuration is reloaded.</para> + + <para>Using <command>enable</command> on masked units is not supported and results in an error.</para> </listitem> </varlistentry> @@ -1005,28 +1048,31 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <term><command>disable <replaceable>NAME</replaceable>...</command></term> <listitem> - <para>Disables one or more units. This removes all symlinks - to the specified unit files from the unit configuration - directory, and hence undoes the changes made by - <command>enable</command>. Note however that this removes - all symlinks to the unit files (i.e. including manual - additions), not just those actually created by - <command>enable</command>. This call implicitly reloads the - systemd daemon configuration after completing the disabling - of the units. Note that this command does not implicitly - stop the units that are being disabled. If this is desired, either - <option>--now</option> should be used together with this command, or - an additional <command>stop</command> command should be executed - afterwards.</para> - - <para>This command will print the actions executed. This - output may be suppressed by passing <option>--quiet</option>. + <para>Disables one or more units. This removes all symlinks to the unit files backing the specified units + from the unit configuration directory, and hence undoes any changes made by <command>enable</command> or + <command>link</command>. Note that this removes <emphasis>all</emphasis> symlinks to matching unit files, + including manually created symlinks, and not just those actually created by <command>enable</command> or + <command>link</command>. Note that while <command>disable</command> undoes the effect of + <command>enable</command>, the two commands are otherwise not symmetric, as <command>disable</command> may + remove more symlinks than a prior <command>enable</command> invocation of the same unit created.</para> + + <para>This command expects valid unit names only, it does not accept paths to unit files.</para> + + <para>In addition to the units specified as arguments, all units are disabled that are listed in the + <varname>Also=</varname> setting contained in the <literal>[Install]</literal> section of any of the unit + files being operated on.</para> + + <para>This command implicitly reloads the system manager configuration after completing the operation. Note + that this command does not implicitly stop the units that are being disabled. If this is desired, either + combine this command with the <option>--now</option> switch, or invoke the <command>stop</command> command + with appropriate arguments later.</para> + + <para>This command will print information about the file system operations (symlink removals) + executed. This output may be suppressed by passing <option>--quiet</option>. </para> - <para>This command honors <option>--system</option>, - <option>--user</option>, <option>--runtime</option> and - <option>--global</option> in a similar way as - <command>enable</command>.</para> + <para>This command honors <option>--system</option>, <option>--user</option>, <option>--runtime</option> + and <option>--global</option> in a similar way as <command>enable</command>.</para> </listitem> </varlistentry> @@ -1034,12 +1080,10 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <term><command>reenable <replaceable>NAME</replaceable>...</command></term> <listitem> - <para>Reenable one or more unit files, as specified on the - command line. This is a combination of - <command>disable</command> and <command>enable</command> and - is useful to reset the symlinks a unit is enabled with to - the defaults configured in the <literal>[Install]</literal> - section of the unit file.</para> + <para>Reenable one or more units, as specified on the command line. This is a combination of + <command>disable</command> and <command>enable</command> and is useful to reset the symlinks a unit file is + enabled with to the defaults configured in its <literal>[Install]</literal> section. This command expects + a unit name only, it does not accept paths to unit files.</para> </listitem> </varlistentry> @@ -1047,22 +1091,23 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <term><command>preset <replaceable>NAME</replaceable>...</command></term> <listitem> - <para>Reset one or more unit files, as specified on the - command line, to the defaults configured in the preset - policy files. This has the same effect as - <command>disable</command> or <command>enable</command>, - depending how the unit is listed in the preset files.</para> + <para>Reset the enable/disable status one or more unit files, as specified on + the command line, to the defaults configured in the preset policy files. This + has the same effect as <command>disable</command> or + <command>enable</command>, depending how the unit is listed in the preset + files.</para> - <para>Use <option>--preset-mode=</option> to control - whether units shall be enabled and disabled, or only - enabled, or only disabled.</para> + <para>Use <option>--preset-mode=</option> to control whether units shall be + enabled and disabled, or only enabled, or only disabled.</para> + + <para>If the unit carries no install information, it will be silently ignored + by this command. <replaceable>NAME</replaceable> must be the real unit name, + any alias names are ignored silently.</para> - <para>For more information on the preset policy format, - see + <para>For more information on the preset policy format, see <citerefentry><refentrytitle>systemd.preset</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - For more information on the concept of presets, please - consult the <ulink - url="http://freedesktop.org/wiki/Software/systemd/Preset">Preset</ulink> + For more information on the concept of presets, please consult the + <ulink url="http://freedesktop.org/wiki/Software/systemd/Preset">Preset</ulink> document.</para> </listitem> </varlistentry> @@ -1099,15 +1144,15 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <tgroup cols='3'> <thead> <row> - <entry>Printed string</entry> - <entry>Meaning</entry> - <entry>Return value</entry> + <entry>Name</entry> + <entry>Description</entry> + <entry>Exit Code</entry> </row> </thead> <tbody> <row> <entry><literal>enabled</literal></entry> - <entry morerows='1'>Enabled through a symlink in <filename>.wants</filename> directory (permanently or just in <filename>/run</filename>).</entry> + <entry morerows='1'>Enabled via <filename>.wants/</filename>, <filename>.requires/</filename> or alias symlinks (permanently in <filename>/etc/systemd/system/</filename>, or transiently in <filename>/run/systemd/system/</filename>).</entry> <entry morerows='1'>0</entry> </row> <row> @@ -1115,34 +1160,49 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service </row> <row> <entry><literal>linked</literal></entry> - <entry morerows='1'>Made available through a symlink to the unit file (permanently or just in <filename>/run</filename>).</entry> - <entry morerows='1'>1</entry> + <entry morerows='1'>Made available through one or more symlinks to the unit file (permanently in <filename>/etc/systemd/system/</filename> or transiently in <filename>/run/systemd/system/</filename>), even though the unit file might reside outside of the unit file search path.</entry> + <entry morerows='1'>> 0</entry> </row> <row> <entry><literal>linked-runtime</literal></entry> </row> <row> <entry><literal>masked</literal></entry> - <entry morerows='1'>Disabled entirely (permanently or just in <filename>/run</filename>).</entry> - <entry morerows='1'>1</entry> + <entry morerows='1'>Completely disabled, so that any start operation on it fails (permanently in <filename>/etc/systemd/system/</filename> or transiently in <filename>/run/systemd/systemd/</filename>).</entry> + <entry morerows='1'>> 0</entry> </row> <row> <entry><literal>masked-runtime</literal></entry> </row> <row> <entry><literal>static</literal></entry> - <entry>Unit file is not enabled, and has no provisions for enabling in the <literal>[Install]</literal> section.</entry> + <entry>The unit file is not enabled, and has no provisions for enabling in the <literal>[Install]</literal> unit file section.</entry> <entry>0</entry> </row> <row> <entry><literal>indirect</literal></entry> - <entry>Unit file itself is not enabled, but it has a non-empty <varname>Also=</varname> setting in the <literal>[Install]</literal> section, listing other unit files that might be enabled.</entry> + <entry>The unit file itself is not enabled, but it has a non-empty <varname>Also=</varname> setting in the <literal>[Install]</literal> unit file section, listing other unit files that might be enabled.</entry> <entry>0</entry> </row> <row> <entry><literal>disabled</literal></entry> - <entry>Unit file is not enabled.</entry> - <entry>1</entry> + <entry>The unit file is not enabled, but contains an <literal>[Install]</literal> section with installation instructions.</entry> + <entry>> 0</entry> + </row> + <row> + <entry><literal>generated</literal></entry> + <entry>The unit file was generated dynamically via a generator tool. See <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>. Generated unit files may not be enabled, they are enabled implicitly by their generator.</entry> + <entry>0</entry> + </row> + <row> + <entry><literal>transient</literal></entry> + <entry>The unit file has been created dynamically with the runtime API. Transient units may not be enabled.</entry> + <entry>0</entry> + </row> + <row> + <entry><literal>bad</literal></entry> + <entry>The unit file is invalid or another error occurred. Note that <command>is-enabled</command> will not actually return this state, but print an error message instead. However the unit file listing printed by <command>list-unit-files</command> might show it.</entry> + <entry>> 0</entry> </row> </tbody> </tgroup> @@ -1155,16 +1215,13 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <term><command>mask <replaceable>NAME</replaceable>...</command></term> <listitem> - <para>Mask one or more unit files, as specified on the - command line. This will link these units to - <filename>/dev/null</filename>, making it impossible to - start them. This is a stronger version of - <command>disable</command>, since it prohibits all kinds of - activation of the unit, including enablement and manual - activation. Use this option with care. This honors the - <option>--runtime</option> option to only mask temporarily - until the next reboot of the system. The <option>--now</option> - option can be used to ensure that the units are also stopped.</para> + <para>Mask one or more units, as specified on the command line. This will link these unit files to + <filename>/dev/null</filename>, making it impossible to start them. This is a stronger version of + <command>disable</command>, since it prohibits all kinds of activation of the unit, including enablement + and manual activation. Use this option with care. This honors the <option>--runtime</option> option to only + mask temporarily until the next reboot of the system. The <option>--now</option> option may be used to + ensure that the units are also stopped. This command expects valid unit names only, it does not accept unit + file paths.</para> </listitem> </varlistentry> @@ -1172,23 +1229,42 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <term><command>unmask <replaceable>NAME</replaceable>...</command></term> <listitem> - <para>Unmask one or more unit files, as specified on the - command line. This will undo the effect of - <command>mask</command>.</para> + <para>Unmask one or more unit files, as specified on the command line. This will undo the effect of + <command>mask</command>. This command expects valid unit names only, it does not accept unit file + paths.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>link <replaceable>PATH</replaceable>...</command></term> + + <listitem> + <para>Link a unit file that is not in the unit file search paths into the unit file search path. This + command expects an absolute path to a unit file. The effect of this may be undone with + <command>disable</command>. The effect of this command is that a unit file is made available for commands + such as <command>start</command>, even though it is not installed directly in the unit search path.</para> </listitem> </varlistentry> <varlistentry> - <term><command>link <replaceable>FILENAME</replaceable>...</command></term> + <term><command>revert <replaceable>NAME</replaceable>...</command></term> <listitem> - <para>Link a unit file that is not in the unit file search - paths into the unit file search path. This requires an - absolute path to a unit file. The effect of this can be - undone with <command>disable</command>. The effect of this - command is that a unit file is available for - <command>start</command> and other commands although it - is not installed directly in the unit search path.</para> + <para>Revert one or more unit files to their vendor versions. This command removes drop-in configuration + files that modify the specified units, as well as any user-configured unit file that overrides a matching + vendor supplied unit file. Specifically, for a unit <literal>foo.service</literal> the matching directories + <literal>foo.service.d/</literal> with all their contained files are removed, both below the persistent and + runtime configuration directories (i.e. below <filename>/etc/systemd/system</filename> and + <filename>/run/systemd/system</filename>); if the unit file has a vendor-supplied version (i.e. a unit file + located below <filename>/usr</filename>) any matching peristent or runtime unit file that overrides it is + removed, too. Note that if a unit file has no vendor-supplied version (i.e. is only defined below + <filename>/etc/systemd/system</filename> or <filename>/run/systemd/system</filename>, but not in a unit + file stored below <filename>/usr</filename>), then it is not removed. Also, if a unit is masked, it is + unmasked.</para> + + <para>Effectively, this command may be used to undo all changes made with <command>systemctl + edit</command>, <command>systemctl set-property</command> and <command>systemctl mask</command> and puts + the original unit file with its settings back in effect.</para> </listitem> </varlistentry> @@ -1200,12 +1276,12 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <listitem> <para>Adds <literal>Wants=</literal> or <literal>Requires=</literal> - dependency, respectively, to the specified + dependencies, respectively, to the specified <replaceable>TARGET</replaceable> for one or more units. </para> <para>This command honors <option>--system</option>, <option>--user</option>, <option>--runtime</option> and - <option>--global</option> in a similar way as + <option>--global</option> in a way similar to <command>enable</command>.</para> </listitem> @@ -1221,8 +1297,8 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <para>Depending on whether <option>--system</option> (the default), <option>--user</option>, or <option>--global</option> is specified, - this creates a drop-in file for each unit either for the system, - for the calling user or for all futures logins of all users. Then, + this command creates a drop-in file for each unit either for the system, + for the calling user, or for all futures logins of all users. Then, the editor (see the "Environment" section below) is invoked on temporary files which will be written to the real location if the editor exits successfully.</para> @@ -1230,12 +1306,15 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <para>If <option>--full</option> is specified, this will copy the original units instead of creating drop-in files.</para> + <para>If <option>--force</option> is specified and any units do + not already exist, new unit files will be opened for editing.</para> + <para>If <option>--runtime</option> is specified, the changes will be made temporarily in <filename>/run</filename> and they will be lost on the next reboot.</para> - <para>If the temporary file is empty upon exit the modification of - the related unit is canceled</para> + <para>If the temporary file is empty upon exit, the modification of + the related unit is canceled.</para> <para>After the units have been edited, systemd configuration is reloaded (in a way that is equivalent to <command>daemon-reload</command>). @@ -1243,7 +1322,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <para>Note that this command cannot be used to remotely edit units and that you cannot temporarily edit units which are in - <filename>/etc</filename> since they take precedence over + <filename>/etc</filename>, since they take precedence over <filename>/run</filename>.</para> </listitem> </varlistentry> @@ -1315,46 +1394,6 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service </refsect2> <refsect2> - <title>Snapshot Commands</title> - - <variablelist> - <varlistentry> - <term><command>snapshot <optional><replaceable>NAME</replaceable></optional></command></term> - - <listitem> - <para>Create a snapshot. If a snapshot name is specified, - the new snapshot will be named after it. If none is - specified, an automatic snapshot name is generated. In - either case, the snapshot name used is printed to standard - output, unless <option>--quiet</option> is specified. - </para> - - <para>A snapshot refers to a saved state of the systemd - manager. It is implemented itself as a unit that is - generated dynamically with this command and has dependencies - on all units active at the time. At a later time, the user - may return to this state by using the - <command>isolate</command> command on the snapshot unit. - </para> - - <para>Snapshots are only useful for saving and restoring - which units are running or are stopped, they do not - save/restore any other state. Snapshots are dynamic and lost - on reboot.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>delete <replaceable>PATTERN</replaceable>...</command></term> - - <listitem> - <para>Remove a snapshot previously created with - <command>snapshot</command>.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect2> - - <refsect2> <title>Environment Commands</title> <variablelist> @@ -1415,7 +1454,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <term><command>daemon-reload</command></term> <listitem> - <para>Reload systemd manager configuration. This will + <para>Reload the systemd manager configuration. This will rerun all generators (see <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>), reload all unit files, and recreate the entire dependency @@ -1453,22 +1492,25 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <listitem> <para>Checks whether the system is operational. This - returns success when the system is fully up and running, - meaning not in startup, shutdown or maintenance - mode. Failure is returned otherwise. In addition, the + returns success (exit code 0) when the system is fully up + and running, specifically not in startup, shutdown or + maintenance mode, and with no failed services. Failure is + returned otherwise (exit code non-zero). In addition, the current state is printed in a short string to standard - output, see table below. Use <option>--quiet</option> to + output, see the table below. Use <option>--quiet</option> to suppress this output.</para> <table> - <title>Manager Operational States</title> - <tgroup cols='2'> - <colspec colname='name' /> - <colspec colname='description' /> + <title><command>is-system-running</command> output</title> + <tgroup cols='3'> + <colspec colname='name'/> + <colspec colname='description'/> + <colspec colname='exit-code'/> <thead> <row> <entry>Name</entry> <entry>Description</entry> + <entry>Exit Code</entry> </row> </thead> <tbody> @@ -1478,32 +1520,53 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <filename>basic.target</filename> is reached or the <varname>maintenance</varname> state entered. </para></entry> + <entry>> 0</entry> </row> <row> <entry><varname>starting</varname></entry> <entry><para>Late bootup, before the job queue becomes idle for the first time, or one of the rescue targets are reached.</para></entry> + <entry>> 0</entry> </row> <row> <entry><varname>running</varname></entry> <entry><para>The system is fully operational.</para></entry> + <entry>0</entry> </row> <row> <entry><varname>degraded</varname></entry> <entry><para>The system is operational but one or more units failed.</para></entry> + <entry>> 0</entry> </row> <row> <entry><varname>maintenance</varname></entry> <entry><para>The rescue or emergency target is active.</para></entry> + <entry>> 0</entry> </row> <row> <entry><varname>stopping</varname></entry> <entry><para>The manager is shutting down.</para></entry> + <entry>> 0</entry> + </row> + <row> + <entry><varname>offline</varname></entry> + <entry><para>The manager is not + running. Specifically, this is the operational + state if an incompatible program is running as + system manager (PID 1).</para></entry> + <entry>> 0</entry> + </row> + <row> + <entry><varname>unknown</varname></entry> + <entry><para>The operational state could not be + determined, due to lack of resources or another + error cause.</para></entry> + <entry>> 0</entry> </row> </tbody> </tgroup> @@ -1542,48 +1605,45 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <term><command>halt</command></term> <listitem> - <para>Shut down and halt the system. This is mostly equivalent to - <command>start halt.target --job-mode=replace-irreversibly</command>, but also - prints a wall message to all users. If combined with - <option>--force</option>, shutdown of all running services is - skipped, however all processes are killed and all file - systems are unmounted or mounted read-only, immediately - followed by the system halt. If <option>--force</option> is - specified twice, the operation is immediately executed - without terminating any processes or unmounting any file - systems. This may result in data loss.</para> + <para>Shut down and halt the system. This is mostly equivalent to <command>start halt.target + --job-mode=replace-irreversibly</command>, but also prints a wall message to all users. If combined with + <option>--force</option>, shutdown of all running services is skipped, however all processes are killed and + all file systems are unmounted or mounted read-only, immediately followed by the system halt. If + <option>--force</option> is specified twice, the operation is immediately executed without terminating any + processes or unmounting any file systems. This may result in data loss. Note that when + <option>--force</option> is specified twice the halt operation is executed by + <command>systemctl</command> itself, and the system manager is not contacted. This means the command should + succeed even when the system manager hangs or crashed.</para> </listitem> </varlistentry> <varlistentry> <term><command>poweroff</command></term> <listitem> - <para>Shut down and power-off the system. This is mostly - equivalent to <command>start poweroff.target --job-mode=replace-irreversibly</command>, - but also prints a wall message to all users. If combined with - <option>--force</option>, shutdown of all running services is - skipped, however all processes are killed and all file - systems are unmounted or mounted read-only, immediately - followed by the powering off. If <option>--force</option> is - specified twice, the operation is immediately executed - without terminating any processes or unmounting any file - systems. This may result in data loss.</para> + <para>Shut down and power-off the system. This is mostly equivalent to <command>start poweroff.target + --job-mode=replace-irreversibly</command>, but also prints a wall message to all users. If combined with + <option>--force</option>, shutdown of all running services is skipped, however all processes are killed and + all file systems are unmounted or mounted read-only, immediately followed by the powering off. If + <option>--force</option> is specified twice, the operation is immediately executed without terminating any + processes or unmounting any file systems. This may result in data loss. Note that when + <option>--force</option> is specified twice the power-off operation is executed by + <command>systemctl</command> itself, and the system manager is not contacted. This means the command should + succeed even when the system manager hangs or crashed.</para> </listitem> </varlistentry> <varlistentry> <term><command>reboot <optional><replaceable>arg</replaceable></optional></command></term> <listitem> - <para>Shut down and reboot the system. This is mostly - equivalent to <command>start reboot.target --job-mode=replace-irreversibly</command>, - but also prints a wall message to all users. If combined with - <option>--force</option>, shutdown of all running services is - skipped, however all processes are killed and all file - systems are unmounted or mounted read-only, immediately - followed by the reboot. If <option>--force</option> is - specified twice, the operation is immediately executed - without terminating any processes or unmounting any file - systems. This may result in data loss.</para> + <para>Shut down and reboot the system. This is mostly equivalent to <command>start reboot.target + --job-mode=replace-irreversibly</command>, but also prints a wall message to all users. If combined with + <option>--force</option>, shutdown of all running services is skipped, however all processes are killed and + all file systems are unmounted or mounted read-only, immediately followed by the reboot. If + <option>--force</option> is specified twice, the operation is immediately executed without terminating any + processes or unmounting any file systems. This may result in data loss. Note that when + <option>--force</option> is specified twice the reboot operation is executed by + <command>systemctl</command> itself, and the system manager is not contacted. This means the command should + succeed even when the system manager hangs or crashed.</para> <para>If the optional argument <replaceable>arg</replaceable> is given, it will be passed @@ -1612,13 +1672,17 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service </varlistentry> <varlistentry> - <term><command>exit</command></term> + <term><command>exit <optional><replaceable>EXIT_CODE</replaceable></optional></command></term> <listitem> <para>Ask the systemd manager to quit. This is only supported for user service managers (i.e. in conjunction - with the <option>--user</option> option) and will fail - otherwise.</para> + with the <option>--user</option> option) or in containers + and is equivalent to <command>poweroff</command> otherwise.</para> + + <para>The systemd manager can exit with a non-zero exit + code if the optional argument + <replaceable>EXIT_CODE</replaceable> is given.</para> </listitem> </varlistentry> @@ -1626,20 +1690,15 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <term><command>switch-root <replaceable>ROOT</replaceable> <optional><replaceable>INIT</replaceable></optional></command></term> <listitem> - <para>Switches to a different root directory and executes a - new system manager process below it. This is intended for - usage in initial RAM disks ("initrd"), and will transition - from the initrd's system manager process (a.k.a "init" - process) to the main system manager process. This call takes two - arguments: the directory that is to become the new root directory, and - the path to the new system manager binary below it to - execute as PID 1. If the latter is omitted or the empty - string, a systemd binary will automatically be searched for - and used as init. If the system manager path is omitted or - equal to the empty string, the state of the initrd's system - manager process is passed to the main system manager, which - allows later introspection of the state of the services - involved in the initrd boot.</para> + <para>Switches to a different root directory and executes a new system manager process below it. This is + intended for usage in initial RAM disks ("initrd"), and will transition from the initrd's system manager + process (a.k.a. "init" process) to the main system manager process which is loaded from the actual host + volume. This call takes two arguments: the directory that is to become the new root directory, and the path + to the new system manager binary below it to execute as PID 1. If the latter is omitted or the empty + string, a systemd binary will automatically be searched for and used as init. If the system manager path is + omitted, equal to the empty string or identical to the path to the systemd binary, the state of the + initrd's system manager process is passed to the main system manager, which allows later introspection of + the state of the services involved in the initrd boot phase.</para> </listitem> </varlistentry> @@ -1678,34 +1737,28 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <refsect2> <title>Parameter Syntax</title> - <para>Unit commands listed above take either a single unit name - (designated as <replaceable>NAME</replaceable>), or multiple - unit specifications (designated as - <replaceable>PATTERN</replaceable>...). In the first case, the - unit name with or without a suffix must be given. If the suffix - is not specified, systemctl will append a suitable suffix, - <literal>.service</literal> by default, and a type-specific - suffix in case of commands which operate only on specific unit - types. For example, + <para>Unit commands listed above take either a single unit name (designated as <replaceable>NAME</replaceable>), + or multiple unit specifications (designated as <replaceable>PATTERN</replaceable>...). In the first case, the + unit name with or without a suffix must be given. If the suffix is not specified (unit name is "abbreviated"), + systemctl will append a suitable suffix, <literal>.service</literal> by default, and a type-specific suffix in + case of commands which operate only on specific unit types. For example, <programlisting># systemctl start sshd</programlisting> and <programlisting># systemctl start sshd.service</programlisting> are equivalent, as are <programlisting># systemctl isolate default</programlisting> and <programlisting># systemctl isolate default.target</programlisting> - Note that (absolute) paths to device nodes are automatically - converted to device unit names, and other (absolute) paths to - mount unit names. + Note that (absolute) paths to device nodes are automatically converted to device unit names, and other (absolute) + paths to mount unit names. <programlisting># systemctl status /dev/sda # systemctl status /home</programlisting> are equivalent to: <programlisting># systemctl status dev-sda.device # systemctl status home.mount</programlisting> - In the second case, shell-style globs will be matched against - currently loaded units; literal unit names, with or without - a suffix, will be treated as in the first case. This means that - literal unit names always refer to exactly one unit, but globs - may match zero units and this is not considered an error.</para> + In the second case, shell-style globs will be matched against the primary names of all units currently in memory; + literal unit names, with or without a suffix, will be treated as in the first case. This means that literal unit + names always refer to exactly one unit, but globs may match zero units and this is not considered an + error.</para> <para>Glob patterns use <citerefentry project='man-pages'><refentrytitle>fnmatch</refentrytitle><manvolnum>3</manvolnum></citerefentry>, @@ -1713,16 +1766,16 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <literal>*</literal>, <literal>?</literal>, <literal>[]</literal> may be used. See <citerefentry project='man-pages'><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for more details. The patterns are matched against the names of - currently loaded units, and patterns which do not match anything + for more details. The patterns are matched against the primary names of + units currently in memory, and patterns which do not match anything are silently skipped. For example: <programlisting># systemctl stop sshd@*.service</programlisting> - will stop all <filename>sshd@.service</filename> instances. + will stop all <filename>sshd@.service</filename> instances. Note that alias names of units, and units that aren't + in memory are not considered for glob expansion. </para> - <para>For unit file commands, the specified - <replaceable>NAME</replaceable> should be the full name of the - unit file, or the absolute path to the unit file: + <para>For unit file commands, the specified <replaceable>NAME</replaceable> should be the name of the unit file + (possibly abbreviated, see above), or the absolute path to the unit file: <programlisting># systemctl enable foo.service</programlisting> or <programlisting># systemctl link /path/to/foo.service</programlisting> @@ -1760,6 +1813,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service </variablelist> <xi:include href="less-variables.xml" xpointer="pager"/> <xi:include href="less-variables.xml" xpointer="less"/> + <xi:include href="less-variables.xml" xpointer="lesscharset"/> </refsect1> <refsect1> diff --git a/man/systemd-analyze.xml b/man/systemd-analyze.xml index 198315052f..8fa7cd3329 100644 --- a/man/systemd-analyze.xml +++ b/man/systemd-analyze.xml @@ -93,7 +93,13 @@ <command>systemd-analyze</command> <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="plain">set-log-level</arg> - <arg choice="opt"><replaceable>LEVEL</replaceable></arg> + <arg choice="plain"><replaceable>LEVEL</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis> + <command>systemd-analyze</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="plain">set-log-target</arg> + <arg choice="plain"><replaceable>TARGET</replaceable></arg> </cmdsynopsis> <cmdsynopsis> <command>systemd-analyze</command> @@ -168,14 +174,22 @@ <option>--log-level=</option> described in <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para> - <para><command>systemd-analyze verify</command> will load unit - files and print warnings if any errors are detected. Files - specified on the command line will be loaded, but also any other - units referenced by them. This command works by prepending the - directories for all command line arguments at the beginning of the - unit load path, which means that all units files found in those - directories will be used in preference to the unit files found in - the standard locations, even if not listed explicitly.</para> + <para><command>systemd-analyze set-log-target + <replaceable>TARGET</replaceable></command> changes the current log + target of the <command>systemd</command> daemon to + <replaceable>TARGET</replaceable> (accepts the same values as + <option>--log-target=</option>, described in + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para> + + <para><command>systemd-analyze verify</command> will load unit files and print + warnings if any errors are detected. Files specified on the command line will be + loaded, but also any other units referenced by them. The full unit search path is + formed by combining the directories for all command line arguments, and the usual unit + load paths (variable <varname>$SYSTEMD_UNIT_PATH</varname> is supported, and may be + used to replace or augment the compiled in set of unit load paths; see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + All units files present in the directories containing the command line arguments will + be used in preference to the other paths.</para> <para>If no command is passed, <command>systemd-analyze time</command> is implied.</para> @@ -213,9 +227,7 @@ <varname>After=</varname> or <varname>Before=</varname> are shown. If <option>--require</option> is passed, only dependencies of type <varname>Requires=</varname>, - <varname>RequiresOverridable=</varname>, <varname>Requisite=</varname>, - <varname>RequisiteOverridable=</varname>, <varname>Wants=</varname> and <varname>Conflicts=</varname> are shown. If neither is passed, this shows dependencies of all these types.</para></listitem> diff --git a/man/systemd-ask-password.xml b/man/systemd-ask-password.xml index 877c71af53..2b6fb5a82f 100644 --- a/man/systemd-ask-password.xml +++ b/man/systemd-ask-password.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -67,22 +67,33 @@ processes.</para> <para>The purpose of this tool is to query system-wide passwords - -- that is passwords not attached to a specific user account. + — that is passwords not attached to a specific user account. Examples include: unlocking encrypted hard disks when they are plugged in or at boot, entering an SSL certificate passphrase for web and VPN servers.</para> - <para>Existing agents are: a boot-time password agent asking the - user for passwords using Plymouth; a boot-time password agent - querying the user directly on the console; an agent requesting - password input via a - <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> - message; an agent suitable for running in a GNOME session; a - command line agent which can be started temporarily to process - queued password requests; a TTY agent that is temporarily spawned - during - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - invocations.</para> + <para>Existing agents are: + <itemizedlist> + + <listitem><para>A boot-time password agent asking the user for + passwords using Plymouth</para></listitem> + + <listitem><para>A boot-time password agent querying the user + directly on the console</para></listitem> + + <listitem><para>An agent requesting password input via a + <citerefentry + project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> + message</para></listitem> + + <listitem><para>A command line agent which can be started + temporarily to process queued password + requests</para></listitem> + + <listitem><para>A TTY agent that is temporarily spawned during + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + invocations</para></listitem> + </itemizedlist></para> <para>Additional password agents may be implemented according to the <ulink @@ -112,6 +123,38 @@ </varlistentry> <varlistentry> + <term><option>--id=</option></term> + <listitem><para>Specify an identifier for this password + query. This identifier is freely choosable and allows + recognition of queries by involved agents. It should include + the subsystem doing the query and the specific object the + query is done for. Example: + <literal>--id=cryptsetup:/dev/sda5</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--keyname=</option></term> + <listitem><para>Configure a kernel keyring key name to use as + cache for the password. If set, then the tool will try to push + any collected passwords into the kernel keyring of the root + user, as a key of the specified name. If combined with + <option>--accept-cached</option>, it will also try to retrieve + such cached passwords from the key in the kernel keyring + instead of querying the user right away. By using this option, + the kernel keyring may be used as effective cache to avoid + repeatedly asking users for passwords, if there are multiple + objects that may be unlocked with the same password. The + cached key will have a timeout of 2.5min set, after which it + will be purged from the kernel keyring. Note that it is + possible to cache multiple passwords under the same keyname, + in which case they will be stored as NUL-separated list of + passwords. Use + <citerefentry project='die-net'><refentrytitle>keyctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to access the cached key via the kernel keyring + directly. Example: <literal>--keyname=cryptsetup</literal></para></listitem> + </varlistentry> + + <varlistentry> <term><option>--timeout=</option></term> <listitem><para>Specify the query timeout in seconds. Defaults @@ -138,7 +181,7 @@ <term><option>--accept-cached</option></term> <listitem><para>If passed, accept cached passwords, i.e. - passwords previously typed in.</para></listitem> + passwords previously entered.</para></listitem> </varlistentry> <varlistentry> @@ -149,6 +192,15 @@ This will output one password per line.</para></listitem> </varlistentry> + <varlistentry> + <term><option>--no-output</option></term> + + <listitem><para>Do not print passwords to standard output. + This is useful if you want to store a password in kernel + keyring with <option>--keyname</option> but do not want it + to show up on screen or in logs.</para></listitem> + </varlistentry> + <xi:include href="standard-options.xml" xpointer="help" /> </variablelist> @@ -166,6 +218,7 @@ <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>keyctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> </para> diff --git a/man/systemd-backlight@.service.xml b/man/systemd-backlight@.service.xml index a259f5d583..3459ed8851 100644 --- a/man/systemd-backlight@.service.xml +++ b/man/systemd-backlight@.service.xml @@ -58,8 +58,8 @@ that restores the display backlight brightness at early boot and saves it at shutdown. On disk, the backlight brightness is stored in <filename>/var/lib/systemd/backlight/</filename>. During - loading, if udev property <option>ID_BACKLIGHT_CLAMP</option> is - not set to false value, the brightness is clamped to a value of at + loading, if the udev property <option>ID_BACKLIGHT_CLAMP</option> is + not set to false, the brightness is clamped to a value of at least 1 or 5% of maximum brightness, whichever is greater. This restriction will be removed when the kernel allows user space to reliably set a brightness value which does not turn off the diff --git a/man/systemd-binfmt.service.xml b/man/systemd-binfmt.service.xml index 66d264389e..cccfb49ca9 100644 --- a/man/systemd-binfmt.service.xml +++ b/man/systemd-binfmt.service.xml @@ -54,7 +54,7 @@ <refsect1> <title>Description</title> - <para><filename>systemd-binfmt.service</filename> is an early-boot + <para><filename>systemd-binfmt.service</filename> is an early boot service that registers additional binary formats for executables in the kernel.</para> diff --git a/man/systemd-bootchart.xml b/man/systemd-bootchart.xml deleted file mode 100644 index 538666760a..0000000000 --- a/man/systemd-bootchart.xml +++ /dev/null @@ -1,323 +0,0 @@ -<?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"> - -<!-- - This file is part of systemd. - - Copyright 2012 Intel Corporation - - Authors: - Auke Kok <auke-jan.h.kok@intel.com> - William Giokas <1007380@gmail.com> - - systemd is free software; you can redistribute it and/or modify it - under the terms of the GNU Lesser General Public License as published by - the Free Software Foundation; either version 2.1 of the License, or - (at your option) any later version. - - systemd is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public License - along with systemd; If not, see <http://www.gnu.org/licenses/>. ---> - -<refentry id="systemd-bootchart" conditional='ENABLE_BOOTCHART' - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-bootchart</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Auke</firstname> - <surname>Kok</surname> - <email>auke-jan.h.kok@intel.com</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-bootchart</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-bootchart</refname> - <refpurpose>Boot performance graphing tool</refpurpose> - </refnamediv> - - <refsect1> - <title>Description</title> - <para> - <command>systemd-bootchart</command> is a tool, usually run at - system startup, that collects the CPU load, disk load, memory - usage, as well as per-process information from a running system. - Collected results are output as an SVG graph. Normally, - systemd-bootchart is invoked by the kernel by passing - <option>init=<filename>/usr/lib/systemd/systemd-bootchart</filename></option> - on the kernel command line. systemd-bootchart will then fork the - real init off to resume normal system startup, while monitoring - and logging startup information in the background. - </para> - <para> - After collecting a certain amount of data (usually 15-30 - seconds, default 20 s) the logging stops and a graph is - generated from the logged information. This graph contains vital - clues as to which resources are being used, in which order, and - where possible problems exist in the startup sequence of the - system. It is essentially a more detailed version of the - <command>systemd-analyze plot</command> function. - </para> - <para> - Of course, bootchart can also be used at any moment in time to - collect and graph some data for an amount of time. It is - recommended to use the <option>--rel</option> switch in this - case. - </para> - <para> - Bootchart does not require root privileges, and will happily run - as a normal user. - </para> - <para> - Bootchart graphs are by default written time-stamped in - <filename>/run/log</filename> and saved to the journal with - <varname>MESSAGE_ID=9f26aa562cf440c2b16c773d0479b518</varname>. - Journal field <varname>BOOTCHART=</varname> contains the - bootchart in SVG format. - </para> - - </refsect1> - - <refsect1> - <title>Invocation</title> - - <para><command>systemd-bootchart</command> can be invoked in several different ways:</para> - - <variablelist> - - <varlistentry> - <term><emphasis>Kernel invocation</emphasis></term> - <listitem><para>The kernel can invoke - <command>systemd-bootchart</command> instead of the init - process. In turn, <command>systemd-bootchart</command> will - invoke <command>/usr/lib/systemd/systemd</command>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><emphasis>Started as a standalone program</emphasis></term> - <listitem><para>One can execute - <command>systemd-bootchart</command> as normal application - from the command line. In this mode it is highly recommended - to pass the <option>-r</option> flag in order to not graph the - time elapsed since boot and before systemd-bootchart was - started, as it may result in extremely large graphs. The time - elapsed since boot might also include any time that the system - was suspended.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>These options can also be set in the - <filename>/etc/systemd/bootchart.conf</filename> file. See - <citerefentry project='man-pages'><refentrytitle>bootchart.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para> - - <variablelist> - <xi:include href="standard-options.xml" xpointer="help" /> - - <varlistentry> - <term><option>-n</option></term> - <term><option>--sample <replaceable>N</replaceable></option></term> - <listitem><para>Specify the number of samples, - <replaceable>N</replaceable>, to record. Samples will be - recorded at intervals defined with <option>--freq</option>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-f</option></term> - <term><option>--freq <replaceable>f</replaceable></option></term> - <listitem><para>Specify the sample log frequency, a positive - real <replaceable>f</replaceable>, in Hz. Most systems can - cope with values up to 25-50 without creating too much - overhead.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-r</option></term> - <term><option>--rel</option></term> - <listitem><para>Use relative times instead of absolute times. - This is useful for using bootchart at post-boot time to - profile an already booted system. Without this option the - graph would become extremely large. If set, the horizontal - axis starts at the first recorded sample instead of time - 0.0.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-F</option></term> - <term><option>--no-filter</option></term> - <listitem><para>Disable filtering of tasks that did not - contribute significantly to the boot. Processes that are too - short-lived (only seen in one sample) or that do not consume - any significant CPU time (less than 0.001 s) will not be - displayed in the output graph. </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-C</option></term> - <term><option>--cmdline</option></term> - <listitem><para>Display the full command line with arguments - of processes, instead of only the process name. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-g</option></term> - <term><option>--control-group</option></term> - <listitem><para>Display process control group - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-o</option></term> - <term><option>--output <replaceable>path</replaceable></option></term> - <listitem><para>Specify the output directory for the graphs. - By default, bootchart writes the graphs to - <filename>/run/log</filename>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-i</option></term> - <term><option>--init <replaceable>path</replaceable></option></term> - <listitem><para>Use this init binary. Defaults to - <command>/usr/lib/systemd/systemd</command>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-p</option></term> - <term><option>--pss</option></term> - <listitem><para>Enable logging and graphing of processes' PSS - (Proportional Set Size) memory consumption. See - <filename>filesystems/proc.txt</filename> in the kernel - documentation for an explanation of this field. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-e</option></term> - <term><option>--entropy</option></term> - <listitem><para>Enable logging and graphing of the kernel - random entropy pool size.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-x</option></term> - <term><option>--scale-x <replaceable>N</replaceable></option></term> - <listitem><para>Horizontal scaling factor for all variable - graph components.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-y</option></term> - <term><option>--scale-y <replaceable>N</replaceable></option></term> - <listitem><para>Vertical scaling factor for all variable graph - components.</para></listitem> - </varlistentry> - - </variablelist> - - - </refsect1> - - <refsect1> - <title>Output</title> - - <para><command>systemd-bootchart</command> generates SVG graphs. - In order to render those on a graphical display any SVG capable - viewer can be used. It should be noted that the SVG render engines - in most browsers (including Chrome and Firefox) are many times - faster than dedicated graphical applications like Gimp and - Inkscape. Just point your browser at - <ulink url="file:///run/log/" />! - </para> - </refsect1> - - <refsect1> - <title>History</title> - - <para>This version of bootchart was implemented from scratch, but - is inspired by former bootchart incantations:</para> - - <variablelist> - <varlistentry> - <term><emphasis>Original bash</emphasis></term> - <listitem><para>The original bash/shell code implemented - bootchart. This version created a compressed tarball for - processing with external applications. This version did not - graph anything, only generated data.</para></listitem> - </varlistentry> - - <varlistentry> - <term><emphasis>Ubuntu C Implementation</emphasis></term> - <listitem><para>This version replaced the shell version with a - fast and efficient data logger, but also did not graph the - data.</para></listitem> - </varlistentry> - - <varlistentry> - <term><emphasis>Java bootchart</emphasis></term> - <listitem><para>This was the original graphing application for - charting the data, written in java.</para></listitem> - </varlistentry> - - <varlistentry> - <term><emphasis>pybootchartgui.py</emphasis></term> - <listitem><para>pybootchart created a graph from the data - collected by either the bash or C version.</para></listitem> - </varlistentry> - </variablelist> - - <para>The version of bootchart you are using now combines both the - data collection and the charting into a single application, making - it more efficient and simpler. There are no longer any timing - issues with the data collector and the grapher, as the graphing - cannot be run until the data has been collected. Also, the data - kept in memory is reduced to the absolute minimum needed.</para> - - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry project='man-pages'><refentrytitle>bootchart.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> - - <refsect1> - <title>Bugs</title> - - <para>systemd-bootchart does not get the model information for the - hard drive unless the root device is specified with - <code>root=/dev/sdxY</code>. Using UUIDs or PARTUUIDs will boot - fine, but the hard drive model will not be added to the - chart.</para> - <para>For bugs, please contact the author and current maintainer:</para> - <simplelist> - <member>Auke Kok <email>auke-jan.h.kok@intel.com</email></member> - </simplelist> - </refsect1> - -</refentry> diff --git a/man/systemd-bus-proxyd.service.xml b/man/systemd-bus-proxyd.service.xml deleted file mode 100644 index 02189eea7c..0000000000 --- a/man/systemd-bus-proxyd.service.xml +++ /dev/null @@ -1,80 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - -<!-- - This file is part of systemd. - - Copyright 2013 Zbigniew Jędrzejewski-Szmek - - systemd is free software; you can redistribute it and/or modify it - under the terms of the GNU Lesser General Public License as published by - the Free Software Foundation; either version 2.1 of the License, or - (at your option) any later version. - - systemd is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public License - along with systemd; If not, see <http://www.gnu.org/licenses/>. ---> - -<refentry id="systemd-bus-proxyd.service"> - - <refentryinfo> - <title>systemd-bus-proxyd.service</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-bus-proxyd.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-bus-proxyd.service</refname> - <refname>systemd-bus-proxyd.socket</refname> - <refpurpose>Proxy classic D-Bus clients to kdbus</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-bus-proxyd.service</filename></para> - <para><filename>systemd-bus-proxyd.socket</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-bus-proxyd.socket</filename> will launch - <filename>systemd-bus-proxyd.service</filename> for connections - to the classic D-Bus socket in - <filename>/var/run/dbus/system_bus_socket</filename>.</para> - - <para><filename>systemd-bus-proxyd.service</filename> is launched - for an existing D-Bus connection and will use - <command>systemd-bus-proxyd</command> to proxy messages from this - connection to the system bus (either kdbus or classic D-Bus). - </para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd-bus-proxyd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='dbus'><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <ulink url="http://freedesktop.org/wiki/Software/dbus">D-Bus</ulink> - </para> - </refsect1> -</refentry> diff --git a/man/systemd-bus-proxyd.xml b/man/systemd-bus-proxyd.xml deleted file mode 100644 index 0923396151..0000000000 --- a/man/systemd-bus-proxyd.xml +++ /dev/null @@ -1,108 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - -<!-- - This file is part of systemd. - - Copyright 2013 Zbigniew Jędrzejewski-Szmek - - systemd is free software; you can redistribute it and/or modify it - under the terms of the GNU Lesser General Public License as published by - the Free Software Foundation; either version 2.1 of the License, or - (at your option) any later version. - - systemd is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public License - along with systemd; If not, see <http://www.gnu.org/licenses/>. ---> - -<refentry id="systemd-bus-proxyd" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-bus-proxyd</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-bus-proxyd</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-bus-proxyd</refname> - <refpurpose>Connect STDIO or a socket to a given bus address</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>/usr/lib/systemd/systemd-bus-proxyd</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="opt"><replaceable>PLACEHOLDER</replaceable></arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-bus-proxyd</command> will proxy D-Bus - messages to and from a bus. The will be either the system bus or - the bus specified with <option>--address</option> when that option - is given. Messages will be proxied to/from standard input and - output, or the socket received through socket activation.</para> - - <para>This program can be used to connect a program using classic - D-Bus to kdbus.</para> - </refsect1> - - <refsect1> - <title>Options and Arguments</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--address=<replaceable>ADDRESS</replaceable><optional>:<replaceable>ADDRESS...</replaceable></optional></option></term> - - <listitem> - <para>Connect to the bus specified by - <replaceable>ADDRESS</replaceable>. Multiple colon-separated - addresses can be specified, in which case - <command>systemd-bus-proxyd</command> will attempt to - connect to them in turn.</para> - </listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - - <para><replaceable>PLACEHOLDER</replaceable>, if given, must be a string - of <literal>x</literal> and will be used to display information about - the process that <command>systemd-bus-proxyd</command> is forwarding - messages for.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry project='dbus'><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <ulink url="http://freedesktop.org/wiki/Software/dbus">D-Bus</ulink> - </para> - </refsect1> -</refentry> diff --git a/man/systemd-cat.xml b/man/systemd-cat.xml index 9b1a8809dc..160db9fb5c 100644 --- a/man/systemd-cat.xml +++ b/man/systemd-cat.xml @@ -112,7 +112,7 @@ <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Defaults to <literal>info</literal>. Note that this simply controls the default, individual lines may be logged with - different levels if they are prefixed accordingly. For details + different levels if they are prefixed accordingly. For details, see <option>--level-prefix=</option> below.</para></listitem> </varlistentry> diff --git a/man/systemd-cgtop.xml b/man/systemd-cgtop.xml index d4b041a1f9..be13631239 100644 --- a/man/systemd-cgtop.xml +++ b/man/systemd-cgtop.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -52,6 +52,7 @@ <cmdsynopsis> <command>systemd-cgtop</command> <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="opt">GROUP</arg> </cmdsynopsis> </refsynopsisdiv> @@ -62,12 +63,14 @@ groups of the local Linux control group hierarchy, ordered by their CPU, memory, or disk I/O load. The display is refreshed in regular intervals (by default every 1s), similar in style to - <citerefentry project='man-pages'><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> + <citerefentry project='man-pages'><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + If a control group path is specified, shows only the services of + the specified control group.</para> - <para>If <command>systemd-cgtop</command> is not connected to a tty, no - column headers are printed and the default is to only run one iteration. - The <varname>--iterations</varname> argument, if given, is still honored. - This mode is suitable for scripting.</para> + <para>If <command>systemd-cgtop</command> is not connected to a + tty, no column headers are printed and the default is to only run + one iteration. The <varname>--iterations=</varname> argument, if + given, is honored. This mode is suitable for scripting.</para> <para>Resource usage is only accounted for control groups in the relevant hierarchy, i.e. CPU usage is only accounted for control @@ -104,6 +107,7 @@ <variablelist> <varlistentry> <term><option>-p</option></term> + <term><option>--order=path</option></term> <listitem><para>Order by control group path name.</para></listitem> @@ -111,25 +115,28 @@ <varlistentry> <term><option>-t</option></term> + <term><option>--order=tasks</option></term> - <listitem><para>Order by number of tasks in control group - (i.e. threads and processes).</para></listitem> + <listitem><para>Order by number of tasks/processes in the control group.</para></listitem> </varlistentry> <varlistentry> <term><option>-c</option></term> + <term><option>--order=cpu</option></term> <listitem><para>Order by CPU load.</para></listitem> </varlistentry> <varlistentry> <term><option>-m</option></term> + <term><option>--order=memory</option></term> <listitem><para>Order by memory usage.</para></listitem> </varlistentry> <varlistentry> <term><option>-i</option></term> + <term><option>--order=io</option></term> <listitem><para>Order by disk I/O load.</para></listitem> </varlistentry> @@ -140,7 +147,7 @@ <listitem><para>Run in "batch" mode: do not accept input and run until the iteration limit set with - <option>--iterations</option> is exhausted or until killed. + <option>--iterations=</option> is exhausted or until killed. This mode could be useful for sending output from <command>systemd-cgtop</command> to other programs or to a file.</para></listitem> @@ -150,17 +157,73 @@ <term><option>-r</option></term> <term><option>--raw</option></term> - <listitem><para>Format byte counts (as in memory usage and IO metrics) + <listitem><para>Format byte counts (as in memory usage and I/O metrics) with raw numeric values rather than human-readable numbers.</para></listitem> </varlistentry> <varlistentry> + <term><option>--cpu=percentage</option></term> + <term><option>--cpu=time</option></term> + + <listitem><para>Controls whether the CPU usage is shown as + percentage or time. By default, the CPU usage is shown as + percentage. This setting may also be toggled at runtime by + pressing the <keycap>%</keycap> key.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-P</option></term> + + <listitem><para>Count only userspace processes instead of all + tasks. By default, all tasks are counted: each kernel thread + and each userspace thread individually. With this setting, + kernel threads are excluded from the counting and each + userspace process only counts as one, regardless how many + threads it consists of. This setting may also be toggled at + runtime by pressing the <keycap>P</keycap> key. This option + may not be combined with + <option>-k</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-k</option></term> + + <listitem><para>Count only userspace processes and kernel + threads instead of all tasks. By default, all tasks are + counted: each kernel thread and each userspace thread + individually. With this setting, kernel threads are included in + the counting and each userspace process only counts as on one, + regardless how many threads it consists of. This setting may + also be toggled at runtime by pressing the <keycap>k</keycap> + key. This option may not be combined with + <option>-P</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--recursive=</option></term> + + <listitem><para>Controls whether the number of processes shown + for a control group shall include all processes that are + contained in any of the child control groups as well. Takes a + boolean argument, which defaults to <literal>yes</literal>. If + enabled, the processes in child control groups are included, if + disabled, only the processes in the control group itself are + counted. This setting may also be toggled at runtime by + pressing the <keycap>r</keycap> key. Note that this setting + only applies to process counting, i.e. when the + <option>-P</option> or <option>-k</option> options are + used. It has not effect if all tasks are counted, in which + case the counting is always recursive.</para></listitem> + </varlistentry> + + <varlistentry> <term><option>-n</option></term> <term><option>--iterations=</option></term> - <listitem><para>Perform only this many iterations. A value of 0 - indicates that the program should run indefinitely.</para></listitem> + <listitem><para>Perform only this many iterations. A value of + 0 indicates that the program should run + indefinitely.</para></listitem> </varlistentry> <varlistentry> @@ -168,10 +231,11 @@ <term><option>--delay=</option></term> <listitem><para>Specify refresh delay in seconds (or if one of - <literal>ms</literal>, - <literal>us</literal>, + <literal>ms</literal>, <literal>us</literal>, <literal>min</literal> is specified as unit in this time - unit).</para></listitem> + unit). This setting may also be increased and decreased at + runtime by pressing the <keycap>+</keycap> and + <keycap>-</keycap> keys.</para></listitem> </varlistentry> <varlistentry> @@ -185,13 +249,22 @@ 3.</para></listitem> </varlistentry> + <varlistentry> + <term><option>-M <replaceable>MACHINE</replaceable></option></term> + <term><option>--machine=<replaceable>MACHINE</replaceable></option></term> + + <listitem><para>Limit control groups shown to the part + corresponding to the container + <replaceable>MACHINE</replaceable>. + This option may not be used when a control group path is specified.</para></listitem> + </varlistentry> + <xi:include href="standard-options.xml" xpointer="help" /> <xi:include href="standard-options.xml" xpointer="version" /> </variablelist> </refsect1> - <refsect1> <title>Keys</title> @@ -200,49 +273,84 @@ <variablelist> <varlistentry> - <term>h</term> + <term><keycap>h</keycap></term> <listitem><para>Shows a short help text.</para></listitem> </varlistentry> <varlistentry> - <term>SPACE</term> + <term><keycap function="space"/></term> <listitem><para>Immediately refresh output.</para></listitem> </varlistentry> <varlistentry> - <term>q</term> + <term><keycap>q</keycap></term> <listitem><para>Terminate the program.</para></listitem> </varlistentry> - <varlistentry> - <term>p</term> - <term>t</term> - <term>c</term> - <term>m</term> - <term>i</term> + <term><keycap>p</keycap></term> + <term><keycap>t</keycap></term> + <term><keycap>c</keycap></term> + <term><keycap>m</keycap></term> + <term><keycap>i</keycap></term> <listitem><para>Sort the control groups by path, number of - tasks, CPU load, memory usage, or IO load, respectively. - </para></listitem> + tasks, CPU load, memory usage, or I/O load, respectively. This + setting may also be controlled using the + <option>--order=</option> command line + switch.</para></listitem> </varlistentry> <varlistentry> - <term>%</term> + <term><keycap>%</keycap></term> <listitem><para>Toggle between showing CPU time as time or - percentage.</para></listitem> + percentage. This setting may also be controlled using the + <option>--cpu=</option> command line switch.</para></listitem> </varlistentry> <varlistentry> - <term>+</term> - <term>-</term> + <term><keycap>+</keycap></term> + <term><keycap>-</keycap></term> <listitem><para>Increase or decrease refresh delay, - respectively.</para></listitem> + respectively. This setting may also be controlled using the + <option>--delay=</option> command line + switch.</para></listitem> + </varlistentry> + + <varlistentry> + <term><keycap>P</keycap></term> + + <listitem><para>Toggle between counting all tasks, or only + userspace processes. This setting may also be controlled using + the <option>-P</option> command line switch (see + above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><keycap>k</keycap></term> + + <listitem><para>Toggle between counting all tasks, or only + userspace processes and kernel threads. This setting may also + be controlled using the <option>-k</option> command line + switch (see above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><keycap>r</keycap></term> + + <listitem><para>Toggle between recursively including or + excluding processes in child control groups in control group + process counts. This setting may also be controlled using the + <option>--recursive=</option> command line switch. This key is + not available if all tasks are counted, it is only available + if processes are counted, as enabled with the + <keycap>P</keycap> or <keycap>k</keycap> + keys.</para></listitem> </varlistentry> </variablelist> diff --git a/man/systemd-coredump.xml b/man/systemd-coredump.xml index 5da3857c08..4a1bc8b296 100644 --- a/man/systemd-coredump.xml +++ b/man/systemd-coredump.xml @@ -45,50 +45,89 @@ <refnamediv> <refname>systemd-coredump</refname> - <refpurpose>Log and store core dumps</refpurpose> + <refname>systemd-coredump.socket</refname> + <refname>systemd-coredump@.service</refname> + <refpurpose>Acquire, save and process core dumps</refpurpose> </refnamediv> <refsynopsisdiv> <para><filename>/usr/lib/systemd/systemd-coredump</filename></para> + <para><filename>systemd-coredump@.service</filename></para> + <para><filename>systemd-coredump.socket</filename></para> </refsynopsisdiv> <refsect1> <title>Description</title> + <para><command>systemd-coredump</command> is a system service that can acquire core dumps + from the kernel and handle them in various ways.</para> - <para><command>systemd-coredump</command> can be used as a helper - binary by the kernel when a user space program receives a fatal - signal and dumps core. For it to be used in this capacity, it must - be specified by the - <varname>kernel.core_pattern</varname> <citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> - setting. Systemd installs - <filename>/usr/lib/sysctl.d/50-coredump.conf</filename> which - configures <varname>kernel.core_pattern</varname> to invoke - <command>systemd-coredump</command>. This file may be masked or - overridden to use a different setting following normal - <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> rules.</para> - - <para>The behaviour of a specific program upon reception of a - signal is governed by a few factors which are described in detail - in <citerefentry project='man-pages'><refentrytitle>core</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - In particular, the coredump will only be processed when the - related resource limits are high enough. For programs started by - <command>systemd</command> those may be set using - <varname>LimitCore=</varname> (see - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + <para>Core dumps can be written to the journal or saved as a file. Once saved they can be retrieved + for further processing, for example in + <citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>. </para> - <para><command>systemd-coredump</command> will log the coredump - including a backtrace if possible, and store the core (contents of - process' memory contents) in an external file on disk in - <filename>/var/lib/systemd/coredump</filename>, or directly in - the journal. This behaviour may be modified using - <citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + <para>By default, <command>systemd-coredump</command> will log the core dump including a backtrace + if possible to the journal and store the core dump itself in an external file in + <filename>/var/lib/systemd/coredump</filename>.</para> + + <para>When the kernel invokes <command>systemd-coredump</command> to handle a core dump, + it will connect to the socket created by the <filename>systemd-coredump.socket</filename> + unit, which in turn will spawn a <filename>systemd-coredump@.service</filename> instance + to process the core dump. Hence <filename>systemd-coredump.socket</filename> + and <filename>systemd-coredump@.service</filename> are helper units which do the actual + processing of core dumps and are subject to normal service management.</para> + + <para>The behavior of a specific program upon reception of a signal is governed by a few + factors which are described in detail in + <citerefentry project='man-pages'><refentrytitle>core</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + In particular, the core dump will only be processed when the related resource limits are sufficient. + </para> + </refsect1> + + <refsect1> + <title>Configuration</title> + <para>For programs started by <command>systemd</command> process resource limits can be set by directive + <varname>LimitCore=</varname>, see + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para> - <para>Apart from the + <para>In order to be used <command>systemd-coredump</command> must be configured in + <citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> + parameter <varname>kernel.core_pattern</varname>. The syntax of this parameter is explained in + <citerefentry project='man-pages'><refentrytitle>core</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + Systemd installs the file <filename>/usr/lib/sysctl.d/50-coredump.conf</filename> which configures + <varname>kernel.core_pattern</varname> accordingly. This file may be masked or overridden to use a different + setting following normal + <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> + rules. + If the sysctl configuration is modified, it must be updated in the kernel before + it takes effect, see + <citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd-sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + </para> + + <para>The behavior of <command>systemd-coredump</command> itself is configured through the configuration file + <filename>/etc/systemd/coredump.conf</filename> and corresponding snippets + <filename>/etc/systemd/coredump.conf.d/*.conf</filename>, see + <citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. A new + instance of <command>systemd-coredump</command> is invoked upon receiving every core dump. Therefore, changes + in these files will take effect the next time a core dump is received.</para> + + <para>Resources used by core dump files are restricted in two ways. Parameters like maximum size of acquired + core dumps and files can be set in files <filename>/etc/systemd/coredump.conf</filename> and snippets mentioned + above. In addition the storage time of core dump files is restricted by <command>systemd-tmpfiles</command>, + corresponding settings are by default in <filename>/usr/lib/tmpfiles.d/systemd.conf</filename>.</para> + </refsect1> + + <refsect1> + <title>Usage</title> + <para>Data stored in the journal can be viewed with <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - log viewer, + as usual. <citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - may be used to list and extract coredumps.</para> + can be used to retrieve saved core dumps independent of their location, to display information and to process + them e.g. by passing to the GNU debugger (gdb).</para> </refsect1> <refsect1> @@ -97,6 +136,7 @@ <citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>core</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-sysctl.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. diff --git a/man/systemd-cryptsetup-generator.xml b/man/systemd-cryptsetup-generator.xml index b6270358ea..f036ab9744 100644 --- a/man/systemd-cryptsetup-generator.xml +++ b/man/systemd-cryptsetup-generator.xml @@ -111,7 +111,7 @@ system and the initrd.</para> <para>If /etc/crypttab contains entries with the same UUID, then the name, keyfile and options specified there will be - used. Otherwise the device will have the name + used. Otherwise, the device will have the name <literal>luks-UUID</literal>.</para> <para>If /etc/crypttab exists, only those UUIDs specified on the kernel command line diff --git a/man/systemd-delta.xml b/man/systemd-delta.xml index 6a6460ffaa..99709604aa 100644 --- a/man/systemd-delta.xml +++ b/man/systemd-delta.xml @@ -70,7 +70,7 @@ directories which contain "drop-in" files with configuration snippets which augment the main configuration file. "Drop-in" files can be overridden in the same way by placing files with the - same name in a directory of higher priority (except that in case + same name in a directory of higher priority (except that, in case of "drop-in" files, both the "drop-in" file name and the name of the containing directory, which corresponds to the name of the main configuration file, must match). For a fuller explanation, diff --git a/man/systemd-detect-virt.xml b/man/systemd-detect-virt.xml index 40755a24d0..61a5f8937f 100644 --- a/man/systemd-detect-virt.xml +++ b/man/systemd-detect-virt.xml @@ -22,7 +22,7 @@ --> <refentry id="systemd-detect-virt" - xmlns:xi="http://www.w3.org/2001/XInclude"> + xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>systemd-detect-virt</title> @@ -59,10 +59,10 @@ <para><command>systemd-detect-virt</command> detects execution in a virtualized environment. It identifies the virtualization - technology and can distinguish full VM virtualization from + technology and can distinguish full machine virtualization from container virtualization. <filename>systemd-detect-virt</filename> exits with a return value of 0 (success) if a virtualization - technology is detected, and non-zero (error) otherwise. By default + technology is detected, and non-zero (error) otherwise. By default, any type of virtualization is detected, and the options <option>--container</option> and <option>--vm</option> can be used to limit what types of virtualization are detected.</para> @@ -81,90 +81,105 @@ <colspec colname="product" /> <thead> <row> - <entry>Type</entry> - <entry>ID</entry> - <entry>Product</entry> + <entry>Type</entry> + <entry>ID</entry> + <entry>Product</entry> </row> </thead> <tbody> <row> - <entry morerows="8">VM</entry> - <entry><varname>qemu</varname></entry> - <entry>QEMU software virtualization</entry> + <entry valign="top" morerows="10">VM</entry> + <entry><varname>qemu</varname></entry> + <entry>QEMU software virtualization</entry> </row> <row> - <entry><varname>kvm</varname></entry> - <entry>Linux KVM kernel virtual machine</entry> + <entry><varname>kvm</varname></entry> + <entry>Linux KVM kernel virtual machine</entry> </row> <row> - <entry><varname>zvm</varname></entry> - <entry>s390 z/VM</entry> + <entry><varname>zvm</varname></entry> + <entry>s390 z/VM</entry> </row> <row> - <entry><varname>vmware</varname></entry> - <entry>VMware Workstation or Server, and related products</entry> + <entry><varname>vmware</varname></entry> + <entry>VMware Workstation or Server, and related products</entry> </row> <row> - <entry><varname>microsoft</varname></entry> - <entry>Hyper-V, also known as Viridian or Windows Server Virtualization</entry> + <entry><varname>microsoft</varname></entry> + <entry>Hyper-V, also known as Viridian or Windows Server Virtualization</entry> </row> <row> - <entry><varname>oracle</varname></entry> - <entry>Oracle VM VirtualBox (historically marketed by innotek and Sun Microsystems)</entry> + <entry><varname>oracle</varname></entry> + <entry>Oracle VM VirtualBox (historically marketed by innotek and Sun Microsystems)</entry> </row> <row> - <entry><varname>xen</varname></entry> - <entry>Xen hypervisor (only domU, not dom0)</entry> + <entry><varname>xen</varname></entry> + <entry>Xen hypervisor (only domU, not dom0)</entry> </row> <row> - <entry><varname>bochs</varname></entry> - <entry>Bochs Emulator</entry> + <entry><varname>bochs</varname></entry> + <entry>Bochs Emulator</entry> </row> <row> - <entry><varname>uml</varname></entry> - <entry>User-mode Linux</entry> + <entry><varname>uml</varname></entry> + <entry>User-mode Linux</entry> </row> <row> - <entry morerows="5">container</entry> - <entry><varname>openvz</varname></entry> - <entry>OpenVZ/Virtuozzo</entry> + <entry><varname>parallels</varname></entry> + <entry>Parallels Desktop, Parallels Server</entry> + </row> + + <row> + <entry><varname>bhyve</varname></entry> + <entry>bhyve, FreeBSD hypervisor</entry> + </row> + + <row> + <entry valign="top" morerows="5">Container</entry> + <entry><varname>openvz</varname></entry> + <entry>OpenVZ/Virtuozzo</entry> </row> <row> - <entry><varname>lxc</varname></entry> - <entry>Linux container implementation by LXC</entry> + <entry><varname>lxc</varname></entry> + <entry>Linux container implementation by LXC</entry> </row> <row> - <entry><varname>lxc-libvirt</varname></entry> - <entry>Linux container implementation by libvirt</entry> + <entry><varname>lxc-libvirt</varname></entry> + <entry>Linux container implementation by libvirt</entry> </row> <row> - <entry><varname>systemd-nspawn</varname></entry> - <entry>systemd's minimal container implementation, see <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry></entry> + <entry><varname>systemd-nspawn</varname></entry> + <entry>systemd's minimal container implementation, see <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry></entry> </row> <row> - <entry><varname>docker</varname></entry> - <entry>Docker container manager</entry> + <entry><varname>docker</varname></entry> + <entry>Docker container manager</entry> + </row> + + <row> + <entry><varname>rkt</varname></entry> + <entry>rkt app container runtime</entry> </row> </tbody> </tgroup> </table> <para>If multiple virtualization solutions are used, only the - "innermost" is detected and identified. That means if both VM - virtualization and container virtualization are used in + "innermost" is detected and identified. That means if both + machine and container virtualization are used in conjunction, only the latter will be identified (unless <option>--vm</option> is passed).</para> </refsect1> @@ -187,8 +202,19 @@ <term><option>-v</option></term> <term><option>--vm</option></term> - <listitem><para>Only detects VM virtualization (i.e. full - hardware virtualization).</para></listitem> + <listitem><para>Only detects hardware virtualization).</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-r</option></term> + <term><option>--chroot</option></term> + + <listitem><para>Detect whether invoked in a + <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry> + environment. In this mode, no output is written, but the return + value indicates whether the process was invoked in a + <function>chroot()</function> + environment or not.</para></listitem> </varlistentry> <varlistentry> @@ -216,7 +242,8 @@ <title>See Also</title> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/systemd-efi-boot-generator.xml b/man/systemd-efi-boot-generator.xml deleted file mode 100644 index 23464bcf15..0000000000 --- a/man/systemd-efi-boot-generator.xml +++ /dev/null @@ -1,85 +0,0 @@ -<?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"> -<!-- - This file is part of systemd. - - Copyright 2013 Lennart Poettering - - systemd is free software; you can redistribute it and/or modify it - under the terms of the GNU Lesser General Public License as published by - the Free Software Foundation; either version 2.1 of the License, or - (at your option) any later version. - - systemd is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public License - along with systemd; If not, see <http://www.gnu.org/licenses/>. ---> -<refentry id="systemd-efi-boot-generator"> - - <refentryinfo> - <title>systemd-efi-boot-generator</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-efi-boot-generator</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-efi-boot-generator</refname> - <refpurpose>Generator for automatically mounting the - EFI System Partition used by the current boot to - <filename>/boot</filename></refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/usr/lib/systemd/system-generators/systemd-efi-boot-generator</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-efi-boot-generator</filename> is a - generator that automatically creates mount and automount units for - the EFI System Partition (ESP), mounting it to - <filename>/boot</filename>. Note that this generator will execute - no operation on non-EFI systems, on systems where the boot loader - does not communicate the used ESP to the OS, on systems where - <filename>/boot</filename> is an explicitly configured mount (for - example, listed in - <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>) - or where the <filename>/boot</filename> mount point is non-empty. - Since this generator creates an automount unit, the mount will - only be activated on-demand, when accessed.</para> - - <para><filename>systemd-efi-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.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-escape.xml b/man/systemd-escape.xml index 0c3b230526..dbb3869a24 100644 --- a/man/systemd-escape.xml +++ b/man/systemd-escape.xml @@ -64,14 +64,14 @@ used to escape and to undo escaping of strings.</para> <para>The command takes any number of strings on the command line, - and will process them individually, one after the other. It will + and will process them individually, one after another. It will output them separated by spaces to stdout.</para> - <para>By default this command will escape the strings passed, + <para>By default, this command will escape the strings passed, unless <option>--unescape</option> is passed which results in the - inverse operation being applied. If <option>--mangle</option> a - special mode of escaping is applied instead, which assumes a - string to be already escaped but will escape everything that + inverse operation being applied. If <option>--mangle</option> is given, a + special mode of escaping is applied instead, which assumes the + string is already escaped but will escape everything that appears obviously non-escaped.</para> </refsect1> diff --git a/man/systemd-firstboot.xml b/man/systemd-firstboot.xml index 67289daa26..b269e48113 100644 --- a/man/systemd-firstboot.xml +++ b/man/systemd-firstboot.xml @@ -80,12 +80,12 @@ <listitem><para>The root user's password</para></listitem> </itemizedlist> - <para>Each of the fields may either be queried interactively from - the users, set non-interactively on the tool's command line, or be + <para>Each of the fields may either be queried interactively by + users, set non-interactively on the tool's command line, or be copied from a host system that is used to set up the system image.</para> - <para>If a setting is already initialized it will not be + <para>If a setting is already initialized, it will not be overwritten and the user will not be prompted for the setting.</para> @@ -166,10 +166,10 @@ <citerefentry project='die-net'><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry> file. This setting exists in two forms: <option>--root-password=</option> accepts the password to set - directly on the command line, + directly on the command line, and <option>--root-password-file=</option> reads it from a file. - Note that it is not recommended specifying passwords on the - command line as other users might be able to see them simply + Note that it is not recommended to specify passwords on the + command line, as other users might be able to see them simply by invoking <citerefentry project='die-net'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem> </varlistentry> diff --git a/man/systemd-fsck@.service.xml b/man/systemd-fsck@.service.xml index e4ffcba168..933c3247ad 100644 --- a/man/systemd-fsck@.service.xml +++ b/man/systemd-fsck@.service.xml @@ -61,16 +61,16 @@ responsible for file system checks. They are instantiated for each device that is configured for file system checking. <filename>systemd-fsck-root.service</filename> is responsible for - file system checks on the root file system, but in only if the - root filesystem wasn't checked in the initramfs. + file system checks on the root file system, but only if the + root filesystem was not checked in the initramfs. <filename>systemd-fsck@.service</filename> is used for all other file systems and for the root file system in the initramfs.</para> - <para>Those services are started at boot if + <para>These services are started at boot if <option>passno</option> in <filename>/etc/fstab</filename> for the file system is set to a value greater than zero. The file system check for root is performed before the other file systems. Other - file systems may be checked in parallel, except when they are one + file systems may be checked in parallel, except when they are on the same rotating disk.</para> <para><filename>systemd-fsck</filename> does not know any details diff --git a/man/systemd-fstab-generator.xml b/man/systemd-fstab-generator.xml index c09ed4b4da..a971cb3675 100644 --- a/man/systemd-fstab-generator.xml +++ b/man/systemd-fstab-generator.xml @@ -126,7 +126,7 @@ <varname>mount.usr=</varname> will default to the value set in <varname>root=</varname>.</para> - <para>Otherwise this parameter defaults to the + <para>Otherwise, this parameter defaults to the <filename>/usr</filename> entry found in <filename>/etc/fstab</filename> on the root filesystem.</para> @@ -143,7 +143,7 @@ <varname>mount.usrfstype=</varname> will default to the value set in <varname>rootfstype=</varname>.</para> - <para>Otherwise this value will be read from the + <para>Otherwise, this value will be read from the <filename>/usr</filename> entry in <filename>/etc/fstab</filename> on the root filesystem.</para> @@ -159,7 +159,7 @@ <varname>mount.usrflags=</varname> will default to the value set in <varname>rootflags=</varname>.</para> - <para>Otherwise this value will be read from the + <para>Otherwise, this value will be read from the <filename>/usr</filename> entry in <filename>/etc/fstab</filename> on the root filesystem.</para> diff --git a/man/systemd-gpt-auto-generator.xml b/man/systemd-gpt-auto-generator.xml index 710c2e065e..d26206710f 100644 --- a/man/systemd-gpt-auto-generator.xml +++ b/man/systemd-gpt-auto-generator.xml @@ -69,7 +69,7 @@ units are explicitly configured (for example, listed in <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>), - the units this generator creates are overriden, but additional + the units this generator creates are overridden, but additional automatic dependencies might be created.</para> <para>This generator will only look for root partitions on the @@ -137,12 +137,17 @@ <entry>Swap</entry> <entry>All swap partitions located on the disk the root partition is located on are enabled.</entry> </row> + <row> + <entry>c12a7328-f81f-11d2-ba4b-00a0c93ec93b</entry> + <entry>EFI System Partition (ESP)</entry> + <entry>The first ESP located on the disk the root partition is located on is mounted to <filename>/boot</filename> or <filename>/efi</filename>, see below.</entry> + </row> </tbody> </tgroup> </table> <para>The <filename>/home</filename> and <filename>/srv</filename> - partitions may be encrypted in LUKS format. In this case a device + partitions may be encrypted in LUKS format. In this case, a device mapper device is set up under the names <filename>/dev/mapper/home</filename> and <filename>/dev/mapper/srv</filename>. Note that this might create @@ -150,10 +155,14 @@ <filename>/etc/crypttab</filename> with a different device mapper device name.</para> - <para>Also note that - <citerefentry><refentrytitle>systemd-efi-boot-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> - will mount the EFI System Partition (ESP) to - <filename>/boot</filename> if not otherwise mounted.</para> + <para>Mount and automount units for the EFI System Partition (ESP) are generated on EFI systems. The ESP is mounted + to <filename>/boot</filename>, unless a mount point directory <filename>/efi</filename> exists, in which case it is + mounted there. Since this generator creates an automount unit, the mount will only be activated on-demand, when + accessed. On systems where <filename>/boot</filename> (or <filename>/efi</filename> if it exists) is an explicitly + configured mount (for example, listed in <citerefentry + project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>) or where the + <filename>/boot</filename> (or <filename>/efi</filename>) mount point is non-empty, no mount units are + generated.</para> <para>When using this generator in conjunction with btrfs file systems, make sure to set the correct default subvolumes on them, @@ -170,7 +179,6 @@ <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-efi-boot-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, diff --git a/man/systemd-halt.service.xml b/man/systemd-halt.service.xml index c94e2a1820..d16e5d628f 100644 --- a/man/systemd-halt.service.xml +++ b/man/systemd-halt.service.xml @@ -57,6 +57,7 @@ <para><filename>systemd-reboot.service</filename></para> <para><filename>systemd-kexec.service</filename></para> <para><filename>/usr/lib/systemd/systemd-shutdown</filename></para> + <para><filename>/usr/lib/systemd/system-shutdown/</filename></para> </refsynopsisdiv> <refsect1> diff --git a/man/systemd-hwdb.xml b/man/systemd-hwdb.xml index f1a14025b0..2b363c77f2 100644 --- a/man/systemd-hwdb.xml +++ b/man/systemd-hwdb.xml @@ -64,7 +64,7 @@ <term><option>-r</option></term> <term><option>--root=<replaceable>PATH</replaceable></option></term> <listitem> - <para>Alternative root path in the filesystem.</para> + <para>Alternate root path in the filesystem.</para> </listitem> </varlistentry> </variablelist> diff --git a/man/systemd-importd.service.xml b/man/systemd-importd.service.xml new file mode 100644 index 0000000000..8fdced475c --- /dev/null +++ b/man/systemd-importd.service.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"> + +<!-- + This file is part of systemd. + + Copyright 2016 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-importd.service" conditional='ENABLE_IMPORTD'> + + <refentryinfo> + <title>systemd-importd.service</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-importd.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-importd.service</refname> + <refname>systemd-importd</refname> + <refpurpose>VM and container image import and export service</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-importd.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-importd</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-importd</command> is a system service that allows importing, exporting and downloading of + system images suitable for running as VM or containers. It is a companion service for + <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, and provides the implementation for + <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s + <command>pull-raw</command>, <command>pull-tar</command>, <command>import-raw</command>, + <command>import-tar</command>, <command>export-raw</command>, and <command>export-tar</command> commands.</para> + + <para>See the + <ulink url="http://www.freedesktop.org/wiki/Software/systemd/importd"> + importd D-Bus API Documentation</ulink> for information about the + APIs <filename>systemd-importd</filename> provides.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-inhibit.xml b/man/systemd-inhibit.xml index 9d85908f97..ce169960d8 100644 --- a/man/systemd-inhibit.xml +++ b/man/systemd-inhibit.xml @@ -61,7 +61,7 @@ <title>Description</title> <para><command>systemd-inhibit</command> may be used to execute a - program with a shutdown, sleep or idle inhibitor lock taken. The + program with a shutdown, sleep, or idle inhibitor lock taken. The lock will be acquired before the specified command line is executed and released afterwards.</para> diff --git a/man/systemd-journal-gatewayd.service.xml b/man/systemd-journal-gatewayd.service.xml index 6df2248578..2cb114f6e3 100644 --- a/man/systemd-journal-gatewayd.service.xml +++ b/man/systemd-journal-gatewayd.service.xml @@ -100,6 +100,16 @@ with <option>--cert=</option>.</para></listitem> </varlistentry> + <varlistentry> + <term><option>-D <replaceable>DIR</replaceable></option></term> + <term><option>--directory=<replaceable>DIR</replaceable></option></term> + + <listitem><para>Takes a directory path as argument. If + specified, <command>systemd-journal-gatewayd</command> will serve the + specified journal directory <replaceable>DIR</replaceable> instead of + the default runtime and system journal paths.</para></listitem> + </varlistentry> + <xi:include href="standard-options.xml" xpointer="help" /> <xi:include href="standard-options.xml" xpointer="version" /> </variablelist> @@ -193,7 +203,7 @@ </varlistentry> <varlistentry> - <term><constant>application/event-stream</constant></term> + <term><constant>text/event-stream</constant></term> <listitem><para>Entries are formatted as JSON data structures, wrapped in a format suitable for <ulink @@ -262,7 +272,7 @@ <term><uri>boot</uri></term> <listitem><para>Limit events to the current boot of the system - (like <command>journalctl --this--boot</command>).</para></listitem> + (like <command>journalctl --this-boot</command>).</para></listitem> </varlistentry> <varlistentry> diff --git a/man/systemd-journal-remote.xml b/man/systemd-journal-remote.xml index ebaca2657f..ee2d5c2486 100644 --- a/man/systemd-journal-remote.xml +++ b/man/systemd-journal-remote.xml @@ -121,8 +121,8 @@ <replaceable>ADDRESS</replaceable>. This URL should refer to the root of a remote <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry> - instance (e.g. <ulink>http://some.host:19531/</ulink> or - <ulink>https://some.host:19531/</ulink>).</para></listitem> + instance, e.g. http://some.host:19531/ or + https://some.host:19531/.</para></listitem> </varlistentry> </variablelist> @@ -250,20 +250,19 @@ </varlistentry> <varlistentry> - <term><option>--compress</option></term> - <term><option>--no-compress</option></term> + <term><option>--compress</option> [<replaceable>BOOL</replaceable>]</term> - <listitem><para>Compress or not, respectively, the data in the - journal using XZ.</para></listitem> + <listitem><para>If this is set to <literal>yes</literal> then compress + the data in the journal using XZ. The default is <literal>yes</literal>. + </para></listitem> </varlistentry> <varlistentry> - <term><option>--seal</option></term> - <term><option>--no-seal</option></term> + <term><option>--seal</option> [<replaceable>BOOL</replaceable>]</term> - <listitem><para>Periodically sign or not, respectively, the - data in the journal using Forward Secure Sealing. - </para></listitem> + <listitem><para>If this is set to <literal>yes</literal> then + periodically sign the data in the journal using Forward Secure Sealing. + The default is <literal>no</literal>.</para></listitem> </varlistentry> <varlistentry> @@ -293,15 +292,24 @@ journalctl -o export | systemd-journal-remote -o /tmp/dir - </programlisting> </para> - <para>Retrieve events from a remote + <para>Retrieve all available events from a remote <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry> instance and store them in - <filename>/var/log/journal/some.host/remote-some~host.journal</filename>: + <filename>/var/log/journal/remote/remote-some.host.journal</filename>: <programlisting> systemd-journal-remote --url http://some.host:19531/ </programlisting> </para> - </refsect1> + + <para>Retrieve current boot events and wait for new events from a remote + <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry> + instance, and store them in + <filename>/var/log/journal/remote/remote-some.host.journal</filename>: + <programlisting> +systemd-journal-remote --url http://some.host:19531/entries?boot&follow + </programlisting> + </para> +</refsect1> <refsect1> <title>See Also</title> diff --git a/man/systemd-journal-upload.xml b/man/systemd-journal-upload.xml index 597f2a2d3e..f9723dea89 100644 --- a/man/systemd-journal-upload.xml +++ b/man/systemd-journal-upload.xml @@ -196,7 +196,7 @@ <programlisting>openssl req -newkey rsa:2048 -days 3650 -x509 -nodes \ -out ca.pem -keyout ca.key -subj '/CN=Certificate authority/' -cat >ca.conf <<EOF +cat >ca.conf <<EOF [ ca ] default_ca = this @@ -221,7 +221,7 @@ emailAddress = optional EOF touch index -echo 0001 > serial +echo 0001 >serial SERVER=server CLIENT=client @@ -244,7 +244,7 @@ openssl ca -batch -config ca.conf -notext -in $CLIENT.csr -out $CLIENT.pem <varname>ServerCertificateFile=</varname>, <varname>ServerKeyFile=</varname>, in <filename>/etc/systemd/journal-remote.conf</filename> and - <filename>/etc/systemd/journal-upload.conf</filename> + <filename>/etc/systemd/journal-upload.conf</filename>, respectively. The default locations can be queried by using <command>systemd-journal-remote --help</command> and <command>systemd-journal-upload --help</command>.</para> diff --git a/man/systemd-journald.service.xml b/man/systemd-journald.service.xml index 8280d6c874..2810638bc2 100644 --- a/man/systemd-journald.service.xml +++ b/man/systemd-journald.service.xml @@ -46,6 +46,7 @@ <refname>systemd-journald.service</refname> <refname>systemd-journald.socket</refname> <refname>systemd-journald-dev-log.socket</refname> + <refname>systemd-journald-audit.socket</refname> <refname>systemd-journald</refname> <refpurpose>Journal service</refpurpose> </refnamediv> @@ -54,6 +55,7 @@ <para><filename>systemd-journald.service</filename></para> <para><filename>systemd-journald.socket</filename></para> <para><filename>systemd-journald-dev-log.socket</filename></para> + <para><filename>systemd-journald-audit.socket</filename></para> <para><filename>/usr/lib/systemd/systemd-journald</filename></para> </refsynopsisdiv> @@ -99,14 +101,10 @@ reboot. To make the data persistent, it is sufficient to create <filename>/var/log/journal/</filename> where <filename>systemd-journald</filename> will then store the - data.</para> + data:</para> - <para><filename>systemd-journald</filename> will forward all - received log messages to the - <constant>AF_UNIX</constant>/<constant>SOCK_DGRAM</constant> - socket <filename>/run/systemd/journal/syslog</filename>, if it - exists, which may be used by Unix syslog daemons to process the - data further.</para> + <programlisting>mkdir -p /var/log/journal +systemd-tmpfiles --create --prefix /var/log/journal</programlisting> <para>See <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> @@ -126,15 +124,30 @@ this is enabled). This must be used after <filename>/var/</filename> is mounted, as otherwise log data from <filename>/run</filename> is never flushed to - <filename>/var</filename> regardless of the - configuration.</para></listitem> + <filename>/var</filename> regardless of the configuration. The + <command>journalctl --flush</command> command uses this signal + to request flushing of the journal files, and then waits for + the operation to complete. See + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for details.</para></listitem> </varlistentry> <varlistentry> <term>SIGUSR2</term> <listitem><para>Request immediate rotation of the journal - files.</para></listitem> + files. The <command>journalctl --rotate</command> command uses + this signal to request journal file + rotation.</para></listitem> + </varlistentry> + + <varlistentry> + <term>SIGRTMIN+1</term> + + <listitem><para>Request that all unwritten log data is written + to disk. The <command>journalctl --sync</command> command uses + this signal to trigger journal synchronization, and then waits + for the operation to complete.</para></listitem> </varlistentry> </variablelist> </refsect1> @@ -203,7 +216,7 @@ <listitem><para>Configure <command>systemd-journald</command> - behaviour. See + behavior. See <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. </para></listitem> </varlistentry> @@ -227,7 +240,20 @@ <filename>/var/log/journal</filename> is not available, or when <option>Storage=volatile</option> is set in the <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - configuration file. </para></listitem> + configuration file.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/dev/kmsg</filename></term> + <term><filename>/dev/log</filename></term> + <term><filename>/run/systemd/journal/dev-log</filename></term> + <term><filename>/run/systemd/journal/socket</filename></term> + <term><filename>/run/systemd/journal/stdout</filename></term> + + <listitem><para>Sockets and other paths that + <command>systemd-journald</command> will listen on that are + visible in the file system. In addition to these, journald can + listen for audit events using netlink.</para></listitem> </varlistentry> </variablelist> </refsect1> @@ -243,7 +269,7 @@ <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>, - <command>pydoc systemd.journal</command>. + <command>pydoc systemd.journal</command> </para> </refsect1> diff --git a/man/systemd-logind.service.xml b/man/systemd-logind.service.xml index 5733e42cd1..f0bdb1c756 100644 --- a/man/systemd-logind.service.xml +++ b/man/systemd-logind.service.xml @@ -84,7 +84,7 @@ management</para></listitem> </itemizedlist> - <para>User sessions are registered in logind via the + <para>User sessions are registered with logind via the <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry> PAM module.</para> diff --git a/man/systemd-machine-id-commit.service.xml b/man/systemd-machine-id-commit.service.xml index 7c8fc0874e..39da1922cc 100644 --- a/man/systemd-machine-id-commit.service.xml +++ b/man/systemd-machine-id-commit.service.xml @@ -42,55 +42,50 @@ <refnamediv> <refname>systemd-machine-id-commit.service</refname> - <refpurpose>Commit transient machine-id to disk</refpurpose> + <refpurpose>Commit a transient machine ID to disk</refpurpose> </refnamediv> <refsynopsisdiv> <para><filename>systemd-machine-id-commit.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-machine-id-commit</filename></para> </refsynopsisdiv> <refsect1> <title>Description</title> - <para><filename>systemd-machine-id-commit.service</filename> is a - service responsible for committing any transient - <filename>/etc/machine-id</filename> file to a writable file + <para><filename>systemd-machine-id-commit.service</filename> is an + early boot service responsible for committing transient + <filename>/etc/machine-id</filename> files to a writable disk file system. See <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more information about this file.</para> - - <para>This service is started shortly after - <filename>local-fs.target</filename> if - <filename>/etc/machine-id</filename> is an independent mount point - (probably a tmpfs one) and /etc is writable. - <command>systemd-machine-id-commit</command> will then write - current machine ID to disk and unmount the transient + for more information about machine IDs.</para> + + <para>This service is started after + <filename>local-fs.target</filename> in case + <filename>/etc/machine-id</filename> is a mount point of its own + (usually from a memory file system such as + <literal>tmpfs</literal>) and /etc is writable. The service will + invoke <command>systemd-machine-id-setup --commit</command>, which + writes the current transient machine ID to disk and unmount the <filename>/etc/machine-id</filename> file in a race-free manner to - ensure that file is always valid for other processes.</para> - - <para>Note that the traditional way to initialize the machine ID - in <filename>/etc/machine-id</filename> is to use - <command>systemd-machine-id-setup</command> by system installer - tools. You can also use - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - to initialize the machine ID on mounted (but not booted) system - images. The main use case for that service is - <filename>/etc/machine-id</filename> being an empty file at boot - and initrd chaining to systemd giving it a read only file system - that will be turned read-write later during the boot - process.</para> - - <para>There is no consequence if that service fails other than a - newer machine-id will be generated during next system boot. - </para> + ensure that file is always valid and accessible for other + processes. See + <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for details.</para> + + <para>The main use case of this service are systems where + <filename>/etc/machine-id</filename> is read-only and initially + not initialized. In this case, the system manager will generate a + transient machine ID file on a memory file system, and mount it + over <filename>/etc/machine-id</filename>, during the early boot + phase. This service is then invoked in a later boot phase, as soon + as <filename>/etc</filename> has been remounted writable and the + ID may thus be committed to disk to make it permanent.</para> </refsect1> <refsect1> <title>See Also</title> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-machine-id-commit</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> diff --git a/man/systemd-machine-id-commit.xml b/man/systemd-machine-id-commit.xml deleted file mode 100644 index cfb1722063..0000000000 --- a/man/systemd-machine-id-commit.xml +++ /dev/null @@ -1,123 +0,0 @@ -<?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"> - -<!-- - This file is part of systemd. - - Copyright 2014 Didier Roche - - systemd is free software; you can redistribute it and/or modify it - under the terms of the GNU Lesser General Public License as published by - the Free Software Foundation; either version 2.1 of the License, or - (at your option) any later version. - - systemd is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public License - along with systemd; If not, see <http://www.gnu.org/licenses/>. ---> - -<refentry id="systemd-machine-id-commit" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-machine-id-commit</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Didier</firstname> - <surname>Roche</surname> - <email>didrocks@ubuntu.com</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-machine-id-commit</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-machine-id-commit</refname> - <refpurpose>Commit transient machine ID to /etc/machine-id</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-machine-id-commit</command> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-machine-id-commit</command> may be used to - write on disk any transient machine ID mounted as a temporary file - system in <filename>/etc/machine-id</filename> at boot time. See - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more information about this file.</para> - - <para>This tool will execute no operation if - <filename>/etc/machine-id</filename> doesn't contain any valid - machine ID, isn't mounted as an independent temporary file system, - of <filename>/etc</filename> is read-only. If those conditions are - met, it will then write current machine ID to disk and unmount the - transient <filename>/etc/machine-id</filename> file in a race-free - manner to ensure that this file is always valid for other - processes.</para> - - <para>Note that the traditional way to initialize the machine ID - in <filename>/etc/machine-id</filename> is to use - <command>systemd-machine-id-setup</command> by system installer - tools. You can also use - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - to initialize the machine ID on mounted (but not booted) system - images.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--root=<replaceable>root</replaceable></option></term> - <listitem><para>Takes a directory path - as an argument. All paths will be - prefixed with the given alternate - <replaceable>root</replaceable> path, - including config search paths. - </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>systemd-machine-id-commit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-machine-id-setup.xml b/man/systemd-machine-id-setup.xml index 182717f524..749987a937 100644 --- a/man/systemd-machine-id-setup.xml +++ b/man/systemd-machine-id-setup.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -35,6 +35,12 @@ <surname>Poettering</surname> <email>lennart@poettering.net</email> </author> + <author> + <contrib>Developer</contrib> + <firstname>Didier</firstname> + <surname>Roche</surname> + <email>didrocks@ubuntu.com</email> + </author> </authorgroup> </refentryinfo> @@ -59,30 +65,43 @@ <para><command>systemd-machine-id-setup</command> may be used by system installer tools to initialize the machine ID stored in - <filename>/etc/machine-id</filename> at install time with a - randomly generated ID. See + <filename>/etc/machine-id</filename> at install time, with a + provisioned or randomly generated ID. See <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information about this file.</para> - <para>This tool will execute no operation if - <filename>/etc/machine-id</filename> is already - initialized.</para> - - <para>If a valid D-Bus machine ID is already configured for the - system, the D-Bus machine ID is copied and used to initialize the - machine ID in <filename>/etc/machine-id</filename>.</para> - - <para>If run inside a KVM virtual machine and a UUID is passed via - the <option>-uuid</option> option, this UUID is used to initialize - the machine ID instead of a randomly generated one. The caller - must ensure that the UUID passed is sufficiently unique and is - different for every booted instanced of the VM.</para> - - <para>Similar, if run inside a Linux container environment and a - UUID is set for the container this is used to initialize the - machine ID. For details see the documentation of the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container - Interface</ulink>.</para> + <para>If the tool is invoked without the <option>--commit</option> + switch, <filename>/etc/machine-id</filename> is initialized with a + valid, new machined ID if it is missing or empty. The new machine + ID will be acquired in the following fashion:</para> + + <orderedlist> + <listitem><para>If a valid D-Bus machine ID is already + configured for the system, the D-Bus machine ID is copied and + used to initialize the machine ID in + <filename>/etc/machine-id</filename>.</para></listitem> + + <listitem><para>If run inside a KVM virtual machine and a UUID + is was configured (via the <option>-uuid</option> + option), this UUID is used to initialize the machine ID. The + caller must ensure that the UUID passed is sufficiently unique + and is different for every booted instance of the + VM.</para></listitem> + + <listitem><para>Similarly, if run inside a Linux container + environment and a UUID is configured for the container, this is + used to initialize the machine ID. For details, see the + documentation of the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container + Interface</ulink>.</para></listitem> + + <listitem><para>Otherwise, a new ID is randomly + generated.</para></listitem> + </orderedlist> + + <para>The <option>--commit</option> switch may be used to commit a + transient machined ID to disk, making it persistent. For details, + see below.</para> <para>Use <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> @@ -97,13 +116,47 @@ <para>The following options are understood:</para> <variablelist> + <varlistentry> <term><option>--root=<replaceable>root</replaceable></option></term> - <listitem><para>Takes a directory path as an argument. All - paths will be prefixed with the given alternate - <replaceable>root</replaceable> path, including config search - paths. </para></listitem> + <listitem><para>Takes a directory path as argument. All paths + operated will be prefixed with the given alternate + <replaceable>root</replaceable> path, including the path for + <filename>/etc/machine-id</filename> itself.</para></listitem> </varlistentry> + + <varlistentry> + <term><option>--commit</option></term> + <listitem><para>Commit a transient machine ID to disk. This + command may be used to convert a transient machine ID into a + persistent one. A transient machine ID file is one that was + bind mounted from a memory file system (usually + <literal>tmpfs</literal>) to + <filename>/etc/machine-id</filename> during the early phase of + the boot process. This may happen because + <filename>/etc</filename> is initially read-only and was + missing a valid machine ID file at that point.</para> + + <para>This command will execute no operation if + <filename>/etc/machine-id</filename> is not mounted from a + memory file system, or if <filename>/etc</filename> is + read-only. The command will write the current transient + machine ID to disk and unmount the + <filename>/etc/machine-id</filename> mount point in a + race-free manner to ensure that this file is always valid and + accessible for other processes.</para> + + <para>This command is primarily used by the + <citerefentry><refentrytitle>systemd-machine-id-commit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + early boot service.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--print</option></term> + + <listitem><para>Print the machine ID generated or commited after the operation is complete.</para></listitem> + </varlistentry> + <xi:include href="standard-options.xml" xpointer="help" /> <xi:include href="standard-options.xml" xpointer="version" /> </variablelist> @@ -122,6 +175,7 @@ <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-machine-id-commit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry project='dbus'><refentrytitle>dbus-uuidgen</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> </para> diff --git a/man/systemd-modules-load.service.xml b/man/systemd-modules-load.service.xml index dacd083bad..b25929b2e4 100644 --- a/man/systemd-modules-load.service.xml +++ b/man/systemd-modules-load.service.xml @@ -55,7 +55,7 @@ <title>Description</title> <para><filename>systemd-modules-load.service</filename> is an - early-boot service that loads kernel modules based on static + early boot service that loads kernel modules based on static configuration.</para> <para>See diff --git a/man/systemd-mount.xml b/man/systemd-mount.xml new file mode 100644 index 0000000000..06b7c85bd8 --- /dev/null +++ b/man/systemd-mount.xml @@ -0,0 +1,295 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2016 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-mount" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-mount</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-mount</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-mount</refname> + <refpurpose>Establish a mount or auto-mount point transiently</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-mount</command> + <arg choice="opt" rep="repeat"><replaceable>OPTIONS</replaceable></arg> + <arg choice="plain"><replaceable>WHAT</replaceable></arg> + <arg choice="opt"><replaceable>WHERE</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis> + <command>systemd-mount</command> + <arg choice="opt" rep="repeat"><replaceable>OPTIONS</replaceable></arg> + <arg choice="plain"><option>--list</option></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-mount</command> may be used to create and start a transient <filename>.mount</filename> or + <filename>.automount</filename> unit of the file system <replaceable>WHAT</replaceable> on the mount point + <replaceable>WHERE</replaceable>.</para> + + <para>In many ways, <command>systemd-mount</command> is similar to the lower-level + <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> command, however instead + of executing the mount operation directly and immediately, <command>systemd-mount</command> schedules it through + the service manager job queue, so that it may pull in further dependencies (such as parent mounts, or a file system + checker to execute a priori), and may make use of the auto-mounting logic.</para> + + <para>The command takes either one or two arguments. If only one argument is specified it should refer to a block + device containing a file system (e.g. <literal>/dev/sdb1</literal>), which is then probed for a label and other + metadata, and is mounted to a directory whose name is generated from the label. In this mode the block device must + exist at the time of invocation of the command, so that it may be probed. If the device is found to be a removable + block device (e.g. a USB stick) an automount point instead of a regular mount point is created (i.e. the + <option>--automount=</option> option is implied, see below).</para> + + <para>If two arguments are specified the first indicates the mount source (the <replaceable>WHAT</replaceable>) and + the second indicates the path to mount it on (the <replaceable>WHERE</replaceable>). In this mode no probing of the + source is attempted, and a backing device node doesn't have to exist yet. However, if this mode is combined with + <option>--discover</option>, device node probing for additional metadata is enabled, and – much like in the + single-argument case discussed above – the specified device has to exist at the time of invocation of the + command.</para> + + <para>Use the <option>--list</option> command to show a terse table of all local, known block devices with file + systems that may be mounted with this command.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + + <varlistentry> + <term><option>--no-block</option></term> + + <listitem> + <para>Do not synchronously wait for the requested operation to finish. If this is not specified, the job will + be verified, enqueued and <command>systemd-mount</command> will wait until the mount or automount unit's + start-up is completed. By passing this argument, it is only verified and enqueued.</para> + </listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="no-pager"/> + <xi:include href="standard-options.xml" xpointer="no-ask-password"/> + + <varlistentry> + <term><option>--quiet</option></term> + <term><option>-q</option></term> + + <listitem><para>Suppresses additional informational output while running.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--discover</option></term> + + <listitem><para>Enable probing of the mount source. This switch is implied if a single argument is specified on + 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 + state quickly after each access.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--type=</option></term> + <term><option>-t</option></term> + + <listitem><para>Specifies the file system type to mount (e.g. <literal>vfat</literal>, <literal>ext4</literal>, + …). If omitted (or set to <literal>auto</literal>) the file system is determined automatically.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--options=</option></term> + <term><option>-o</option></term> + + <listitem><para>Additional mount options for the mount point.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--fsck=</option></term> + + <listitem><para>Takes a boolean argument, defaults to on. Controls whether to run a file system check + immediately before the mount operation. In the automount case (see <option>--automount=</option> below) the + check will be run the moment the first access to the device is made, which might slightly delay the + access.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--description=</option></term> + + <listitem><para>Provide a description for the mount or automount unit. See <varname>Description=</varname> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--property=</option></term> + <term><option>-p</option></term> + + <listitem><para>Sets a unit property for the mount unit that is created. This takes an assignment in the same + format as <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s + <command>set-property</command> command.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--automount=</option></term> + + <listitem><para>Takes a boolean argument. Controls whether to create an automount point or a regular mount + point. If true an automount point is created that is backed by the actual file system at the time of first + access. If false a plain mount point is created that is backed by the actual file system immediately. Automount + points have the benefit that the file system stays unmounted and hence in clean state until it is first + accessed. In automount mode the <option>--timeout-idle-sec=</option> switch (see below) may be used to ensure + the mount point is unmounted automatically after the last access and an idle period passed.</para> + + <para>If this switch is not specified it defaults to false. If not specified and <option>--discover</option> is + used (or only a single argument passed, which implies <option>--discover</option>, see above), and the file + system block device is detected to be removable, it is set to true, in order to increase the chance that the + file system is in a fully clean state if the device is unplugged abruptly.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-A</option></term> + + <listitem><para>Equivalent to <option>--automount=yes</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--timeout-idle-sec=</option></term> + + <listitem><para>Takes a time value that controls the idle timeout in automount mode. If set to + <literal>infinity</literal> (the default) no automatic unmounts are done. Otherwise the file system backing the + automount point is detached after the last access and the idle timeout passed. See + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details on + the time syntax supported. This option has no effect if only a regular mount is established, and automounting + is not used.</para> + + <para>Note that if <option>--discover</option> is used (or only a single argument passed, which implies + <option>--discover</option>, see above), and the file system block device is detected to be removable, + <option>--timeout-idle-sec=1s</option> is implied.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--automount-property=</option></term> + + <listitem><para>Similar to <option>--property=</option>, but applies additional properties to the automount + unit created, instead of the mount unit.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--bind-device=</option></term> + + <listitem><para>Takes a boolean argument, defaults to off. This option only has an effect in automount mode, + and controls whether the automount unit shall be bound to the backing device's lifetime. If enabled, the + automount point will be removed automatically when the backing device vanishes. If disabled the automount point + stays around, and subsequent accesses will block until backing device is replugged. This option has no effect + in case of non-device mounts, such as network or virtual file system mounts.</para> + + <para>Note that if <option>--discover</option> is used (or only a single argument passed, which implies + <option>--discover</option>, see above), and the file system block device is detected to be removable, this + option is implied.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--list</option></term> + + <listitem><para>Instead of establishing a mount or automount point, print a terse list of block devices + containing file systems that may be mounted with <literal>systemd-mount</literal>, along with useful metadata + such as labels, etc.</para></listitem> + </varlistentry> + + <xi:include href="user-system-options.xml" xpointer="user" /> + <xi:include href="user-system-options.xml" xpointer="system" /> + <xi:include href="user-system-options.xml" xpointer="host" /> + <xi:include href="user-system-options.xml" xpointer="machine" /> + + <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>The udev Database</title> + + <para>If <option>--discover</option> is used, <command>systemd-mount</command> honors a couple of additional udev + properties of block devices:</para> + + <variablelist class='udev-directives'> + <varlistentry> + <term><varname>SYSTEMD_MOUNT_OPTIONS=</varname></term> + + <listitem><para>The mount options to use, if <option>--options=</option> is not used.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SYSTEMD_MOUNT_WHERE=</varname></term> + + <listitem><para>The file system path to place the mount point at, instead of the automatically generated + one.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-networkd-wait-online.service.xml b/man/systemd-networkd-wait-online.service.xml index f53b337daa..e21c805342 100644 --- a/man/systemd-networkd-wait-online.service.xml +++ b/man/systemd-networkd-wait-online.service.xml @@ -80,12 +80,13 @@ several interfaces which will be configured, but a particular one is necessary to access some network resources. This option may be used more than once to wait for multiple network - interfaces.</para></listitem> + interfaces. When used, all other interfaces are ignored. + </para></listitem> </varlistentry> <varlistentry> <term><option>--ignore=</option></term> <listitem><para>Network interfaces to be ignored when deciding - if the system is online. By default only the loopback + if the system is online. By default, only the loopback interface is ignored. This option may be used more than once to ignore multiple network interfaces. </para></listitem> </varlistentry> diff --git a/man/systemd-notify.xml b/man/systemd-notify.xml index 06d5ae5319..a5f4077166 100644 --- a/man/systemd-notify.xml +++ b/man/systemd-notify.xml @@ -60,7 +60,7 @@ <para><command>systemd-notify</command> may be called by daemon scripts to notify the init system about status changes. It can be used to send arbitrary information, encoded in an - environment-block-like list of strings. Most importantly it can be + environment-block-like list of strings. Most importantly, it can be used for start-up completion notification.</para> <para>This is mostly just a wrapper around @@ -124,7 +124,12 @@ systemd, non-zero otherwise. If this option is passed, no message is sent. This option is hence unrelated to the other options. For details about the semantics of this option, see - <citerefentry><refentrytitle>sd_booted</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> + <citerefentry><refentrytitle>sd_booted</refentrytitle><manvolnum>3</manvolnum></citerefentry>. An + alternate way to check for this state is to call + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + with the <command>is-system-running</command> command. It will + return <literal>offline</literal> if the system was not booted + with systemd. </para></listitem> </varlistentry> <xi:include href="standard-options.xml" xpointer="help" /> @@ -156,12 +161,12 @@ mkfifo /tmp/waldo systemd-notify --ready --status="Waiting for data..." while : ; do - read a < /tmp/waldo - systemd-notify --status="Processing $a" + read a < /tmp/waldo + systemd-notify --status="Processing $a" - # Do something with $a ... + # Do something with $a ... - systemd-notify --status="Waiting for data..." + systemd-notify --status="Waiting for data..." done</programlisting> </example> </refsect1> diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml index 06285edc0b..f153034296 100644 --- a/man/systemd-nspawn.xml +++ b/man/systemd-nspawn.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -58,7 +58,7 @@ </cmdsynopsis> <cmdsynopsis> <command>systemd-nspawn</command> - <arg choice="plain">-b</arg> + <arg choice="plain">--boot</arg> <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt" rep="repeat">ARGS</arg> </cmdsynopsis> @@ -67,70 +67,80 @@ <refsect1> <title>Description</title> - <para><command>systemd-nspawn</command> may be used to run a - command or OS in a light-weight namespace container. In many ways - it is similar to - <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - but more powerful since it fully virtualizes the file system - hierarchy, as well as the process tree, the various IPC subsystems - and the host and domain name.</para> - - <para><command>systemd-nspawn</command> limits access to various - kernel interfaces in the container to read-only, such as - <filename>/sys</filename>, <filename>/proc/sys</filename> or - <filename>/sys/fs/selinux</filename>. Network interfaces and the - system clock may not be changed from within the container. Device - nodes may not be created. The host system cannot be rebooted and - kernel modules may not be loaded from within the container.</para> - - <para>Note that even though these security precautions are taken - <command>systemd-nspawn</command> is not suitable for fully secure - container setups. Many of the security features may be - circumvented and are hence primarily useful to avoid accidental - changes to the host system from the container.</para> - - <para>In contrast to - <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry> <command>systemd-nspawn</command> - may be used to boot full Linux-based operating systems in a + <para><command>systemd-nspawn</command> may be used to run a command or OS in a light-weight namespace + container. In many ways it is similar to <citerefentry + project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>, but more powerful + since it fully virtualizes the file system hierarchy, as well as the process tree, the various IPC subsystems and + the host and domain name.</para> + + <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 + system.</para> + + <para>In contrast to <citerefentry + project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry> <command>systemd-nspawn</command> + may be used to boot full Linux-based operating systems in a container.</para> + + <para><command>systemd-nspawn</command> limits access to various kernel interfaces in the container to read-only, + such as <filename>/sys</filename>, <filename>/proc/sys</filename> or <filename>/sys/fs/selinux</filename>. The + host's network interfaces and the system clock may not be changed from within the container. Device nodes may not + be created. The host system cannot be rebooted and kernel modules may not be loaded from within the container.</para> - <para>Use a tool like - <citerefentry project='mankier'><refentrytitle>dnf</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - or - <citerefentry project='archlinux'><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry> - to set up an OS directory tree suitable as file system hierarchy - for <command>systemd-nspawn</command> containers.</para> - - <para>Note that <command>systemd-nspawn</command> will mount file - systems private to the container to <filename>/dev</filename>, - <filename>/run</filename> and similar. These will not be visible - outside of the container, and their contents will be lost when the - container exits.</para> - - <para>Note that running two <command>systemd-nspawn</command> - containers from the same directory tree will not make processes in - them see each other. The PID namespace separation of the two - containers is complete and the containers will share very few - runtime objects except for the underlying file system. Use - <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s - <command>login</command> command to request an additional login - prompt in a running container.</para> - - <para><command>systemd-nspawn</command> implements the - <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container - Interface</ulink> specification.</para> - - <para>As a safety check <command>systemd-nspawn</command> will - verify the existence of <filename>/usr/lib/os-release</filename> - or <filename>/etc/os-release</filename> in the container tree - before starting the container (see - <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>). - It might be necessary to add this file to the container tree - manually if the OS of the container is too old to contain this + <para>Use a tool like <citerefentry + project='mankier'><refentrytitle>dnf</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry + project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>, or + <citerefentry project='archlinux'><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry> to + set up an OS directory tree suitable as file system hierarchy for <command>systemd-nspawn</command> containers. See + the Examples section below for details on suitable invocation of these commands.</para> + + <para>As a safety check <command>systemd-nspawn</command> will verify the existence of + <filename>/usr/lib/os-release</filename> or <filename>/etc/os-release</filename> in the container tree before + starting the container (see + <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>). It might be + necessary to add this file to the container tree manually if the OS of the container is too old to contain this file out-of-the-box.</para> + + <para><command>systemd-nspawn</command> may be invoked directly from the interactive command line or run as system + service in the background. In this mode each container instance runs as its own service instance; a default + template unit file <filename>systemd-nspawn@.service</filename> is provided to make this easy, taking the container + name as instance identifier. Note that different default options apply when <command>systemd-nspawn</command> is + invoked by the template unit file than interactively on the command line. Most importantly the template unit file + makes use of the <option>--boot</option> which is not the default in case <command>systemd-nspawn</command> is + invoked from the interactive command line. Further differences with the defaults are documented along with the + various supported options below.</para> + + <para>The <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> tool may + be used to execute a number of operations on containers. In particular it provides easy-to-use commands to run + containers as system services using the <filename>systemd-nspawn@.service</filename> template unit + file.</para> + + <para>Along with each container a settings file with the <filename>.nspawn</filename> suffix may exist, containing + additional settings to apply when running the container. See + <citerefentry><refentrytitle>systemd.nspawn</refentrytitle><manvolnum>5</manvolnum></citerefentry> for + details. Settings files override the default options used by the <filename>systemd-nspawn@.service</filename> + template unit file, making it usually unnecessary to alter this template file directly.</para> + + <para>Note that <command>systemd-nspawn</command> will mount file systems private to the container to + <filename>/dev</filename>, <filename>/run</filename> and similar. These will not be visible outside of the + container, and their contents will be lost when the container exits.</para> + + <para>Note that running two <command>systemd-nspawn</command> containers from the same directory tree will not make + processes in them see each other. The PID namespace separation of the two containers is complete and the containers + will share very few runtime objects except for the underlying file system. Use + <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s + <command>login</command> or <command>shell</command> commands to request an additional login session in a running + container.</para> + + <para><command>systemd-nspawn</command> implements the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container Interface</ulink> + specification.</para> + + <para>While running, containers invoked with <command>systemd-nspawn</command> are registered with the + <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry> service that + keeps track of running containers, and provides programming interfaces to interact with them.</para> </refsect1> <refsect1> @@ -140,7 +150,7 @@ are used as arguments for the init binary. Otherwise, <replaceable>COMMAND</replaceable> specifies the program to launch in the container, and the remaining arguments are used as - arguments for this program. If <option>-b</option> is not used and + arguments for this program. If <option>--boot</option> is not used and no arguments are specified, a shell is launched in the container.</para> @@ -156,12 +166,15 @@ <para>If neither <option>--directory=</option>, nor <option>--image=</option> is specified the directory is - determined as <filename>/var/lib/machines/</filename> suffixed - by the machine name as specified with - <option>--machine=</option>. If neither - <option>--directory=</option>, <option>--image=</option>, nor - <option>--machine=</option> are specified, the current - directory will be used. May not be specified together with + determined by searching for a directory named the same as the + machine name specified with <option>--machine=</option>. See + <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + section "Files and Directories" for the precise search path.</para> + + <para>If neither <option>--directory=</option>, + <option>--image=</option>, nor <option>--machine=</option> + are specified, the current directory will + be used. May not be specified together with <option>--image=</option>.</para></listitem> </varlistentry> @@ -247,15 +260,76 @@ </varlistentry> <varlistentry> + <term><option>-a</option></term> + <term><option>--as-pid2</option></term> + + <listitem><para>Invoke the shell or specified program as process ID (PID) 2 instead of PID 1 (init). By + default, if neither this option nor <option>--boot</option> is used, the selected binary is run as process with + PID 1, a mode only suitable for programs that are aware of the special semantics that the process with PID 1 + has on UNIX. For example, it needs to reap all processes reparented to it, and should implement + <command>sysvinit</command> compatible signal handling (specifically: it needs to reboot on SIGINT, reexecute + on SIGTERM, reload configuration on SIGHUP, and so on). With <option>--as-pid2</option> a minimal stub init + process is run as PID 1 and the selected binary is executed as PID 2 (and hence does not need to implement any + special semantics). The stub init process will reap processes as necessary and react appropriately to + signals. It is recommended to use this mode to invoke arbitrary commands in containers, unless they have been + modified to run correctly as PID 1. Or in other words: this switch should be used for pretty much all commands, + except when the command refers to an init or shell implementation, as these are generally capable of running + correctly as PID 1. This option may not be combined with <option>--boot</option>.</para> + </listitem> + </varlistentry> + + <varlistentry> <term><option>-b</option></term> <term><option>--boot</option></term> - <listitem><para>Automatically search for an init binary and - invoke it instead of a shell or a user supplied program. If - this option is used, arguments specified on the command line - are used as arguments for the init binary. This option may not - be combined with <option>--share-system</option>. - </para></listitem> + <listitem><para>Automatically search for an init binary and invoke it as PID 1, instead of a shell or a user + supplied program. If this option is used, arguments specified on the command line are used as arguments for the + init binary. This option may not be combined with <option>--as-pid2</option>.</para> + + <para>The following table explains the different modes of invocation and relationship to + <option>--as-pid2</option> (see above):</para> + + <table> + <title>Invocation Mode</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname="switch" /> + <colspec colname="explanation" /> + <thead> + <row> + <entry>Switch</entry> + <entry>Explanation</entry> + </row> + </thead> + <tbody> + <row> + <entry>Neither <option>--as-pid2</option> nor <option>--boot</option> specified</entry> + <entry>The passed parameters are interpreted as the command line, which is executed as PID 1 in the container.</entry> + </row> + + <row> + <entry><option>--as-pid2</option> specified</entry> + <entry>The passed parameters are interpreted as the command line, which is executed as PID 2 in the container. A stub init process is run as PID 1.</entry> + </row> + + <row> + <entry><option>--boot</option> specified</entry> + <entry>An init binary as automatically searched and run as PID 1 in the container. The passed parameters are used as invocation parameters for this process.</entry> + </row> + + </tbody> + </tgroup> + </table> + + <para>Note that <option>--boot</option> is the default mode of operation if the + <filename>systemd-nspawn@.service</filename> template unit file is used.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--chdir=</option></term> + + <listitem><para>Change to the specified working directory before invoking the process in the container. Expects + an absolute path in the container's file system namespace.</para></listitem> </varlistentry> <varlistentry> @@ -293,7 +367,9 @@ <listitem><para>Set the specified UUID for the container. The init system will initialize <filename>/etc/machine-id</filename> from this if this file is - not set yet. </para></listitem> + not set yet. Note that this option takes effect only if + <filename>/etc/machine-id</filename> in the container is + unpopulated.</para></listitem> </varlistentry> <varlistentry> @@ -323,38 +399,89 @@ <varlistentry> <term><option>--private-users=</option></term> - <listitem><para>Enables user namespacing. If enabled the - container will run with its own private set of Unix user and - group ids (UIDs and GIDs). Takes none, one or two - colon-separated parameters: the first parameter specifies the - first host UID to assign to the container, the second - parameter specifies the number of host UIDs to assign to the - container. If the second parameter is omitted, 65536 UIDs are - assigned. If the first parameter is also omitted (and hence - no parameter passed at all), the first UID assigned to the - container is read from the owner of the root directory of the - container's directory tree. By default no user namespacing is - applied.</para> + <listitem><para>Controls user namespacing. If enabled, the container will run with its own private set of UNIX + user and group ids (UIDs and GIDs). This involves mapping the private UIDs/GIDs used in the container (starting + with the container's root user 0 and up) to a range of UIDs/GIDs on the host that are not used for other + purposes (usually in the range beyond the host's UID/GID 65536). The parameter may be specified as follows:</para> + + <orderedlist> + <listitem><para>If one or two colon-separated numbers are specified, user namespacing is turned on. The first + parameter specifies the first host UID/GID to assign to the container, the second parameter specifies the + number of host UIDs/GIDs to assign to the container. If the second parameter is omitted, 65536 UIDs/GIDs are + assigned.</para></listitem> + + <listitem><para>If the parameter is omitted, or true, user namespacing is turned on. The UID/GID range to + use is determined automatically from the file ownership of the root directory of the container's directory + tree. To use this option, make sure to prepare the directory tree in advance, and ensure that all files and + directories in it are owned by UIDs/GIDs in the range you'd like to use. Also, make sure that used file ACLs + exclusively reference UIDs/GIDs in the appropriate range. If this mode is used the number of UIDs/GIDs + assigned to the container for use is 65536, and the UID/GID of the root directory must be a multiple of + 65536.</para></listitem> + + <listitem><para>If the parameter is false, user namespacing is turned off. This is the default.</para> + </listitem> + + <listitem><para>The special value <literal>pick</literal> turns on user namespacing. In this case the UID/GID + range is automatically chosen. As first step, the file owner of the root directory of the container's + directory tree is read, and it is checked that it is currently not used by the system otherwise (in + particular, that no other container is using it). If this check is successful, the UID/GID range determined + this way is used, similar to the behavior if "yes" is specified. If the check is not successful (and thus + the UID/GID range indicated in the root directory's file owner is already used elsewhere) a new – currently + unused – UID/GID range of 65536 UIDs/GIDs is randomly chosen between the host UID/GIDs of 524288 and + 1878982656, always starting at a multiple of 65536. This setting implies + <option>--private-users-chown</option> (see below), which has the effect that the files and directories in + the container's directory tree will be owned by the appropriate users of the range picked. Using this option + makes user namespace behavior fully automatic. Note that the first invocation of a previously unused + container image might result in picking a new UID/GID range for it, and thus in the (possibly expensive) file + ownership adjustment operation. However, subsequent invocations of the container will be cheap (unless of + course the picked UID/GID range is assigned to a different use by then).</para></listitem> + </orderedlist> + + <para>It is recommended to assign at least 65536 UIDs/GIDs to each container, so that the usable UID/GID range in the + container covers 16 bit. For best security, do not assign overlapping UID/GID ranges to multiple containers. It is + hence a good idea to use the upper 16 bit of the host 32-bit UIDs/GIDs as container identifier, while the lower 16 + bit encode the container UID/GID used. This is in fact the behavior enforced by the + <option>--private-users=pick</option> option.</para> + + <para>When user namespaces are used, the GID range assigned to each container is always chosen identical to the + UID range.</para> + + <para>In most cases, using <option>--private-users=pick</option> is the recommended option as it enhances + container security massively and operates fully automatically in most cases.</para> + + <para>Note that the picked UID/GID range is not written to <filename>/etc/passwd</filename> or + <filename>/etc/group</filename>. In fact, the allocation of the range is not stored persistently anywhere, + except in the file ownership of the files and directories of the container.</para></listitem> + </varlistentry> - <para>Note that user namespacing currently requires OS trees - that are prepared for the UID shift that is being applied: - UIDs and GIDs used for file ownership or in file ACL entries - must be shifted to the container UID base that is - used during container runtime.</para> + <varlistentry> + <term><option>--private-users-chown</option></term> - <para>It is recommended to assign as least 65536 UIDs to each - container, so that the usable UID range in the container - covers 16bit. For best security do not assign overlapping UID - ranges to multiple containers. It is hence a good idea to use - the upper 16bit of the host 32bit UIDs as container - identifier, while the lower 16bit encode the container UID - used.</para> + <listitem><para>If specified, all files and directories in the container's directory tree will adjusted so that + they are owned to the appropriate UIDs/GIDs selected for the container (see above). This operation is + potentially expensive, as it involves descending and iterating through the full directory tree of the + container. Besides actual file ownership, file ACLs are adjusted as well.</para> - <para>When user namespaces are used the GID range assigned to - each container is always chosen identical to the UID - range.</para></listitem> + <para>This option is implied if <option>--private-users=pick</option> is used. This option has no effect if + user namespacing is not used.</para></listitem> </varlistentry> + <varlistentry> + <term><option>-U</option></term> + + <listitem><para>If the kernel supports the user namespaces feature, equivalent to + <option>--private-users=pick --private-users-chown</option>, otherwise equivalent to + <option>--private-users=no</option>.</para> + + <para>Note that <option>-U</option> is the default if the + <filename>systemd-nspawn@.service</filename> template unit file is used.</para> + + <para>Note: it is possible to undo the effect of <option>--private-users-chown</option> (or + <option>-U</option>) on the file system by redoing the operation with the first UID of 0:</para> + + <programlisting>systemd-nspawn … --private-users=0 --private-users-chown</programlisting> + </listitem> + </varlistentry> <varlistentry> <term><option>--private-network</option></term> @@ -419,30 +546,83 @@ <term><option>-n</option></term> <term><option>--network-veth</option></term> - <listitem><para>Create a virtual Ethernet link - (<literal>veth</literal>) between host and container. The host - side of the Ethernet link will be available as a network - interface named after the container's name (as specified with - <option>--machine=</option>), prefixed with - <literal>ve-</literal>. The container side of the Ethernet - link will be named <literal>host0</literal>. Note that - <option>--network-veth</option> implies - <option>--private-network</option>.</para></listitem> + <listitem><para>Create a virtual Ethernet link (<literal>veth</literal>) between host and container. The host + side of the Ethernet link will be available as a network interface named after the container's name (as + specified with <option>--machine=</option>), prefixed with <literal>ve-</literal>. The container side of the + Ethernet link will be named <literal>host0</literal>. The <option>--network-veth</option> option implies + <option>--private-network</option>.</para> + + <para>Note that + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + includes by default a network file <filename>/usr/lib/systemd/network/80-container-ve.network</filename> + matching the host-side interfaces created this way, which contains settings to enable automatic address + provisioning on the created virtual link via DHCP, as well as automatic IP routing onto the host's external + network interfaces. It also contains <filename>/usr/lib/systemd/network/80-container-host0.network</filename> + matching the container-side interface created this way, containing settings to enable client side address + assignment via DHCP. In case <filename>systemd-networkd</filename> is running on both the host and inside the + container, automatic IP communication from the container to the host is thus available, with further + connectivity to the external network.</para> + + <para>Note that <option>--network-veth</option> is the default if the + <filename>systemd-nspawn@.service</filename> template unit file is used.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--network-veth-extra=</option></term> + + <listitem><para>Adds an additional virtual Ethernet link + between host and container. Takes a colon-separated pair of + host interface name and container interface name. The latter + may be omitted in which case the container and host sides will + be assigned the same name. This switch is independent of + <option>--network-veth</option>, and — in contrast — may be + used multiple times, and allows configuration of the network + interface names. Note that <option>--network-bridge=</option> + has no effect on interfaces created with + <option>--network-veth-extra=</option>.</para></listitem> </varlistentry> <varlistentry> <term><option>--network-bridge=</option></term> - <listitem><para>Adds the host side of the Ethernet link - created with <option>--network-veth</option> to the specified - bridge. Note that <option>--network-bridge=</option> implies - <option>--network-veth</option>. If this option is used, the - host side of the Ethernet link will use the - <literal>vb-</literal> prefix instead of + <listitem><para>Adds the host side of the Ethernet link created with <option>--network-veth</option> to the + specified Ethernet bridge interface. Expects a valid network interface name of a bridge device as + argument. Note that <option>--network-bridge=</option> implies <option>--network-veth</option>. If this option + is used, the host side of the Ethernet link will use the <literal>vb-</literal> prefix instead of <literal>ve-</literal>.</para></listitem> </varlistentry> <varlistentry> + <term><option>--network-zone=</option></term> + + <listitem><para>Creates a virtual Ethernet link (<literal>veth</literal>) to the container and adds it to an + automatically managed Ethernet bridge interface. The bridge interface is named after the passed argument, + prefixed with <literal>vz-</literal>. The bridge interface is automatically created when the first container + configured for its name is started, and is automatically removed when the last container configured for its + name exits. Hence, each bridge interface configured this way exists only as long as there's at least one + container referencing it running. This option is very similar to <option>--network-bridge=</option>, besides + this automatic creation/removal of the bridge device.</para> + + <para>This setting makes it easy to place multiple related containers on a common, virtual Ethernet-based + broadcast domain, here called a "zone". Each container may only be part of one zone, but each zone may contain + any number of containers. Each zone is referenced by its name. Names may be chosen freely (as long as they form + valid network interface names when prefixed with <literal>vz-</literal>), and it is sufficient to pass the same + name to the <option>--network-zones=</option> switch of the various concurrently running containers to join + them in one zone.</para> + + <para>Note that + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + includes by default a network file <filename>/usr/lib/systemd/network/80-container-vz.network</filename> + matching the bridge interfaces created this way, which contains settings to enable automatic address + provisioning on the created virtual network via DHCP, as well as automatic IP routing onto the host's external + network interfaces. Using <option>--network-zone=</option> is hence in most cases fully automatic and + sufficient to connect multiple local containers in a joined broadcast domain to the host, with further + connectivity to the external network.</para> + </listitem> + </varlistentry> + + <varlistentry> <term><option>-p</option></term> <term><option>--port=</option></term> @@ -456,8 +636,8 @@ which case <literal>tcp</literal> is assumed. The container port number and its colon may be omitted, in which case the same port as the host port is implied. This option is only - supported if private networking is used, such as - <option>--network-veth</option> or + supported if private networking is used, such as with + <option>--network-veth</option>, <option>--network-zone=</option> <option>--network-bridge=</option>.</para></listitem> </varlistentry> @@ -518,9 +698,8 @@ order to trigger an orderly shutdown of the container. Defaults to SIGRTMIN+3 if <option>--boot</option> is used (on systemd-compatible init systems SIGRTMIN+3 - triggers an orderly shutdown). Takes a signal name like - <literal>SIGHUP</literal>, <literal>SIGTERM</literal> or - similar as argument.</para></listitem> + triggers an orderly shutdown). For a list of valid signals, see + <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para></listitem> </varlistentry> <varlistentry> @@ -543,7 +722,7 @@ and the subdirectory is symlinked into the host at the same location. <literal>try-host</literal> and <literal>try-guest</literal> do the same but do not fail if - the host does not have persistent journalling enabled. If + the host does not have persistent journaling enabled. If <literal>auto</literal> (the default), and the right subdirectory of <filename>/var/log/journal</filename> exists, it will be bind mounted into the container. If the @@ -551,7 +730,10 @@ Effectively, booting a container once with <literal>guest</literal> or <literal>host</literal> will link the journal persistently if further on the default of - <literal>auto</literal> is used.</para></listitem> + <literal>auto</literal> is used.</para> + + <para>Note that <option>--link-journal=try-guest</option> is the default if the + <filename>systemd-nspawn@.service</filename> template unit file is used.</para></listitem> </varlistentry> <varlistentry> @@ -573,12 +755,17 @@ <term><option>--bind-ro=</option></term> <listitem><para>Bind mount a file or directory from the host - into the container. Either takes a path argument -- in which + into the container. Takes one of: a path argument — in which case the specified path will be mounted from the host to the - same path in the container --, or a colon-separated pair of - paths -- in which case the first specified path is the source + same path in the container —, or a colon-separated pair of + paths — in which case the first specified path is the source in the host, and the second path is the destination in the - container. This option may be specified multiple times for + container —, or a colon-separated triple of source path, + destination path and mount options. Mount options are + comma-separated and currently, only "rbind" and "norbind" + are allowed. Defaults to "rbind". Backslash escapes are interpreted, so + <literal>\:</literal> may be used to embed colons in either path. + This option may be specified multiple times for creating multiple independent bind mount points. The <option>--bind-ro=</option> option creates read-only bind mounts.</para></listitem> @@ -592,12 +779,15 @@ mount the tmpfs instance to (in which case the directory access mode will be chosen as 0755, owned by root/root), or optionally a colon-separated pair of path and mount option - string, that is used for mounting (in which case the kernel + string that is used for mounting (in which case the kernel default for access mode and owner will be chosen, unless otherwise specified). This option is particularly useful for mounting directories such as <filename>/var</filename> as tmpfs, to allow state-less systems, in particular when - combined with <option>--read-only</option>.</para></listitem> + combined with <option>--read-only</option>. + Backslash escapes are interpreted in the path, so + <literal>\:</literal> may be used to embed colons in the path. + </para></listitem> </varlistentry> <varlistentry> @@ -609,6 +799,10 @@ list of colon-separated paths to the directory trees to combine and the destination mount point.</para> + <para>Backslash escapes are interpreted in the paths, so + <literal>\:</literal> may be used to embed colons in the paths. + </para> + <para>If three or more paths are specified, then the last specified path is the destination mount point in the container, all paths specified before refer to directory trees @@ -616,9 +810,9 @@ overlay file system. The left-most path is hence the lowest directory tree, the second-to-last path the highest directory tree in the stacking order. If <option>--overlay-ro=</option> - is used instead of <option>--overlay=</option> a read-only + is used instead of <option>--overlay=</option>, a read-only overlay file system is created. If a writable overlay file - system is created all changes made to it are written to the + system is created, all changes made to it are written to the highest directory tree in the stacking order, i.e. the second-to-last specified.</para> @@ -647,7 +841,8 @@ </varlistentry> <varlistentry> - <term><option>--setenv=</option></term> + <term><option>-E <replaceable>NAME</replaceable>=<replaceable>VALUE</replaceable></option></term> + <term><option>--setenv=<replaceable>NAME</replaceable>=<replaceable>VALUE</replaceable></option></term> <listitem><para>Specifies an environment variable assignment to pass to the init process in the container, in the format @@ -657,29 +852,12 @@ </varlistentry> <varlistentry> - <term><option>--share-system</option></term> - - <listitem><para>Allows the container to share certain system - facilities with the host. More specifically, this turns off - PID namespacing, UTS namespacing and IPC namespacing, and thus - allows the guest to see and interact more easily with - processes outside of the container. Note that using this - option makes it impossible to start up a full Operating System - in the container, as an init system cannot operate in this - mode. It is only useful to run specific programs or - applications this way, without involving an init system in the - container. This option implies <option>--register=no</option>. - This option may not be combined with - <option>--boot</option>.</para></listitem> - </varlistentry> - - <varlistentry> <term><option>--register=</option></term> <listitem><para>Controls whether the container is registered with <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - Takes a boolean argument, defaults to <literal>yes</literal>. + Takes a boolean argument, which defaults to <literal>yes</literal>. This option should be enabled when the container runs a full Operating System (more specifically: an init system), and is useful to ensure that the container is accessible via @@ -687,9 +865,7 @@ and shown by tools such as <citerefentry project='man-pages'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>. If the container does not run an init system, it is - recommended to set this option to <literal>no</literal>. Note - that <option>--share-system</option> implies - <option>--register=no</option>. </para></listitem> + recommended to set this option to <literal>no</literal>.</para></listitem> </varlistentry> <varlistentry> @@ -733,34 +909,99 @@ </varlistentry> <varlistentry> - <term><option>--volatile</option><replaceable>=MODE</replaceable></term> + <term><option>--volatile</option></term> + <term><option>--volatile=</option><replaceable>MODE</replaceable></term> <listitem><para>Boots the container in volatile mode. When no mode parameter is passed or when mode is specified as - <literal>yes</literal> full volatile mode is enabled. This - means the root directory is mounted as mostly unpopulated + <option>yes</option>, full volatile mode is enabled. This + means the root directory is mounted as a mostly unpopulated <literal>tmpfs</literal> instance, and - <filename>/usr</filename> from the OS tree is mounted into it, - read-only (the system thus starts up with read-only OS - resources, but pristine state and configuration, any changes - to the either are lost on shutdown). When the mode parameter - is specified as <literal>state</literal> the OS tree is + <filename>/usr</filename> from the OS tree is mounted into it + in read-only mode (the system thus starts up with read-only OS + image, but pristine state and configuration, any changes + are lost on shutdown). When the mode parameter + is specified as <option>state</option>, the OS tree is mounted read-only, but <filename>/var</filename> is mounted as - <literal>tmpfs</literal> instance into it (the system thus + a <literal>tmpfs</literal> instance into it (the system thus starts up with read-only OS resources and configuration, but - pristine state, any changes to the latter are lost on + pristine state, and any changes to the latter are lost on shutdown). When the mode parameter is specified as - <literal>no</literal> (the default) the whole OS tree is made + <option>no</option> (the default), the whole OS tree is made available writable.</para> - <para>Note that setting this to <literal>yes</literal> or - <literal>state</literal> will only work correctly with + <para>Note that setting this to <option>yes</option> or + <option>state</option> will only work correctly with operating systems in the container that can boot up with only <filename>/usr</filename> mounted, and are able to populate <filename>/var</filename> automatically, as needed.</para></listitem> </varlistentry> + <varlistentry> + <term><option>--settings=</option><replaceable>MODE</replaceable></term> + + <listitem><para>Controls whether + <command>systemd-nspawn</command> shall search for and use + additional per-container settings from + <filename>.nspawn</filename> files. Takes a boolean or the + special values <option>override</option> or + <option>trusted</option>.</para> + + <para>If enabled (the default), a settings file named after the + machine (as specified with the <option>--machine=</option> + setting, or derived from the directory or image file name) + with the suffix <filename>.nspawn</filename> is searched in + <filename>/etc/systemd/nspawn/</filename> and + <filename>/run/systemd/nspawn/</filename>. If it is found + there, its settings are read and used. If it is not found + there, it is subsequently searched in the same directory as the + image file or in the immediate parent of the root directory of + the container. In this case, if the file is found, its settings + will be also read and used, but potentially unsafe settings + are ignored. Note that in both these cases, settings on the + command line take precedence over the corresponding settings + from loaded <filename>.nspawn</filename> files, if both are + specified. Unsafe settings are considered all settings that + elevate the container's privileges or grant access to + additional resources such as files or directories of the + host. For details about the format and contents of + <filename>.nspawn</filename> files, consult + <citerefentry><refentrytitle>systemd.nspawn</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para>If this option is set to <option>override</option>, the + file is searched, read and used the same way, however, the order of + precedence is reversed: settings read from the + <filename>.nspawn</filename> file will take precedence over + the corresponding command line options, if both are + specified.</para> + + <para>If this option is set to <option>trusted</option>, the + file is searched, read and used the same way, but regardless + of being found in <filename>/etc/systemd/nspawn/</filename>, + <filename>/run/systemd/nspawn/</filename> or next to the image + file or container root directory, all settings will take + effect, however, command line arguments still take precedence + over corresponding settings.</para> + + <para>If disabled, no <filename>.nspawn</filename> file is read + and no settings except the ones on the command line are in + effect.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--notify-ready=</option></term> + + <listitem><para>Configures support for notifications from the container's init process. + <option>--notify-ready=</option> takes a boolean (<option>no</option> and <option>yes</option>). + With option <option>no</option> systemd-nspawn notifies systemd + with a <literal>READY=1</literal> message when the init process is created. + With option <option>yes</option> systemd-nspawn waits for the + <literal>READY=1</literal> message from the init process in the container + before sending its own to systemd. For more details about notifications + see <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>).</para></listitem> + </varlistentry> + <xi:include href="standard-options.xml" xpointer="help" /> <xi:include href="standard-options.xml" xpointer="version" /> </variablelist> @@ -773,8 +1014,8 @@ <example> <title>Download a Fedora image and start a shell in it</title> - <programlisting># machinectl pull-raw --verify=no http://ftp.halifax.rwth-aachen.de/fedora/linux/releases/21/Cloud/Images/x86_64/Fedora-Cloud-Base-20141203-21.x86_64.raw.xz -# systemd-nspawn -M Fedora-Cloud-Base-20141203-21</programlisting> + <programlisting># machinectl pull-raw --verify=no http://ftp.halifax.rwth-aachen.de/fedora/linux/releases/24/CloudImages/x86_64/images/Fedora-Cloud-Base-24-1.2.x86_64.raw.xz +# systemd-nspawn -M Fedora-Cloud-Base-24-1.2.x86_64.raw</programlisting> <para>This downloads an image using <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> @@ -784,7 +1025,7 @@ <example> <title>Build and boot a minimal Fedora distribution in a container</title> - <programlisting># dnf -y --releasever=21 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd dnf fedora-release vim-minimal + <programlisting># dnf -y --releasever=23 --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora --enablerepo=updates install systemd passwd dnf fedora-release vim-minimal # systemd-nspawn -bD /srv/mycontainer</programlisting> <para>This installs a minimal Fedora distribution into the @@ -844,9 +1085,9 @@ <title>See Also</title> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.nspawn</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry project='mankier'><refentrytitle>dnf</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry project='archlinux'><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, diff --git a/man/systemd-path.xml b/man/systemd-path.xml index dfc75ee0ff..e2b23eec51 100644 --- a/man/systemd-path.xml +++ b/man/systemd-path.xml @@ -60,13 +60,13 @@ <para><command>systemd-path</command> may be used to query system and user paths. The tool makes many of the paths described in <citerefentry><refentrytitle>file-hierarchy</refentrytitle><manvolnum>7</manvolnum></citerefentry> - queriable.</para> + available for querying.</para> - <para>When invoked without arguments a list of known paths and + <para>When invoked without arguments, a list of known paths and their current values is shown. When at least one argument is - passed the path with this is name is queried and its value shown. + passed, the path with this name is queried and its value shown. The variables whose name begins with <literal>search-</literal> - don't refer to individual paths, but instead a to a list of + do not refer to individual paths, but instead to a list of colon-separated search paths, in their order of precedence.</para> </refsect1> diff --git a/man/systemd-random-seed.service.xml b/man/systemd-random-seed.service.xml index 8c836688fe..f3b5a947da 100644 --- a/man/systemd-random-seed.service.xml +++ b/man/systemd-random-seed.service.xml @@ -55,7 +55,7 @@ <title>Description</title> <para><filename>systemd-random-seed.service</filename> is a - service that restores the random seed of the system at early-boot + service that restores the random seed of the system at early boot and saves it at shutdown. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for details. Saving/restoring the random seed across boots diff --git a/man/systemd-remount-fs.service.xml b/man/systemd-remount-fs.service.xml index 9bc07fcdda..176f2b2d20 100644 --- a/man/systemd-remount-fs.service.xml +++ b/man/systemd-remount-fs.service.xml @@ -55,7 +55,7 @@ <title>Description</title> <para><filename>systemd-remount-fs.service</filename> is an - early-boot service that applies mount options listed in + early boot service that applies mount options listed in <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry> to the root file system, the <filename>/usr</filename> file system, and the kernel API file systems. This is required so that the diff --git a/man/systemd-resolve.xml b/man/systemd-resolve.xml new file mode 100644 index 0000000000..2bc917ac26 --- /dev/null +++ b/man/systemd-resolve.xml @@ -0,0 +1,394 @@ +<?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"> + +<!-- + This file is part of systemd. + + Copyright 2016 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-resolve" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-resolve</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-resolve</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-resolve</refname> + <refpurpose>Resolve domain names, IPV4 and IPv6 addresses, DNS resource records, and services</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-resolve</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="plain" rep="repeat"><replaceable>HOSTNAME</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis> + <command>systemd-resolve</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="plain" rep="repeat"><replaceable>ADDRESS</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis> + <command>systemd-resolve</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <command> --type=<replaceable>TYPE</replaceable></command> + <arg choice="plain" rep="repeat"><replaceable>DOMAIN</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis> + <command>systemd-resolve</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <command> --service</command> + <arg choice="plain"><arg choice="opt"><arg choice="opt"><replaceable>NAME</replaceable></arg> + <replaceable>TYPE</replaceable></arg> <replaceable>DOMAIN</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis> + <command>systemd-resolve</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <command> --openpgp</command> + <arg choice="plain"><replaceable>USER@DOMAIN</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis> + <command>systemd-resolve</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <command> --tlsa</command> + <arg choice="plain"><replaceable>DOMAIN<optional>:PORT</optional></replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis> + <command>systemd-resolve</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <command> --statistics</command> + </cmdsynopsis> + + <cmdsynopsis> + <command>systemd-resolve</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <command> --reset-statistics</command> + </cmdsynopsis> + + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-resolve</command> may be used to resolve domain names, IPv4 and IPv6 addresses, DNS resource + records and services with the + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + resolver service. By default, the specified list of parameters will be resolved as hostnames, retrieving their IPv4 + and IPv6 addresses. If the parameters specified are formatted as IPv4 or IPv6 operation the reverse operation is + done, and a hostname is retrieved for the specified addresses.</para> + + <para>The program's output contains information about the protocol used for the look-up and on which network + interface the data was discovered. It also contains information on whether the information could be + authenticated. All data for which local DNSSEC validation succeeds is considered authenticated. Moreover all data + originating from local, trusted sources is also reported authenticated, including resolution of the local host + name, the <literal>localhost</literal> host name or all data from <filename>/etc/hosts</filename>.</para> + + <para>The <option>--type=</option> switch may be used to specify a DNS resource record type (A, AAAA, SOA, MX, ...) in + order to request a specific DNS resource record, instead of the address or reverse address lookups. + The special value <literal>help</literal> may be used to list known values.</para> + + <para>The <option>--service</option> switch may be used to resolve <ulink + url="https://tools.ietf.org/html/rfc2782">SRV</ulink> and <ulink + url="https://tools.ietf.org/html/rfc6763">DNS-SD</ulink> services (see below). In this mode, between one and three + arguments are required. If three parameters are passed the first is assumed to be the DNS-SD service name, the + second the SRV service type, and the third the domain to search in. In this case a full DNS-SD style SRV and TXT + lookup is executed. If only two parameters are specified, the first is assumed to be the SRV service type, and the + second the domain to look in. In this case no TXT RR is requested. Finally, if only one parameter is specified, it + is assumed to be a domain name, that is already prefixed with an SRV type, and an SRV lookup is done (no + TXT).</para> + + <para>The <option>--openpgp</option> switch may be used to query PGP keys stored as + <ulink url="https://tools.ietf.org/html/rfc7929">OPENPGPKEY</ulink> resource records. + When this option is specified one or more e-mail address must be specified.</para> + + <para>The <option>--tlsa</option> switch maybe be used to query TLS public + keys stored as + <ulink url="https://tools.ietf.org/html/rfc6698">TLSA</ulink> resource records. + When this option is specified one or more domain names must be specified.</para> + + <para>The <option>--statistics</option> switch may be used to show resolver statistics, including information about + the number of successful and failed DNSSEC validations.</para> + + <para>The <option>--reset-statistics</option> may be used to reset various statistics counters maintained the + resolver, including those shown in the <option>--statistics</option> output. This operation requires root + privileges.</para> + </refsect1> + + <refsect1> + <title>Options</title> + <variablelist> + <varlistentry> + <term><option>-4</option></term> + <term><option>-6</option></term> + + <listitem><para>By default, when resolving a hostname, both IPv4 and IPv6 + addresses are acquired. By specifying <option>-4</option> only IPv4 addresses are requested, by specifying + <option>-6</option> only IPv6 addresses are requested.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-i</option> <replaceable>INTERFACE</replaceable></term> + <term><option>--interface=</option><replaceable>INTERFACE</replaceable></term> + + <listitem><para>Specifies the network interface to execute the query on. This may either be specified as numeric + interface index or as network interface string (e.g. <literal>en0</literal>). Note that this option has no + effect if system-wide DNS configuration (as configured in <filename>/etc/resolv.conf</filename> or + <filename>/etc/systemd/resolve.conf</filename>) in place of per-link configuration is used.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-p</option> <replaceable>PROTOCOL</replaceable></term> + <term><option>--protocol=</option><replaceable>PROTOCOL</replaceable></term> + + <listitem><para>Specifies the network protocol for the query. May be one of <literal>dns</literal> + (i.e. classic unicast DNS), <literal>llmnr</literal> (<ulink + url="https://tools.ietf.org/html/rfc4795">Link-Local Multicast Name Resolution</ulink>), + <literal>llmnr-ipv4</literal>, <literal>llmnr-ipv6</literal> (LLMNR via the indicated underlying IP + protocols). By default the lookup is done via all protocols suitable for the lookup. If used, limits the set of + protocols that may be used. Use this option multiple times to enable resolving via multiple protocols at the + same time. The setting <literal>llmnr</literal> is identical to specifying this switch once with + <literal>llmnr-ipv4</literal> and once via <literal>llmnr-ipv6</literal>. Note that this option does not force + the service to resolve the operation with the specified protocol, as that might require a suitable network + interface and configuration. + The special value <literal>help</literal> may be used to list known values. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-t</option> <replaceable>TYPE</replaceable></term> + <term><option>--type=</option><replaceable>TYPE</replaceable></term> + <term><option>-c</option> <replaceable>CLASS</replaceable></term> + <term><option>--class=</option><replaceable>CLASS</replaceable></term> + + <listitem><para>Specifies the DNS resource record type (e.g. A, AAAA, MX, …) and class (e.g. IN, ANY, …) to + look up. If these options are used a DNS resource record set matching the specified class and type is + requested. The class defaults to IN if only a type is specified. + The special value <literal>help</literal> may be used to list known values. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--service</option></term> + + <listitem><para>Enables service resolution. This enables DNS-SD and simple SRV service resolution, depending + on the specified list of parameters (see above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--service-address=</option><replaceable>BOOL</replaceable></term> + + <listitem><para>Takes a boolean parameter. If true (the default), when doing a service lookup with + <option>--service</option> the hostnames contained in the SRV resource records are resolved as well.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--service-txt=</option><replaceable>BOOL</replaceable></term> + + <listitem><para>Takes a boolean parameter. If true (the default), when doing a DNS-SD service lookup with + <option>--service</option> the TXT service metadata record is resolved as well.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--openpgp</option></term> + + <listitem><para>Enables OPENPGPKEY resource record resolution (see above). Specified e-mail + addresses are converted to the corresponding DNS domain name, and any OPENPGPKEY keys are + printed.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--tlsa</option></term> + + <listitem><para>Enables TLSA resource record resolution (see above). + A query will be performed for each of the specified names prefixed with + the port and family + (<literal>_<replaceable>port</replaceable>._<replaceable>family</replaceable>.<replaceable>domain</replaceable></literal>). + The port number may be specified after a colon + (<literal>:</literal>), otherwise <constant>443</constant> will be used + by default. The family may be specified as an argument after + <option>--tlsa</option>, otherwise <constant>tcp</constant> will be + used.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--cname=</option><replaceable>BOOL</replaceable></term> + + <listitem><para>Takes a boolean parameter. If true (the default), DNS CNAME or DNAME redirections are + followed. Otherwise, if a CNAME or DNAME record is encountered while resolving, an error is + returned.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--search=</option><replaceable>BOOL</replaceable></term> + + <listitem><para>Takes a boolean parameter. If true (the default), any specified single-label hostnames will be + searched in the domains configured in the search domain list, if it is non-empty. Otherwise, the search domain + logic is disabled.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--raw</option><optional>=payload|packet</optional></term> + + <listitem><para>Dump the answer as binary data. If there is no argument or if the argument is + <literal>payload</literal>, the payload of the packet is exported. If the argument is + <literal>packet</literal>, the whole packet is dumped in wire format, prefixed by + length specified as a little-endian 64-bit number. This format allows multiple packets + to be dumped and unambigously parsed.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--legend=</option><replaceable>BOOL</replaceable></term> + + <listitem><para>Takes a boolean parameter. If true (the default), column headers and meta information about the + query response are shown. Otherwise, this output is suppressed.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--statistics</option></term> + + <listitem><para>If specified general resolver statistics are shown, including information whether DNSSEC is + enabled and available, as well as resolution and validation statistics.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--reset-statistics</option></term> + + <listitem><para>Resets the statistics counters shown in <option>--statistics</option> to zero.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--flush-caches</option></term> + + <listitem><para>Flushes all DNS resource record caches the service maintains locally.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--status</option></term> + + <listitem><para>Shows the global and per-link DNS settings in currently in effect.</para></listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + <xi:include href="standard-options.xml" xpointer="no-pager" /> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + + <example> + <title>Retrieve the addresses of the <literal>www.0pointer.net</literal> domain</title> + + <programlisting>$ systemd-resolve www.0pointer.net +www.0pointer.net: 2a01:238:43ed:c300:10c3:bcf3:3266:da74 + 85.214.157.71 + +-- Information acquired via protocol DNS in 611.6ms. +-- Data is authenticated: no +</programlisting> + </example> + + <example> + <title>Retrieve the domain of the <literal>85.214.157.71</literal> IP address</title> + + <programlisting>$ systemd-resolve 85.214.157.71 +85.214.157.71: gardel.0pointer.net + +-- Information acquired via protocol DNS in 1.2997s. +-- Data is authenticated: no +</programlisting> + </example> + + <example> + <title>Retrieve the MX record of the <literal>yahoo.com</literal> domain</title> + + <programlisting>$ systemd-resolve -t MX yahoo.com --legend=no +yahoo.com. IN MX 1 mta7.am0.yahoodns.net +yahoo.com. IN MX 1 mta6.am0.yahoodns.net +yahoo.com. IN MX 1 mta5.am0.yahoodns.net +</programlisting> + </example> + + <example> + <title>Resolve an SRV service</title> + + <programlisting>$ systemd-resolve --service _xmpp-server._tcp gmail.com +_xmpp-server._tcp/gmail.com: alt1.xmpp-server.l.google.com:5269 [priority=20, weight=0] + 173.194.210.125 + alt4.xmpp-server.l.google.com:5269 [priority=20, weight=0] + 173.194.65.125 + ... +</programlisting> + </example> + + <example> + <title>Retrieve a PGP key</title> + + <programlisting>$ systemd-resolve --openpgp zbyszek@fedoraproject.org +d08ee310438ca124a6149ea5cc21b6313b390dce485576eff96f8722._openpgpkey.fedoraproject.org. IN OPENPGPKEY + mQINBFBHPMsBEACeInGYJCb+7TurKfb6wGyTottCDtiSJB310i37/6ZYoeIay/5soJjlMyf + MFQ9T2XNT/0LM6gTa0MpC1st9LnzYTMsT6tzRly1D1UbVI6xw0g0vE5y2Cjk3xUwAynCsSs + ... +</programlisting> + </example> + + <example> + <title>Retrieve a TLS key (<literal>=tcp</literal> and + <literal>:443</literal> could be skipped)</title> + + <programlisting>$ systemd-resolve --tlsa=tcp fedoraproject.org:443 +_443._tcp.fedoraproject.org IN TLSA 0 0 1 19400be5b7a31fb733917700789d2f0a2471c0c9d506c0e504c06c16d7cb17c0 + -- Cert. usage: CA constraint + -- Selector: Full Certificate + -- Matching type: SHA-256 +</programlisting> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> +</refentry> diff --git a/man/systemd-resolved.service.xml b/man/systemd-resolved.service.xml index 89ec5f8b19..56f67960ce 100644 --- a/man/systemd-resolved.service.xml +++ b/man/systemd-resolved.service.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -56,25 +56,164 @@ <refsect1> <title>Description</title> - <para><command>systemd-resolved</command> is a system service that - manages network name resolution. It implements a caching DNS stub - resolver and an LLMNR resolver and responder. It also generates - <filename>/run/systemd/resolve/resolv.conf</filename> for - compatibility which may be symlinked from - <filename>/etc/resolv.conf</filename>.</para> - - <para>The DNS servers contacted are determined from the global - settings in - <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - the per-link static settings in <filename>.network</filename> - files, and the per-link dynamic settings received over DHCP. See + <para><command>systemd-resolved</command> is a system service that provides network name resolution to local + applications. It implements a caching and validating DNS/DNSSEC stub resolver, as well as an LLMNR resolver and + responder. Local applications may submit network name resolution requests via three interfaces:</para> + + <itemizedlist> + <listitem><para>The native, fully-featured API <command>systemd-resolved</command> exposes on the bus. See the + <ulink url="http://www.freedesktop.org/wiki/Software/systemd/resolved">API Documentation</ulink> for + details. Usage of this API is generally recommended to clients as it is asynchronous and fully featured (for + example, properly returns DNSSEC validation status and interface scope for addresses as necessary for supporting + link-local networking).</para></listitem> + + <listitem><para>The glibc + <citerefentry project='man-pages'><refentrytitle>getaddrinfo</refentrytitle><manvolnum>3</manvolnum></citerefentry> API as defined + by <ulink url="https://tools.ietf.org/html/rfc3493">RFC3493</ulink> and its related resolver functions, + including <citerefentry project='man-pages'><refentrytitle>gethostbyname</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This + API is widely supported, including beyond the Linux platform. In its current form it does not expose DNSSEC + validation status information however, and is synchronous only. This API is backed by the glibc Name Service + Switch (<citerefentry project='man-pages'><refentrytitle>nss</refentrytitle><manvolnum>5</manvolnum></citerefentry>). Usage of the + glibc NSS module <citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry> + is required in order to allow glibc's NSS resolver functions to resolve host names via + <command>systemd-resolved</command>.</para></listitem> + + <listitem><para>Additionally, <command>systemd-resolved</command> provides a local DNS stub listener on IP + address 127.0.0.53 on the local loopback interface. Programs issuing DNS requests directly, bypassing any local + API may be directed to this stub, in order to connect them to <command>systemd-resolved</command>. Note however + that it is strongly recommended that local programs use the glibc NSS or bus APIs instead (as described above), + as various network resolution concepts (such as link-local addressing, or LLMNR Unicode domains) cannot be mapped + to the unicast DNS protocol.</para></listitem> + </itemizedlist> + + <para>The DNS servers contacted are determined from the global settings in + <filename>/etc/systemd/resolved.conf</filename>, the per-link static settings in + <filename>/etc/systemd/network/*.network</filename> files, the per-link dynamic settings received over DHCP 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/resolv.conf</filename> (see below).</para> + + <para><command>systemd-resolved</command> synthesizes DNS resource records (RRs) for the following cases:</para> + + <itemizedlist> + <listitem><para>The local, configured hostname is resolved to + all locally configured IP addresses ordered by their scope, or + — if none are configured — the IPv4 address 127.0.0.2 (which + is on the local loopback) and the IPv6 address ::1 (which is the + local host).</para></listitem> + + <listitem><para>The hostnames <literal>localhost</literal> and + <literal>localhost.localdomain</literal> (as well as any hostname + ending in <literal>.localhost</literal> or <literal>.localhost.localdomain</literal>) + are resolved to the IP addresses 127.0.0.1 and ::1.</para></listitem> + + <listitem><para>The hostname <literal>gateway</literal> is + resolved to all current default routing gateway addresses, + ordered by their metric. This assigns a stable hostname to the + current gateway, useful for referencing it independently of the + current network configuration state.</para></listitem> + + <listitem><para>The mappings defined in <filename>/etc/hosts</filename> are resolved to their configured + addresses and back.</para></listitem> + </itemizedlist> + + <para>Lookup requests are routed to the available DNS servers + and LLMNR interfaces according to the following rules:</para> + + <itemizedlist> + <listitem><para>Lookups for the special hostname + <literal>localhost</literal> are never routed to the + network. (A few other, special domains are handled the same way.)</para></listitem> + + <listitem><para>Single-label names are routed to all local + interfaces capable of IP multicasting, using the LLMNR + protocol. Lookups for IPv4 addresses are only sent via LLMNR on + IPv4, and lookups for IPv6 addresses are only sent via LLMNR on + IPv6. Lookups for the locally configured host name and the + <literal>gateway</literal> host name are never routed to + LLMNR.</para></listitem> + + <listitem><para>Multi-label names are routed to all local + interfaces that have a DNS sever configured, plus the globally + configured DNS server if there is one. Address lookups from the + link-local address range are never routed to + DNS.</para></listitem> + </itemizedlist> + + <para>If lookups are routed to multiple interfaces, the first + successful response is returned (thus effectively merging the + 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 more details.</para> + for details. Lookups for a hostname ending in one of the + per-interface domains are exclusively routed to the matching + interfaces.</para> - <para>Note that - <filename>/run/systemd/resolve/resolv.conf</filename> should not - be used directly, but only through a symlink from - <filename>/etc/resolv.conf</filename>.</para> + <para>See the <ulink url="http://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> + <title><filename>/etc/resolv.conf</filename></title> + + <para>Three modes of handling <filename>/etc/resolv.conf</filename> (see + <citerefentry project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>) are + supported:</para> + + <itemizedlist> + <listitem><para>A static file <filename>/usr/lib/systemd/resolv.conf</filename> is provided that lists + the 127.0.0.53 DNS stub (see above) as only DNS server. This file may be symlinked from + <filename>/etc/resolv.conf</filename> in order to connect all local clients that bypass local DNS APIs to + <command>systemd-resolved</command>. This mode of operation is recommended.</para></listitem> + + <listitem><para><command>systemd-resolved</command> maintains the + <filename>/run/systemd/resolve/resolv.conf</filename> file for compatibility with traditional Linux + programs. This file may be symlinked from <filename>/etc/resolv.conf</filename> and is always kept up-to-date, + containing information about all known DNS servers. Note the file format's limitations: it does not know a + concept of per-interface DNS servers and hence only contains system-wide DNS server definitions. Note that + <filename>/run/systemd/resolve/resolv.conf</filename> should not be used directly by applications, but only + through a symlink from <filename>/etc/resolv.conf</filename>. If this mode of operation is used local clients + that bypass any local DNS API will also bypass <command>systemd-resolved</command> and will talk directly to the + known DNS servers.</para> </listitem> + + <listitem><para>Alternatively, <filename>/etc/resolv.conf</filename> may be managed by other packages, in which + case <command>systemd-resolved</command> will read it for DNS configuration data. In this mode of operation + <command>systemd-resolved</command> is consumer rather than provider of this configuration + file. </para></listitem> + </itemizedlist> + + <para>Note that the selected mode of operation for this file is detected fully automatically, depending on whether + <filename>/etc/resolv.conf</filename> is a symlink to <filename>/run/systemd/resolve/resolv.conf</filename> or + lists 127.0.0.53 as DNS server.</para> + </refsect1> + + <refsect1> + <title>Signals</title> + + <variablelist> + <varlistentry> + <term><constant>SIGUSR1</constant></term> + + <listitem><para>Upon reception of the SIGUSR1 process signal <command>systemd-resolved</command> will dump the + contents of all DNS resource record caches it maintains into the system logs.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGUSR2</constant></term> + + <listitem><para>Upon reception of the SIGUSR2 process signal <command>systemd-resolved</command> will flush all + caches it maintains. Note that it should normally not be necessary to request this explicitly – except for + debugging purposes – as <command>systemd-resolved</command> flushes the caches automatically anyway any time + the host's network configuration changes.</para></listitem> + </varlistentry> + </variablelist> </refsect1> <refsect1> @@ -82,6 +221,11 @@ <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>dnssec-trust-anchors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-resolve</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>hosts</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> </para> diff --git a/man/systemd-rfkill@.service.xml b/man/systemd-rfkill.service.xml index 709b09d818..f464842700 100644 --- a/man/systemd-rfkill@.service.xml +++ b/man/systemd-rfkill.service.xml @@ -19,10 +19,10 @@ You should have received a copy of the GNU Lesser General Public License along with systemd; If not, see <http://www.gnu.org/licenses/>. --> -<refentry id="systemd-rfkill@.service" conditional='ENABLE_RFKILL'> +<refentry id="systemd-rfkill.service" conditional='ENABLE_RFKILL'> <refentryinfo> - <title>systemd-rfkill@.service</title> + <title>systemd-rfkill.service</title> <productname>systemd</productname> <authorgroup> @@ -36,27 +36,29 @@ </refentryinfo> <refmeta> - <refentrytitle>systemd-rfkill@.service</refentrytitle> + <refentrytitle>systemd-rfkill.service</refentrytitle> <manvolnum>8</manvolnum> </refmeta> <refnamediv> - <refname>systemd-rfkill@.service</refname> + <refname>systemd-rfkill.service</refname> + <refname>systemd-rfkill.socket</refname> <refname>systemd-rfkill</refname> - <refpurpose>Load and save the RF kill switch state at boot and shutdown</refpurpose> + <refpurpose>Load and save the RF kill switch state at boot and change</refpurpose> </refnamediv> <refsynopsisdiv> - <para><filename>systemd-rfkill@.service</filename></para> + <para><filename>systemd-rfkill.service</filename></para> + <para><filename>systemd-rfkill.socket</filename></para> <para><filename>/usr/lib/systemd/systemd-rfkill</filename></para> </refsynopsisdiv> <refsect1> <title>Description</title> - <para><filename>systemd-rfkill@.service</filename> is a service + <para><filename>systemd-rfkill.service</filename> is a service that restores the RF kill switch state at early boot and saves it - at shutdown. On disk, the RF kill switch state is stored in + on each change. On disk, the RF kill switch state is stored in <filename>/var/lib/systemd/rfkill/</filename>.</para> </refsect1> diff --git a/man/systemd-run.xml b/man/systemd-run.xml index 71b365c8eb..2ad8cb0835 100644 --- a/man/systemd-run.xml +++ b/man/systemd-run.xml @@ -45,7 +45,7 @@ <refnamediv> <refname>systemd-run</refname> - <refpurpose>Run programs in transient scope or service or timer units</refpurpose> + <refpurpose>Run programs in transient scope units, service units, or timer-scheduled service units</refpurpose> </refnamediv> <refsynopsisdiv> @@ -68,39 +68,30 @@ <refsect1> <title>Description</title> - <para><command>systemd-run</command> may be used to create and - start a transient <filename>.service</filename> or a transient - <filename>.timer</filename> or a <filename>.scope</filename> unit - and run the specified <replaceable>COMMAND</replaceable> in - it.</para> - - <para>If a command is run as transient service unit, it will be - started and managed by the service manager like any other service, - and thus show up in the output of <command>systemctl - list-units</command> like any other unit. It will run in a clean - and detached execution environment. <command>systemd-run</command> - will start the service asynchronously in the background and - immediately return.</para> - - <para>If a command is run with timer options, transient timer unit - also be created with transient service unit. But the transient - timer unit is only started immediately. The transient service unit - will be started when the transient timer is elapsed. If - <option>--unit=</option> is specified with timer options, the - <replaceable>COMMAND</replaceable> can be omitted. In this case, - <command>systemd-run</command> assumes service unit is already - loaded and creates transient timer unit only. To successfully - create timer unit, already loaded service unit should be specified - with <option>--unit=</option>. This transient timer unit can - activate the existing service unit like any other timer.</para> - - <para>If a command is run as transient scope unit, it will be - started directly by <command>systemd-run</command> and thus - inherit the execution environment of the caller. It is however - managed by the service manager similar to normal services, and - will also show up in the output of <command>systemctl - list-units</command>. Execution in this case is synchronous, and - execution will return only when the command finishes.</para> + <para><command>systemd-run</command> may be used to create and start a transient <filename>.service</filename> or + <filename>.scope</filename> unit and run the specified <replaceable>COMMAND</replaceable> in it. It may also be + used to create and start a transient <filename>.timer</filename> unit, that activates a + <filename>.service</filename> unit when elapsing.</para> + + <para>If a command is run as transient service unit, it will be started and managed by the service manager like any + other service, and thus shows up in the output of <command>systemctl list-units</command> like any other unit. It + will run in a clean and detached execution environment, with the service manager as its parent process. In this + mode, <command>systemd-run</command> will start the service asynchronously in the background and return after the + command has begun execution (unless <option>--no-block</option> or <option>--watch</option> are specified, see + below).</para> + + <para>If a command is run as transient scope unit, it will be executed by <command>systemd-run</command> itself as + parent process and will thus inherit the execution environment of the caller. However, the processes of the command + are managed by the service manager similar to normal services, and will show up in the output of <command>systemctl + list-units</command>. Execution in this case is synchronous, and will return only when the command finishes. This + mode is enabled via the <option>--scope</option> switch (see below). </para> + + <para>If a command is run with timer options such as <option>--on-calendar=</option> (see below), a transient timer + unit is created alongside the service unit for the specified command. Only the transient timer unit is started + immediately, the transient service unit will be started when the timer elapses. If the <option>--unit=</option> + option is specified, the <replaceable>COMMAND</replaceable> may be omitted. In this case, + <command>systemd-run</command> creates only a <filename>.timer</filename> unit that invokes the specified unit when + elapsing.</para> </refsect1> <refsect1> @@ -110,11 +101,18 @@ <variablelist> <varlistentry> + <term><option>--no-ask-password</option></term> + + <listitem><para>Do not query the user for authentication for + privileged operations.</para></listitem> + </varlistentry> + + <varlistentry> <term><option>--scope</option></term> <listitem> - <para>Create a transient <filename>.scope</filename> unit instead of - the default transient <filename>.service</filename> unit. + <para>Create a transient <filename>.scope</filename> unit instead of the default transient + <filename>.service</filename> unit (see above). </para> </listitem> </varlistentry> @@ -130,9 +128,8 @@ <term><option>--property=</option></term> <term><option>-p</option></term> - <listitem><para>Sets a unit property for the scope or service - unit that is created. This takes an assignment in the same - format as + <listitem><para>Sets a property on the scope or service unit that is created. This option takes an assignment + in the same format as <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s <command>set-property</command> command.</para> </listitem> @@ -141,9 +138,8 @@ <varlistentry> <term><option>--description=</option></term> - <listitem><para>Provide a description for the service or scope - unit. If not specified, the command itself will be used as a - description. See <varname>Description=</varname> in + <listitem><para>Provide a description for the service, scope or timer unit. If not specified, the command + itself will be used as a description. See <varname>Description=</varname> in <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. </para></listitem> </varlistentry> @@ -151,19 +147,16 @@ <varlistentry> <term><option>--slice=</option></term> - <listitem><para>Make the new <filename>.service</filename> or - <filename>.scope</filename> unit part of the specified slice, - instead of the <filename>system.slice</filename>.</para> + <listitem><para>Make the new <filename>.service</filename> or <filename>.scope</filename> unit part of the + specified slice, instead of <filename>system.slice</filename>.</para> </listitem> </varlistentry> <varlistentry> <term><option>--remain-after-exit</option></term> - <listitem><para>After the service or scope process has - terminated, keep the service around until it is explicitly - stopped. This is useful to collect runtime information about - the service after it finished running. Also see + <listitem><para>After the service process has terminated, keep the service around until it is explicitly + stopped. This is useful to collect runtime information about the service after it finished running. Also see <varname>RemainAfterExit=</varname> in <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>. </para> @@ -173,10 +166,8 @@ <varlistentry> <term><option>--send-sighup</option></term> - <listitem><para>When terminating the scope or service unit, - send a SIGHUP immediately after SIGTERM. This is useful to - indicate to shells and shell-like processes that the - connection has been severed. Also see + <listitem><para>When terminating the scope or service unit, send a SIGHUP immediately after SIGTERM. This is + useful to indicate to shells and shell-like processes that the connection has been severed. Also see <varname>SendSIGHUP=</varname> in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. </para> @@ -199,9 +190,8 @@ <term><option>--uid=</option></term> <term><option>--gid=</option></term> - <listitem><para>Runs the service process under the UNIX user - and group. Also see <varname>User=</varname> and - <varname>Group=</varname> in + <listitem><para>Runs the service process under the specified UNIX user and group. Also see + <varname>User=</varname> and <varname>Group=</varname> in <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> </listitem> </varlistentry> @@ -216,11 +206,11 @@ </varlistentry> <varlistentry> - <term><option>--setenv=</option></term> + <term><option>-E <replaceable>NAME</replaceable>=<replaceable>VALUE</replaceable></option></term> + <term><option>--setenv=<replaceable>NAME</replaceable>=<replaceable>VALUE</replaceable></option></term> - <listitem><para>Runs the service process with the specified - environment variables set. Also see - <varname>Environment=</varname> in + <listitem><para>Runs the service process with the specified environment variable set. + Also see <varname>Environment=</varname> in <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> </listitem> </varlistentry> @@ -229,11 +219,9 @@ <term><option>--pty</option></term> <term><option>-t</option></term> - <listitem><para>When invoking a command as service connects - its standard input and output to the invoking tty via a - pseudo TTY device. This allows invoking binaries as services - that expect interactive user input, such as interactive - command shells.</para></listitem> + <listitem><para>When invoking the command, the transient service connects its standard input and output to the + terminal <command>systemd-run</command> is invoked on, via a pseudo TTY device. This allows running binaries + that expect interactive user input as services, such as interactive command shells.</para></listitem> </varlistentry> <varlistentry> @@ -253,44 +241,32 @@ <term><option>--on-unit-active=</option></term> <term><option>--on-unit-inactive=</option></term> - <listitem><para>Defines monotonic timers relative to different - starting points. Also see <varname>OnActiveSec=</varname>, - <varname>OnBootSec=</varname>, - <varname>OnStartupSec=</varname>, - <varname>OnUnitActiveSec=</varname> and - <varname>OnUnitInactiveSec=</varname> in - <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This - options have no effect in conjunction with - <option>--scope</option>.</para> + <listitem><para>Defines a monotonic timer relative to different starting points for starting the specified + command. See <varname>OnActiveSec=</varname>, <varname>OnBootSec=</varname>, <varname>OnStartupSec=</varname>, + <varname>OnUnitActiveSec=</varname> and <varname>OnUnitInactiveSec=</varname> in + <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry> for + details. These options may not be combined with <option>--scope</option>.</para> </listitem> </varlistentry> <varlistentry> <term><option>--on-calendar=</option></term> - <listitem><para>Defines realtime (i.e. wallclock) timers with - calendar event expressions. Also see - <varname>OnCalendar=</varname> in - <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This - option has no effect in conjunction with - <option>--scope</option>.</para> + <listitem><para>Defines a calendar timer for starting the specified command. See <varname>OnCalendar=</varname> + in <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This + option may not be combined with <option>--scope</option>.</para> </listitem> </varlistentry> <varlistentry> <term><option>--timer-property=</option></term> - <listitem><para>Sets a timer unit property for the timer unit - that is created. It is similar with - <option>--property</option> but only for created timer - unit. This option only has effect in conjunction with - <option>--on-active=</option>, <option>--on-boot=</option>, - <option>--on-startup=</option>, - <option>--on-unit-active=</option>, - <option>--on-unit-inactive=</option>, - <option>--on-calendar=</option>. This takes an assignment in - the same format as - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s + <listitem><para>Sets a property on the timer unit that is created. This option is similar to + <option>--property=</option> but applies to the transient timer unit rather than the transient service unit + created. This option only has an effect in conjunction with <option>--on-active=</option>, + <option>--on-boot=</option>, <option>--on-startup=</option>, <option>--on-unit-active=</option>, + <option>--on-unit-inactive=</option> or <option>--on-calendar=</option>. This option takes an assignment in the + same format as <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s <command>set-property</command> command.</para> </listitem> </varlistentry> @@ -298,14 +274,25 @@ <term><option>--no-block</option></term> <listitem> - <para>Do not synchronously wait for the requested operation - to finish. If this is not specified, the job will be - verified, enqueued and <command>systemd-run</command> will - wait until the unit's start-up is completed. By passing this - argument, it is only verified and enqueued.</para> + <para>Do not synchronously wait for the unit start operation to finish. If this option is not specified, the + start request for the transient unit will be verified, enqueued and <command>systemd-run</command> will wait + until the unit's start-up is completed. By passing this argument, it is only verified and enqueued. This + option may not be combined with <option>--wait</option>.</para> </listitem> </varlistentry> + <varlistentry> + <term><option>--wait</option></term> + + <listitem><para>Synchronously wait for the transient service to terminate. If this option is specified, the + start request for the transient unit is verified, enqueued, and waited for. Subsequently the invoked unit is + monitored, and it is waited until it is deactivated again (most likely because the specified command + completed). On exit, terse information about the unit's runtime is shown, including total runtime (as well as + CPU usage, if <option>--property=CPUAccounting=1</option> was set) and the exit code and status of the main + process. This output may be suppressed with <option>--quiet</option>. This option may not be combined with + <option>--no-block</option>, <option>--scope</option> or the various timer options.</para></listitem> + </varlistentry> + <xi:include href="user-system-options.xml" xpointer="user" /> <xi:include href="user-system-options.xml" xpointer="system" /> <xi:include href="user-system-options.xml" xpointer="host" /> @@ -331,33 +318,41 @@ <refsect1> <title>Examples</title> - <para>The following command will log the environment variables - provided by systemd to services:</para> + <example> + <title>Logging environment variables provided by systemd to services</title> - <programlisting># systemd-run env -Running as unit run-19945.service. + <programlisting># systemd-run env +Running as unit: run-19945.service # journalctl -u run-19945.service Sep 08 07:37:21 bupkis systemd[1]: Starting /usr/bin/env... Sep 08 07:37:21 bupkis systemd[1]: Started /usr/bin/env. Sep 08 07:37:21 bupkis env[19948]: PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin Sep 08 07:37:21 bupkis env[19948]: LANG=en_US.UTF-8 Sep 08 07:37:21 bupkis env[19948]: BOOT_IMAGE=/vmlinuz-3.11.0-0.rc5.git6.2.fc20.x86_64</programlisting> + </example> + + <example> + <title>Limiting resources available to a command</title> + + <programlisting># systemd-run -p BlockIOWeight=10 updatedb</programlisting> - <para>The following command invokes the - <citerefentry project='man-pages'><refentrytitle>updatedb</refentrytitle><manvolnum>8</manvolnum></citerefentry> - tool, but lowers the block IO weight for it to 10. See - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more information on the <varname>BlockIOWeight=</varname> - property.</para> + <para>This command invokes the + <citerefentry project='man-pages'><refentrytitle>updatedb</refentrytitle><manvolnum>8</manvolnum></citerefentry> + tool, but lowers the block I/O weight for it to 10. See + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information on the <varname>BlockIOWeight=</varname> + property.</para> + </example> - <programlisting># systemd-run -p BlockIOWeight=10 updatedb</programlisting> + <example> + <title>Running commands at a specified time</title> - <para>The following command will touch a file after 30 seconds.</para> + <para>The following command will touch a file after 30 seconds.</para> - <programlisting># date; systemd-run --on-active=30 --timer-property=AccuracySec=100ms /bin/touch /tmp/foo + <programlisting># date; systemd-run --on-active=30 --timer-property=AccuracySec=100ms /bin/touch /tmp/foo Mon Dec 8 20:44:24 KST 2014 -Running as unit run-71.timer. -Will run as unit run-71.service. +Running as unit: run-71.timer +Will run service as unit: run-71.service # journalctl -b -u run-71.timer -- Logs begin at Fri 2014-12-05 19:09:21 KST, end at Mon 2014-12-08 20:44:54 KST. -- Dec 08 20:44:38 container systemd[1]: Starting /bin/touch /tmp/foo. @@ -366,13 +361,60 @@ Dec 08 20:44:38 container systemd[1]: Started /bin/touch /tmp/foo. -- Logs begin at Fri 2014-12-05 19:09:21 KST, end at Mon 2014-12-08 20:44:54 KST. -- Dec 08 20:44:48 container systemd[1]: Starting /bin/touch /tmp/foo... Dec 08 20:44:48 container systemd[1]: Started /bin/touch /tmp/foo.</programlisting> - - <para>The following command invokes <filename>/bin/bash</filename> - as a service passing its standard input, output and error to - the calling TTY.</para> - - <programlisting># systemd-run -t /bin/bash</programlisting> - + </example> + + <example> + <title>Allowing access to the tty</title> + + <para>The following command invokes <filename>/bin/bash</filename> as a service + passing its standard input, output and error to the calling TTY.</para> + + <programlisting># systemd-run -t --send-sighup /bin/bash</programlisting> + </example> + + <example> + <title>Start <command>screen</command> as a user service</title> + + <programlisting>$ systemd-run --scope --user screen +Running scope as unit run-r14b0047ab6df45bfb45e7786cc839e76.scope. + +$ screen -ls +There is a screen on: + 492..laptop (Detached) +1 Socket in /var/run/screen/S-fatima. +</programlisting> + + <para>This starts the <command>screen</command> process as a child of the + <command>systemd --user</command> process that was started by + <filename>user@.service</filename>, in a scope unit. A + <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry> + unit is used instead of a + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + unit, because <command>screen</command> will exit when detaching from the terminal, + and a service unit would be terminated. Running <command>screen</command> + as a user unit has the advantage that it is not part of the session scope. + If <varname>KillUserProcesses=yes</varname> is configured in + <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + the default, the session scope will be terminated when the user logs + out of that session.</para> + + <para>The <filename>user@.service</filename> is started automatically + when the user first logs in, and stays around as long as at least one + login session is open. After the user logs out of the last session, + <filename>user@.service</filename> and all services underneath it + are terminated. This behavior is the default, when "lingering" is + not enabled for that user. Enabling lingering means that + <filename>user@.service</filename> is started automatically during + boot, even if the user is not logged in, and that the service is + not terminated when the user logs out.</para> + + <para>Enabling lingering allows the user to run processes without being logged in, + for example to allow <command>screen</command> to persist after the user logs out, + even if the session scope is terminated. In the default configuration, users can + enable lingering for themselves:</para> + + <programlisting>$ loginctl enable-linger</programlisting> + </example> </refsect1> <refsect1> @@ -387,6 +429,7 @@ Dec 08 20:44:48 container systemd[1]: Started /bin/touch /tmp/foo.</programlisti <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-mount</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/systemd-activate.xml b/man/systemd-socket-activate.xml index 3b854fd8ec..2cf3a7d377 100644 --- a/man/systemd-activate.xml +++ b/man/systemd-socket-activate.xml @@ -21,11 +21,11 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>. --> -<refentry id="systemd-activate" +<refentry id="systemd-socket-activate" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> - <title>systemd-activate</title> + <title>systemd-socket-activate</title> <productname>systemd</productname> <authorgroup> @@ -39,18 +39,18 @@ </refentryinfo> <refmeta> - <refentrytitle>systemd-activate</refentrytitle> - <manvolnum>8</manvolnum> + <refentrytitle>systemd-socket-activate</refentrytitle> + <manvolnum>1</manvolnum> </refmeta> <refnamediv> - <refname>systemd-activate</refname> + <refname>systemd-socket-activate</refname> <refpurpose>Test socket activation of daemons</refpurpose> </refnamediv> <refsynopsisdiv> <cmdsynopsis> - <command>/usr/lib/systemd/systemd-activate</command> + <command>systemd-socket-activate</command> <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="plain"><replaceable>daemon</replaceable></arg> <arg choice="opt" rep="repeat">OPTIONS</arg> @@ -60,24 +60,21 @@ <refsect1> <title>Description</title> - <para><command>systemd-activate</command> can be used to - launch a socket activated daemon from the command line for - testing purposes. It can also be used to launch single instances - of the daemon per connection (inetd-style). + <para><command>systemd-socket-activate</command> may be used to launch a socket-activated service binary from the command + line for testing purposes. It may also be used to launch individual instances of the service binary per connection. </para> <para>The daemon to launch and its options should be specified - after options intended for <command>systemd-activate</command>. + after options intended for <command>systemd-socket-activate</command>. </para> - <para>If the <option>-a</option> option is given, file descriptor - of the connection will be used as the standard input and output of - the launched process. Otherwise, standard input and output will be - inherited, and sockets will be passed through file descriptors 3 - and higher. Sockets passed through <varname>$LISTEN_FDS</varname> - to <command>systemd-activate</command> will be passed through to - the daemon, in the original positions. Other sockets specified - with <option>--listen</option> will use consecutive descriptors. + <para>If the <option>--inetd</option> option is given, the socket file descriptor will be used as the standard + input and output of the launched process. Otherwise, standard input and output will be inherited, and sockets will + be passed through file descriptors 3 and higher. Sockets passed through <varname>$LISTEN_FDS</varname> to + <command>systemd-socket-activate</command> will be passed through to the daemon, in the original positions. Other sockets + specified with <option>--listen=</option> will use consecutive descriptors. By default, + <command>systemd-socket-activate</command> listens on a stream socket, use <option>--datagram</option> and + <option>--seqpacket</option> to listen on datagram or sequential packet sockets instead (see below). </para> </refsect1> @@ -98,9 +95,32 @@ <term><option>-a</option></term> <term><option>--accept</option></term> - <listitem><para>Launch a separate instance of daemon per - connection and pass the connection socket as standard input - and standard output.</para></listitem> + <listitem><para>Launch an instance of the service binary for each connection and pass the connection + socket.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-d</option></term> + <term><option>--datagram</option></term> + + <listitem><para>Listen on a datagram socket (<constant>SOCK_DGRAM</constant>), instead of a stream socket + (<constant>SOCK_STREAM</constant>). May not be combined with <option>--seqpacket</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--seqpacket</option></term> + + <listitem><para>Listen on a sequential packet socket (<constant>SOCK_SEQPACKET</constant>), instead of a stream + socket (<constant>SOCK_STREAM</constant>). May not be combined with + <option>--datagram</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--inetd</option></term> + + <listitem><para>Use the inetd protocol for passing file descriptors, i.e. as standard input and standard + output, instead of the new-style protocol for passing file descriptors using <varname>$LISTEN_FDS</varname> + (see above).</para></listitem> </varlistentry> <varlistentry> @@ -111,7 +131,19 @@ launched process. If <replaceable>VAR</replaceable> is followed by <literal>=</literal>, assume that it is a variable–value pair. Otherwise, obtain the value from the - environment of <command>systemd-activate</command> itself. + environment of <command>systemd-socket-activate</command> itself. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--fdname=</option><replaceable>NAME</replaceable><optional>:<replaceable>NAME</replaceable>...</optional></term> + + <listitem><para>Specify names for the file descriptors passed. This is equivalent to setting + <varname>FileDescriptorName=</varname> in socket unit files, and enables use of + <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + Multiple entries may be specifies using separate options or by separating names with colons + (<literal>:</literal>) in one option. In case more names are given than descriptors, superfluous ones willl be + ignored. In case less names are given than descriptors, the remaining file descriptors will be unnamed. </para></listitem> </varlistentry> @@ -126,6 +158,7 @@ <varlistentry> <term><varname>$LISTEN_FDS</varname></term> <term><varname>$LISTEN_PID</varname></term> + <term><varname>$LISTEN_FDNAMES</varname></term> <listitem><para>See <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> @@ -149,13 +182,13 @@ <example> <title>Run an echo server on port 2000</title> - <programlisting>$ /usr/lib/systemd/systemd-activate -l 2000 -a cat</programlisting> + <programlisting>$ systemd-socket-activate -l 2000 --inetd -a cat</programlisting> </example> <example> - <title>Run a socket activated instance of <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry></title> + <title>Run a socket-activated instance of <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry></title> - <programlisting>$ /usr/lib/systemd/systemd-activate -l 19531 /usr/lib/systemd/systemd-journal-gatewayd</programlisting> + <programlisting>$ systemd-socket-activate -l 19531 /usr/lib/systemd/systemd-journal-gatewayd</programlisting> </example> </refsect1> @@ -165,6 +198,8 @@ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>cat</refentrytitle><manvolnum>1</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/systemd-sysctl.service.xml b/man/systemd-sysctl.service.xml index d4c1a7ebe3..686b2cdef4 100644 --- a/man/systemd-sysctl.service.xml +++ b/man/systemd-sysctl.service.xml @@ -19,7 +19,8 @@ You should have received a copy of the GNU Lesser General Public License along with systemd; If not, see <http://www.gnu.org/licenses/>. --> -<refentry id="systemd-sysctl.service"> +<refentry id="systemd-sysctl.service" + xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>systemd-sysctl.service</title> @@ -47,21 +48,96 @@ </refnamediv> <refsynopsisdiv> + <cmdsynopsis> + <command>/usr/lib/systemd/systemd-sysctl</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="opt" rep="repeat"><replaceable>CONFIGFILE</replaceable></arg> + </cmdsynopsis> <para><filename>systemd-sysctl.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-sysctl</filename></para> </refsynopsisdiv> <refsect1> <title>Description</title> - <para><filename>systemd-sysctl.service</filename> is an early-boot + <para><filename>systemd-sysctl.service</filename> is an early boot service that configures <citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> - kernel parameters.</para> + kernel parameters by invoking <command>/usr/lib/systemd/systemd-sysctl</command>.</para> + + <para>When invoked with no arguments, <command>/usr/lib/systemd/systemd-sysctl</command> applies + all directives from configuration files listed in + <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + If one or more filenames are passed on the command line, only the directives in these files are + applied.</para> + + <para>In addition, <option>--prefix=</option> option may be used to limit which sysctl + settings are applied.</para> <para>See <citerefentry project='man-pages'><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for information about the configuration of this service.</para> + for information about the configuration of sysctl settings. After sysctl configuration is + changed on disk, it must be written to the files in <filename>/proc/sys</filename> before it + takes effect. It is possible to update specific settings, or simply to reload all configuration, + see Examples below.</para> + </refsect1> + + <refsect1><title>Options</title> + <variablelist> + <varlistentry id='prefix'> + <term><option>--prefix=</option></term> + <listitem> + <para>Only apply rules with the specified prefix.</para> + </listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + + <example> + <title>Reset all sysctl settings</title> + + <programlisting>systemctl restart systemd-sysctl</programlisting> + </example> + + <example> + <title>View coredump handler configuration</title> + + <programlisting># sysctl kernel.core_pattern +kernel.core_pattern = |/usr/libexec/abrt-hook-ccpp %s %c %p %u %g %t %P %I +</programlisting> + </example> + + <example> + <title>Update coredump handler configuration</title> + + <programlisting># /usr/lib/systemd/systemd-sysctl --prefix kernel.core_pattern</programlisting> + + <para>This searches all the directories listed in + <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for configuration files and writes <filename>/proc/sys/kernel/core_pattern</filename>.</para> + </example> + + <example> + <title>Update coredump handler configuration according to a specific file</title> + + <programlisting># /usr/lib/systemd/systemd-sysctl 50-coredump.conf</programlisting> + + <para>This applies all the settings found in <filename>50-coredump.conf</filename>. + Either <filename>/etc/sysctl.d/50-coredump.conf</filename>, or + <filename>/run/sysctl.d/50-coredump.conf</filename>, or + <filename>/usr/lib/sysctl.d/50-coredump.conf</filename> will be used, in the order + of preference.</para> + </example> + + <para>See + <citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for various ways to directly apply sysctl settings.</para> </refsect1> <refsect1> diff --git a/man/systemd-system-update-generator.xml b/man/systemd-system-update-generator.xml index e7fc95c742..833ed79646 100644 --- a/man/systemd-system-update-generator.xml +++ b/man/systemd-system-update-generator.xml @@ -54,11 +54,10 @@ <para><filename>systemd-system-update-generator</filename> is a generator that automatically redirects the boot process to - <filename>system-update.target</filename> if + <filename>system-update.target</filename>, if <filename>/system-update</filename> exists. This is required to - implement the logic explained in the <ulink - url="http://freedesktop.org/wiki/Software/systemd/SystemUpdates">System - Updates Specification</ulink>. + implement the logic explained in the + <citerefentry><refentrytitle>systemd.offline-updates</refentrytitle><manvolnum>7</manvolnum></citerefentry>. </para> <para><filename>systemd-system-update-generator</filename> implements diff --git a/man/systemd-system.conf.xml b/man/systemd-system.conf.xml index c06accd791..1d995f143e 100644 --- a/man/systemd-system.conf.xml +++ b/man/systemd-system.conf.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -51,14 +51,14 @@ </refnamediv> <refsynopsisdiv> - <para><filename>/etc/systemd/system.conf</filename></para> - <para><filename>/etc/systemd/system.conf.d/*.conf</filename></para> - <para><filename>/run/systemd/system.conf.d/*.conf</filename></para> - <para><filename>/usr/lib/systemd/system.conf.d/*.conf</filename></para> - <para><filename>/etc/systemd/user.conf</filename></para> - <para><filename>/etc/systemd/user.conf.d/*.conf</filename></para> - <para><filename>/run/systemd/user.conf.d/*.conf</filename></para> - <para><filename>/usr/lib/systemd/user.conf.d/*.conf</filename></para> + <para><filename>/etc/systemd/system.conf</filename>, + <filename>/etc/systemd/system.conf.d/*.conf</filename>, + <filename>/run/systemd/system.conf.d/*.conf</filename>, + <filename>/usr/lib/systemd/system.conf.d/*.conf</filename></para> + <para><filename>/etc/systemd/user.conf</filename>, + <filename>/etc/systemd/user.conf.d/*.conf</filename>, + <filename>/run/systemd/user.conf.d/*.conf</filename>, + <filename>/usr/lib/systemd/user.conf.d/*.conf</filename></para> </refsynopsisdiv> <refsect1> @@ -90,9 +90,10 @@ <term><varname>LogColor=</varname></term> <term><varname>LogLocation=</varname></term> <term><varname>DumpCore=yes</varname></term> + <term><varname>CrashChangeVT=no</varname></term> <term><varname>CrashShell=no</varname></term> + <term><varname>CrashReboot=no</varname></term> <term><varname>ShowStatus=yes</varname></term> - <term><varname>CrashChVT=1</varname></term> <term><varname>DefaultStandardOutput=journal</varname></term> <term><varname>DefaultStandardError=inherit</varname></term> @@ -105,11 +106,24 @@ </varlistentry> <varlistentry> + <term><varname>CtrlAltDelBurstAction=</varname></term> + + <listitem><para>Defines what action will be performed + if user presses Ctrl-Alt-Delete more than 7 times in 2s. + Can be set to <literal>reboot-force</literal>, <literal>poweroff-force</literal> + or disabled with <literal>ignore</literal>. Defaults to + <literal>reboot-force</literal>. + </para></listitem> + </varlistentry> + + <varlistentry> <term><varname>CPUAffinity=</varname></term> <listitem><para>Configures the initial CPU affinity for the - init process. Takes a space-separated list of CPU - indices.</para></listitem> + 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> @@ -268,16 +282,16 @@ </varlistentry> <varlistentry> - <term><varname>DefaultStartLimitInterval=</varname></term> + <term><varname>DefaultStartLimitIntervalSec=</varname></term> <term><varname>DefaultStartLimitBurst=</varname></term> <listitem><para>Configure the default unit start rate limiting, as configured per-service by - <varname>StartLimitInterval=</varname> and + <varname>StartLimitIntervalSec=</varname> and <varname>StartLimitBurst=</varname>. See <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details on the per-service settings. - <varname>DefaultStartLimitInterval=</varname> defaults to + <varname>DefaultStartLimitIntervalSec=</varname> defaults to 10s. <varname>DefaultStartLimitBurst=</varname> defaults to 5.</para></listitem> </varlistentry> @@ -305,14 +319,28 @@ <term><varname>DefaultCPUAccounting=</varname></term> <term><varname>DefaultBlockIOAccounting=</varname></term> <term><varname>DefaultMemoryAccounting=</varname></term> + <term><varname>DefaultTasksAccounting=</varname></term> <listitem><para>Configure the default resource accounting settings, as configured per-unit by <varname>CPUAccounting=</varname>, - <varname>BlockIOAccounting=</varname> and - <varname>MemoryAccounting=</varname>. See + <varname>BlockIOAccounting=</varname>, + <varname>MemoryAccounting=</varname> and + <varname>TasksAccounting=</varname>. See + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details on the per-unit + settings. <varname>DefaulTasksAccounting=</varname> defaults + to on, the other three settings to off.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultTasksMax=</varname></term> + + <listitem><para>Configure the default value for the per-unit <varname>TasksMax=</varname> setting. See <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details on the per-unit settings.</para></listitem> + for details. This setting applies to all unit types that support resource control settings, with the exception + of slice units. Defaults to 15%, which equals 4915 with the kernel's defaults on the host, but might be smaller + in OS containers.</para></listitem> </varlistentry> <varlistentry> @@ -336,11 +364,26 @@ <listitem><para>These settings control various default resource limits for units. See <citerefentry><refentrytitle>setrlimit</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details. Use the string <varname>infinity</varname> to - configure no limit on a specific resource. These settings may - be overridden in individual units using the corresponding - LimitXXX= directives. Note that these resource limits are only - defaults for units, they are not applied to PID 1 + for details. The resource limit is possible to specify in two formats, + <option>value</option> to set soft and hard limits to the same value, + or <option>soft:hard</option> to set both limits individually (e.g. DefaultLimitAS=4G:16G). + Use the string <varname>infinity</varname> to + configure no limit on a specific resource. The multiplicative + suffixes K (=1024), M (=1024*1024) and so on for G, T, P and E + may be used for resource limits measured in bytes + (e.g. DefaultLimitAS=16G). For the limits referring to time values, + the usual time units ms, s, min, h and so on may be used (see + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details). Note that if no time unit is specified for + <varname>DefaultLimitCPU=</varname> the default unit of seconds is + implied, while for <varname>DefaultLimitRTTIME=</varname> the default + unit of microseconds is implied. Also, note that the effective + granularity of the limits might influence their + enforcement. For example, time limits specified for + <varname>DefaultLimitCPU=</varname> will be rounded up implicitly to + multiples of 1s. These settings may be overridden in individual units + using the corresponding LimitXXX= directives. Note that these resource + limits are only defaults for units, they are not applied to PID 1 itself.</para></listitem> </varlistentry> </variablelist> diff --git a/man/systemd-sysusers.xml b/man/systemd-sysusers.xml index a0c0f996ac..4892caad12 100644 --- a/man/systemd-sysusers.xml +++ b/man/systemd-sysusers.xml @@ -74,7 +74,7 @@ specified in <citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> are searched for a matching file. If the string - <filename>-</filename> is specified as filenames entries from the + <filename>-</filename> is specified as filename, entries from the standard input of the process are read.</para> </refsect1> diff --git a/man/systemd-sysv-generator.xml b/man/systemd-sysv-generator.xml index f2d56cbcd2..2353eb3efe 100644 --- a/man/systemd-sysv-generator.xml +++ b/man/systemd-sysv-generator.xml @@ -63,7 +63,7 @@ <para><ulink url="http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB headers</ulink> in SysV init scripts are interpreted, and the ordering specified in the header is turned into dependencies between the generated - unit and other units. LSB facilities + unit and other units. The LSB facilities <literal>$remote_fs</literal>, <literal>$network</literal>, <literal>$named</literal>, <literal>$portmap</literal>, <literal>$time</literal> are supported and will be turned into @@ -73,11 +73,11 @@ <para>SysV runlevels have corresponding systemd targets (<filename>runlevel<replaceable>X</replaceable>.target</filename>). - Wrapper unit that is generated will be wanted by those targets + The wrapper unit that is generated will be wanted by those targets which correspond to runlevels for which the script is enabled.</para> - <para><command>systemd</command> does not supports SysV scripts as + <para><command>systemd</command> does not support SysV scripts as part of early boot, so all wrapper units are ordered after <filename>basic.target</filename>.</para> diff --git a/man/systemd-timesyncd.service.xml b/man/systemd-timesyncd.service.xml index ac1af2d136..6ec384313b 100644 --- a/man/systemd-timesyncd.service.xml +++ b/man/systemd-timesyncd.service.xml @@ -71,6 +71,10 @@ files, and the per-link dynamic settings received over DHCP. See <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more details.</para> + + <para><citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s + <command>set-ntp</command> command may be used to enable and + start, or disable and stop this service.</para> </refsect1> <refsect1> @@ -81,7 +85,7 @@ <term><filename>/var/lib/systemd/clock</filename></term> <listitem> - <para>This file contains the timestamp of last successful + <para>This file contains the timestamp of the last successful synchronization.</para> </listitem> </varlistentry> diff --git a/man/systemd-tmpfiles.xml b/man/systemd-tmpfiles.xml index ceec06f840..c1aab51551 100644 --- a/man/systemd-tmpfiles.xml +++ b/man/systemd-tmpfiles.xml @@ -75,11 +75,11 @@ <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>. </para> - <para>If invoked with no arguments, it applies all directives from - all configuration files. If one or more filenames are passed on - the command line, only the directives in these files are applied. - If only the basename of a configuration file is specified, all - configuration directories as specified in + <para>If invoked with no arguments, it applies all directives from all configuration + files. If one or more absolute filenames are passed on the command line, only the + directives in these files are applied. If <literal>-</literal> is specified instead + of a filename, directives are read from standard input. If only the basename of a + configuration file is specified, all configuration directories as specified in <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> are searched for a matching file.</para> </refsect1> diff --git a/man/systemd-udevd.service.xml b/man/systemd-udevd.service.xml index b19b04d7cb..243fd06471 100644 --- a/man/systemd-udevd.service.xml +++ b/man/systemd-udevd.service.xml @@ -103,7 +103,7 @@ <term><option>--event-timeout=</option></term> <listitem> <para>Set the number of seconds to wait for events to finish. After - this time the event will be terminated. The default is 180 seconds.</para> + this time, the event will be terminated. The default is 180 seconds.</para> </listitem> </varlistentry> diff --git a/man/systemd-update-done.service.xml b/man/systemd-update-done.service.xml index d65f175418..a2dad39f01 100644 --- a/man/systemd-update-done.service.xml +++ b/man/systemd-update-done.service.xml @@ -58,7 +58,7 @@ service that is invoked as part of the first boot after the vendor operating system resources in <filename>/usr</filename> have been updated. This is useful to implement offline updates of - <filename>/usr</filename> which might requires updates to + <filename>/usr</filename> which might require updates to <filename>/etc</filename> or <filename>/var</filename> on the following boot.</para> diff --git a/man/systemd-user-sessions.service.xml b/man/systemd-user-sessions.service.xml index e75ef11c4e..67aba54119 100644 --- a/man/systemd-user-sessions.service.xml +++ b/man/systemd-user-sessions.service.xml @@ -57,9 +57,9 @@ <para><filename>systemd-user-sessions.service</filename> is a service that controls user logins through <citerefentry project='man-pages'><refentrytitle>pam_nologin</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - After basic system initialization is complete it removes + After basic system initialization is complete, it removes <filename>/run/nologin</filename>, thus permitting logins. Before - system shutdown it creates <filename>/run/nologin</filename>, thus + system shutdown, it creates <filename>/run/nologin</filename>, thus prohibiting further logins.</para> </refsect1> diff --git a/man/systemd-vconsole-setup.service.xml b/man/systemd-vconsole-setup.service.xml index 7c6ed08997..e048258621 100644 --- a/man/systemd-vconsole-setup.service.xml +++ b/man/systemd-vconsole-setup.service.xml @@ -55,7 +55,7 @@ <title>Description</title> <para><filename>systemd-vconsole-setup.service</filename> is an - early-boot service that configures the virtual console font and + early boot service that configures the virtual console font and console keymap. Internally it calls <citerefentry project='mankier'><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry> and @@ -63,41 +63,7 @@ <para>See <citerefentry><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for information about the configuration files understood by this - service.</para> - - - </refsect1> - - <refsect1> - <title>Kernel Command Line</title> - - <para>A few configuration parameters from - <filename>vconsole.conf</filename> may be overridden on the kernel - command line:</para> - - <variablelist class='kernel-commandline-options'> - <varlistentry> - <term><varname>vconsole.keymap=</varname></term> - <term><varname>vconsole.keymap.toggle=</varname></term> - - <listitem><para>Overrides the key mapping table for the - keyboard and the second toggle keymap.</para></listitem> - </varlistentry> - <varlistentry> - - <term><varname>vconsole.font=</varname></term> - <term><varname>vconsole.font.map=</varname></term> - <term><varname>vconsole.font.unimap=</varname></term> - - <listitem><para>Configures the console font, the console map, - and the unicode font map.</para></listitem> - </varlistentry> - </variablelist> - - <para>See - <citerefentry><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for information about these settings.</para> + for information about the configuration files and kernel command line options understood by this program.</para> </refsect1> <refsect1> diff --git a/man/systemd.automount.xml b/man/systemd.automount.xml index 9561590c5c..a43dc981bd 100644 --- a/man/systemd.automount.xml +++ b/man/systemd.automount.xml @@ -66,14 +66,13 @@ [Install] sections. The automount specific configuration options are configured in the [Automount] section.</para> - <para>Automount units must be named after the automount - directories they control. Example: the automount point - <filename noindex='true'>/home/lennart</filename> must be - configured in a unit file - <filename>home-lennart.automount</filename>. For details about the - escaping logic used to convert a file system path to a unit name - see - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + <para>Automount units must be named after the automount directories they control. Example: the automount point + <filename noindex='true'>/home/lennart</filename> must be configured in a unit file + <filename>home-lennart.automount</filename>. For details about the escaping logic used to convert a file system + path to a unit name see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Note that + automount units cannot be templated, nor is it possible to add multiple names to an automount unit by creating + additional symlinks to its unit file.</para> <para>For each automount unit file a matching mount unit file (see <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry> @@ -85,10 +84,22 @@ <para>Automount units may be used to implement on-demand mounting as well as parallelized mounting of file systems.</para> + </refsect1> + + <refsect1> + <title>Automatic Dependencies</title> + + <para>If an automount unit is beneath another mount unit in the + file system hierarchy, both a requirement and an ordering + dependency between both units are created automatically.</para> + + <para>An implicit <varname>Before=</varname> dependency is created + between an automount unit and the mount unit it activates.</para> + + <para>Automount units acquire automatic <varname>Before=</varname> and <varname>Conflicts=</varname> on + <filename>umount.target</filename> in order to be stopped during shutdown, unless + <varname>DefaultDependencies=no</varname> is set in the <literal>[Unit]</literal> section.</para> - <para>If an automount point is beneath another mount point in the - file system hierarchy, a dependency between both units is created - automatically.</para> </refsect1> <refsect1> @@ -137,7 +148,7 @@ </varlistentry> <varlistentry> <term><varname>TimeoutIdleSec=</varname></term> - <listitem><para>Configures an idleness timeout. Once the mount has been + <listitem><para>Configures an idle timeout. Once the mount has been idle for the specified time, systemd will attempt to unmount. Takes a unit-less value in seconds, or a time span value such as "5min 20s". Pass 0 to disable the timeout logic. The timeout is disabled by diff --git a/man/systemd.device.xml b/man/systemd.device.xml index ac6deafb18..effed098dd 100644 --- a/man/systemd.device.xml +++ b/man/systemd.device.xml @@ -83,7 +83,18 @@ the escaping logic used to convert a file system path to a unit name see <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </refsect1> + <refsect1> + <title>Automatic Dependencies</title> + + <para>Many unit types automatically acquire dependencies on device + units of devices they require. For example, + <filename>.socket</filename> unit acquire dependencies on the + device units of the network interface specified in + <varname>BindToDevice=</varname>. Similar, swap and mount units + acquire dependencies on the units encapsulating their backing + block devices.</para> </refsect1> <refsect1> diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index 45a4422dc3..c088042a51 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -1,3 +1,4 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -76,6 +77,29 @@ </refsect1> <refsect1> + <title>Automatic Dependencies</title> + + <para>A few execution parameters result in additional, automatic + dependencies to be added.</para> + + <para>Units with <varname>WorkingDirectory=</varname> or + <varname>RootDirectory=</varname> set automatically gain + dependencies of type <varname>Requires=</varname> and + <varname>After=</varname> on all mount units required to access + the specified paths. This is equivalent to having them listed + explicitly in <varname>RequiresMountsFor=</varname>.</para> + + <para>Similar, units with <varname>PrivateTmp=</varname> enabled + automatically get mount unit dependencies for all mounts + required to access <filename>/tmp</filename> and + <filename>/var/tmp</filename>.</para> + + <para>Units whose standard output or error output is connected to <option>journal</option>, <option>syslog</option> + or <option>kmsg</option> (or their combinations with console output, see below) automatically acquire dependencies + of type <varname>After=</varname> on <filename>systemd-journald.socket</filename>.</para> + </refsect1> + + <refsect1> <title>Options</title> <variablelist class='unit-directives'> @@ -83,32 +107,71 @@ <varlistentry> <term><varname>WorkingDirectory=</varname></term> - <listitem><para>Takes an absolute directory path. Sets the - working directory for executed processes. If not set, defaults - to the root directory when systemd is running as a system - instance and the respective user's home directory if run as - user.</para></listitem> + <listitem><para>Takes a directory path relative to the service's root directory specified by + <varname>RootDirectory=</varname>, or the special value <literal>~</literal>. Sets the working directory for + executed processes. If set to <literal>~</literal>, the home directory of the user specified in + <varname>User=</varname> is used. If not set, defaults to the root directory when systemd is running as a + system instance and the respective user's home directory if run as user. If the setting is prefixed with the + <literal>-</literal> character, a missing working directory is not considered fatal. If + <varname>RootDirectory=</varname> is not set, then <varname>WorkingDirectory=</varname> is relative to the root + of the system running the service manager. Note that setting this parameter might result in additional + dependencies to be added to the unit (see above).</para></listitem> </varlistentry> <varlistentry> <term><varname>RootDirectory=</varname></term> - <listitem><para>Takes an absolute directory path. Sets the - root directory for executed processes, with the - <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry> - system call. If this is used, it must be ensured that the - process and all its auxiliary files are available in the - <function>chroot()</function> jail.</para></listitem> + <listitem><para>Takes a directory path relative to the host's root directory (i.e. the root of the system + running the service manager). Sets the root directory for executed processes, with the <citerefentry + project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system + call. If this is used, it must be ensured that the process binary and all its auxiliary files are available in + the <function>chroot()</function> jail. Note that setting this parameter might result in additional + dependencies to be added to the unit (see above).</para> + + <para>The <varname>PrivateUsers=</varname> setting is particularly useful in conjunction with + <varname>RootDirectory=</varname>. For details, see below.</para></listitem> </varlistentry> <varlistentry> <term><varname>User=</varname></term> <term><varname>Group=</varname></term> - <listitem><para>Sets the Unix user or group that the processes - are executed as, respectively. Takes a single user or group - name or ID as argument. If no group is set, the default group - of the user is chosen.</para></listitem> + <listitem><para>Set the UNIX user or group that the processes are executed as, respectively. Takes a single + user or group name, or numeric ID as argument. If no group is set, the default group of the user is used. This + setting does not affect commands whose command line is prefixed with <literal>+</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DynamicUser=</varname></term> + + <listitem><para>Takes a boolean parameter. If set, a UNIX user and group pair is allocated dynamically when the + unit is started, and released as soon as it is stopped. The user and group will not be added to + <filename>/etc/passwd</filename> or <filename>/etc/group</filename>, but are managed transiently during + runtime. The <citerefentry><refentrytitle>nss-systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry> + glibc NSS module provides integration of these dynamic users/groups into the system's user and group + databases. The user and group name to use may be configured via <varname>User=</varname> and + <varname>Group=</varname> (see above). If these options are not used and dynamic user/group allocation is + enabled for a unit, the name of the dynamic user/group is implicitly derived from the unit name. If the unit + name without the type suffix qualifies as valid user name it is used directly, otherwise a name incorporating a + hash of it is used. If a statically allocated user or group of the configured name already exists, it is used + and no dynamic user/group is allocated. Dynamic users/groups are allocated from the UID/GID range + 61184…65519. It is recommended to avoid this range for regular system or login users. At any point in time + each UID/GID from this range is only assigned to zero or one dynamically allocated users/groups in + use. However, UID/GIDs are recycled after a unit is terminated. Care should be taken that any processes running + as part of a unit for which dynamic users/groups are enabled do not leave files or directories owned by these + users/groups around, as a different unit might get the same UID/GID assigned later on, and thus gain access to + these files or directories. If <varname>DynamicUser=</varname> is enabled, <varname>RemoveIPC=</varname>, + <varname>PrivateTmp=</varname> are implied. This ensures that the lifetime of IPC objects and temporary files + created by the executed processes is bound to the runtime of the service, and hence the lifetime of the dynamic + user/group. Since <filename>/tmp</filename> and <filename>/var/tmp</filename> are usually the only + world-writable directories on a system this ensures that a unit making use of dynamic user/group allocation + cannot leave files around after unit termination. Moreover <varname>ProtectSystem=strict</varname> and + <varname>ProtectHome=read-only</varname> are implied, thus prohibiting the service to write to arbitrary file + system locations. In order to allow the service to write to certain directories, they have to be whitelisted + using <varname>ReadWritePaths=</varname>, but care must be taken so that UID/GID recycling doesn't + create security issues involving files created by the service. Use <varname>RuntimeDirectory=</varname> (see + below) in order to assign a writable runtime directory to a service, owned by the dynamic user/group and + removed automatically when the unit is terminated. Defaults to off.</para></listitem> </varlistentry> <varlistentry> @@ -117,13 +180,25 @@ <listitem><para>Sets the supplementary Unix groups the processes are executed as. This takes a space-separated list of group names or IDs. This option may be specified more than - once in which case all listed groups are set as supplementary - groups. When the empty string is assigned the list of + once, in which case all listed groups are set as supplementary + groups. When the empty string is assigned, the list of supplementary groups is reset, and all assignments prior to this one will have no effect. In any way, this option does not override, but extends the list of supplementary groups configured in the system group database for the - user.</para></listitem> + user. This does not affect commands prefixed with <literal>+</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RemoveIPC=</varname></term> + + <listitem><para>Takes a boolean parameter. If set, all System V and POSIX IPC objects owned by the user and + group the processes of this unit are run as are removed when the unit is stopped. This setting only has an + effect if at least one of <varname>User=</varname>, <varname>Group=</varname> and + <varname>DynamicUser=</varname> are used. It has no effect on IPC objects owned by the root user. Specifically, + this removes System V semaphores, as well as System V and POSIX shared memory segments and message queues. If + multiple units use the same user or group the IPC objects are removed when the last of these units is + stopped. This setting is implied if <varname>DynamicUser=</varname> is set.</para></listitem> </varlistentry> <varlistentry> @@ -151,7 +226,7 @@ <varlistentry> <term><varname>IOSchedulingClass=</varname></term> - <listitem><para>Sets the IO scheduling class for executed + <listitem><para>Sets the I/O scheduling class for executed processes. Takes an integer between 0 and 3 or one of the strings <option>none</option>, <option>realtime</option>, <option>best-effort</option> or <option>idle</option>. See @@ -162,10 +237,10 @@ <varlistentry> <term><varname>IOSchedulingPriority=</varname></term> - <listitem><para>Sets the IO scheduling priority for executed + <listitem><para>Sets the I/O scheduling priority for executed processes. Takes an integer between 0 (highest priority) and 7 (lowest priority). The available priorities depend on the - selected IO scheduling class (see above). See + selected I/O scheduling class (see above). See <citerefentry><refentrytitle>ioprio_set</refentrytitle><manvolnum>2</manvolnum></citerefentry> for details.</para></listitem> </varlistentry> @@ -211,8 +286,10 @@ <term><varname>CPUAffinity=</varname></term> <listitem><para>Controls the CPU affinity of the executed - processes. Takes a space-separated list of CPU indices. This - option may be specified more than once in which case the + 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. + This option may be specified more than once, in which case the specified CPU affinity masks are merged. If the empty string is assigned, the mask is reset, all assignments prior to this will have no effect. See @@ -234,7 +311,7 @@ <listitem><para>Sets environment variables for executed processes. Takes a space-separated list of variable - assignments. This option may be specified more than once in + assignments. This option may be specified more than once, in which case all listed variables will be set. If the same variable is set twice, the later setting will override the earlier setting. If the empty string is assigned to this @@ -263,7 +340,8 @@ <listitem><para>Similar to <varname>Environment=</varname> but reads the environment variables from a text file. The text file should contain new-line-separated variable assignments. - Empty lines and lines starting with ; or # will be ignored, + Empty lines, lines without an <literal>=</literal> separator, + or lines starting with ; or # will be ignored, which may be used for commenting. A line ending with a backslash will be concatenated with the following one, allowing multiline variable definitions. The parser strips @@ -294,6 +372,33 @@ </varlistentry> <varlistentry> + <term><varname>PassEnvironment=</varname></term> + + <listitem><para>Pass environment variables from the systemd system + manager to executed processes. Takes a space-separated list of variable + names. This option may be specified more than once, in which case all + listed variables will be set. If the empty string is assigned to this + option, the list of environment variables is reset, all prior + assignments have no effect. Variables that are not set in the system + manager will not be passed and will be silently ignored.</para> + + <para>Variables passed from this setting are overridden by those passed + from <varname>Environment=</varname> or + <varname>EnvironmentFile=</varname>.</para> + + <para>Example: + <programlisting>PassEnvironment=VAR1 VAR2 VAR3</programlisting> + passes three variables <literal>VAR1</literal>, + <literal>VAR2</literal>, <literal>VAR3</literal> + with the values set for those variables in PID1.</para> + + <para> + See + <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details about environment variables.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>StandardInput=</varname></term> <listitem><para>Controls where file descriptor 0 (STDIN) of the executed processes is connected to. Takes one of @@ -342,6 +447,7 @@ <para>This setting defaults to <option>null</option>.</para></listitem> </varlistentry> + <varlistentry> <term><varname>StandardOutput=</varname></term> <listitem><para>Controls where file descriptor 1 (STDOUT) of @@ -404,11 +510,18 @@ similar to the same option of <varname>StandardInput=</varname>.</para> + <para>If the standard output (or error output, see below) of a unit is connected to the journal, syslog or the + kernel log buffer, the unit will implicitly gain a dependency of type <varname>After=</varname> on + <filename>systemd-journald.socket</filename> (also see the automatic dependencies section above).</para> + <para>This setting defaults to the value set with <option>DefaultStandardOutput=</option> in <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - which defaults to <option>journal</option>.</para></listitem> + which defaults to <option>journal</option>. Note that setting + this parameter might result in additional dependencies to be + added to the unit (see above).</para></listitem> </varlistentry> + <varlistentry> <term><varname>StandardError=</varname></term> <listitem><para>Controls where file descriptor 2 (STDERR) of @@ -419,8 +532,11 @@ standard error. This setting defaults to the value set with <option>DefaultStandardError=</option> in <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - which defaults to <option>inherit</option>.</para></listitem> + which defaults to <option>inherit</option>. Note that setting + this parameter might result in additional dependencies to be + added to the unit (see above).</para></listitem> </varlistentry> + <varlistentry> <term><varname>TTYPath=</varname></term> <listitem><para>Sets the terminal device node to use if @@ -484,7 +600,7 @@ </varlistentry> <varlistentry> <term><varname>SyslogLevel=</varname></term> - <listitem><para>Default syslog level to use when logging to + <listitem><para>The default syslog level to use when logging to syslog or the kernel log buffer. One of <option>emerg</option>, <option>alert</option>, @@ -503,7 +619,7 @@ different log level which can be used to override the default log level specified here. The interpretation of these prefixes may be disabled with <varname>SyslogLevelPrefix=</varname>, - see below. For details see + see below. For details, see <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Defaults to @@ -555,92 +671,147 @@ <term><varname>LimitNICE=</varname></term> <term><varname>LimitRTPRIO=</varname></term> <term><varname>LimitRTTIME=</varname></term> - <listitem><para>These settings set both soft and hard limits - of various resources for executed processes. See - <citerefentry><refentrytitle>setrlimit</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details. Use the string <varname>infinity</varname> to - configure no limit on a specific resource.</para></listitem> + <listitem><para>Set soft and hard limits on various resources for executed processes. See + <citerefentry><refentrytitle>setrlimit</refentrytitle><manvolnum>2</manvolnum></citerefentry> for details on + the resource limit concept. Resource limits may be specified in two formats: either as single value to set a + specific soft and hard limit to the same value, or as colon-separated pair <option>soft:hard</option> to set + both limits individually (e.g. <literal>LimitAS=4G:16G</literal>). Use the string <varname>infinity</varname> + to configure no limit on a specific resource. The multiplicative suffixes K, M, G, T, P and E (to the base + 1024) may be used for resource limits measured in bytes (e.g. LimitAS=16G). For the limits referring to time + values, the usual time units ms, s, min, h and so on may be used (see + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for + details). Note that if no time unit is specified for <varname>LimitCPU=</varname> the default unit of seconds + is implied, while for <varname>LimitRTTIME=</varname> the default unit of microseconds is implied. Also, note + that the effective granularity of the limits might influence their enforcement. For example, time limits + specified for <varname>LimitCPU=</varname> will be rounded up implicitly to multiples of 1s. For + <varname>LimitNICE=</varname> the value may be specified in two syntaxes: if prefixed with <literal>+</literal> + or <literal>-</literal>, the value is understood as regular Linux nice value in the range -20..19. If not + prefixed like this the value is understood as raw resource limit parameter in the range 0..40 (with 0 being + equivalent to 1).</para> + + <para>Note that most process resource limits configured with + these options are per-process, and processes may fork in order + to acquire a new set of resources that are accounted + independently of the original process, and may thus escape + limits set. Also note that <varname>LimitRSS=</varname> is not + implemented on Linux, and setting it has no effect. Often it + is advisable to prefer the resource controls listed in + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> + over these per-process limits, as they apply to services as a + whole, may be altered dynamically at runtime, and are + generally more expressive. For example, + <varname>MemoryLimit=</varname> is a more powerful (and + working) replacement for <varname>LimitRSS=</varname>.</para> + + <para>For system units these resource limits may be chosen freely. For user units however (i.e. units run by a + per-user instance of + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>), these limits are + bound by (possibly more restrictive) per-user limits enforced by the OS.</para> + + <para>Resource limits not configured explicitly for a unit default to the value configured in the various + <varname>DefaultLimitCPU=</varname>, <varname>DefaultLimitFSIZE=</varname>, … options available in + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, and – + if not configured there – the kernel or per-user defaults, as defined by the OS (the latter only for user + services, see above).</para> <table> - <title>Limit directives and their equivalent with ulimit</title> + <title>Resource limit directives, their equivalent <command>ulimit</command> shell commands and the unit used</title> - <tgroup cols='2'> + <tgroup cols='3'> <colspec colname='directive' /> <colspec colname='equivalent' /> + <colspec colname='unit' /> <thead> <row> <entry>Directive</entry> - <entry>ulimit equivalent</entry> + <entry><command>ulimit</command> equivalent</entry> + <entry>Unit</entry> </row> </thead> <tbody> <row> - <entry>LimitCPU</entry> + <entry>LimitCPU=</entry> <entry>ulimit -t</entry> + <entry>Seconds</entry> </row> <row> - <entry>LimitFSIZE</entry> + <entry>LimitFSIZE=</entry> <entry>ulimit -f</entry> + <entry>Bytes</entry> </row> <row> - <entry>LimitDATA</entry> + <entry>LimitDATA=</entry> <entry>ulimit -d</entry> + <entry>Bytes</entry> </row> <row> - <entry>LimitSTACK</entry> + <entry>LimitSTACK=</entry> <entry>ulimit -s</entry> + <entry>Bytes</entry> </row> <row> - <entry>LimitCORE</entry> + <entry>LimitCORE=</entry> <entry>ulimit -c</entry> + <entry>Bytes</entry> </row> <row> - <entry>LimitRSS</entry> + <entry>LimitRSS=</entry> <entry>ulimit -m</entry> + <entry>Bytes</entry> </row> <row> - <entry>LimitNOFILE</entry> + <entry>LimitNOFILE=</entry> <entry>ulimit -n</entry> + <entry>Number of File Descriptors</entry> </row> <row> - <entry>LimitAS</entry> + <entry>LimitAS=</entry> <entry>ulimit -v</entry> + <entry>Bytes</entry> </row> <row> - <entry>LimitNPROC</entry> + <entry>LimitNPROC=</entry> <entry>ulimit -u</entry> + <entry>Number of Processes</entry> </row> <row> - <entry>LimitMEMLOCK</entry> + <entry>LimitMEMLOCK=</entry> <entry>ulimit -l</entry> + <entry>Bytes</entry> </row> <row> - <entry>LimitLOCKS</entry> + <entry>LimitLOCKS=</entry> <entry>ulimit -x</entry> + <entry>Number of Locks</entry> </row> <row> - <entry>LimitSIGPENDING</entry> + <entry>LimitSIGPENDING=</entry> <entry>ulimit -i</entry> + <entry>Number of Queued Signals</entry> </row> <row> - <entry>LimitMSGQUEUE</entry> + <entry>LimitMSGQUEUE=</entry> <entry>ulimit -q</entry> + <entry>Bytes</entry> </row> <row> - <entry>LimitNICE</entry> + <entry>LimitNICE=</entry> <entry>ulimit -e</entry> + <entry>Nice Level</entry> </row> <row> - <entry>LimitRTPRIO</entry> + <entry>LimitRTPRIO=</entry> <entry>ulimit -r</entry> + <entry>Realtime Priority</entry> </row> <row> - <entry>LimitRTTIME</entry> + <entry>LimitRTTIME=</entry> <entry>No equivalent</entry> + <entry>Microseconds</entry> </row> </tbody> </tgroup> - </table> + </table></listitem> </varlistentry> <varlistentry> @@ -658,32 +829,40 @@ <varlistentry> <term><varname>CapabilityBoundingSet=</varname></term> - <listitem><para>Controls which capabilities to include in the - capability bounding set for the executed process. See - <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details. Takes a whitespace-separated list of capability - names as read by - <citerefentry project='mankier'><refentrytitle>cap_from_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - e.g. <constant>CAP_SYS_ADMIN</constant>, - <constant>CAP_DAC_OVERRIDE</constant>, - <constant>CAP_SYS_PTRACE</constant>. Capabilities listed will - be included in the bounding set, all others are removed. If - the list of capabilities is prefixed with - <literal>~</literal>, all but the listed capabilities will be - included, the effect of the assignment inverted. Note that - this option also affects the respective capabilities in the - effective, permitted and inheritable capability sets, on top - of what <varname>Capabilities=</varname> does. If this option - is not used, the capability bounding set is not modified on - process execution, hence no limits on the capabilities of the - process are enforced. This option may appear more than once in - which case the bounding sets are merged. If the empty string - is assigned to this option, the bounding set is reset to the - empty capability set, and all prior settings have no effect. - If set to <literal>~</literal> (without any further argument), - the bounding set is reset to the full set of available - capabilities, also undoing any previous - settings.</para></listitem> + <listitem><para>Controls which capabilities to include in the capability bounding set for the executed + process. See <citerefentry + project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> for + details. Takes a whitespace-separated list of capability names, e.g. <constant>CAP_SYS_ADMIN</constant>, + <constant>CAP_DAC_OVERRIDE</constant>, <constant>CAP_SYS_PTRACE</constant>. Capabilities listed will be + included in the bounding set, all others are removed. If the list of capabilities is prefixed with + <literal>~</literal>, all but the listed capabilities will be included, the effect of the assignment + inverted. Note that this option also affects the respective capabilities in the effective, permitted and + inheritable capability sets. If this option is not used, the capability bounding set is not modified on process + execution, hence no limits on the capabilities of the process are enforced. This option may appear more than + once, in which case the bounding sets are merged. If the empty string is assigned to this option, the bounding + set is reset to the empty capability set, and all prior settings have no effect. If set to + <literal>~</literal> (without any further argument), the bounding set is reset to the full set of available + capabilities, also undoing any previous settings. This does not affect commands prefixed with + <literal>+</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>AmbientCapabilities=</varname></term> + + <listitem><para>Controls which capabilities to include in the ambient capability set for the executed + process. Takes a whitespace-separated list of capability names, e.g. <constant>CAP_SYS_ADMIN</constant>, + <constant>CAP_DAC_OVERRIDE</constant>, <constant>CAP_SYS_PTRACE</constant>. This option may appear more than + once in which case the ambient capability sets are merged. If the list of capabilities is prefixed with + <literal>~</literal>, all but the listed capabilities will be included, the effect of the assignment + inverted. If the empty string is assigned to this option, the ambient capability set is reset to the empty + capability set, and all prior settings have no effect. If set to <literal>~</literal> (without any further + argument), the ambient capability set is reset to the full set of available capabilities, also undoing any + previous settings. Note that adding capabilities to ambient capability set adds them to the process's inherited + capability set. </para><para> Ambient capability sets are useful if you want to execute a process as a + non-privileged user but still want to give it some capabilities. Note that in this case option + <constant>keep-caps</constant> is automatically added to <varname>SecureBits=</varname> to retain the + capabilities over the user change. <varname>AmbientCapabilities=</varname> does not affect commands prefixed + with <literal>+</literal>.</para></listitem> </varlistentry> <varlistentry> @@ -697,118 +876,87 @@ <option>no-setuid-fixup-locked</option>, <option>noroot</option>, and <option>noroot-locked</option>. - This option may appear more than once in which case the secure + This option may appear more than once, in which case the secure bits are ORed. If the empty string is assigned to this option, - the bits are reset to 0. See - <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> + the bits are reset to 0. This does not affect commands prefixed with <literal>+</literal>. + See <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details.</para></listitem> </varlistentry> <varlistentry> - <term><varname>Capabilities=</varname></term> - <listitem><para>Controls the - <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> - set for the executed process. Take a capability string - describing the effective, permitted and inherited capability - sets as documented in - <citerefentry project='mankier'><refentrytitle>cap_from_text</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - Note that these capability sets are usually influenced (and - filtered) by the capabilities attached to the executed file. - Due to that <varname>CapabilityBoundingSet=</varname> is - probably a much more useful setting.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ReadWriteDirectories=</varname></term> - <term><varname>ReadOnlyDirectories=</varname></term> - <term><varname>InaccessibleDirectories=</varname></term> - - <listitem><para>Sets up a new file system namespace for - executed processes. These options may be used to limit access - a process might have to the main file system hierarchy. Each - setting takes a space-separated list of absolute directory - paths. Directories listed in - <varname>ReadWriteDirectories=</varname> are accessible from - within the namespace with the same access rights as from - outside. Directories listed in - <varname>ReadOnlyDirectories=</varname> are accessible for - reading only, writing will be refused even if the usual file - access controls would permit this. Directories listed in - <varname>InaccessibleDirectories=</varname> will be made - inaccessible for processes inside the namespace. Note that - restricting access with these options does not extend to - submounts of a directory that are created later on. These - options may be specified more than once in which case all - directories 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> - <para>Paths in - <varname>ReadOnlyDirectories=</varname> - and - <varname>InaccessibleDirectories=</varname> - may be prefixed with - <literal>-</literal>, in which case - they will be ignored when they do not - exist. 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.</para></listitem> + <term><varname>ReadWritePaths=</varname></term> + <term><varname>ReadOnlyPaths=</varname></term> + <term><varname>InaccessiblePaths=</varname></term> + + <listitem><para>Sets up a new file system namespace for executed processes. These options may be used to limit + access a process might have to the file system hierarchy. Each setting takes a space-separated list of paths + relative to the host's root directory (i.e. the system running the service manager). Note that if paths + contain symlinks, they are resolved relative to the root directory set with + <varname>RootDirectory=</varname>.</para> + + <para>Paths listed in <varname>ReadWritePaths=</varname> are accessible from within the namespace with the same + access modes as from outside of it. Paths listed in <varname>ReadOnlyPaths=</varname> are accessible for + reading only, writing will be refused even if the usual file access controls would permit this. Nest + <varname>ReadWritePaths=</varname> inside of <varname>ReadOnlyPaths=</varname> in order to provide writable + subdirectories within read-only directories. Use <varname>ReadWritePaths=</varname> in order to whitelist + specific paths for write access if <varname>ProtectSystem=strict</varname> is used. Paths listed in + <varname>InaccessiblePaths=</varname> will be made inaccessible for processes inside the namespace (along with + everything below them in the file system hierarchy).</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, + 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> + + <para>Paths in <varname>ReadWritePaths=</varname>, <varname>ReadOnlyPaths=</varname> and + <varname>InaccessiblePaths=</varname> may be prefixed with <literal>-</literal>, in which case they will be ignored + when they do not exist. 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 + <varname>CapabilityBoundingSet=~CAP_SYS_ADMIN</varname> or <varname>SystemCallFilter=~@mount</varname>.</para></listitem> </varlistentry> <varlistentry> <term><varname>PrivateTmp=</varname></term> - <listitem><para>Takes a boolean argument. If true, sets up a - new file system namespace for the executed processes and - mounts private <filename>/tmp</filename> and - <filename>/var/tmp</filename> directories inside it that is - not shared by processes outside of the namespace. This is - useful to secure access to temporary files of the process, but - makes sharing between processes via <filename>/tmp</filename> - or <filename>/var/tmp</filename> impossible. If this is - enabled, all temporary files created by a service in these - directories will be removed after the service is stopped. - Defaults to false. It is possible to run two or more units - within the same private <filename>/tmp</filename> and - <filename>/var/tmp</filename> namespace by using the + <listitem><para>Takes a boolean argument. If true, sets up a new file system namespace for the executed + processes and mounts private <filename>/tmp</filename> and <filename>/var/tmp</filename> directories inside it + that is not shared by processes outside of the namespace. This is useful to secure access to temporary files of + the process, but makes sharing between processes via <filename>/tmp</filename> or <filename>/var/tmp</filename> + impossible. If this is enabled, all temporary files created by a service in these directories will be removed + after the service is stopped. Defaults to false. It is possible to run two or more units within the same + private <filename>/tmp</filename> and <filename>/var/tmp</filename> namespace by using the <varname>JoinsNamespaceOf=</varname> directive, see - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. 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.</para></listitem> + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for + details. This setting is implied if <varname>DynamicUser=</varname> is set. For this setting the same + restrictions regarding mount propagation and privileges apply as for <varname>ReadOnlyPaths=</varname> and + related calls, see above.</para></listitem> + </varlistentry> <varlistentry> <term><varname>PrivateDevices=</varname></term> - <listitem><para>Takes a boolean argument. If true, sets up a - new /dev namespace for the executed processes and only adds - API pseudo devices such as <filename>/dev/null</filename>, - <filename>/dev/zero</filename> or - <filename>/dev/random</filename> (as well as the pseudo TTY - subsystem) to it, but no physical devices such as - <filename>/dev/sda</filename>. This is useful to securely turn - off physical device access by the executed process. Defaults - to false. Enabling this option will also remove - <constant>CAP_MKNOD</constant> from the capability bounding - set for the unit (see above), and set + <listitem><para>Takes a boolean argument. If true, sets up a new /dev namespace for the executed processes and + only adds API pseudo devices such as <filename>/dev/null</filename>, <filename>/dev/zero</filename> or + <filename>/dev/random</filename> (as well as the pseudo TTY subsystem) to it, but no physical devices such as + <filename>/dev/sda</filename>, system memory <filename>/dev/mem</filename>, system ports + <filename>/dev/port</filename> and others. This is useful to securely turn off physical device access by the + executed process. Defaults to false. Enabling this option will install a system call filter to block low-level + I/O system calls that are grouped in the <varname>@raw-io</varname> set, will also remove + <constant>CAP_MKNOD</constant> from the capability bounding set for the unit (see above), and set <varname>DevicePolicy=closed</varname> (see <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details). 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.</para></listitem> + for details). 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. The /dev namespace will be + mounted read-only and 'noexec'. The latter may break old programs which try to set up executable memory by + using <citerefentry><refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum></citerefentry> of + <filename>/dev/zero</filename> instead of using <constant>MAP_ANON</constant>. This setting is implied if + <varname>DynamicUser=</varname> is set. For this setting the same restrictions regarding mount propagation and + privileges apply as for <varname>ReadOnlyPaths=</varname> and related calls, see above.</para></listitem> </varlistentry> <varlistentry> @@ -833,76 +981,104 @@ </varlistentry> <varlistentry> + <term><varname>PrivateUsers=</varname></term> + + <listitem><para>Takes a boolean argument. If true, sets up a new user namespace for the executed processes and + configures a minimal user and group mapping, that maps the <literal>root</literal> user and group as well as + the unit's own user and group to themselves and everything else to the <literal>nobody</literal> user and + group. This is useful to securely detach the user and group databases used by the unit from the rest of the + system, and thus to create an effective sandbox environment. All files, directories, processes, IPC objects and + other resources owned by users/groups not equaling <literal>root</literal> or the unit's own will stay visible + from within the unit but appear owned by the <literal>nobody</literal> user and group. If this mode is enabled, + all unit processes are run without privileges in the host user namespace (regardless if the unit's own + user/group is <literal>root</literal> or not). Specifically this means that the process will have zero process + capabilities on the host's user namespace, but full capabilities within the service's user namespace. Settings + such as <varname>CapabilityBoundingSet=</varname> will affect only the latter, and there's no way to acquire + additional capabilities in the host's user namespace. Defaults to off.</para> + + <para>This setting is particularly useful in conjunction with <varname>RootDirectory=</varname>, as the need to + synchronize the user and group databases in the root directory and on the host is reduced, as the only users + and groups who need to be matched are <literal>root</literal>, <literal>nobody</literal> and the unit's own + user and group.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>ProtectSystem=</varname></term> - <listitem><para>Takes a boolean argument or - <literal>full</literal>. If true, mounts the - <filename>/usr</filename> and <filename>/boot</filename> - directories read-only for processes invoked by this unit. If - set to <literal>full</literal>, the <filename>/etc</filename> - directory is mounted read-only, too. This setting ensures that - any modification of the vendor supplied operating system (and - optionally its configuration) is prohibited for the service. - It is 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. Note however - that processes retaining the CAP_SYS_ADMIN capability can undo - the effect of this setting. This setting is hence particularly - useful for daemons which have this capability removed, for - example with <varname>CapabilityBoundingSet=</varname>. - Defaults to off.</para></listitem> + <listitem><para>Takes a boolean argument or the special values <literal>full</literal> or + <literal>strict</literal>. If true, mounts the <filename>/usr</filename> and <filename>/boot</filename> + directories read-only for processes invoked by this unit. If set to <literal>full</literal>, the + <filename>/etc</filename> directory is mounted read-only, too. If set to <literal>strict</literal> the entire + file system hierarchy is mounted read-only, except for the API file system subtrees <filename>/dev</filename>, + <filename>/proc</filename> and <filename>/sys</filename> (protect these directories using + <varname>PrivateDevices=</varname>, <varname>ProtectKernelTunables=</varname>, + <varname>ProtectControlGroups=</varname>). This setting ensures that any modification of the vendor-supplied + operating system (and optionally its configuration, and local mounts) is prohibited for the service. It is + 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 + above. Defaults to off.</para></listitem> </varlistentry> <varlistentry> <term><varname>ProtectHome=</varname></term> - <listitem><para>Takes a boolean argument or - <literal>read-only</literal>. If true, the directories - <filename>/home</filename>, <filename>/root</filename> and - <filename>/run/user</filename> - are made inaccessible and empty for processes invoked by this - unit. If set to <literal>read-only</literal>, the three - directories are made read-only instead. 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. Note however that - processes retaining the CAP_SYS_ADMIN capability can undo the - effect of this setting. This setting is hence particularly - useful for daemons which have this capability removed, for - example with <varname>CapabilityBoundingSet=</varname>. - Defaults to off.</para></listitem> + <listitem><para>Takes a boolean argument or <literal>read-only</literal>. If true, the directories + <filename>/home</filename>, <filename>/root</filename> and <filename>/run/user</filename> are made inaccessible + and empty for processes invoked by this unit. If set to <literal>read-only</literal>, the three directories are + made read-only instead. 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 above.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ProtectKernelTunables=</varname></term> + + <listitem><para>Takes a boolean argument. If true, kernel variables accessible through + <filename>/proc/sys</filename>, <filename>/sys</filename>, <filename>/proc/sysrq-trigger</filename>, + <filename>/proc/latency_stats</filename>, <filename>/proc/acpi</filename>, + <filename>/proc/timer_stats</filename>, <filename>/proc/fs</filename> and <filename>/proc/irq</filename> will + be made read-only to all processes of the unit. Usually, tunable kernel variables should only be written at + boot-time, with the <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> + mechanism. Almost no services need to write to these at runtime; it is hence recommended to turn this on for + most services. For this setting the same restrictions regarding mount propagation and privileges apply as for + <varname>ReadOnlyPaths=</varname> and related calls, see above. Defaults to off.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ProtectControlGroups=</varname></term> + + <listitem><para>Takes a boolean argument. If true, the Linux Control Groups (<citerefentry + project='man-pages'><refentrytitle>cgroups</refentrytitle><manvolnum>7</manvolnum></citerefentry>) hierarchies + accessible through <filename>/sys/fs/cgroup</filename> will be made read-only to all processes of the + unit. Except for container managers no services should require write access to the control groups hierarchies; + it is hence recommended to turn this on for most services. For this setting the same restrictions regarding + mount propagation and privileges apply as for <varname>ReadOnlyPaths=</varname> and related calls, see + above. Defaults to off.</para></listitem> </varlistentry> <varlistentry> <term><varname>MountFlags=</varname></term> - <listitem><para>Takes a mount propagation flag: - <option>shared</option>, <option>slave</option> or - <option>private</option>, which control whether mounts in the - file system namespace set up for this unit's processes will - receive or propagate mounts or unmounts. See - <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details. Defaults to <option>shared</option>. Use - <option>shared</option> to ensure that mounts and unmounts are - propagated from the host to the container and vice versa. Use - <option>slave</option> to run processes so that none of their - mounts and unmounts will propagate to the host. Use - <option>private</option> to also ensure that no mounts and - unmounts from the host will propagate into the unit processes' - namespace. Note that <option>slave</option> means that file - systems mounted on the host might stay mounted continuously in - the unit's namespace, and thus keep the device busy. Note that - the file system namespace related options - (<varname>PrivateTmp=</varname>, - <varname>PrivateDevices=</varname>, - <varname>ProtectSystem=</varname>, - <varname>ProtectHome=</varname>, - <varname>ReadOnlyDirectories=</varname>, - <varname>InaccessibleDirectories=</varname> and - <varname>ReadWriteDirectories=</varname>) require that mount - and unmount propagation from the unit's file system namespace - is disabled, and hence downgrade <option>shared</option> to + <listitem><para>Takes a mount propagation flag: <option>shared</option>, <option>slave</option> or + <option>private</option>, which control whether mounts in the file system namespace set up for this unit's + processes will receive or propagate mounts or unmounts. See <citerefentry + project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>2</manvolnum></citerefentry> for + details. Defaults to <option>shared</option>. Use <option>shared</option> to ensure that mounts and unmounts + are propagated from the host to the container and vice versa. Use <option>slave</option> to run processes so + that none of their mounts and unmounts will propagate to the host. Use <option>private</option> to also ensure + that no mounts and unmounts from the host will propagate into the unit processes' namespace. Note that + <option>slave</option> means that file systems mounted on the host might stay mounted continuously in the + unit's namespace, and thus keep the device busy. Note that the file system namespace related options + (<varname>PrivateTmp=</varname>, <varname>PrivateDevices=</varname>, <varname>ProtectSystem=</varname>, + <varname>ProtectHome=</varname>, <varname>ProtectKernelTunables=</varname>, + <varname>ProtectControlGroups=</varname>, <varname>ReadOnlyPaths=</varname>, + <varname>InaccessiblePaths=</varname>, <varname>ReadWritePaths=</varname>) require that mount and unmount + propagation from the unit's file system namespace is disabled, and hence downgrade <option>shared</option> to <option>slave</option>. </para></listitem> </varlistentry> @@ -910,10 +1086,16 @@ <term><varname>UtmpIdentifier=</varname></term> <listitem><para>Takes a four character identifier string for - an utmp/wtmp entry for this service. This should only be set - for services such as <command>getty</command> implementations + an <citerefentry + project='man-pages'><refentrytitle>utmp</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and wtmp entry for this service. This should only be + set for services such as <command>getty</command> + implementations (such as <citerefentry + project='die-net'><refentrytitle>agetty</refentrytitle><manvolnum>8</manvolnum></citerefentry>) where utmp/wtmp entries must be created and cleared before and - after execution. If the configured string is longer than four + after execution, or for services that shall be executed as if + they were run by a <command>getty</command> process (see + below). If the configured string is longer than four characters, it is truncated and the terminal four characters are used. This setting interprets %I style string replacements. This setting is unset by default, i.e. no @@ -922,6 +1104,34 @@ </varlistentry> <varlistentry> + <term><varname>UtmpMode=</varname></term> + + <listitem><para>Takes one of <literal>init</literal>, + <literal>login</literal> or <literal>user</literal>. If + <varname>UtmpIdentifier=</varname> is set, controls which + type of <citerefentry + project='man-pages'><refentrytitle>utmp</refentrytitle><manvolnum>5</manvolnum></citerefentry>/wtmp + entries for this service are generated. This setting has no + effect unless <varname>UtmpIdentifier=</varname> is set + too. If <literal>init</literal> is set, only an + <constant>INIT_PROCESS</constant> entry is generated and the + invoked process must implement a + <command>getty</command>-compatible utmp/wtmp logic. If + <literal>login</literal> is set, first an + <constant>INIT_PROCESS</constant> entry, followed by a + <constant>LOGIN_PROCESS</constant> entry is generated. In + this case, the invoked process must implement a <citerefentry + project='die-net'><refentrytitle>login</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible + utmp/wtmp logic. If <literal>user</literal> is set, first an + <constant>INIT_PROCESS</constant> entry, then a + <constant>LOGIN_PROCESS</constant> entry and finally a + <constant>USER_PROCESS</constant> entry is generated. In this + case, the invoked process may be any process that is suitable + to be run as session leader. Defaults to + <literal>init</literal>.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>SELinuxContext=</varname></term> <listitem><para>Set the SELinux security context of the @@ -929,8 +1139,8 @@ domain transition. However, the policy still needs to authorize the transition. This directive is ignored if SELinux is disabled. If prefixed by <literal>-</literal>, all errors - will be ignored. See - <citerefentry project='die-net'><refentrytitle>setexeccon</refentrytitle><manvolnum>3</manvolnum></citerefentry> + will be ignored. This does not affect commands prefixed with <literal>+</literal>. + See <citerefentry project='die-net'><refentrytitle>setexeccon</refentrytitle><manvolnum>3</manvolnum></citerefentry> for details.</para></listitem> </varlistentry> @@ -942,7 +1152,7 @@ Profiles must already be loaded in the kernel, or the unit will fail. This result in a non operation if AppArmor is not enabled. If prefixed by <literal>-</literal>, all errors will - be ignored. </para></listitem> + be ignored. This does not affect commands prefixed with <literal>+</literal>.</para></listitem> </varlistentry> <varlistentry> @@ -951,7 +1161,7 @@ <listitem><para>Takes a <option>SMACK64</option> security label as argument. The process executed by the unit will be started under this label and SMACK will decide whether the - processes is allowed to run or not based on it. The process + process is allowed to run or not, based on it. The process will continue to run under the label specified here unless the executable has its own <option>SMACK64EXEC</option> label, in which case the process will transition to run under that @@ -961,7 +1171,8 @@ <para>The value may be prefixed by <literal>-</literal>, in which case all errors will be ignored. An empty value may be - specified to unset previous assignments.</para> + specified to unset previous assignments. This does not affect + commands prefixed with <literal>+</literal>.</para> </listitem> </varlistentry> @@ -997,7 +1208,9 @@ first character of the list is <literal>~</literal>, the effect is inverted: only the listed system calls will result in immediate process termination (blacklisting). If running in - user mode and this option is used, + user mode, or in system mode, but without the + <constant>CAP_SYS_ADMIN</constant> capability (e.g. setting + <varname>User=nobody</varname>), <varname>NoNewPrivileges=yes</varname> is implied. This feature makes use of the Secure Computing Mode 2 interfaces of the kernel ('seccomp filtering') and is useful for enforcing a @@ -1007,10 +1220,10 @@ <function>sigreturn</function>, <function>exit_group</function>, <function>exit</function> system calls are implicitly whitelisted and do not need to be - listed explicitly. This option may be specified more than once + listed explicitly. This option may be specified more than once, in which case the filter masks are merged. If the empty string is assigned, the filter is reset, all prior assignments will - have no effect.</para> + have no effect. This does not affect commands prefixed with <literal>+</literal>.</para> <para>If you specify both types of this option (i.e. whitelisting and blacklisting), the first encountered will @@ -1023,7 +1236,92 @@ <function>read</function> and <function>write</function>, and right after it add a blacklisting of <function>write</function>, then <function>write</function> - will be removed from the set.) </para></listitem> + will be removed from the set.)</para> + + <para>As the number of possible system + calls is large, predefined sets of system calls are provided. + A set starts with <literal>@</literal> character, followed by + name of the set. + + <table> + <title>Currently predefined system call sets</title> + + <tgroup cols='2'> + <colspec colname='set' /> + <colspec colname='description' /> + <thead> + <row> + <entry>Set</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>@clock</entry> + <entry>System calls for changing the system clock (<citerefentry project='man-pages'><refentrytitle>adjtimex</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>settimeofday</refentrytitle><manvolnum>2</manvolnum></citerefentry>, and related calls)</entry> + </row> + <row> + <entry>@cpu-emulation</entry> + <entry>System calls for CPU emulation functionality (<citerefentry project='man-pages'><refentrytitle>vm86</refentrytitle><manvolnum>2</manvolnum></citerefentry> and related calls)</entry> + </row> + <row> + <entry>@debug</entry> + <entry>Debugging, performance monitoring and tracing functionality (<citerefentry project='man-pages'><refentrytitle>ptrace</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>perf_event_open</refentrytitle><manvolnum>2</manvolnum></citerefentry> and related calls)</entry> + </row> + <row> + <entry>@io-event</entry> + <entry>Event loop system calls (<citerefentry project='man-pages'><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>select</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>eventfd</refentrytitle><manvolnum>2</manvolnum></citerefentry> and related calls)</entry> + </row> + <row> + <entry>@ipc</entry> + <entry>SysV IPC, POSIX Message Queues or other IPC (<citerefentry project='man-pages'><refentrytitle>mq_overview</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>svipc</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> + </row> + <row> + <entry>@keyring</entry> + <entry>Kernel keyring access (<citerefentry project='man-pages'><refentrytitle>keyctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> and related calls)</entry> + </row> + <row> + <entry>@module</entry> + <entry>Kernel module control (<citerefentry project='man-pages'><refentrytitle>init_module</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>delete_module</refentrytitle><manvolnum>2</manvolnum></citerefentry> and related calls)</entry> + </row> + <row> + <entry>@mount</entry> + <entry>File system mounting and unmounting (<citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry>, and related calls)</entry> + </row> + <row> + <entry>@network-io</entry> + <entry>Socket I/O (including local AF_UNIX): <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry></entry> + </row> + <row> + <entry>@obsolete</entry> + <entry>Unusual, obsolete or unimplemented (<citerefentry project='man-pages'><refentrytitle>create_module</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>gtty</refentrytitle><manvolnum>2</manvolnum></citerefentry>, …)</entry> + </row> + <row> + <entry>@privileged</entry> + <entry>All system calls which need super-user capabilities (<citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> + </row> + <row> + <entry>@process</entry> + <entry>Process control, execution, namespaces (<citerefentry project='man-pages'><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>namespaces</refentrytitle><manvolnum>7</manvolnum></citerefentry>, …</entry> + </row> + <row> + <entry>@raw-io</entry> + <entry>Raw I/O port access (<citerefentry project='man-pages'><refentrytitle>ioperm</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>iopl</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <function>pciconfig_read()</function>, …</entry> + </row> + </tbody> + </tgroup> + </table> + + Note, that as new system calls are added to the kernel, additional system calls might be added to the groups + above, so the contents of the sets may change between systemd versions.</para> + + <para>It is recommended to combine the file system namespacing related options with + <varname>SystemCallFilter=~@mount</varname>, in order to prohibit the unit's processes to undo the + mappings. Specifically these are the options <varname>PrivateTmp=</varname>, + <varname>PrivateDevices=</varname>, <varname>ProtectSystem=</varname>, <varname>ProtectHome=</varname>, + <varname>ProtectKernelTunables=</varname>, <varname>ProtectControlGroups=</varname>, + <varname>ReadOnlyPaths=</varname>, <varname>InaccessiblePaths=</varname> and + <varname>ReadWritePaths=</varname>.</para></listitem> </varlistentry> <varlistentry> @@ -1043,11 +1341,12 @@ <varlistentry> <term><varname>SystemCallArchitectures=</varname></term> - <listitem><para>Takes a space separated list of architecture + <listitem><para>Takes a space-separated list of architecture identifiers to include in the system call filter. The known architecture identifiers are <constant>x86</constant>, <constant>x86-64</constant>, <constant>x32</constant>, - <constant>arm</constant> as well as the special identifier + <constant>arm</constant>, <constant>s390</constant>, + <constant>s390x</constant> as well as the special identifier <constant>native</constant>. Only system calls of the specified architectures will be permitted to processes of this unit. This is an effective way to disable compatibility with @@ -1056,8 +1355,10 @@ systems. The special <constant>native</constant> identifier implicitly maps to the native architecture of the system (or more strictly: to the architecture the system manager is - compiled for). If running in user mode and this option is - used, <varname>NoNewPrivileges=yes</varname> is implied. Note + compiled for). If running in user mode, or in system mode, + but without the <constant>CAP_SYS_ADMIN</constant> + capability (e.g. setting <varname>User=nobody</varname>), + <varname>NoNewPrivileges=yes</varname> is implied. Note that setting this option to a non-empty list implies that <constant>native</constant> is included too. By default, this option is set to the empty list, i.e. no architecture system @@ -1086,8 +1387,10 @@ <function>socketpair()</function> (which creates connected AF_UNIX sockets only) are unaffected. Note that this option has no effect on 32-bit x86 and is ignored (but works - correctly on x86-64). If running in user mode and this option - is used, <varname>NoNewPrivileges=yes</varname> is implied. By + correctly on x86-64). If running in user mode, or in system + mode, but without the <constant>CAP_SYS_ADMIN</constant> + capability (e.g. setting <varname>User=nobody</varname>), + <varname>NoNewPrivileges=yes</varname> is implied. By default, no restriction applies, all address families are accessible to processes. If assigned the empty string, any previous list changes are undone.</para> @@ -1098,20 +1401,23 @@ family should be included in the configured whitelist as it is frequently used for local communication, including for <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>2</manvolnum></citerefentry> - logging.</para></listitem> + logging. This does not affect commands prefixed with <literal>+</literal>.</para></listitem> </varlistentry> <varlistentry> <term><varname>Personality=</varname></term> - <listitem><para>Controls which kernel architecture - <citerefentry project='man-pages'><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry> - shall report, when invoked by unit processes. Takes one of - <constant>x86</constant> and <constant>x86-64</constant>. This - is useful when running 32-bit services on a 64-bit host - system. If not specified, the personality is left unmodified - and thus reflects the personality of the host system's - kernel.</para></listitem> + <listitem><para>Controls which kernel architecture <citerefentry + project='man-pages'><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry> shall report, + when invoked by unit processes. Takes one of the architecture identifiers <constant>x86</constant>, + <constant>x86-64</constant>, <constant>ppc</constant>, <constant>ppc-le</constant>, <constant>ppc64</constant>, + <constant>ppc64-le</constant>, <constant>s390</constant> or <constant>s390x</constant>. Which personality + architectures are supported depends on the system architecture. Usually the 64bit versions of the various + system architectures support their immediate 32bit personality architecture counterpart, but no others. For + example, <constant>x86-64</constant> systems support the <constant>x86-64</constant> and + <constant>x86</constant> personalities but no others. The personality feature is useful when running 32-bit + services on a 64-bit host system. If not specified, the personality is left unmodified and thus reflects the + personality of the host system's kernel.</para></listitem> </varlistentry> <varlistentry> @@ -1140,6 +1446,35 @@ <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> </varlistentry> + <varlistentry> + <term><varname>MemoryDenyWriteExecute=</varname></term> + + <listitem><para>Takes a boolean argument. If set, attempts to create memory mappings that are writable and + executable at the same time, or to change existing memory mappings to become executable are prohibited. + Specifically, a system call filter is added that rejects + <citerefentry><refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum></citerefentry> + system calls with both <constant>PROT_EXEC</constant> and <constant>PROT_WRITE</constant> set + and <citerefentry><refentrytitle>mprotect</refentrytitle><manvolnum>2</manvolnum></citerefentry> + system calls with <constant>PROT_EXEC</constant> set. Note that this option is incompatible with programs + that generate program code dynamically at runtime, such as JIT execution engines, or programs compiled making + use of the code "trampoline" feature of various C compilers. This option improves service security, as it makes + harder for software exploits to change running code dynamically. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RestrictRealtime=</varname></term> + + <listitem><para>Takes a boolean argument. If set, any attempts to enable realtime scheduling in a process of + the unit are refused. This restricts access to realtime task scheduling policies such as + <constant>SCHED_FIFO</constant>, <constant>SCHED_RR</constant> or <constant>SCHED_DEADLINE</constant>. See + <citerefentry project='man-pages'><refentrytitle>sched</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details about + these scheduling policies. Realtime scheduling policies may be used to monopolize CPU time for longer periods + of time, and may hence be used to lock up or otherwise trigger Denial-of-Service situations on the system. It + is hence recommended to restrict access to realtime scheduling to the few programs that actually require + them. Defaults to off.</para></listitem> + </varlistentry> + </variablelist> </refsect1> @@ -1190,6 +1525,16 @@ </varlistentry> <varlistentry> + <term><varname>$INVOCATION_ID</varname></term> + + <listitem><para>Contains a randomized, unique 128bit ID identifying each runtime cycle of the unit, formatted + as 32 character hexadecimal string. A new ID is assigned each time the unit changes from an inactive state into + an activating or active state, and may be used to identify this specific runtime cycle, in particular in data + stored offline, such as the journal. The same ID is passed to all processes run as part of the + unit.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>$XDG_RUNTIME_DIR</varname></term> <listitem><para>The directory for volatile state. Set for the @@ -1215,7 +1560,7 @@ <varlistentry> <term><varname>$MAINPID</varname></term> - <listitem><para>The PID of the units main process if it is + <listitem><para>The PID of the unit's main process if it is known. This is only set for control processes as invoked by <varname>ExecReload=</varname> and similar. </para></listitem> </varlistentry> @@ -1230,6 +1575,7 @@ <varlistentry> <term><varname>$LISTEN_FDS</varname></term> <term><varname>$LISTEN_PID</varname></term> + <term><varname>$LISTEN_FDNAMES</varname></term> <listitem><para>Information about file descriptors passed to a service for socket activation. See @@ -1238,6 +1584,24 @@ </varlistentry> <varlistentry> + <term><varname>$NOTIFY_SOCKET</varname></term> + + <listitem><para>The socket + <function>sd_notify()</function> talks to. See + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$WATCHDOG_PID</varname></term> + <term><varname>$WATCHDOG_USEC</varname></term> + + <listitem><para>Information about watchdog keep-alive notifications. See + <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + + <varlistentry> <term><varname>$TERM</varname></term> <listitem><para>Terminal type, set only for units connected to @@ -1247,12 +1611,144 @@ <citerefentry project='man-pages'><refentrytitle>termcap</refentrytitle><manvolnum>5</manvolnum></citerefentry>. </para></listitem> </varlistentry> + + <varlistentry> + <term><varname>$JOURNAL_STREAM</varname></term> + + <listitem><para>If the standard output or standard error output of the executed processes are connected to the + journal (for example, by setting <varname>StandardError=journal</varname>) <varname>$JOURNAL_STREAM</varname> + contains the device and inode numbers of the connection file descriptor, formatted in decimal, separated by a + colon (<literal>:</literal>). This permits invoked processes to safely detect whether their standard output or + standard error output are connected to the journal. The device and inode numbers of the file descriptors should + be compared with the values set in the environment variable to determine whether the process output is still + connected to the journal. Note that it is generally not sufficient to only check whether + <varname>$JOURNAL_STREAM</varname> is set at all as services might invoke external processes replacing their + standard output or standard error output, without unsetting the environment variable.</para> + + <para>This environment variable is primarily useful to allow services to optionally upgrade their used log + protocol to the native journal protocol (using + <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry> and other + functions) if their standard output or standard error output is connected to the journal anyway, thus enabling + delivery of structured metadata along with logged messages.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$SERVICE_RESULT</varname></term> + + <listitem><para>Only defined for the service unit type, this environment variable is passed to all + <varname>ExecStop=</varname> and <varname>ExecStopPost=</varname> processes, and encodes the service + "result". Currently, the following values are defined: <literal>timeout</literal> (in case of an operation + timeout), <literal>exit-code</literal> (if a service process exited with a non-zero exit code; see + <varname>$EXIT_CODE</varname> below for the actual exit code returned), <literal>signal</literal> (if a + service process was terminated abnormally by a signal; see <varname>$EXIT_CODE</varname> below for the actual + signal used for the termination), <literal>core-dump</literal> (if a service process terminated abnormally and + dumped core), <literal>watchdog</literal> (if the watchdog keep-alive ping was enabled for the service but it + missed the deadline), or <literal>resources</literal> (a catch-all condition in case a system operation + failed).</para> + + <para>This environment variable is useful to monitor failure or successful termination of a service. Even + though this variable is available in both <varname>ExecStop=</varname> and <varname>ExecStopPost=</varname>, it + is usually a better choice to place monitoring tools in the latter, as the former is only invoked for services + that managed to start up correctly, and the latter covers both services that failed during their start-up and + those which failed during their runtime.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$EXIT_CODE</varname></term> + <term><varname>$EXIT_STATUS</varname></term> + + <listitem><para>Only defined for the service unit type, these environment variables are passed to all + <varname>ExecStop=</varname>, <varname>ExecStopPost=</varname> processes and contain exit status/code + information of the main process of the service. For the precise definition of the exit code and status, see + <citerefentry><refentrytitle>wait</refentrytitle><manvolnum>2</manvolnum></citerefentry>. <varname>$EXIT_CODE</varname> + is one of <literal>exited</literal>, <literal>killed</literal>, + <literal>dumped</literal>. <varname>$EXIT_STATUS</varname> contains the numeric exit code formatted as string + if <varname>$EXIT_CODE</varname> is <literal>exited</literal>, and the signal name in all other cases. Note + that these environment variables are only set if the service manager succeeded to start and identify the main + process of the service.</para> + + <table> + <title>Summary of possible service result variable values</title> + <tgroup cols='3'> + <colspec colname='result' /> + <colspec colname='status' /> + <colspec colname='code' /> + <thead> + <row> + <entry><varname>$SERVICE_RESULT</varname></entry> + <entry><varname>$EXIT_STATUS</varname></entry> + <entry><varname>$EXIT_CODE</varname></entry> + </row> + </thead> + + <tbody> + <row> + <entry morerows="1" valign="top"><literal>timeout</literal></entry> + <entry valign="top"><literal>killed</literal></entry> + <entry><literal>TERM</literal>, <literal>KILL</literal></entry> + </row> + + <row> + <entry valign="top"><literal>exited</literal></entry> + <entry><literal>0</literal>, <literal>1</literal>, <literal>2</literal>, <literal + >3</literal>, …, <literal>255</literal></entry> + </row> + + <row> + <entry valign="top"><literal>exit-code</literal></entry> + <entry valign="top"><literal>exited</literal></entry> + <entry><literal>0</literal>, <literal>1</literal>, <literal>2</literal>, <literal + >3</literal>, …, <literal>255</literal></entry> + </row> + + <row> + <entry valign="top"><literal>signal</literal></entry> + <entry valign="top"><literal>killed</literal></entry> + <entry><literal>HUP</literal>, <literal>INT</literal>, <literal>KILL</literal>, …</entry> + </row> + + <row> + <entry valign="top"><literal>core-dump</literal></entry> + <entry valign="top"><literal>dumped</literal></entry> + <entry><literal>ABRT</literal>, <literal>SEGV</literal>, <literal>QUIT</literal>, …</entry> + </row> + + <row> + <entry morerows="2" valign="top"><literal>watchdog</literal></entry> + <entry><literal>dumped</literal></entry> + <entry><literal>ABRT</literal></entry> + </row> + <row> + <entry><literal>killed</literal></entry> + <entry><literal>TERM</literal>, <literal>KILL</literal></entry> + </row> + <row> + <entry><literal>exited</literal></entry> + <entry><literal>0</literal>, <literal>1</literal>, <literal>2</literal>, <literal + >3</literal>, …, <literal>255</literal></entry> + </row> + + <row> + <entry><literal>resources</literal></entry> + <entry>any of the above</entry> + <entry>any of the above</entry> + </row> + + <row> + <entry namest="results" nameend="code">Note: the process may be also terminated by a signal not sent by systemd. In particular the process may send an arbitrary signal to itself in a handler for any of the non-maskable signals. Nevertheless, in the <literal>timeout</literal> and <literal>watchdog</literal> rows above only the signals that systemd sends have been included.</entry> + </row> + </tbody> + </tgroup> + </table> + + </listitem> + </varlistentry> </variablelist> <para>Additional variables may be configured by the following means: for processes spawned in specific units, use the - <varname>Environment=</varname> and - <varname>EnvironmentFile=</varname> options above; to specify + <varname>Environment=</varname>, <varname>EnvironmentFile=</varname> + and <varname>PassEnvironment=</varname> options above; to specify variables globally, use <varname>DefaultEnvironment=</varname> (see <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>) @@ -1275,10 +1771,12 @@ <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>exec</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> </refsect1> + </refentry> diff --git a/man/systemd.generator.xml b/man/systemd.generator.xml index 2285e91812..b268104c9d 100644 --- a/man/systemd.generator.xml +++ b/man/systemd.generator.xml @@ -87,7 +87,7 @@ dynamically into native unit files.</para> <para>Generators are loaded from a set of paths determined during - compilation, listed above. System and user generators are loaded + compilation, as listed above. System and user generators are loaded from directories with names ending in <filename>system-generators/</filename> and <filename>user-generators/</filename>, respectively. Generators @@ -96,7 +96,7 @@ <filename>/dev/null</filename> or an empty file can be used to mask a generator, thereby preventing it from running. Please note that the order of the two directories with the highest priority is - reversed with respect to the unit load path and generators in + reversed with respect to the unit load path, and generators in <filename>/run</filename> overwrite those in <filename>/etc</filename>.</para> @@ -164,19 +164,22 @@ Generators are run very early at boot and cannot rely on any external services. They may not talk to any other process. That includes simple things such as logging to - <citerefentry - project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>, or <command>systemd</command> itself (this means: no - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>!). They - can however rely on the most basic kernel functionality to - be available, including mounted <filename>/sys</filename>, - <filename>/proc</filename>, <filename>/dev</filename>. + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>)! + Non-essential file systems like + <filename>/var</filename> and <filename>/home</filename> + are mounted after generators have run. Generators + can however rely on the most basic kernel functionality to be + available, including a mounted <filename>/sys</filename>, + <filename>/proc</filename>, <filename>/dev</filename>, + <filename>/usr</filename>. </para> </listitem> <listitem> <para> - Units written by generators are removed when configuration + Units written by generators are removed when the configuration is reloaded. That means the lifetime of the generated units is closely bound to the reload cycles of <command>systemd</command> itself. @@ -187,9 +190,9 @@ <para> Generators should only be used to generate unit files, not any other kind of configuration. Due to the lifecycle - logic mentioned above generators are not a good fit to + logic mentioned above, generators are not a good fit to generate dynamic configuration for other services. If you - need to generate dynamic configuration for other services + need to generate dynamic configuration for other services, do so in normal services you order before the service in question. </para> @@ -199,7 +202,7 @@ <para> Since <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> - is not available (see above) log messages have to be + is not available (see above), log messages have to be written to <filename>/dev/kmsg</filename> instead. </para> </listitem> @@ -221,19 +224,19 @@ Generators may write out dynamic unit files or just hook unit files into other units with the usual <filename>.wants/</filename> or - <filename>.requires/</filename> symlinks. Often it is + <filename>.requires/</filename> symlinks. Often, it is nicer to simply instantiate a template unit file from <filename>/usr</filename> with a generator instead of - writing out entirely dynamic unit files. Of course this + writing out entirely dynamic unit files. Of course, this works only if a single parameter is to be used. </para> </listitem> <listitem> <para> - If you are careful you can implement generators in shell + If you are careful, you can implement generators in shell scripts. We do recommend C code however, since generators - delay are executed synchronously and hence delay the + are executed synchronously and hence delay the entire boot if they are slow. </para> </listitem> @@ -269,7 +272,7 @@ <para> Instead of heading off now and writing all kind of generators for legacy configuration file formats, please - think twice! It's often a better idea to just deprecate + think twice! It is often a better idea to just deprecate old stuff instead of keeping it artificially alive. </para> </listitem> @@ -306,16 +309,16 @@ <para><citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> temporarily redirects <filename>default.target</filename> to - <filename>system-update.target</filename> if a system update is + <filename>system-update.target</filename>, if a system update is scheduled. Since this needs to override the default user - configuration for <filename>default.target</filename> it uses + configuration for <filename>default.target</filename>, it uses argv[2]. For details about this logic, see - <ulink url="http://www.freedesktop.org/wiki/Software/systemd/SystemUpdates">Implementing - Offline System Updates</ulink>.</para> + <citerefentry><refentrytitle>systemd.offline-updates</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + </para> </example> <example> - <title>Debuging a generator</title> + <title>Debugging a generator</title> <programlisting>dir=$(mktemp -d) SYSTEMD_LOG_LEVEL=debug &systemgeneratordir;/systemd-fstab-generator \ @@ -331,7 +334,6 @@ find $dir</programlisting> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-debug-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-efi-boot-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-getty-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, diff --git a/man/systemd.journal-fields.xml b/man/systemd.journal-fields.xml index afe1200d7e..494f97aad1 100644 --- a/man/systemd.journal-fields.xml +++ b/man/systemd.journal-fields.xml @@ -73,7 +73,7 @@ <para>The human-readable message string for this entry. This is supposed to be the primary text shown to the user. It is usually not translated (but might be in some cases), and is - not supposed to be parsed for meta data.</para> + not supposed to be parsed for metadata.</para> </listitem> </varlistentry> @@ -258,6 +258,16 @@ <variablelist> <varlistentry> <term> + <option>audit</option> + </term> + <listitem> + <para>for those read from the kernel audit subsystem + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> <option>driver</option> </term> <listitem> diff --git a/man/systemd.kill.xml b/man/systemd.kill.xml index 1292f4f513..13b7ab14df 100644 --- a/man/systemd.kill.xml +++ b/man/systemd.kill.xml @@ -138,8 +138,8 @@ <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>. Defaults to <constant>SIGTERM</constant>. </para> - <para>Note that right after sending the signal specified in - this setting systemd will always send + <para>Note that, right after sending the signal specified in + this setting, systemd will always send <constant>SIGCONT</constant>, to ensure that even suspended tasks can be terminated cleanly.</para> </listitem> diff --git a/man/systemd.link.xml b/man/systemd.link.xml index d9b1879c59..8edbe758d9 100644 --- a/man/systemd.link.xml +++ b/man/systemd.link.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -68,11 +68,10 @@ in <filename>/etc</filename> have the highest priority, files in <filename>/run</filename> take precedence over files with the same name in <filename>/usr/lib</filename>. This can be used to - override a system-supplied link file with a local file if needed; - a symlink in <filename>/etc</filename> with the same name as a - link file in <filename>/usr/lib</filename>, pointing to - <filename>/dev/null</filename>, disables the link file - entirely.</para> + override a system-supplied link file with a local file if needed. + As a special case, an empty file (file size 0) or symlink with the + same name pointing to <filename>/dev/null</filename> disables the + configuration file entirely (it is "masked").</para> <para>The link file contains a <literal>[Match]</literal> section, which determines if a given link file may be applied to a given @@ -83,6 +82,10 @@ shipped by the system, any user-supplied <filename>.link</filename> should hence have a lexically earlier name to be considered at all.</para> + + <para>See + <citerefentry><refentrytitle>udevadm</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for diagnosing problems with <filename>.link</filename> files.</para> </refsect1> <refsect1> @@ -104,7 +107,7 @@ <listitem> <para>A whitespace-separated list of shell-style globs matching the device name, as exposed by the udev property - "INTERFACE". This can not be used to match on names that have + "INTERFACE". This cannot be used to match on names that have already been changed from userspace. Caution is advised when matching on kernel-assigned names, as they are known to be unstable between reboots.</para> @@ -218,8 +221,8 @@ generated which is guaranteed to be the same on every boot for the given machine and the given device, but which is otherwise random. This feature depends on ID_NET_NAME_* - properties existing for the link, on hardware where these - properties are not set the generation of a persistent MAC address + properties to exist for the link. On hardware where these + properties are not set, the generation of a persistent MAC address will fail.</para> </listitem> </varlistentry> @@ -229,11 +232,17 @@ <para>If the kernel is using a random MAC address, nothing is done. Otherwise, a new address is randomly generated each time the device appears, typically at - boot. Either way the random address will have the + boot. Either way, the random address will have the <literal>unicast</literal> and <literal>locally administered</literal> bits set.</para> </listitem> </varlistentry> + <varlistentry> + <term><literal>none</literal></term> + <listitem> + <para>Keeps the MAC address assigned by the kernel.</para> + </listitem> + </varlistentry> </variablelist> </listitem> </varlistentry> @@ -378,13 +387,96 @@ </variablelist> </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> + </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> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>UDPSegmentationOffload=</varname></term> + <listitem> + <para>The UDP Segmentation Offload (USO) when true enables + UDP segmentation offload. Takes a boolean value. + Defaults to "unset".</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> + </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> + </listitem> + </varlistentry> </variablelist> </refsect1> <refsect1> - <title>Example</title> + <title>Examples</title> + + <example> + <title>/usr/lib/systemd/network/99-default.link</title> + + <para>The link file <filename>99-default.link</filename> that is + shipped with systemd defines the default naming policy for + links.</para> + + <programlisting>[Link] +NamePolicy=kernel database onboard slot path +MACAddressPolicy=persistent</programlisting> + </example> + <example> - <title>/etc/systemd/network/wireless.link</title> + <title>/etc/systemd/network/10-dmz.link</title> + + <para>This example assigns the fixed name + <literal>dmz0</literal> to the interface with the MAC address + 00:a0:de:63:7a:e6:</para> + + <programlisting>[Match] +MACAddress=00:a0:de:63:7a:e6 + +[Link] +Name=dmz0</programlisting> + </example> + + <example> + <title>/etc/systemd/network/10-internet.link</title> + + <para>This example assigns the fixed name + <literal>internet0</literal> to the interface with the device + path <literal>pci-0000:00:1a.0-*</literal>:</para> + + <programlisting>[Match] +Path=pci-0000:00:1a.0-* + +[Link] +Name=internet0</programlisting> + </example> + + <example> + <title>/etc/systemd/network/25-wireless.link</title> + + <para>Here's an overly complex example that shows the use of a large number of [Match] and [Link] settings.</para> <programlisting>[Match] MACAddress=12:34:56:78:9a:bc diff --git a/man/systemd.mount.xml b/man/systemd.mount.xml index ffffc56936..b0f156f6df 100644 --- a/man/systemd.mount.xml +++ b/man/systemd.mount.xml @@ -82,22 +82,17 @@ will refuse options that are not listed in <filename>/etc/fstab</filename> if it is not run as UID 0.</para> - <para>Mount units must be named after the mount point directories - they control. Example: the mount point - <filename noindex='true'>/home/lennart</filename> must be - configured in a unit file <filename>home-lennart.mount</filename>. - For details about the escaping logic used to convert a file system - path to a unit name, see - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + <para>Mount units must be named after the mount point directories they control. Example: the mount point <filename + noindex='true'>/home/lennart</filename> must be configured in a unit file <filename>home-lennart.mount</filename>. + For details about the escaping logic used to convert a file system path to a unit name, see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Note that mount + units cannot be templated, nor is possible to add multiple names to a mount unit by creating additional symlinks to + it.</para> <para>Optionally, a mount unit may be accompanied by an automount unit, to allow on-demand or parallelized mounting. See <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - <para>If a mount point is beneath another mount point in the file - system hierarchy, a dependency between both units is created - automatically.</para> - <para>Mount points created at runtime (independently of unit files or <filename>/etc/fstab</filename>) will be monitored by systemd and appear like any other mount unit in systemd. See @@ -114,6 +109,43 @@ </refsect1> <refsect1> + <title>Automatic Dependencies</title> + + <para>If a mount unit is beneath another mount unit in the file + system hierarchy, both a requirement dependency and an ordering + dependency between both units are created automatically.</para> + + <para>Block device backed file systems automatically gain + <varname>BindsTo=</varname> and <varname>After=</varname> type + dependencies on the device unit encapsulating the block + device (see below).</para> + + <para>If traditional file system quota is enabled for a mount + unit, automatic <varname>Wants=</varname> and + <varname>Before=</varname> dependencies on + <filename>systemd-quotacheck.service</filename> and + <filename>quotaon.service</filename> are added.</para> + + <para>For mount units with <varname>DefaultDependencies=yes</varname> in the <literal>[Unit]</literal> section (the + default) a couple additional dependencies are added. Mount units referring to local file systems automatically gain + an <varname>After=</varname> dependency on <filename>local-fs-pre.target</filename>. Network mount units + automatically acquire <varname>After=</varname> dependencies on <filename>remote-fs-pre.target</filename>, + <filename>network.target</filename> and <filename>network-online.target</filename>. Towards the latter a + <varname>Wants=</varname> unit is added as well. Mount units referring to local and network file systems are + distinguished by their file system type specification. In some cases this is not sufficient (for example network + block device based mounts, such as iSCSI), in which case <option>_netdev</option> may be added to the mount option + string of the unit, which forces systemd to consider the mount unit a network mount. Mount units (regardless if + local or network) also acquire automatic <varname>Before=</varname> and <varname>Conflicts=</varname> on + <filename>umount.target</filename> in order to be stopped during shutdown.</para> + + <para>Additional implicit dependencies may be added as result of + execution and resource control parameters as documented in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> <title><filename>fstab</filename></title> <para>Mount units may either be configured via unit files, or via @@ -127,10 +159,15 @@ <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> for details about the conversion.</para> + <para>The NFS mount option <option>bg</option> for NFS background mounts + as documented in <citerefentry project='man-pages'><refentrytitle>nfs</refentrytitle><manvolnum>5</manvolnum></citerefentry> + is not supported in <filename>/etc/fstab</filename> entries. The systemd mount option <option>nofail</option> + provides similar functionality and should be used instead.</para> + <para>When reading <filename>/etc/fstab</filename> a few special mount options are understood by systemd which influence how dependencies are created for mount points. systemd will create a - dependency of type <option>Wants</option> or + dependency of type <varname>Wants=</varname> or <option>Requires</option> (see option <option>nofail</option> below), from either <filename>local-fs.target</filename> or <filename>remote-fs.target</filename>, depending whether the file @@ -180,7 +217,7 @@ <varlistentry> <term><option>x-systemd.idle-timeout=</option></term> - <listitem><para>Configures the idleness timeout of the + <listitem><para>Configures the idle timeout of the automount unit. See <varname>TimeoutIdleSec=</varname> in <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.</para></listitem> @@ -192,13 +229,13 @@ <listitem><para>Configure how long systemd should wait for a device to show up before giving up on an entry from <filename>/etc/fstab</filename>. Specify a time in seconds or - explicitly append a unit as <literal>s</literal>, + explicitly append a unit such as <literal>s</literal>, <literal>min</literal>, <literal>h</literal>, <literal>ms</literal>.</para> <para>Note that this option can only be used in <filename>/etc/fstab</filename>, and will be - ignored when part of <varname>Options=</varname> + ignored when part of the <varname>Options=</varname> setting in a unit file.</para> </listitem> </varlistentry> @@ -212,7 +249,7 @@ <filename>local-fs.target</filename> or <filename>remote-fs.target</filename>. This means that it will not be mounted automatically during boot, unless it is pulled - in by some other unit. Option <option>auto</option> has the + in by some other unit. The <option>auto</option> option has the opposite meaning and is the default.</para> </listitem> </varlistentry> @@ -220,7 +257,7 @@ <varlistentry> <term><option>nofail</option></term> - <listitem><para>With <option>nofail</option> this mount will + <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 @@ -315,6 +352,30 @@ </varlistentry> <varlistentry> + <term><varname>LazyUnmount=</varname></term> + + <listitem><para>Takes a boolean argument. If true, detach the + filesystem from the filesystem hierarchy at time of the unmount + operation, and clean up all references to the filesystem as + soon as they are not busy anymore. + This corresponds with + <citerefentry project='man-pages'><refentrytitle>umount</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s + <parameter>-l</parameter> switch. Defaults to + off.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ForceUnmount=</varname></term> + + <listitem><para>Takes a boolean argument. If true, force an + unmount (in case of an unreachable NFS system). + This corresponds with + <citerefentry project='man-pages'><refentrytitle>umount</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s + <parameter>-f</parameter> switch. Defaults to + off.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>DirectoryMode=</varname></term> <listitem><para>Directories of mount points (and any parent directories) are automatically created if needed. This option @@ -336,7 +397,7 @@ Takes a unit-less value in seconds, or a time span value such as "5min 20s". Pass 0 to disable the timeout logic. The default value is set from the manager configuration file's - <varname>DefaultTimeoutStart=</varname> + <varname>DefaultTimeoutStartSec=</varname> variable.</para></listitem> </varlistentry> </variablelist> diff --git a/man/systemd.netdev.xml b/man/systemd.netdev.xml index d15c21be60..ffb66e735b 100644 --- a/man/systemd.netdev.xml +++ b/man/systemd.netdev.xml @@ -58,33 +58,38 @@ <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>. </para> - <para>Virtual Network Device files must have the extension - <filename>.netdev</filename>; other extensions are ignored. - Virtual network devices are created as soon as networkd is - started. If a netdev with the specified name already exists, - networkd will use that as-is rather than create its own. Note that - the settings of the pre-existing netdev will not be changed by + <para>The main Virtual Network Device file must have the extension <filename>.netdev</filename>; + other extensions are ignored. Virtual network devices are created as soon as networkd is + started. If a netdev with the specified name already exists, networkd will use that as-is rather + than create its own. Note that the settings of the pre-existing netdev will not be changed by networkd.</para> - <para>The <filename>.netdev</filename> files are read from the - files located in the system network directory - <filename>/usr/lib/systemd/network</filename>, the volatile - runtime network directory - <filename>/run/systemd/network</filename> and the local - administration network directory - <filename>/etc/systemd/network</filename>. All configuration files - are collectively sorted and processed in lexical order, regardless - of the directories in which they live. However, files with - identical filenames replace each other. Files in - <filename>/etc</filename> have the highest priority, files in - <filename>/run</filename> take precedence over files with the same - name in <filename>/usr/lib</filename>. This can be used to - override a system-supplied configuration file with a local file if - needed; a symlink in <filename>/etc</filename> with the same name - as a configuration file in <filename>/usr/lib</filename>, pointing - to <filename>/dev/null</filename>, disables the configuration file - entirely.</para> - + <para>The <filename>.netdev</filename> files are read from the files located in the system + network directory <filename>/usr/lib/systemd/network</filename>, the volatile runtime network + directory <filename>/run/systemd/network</filename> and the local administration network + directory <filename>/etc/systemd/network</filename>. All configuration files are collectively + sorted and processed in lexical order, regardless of the directories in which they live. + However, files with identical filenames replace each other. Files in <filename>/etc</filename> + have the highest priority, files in <filename>/run</filename> take precedence over files with + the same name in <filename>/usr/lib</filename>. This can be used to override a system-supplied + configuration file with a local file if needed. As a special case, an empty file (file size 0) + or symlink with the same name pointing to <filename>/dev/null</filename> disables the + configuration file entirely (it is "masked").</para> + + <para>Along with the netdev file <filename>foo.netdev</filename>, a "drop-in" directory + <filename>foo.netdev.d/</filename> may exist. All files with the suffix <literal>.conf</literal> + from this directory will be parsed after the file itself is parsed. This is useful to alter or + add configuration settings, without having to modify the main configuration file. Each drop-in + file must have appropriate section headers.</para> + + <para>In addition to <filename>/etc/systemd/network</filename>, drop-in <literal>.d</literal> + directories can be placed in <filename>/usr/lib/systemd/network</filename> or + <filename>/run/systemd/network</filename> directories. Drop-in files in + <filename>/etc</filename> take precedence over those in <filename>/run</filename> which in turn + take precedence over those in <filename>/usr/lib</filename>. Drop-in files under any of these + directories take precedence over the main netdev file wherever located. (Of course, since + <filename>/run</filename> is temporary and <filename>/usr/lib</filename> is for vendors, it is + unlikely drop-ins should be used in either of those places.)</para> </refsect1> <refsect1> @@ -108,7 +113,7 @@ <entry>A bond device is an aggregation of all its slave devices. See <ulink url="https://www.kernel.org/doc/Documentation/networking/bonding.txt">Linux Ethernet Bonding Driver HOWTO</ulink> for details.Local configuration</entry></row> <row><entry><varname>bridge</varname></entry> - <entry>A bridge device is a software switch, each of its slave devices and the bridge itself are ports of the switch.</entry></row> + <entry>A bridge device is a software switch, and each of its slave devices and the bridge itself are ports of the switch.</entry></row> <row><entry><varname>dummy</varname></entry> <entry>A dummy device drops all packets sent to it.</entry></row> @@ -126,7 +131,7 @@ <entry>An IPv4 or IPv6 tunnel over IPv6</entry></row> <row><entry><varname>ip6gretap</varname></entry> - <entry>An Level 2 GRE tunnel over IPv6.</entry></row> + <entry>A Level 2 GRE tunnel over IPv6.</entry></row> <row><entry><varname>ipip</varname></entry> <entry>An IPv4 over IPv4 tunnel.</entry></row> @@ -137,6 +142,9 @@ <row><entry><varname>macvlan</varname></entry> <entry>A macvlan device is a stacked device which receives packets from its underlying device based on MAC address filtering.</entry></row> + <row><entry><varname>macvtap</varname></entry> + <entry>A macvtap device is a stacked device which receives packets from its underlying device based on MAC address filtering.</entry></row> + <row><entry><varname>sit</varname></entry> <entry>An IPv6 over IPv4 tunnel.</entry></row> @@ -147,7 +155,7 @@ <entry>A persistent Level 3 tunnel between a network device and a device node.</entry></row> <row><entry><varname>veth</varname></entry> - <entry>An ethernet tunnel between a pair of network devices.</entry></row> + <entry>An Ethernet tunnel between a pair of network devices.</entry></row> <row><entry><varname>vlan</varname></entry> <entry>A VLAN is a stacked device which receives packets from its underlying device based on VLAN tagging. See <ulink url="http://www.ieee802.org/1/pages/802.1Q.html">IEEE 802.1Q</ulink> for details.</entry></row> @@ -160,6 +168,13 @@ <row><entry><varname>vxlan</varname></entry> <entry>A virtual extensible LAN (vxlan), for connecting Cloud computing deployments.</entry></row> + + <row><entry><varname>vrf</varname></entry> + <entry>A Virtual Routing and Forwarding (<ulink url="https://www.kernel.org/doc/Documentation/networking/vrf.txt">VRF</ulink>) interface to create separate routing and forwarding domains.</entry></row> + + <row><entry><varname>vcan</varname></entry> + <entry>The virtual CAN driver (vcan). Similar to the network loopback devices, vcan offers a virtual local CAN interface.</entry></row> + </tbody> </tgroup> </table> @@ -276,6 +291,99 @@ </variablelist> </refsect1> + <refsect1> + <title>[Bridge] Section Options</title> + + <para>The <literal>[Bridge]</literal> section only applies for + netdevs of kind <literal>bridge</literal>, and accepts the + following keys:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>HelloTimeSec=</varname></term> + <listitem> + <para>HelloTimeSec specifies the number of seconds between two hello packets + sent out by the root bridge and the designated bridges. Hello packets are + used to communicate information about the topology throughout the entire + bridged local area network.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MaxAgeSec=</varname></term> + <listitem> + <para>MaxAgeSec specifies the number of seconds of maximum message age. + If the last seen (received) hello packet is more than this number of + seconds old, the bridge in question will start the takeover procedure + in attempt to become the Root Bridge itself.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>ForwardDelaySec=</varname></term> + <listitem> + <para>ForwardDelaySec specifies the number of seconds spent in each + of the Listening and Learning states before the Forwarding state is entered.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>AgeingTimeSec=</varname></term> + <listitem> + <para>This specifies the number of seconds a MAC Address will be kept in + the forwarding database after having a packet received from this MAC Address.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Priority=</varname></term> + <listitem> + <para>The priority of the bridge. An integer between 0 and 65535. A lower value + means higher priority. The bridge having the lowest priority will be elected as root bridge.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>DefaultPVID=</varname></term> + <listitem> + <para>This specifies the default port VLAN ID of a newly attached bridge port.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MulticastQuerier=</varname></term> + <listitem> + <para>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. + </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. + 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. + </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> + </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> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + <refsect1> <title>[VLAN] Section Options</title> @@ -318,6 +426,15 @@ </refsect1> + <refsect1> + <title>[MACVTAP] Section Options</title> + + <para>The <literal>[MACVTAP]</literal> section applies for + netdevs of kind <literal>macvtap</literal> and accepts the + same key as <literal>[MACVLAN]</literal>.</para> + + </refsect1> + <refsect1> <title>[IPVLAN] Section Options</title> @@ -367,7 +484,7 @@ <term><varname>TTL=</varname></term> <listitem> <para>A fixed Time To Live N on Virtual eXtensible Local - Area Network packets. N is a number in the range 1-255. 0 + Area Network packets. N is a number in the range 1–255. 0 is a special value meaning that packets inherit the TTL value.</para> </listitem> @@ -383,13 +500,19 @@ <term><varname>FDBAgeingSec=</varname></term> <listitem> <para>The lifetime of Forwarding Database entry learnt by - the kernel in seconds.</para> + the kernel, in seconds.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MaximumFDBEntries=</varname></term> + <listitem> + <para>Configures maximum number of FDB entries.</para> </listitem> </varlistentry> <varlistentry> <term><varname>ARPProxy=</varname></term> <listitem> - <para>A boolean. When true, enables ARP proxy.</para> + <para>A boolean. When true, enables ARP proxying.</para> </listitem> </varlistentry> <varlistentry> @@ -402,33 +525,73 @@ <varlistentry> <term><varname>L3MissNotification=</varname></term> <listitem> - <para>A boolean. When true, enables netlink IP ADDR miss + <para>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 circuit is turned + <para>A boolean. When true, route short circuiting is turned on.</para> </listitem> </varlistentry> <varlistentry> - <term><varname>UDPCheckSum=</varname></term> + <term><varname>UDPChecksum=</varname></term> <listitem> - <para>A boolean. When true transmitting UDP checksums when doing VXLAN/IPv4 is turned on.</para> + <para>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>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> </listitem> </varlistentry> <varlistentry> - <term><varname>UDP6ZeroCheckSumRx=</varname></term> + <term><varname>RemoteChecksumTx=</varname></term> <listitem> - <para>A boolean. When true receiving zero checksums in VXLAN/IPv6 is turned on.</para> + <para>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> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>GroupPolicyExtension=</varname></term> + <listitem> + <para>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> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>DestinationPort=</varname></term> + <listitem> + <para>Configures the default destination UDP port on a per-device basis. + If destination port is not specified then Linux kernel default will be used. + Set destination port 4789 to get the IANA assigned value, + and destination port 0 to get default values.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>PortRange=</varname></term> + <listitem> + <para>Configures VXLAN port range. VXLAN bases source + UDP port based on flow to help the receiver to be able + to load balance based on outer header flow. It + restricts the port range to the normal UDP local + ports, and allows overriding via configuration.</para> </listitem> </varlistentry> </variablelist> @@ -467,7 +630,7 @@ <term><varname>TOS=</varname></term> <listitem> <para>The Type Of Service byte value for a tunnel interface. - For details about the TOS see the + For details about the TOS, see the <ulink url="http://tools.ietf.org/html/rfc1349"> Type of Service in the Internet Protocol Suite </ulink> document. </para> @@ -477,9 +640,9 @@ <term><varname>TTL=</varname></term> <listitem> <para>A fixed Time To Live N on tunneled packets. N is a - number in the range 1-255. 0 is a special value meaning that + number in the range 1–255. 0 is a special value meaning that packets inherit the TTL value. The default value for IPv4 - tunnels is: inherit. The default value for IPv6 tunnels is: + tunnels is: inherit. The default value for IPv6 tunnels is 64.</para> </listitem> </varlistentry> @@ -493,20 +656,72 @@ <varlistentry> <term><varname>IPv6FlowLabel=</varname></term> <listitem> - <para>Configures The 20-bit Flow Label (see <ulink url="https://tools.ietf.org/html/rfc6437"> + <para>Configures the 20-bit flow label (see <ulink url="https://tools.ietf.org/html/rfc6437"> RFC 6437</ulink>) field in the IPv6 header (see <ulink url="https://tools.ietf.org/html/rfc2460"> - RFC 2460</ulink>), is used by a node to label packets of a flow. - It's only used for IPv6 Tunnels. - A Flow Label of zero is used to indicate packets that have - not been labeled. Takes following values. - When <literal>inherit</literal> it uses the original flowlabel, - or can be configured to any value betwen 0 to 0xFFFFF.</para> + RFC 2460</ulink>), which is used by a node to label packets of a flow. + It is only used for IPv6 tunnels. + A flow label of zero is used to indicate packets that have + not been labeled. + It can be configured to a value in the range 0–0xFFFFF, or be + set to <literal>inherit</literal>, in which case the original flowlabel is used.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>CopyDSCP=</varname></term> + <listitem> + <para>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 + levels of service to be assigned to network traffic. + Defaults to <literal>no</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>EncapsulationLimit=</varname></term> + <listitem> + <para>The Tunnel Encapsulation Limit option specifies how many additional + levels of encapsulation are permitted to be prepended to the packet. + For example, a Tunnel Encapsulation Limit option containing a limit + value of zero means that a packet carrying that option may not enter + another tunnel before exiting the current tunnel. + (see <ulink url="https://tools.ietf.org/html/rfc2473#section-4.1.1"> RFC 2473</ulink>). + The valid range is 0–255 and <literal>none</literal>. Defaults to 4. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Key=</varname></term> + <listitem> + <para>The <varname>Key=</varname> parameter specifies the same key to use in + both directions (<varname>InputKey=</varname> and <varname>OutputKey=</varname>). + The <varname>Key=</varname> is either a number or an IPv4 address-like dotted quad. + It is used as mark-configured SAD/SPD entry as part of the lookup key (both in data + and control path) in ip xfrm (framework used to implement IPsec protocol). + See <ulink url="http://man7.org/linux/man-pages/man8/ip-xfrm.8.html"> + ip-xfrm — transform configuration</ulink> for details. It is only used for VTI/VTI6 + tunnels.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>InputKey=</varname></term> + <listitem> + <para>The <varname>InputKey=</varname> parameter specifies the key to use for input. + The format is same as <varname>Key=</varname>. It is only used for VTI/VTI6 tunnels.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>OutputKey=</varname></term> + <listitem> + <para>The <varname>OutputKey=</varname> parameter specifies the key to use for output. + The format is same as <varname>Key=</varname>. It is only used for VTI/VTI6 tunnels.</para> </listitem> </varlistentry> <varlistentry> <term><varname>Mode=</varname></term> <listitem> - <para>An <literal>ip6tnl</literal> tunnels can have three + <para>An <literal>ip6tnl</literal> tunnel can be in one of three modes <literal>ip6ip6</literal> for IPv6 over IPv6, <literal>ipip6</literal> for IPv4 over IPv6 or @@ -521,7 +736,7 @@ <para>The <literal>[Peer]</literal> section only applies for netdevs of kind <literal>veth</literal> and accepts the - following key:</para> + following keys:</para> <variablelist class='network-directives'> <varlistentry> @@ -534,7 +749,7 @@ <varlistentry> <term><varname>MACAddress=</varname></term> <listitem> - <para>The peer MACAddress, if not set it is generated in + <para>The peer MACAddress, if not set, it is generated in the same way as the MAC address of the main interface.</para> </listitem> @@ -570,13 +785,13 @@ <term><varname>PacketInfo=</varname></term> <listitem><para>Takes a boolean argument. Configures whether packets should be prepended with four extra bytes (two flag - bytes and two protocol bytes). If disabled it indicates that + bytes and two protocol bytes). If disabled, it indicates that the packets will be pure IP packets. Defaults to <literal>no</literal>.</para> </listitem> </varlistentry> <varlistentry> - <term><varname>VnetHeader=</varname></term> + <term><varname>VNetHeader=</varname></term> <listitem><para>Takes a boolean argument. Configures IFF_VNET_HDR flag for a tap device. It allows sending and receiving larger Generic Segmentation Offload (GSO) @@ -642,8 +857,7 @@ <literal>layer2</literal>, <literal>layer3+4</literal>, <literal>layer2+3</literal>, - <literal>encap2+3</literal>, - <literal>802.3ad</literal>, and + <literal>encap2+3</literal>, and <literal>encap3+4</literal>. </para> </listitem> @@ -667,7 +881,7 @@ <listitem> <para>Specifies the frequency that Media Independent Interface link monitoring will occur. A value of zero - disables MII link monitoring. This values is rounded down to + disables MII link monitoring. This value is rounded down to the nearest millisecond. The default value is 0.</para> </listitem> </varlistentry> @@ -696,9 +910,9 @@ <term><varname>LearnPacketIntervalSec=</varname></term> <listitem> <para>Specifies the number of seconds between instances where the bonding - driver sends learning packets to each slaves peer switch. - The valid range is 1 - 0x7fffffff; the default value is 1. This Option - has effect only in balance-tlb and balance-alb modes.</para> + driver sends learning packets to each slave peer switch. + The valid range is 1–0x7fffffff; the default value is 1. This option + has an effect only for the balance-tlb and balance-alb modes.</para> </listitem> </varlistentry> @@ -707,8 +921,8 @@ <listitem> <para>Specifies the 802.3ad aggregation selection logic to use. Possible values are <literal>stable</literal>, - <literal>bandwidth</literal>, - <literal>count</literal> + <literal>bandwidth</literal> and + <literal>count</literal>. </para> </listitem> </varlistentry> @@ -716,13 +930,13 @@ <varlistentry> <term><varname>FailOverMACPolicy=</varname></term> <listitem> - <para>Specifies whether active-backup mode should set all slaves to - the same MAC address at enslavement or, when enabled, perform special handling of the + <para>Specifies whether the active-backup mode should set all slaves to + the same MAC address at the time of enslavement or, when enabled, to perform special handling of the bond's MAC address in accordance with the selected policy. The default policy is none. Possible values are <literal>none</literal>, - <literal>active</literal>, - <literal>follow</literal> + <literal>active</literal> and + <literal>follow</literal>. </para> </listitem> </varlistentry> @@ -736,8 +950,8 @@ monitoring purposes. Possible values are <literal>none</literal>, <literal>active</literal>, - <literal>backup</literal>, - <literal>all</literal> + <literal>backup</literal> and + <literal>all</literal>. </para> </listitem> </varlistentry> @@ -757,7 +971,7 @@ <para>Specifies the IP addresses to use as ARP monitoring peers when ARPIntervalSec is greater than 0. These are the targets of the ARP request sent to determine the health of the link to the targets. - Specify these values in ipv4 dotted decimal format. At least one IP + Specify these values in IPv4 dotted decimal format. At least one IP address must be given for ARP monitoring to function. The maximum number of targets that can be specified is 16. The default value is no IP addresses. @@ -772,8 +986,8 @@ in order for the ARP monitor to consider a slave as being up. This option affects only active-backup mode for slaves with ARPValidate enabled. Possible values are - <literal>any</literal>, - <literal>all</literal> + <literal>any</literal> and + <literal>all</literal>. </para> </listitem> </varlistentry> @@ -787,8 +1001,8 @@ occurs. This option is designed to prevent flip-flopping between the primary slave and other slaves. Possible values are <literal>always</literal>, - <literal>better</literal>, - <literal>failure</literal> + <literal>better</literal> and + <literal>failure</literal>. </para> </listitem> </varlistentry> @@ -799,7 +1013,7 @@ <para>Specifies the number of IGMP membership reports to be issued after a failover event. One membership report is issued immediately after the failover, subsequent packets are sent in each 200ms interval. - The valid range is (0 - 255). Defaults to 1. A value of 0 + The valid range is 0–255. Defaults to 1. A value of 0 prevents the IGMP membership report from being issued in response to the failover event. </para> @@ -809,10 +1023,10 @@ <varlistentry> <term><varname>PacketsPerSlave=</varname></term> <listitem> - <para> Specify the number of packets to transmit through a slave before - moving to the next one. When set to 0 then a slave is chosen at - random.The valid range is (0 - 65535). Defaults to 1. This option - has effect only in balance-rr mode. + <para>Specify the number of packets to transmit through a slave before + moving to the next one. When set to 0, then a slave is chosen at + random. The valid range is 0–65535. Defaults to 1. This option + only has effect when in balance-rr mode. </para> </listitem> </varlistentry> @@ -822,11 +1036,11 @@ <listitem> <para>Specify the number of peer notifications (gratuitous ARPs and unsolicited IPv6 Neighbor Advertisements) to be issued after a - failover event. As soon as the link is up on the new slave + failover event. As soon as the link is up on the new slave, a peer notification is sent on the bonding device and each VLAN sub-device. This is repeated at each link monitor interval (ARPIntervalSec or MIIMonitorSec, whichever is active) if the number is - greater than 1. The valid range is (0 - 255). Default value is 1. + greater than 1. The valid range is 0–255. The default value is 1. These options affect only the active-backup mode. </para> </listitem> @@ -835,8 +1049,8 @@ <varlistentry> <term><varname>AllSlavesActive=</varname></term> <listitem> - <para> A boolean. Specifies that duplicate frames (received on inactive ports) - should be dropped false or delivered true. Normally, bonding will drop + <para>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 frames to be delivered. The default value is false (drop duplicate frames @@ -865,7 +1079,7 @@ <refsect1> <title>Example</title> <example> - <title>/etc/systemd/network/bridge.netdev</title> + <title>/etc/systemd/network/25-bridge.netdev</title> <programlisting>[NetDev] Name=bridge0 @@ -873,7 +1087,7 @@ Kind=bridge</programlisting> </example> <example> - <title>/etc/systemd/network/vlan1.netdev</title> + <title>/etc/systemd/network/25-vlan1.netdev</title> <programlisting>[Match] Virtualization=no @@ -886,7 +1100,7 @@ Kind=vlan Id=1</programlisting> </example> <example> - <title>/etc/systemd/network/ipip.netdev</title> + <title>/etc/systemd/network/25-ipip.netdev</title> <programlisting>[NetDev] Name=ipip-tun Kind=ipip @@ -898,7 +1112,7 @@ Remote=192.169.224.239 TTL=64</programlisting> </example> <example> - <title>/etc/systemd/network/tap.netdev</title> + <title>/etc/systemd/network/25-tap.netdev</title> <programlisting>[NetDev] Name=tap-test Kind=tap @@ -908,7 +1122,7 @@ MultiQueue=true PacketInfo=true</programlisting> </example> <example> - <title>/etc/systemd/network/sit.netdev</title> + <title>/etc/systemd/network/25-sit.netdev</title> <programlisting>[NetDev] Name=sit-tun Kind=sit @@ -920,7 +1134,7 @@ Remote=10.65.223.239</programlisting> </example> <example> - <title>/etc/systemd/network/gre.netdev</title> + <title>/etc/systemd/network/25-gre.netdev</title> <programlisting>[NetDev] Name=gre-tun Kind=gre @@ -932,7 +1146,7 @@ Remote=10.65.223.239</programlisting> </example> <example> - <title>/etc/systemd/network/vti.netdev</title> + <title>/etc/systemd/network/25-vti.netdev</title> <programlisting>[NetDev] Name=vti-tun @@ -945,7 +1159,7 @@ Remote=10.65.223.239</programlisting> </example> <example> - <title>/etc/systemd/network/veth.netdev</title> + <title>/etc/systemd/network/25-veth.netdev</title> <programlisting>[NetDev] Name=veth-test Kind=veth @@ -955,13 +1169,36 @@ Name=veth-peer</programlisting> </example> <example> - <title>/etc/systemd/network/dummy.netdev</title> + <title>/etc/systemd/network/25-bond.netdev</title> + <programlisting>[NetDev] +Name=bond1 +Kind=bond + +[Bond] +Mode=802.3ad +TransmitHashPolicy=layer3+4 +MIIMonitorSec=1s +LACPTransmitRate=fast +</programlisting> + </example> + + <example> + <title>/etc/systemd/network/25-dummy.netdev</title> <programlisting>[NetDev] Name=dummy-test Kind=dummy MACAddress=12:34:56:78:9a:bc</programlisting> </example> + <example> + <title>/etc/systemd/network/25-vrf.netdev</title> + <para>Create a VRF interface with table 42.</para> + <programlisting>[NetDev] +Name=vrf-test +Kind=vrf +[VRF] +TableId=42</programlisting> + </example> </refsect1> <refsect1> <title>See Also</title> diff --git a/man/systemd.network.xml b/man/systemd.network.xml index 90a0e8fff6..2fb4907634 100644 --- a/man/systemd.network.xml +++ b/man/systemd.network.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -58,29 +58,41 @@ <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>. </para> - <para>Network files must have the extension - <filename>.network</filename>; other extensions are ignored. - Networks are applied to links whenever the links appear.</para> - - <para>The <filename>.network</filename> files are read from the - files located in the system network directory - <filename>/usr/lib/systemd/network</filename>, the volatile - runtime network directory - <filename>/run/systemd/network</filename> and the local - administration network directory - <filename>/etc/systemd/network</filename>. All configuration files - are collectively sorted and processed in lexical order, regardless - of the directories in which they live. However, files with - identical filenames replace each other. Files in - <filename>/etc</filename> have the highest priority, files in - <filename>/run</filename> take precedence over files with the same - name in <filename>/usr/lib</filename>. This can be used to - override a system-supplied configuration file with a local file if - needed; a symlink in <filename>/etc</filename> with the same name - as a configuration file in <filename>/usr/lib</filename>, pointing - to <filename>/dev/null</filename>, disables the configuration file - entirely.</para> - + <para>The main network file must have the extension <filename>.network</filename>; other + extensions are ignored. Networks are applied to links whenever the links appear.</para> + + <para>The <filename>.network</filename> files are read from the files located in the system + network directory <filename>/usr/lib/systemd/network</filename>, the volatile runtime network + directory <filename>/run/systemd/network</filename> and the local administration network + directory <filename>/etc/systemd/network</filename>. All configuration files are collectively + sorted and processed in lexical order, regardless of the directories in which they live. + However, files with identical filenames replace each other. Files in <filename>/etc</filename> + have the highest priority, files in <filename>/run</filename> take precedence over files with + the same name in <filename>/usr/lib</filename>. This can be used to override a system-supplied + configuration file with a local file if needed. As a special case, an empty file (file size 0) + or symlink with the same name pointing to <filename>/dev/null</filename> disables the + configuration file entirely (it is "masked").</para> + + <para>Along with the network file <filename>foo.network</filename>, a "drop-in" directory + <filename>foo.network.d/</filename> may exist. All files with the suffix + <literal>.conf</literal> from this directory will be parsed after the file itself is + parsed. This is useful to alter or add configuration settings, without having to modify the main + configuration file. Each drop-in file must have appropriate section headers.</para> + + <para>In addition to <filename>/etc/systemd/network</filename>, drop-in <literal>.d</literal> + directories can be placed in <filename>/usr/lib/systemd/network</filename> or + <filename>/run/systemd/network</filename> directories. Drop-in files in + <filename>/etc</filename> take precedence over those in <filename>/run</filename> which in turn + take precedence over those in <filename>/usr/lib</filename>. Drop-in files under any of these + directories take precedence over the main netdev file wherever located. (Of course, since + <filename>/run</filename> is temporary and <filename>/usr/lib</filename> is for vendors, it is + unlikely drop-ins should be used in either of those places.)</para> + + <para>Note that an interface without any static IPv6 addresses configured, and neither DHCPv6 + nor IPv6LL enabled, shall be considered to have no IPv6 support. IPv6 will be automatically + disabled for that interface by writing "1" to + <filename>/proc/sys/net/ipv6/conf/<replaceable>ifname</replaceable>/disable_ipv6</filename>. + </para> </refsect1> <refsect1> @@ -102,7 +114,8 @@ <varlistentry> <term><varname>MACAddress=</varname></term> <listitem> - <para>The hardware address.</para> + <para>The hardware address of the interface (use full colon-delimited hexadecimal, e.g., + 01:23:45:67:89:ab).</para> </listitem> </varlistentry> <varlistentry> @@ -195,7 +208,7 @@ <varlistentry> <term><varname>MACAddress=</varname></term> <listitem> - <para>The hardware address.</para> + <para>The hardware address to set for the device.</para> </listitem> </varlistentry> <varlistentry> @@ -204,6 +217,19 @@ <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.</para> + <para>Note that if IPv6 is enabled on the interface, and the MTU is chosen + below 1280 (the minimum MTU for IPv6) it will automatically be increased to this value.</para> + </listitem> + </varlistentry> + <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> 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 + the network otherwise.</para> </listitem> </varlistentry> </variablelist> @@ -225,21 +251,32 @@ <varlistentry> <term><varname>DHCP=</varname></term> <listitem> - <para>Enables DHCPv4 and/or DHCPv6 support. Accepts + <para>Enables DHCPv4 and/or DHCPv6 client support. Accepts <literal>yes</literal>, <literal>no</literal>, <literal>ipv4</literal>, or <literal>ipv6</literal>.</para> - <para>Please note that by default the domain name + <para>Note that DHCPv6 will by default be triggered by Router + Advertisement, if that is enabled, regardless of this parameter. + By enabling DHCPv6 support explicitly, the DHCPv6 client will + be started regardless of the presence of routers on the link, + or what flags the routers pass. See + <literal>IPv6AcceptRA=</literal>.</para> + + <para>Furthermore, note that by default the domain name specified through DHCP is not used for name resolution. See option <option>UseDomains=</option> below.</para> + + <para>See the <literal>[DHCP]</literal> section below for further configuration options for the DHCP client + support.</para> </listitem> </varlistentry> <varlistentry> <term><varname>DHCPServer=</varname></term> <listitem> - <para>A boolean. Enables a basic DHCPv4 server on the - device. Mostly useful for handing out leases to container - instances.</para> + <para>A boolean. Enables DHCPv4 server support. Defaults + to <literal>no</literal>. Further settings for the DHCP + server may be set in the <literal>[DHCPServer]</literal> + section described below.</para> </listitem> </varlistentry> <varlistentry> @@ -264,34 +301,117 @@ <term><varname>IPv6Token=</varname></term> <listitem> <para>An IPv6 address with the top 64 bits unset. When set, indicates the - 64 bits interface part of SLAAC IPv6 addresses for this link. By default - it is autogenerated.</para> + 64-bit interface part of SLAAC IPv6 addresses for this link. Note that + the token is only ever used for SLAAC, and not for DHCPv6 addresses, even + in the case DHCP is requested by router advertisement. By default, the + token is autogenerated.</para> </listitem> </varlistentry> <varlistentry> <term><varname>LLMNR=</varname></term> <listitem> - <para>A boolean or <literal>resolve</literal>. When true, enables - Link-Local Multicast Name Resolution on the link, when set to - <literal>resolve</literal> only resolution is enabled, but not - announcement. Defaults to true.</para> + <para>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 + <literal>resolve</literal>, only resolution is enabled, + but not host registration and announcement. Defaults to + true. This setting is read by + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MulticastDNS=</varname></term> + <listitem> + <para>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 + <literal>resolve</literal>, only resolution is enabled, + but not host or service registration and + announcement. Defaults to false. This setting is read by + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>DNSSEC=</varname></term> + <listitem> + <para>A boolean or + <literal>allow-downgrade</literal>. When true, enables + <ulink + url="https://tools.ietf.org/html/rfc4033">DNSSEC</ulink> + DNS validation support on the link. When set to + <literal>allow-downgrade</literal>, compatibility with + non-DNSSEC capable networks is increased, by automatically + turning off DNSEC in this case. This option defines a + per-interface setting for + <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>'s + global <varname>DNSSEC=</varname> option. Defaults to + false. This setting is read by + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>DNSSECNegativeTrustAnchors=</varname></term> + <listitem><para>A space-separated list of DNSSEC negative + trust anchor domains. If specified and DNSSEC is enabled, + look-ups done via the interface's DNS server will be subject + to the list of negative trust anchors, and not require + authentication for the specified domains, or anything below + it. Use this to disable DNSSEC authentication for specific + private domains, that cannot be proven valid using the + Internet DNS hierarchy. Defaults to the empty list. This + setting is read by + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> </listitem> </varlistentry> <varlistentry> <term><varname>LLDP=</varname></term> <listitem> - <para>A boolean. When true, enables LLDP link receive support. + <para>Controls support for Ethernet LLDP packet reception. LLDP is a link-layer protocol commonly + implemented on professional routers and bridges which announces which physical port a system is connected + to, as well as other related data. Accepts a boolean or the special value + <literal>routers-only</literal>. When true, incoming LLDP packets are accepted and a database of all LLDP + neighbors maintained. If <literal>routers-only</literal> is set only LLDP data of various types of routers + is collected and LLDP data about other types of devices ignored (such as stations, telephones and + others). If false, LLDP reception is disabled. Defaults to <literal>routers-only</literal>. Use + <citerefentry><refentrytitle>networkctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> to query the + collected neighbor data. LLDP is only available on Ethernet links. See <varname>EmitLLDP=</varname> below + for enabling LLDP packet emission from the local system. </para> </listitem> </varlistentry> <varlistentry> + <term><varname>EmitLLDP=</varname></term> + <listitem> + <para>Controls support for Ethernet LLDP packet emission. Accepts a boolean parameter or the special values + <literal>nearest-bridge</literal>, <literal>non-tpmr-bridge</literal> and + <literal>customer-bridge</literal>. Defaults to false, which turns off LLDP packet emission. If not false, + a short LLDP packet with information about the local system is sent out in regular intervals on the + link. The LLDP packet will contain information about the local host name, the local machine ID (as stored + in <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>) and the + local interface name, as well as the pretty hostname of the system (as set in + <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>). LLDP + emission is only available on Ethernet links. Note that this setting passes data suitable for + identification of host to the network and should thus not be enabled on untrusted networks, where such + identification data should not be made available. Use this option to permit other systems to identify on + which interfaces they are connected to this system. The three special values control propagation of the + LLDP packets. The <literal>nearest-bridge</literal> setting permits propagation only to the nearest + connected bridge, <literal>non-tpmr-bridge</literal> permits propagation across Two-Port MAC Relays, but + not any other bridges, and <literal>customer-bridge</literal> permits propagation until a customer bridge + is reached. For details about these concepts, see <ulink + url="http://standards.ieee.org/getieee802/download/802.1AB-2009.pdf">IEEE 802.1AB-2009</ulink>. Note that + configuring this setting to true is equivalent to <literal>nearest-bridge</literal>, the recommended and + most restricted level of propagation. See <varname>LLDP=</varname> above for an option to enable LLDP + reception.</para> + </listitem> + </varlistentry> + <varlistentry> <term><varname>BindCarrier=</varname></term> <listitem> - <para>A port or a list of ports. When set, controls the - behaviour of the current interface. When all ports in the list - are in an operational down state, the current interface is brought - down. When at least one port has carrier, the current interface - is brought up. + <para>A link name or a list of link names. When set, controls the behavior of the current + link. When all links in the list are in an operational down state, the current link is brought + down. When at least one link has carrier, the current interface is brought up. </para> </listitem> </varlistentry> @@ -340,52 +460,77 @@ <para>A DNS server address, which must be in the format described in <citerefentry project='man-pages'><refentrytitle>inet_pton</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - This option may be specified more than once.</para> + This option may be specified more than once. This setting is read by + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> </listitem> </varlistentry> <varlistentry> <term><varname>Domains=</varname></term> <listitem> - <para>The domains used for DNS resolution over this link.</para> + <para>A list of domains which should be resolved using the DNS servers on this link. Each item in the list + should be a domain name, optionally prefixed with a tilde (<literal>~</literal>). The domains with the + prefix are called "routing-only domains". The domains without the prefix are called "search domains" and + are first used as search suffixes for extending single-label host names (host names containing no dots) to + become fully qualified domain names (FQDNs). If a single-label host name is resolved on this interface, + each of the specified search domains are appended to it in turn, converting it into a fully qualified + domain name, until one of them may be successfully resolved.</para> + + <para>Both "search" and "routing-only" domains are used for routing of DNS queries: look-ups for host names + ending in those domains (hence also single label names, if any "search domains" are listed), are routed to + the DNS servers configured for this interface. The domain routing logic is particularly useful on + multi-homed hosts with DNS servers serving particular private DNS zones on each interface.</para> + + <para>The "routing-only" domain <literal>~.</literal> (the tilde indicating definition of a routing domain, + the dot referring to the DNS root domain which is the implied suffix of all valid DNS names) has special + effect. It causes all DNS traffic which does not match another configured domain routing entry to be routed + to DNS servers specified for this interface. This setting is useful to prefer a certain set of DNS servers + if a link on which they are connected is available.</para> + + <para>This setting is read by + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + "Search domains" correspond to the <varname>domain</varname> and <varname>search</varname> entries in + <citerefentry><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + Domain name routing has no equivalent in the traditional glibc API, which has no concept of domain + name servers limited to a specific link.</para> </listitem> </varlistentry> <varlistentry> <term><varname>NTP=</varname></term> <listitem> - <para>An NTP server address. This option may be specified more than once.</para> + <para>An NTP server address. This option may be specified more than once. This setting is read by + <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> </listitem> </varlistentry> <varlistentry> <term><varname>IPForward=</varname></term> - <listitem><para>Configures IP forwarding for the network - interface. If enabled incoming packets on the network - interface will be forwarded to other interfaces according to - the routing table. Takes either a boolean argument, or the - values <literal>ipv4</literal> or <literal>ipv6</literal>, - which only enables IP forwarding for the specified address - family, or <literal>kernel</literal>, which preserves existing sysctl settings. - This controls the - <filename>net.ipv4.conf.<interface>.forwarding</filename> - and - <filename>net.ipv6.conf.<interface>.forwarding</filename> - sysctl options of the network interface (see <ulink + <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 + <literal>ipv6</literal>, which only enable IP packet + forwarding for the specified address family. This controls + the <filename>net.ipv4.ip_forward</filename> and + <filename>net.ipv6.conf.all.forwarding</filename> sysctl + options of the network interface (see <ulink url="https://www.kernel.org/doc/Documentation/networking/ip-sysctl.txt">ip-sysctl.txt</ulink> for details about sysctl options). Defaults to <literal>no</literal>.</para> - <para>Note: unless this option is turned on, or set to <literal>kernel</literal>, - no IP forwarding is done on this interface, even if this is - globally turned on in the kernel, with the - <filename>net.ipv4.ip_forward</filename>, - <filename>net.ipv4.conf.all.forwarding</filename>, and - <filename>net.ipv6.conf.all.forwarding</filename> sysctl - options.</para> + <para>Note: this setting controls a global kernel option, + and does so one way only: if a network that has this setting + enabled is set up the global setting is turned on. However, + it is never turned off again, even after all networks with + this setting enabled are shut down again.</para> + + <para>To allow IP packet forwarding only between specific + network interfaces use a firewall.</para> </listitem> </varlistentry> <varlistentry> <term><varname>IPMasquerade=</varname></term> <listitem><para>Configures IP masquerading for the network - interface. If enabled packets forwarded from the network + interface. If enabled, packets forwarded from the network interface will be appear as coming from the local host. Takes a boolean argument. Implies <varname>IPForward=ipv4</varname>. Defaults to @@ -399,16 +544,56 @@ Privacy Extensions for Stateless Address Autoconfiguration in IPv6). Takes a boolean or the special values <literal>prefer-public</literal> and - <literal>kernel</literal>. When true enables the privacy + <literal>kernel</literal>. When true, enables the privacy extensions and prefers temporary addresses over public - addresses. When <literal>prefer-public</literal> enables the + addresses. When <literal>prefer-public</literal>, enables the privacy extensions, but prefers public addresses over temporary addresses. When false, the privacy extensions - remain disabled. When <literal>kernel</literal> the kernel's + remain disabled. When <literal>kernel</literal>, the kernel's default setting will be left in place. Defaults to <literal>no</literal>.</para></listitem> </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 + 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> + + <para>Further settings for the IPv6 RA support may be configured in the + <literal>[IPv6AcceptRA]</literal> section, see below.</para> + + <para>Also see <ulink + url="https://www.kernel.org/doc/Documentation/networking/ip-sysctl.txt">ip-sysctl.txt</ulink> in the kernel + documentation regarding <literal>accept_ra</literal>, but note that systemd's setting of + <constant>1</constant> (i.e. true) corresponds to kernel's setting of <constant>2</constant>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>IPv6DuplicateAddressDetection=</varname></term> + <listitem><para>Configures the amount of IPv6 Duplicate + Address Detection (DAD) probes to send. Defaults to unset. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>IPv6HopLimit=</varname></term> + <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. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>ProxyARP=</varname></term> + <listitem><para>A boolean. Configures proxy ARP. 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. + </para></listitem> + </varlistentry> + <varlistentry> <term><varname>Bridge=</varname></term> <listitem> <para>The name of the bridge to add the link to.</para> @@ -421,6 +606,12 @@ </listitem> </varlistentry> <varlistentry> + <term><varname>VRF=</varname></term> + <listitem> + <para>The name of the VRF to add the link to.</para> + </listitem> + </varlistentry> + <varlistentry> <term><varname>VLAN=</varname></term> <listitem> <para>The name of a VLAN to create on the link. This @@ -492,6 +683,69 @@ <para>An address label.</para> </listitem> </varlistentry> + <varlistentry> + <term><varname>PreferredLifetime=</varname></term> + <listitem> + <para>Allows the default "preferred lifetime" of the address to be overridden. + Only three settings are accepted: <literal>forever</literal> or <literal>infinity</literal> + which is the default and means that the address never expires, and <literal>0</literal> which means + that the address is considered immediately "expired" and will not be used, + unless explicitly requested. A setting of PreferredLifetime=0 is useful for + addresses which are added to be used only by a specific application, + which is then configured to use them explicitly.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>HomeAddress=</varname></term> + <listitem> + <para>Takes a boolean argument. 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> + </varlistentry> + <varlistentry> + <term><varname>DuplicateAddressDetection=</varname></term> + <listitem> + <para>Takes a boolean argument. 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> + </varlistentry> + <varlistentry> + <term><varname>ManageTemporaryAddress=</varname></term> + <listitem> + <para>Takes a boolean argument. 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. + The given address needs to have a prefix length of 64. This flag allows to use privacy + extensions in a manually configured network, just like if stateless auto-configuration + was active. Defaults to false. </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>PrefixRoute=</varname></term> + <listitem> + <para>Takes a boolean argument. 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> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>AutoJoin=</varname></term> + <listitem> + <para>Takes a boolean argument. 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 + <command>ip link add vxlan</command> or networkd's netdev kind vxlan have the group option + that enables then to do the required join. By extending ip address command with option + <literal>autojoin</literal> we can get similar functionality for openvswitch (OVS) vxlan + interfaces as well as other tunneling mechanisms that need to receive multicast traffic. + Defaults to <literal>no</literal>.</para> + </listitem> + </varlistentry> </variablelist> </refsect1> @@ -512,7 +766,7 @@ <term><varname>Destination=</varname></term> <listitem> <para>The destination prefix of the route. Possibly - followed by a slash and the prefixlength. If omitted, a + followed by a slash and the prefix length. If omitted, a full-length host route is assumed.</para> </listitem> </varlistentry> @@ -520,30 +774,48 @@ <term><varname>Source=</varname></term> <listitem> <para>The source prefix of the route. Possibly followed by - a slash and the prefixlength. If omitted, a full-length + a slash and the prefix length. If omitted, a full-length host route is assumed.</para> </listitem> </varlistentry> <varlistentry> <term><varname>Metric=</varname></term> <listitem> - <para>The metric of the route. An unsigned integer</para> + <para>The metric of the route (an unsigned integer).</para> </listitem> </varlistentry> <varlistentry> <term><varname>Scope=</varname></term> <listitem> - <para>The scope of the route. One of the values <literal>global</literal>, + <para>The scope of the route, which can be <literal>global</literal>, <literal>link</literal> or <literal>host</literal>. Defaults to <literal>global</literal>.</para> </listitem> </varlistentry> + <varlistentry> + <term><varname>PreferredSource=</varname></term> + <listitem> + <para>The preferred source address of the route. The address + must be in the format described in + <citerefentry project='man-pages'><refentrytitle>inet_pton</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Table=<replaceable>num</replaceable></varname></term> + <listitem> + <para>The table identifier for the route (a number between 1 and 4294967295, or 0 to unset). + The table can be retrieved using <command>ip route show table <replaceable>num</replaceable></command>. + </para> + </listitem> + </varlistentry> </variablelist> </refsect1> <refsect1> <title>[DHCP] Section Options</title> - <para>The <literal>[DHCP]</literal> section accepts the following keys:</para> + <para>The <literal>[DHCP]</literal> section configures the + DHCPv4 and DHCP6 client, if it is enabled with the + <varname>DHCP=</varname> setting described above:</para> <variablelist class='network-directives'> <varlistentry> @@ -554,7 +826,8 @@ any statically configured ones.</para> <para>This corresponds to the <option>nameserver</option> - option in <citerefentry project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + option in <citerefentry + project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> </listitem> </varlistentry> <varlistentry> @@ -576,36 +849,42 @@ <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.</para> </listitem> </varlistentry> <varlistentry> <term><varname>UseHostname=</varname></term> <listitem> <para>When true (the default), the hostname received from - the DHCP server will be used as the transient - hostname.</para> + the DHCP server will be set as the transient hostname of the system + </para> </listitem> </varlistentry> <varlistentry> <term><varname>Hostname=</varname></term> <listitem> - <para>Hostname is a option to override the machine's hostname that will be sent to the DHCP server</para> + <para>Use this value for the hostname which is sent to the + DHCP server, instead of machine's hostname.</para> </listitem> </varlistentry> <varlistentry> <term><varname>UseDomains=</varname></term> <listitem> - <para>When true (not the default), the domain name - received from the DHCP server will be used for DNS - resolution over this link. When a name cannot be resolved - as specified, the domain name will be used a suffix and - name resolution of that will be attempted.</para> + <para>Takes a boolean argument, 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 + the <option>Domains=</option> setting when the argument is prefixed with <literal>~</literal>. Defaults to + false.</para> - <para>This corresponds to the <option>domain</option> - option in <citerefentry project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - and should not be enabled on untrusted networks.</para> + <para>It is recommended to enable this option only on trusted networks, as setting this affects resolution + of all host names, in particular of single-label names. It is generally safer to use the supplied domain + only as routing domain, rather than as search domain, in order to not have it affect local resolution of + single-label names.</para> + + <para>When set to true, this setting corresponds to the <option>domain</option> option in <citerefentry + project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> </listitem> </varlistentry> <varlistentry> @@ -613,9 +892,18 @@ <listitem> <para>When true (the default), the static routes will be requested from the DHCP server and added to the routing - table with metric of 1024.</para> + table with a metric of 1024.</para> </listitem> </varlistentry> + + <varlistentry> + <term><varname>UseTimezone=</varname></term> + + <listitem><para>When true, the timezone received from the + DHCP server will be set as timezone of the local + system. Defaults to <literal>no</literal>.</para></listitem> + </varlistentry> + <varlistentry> <term><varname>CriticalConnection=</varname></term> <listitem> @@ -626,14 +914,15 @@ false.</para> </listitem> </varlistentry> + <varlistentry> <term><varname>ClientIdentifier=</varname></term> <listitem> - <para>DHCP client identifier to use. Either <literal>mac</literal> - to use the MAC address of the link or <literal>duid</literal> - (the default) to use a RFC4361-compliant Client ID.</para> + <para>The DHCPv4 client identifier to use. Either <literal>mac</literal> to use the MAC address of the link + or <literal>duid</literal> (the default, see below) to use an RFC4361-compliant Client ID.</para> </listitem> </varlistentry> + <varlistentry> <term><varname>VendorClassIdentifier=</varname></term> <listitem> @@ -641,6 +930,32 @@ type and configuration.</para> </listitem> </varlistentry> + + <varlistentry> + <term><varname>DUIDType=</varname></term> + <listitem> + <para>Override the global <varname>DUIDType</varname> setting for this network. See + <citerefentry><refentrytitle>networkd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for a description of possible values.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>DUIDRawData=</varname></term> + <listitem> + <para>Override the global <varname>DUIDRawData</varname> setting for this network. See + <citerefentry><refentrytitle>networkd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for a description of possible values.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>IAID=</varname></term> + <listitem> + <para>The DHCP Identity Association Identifier (IAID) for the interface, a 32-bit unsigned integer.</para> + </listitem> + </varlistentry> + <varlistentry> <term><varname>RequestBroadcast=</varname></term> <listitem> @@ -652,6 +967,7 @@ networks where broadcasts are filtered out.</para> </listitem> </varlistentry> + <varlistentry> <term><varname>RouteMetric=</varname></term> <listitem> @@ -659,8 +975,180 @@ DHCP server.</para> </listitem> </varlistentry> - </variablelist> + <varlistentry> + <term><varname>RouteTable=<replaceable>num</replaceable></varname></term> + <listitem> + <para>The table identifier for DHCP routes (a number between 1 and 4294967295, or 0 to unset). + The table can be retrieved using <command>ip route show table <replaceable>num</replaceable></command>. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>[IPv6AcceptRA] Section Options</title> + <para>The <literal>[IPv6AcceptRA]</literal> section configures the IPv6 Router Advertisement + (RA) client, if it is enabled with the <varname>IPv6AcceptRA=</varname> setting described + above:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>UseDNS=</varname></term> + <listitem> + <para>When true (the default), the DNS servers received in the Router Advertisement will be used and take + precedence over any statically configured ones.</para> + + <para>This corresponds to the <option>nameserver</option> option in <citerefentry + project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</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 + 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 + effect of the <option>Domains=</option> setting when the argument is prefixed with + <literal>~</literal>. Defaults to false.</para> + + <para>It is recommended to enable this option only on trusted networks, as setting this affects resolution + of all host names, in particular of single-label names. It is generally safer to use the supplied domain + only as routing domain, rather than as search domain, in order to not have it affect local resolution of + single-label names.</para> + + <para>When set to true, this setting corresponds to the <option>domain</option> option in <citerefentry + project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>RouteTable=<replaceable>num</replaceable></varname></term> + <listitem> + <para>The table identifier for the routes received in the Router Advertisement + (a number between 1 and 4294967295, or 0 to unset). + The table can be retrieved using <command>ip route show table <replaceable>num</replaceable></command>. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + + <refsect1> + <title>[DHCPServer] Section Options</title> + <para>The <literal>[DHCPServer]</literal> section contains + settings for the DHCP server, if enabled via the + <varname>DHCPServer=</varname> option described above:</para> + + <variablelist class='network-directives'> + + <varlistentry> + <term><varname>PoolOffset=</varname></term> + <term><varname>PoolSize=</varname></term> + + <listitem><para>Configures the pool of addresses to hand out. The pool + is a contiguous sequence of IP addresses in the subnet configured for + the server address, which does not include the subnet nor the broadcast + address. <varname>PoolOffset=</varname> takes the offset of the pool + from the start of subnet, or zero to use the default value. + <varname>PoolSize=</varname> takes the number of IP addresses in the + pool or zero to use the default value. By default, the pool starts at + the first address after the subnet address and takes up the rest of + the subnet, excluding the broadcast address. If the pool includes + the server address (the default), this is reserved and not handed + out to clients.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultLeaseTimeSec=</varname></term> + <term><varname>MaxLeaseTimeSec=</varname></term> + + <listitem><para>Control the default and maximum DHCP lease + time to pass to clients. These settings take time values in seconds or + another common time unit, depending on the suffix. The default + lease time is used for clients that did not ask for a specific + lease time. If a client asks for a lease time longer than the + maximum lease time, it is automatically shortened to the + specified time. The default lease time defaults to 1h, the + maximum lease time to 12h. Shorter lease times are beneficial + if the configuration data in DHCP leases changes frequently + and clients shall learn the new settings with shorter + latencies. Longer lease times reduce the generated DHCP + network traffic.</para></listitem> + </varlistentry> + + <varlistentry> + <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 + <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 + automatically propagated from an "uplink" interface that has + appropriate servers set. The "uplink" interface is determined + by the default route of the system with the highest + priority. Note that this information is acquired at the time + the lease is handed out, and does not take uplink interfaces + into account that acquire DNS or NTP server information at a + later point. DNS server propagation does not take + <filename>/etc/resolv.conf</filename> into account. Also, note + that the leases are not refreshed if the uplink network + configuration changes. To ensure clients regularly acquire the + most current uplink DNS server information, it is thus + advisable to shorten the DHCP lease time via + <varname>MaxLeaseTimeSec=</varname> described + above.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>EmitNTP=</varname></term> + <term><varname>NTP=</varname></term> + + <listitem><para>Similar to the <varname>EmitDNS=</varname> and + <varname>DNS=</varname> settings described above, these + settings configure whether and what NTP server information + shall be emitted as part of the DHCP lease. The same syntax, + propagation semantics and defaults apply as for + <varname>EmitDNS=</varname> and + <varname>DNS=</varname>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>EmitRouter=</varname></term> + + <listitem><para>Similar to the <varname>EmitDNS=</varname> + setting described above, this setting configures whether the + DHCP lease should contain the router option. The same syntax, + propagation semantics and defaults apply as for + <varname>EmitDNS=</varname>.</para></listitem> + </varlistentry> + + <varlistentry> + <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 + <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 + timezone is set, the system timezone of the local host is + propagated, as determined by the + <filename>/etc/localtime</filename> symlink.</para></listitem> + </varlistentry> + + </variablelist> </refsect1> <refsect1> @@ -669,16 +1157,57 @@ following keys.</para> <variablelist class='network-directives'> <varlistentry> + <term><varname>UnicastFlood=</varname></term> + <listitem> + <para>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 on. + </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. By default, this + flag is false, and the bridge will not forward traffic back + out of the receiving port.</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 yes.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>FastLeave=</varname></term> + <listitem> + <para>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 off.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>AllowPortToBeRoot=</varname></term> + <listitem> + <para>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 on.</para> + </listitem> + </varlistentry> + <varlistentry> <term><varname>Cost=</varname></term> <listitem> - <para>Each port in a bridge may have different speed. Cost + <para>Sets the "cost" of sending packets of this interface. + Each port in a bridge may have a different speed and the cost is used to decide which link to use. Faster interfaces - should have lower costs</para> + should have lower costs.</para> </listitem> </varlistentry> </variablelist> </refsect1> - <refsect1> <title>[BridgeFDB] Section Options</title> <para>The <literal>[BridgeFDB]</literal> section manages the @@ -697,13 +1226,46 @@ <varlistentry> <term><varname>VLANId=</varname></term> <listitem> - <para>The VLAN Id for the new static MAC table entry. If - omitted, no VLAN Id info is appended to the new static MAC + <para>The VLAN ID for the new static MAC table entry. If + omitted, no VLAN ID info is appended to the new static MAC table entry.</para> </listitem> </varlistentry> </variablelist> </refsect1> + <refsect1> + <title>[BridgeVLAN] Section Options</title> + <para>The <literal>[BridgeVLAN]</literal> section manages the VLAN ID configuration of a bridge port and accepts + the following keys. Specify several <literal>[BridgeVLAN]</literal> sections to configure several VLAN entries. + The <varname>VLANFiltering=</varname> option has to be enabled, see <literal>[Bridge]</literal> section in + <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>VLAN=</varname></term> + <listitem> + <para>The VLAN ID allowed on the port. This can be either a single ID or a range M-N. VLAN IDs are valid + from 1 to 4094.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>EgressUntagged=</varname></term> + <listitem> + <para>The VLAN ID specified here will be used to untag frames on egress. Configuring + <varname>EgressUntagged=</varname> implicates the use of <varname>VLAN=</varname> above and will enable the + VLAN ID for ingress as well. This can be either a single ID or a range M-N.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>PVID=</varname></term> + <listitem> + <para>The Port VLAN ID specified here is assigned to all untagged frames at ingress. + <varname>PVID=</varname> can be used only once. Configuring <varname>PVID=</varname> implicates the use of + <varname>VLAN=</varname> above and will enable the VLAN ID for ingress as well.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> <refsect1> <title>Example</title> @@ -729,7 +1291,7 @@ DHCP=yes</programlisting> </example> <example> - <title>/etc/systemd/network/bridge-static.network</title> + <title>/etc/systemd/network/25-bridge-static.network</title> <programlisting>[Match] Name=bridge0 @@ -741,7 +1303,7 @@ DNS=192.168.0.1</programlisting> </example> <example> - <title>/etc/systemd/network/bridge-slave-interface.network</title> + <title>/etc/systemd/network/25-bridge-slave-interface.network</title> <programlisting>[Match] Name=enp2s0 @@ -750,7 +1312,27 @@ Name=enp2s0 Bridge=bridge0</programlisting> </example> <example> - <title>/etc/systemd/network/ipip.network</title> + <title>/etc/systemd/network/25-bridge-slave-interface-vlan.network</title> + + <programlisting>[Match] +Name=enp2s0 + +[Network] +Bridge=bridge0 + +[BridgeVLAN] +VLAN=1-32 +PVID=42 +EgressUntagged=42 + +[BridgeVLAN] +VLAN=100-200 + +[BridgeVLAN] +EgressUntagged=300-400</programlisting> + </example> + <example> + <title>/etc/systemd/network/25-ipip.network</title> <programlisting>[Match] Name=em1 @@ -760,7 +1342,7 @@ Tunnel=ipip-tun</programlisting> </example> <example> - <title>/etc/systemd/network/sit.network</title> + <title>/etc/systemd/network/25-sit.network</title> <programlisting>[Match] Name=em1 @@ -770,7 +1352,7 @@ Tunnel=sit-tun</programlisting> </example> <example> - <title>/etc/systemd/network/gre.network</title> + <title>/etc/systemd/network/25-gre.network</title> <programlisting>[Match] Name=em1 @@ -780,7 +1362,7 @@ Tunnel=gre-tun</programlisting> </example> <example> - <title>/etc/systemd/network/vti.network</title> + <title>/etc/systemd/network/25-vti.network</title> <programlisting>[Match] Name=em1 @@ -788,15 +1370,39 @@ Name=em1 [Network] Tunnel=vti-tun</programlisting> </example> + + <example> + <title>/etc/systemd/network/25-bond.network</title> + + <programlisting>[Match] +Name=bond1 + +[Network] +DHCP=yes +</programlisting> + </example> + + <example> + <title>/etc/systemd/network/25-vrf.network</title> + <para>Add the bond1 interface to the VRF master interface vrf-test. This will redirect routes generated on this interface to be within the routing table defined during VRF creation. Traffic won't be redirected towards the VRFs routing table unless specific ip-rules are added.</para> + <programlisting>[Match] +Name=bond1 + +[Network] +VRF=vrf-test +</programlisting> + </example> + </refsect1> <refsect1> <title>See Also</title> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> + <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/systemd.nspawn.xml b/man/systemd.nspawn.xml new file mode 100644 index 0000000000..b1344d6c10 --- /dev/null +++ b/man/systemd.nspawn.xml @@ -0,0 +1,463 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!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" > +%entities; +]> + +<!-- + This file is part of systemd. + + Copyright 2015 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.nspawn"> + + <refentryinfo> + <title>systemd.nspawn</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.nspawn</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.nspawn</refname> + <refpurpose>Container settings</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/systemd/nspawn/<replaceable>machine</replaceable>.nspawn</filename></para> + <para><filename>/run/systemd/nspawn/<replaceable>machine</replaceable>.nspawn</filename></para> + <para><filename>/var/lib/machines/<replaceable>machine</replaceable>.nspawn</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>An nspawn container settings file (suffix + <filename>.nspawn</filename>) encodes additional runtime + information about a local container, and is searched, read and + used by + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + when starting a container. Files of this type are named after the + containers they define settings for. They are optional, and only + required for containers whose execution environment shall differ + from the defaults. Files of this type mostly contain settings that + may also be set on the <command>systemd-nspawn</command> command + line, and make it easier to persistently attach specific settings + to specific containers. The syntax of these files is inspired by + <filename>.desktop</filename> files following the <ulink + url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG + Desktop Entry Specification</ulink>, which in turn are inspired by + Microsoft Windows <filename>.ini</filename> files.</para> + + <para>Boolean arguments used in these settings 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>Empty lines and lines starting with # or ; are + ignored. This may be used for commenting. Lines ending + in a backslash are concatenated with the following + line while reading and the backslash is replaced by a + space character. This may be used to wrap long lines.</para> + + </refsect1> + + <refsect1> + <title><filename>.nspawn</filename> File Discovery</title> + + <para>Files are searched by appending the + <filename>.nspawn</filename> suffix to the machine name of the + container, as specified with the <option>--machine=</option> + switch of <command>systemd-nspawn</command>, or derived from the + directory or image file name. This file is first searched in + <filename>/etc/systemd/nspawn/</filename> and + <filename>/run/systemd/nspawn/</filename>. If found in these + directories, its settings are read and all of them take full effect + (but are possibly overridden by corresponding command line + arguments). If not found, the file will then be searched next to + the image file or in the immediate parent of the root directory of + the container. If the file is found there, only a subset of the + settings will take effect however. All settings that possibly + elevate privileges or grant additional access to resources of the + host (such as files or directories) are ignored. To which options + this applies is documented below.</para> + + <para>Persistent settings files created and maintained by the + administrator (and thus trusted) should be placed in + <filename>/etc/systemd/nspawn/</filename>, while automatically + downloaded (and thus potentially untrusted) settings files are + placed in <filename>/var/lib/machines/</filename> instead (next to + the container images), where their security impact is limited. In + order to add privileged settings to <filename>.nspawn</filename> + files acquired from the image vendor, it is recommended to copy the + settings files into <filename>/etc/systemd/nspawn/</filename> and + edit them there, so that the privileged options become + available. The precise algorithm for how the files are searched and + interpreted may be configured with + <command>systemd-nspawn</command>'s <option>--settings=</option> + switch, see + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for details.</para> + </refsect1> + + <refsect1> + <title>[Exec] Section Options</title> + + <para>Settings files may include an <literal>[Exec]</literal> + section, which carries various execution parameters:</para> + + <variablelist> + + <varlistentry> + <term><varname>Boot=</varname></term> + + <listitem><para>Takes a boolean argument, which defaults to off. If enabled, <command>systemd-nspawn</command> + will automatically search for an <filename>init</filename> executable and invoke it. In this case, the + specified parameters using <varname>Parameters=</varname> are passed as additional arguments to the + <filename>init</filename> process. This setting corresponds to the <option>--boot</option> switch on the + <command>systemd-nspawn</command> command line. This option may not be combined with + <varname>ProcessTwo=yes</varname>. This option is the default if the + <filename>systemd-nspawn@.service</filename> template unit file is used.</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 + PID 2. A stub init process is run as PID 1. This setting corresponds to the <option>--as-pid2</option> switch + on the <command>systemd-nspawn</command> command line. This option may not be combined with + <varname>Boot=yes</varname>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Parameters=</varname></term> + + <listitem><para>Takes a space-separated list of + arguments. This is either a command line, beginning with the + binary name to execute, or – if <varname>Boot=</varname> is + enabled – the list of arguments to pass to the init + process. This setting corresponds to the command line + parameters passed on the <command>systemd-nspawn</command> + command line.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Environment=</varname></term> + + <listitem><para>Takes an environment variable assignment + consisting of key and value, separated by + <literal>=</literal>. Sets an environment variable for the + main process invoked in the container. This setting may be + used multiple times to set multiple environment variables. It + corresponds to the <option>--setenv=</option> command line + switch.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>User=</varname></term> + + <listitem><para>Takes a UNIX user name. Specifies the user + name to invoke the main process of the container as. This user + must be known in the container's user database. This + corresponds to the <option>--user=</option> command line + switch.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>WorkingDirectory=</varname></term> + + <listitem><para>Selects the working directory for the process invoked in the container. Expects an absolute + path in the container's file system namespace. This corresponds to the <option>--chdir=</option> command line + switch.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Capability=</varname></term> + <term><varname>DropCapability=</varname></term> + + <listitem><para>Takes a space-separated list of Linux process + capabilities (see + <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details). The <varname>Capability=</varname> setting + specifies additional capabilities to pass on top of the + default set of capabilities. The + <varname>DropCapability=</varname> setting specifies + capabilities to drop from the default set. These settings + correspond to the <option>--capability=</option> and + <option>--drop-capability=</option> command line + switches. Note that <varname>Capability=</varname> is a + privileged setting, and only takes effect in + <filename>.nspawn</filename> files in + <filename>/etc/systemd/nspawn/</filename> and + <filename>/run/system/nspawn/</filename> (see above). On the + other hand, <varname>DropCapability=</varname> takes effect in + all cases.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>KillSignal=</varname></term> + + <listitem><para>Specify the process signal to send to the + container's PID 1 when nspawn itself receives SIGTERM, in + order to trigger an orderly shutdown of the container. + Defaults to SIGRTMIN+3 if <option>Boot=</option> is used + (on systemd-compatible init systems SIGRTMIN+3 triggers an + orderly shutdown). For a list of valid signals, see + <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Personality=</varname></term> + + <listitem><para>Configures the kernel personality for the + container. This is equivalent to the + <option>--personality=</option> switch.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>MachineID=</varname></term> + + <listitem><para>Configures the 128-bit machine ID (UUID) to pass to + the container. This is equivalent to the + <option>--uuid=</option> command line switch. This option is + privileged (see above). </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PrivateUsers=</varname></term> + + <listitem><para>Configures support for usernamespacing. This is equivalent to the + <option>--private-users=</option> command line switch, and takes the same options. This option is privileged + (see above). This option is the default if the <filename>systemd-nspawn@.service</filename> template unit file + is used.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>NotifyReady=</varname></term> + + <listitem><para>Configures support for notifications from the container's init process. + This is equivalent to use <option>--notify-ready=</option> command line switch, + and takes the same options. See <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for details about the specific options supported.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>[Files] Section Options</title> + + <para>Settings files may include a <literal>[Files]</literal> + section, which carries various parameters configuring the file + system of the container:</para> + + <variablelist> + + <varlistentry> + <term><varname>ReadOnly=</varname></term> + + <listitem><para>Takes a boolean argument, which defaults to off. If + specified, the container will be run with a read-only file + system. This setting corresponds to the + <option>--read-only</option> command line + switch.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Volatile=</varname></term> + + <listitem><para>Takes a boolean argument, or the special value + <literal>state</literal>. This configures whether to run the + container with volatile state and/or configuration. This + option is equivalent to <option>--volatile=</option>, see + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for details about the specific options + supported.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Bind=</varname></term> + <term><varname>BindReadOnly=</varname></term> + + <listitem><para>Adds a bind mount from the host into the + container. Takes a single path, a pair of two paths separated + by a colon, or a triplet of two paths plus an option string + separated by colons. This option may be used multiple times to + configure multiple bind mounts. This option is equivalent to + the command line switches <option>--bind=</option> and + <option>--bind-ro=</option>, see + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for details about the specific options supported. This setting + is privileged (see above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TemporaryFileSystem=</varname></term> + + <listitem><para>Adds a <literal>tmpfs</literal> mount to the + container. Takes a path or a pair of path and option string, + separated by a colon. This option may be used multiple times to + configure multiple <literal>tmpfs</literal> mounts. This + option is equivalent to the command line switch + <option>--tmpfs=</option>, see + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for details about the specific options supported. This setting + is privileged (see above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PrivateUsersChown=</varname></term> + + <listitem><para>Configures whether the ownership of the files and directories in the container tree shall be + adjusted to the UID/GID range used, if necessary and user namespacing is enabled. This is equivalent to the + <option>--private-users-chown</option> command line switch. This option is privileged (see + above). </para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>[Network] Section Options</title> + + <para>Settings files may include a <literal>[Network]</literal> + section, which carries various parameters configuring the network + connectivity of the container:</para> + + <variablelist> + + <varlistentry> + <term><varname>Private=</varname></term> + + <listitem><para>Takes a boolean argument, which defaults to off. If + enabled, the container will run in its own network namespace + and not share network interfaces and configuration with the + host. This setting corresponds to the + <option>--private-network</option> command line + switch.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>VirtualEthernet=</varname></term> + + <listitem><para>Takes a boolean argument. Configures whether to create a virtual Ethernet connection + (<literal>veth</literal>) between host and the container. This setting implies + <varname>Private=yes</varname>. This setting corresponds to the <option>--network-veth</option> command line + switch. This option is privileged (see above). This option is the default if the + <filename>systemd-nspawn@.service</filename> template unit file is used.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>VirtualEthernetExtra=</varname></term> + + <listitem><para>Takes a colon-separated pair of interface + names. Configures an additional virtual Ethernet connection + (<literal>veth</literal>) between host and the container. The + first specified name is the interface name on the host, the + second the interface name in the container. The latter may be + omitted in which case it is set to the same name as the host + side interface. This setting implies + <varname>Private=yes</varname>. This setting corresponds to + the <option>--network-veth-extra=</option> command line + switch, and maybe be used multiple times. It is independent of + <varname>VirtualEthernet=</varname>. This option is privileged + (see above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Interface=</varname></term> + + <listitem><para>Takes a space-separated list of interfaces to + add to the container. This option corresponds to the + <option>--network-interface=</option> command line switch and + implies <varname>Private=yes</varname>. This option is + privileged (see above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>MACVLAN=</varname></term> + <term><varname>IPVLAN=</varname></term> + + <listitem><para>Takes a space-separated list of interfaces to + add MACLVAN or IPVLAN interfaces to, which are then added to + the container. These options correspond to the + <option>--network-macvlan=</option> and + <option>--network-ipvlan=</option> command line switches and + imply <varname>Private=yes</varname>. These options are + privileged (see above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Bridge=</varname></term> + + <listitem><para>Takes an interface name. This setting implies + <varname>VirtualEthernet=yes</varname> and + <varname>Private=yes</varname> and has the effect that the + host side of the created virtual Ethernet link is connected to + the specified bridge interface. This option corresponds to the + <option>--network-bridge=</option> command line switch. This + option is privileged (see above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Zone=</varname></term> + + <listitem><para>Takes a network zone name. This setting implies <varname>VirtualEthernet=yes</varname> and + <varname>Private=yes</varname> and has the effect that the host side of the created virtual Ethernet link is + connected to an automatically managed bridge interface named after the passed argument, prefixed with + <literal>vz-</literal>. This option corresponds to the <option>--network-zone=</option> command line + switch. This option is privileged (see above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Port=</varname></term> + + <listitem><para>Exposes a TCP or UDP port of the container on + the host. This option corresponds to the + <option>--port=</option> command line switch, see + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for the precise syntax of the argument this option takes. This + option is privileged (see above).</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd.offline-updates.xml b/man/systemd.offline-updates.xml new file mode 100644 index 0000000000..f404c8d72f --- /dev/null +++ b/man/systemd.offline-updates.xml @@ -0,0 +1,169 @@ +<?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"> + +<!-- + This file is part of systemd. + + Copyright 2013 Lennart Poettering + Copyright 2016 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.offline-updates"> + <refentryinfo> + <title>systemd.offline-updates</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.offline-updates</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.offline-updates</refname> + <refpurpose>Implementation of offline updates in systemd</refpurpose> + </refnamediv> + + <refsect1> + <title>Implementing Offline System Updates</title> + + <para>This man page describes how to implement "offline" system updates with systemd. By "offline" + OS updates we mean package installations and updates that are run with the system booted into a + special system update mode, in order to avoid problems related to conflicts of libraries and + services that are currently running with those on disk. This document is inspired by this + <ulink url="https://wiki.gnome.org/Design/OS/SoftwareUpdates">GNOME design whiteboard</ulink>. + </para> + + <para>The logic:</para> + + <orderedlist> + <listitem> + <para>The package manager prepares system updates by downloading all (RPM or DEB or + whatever) packages to update off-line in a special directory + <filename noindex="true">/var/lib/system-update</filename> (or + another directory of the package/upgrade manager's choice).</para> + </listitem> + + <listitem> + <para>When the user OK'ed the update, the symlink <filename>/system-update</filename> is + created that points to <filename noindex="true">/var/lib/system-update</filename> (or + wherever the directory with the upgrade files is located) and the system is rebooted. This + symlink is in the root directory, since we need to check for it very early at boot, at a + time where <filename>/var</filename> is not available yet.</para> + </listitem> + + <listitem> + <para>Very early in the new boot + <citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + checks whether <filename>/system-update</filename> exists. If so, it (temporarily and for + this boot only) redirects (i.e. symlinks) <filename>default.target</filename> to + <filename>system-update.target</filename>, a special target that is pulls in the base system + (i.e. <filename>sysinit.target</filename>, so that all file systems are mounted but little + else) and the system update units.</para> + </listitem> + + <listitem> + <para>The system now continues to boot into <filename>default.target</filename>, and thus + into <filename>system-update.target</filename>. This target pulls in the system update unit, + which starts the system update script after all file systems have been mounted.</para> + </listitem> + + <listitem> + <para>As the first step, the update script should check if the + <filename>/system-update</filename> symlink points to the location used by that update + script. In case it does not exists or points to a different location, the script must exit + without error. It is possible for multiple update services to be installed, and for multiple + update scripts to be launched in parallel, and only the one that corresponds to the tool + that <emphasis>created</emphasis> the symlink before reboot should perform any actions. It + is unsafe to run multiple updates in parallel.</para> + </listitem> + + <listitem> + <para>The update script should now do its job. If applicable and possible, it should + create a file system snapshot, then install all packages. + After completion (regardless whether the update succeeded or failed) the machine + must be rebooted, for example by calling <command>systemctl reboot</command>. + In addition, on failure the script should revert to the old file system snapshot + (without the symlink).</para> + </listitem> + + <listitem> + <para>The system is rebooted. Since the <filename>/system-update</filename> symlink is gone, + the generator won't redirect <filename>default.target</filename> after reboot and the + system now boots into the default target again.</para> + </listitem> + </orderedlist> + </refsect1> + + <refsect1> + <title>Recommendations</title> + + <orderedlist> + <listitem> + <para>To make things a bit more robust we recommend hooking the update script into + <filename>system-update.target</filename> via a <filename noindex='true'>.wants/</filename> + symlink in the distribution package, rather than depending on <command>systemctl + enable</command> in the postinst scriptlets of your package. More specifically, for your + update script create a .service file, without [Install] section, and then add a symlink like + <filename noindex='true'>/usr/lib/systemd/system-update.target.wants/foobar.service</filename> + → <filename noindex='true'>../foobar.service</filename> to your package.</para> + </listitem> + + <listitem> + <para>Make sure to remove the <filename>/system-update</filename> symlink as early as + possible in the update script to avoid reboot loops in case the update fails.</para> + </listitem> + + <listitem> + <para>Use <varname>FailureAction=reboot</varname> in the service file for your update script + to ensure that a reboot is automatically triggered if the update fails. + <varname>FailureAction=</varname> makes sure that the specified unit is activated if your + script exits uncleanly (by non-zero error code, or signal/coredump). If your script succeeds + you should trigger the reboot in your own code, for example by invoking logind's + <command>Reboot()</command> call or calling <command>systemct reboot</command>. See + <ulink url="http://www.freedesktop.org/wiki/Software/systemd/logind">logind dbus API</ulink> + for details.</para> + </listitem> + + <listitem> + <para>The update service should declare <varname>DefaultDependencies=false</varname>, + and pull in any services it requires explicitly.</para> + </listitem> + </orderedlist> + </refsect1> + + <refsect1> + <title>See also</title> + + <para> + <ulink url="http://www.freedesktop.org/wiki/Software/systemd/SystemUpdates/">Implementing Offline System Updates</ulink>, + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='mankier'><refentrytitle>dnf.plugin.system-upgrade</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> +</refentry> diff --git a/man/systemd.path.xml b/man/systemd.path.xml index d02bc92ae6..7200c8fe27 100644 --- a/man/systemd.path.xml +++ b/man/systemd.path.xml @@ -79,17 +79,24 @@ limitations as inotify, and for example cannot be used to monitor files or directories changed by other machines on remote NFS file systems.</para> + </refsect1> + + <refsect1> + <title>Automatic Dependencies</title> + + <para>If a path unit is beneath another mount unit in the file + system hierarchy, both a requirement and an ordering dependency + between both units are created automatically.</para> - <para>If a path unit is beneath another mount point in the file - system hierarchy, a dependency between both units is created - automatically.</para> + <para>An implicit <varname>Before=</varname> dependency is added + between a path unit and the unit it is supposed to activate.</para> - <para>Unless <varname>DefaultDependencies=false</varname> is used, - path units will implicitly have dependencies of type - <varname>Conflicts=</varname> and <varname>Before=</varname> on - <filename>shutdown.target</filename>. These ensure that path units - are terminated cleanly prior to system shutdown. Only path units - involved with early boot or late system shutdown should disable + <para>Unless <varname>DefaultDependencies=false</varname> in the <literal>[Unit]</literal> section is used, path + units will implicitly have dependencies of type <varname>Before=</varname> on <filename>paths.target</filename>, + dependencies of type <varname>After=</varname> and <varname>Requires=</varname> on + <filename>sysinit.target</filename>, and have dependencies of type <varname>Conflicts=</varname> and + <varname>Before=</varname> on <filename>shutdown.target</filename>. These ensure that path units are terminated + cleanly prior to system shutdown. Only path units involved with early boot or late system shutdown should disable this option. </para> </refsect1> diff --git a/man/systemd.preset.xml b/man/systemd.preset.xml index b7164014f0..d09167baaf 100644 --- a/man/systemd.preset.xml +++ b/man/systemd.preset.xml @@ -98,6 +98,10 @@ Empty lines and lines whose first non-whitespace character is # or ; are ignored.</para> + <para>Presets must refer to the "real" unit file, and not to any aliases. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for a description of unit aliasing.</para> + <para>Two different directives are understood: <literal>enable</literal> may be used to enable units by default, <literal>disable</literal> to disable units by default.</para> diff --git a/man/systemd.resource-control.xml b/man/systemd.resource-control.xml index 8f4e7a3f16..c11f420fe5 100644 --- a/man/systemd.resource-control.xml +++ b/man/systemd.resource-control.xml @@ -90,6 +90,70 @@ </refsect1> <refsect1> + <title>Automatic Dependencies</title> + + <para>Units with the <varname>Slice=</varname> setting set automatically acquire <varname>Requires=</varname> and + <varname>After=</varname> dependencies on the specified slice unit.</para> + </refsect1> + + <refsect1> + <title>Unified and Legacy Control Group Hierarchies</title> + + <para>The unified control group hierarchy is the new version of kernel control group interface, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>. Depending on the resource type, + there are differences in resource control capabilities. Also, because of interface changes, some resource types + have separate set of options on the unified hierarchy.</para> + + <para> + <variablelist> + + <varlistentry> + <term><option>CPU</option></term> + <listitem> + <para>Due to the lack of consensus in the kernel community, the CPU controller support on the unified + cgroup hierarchy requires out-of-tree kernel patches. See <ulink + url="https://git.kernel.org/cgit/linux/kernel/git/tj/cgroup.git/tree/Documentation/cgroup-v2-cpu.txt?h=cgroup-v2-cpu">cgroup-v2-cpu.txt</ulink>.</para> + + <para><varname>CPUWeight=</varname> and <varname>StartupCPUWeight=</varname> replace + <varname>CPUShares=</varname> and <varname>StartupCPUShares=</varname>, respectively.</para> + + <para>The <literal>cpuacct</literal> controller does not exist separately on the unified hierarchy.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>Memory</option></term> + <listitem> + <para><varname>MemoryMax=</varname> replaces <varname>MemoryLimit=</varname>. <varname>MemoryLow=</varname> + and <varname>MemoryHigh=</varname> are effective only on unified hierarchy.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>IO</option></term> + <listitem> + <para><varname>IO</varname> prefixed settings are superset of and replace <varname>BlockIO</varname> + prefixed ones. On unified hierarchy, IO resource control also applies to buffered writes.</para> + </listitem> + </varlistentry> + + </variablelist> + </para> + + <para>To ease the transition, there is best-effort translation between the two versions of settings. If all + settings of a unit for a given resource type are for the other hierarchy type, the settings are translated and + applied. If there are any valid settings for the hierarchy in use, all translations are disabled for the resource + type. Mixing the two types of settings on a unit can lead to confusing results.</para> + + <para>Legacy control group hierarchy (see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v1/cgroups.txt">cgroups.txt</ulink>), also called cgroup-v1, + doesn't allow safe delegation of controllers to unprivileged processes. If the system uses the legacy control group + hierarchy, resource control is disabled for systemd user instance, see + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + </para> + </refsect1> + + <refsect1> <title>Options</title> <para>Units of the types listed above can have settings @@ -103,39 +167,59 @@ <listitem> <para>Turn on CPU usage accounting for this unit. Takes a boolean argument. Note that turning on CPU accounting for - one unit might also implicitly turn it on for all units + one unit will also implicitly turn it on for all units contained in the same slice and for all its parent slices and the units contained therein. The system default for this - setting maybe controlled with + setting may be controlled with <varname>DefaultCPUAccounting=</varname> in <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> </listitem> </varlistentry> <varlistentry> + <term><varname>CPUWeight=<replaceable>weight</replaceable></varname></term> + <term><varname>StartupCPUWeight=<replaceable>weight</replaceable></varname></term> + + <listitem> + <para>Assign the specified CPU time weight to the processes executed, if the unified control group hierarchy + is used on the system. These options take an integer value and control the <literal>cpu.weight</literal> + control group attribute. The allowed range is 1 to 10000. Defaults to 100. For details about this control + group attribute, 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>. + The available CPU time is split up among all units within one slice relative to their CPU time weight.</para> + + <para>While <varname>StartupCPUWeight=</varname> only applies to the startup phase of the system, + <varname>CPUWeight=</varname> applies to normal runtime of the system, and if the former is not set also to + 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 are supported only if the unified control group hierarchy is used.</para> + </listitem> + </varlistentry> + + <varlistentry> <term><varname>CPUShares=<replaceable>weight</replaceable></varname></term> <term><varname>StartupCPUShares=<replaceable>weight</replaceable></varname></term> <listitem> - <para>Assign the specified CPU time share weight to the - processes executed. Those options take an integer value and - control the <literal>cpu.shares</literal> control group - attribute, which defaults to 1024. For details about this - control group attribute, see <ulink + <para>Assign the specified CPU time share weight to the processes executed. These options take an integer + value and control the <literal>cpu.shares</literal> control group attribute. The allowed range is 2 to + 262144. Defaults to 1024. For details about this control group attribute, see <ulink url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>. - The available CPU time is split up among all units within - one slice relative to their CPU time share weight.</para> + The available CPU time is split up among all units within one slice relative to their CPU time share + weight.</para> - <para>While <varname>StartupCPUShares=</varname> only - applies to the startup phase of the system, - <varname>CPUShares=</varname> applies to normal runtime of - the system, and if the former is not set also to the startup - phase. Using <varname>StartupCPUShares=</varname> allows - prioritizing specific services at boot-up differently than - during normal runtime.</para> + <para>While <varname>StartupCPUShares=</varname> only applies to the startup phase of the system, + <varname>CPUShares=</varname> applies to normal runtime of the system, and if the former is not set also to + 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>Those options imply - <literal>CPUAccounting=true</literal>.</para> + <para>These settings are supported only if the legacy control group hierarchy is used.</para> </listitem> </varlistentry> @@ -143,22 +227,20 @@ <term><varname>CPUQuota=</varname></term> <listitem> - <para>Assign the specified CPU time quota to the processes - executed. Takes a percentage value, suffixed with "%". The - percentage specifies how much CPU time the unit shall get at - maximum, relative to the total CPU time available on one - CPU. Use values > 100% for allotting CPU time on more than - one CPU. This controls the - <literal>cpu.cfs_quota_us</literal> control group - attribute. For details about this control group attribute, - see <ulink + <para>Assign the specified CPU time quota to the processes executed. Takes a percentage value, suffixed with + "%". The percentage specifies how much CPU time the unit shall get at maximum, relative to the total CPU time + available on one CPU. Use values > 100% for allotting CPU time on more than one CPU. This controls the + <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> - <para>Example: <varname>CPUQuota=20%</varname> ensures that - the executed processes will never get more than 20% CPU time - on one CPU.</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> + + <para>This setting is supported on both unified and legacy control group hierarchies.</para> </listitem> </varlistentry> @@ -168,31 +250,266 @@ <listitem> <para>Turn on process and kernel memory accounting for this unit. Takes a boolean argument. Note that turning on memory - accounting for one unit might also implicitly turn it on for - all its parent slices. The system default for this setting - maybe controlled with + accounting for one unit will also implicitly turn it on for + all units contained in the same slice and for all its parent + slices and the units contained therein. The system default + for this setting may be controlled with <varname>DefaultMemoryAccounting=</varname> in <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> </listitem> </varlistentry> <varlistentry> + <term><varname>MemoryLow=<replaceable>bytes</replaceable></varname></term> + + <listitem> + <para>Specify the best-effort memory usage protection of the executed processes in this unit. If the memory + usages of this unit and all its ancestors are below their low boundaries, this unit's memory won't be + reclaimed as long as memory can be reclaimed from unprotected units.</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.low</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.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>MemoryHigh=<replaceable>bytes</replaceable></varname></term> + + <listitem> + <para>Specify the high limit on memory usage of the executed processes in this unit. Memory usage may go + above the limit if unavoidable, but the processes are heavily slowed down and memory is taken away + aggressively in such cases. This is the main mechanism to control memory usage of a unit.</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. If assigned the + special value <literal>infinity</literal>, no memory limit is applied. This controls the + <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.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>MemoryMax=<replaceable>bytes</replaceable></varname></term> + + <listitem> + <para>Specify the absolute limit on memory usage of the executed processes in this unit. If memory usage + cannot be contained under the limit, out-of-memory killer is invoked inside the unit. It is recommended to + use <varname>MemoryHigh=</varname> as the main control mechanism and use <varname>MemoryMax=</varname> as the + last line of defense.</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. If + assigned the special value <literal>infinity</literal>, no memory limit is applied. This controls the + <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 is supported only if the unified control group hierarchy is used. Use + <varname>MemoryLimit=</varname> on systems using the legacy control group hierarchy.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>MemorySwapMax=<replaceable>bytes</replaceable></varname></term> + + <listitem> + <para>Specify the absolute limit on swap usage of the executed processes in this unit.</para> + + <para>Takes a swap size in bytes. If the value is suffixed with K, M, G or T, the specified swap size is + parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. If assigned the + special value <literal>infinity</literal>, no swap limit is applied. This controls the + <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.</para> + </listitem> + </varlistentry> + + <varlistentry> <term><varname>MemoryLimit=<replaceable>bytes</replaceable></varname></term> <listitem> - <para>Specify the limit on maximum memory usage of the - executed processes. The limit specifies how much process and - kernel memory can be used by tasks in this unit. 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. This controls the - <literal>memory.limit_in_bytes</literal> control group - attribute. For details about this control group attribute, - see <ulink - url="https://www.kernel.org/doc/Documentation/cgroups/memory.txt">memory.txt</ulink>.</para> + <para>Specify the limit on maximum memory usage of the executed processes. The limit specifies how much + process and kernel memory can be used by tasks in this unit. 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. If assigned the special value + <literal>infinity</literal>, no memory limit is applied. This controls the + <literal>memory.limit_in_bytes</literal> control group attribute. For details about this control group + 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>This setting is supported only if the legacy control group hierarchy is used. Use + <varname>MemoryMax=</varname> on systems using the unified control group hierarchy.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>TasksAccounting=</varname></term> + + <listitem> + <para>Turn on task accounting for this unit. Takes a + boolean argument. If enabled, the system manager will keep + track of the number of tasks in the unit. The number of + tasks accounted this way includes both kernel threads and + userspace processes, with each thread counting + individually. Note that turning on tasks accounting for one + unit will also implicitly turn it on for all units contained + in the same slice and for all its parent slices and the + units contained therein. The system default for this setting + may be controlled with + <varname>DefaultTasksAccounting=</varname> in + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>TasksMax=<replaceable>N</replaceable></varname></term> + + <listitem> + <para>Specify the maximum number of tasks that may be created in the unit. This ensures that the number of + tasks accounted for the unit (see above) stays below a specific limit. This either takes an absolute number + of tasks or a percentage value that is taken relative to the configured maximum number of tasks on the + system. If assigned the special value <literal>infinity</literal>, no tasks limit is applied. This controls + 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 + system default for this setting may be controlled with + <varname>DefaultTasksMax=</varname> in + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>IOAccounting=</varname></term> + + <listitem> + <para>Turn on Block I/O accounting for this unit, if the unified control group hierarchy is used on the + system. Takes a boolean argument. Note that turning on block I/O accounting for one unit will also implicitly + turn it on for all units contained in the same slice and all for its parent slices and the units contained + therein. The system default for this setting may be controlled with <varname>DefaultIOAccounting=</varname> + in + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para>This setting is supported only if the unified control group hierarchy is used. Use + <varname>BlockIOAccounting=</varname> on systems using the legacy control group hierarchy.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>IOWeight=<replaceable>weight</replaceable></varname></term> + <term><varname>StartupIOWeight=<replaceable>weight</replaceable></varname></term> + + <listitem> + <para>Set the default overall block I/O weight for the executed processes, if the unified control group + hierarchy is used on the system. Takes a single weight value (between 1 and 10000) to set the default block + I/O weight. This controls the <literal>io.weight</literal> control group attribute, which defaults to + 100. For details about this control group attribute, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>. The available I/O + bandwidth is split up among all units within one slice relative to their block I/O weight.</para> + + <para>While <varname>StartupIOWeight=</varname> only applies + to the startup phase of the system, + <varname>IOWeight=</varname> applies to the later runtime of + the system, and if the former is not set also to the startup + phase. This allows prioritizing specific services at boot-up + differently than during runtime.</para> + + <para>Implies <literal>IOAccounting=true</literal>.</para> + + <para>This setting is supported only if the unified control group hierarchy is used. Use + <varname>BlockIOWeight=</varname> and <varname>StartupBlockIOWeight=</varname> on systems using the legacy + control group hierarchy.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>IODeviceWeight=<replaceable>device</replaceable> <replaceable>weight</replaceable></varname></term> + + <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 + 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 is supported only if the unified control group hierarchy is used. Use + <varname>BlockIODeviceWeight=</varname> on systems using the legacy control group hierarchy.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>IOReadBandwidthMax=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term> + <term><varname>IOWriteBandwidthMax=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term> + + <listitem> + <para>Set the per-device overall block I/O bandwidth maximum limit for the executed processes, if the unified + control group hierarchy is used on the system. This limit is not work-conserving and the executed processes + are not allowed to use more even if the device has idle capacity. Takes a space-separated pair of a file + path and a bandwidth value (in bytes per second) to specify the device specific bandwidth. The file path may + be a 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 used. If the bandwidth is suffixed with K, M, G, or T, the specified bandwidth is + parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes, respectively, to the base of 1000. (Example: + "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This controls the <literal>io.max</literal> control + group attributes. Use this option multiple times to set bandwidth limits 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 is supported only if the unified control group hierarchy is used. Use + <varname>BlockIOAccounting=</varname> on systems using the legacy control group hierarchy.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>IOReadIOPSMax=<replaceable>device</replaceable> <replaceable>IOPS</replaceable></varname></term> + <term><varname>IOWriteIOPSMax=<replaceable>device</replaceable> <replaceable>IOPS</replaceable></varname></term> + + <listitem> + <para>Set the per-device overall block I/O IOs-Per-Second maximum limit for the executed processes, if the + unified control group hierarchy is used on the system. This limit is not work-conserving and the executed + processes are not allowed to use more even if the device has idle capacity. Takes a space-separated pair of + a file path and an IOPS value to specify the device specific IOPS. The file path may be a 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 + used. If the IOPS is suffixed with K, M, G, or T, the specified IOPS is parsed as KiloIOPS, MegaIOPS, + GigaIOPS, or TeraIOPS, respectively, to the base of 1000. (Example: + "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 1K"). This controls the <literal>io.max</literal> control + group attributes. Use this option multiple times to set IOPS limits 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 is supported only if the unified control group hierarchy is used.</para> </listitem> </varlistentry> @@ -200,14 +517,15 @@ <term><varname>BlockIOAccounting=</varname></term> <listitem> - <para>Turn on Block IO accounting for this unit. Takes a - boolean argument. Note that turning on block IO accounting - for one unit might also implicitly turn it on for all units - contained in the same slice and all for its parent slices - and the units contained therein. The system default for this - setting maybe controlled with + <para>Turn on Block I/O accounting for this unit, if the legacy control group hierarchy is used on the + system. Takes a boolean argument. Note that turning on block I/O accounting for one unit will also implicitly + turn it on for all units contained in the same slice and all for its parent slices and the units contained + therein. The system default for this setting may be controlled with <varname>DefaultBlockIOAccounting=</varname> in <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para>This setting is supported only if the legacy control group hierarchy is used. Use + <varname>IOAccounting=</varname> on systems using the unified control group hierarchy.</para> </listitem> </varlistentry> @@ -215,15 +533,13 @@ <term><varname>BlockIOWeight=<replaceable>weight</replaceable></varname></term> <term><varname>StartupBlockIOWeight=<replaceable>weight</replaceable></varname></term> - <listitem><para>Set the default overall block IO weight for - the executed processes. Takes a single weight value (between - 10 and 1000) to set the default block IO weight. This controls - the <literal>blkio.weight</literal> control group attribute, - which defaults to 1000. For details about this control group - attribute, see <ulink - url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>. - The available IO bandwidth is split up among all units within - one slice relative to their block IO weight.</para> + <listitem><para>Set the default overall block I/O weight for the executed processes, if the legacy control + group hierarchy is used on the system. Takes a single weight value (between 10 and 1000) to set the default + block I/O weight. This controls the <literal>blkio.weight</literal> control group attribute, which defaults to + 500. For details about this control group attribute, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>. + The available I/O bandwidth is split up among all units within one slice relative to their block I/O + weight.</para> <para>While <varname>StartupBlockIOWeight=</varname> only applies to the startup phase of the system, @@ -234,29 +550,32 @@ <para>Implies <literal>BlockIOAccounting=true</literal>.</para> - </listitem> + + <para>This setting is supported only if the legacy control group hierarchy is used. Use + <varname>IOWeight=</varname> and <varname>StartupIOWeight=</varname> on systems using the unified control group + hierarchy.</para> + + </listitem> </varlistentry> <varlistentry> <term><varname>BlockIODeviceWeight=<replaceable>device</replaceable> <replaceable>weight</replaceable></varname></term> <listitem> - <para>Set the per-device overall block IO weight for the - executed processes. Takes a space-separated pair of a file - path and a weight value to specify the device specific - weight value, between 10 and 1000. (Example: "/dev/sda - 500"). 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>blkio.weight_device</literal> control group - attribute, which defaults to 1000. 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/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.</para> + <para>Set the per-device overall block I/O weight for the executed processes, if the legacy 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 10 and 1000. (Example: "/dev/sda 500"). 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>blkio.weight_device</literal> control group + attribute, which defaults to 1000. 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-v1/blkio-controller.txt">blkio-controller.txt</ulink>.</para> <para>Implies <literal>BlockIOAccounting=true</literal>.</para> + + <para>This setting is supported only if the legacy control group hierarchy is used. Use + <varname>IODeviceWeight=</varname> on systems using the unified control group hierarchy.</para> </listitem> </varlistentry> @@ -265,27 +584,25 @@ <term><varname>BlockIOWriteBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term> <listitem> - <para>Set the per-device overall block IO bandwidth limit - for the executed processes. Takes a space-separated pair of - a file path and a bandwidth value (in bytes per second) to - specify the device specific bandwidth. The file path may be - a 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 used. If the bandwidth is suffixed with K, M, G, or T, - the specified bandwidth is parsed as Kilobytes, Megabytes, - Gigabytes, or Terabytes, respectively, to the base of - 1000. (Example: - "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This - controls the <literal>blkio.read_bps_device</literal> and - <literal>blkio.write_bps_device</literal> control group - attributes. Use this option multiple times to set bandwidth - limits for multiple devices. For details about these control - group attributes, see <ulink - url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>. + <para>Set the per-device overall block I/O bandwidth limit for the executed processes, if the legacy control + group hierarchy is used on the system. Takes a space-separated pair of a file path and a bandwidth value (in + bytes per second) to specify the device specific bandwidth. The file path may be a 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 used. If + the bandwidth is suffixed with K, M, G, or T, the specified bandwidth is parsed as Kilobytes, Megabytes, + Gigabytes, or Terabytes, respectively, to the base of 1000. (Example: + "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This controls the + <literal>blkio.throttle.read_bps_device</literal> and <literal>blkio.throttle.write_bps_device</literal> + control group attributes. Use this option multiple times to set bandwidth limits for multiple devices. For + details about these control group attributes, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>. </para> <para>Implies <literal>BlockIOAccounting=true</literal>.</para> + + <para>This setting is supported only if the legacy control group hierarchy is used. Use + <varname>IOReadBandwidthMax=</varname> and <varname>IOWriteBandwidthMax=</varname> on systems using the + unified control group hierarchy.</para> </listitem> </varlistentry> @@ -305,7 +622,7 @@ <literal>devices.deny</literal> control group attributes. For details about these control group attributes, see <ulink - url="https://www.kernel.org/doc/Documentation/cgroups/devices.txt">devices.txt</ulink>.</para> + url="https://www.kernel.org/doc/Documentation/cgroup-v1/devices.txt">devices.txt</ulink>.</para> <para>The device node specifier is either a path to a device node in the file system, starting with @@ -390,6 +707,12 @@ this setting is the parent slice. Since the name of a slice unit implies the parent slice, it is hence redundant to ever set this parameter directly for slice units.</para> + + <para>Special care should be taken when relying on the default slice assignment in templated service units + that have <varname>DefaultDependencies=no</varname> set, see + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, section + "Automatic Dependencies" for details.</para> + </listitem> </varlistentry> @@ -400,9 +723,9 @@ <para>Turns on delegation of further resource control partitioning to processes of the unit. For unprivileged services (i.e. those using the <varname>User=</varname> - setting) this allows processes to create a subhierarchy + setting), this allows processes to create a subhierarchy beneath its control group path. For privileged services and - scopes this ensures the processes will have all control + scopes, this ensures the processes will have all control group controllers enabled.</para> </listitem> </varlistentry> @@ -424,10 +747,10 @@ <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, The documentation for control groups and specific controllers in the Linux kernel: - <ulink url="https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink>, - <ulink url="https://www.kernel.org/doc/Documentation/cgroups/cpuacct.txt">cpuacct.txt</ulink>, - <ulink url="https://www.kernel.org/doc/Documentation/cgroups/memory.txt">memory.txt</ulink>, - <ulink url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>. + <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/cgroups.txt">cgroups.txt</ulink>, + <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>. </para> </refsect1> </refentry> diff --git a/man/systemd.scope.xml b/man/systemd.scope.xml index fd65a851e2..f69b2ef635 100644 --- a/man/systemd.scope.xml +++ b/man/systemd.scope.xml @@ -72,6 +72,10 @@ url="http://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/">New Control Group Interfaces</ulink> for an introduction on how to make use of scope units from programs.</para> + </refsect1> + + <refsect1> + <title>Automatic Dependencies</title> <para>Unless <varname>DefaultDependencies=false</varname> is used, scope units will implicitly have dependencies of @@ -82,6 +86,11 @@ shutdown. Only scope units involved with early boot or late system shutdown should disable this option. </para> + + <para>Additional implicit dependencies may be added as result of + resource control parameters as documented in + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </refsect1> <refsect1> diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 4368ca8a19..8203f2d52e 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -77,18 +77,6 @@ which configure resource control settings for the processes of the service.</para> - <para>Unless <varname>DefaultDependencies=</varname> is set to - <option>false</option>, service units will implicitly have - dependencies of type <varname>Requires=</varname> and - <varname>After=</varname> on <filename>basic.target</filename> as - well as dependencies of type <varname>Conflicts=</varname> and - <varname>Before=</varname> on - <filename>shutdown.target</filename>. These ensure that normal - service units pull in basic system initialization, and are - terminated cleanly prior to system shutdown. Only services - involved with early boot or late system shutdown should disable - this option.</para> - <para>If a service is requested under a certain name but no unit configuration file is found, systemd looks for a SysV init script by the same name (with the <filename>.service</filename> suffix @@ -97,8 +85,44 @@ compatibility is quite comprehensive but not 100%. For details about the incompatibilities, see the <ulink url="http://www.freedesktop.org/wiki/Software/systemd/Incompatibilities">Incompatibilities - with SysV</ulink> document. - </para> + with SysV</ulink> document.</para> + </refsect1> + + <refsect1> + <title>Automatic Dependencies</title> + + <para>Services with <varname>Type=dbus</varname> set automatically + acquire dependencies of type <varname>Requires=</varname> and + <varname>After=</varname> on + <filename>dbus.socket</filename>.</para> + + <para>Socket activated service are automatically ordered after + their activated <filename>.socket</filename> units via an + automatic <varname>After=</varname> dependency.</para> + + <para>Unless <varname>DefaultDependencies=</varname> in the <literal>[Unit]</literal> is set to + <option>false</option>, service units will implicitly have dependencies of type <varname>Requires=</varname> and + <varname>After=</varname> on <filename>sysinit.target</filename>, a dependency of type <varname>After=</varname> on + <filename>basic.target</filename> as well as dependencies of type <varname>Conflicts=</varname> and + <varname>Before=</varname> on <filename>shutdown.target</filename>. These ensure that normal service units pull in + basic system initialization, and are terminated cleanly prior to system shutdown. Only services involved with early + boot or late system shutdown should disable this option.</para> + + <para>Instanced service units (i.e. service units with an <literal>@</literal> in their name) are assigned by + default a per-template slice unit (see + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>), named after the + template unit, containing all instances of the specific template. This slice is normally stopped at shutdown, + together with all template instances. If that is not desired, set <varname>DefaultDependencies=no</varname> in the + template unit, and either define your own per-template slice unit file that also sets + <varname>DefaultDependencies=no</varname>, or set <varname>Slice=system.slice</varname> (or another suitable slice) + in the template unit. Also see + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para>Additional implicit dependencies may be added as result of + execution and resource control parameters as documented in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> </refsect1> <refsect1> @@ -178,17 +202,18 @@ 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 not set, it will be - implicitly set to <option>main</option>. Note that currently + <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 binary is delayed until all jobs are dispatched. This - may be used to avoid interleaving of output of shell services - with the status output on the console.</para> + <para>Behavior of <option>idle</option> is very similar to <option>simple</option>; however, actual execution + of the service binary 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 binary is invoked anyway.</para> </listitem> </varlistentry> @@ -244,72 +269,28 @@ </varlistentry> <varlistentry> - <term><varname>BusPolicy=</varname></term> - - <listitem><para>If specified, a custom kdbus - endpoint will be created and installed as the default bus node - for the service. Such a custom endpoint can hold an own set of - policy rules that are enforced on top of the bus-wide ones. - The custom endpoint is named after the service it was created - for, and its node will be bind-mounted over the default bus - node location, so the service can only access the bus through - its own endpoint. Note that custom bus endpoints default to a - 'deny all' policy. Hence, if at least one - <varname>BusPolicy=</varname> directive is given, you have to - make sure to add explicit rules for everything the service - should be able to do.</para> - <para>The value of this directive is comprised - of two parts; the bus name, and a verb to - specify to granted access, which is one of - <option>see</option>, - <option>talk</option>, or - <option>own</option>. - <option>talk</option> implies - <option>see</option>, and <option>own</option> - implies both <option>talk</option> and - <option>see</option>. - If multiple access levels are specified for the - same bus name, the most powerful one takes - effect. - </para> - <para>Examples:</para> - <programlisting>BusPolicy=org.freedesktop.systemd1 talk</programlisting> - <programlisting>BusPolicy=org.foo.bar see</programlisting> - <para>This option is only available on kdbus enabled systems.</para> - </listitem> - </varlistentry> - - <varlistentry> <term><varname>ExecStart=</varname></term> <listitem><para>Commands with their arguments that are executed when this service is started. The value is split into - zero or more command lines is according to the rules described + zero or more command lines according to the rules described below (see section "Command Lines" below). </para> - <para>When <varname>Type</varname> is not - <option>oneshot</option>, only one command may and must be - given. When <varname>Type=oneshot</varname> is used, zero or - more commands may be specified. This can be specified by - providing multiple command lines in the same directive, or - alternatively, this directive may be specified more than once - with the same effect. If the empty string is assigned to this - option, the list of commands to start is reset, prior - assignments of this option will have no effect. If no - <varname>ExecStart=</varname> is specified, then the service - must have <varname>RemainAfterExit=yes</varname> set.</para> - - <para>For each of the specified commands, the first argument - must be an absolute path to an executable. Optionally, if this - file name is prefixed with <literal>@</literal>, the second - token will be passed as <literal>argv[0]</literal> to the - executed process, followed by the further arguments specified. - If the absolute filename 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. If both - <literal>-</literal> and <literal>@</literal> are used, they - can appear in either order.</para> + <para>Unless <varname>Type=</varname> is <option>oneshot</option>, exactly one command must be given. When + <varname>Type=oneshot</varname> is used, zero or more commands may be specified. Commands may be specified by + providing multiple command lines in the same directive, or alternatively, this directive may be specified more + than once with the same effect. If the empty string is assigned to this option, the list of commands to start + is reset, prior assignments of this option will have no effect. If no <varname>ExecStart=</varname> is + specified, then the service must have <varname>RemainAfterExit=yes</varname> set.</para> + + <para>For each of the specified commands, the first argument must be an absolute path to an + executable. Optionally, if this file name is prefixed with <literal>@</literal>, the second token will be + passed as <literal>argv[0]</literal> to the executed process, followed by the further arguments specified. If + the absolute filename 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. If the + absolute path is prefixed with <literal>+</literal> then it is executed with full + privileges. <literal>@</literal>, <literal>-</literal>, and <literal>+</literal> may be used together and they + can appear in any order.</para> <para>If more than one command is specified, the commands are invoked sequentially in the order they appear in the unit @@ -337,10 +318,28 @@ <literal>-</literal>) fail, the rest are not executed and the unit is considered failed.</para> + <para><varname>ExecStart=</varname> commands are only run after + all <varname>ExecStartPre=</varname> commands that were not prefixed + with a <literal>-</literal> exit successfully.</para> + + <para><varname>ExecStartPost=</varname> commands are only run after + the service has started successfully, as determined by <varname>Type=</varname> + (i.e. the process has been started for <varname>Type=simple</varname> + or <varname>Type=idle</varname>, the process exits successfully for + <varname>Type=oneshot</varname>, the initial process exits successfully + for <varname>Type=forking</varname>, <literal>READY=1</literal> is sent + for <varname>Type=notify</varname>, or the <varname>BusName=</varname> + has been taken for <varname>Type=dbus</varname>).</para> + <para>Note that <varname>ExecStartPre=</varname> may not be used to start long-running processes. All processes forked off by processes invoked via <varname>ExecStartPre=</varname> will be killed before the next service process is run.</para> + + <para>Note that if any of the commands specified in <varname>ExecStartPre=</varname>, + <varname>ExecStart=</varname>, or <varname>ExecStartPost=</varname> fail (and are not prefixed with + <literal>-</literal>, see above) or time out before the service is fully up, execution continues with commands + specified in <varname>ExecStopPost=</varname>, the commands in <varname>ExecStop=</varname> are skipped.</para> </listitem> </varlistentry> @@ -390,27 +389,48 @@ <para>Note that it is usually not sufficient to specify a command for this setting that only asks the service to - terminate (for example by queuing some form of termination + terminate (for example, by queuing some form of termination signal for it), but does not wait for it to do so. Since the remaining processes of the services are killed using <constant>SIGKILL</constant> immediately after the command - exited this would not result in a clean stop. The specified + exited, this would not result in a clean stop. The specified command should hence be a synchronous operation, not an - asynchronous one.</para></listitem> + asynchronous one.</para> + + <para>Note that the commands specified in <varname>ExecStop=</varname> are only executed when the service + started successfully first. They are not invoked if the service was never started at all, or in case its + start-up failed, for example because any of the commands specified in <varname>ExecStart=</varname>, + <varname>ExecStartPre=</varname> or <varname>ExecStartPost=</varname> failed (and weren't prefixed with + <literal>-</literal>, see above) or timed out. Use <varname>ExecStopPost=</varname> to invoke commands when a + service failed to start up correctly and is shut down again.</para> + + <para>It is recommended to use this setting for commands that communicate with the service requesting clean + termination. When the commands specified with this option are executed it should be assumed that the service is + still fully up and is able to react correctly to all commands. For post-mortem clean-up steps use + <varname>ExecStopPost=</varname> instead.</para></listitem> </varlistentry> <varlistentry> <term><varname>ExecStopPost=</varname></term> - <listitem><para>Additional commands that are executed after - the service was stopped. This includes cases where the - commands configured in <varname>ExecStop=</varname> were used, - where the service does not have any - <varname>ExecStop=</varname> defined, or where the service - exited unexpectedly. This argument takes multiple command - lines, following the same scheme as described for - <varname>ExecStart</varname>. Use of these settings is - optional. Specifier and environment variable substitution is - supported.</para></listitem> + <listitem><para>Additional commands that are executed after the service is stopped. This includes cases where + the commands configured in <varname>ExecStop=</varname> were used, where the service does not have any + <varname>ExecStop=</varname> defined, or where the service exited unexpectedly. This argument takes multiple + command lines, following the same scheme as described for <varname>ExecStart=</varname>. Use of these settings + is optional. Specifier and environment variable substitution is supported. Note that – unlike + <varname>ExecStop=</varname> – commands specified with this setting are invoked when a service failed to start + up correctly and is shut down again.</para> + + <para>It is recommended to use this setting for clean-up operations that shall be executed even when the + service failed to start up correctly. Commands configured with this setting need to be able to operate even if + the service failed starting up half-way and left incompletely initialized data around. As the service's + processes have been terminated already when the commands specified with this setting are executed they should + not attempt to communicate with them.</para> + + <para>Note that all commands that are configured with this setting are invoked with the result code of the + service, as well as the main process' exit code and status, set in the <varname>$SERVICE_RESULT</varname>, + <varname>$EXIT_CODE</varname> and <varname>$EXIT_STATUS</varname> environment variables, see + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for + details.</para></listitem> </varlistentry> <varlistentry> @@ -428,7 +448,7 @@ configured time, the service will be considered failed and will be shut down again. Takes a unit-less value in seconds, or a time span value such as "5min 20s". Pass - <literal>0</literal> to disable the timeout logic. Defaults to + <literal>infinity</literal> to disable the timeout logic. Defaults to <varname>DefaultTimeoutStartSec=</varname> from the manager configuration file, except when <varname>Type=oneshot</varname> is used, in which case the @@ -447,7 +467,7 @@ <varname>KillMode=</varname> in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). Takes a unit-less value in seconds, or a time span value such - as "5min 20s". Pass <literal>0</literal> to disable the + as "5min 20s". Pass <literal>infinity</literal> to disable the timeout logic. Defaults to <varname>DefaultTimeoutStopSec=</varname> from the manager configuration file (see @@ -464,6 +484,16 @@ </varlistentry> <varlistentry> + <term><varname>RuntimeMaxSec=</varname></term> + + <listitem><para>Configures a maximum time for the service to run. If this is used and the service has been + active for longer than the specified time it is terminated and put into a failure state. Note that this setting + does not have any effect on <varname>Type=oneshot</varname> services, as they terminate immediately after + activation completed. Pass <literal>infinity</literal> (the default) to configure no runtime + limit.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>WatchdogSec=</varname></term> <listitem><para>Configures the watchdog timeout for a service. The watchdog is activated when the start-up is completed. The @@ -473,8 +503,9 @@ "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 - <varname>SIGABRT</varname>. By setting - <varname>Restart=</varname> to <option>on-failure</option> or + <constant>SIGABRT</constant>. 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 restarted. The time configured here will be passed to the executed service process in the @@ -485,7 +516,14 @@ should be set to open access to the notification socket provided by systemd. If <varname>NotifyAccess=</varname> is not set, it will be implicitly set to <option>main</option>. - Defaults to 0, which disables this feature.</para></listitem> + Defaults to 0, which disables this feature. The service can + check whether the service manager expects watchdog keep-alive + notifications. See + <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for details. + <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + may be used to enable automatic watchdog notification support. + </para></listitem> </varlistentry> <varlistentry> @@ -615,7 +653,7 @@ </tgroup> </table> - <para>As exceptions to the setting above the service will not + <para>As exceptions to the setting above, the service will not be restarted if the exit code or signal is specified in <varname>RestartPreventExitStatus=</varname> (see below). Also, the services will always be restarted if the exit code @@ -633,16 +671,18 @@ <varlistentry> <term><varname>SuccessExitStatus=</varname></term> - <listitem><para>Takes a list of exit status definitions that - when returned by the main service process will be considered + <listitem><para>Takes a list of exit status definitions that, + when returned by the main service process, will be considered successful termination, in addition to the normal successful exit code 0 and the signals <constant>SIGHUP</constant>, <constant>SIGINT</constant>, <constant>SIGTERM</constant>, and <constant>SIGPIPE</constant>. Exit status definitions can either be numeric exit codes or termination signal names, separated by spaces. For example: - <programlisting>SuccessExitStatus=1 2 8 - SIGKILL</programlisting> ensures that exit codes 1, 2, 8 and + + <programlisting>SuccessExitStatus=1 2 8 SIGKILL</programlisting> + + ensures that exit codes 1, 2, 8 and the termination signal <constant>SIGKILL</constant> are considered clean service terminations. </para> @@ -666,28 +706,30 @@ <varlistentry> <term><varname>RestartPreventExitStatus=</varname></term> - <listitem><para>Takes a list of exit status definitions that - when returned by the main service process will prevent + <listitem><para>Takes a list of exit status definitions that, + when returned by the main service process, will prevent automatic service restarts, regardless of the restart setting configured with <varname>Restart=</varname>. Exit status definitions can either be numeric exit codes or termination signal names, and are separated by spaces. Defaults to the empty list, so that, by default, no exit status is excluded from the configured restart logic. For example: - <programlisting>RestartPreventExitStatus=1 6 - SIGABRT</programlisting> ensures that exit codes 1 and 6 and - the termination signal <constant>SIGABRT</constant> will not - result in automatic service restarting. This option may appear - more than once, in which case the list of restart-preventing - statuses is merged. If the empty string is assigned to this - option, the list is reset and all prior assignments of this - option will have no effect.</para></listitem> + + <programlisting>RestartPreventExitStatus=1 6 SIGABRT</programlisting> + + ensures that exit codes 1 and 6 and the termination signal + <constant>SIGABRT</constant> will not result in automatic + service restarting. This option may appear more than once, in + which case the list of restart-preventing statuses is + merged. If the empty string is assigned to this option, the + list is reset and all prior assignments of this option will + have no effect.</para></listitem> </varlistentry> <varlistentry> <term><varname>RestartForceExitStatus=</varname></term> - <listitem><para>Takes a list of exit status definitions that - when returned by the main service process will force automatic + <listitem><para>Takes a list of exit status definitions that, + when returned by the main service process, will force automatic service restarts, regardless of the restart setting configured with <varname>Restart=</varname>. The argument format is similar to @@ -766,8 +808,8 @@ <term><varname>Sockets=</varname></term> <listitem><para>Specifies the name of the socket units this service shall inherit socket file descriptors from when the - service is started. Normally it should not be necessary to use - this setting as all socket file descriptors whose unit shares + service is started. Normally, it should not be necessary to use + this setting, as all socket file descriptors whose unit shares the same name as the service (subject to the different unit name suffix of course) are passed to the spawned process.</para> @@ -776,7 +818,7 @@ to multiple processes simultaneously. Also note that a different service may be activated on incoming socket traffic than the one which is ultimately configured to inherit the - socket file descriptors. Or in other words: the + socket file descriptors. Or, in other words: the <varname>Service=</varname> setting of <filename>.socket</filename> units does not have to match the inverse of the <varname>Sockets=</varname> setting of the @@ -790,85 +832,11 @@ </varlistentry> <varlistentry> - <term><varname>StartLimitInterval=</varname></term> - <term><varname>StartLimitBurst=</varname></term> - - <listitem><para>Configure service start rate limiting. By - default, services which are started more than 5 times within - 10 seconds are not permitted to start any more times until the - 10 second interval ends. With these two options, this rate - limiting may be modified. Use - <varname>StartLimitInterval=</varname> to configure the - checking interval (defaults to - <varname>DefaultStartLimitInterval=</varname> in manager - configuration file, set to 0 to disable any kind of rate - limiting). Use <varname>StartLimitBurst=</varname> to - configure how many starts per interval are allowed (defaults - to <varname>DefaultStartLimitBurst=</varname> in manager - configuration file). These configuration options are - particularly useful in conjunction with - <varname>Restart=</varname>; however, they apply to all kinds - of starts (including manual), not just those triggered by the - <varname>Restart=</varname> logic. Note that units which are - configured for <varname>Restart=</varname> and which reach the - start limit are not attempted to be restarted anymore; - however, they may still be restarted manually at a later - point, from which point on, the restart logic is again - activated. Note that <command>systemctl reset-failed</command> - will cause the restart rate counter for a service to be - flushed, which is useful if the administrator wants to - manually start a service and the start limit interferes with - that.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>StartLimitAction=</varname></term> - - <listitem><para>Configure the action to take if the rate limit - configured with <varname>StartLimitInterval=</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. Similar, - <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> - </varlistentry> - - <varlistentry> <term><varname>FailureAction=</varname></term> - <listitem><para>Configure the action to take when the service - enters a failed state. Takes the same values as - <varname>StartLimitAction=</varname> and executes the same - actions. Defaults to <option>none</option>. </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>RebootArgument=</varname></term> - <listitem><para>Configure the optional argument for the - <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> - system call if <varname>StartLimitAction=</varname> or - <varname>FailureAction=</varname> is a reboot action. This - works just like the optional argument to <command>systemctl - reboot</command> command.</para></listitem> + <listitem><para>Configure the action to take when the service enters a failed state. Takes the same values as + the unit setting <varname>StartLimitAction=</varname> and executes the same actions (see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>). Defaults to + <option>none</option>. </para></listitem> </varlistentry> <varlistentry> @@ -890,6 +858,27 @@ and no job queued or being executed for it.</para></listitem> </varlistentry> + <varlistentry> + <term><varname>USBFunctionDescriptors=</varname></term> + <listitem><para>Configure the location of a file containing + <ulink + url="https://www.kernel.org/doc/Documentation/usb/functionfs.txt">USB + FunctionFS</ulink> descriptors, for implementation of USB + gadget functions. This is used only in conjunction with a + socket unit with <varname>ListenUSBFunction=</varname> + configured. The contents of this file are written to the + <filename>ep0</filename> file after it is + opened.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>USBFunctionStrings=</varname></term> + <listitem><para>Configure the location of a file containing + USB FunctionFS strings. Behavior is similar to + <varname>USBFunctionDescriptors=</varname> + above.</para></listitem> + </varlistentry> + </variablelist> <para>Check @@ -922,7 +911,10 @@ the arguments. Double quotes ("...") and single quotes ('...') may be used, in which case everything until the next matching quote becomes part of the same argument. C-style escapes are also - supported, see table below. Quotes themselves are removed after + supported. The table below contains the list of allowed escape + patterns. Only patterns which match the syntax in the table are + allowed; others will result in an error, and must be escaped by + doubling the backslash. Quotes themselves are removed after parsing and escape sequences substituted. In addition, a trailing backslash (<literal>\</literal>) may be used to merge lines. </para> @@ -939,7 +931,7 @@ <literal>&</literal>, and <emphasis>other elements of shell syntax are not supported</emphasis>.</para> - <para>The command to execute must an absolute path name. It may + <para>The command to execute must be an absolute path name. It may contain spaces, but control characters are not allowed.</para> <para>The command line accepts <literal>%</literal> specifiers as @@ -955,8 +947,8 @@ contains, resulting in a single argument. Use <literal>$FOO</literal> as a separate word on the command line, in which case it will be replaced by the value of the environment - variable split at whitespace resulting in zero or more arguments. - For this type of expansion, quotes and respected when splitting + variable split at whitespace, resulting in zero or more arguments. + For this type of expansion, quotes are respected when splitting into words, and afterwards removed.</para> <para>Example:</para> @@ -1138,7 +1130,7 @@ WantedBy=multi-user.target</programlisting> <example> <title>Oneshot service</title> - <para>Sometimes units should just execute an action without + <para>Sometimes, units should just execute an action without keeping active processes, such as a filesystem check or a cleanup action on boot. For this, <varname>Type=</varname><option>oneshot</option> exists. Units @@ -1157,10 +1149,10 @@ ExecStart=/usr/sbin/foo-cleanup WantedBy=multi-user.target</programlisting> <para>Note that systemd will consider the unit to be in the - state 'starting' until the program has terminated, so ordered + state "starting" until the program has terminated, so ordered dependencies will wait for the program to finish before starting - themselves. The unit will revert to the 'inactive' state after - the execution is done, never reaching the 'active' state. That + themselves. The unit will revert to the "inactive" state after + the execution is done, never reaching the "active" state. That means another request to start the unit will perform the action again.</para> @@ -1177,9 +1169,9 @@ WantedBy=multi-user.target</programlisting> <para>Similarly to the oneshot services, there are sometimes units that need to execute a program to set up something and then execute another to shut it down, but no process remains - active while they are considered 'started'. Network + active while they are considered "started". Network configuration can sometimes fall into this category. Another use - case is if a oneshot service shall not be executed a each time + case is if a oneshot service shall not be executed each time when they are pulled in as a dependency, but only the first time.</para> @@ -1190,11 +1182,11 @@ WantedBy=multi-user.target</programlisting> types, but is most useful with <varname>Type=</varname><option>oneshot</option> and <varname>Type=</varname><option>simple</option>. With - <varname>Type=</varname><option>oneshot</option> systemd waits + <varname>Type=</varname><option>oneshot</option>, systemd waits until the start action has completed before it considers the unit to be active, so dependencies start only after the start action has succeeded. With - <varname>Type=</varname><option>simple</option> dependencies + <varname>Type=</varname><option>simple</option>, dependencies will start immediately after the start action has been dispatched. The following unit provides an example for a simple static firewall.</para> @@ -1229,7 +1221,7 @@ WantedBy=multi-user.target</programlisting> <varname>RemainAfterExit=</varname><option>no</option>), the service is considered started.</para> - <para>Often a traditional daemon only consists of one process. + <para>Often, a traditional daemon only consists of one process. Therefore, if only one process is left after the original process terminates, systemd will consider that process the main process of the service. In that case, the @@ -1244,7 +1236,7 @@ WantedBy=multi-user.target</programlisting> traditional PID file, systemd will be able to read the main PID from there. Please set <varname>PIDFile=</varname> accordingly. Note that the daemon should write that file before finishing - with its initialization, otherwise systemd might try to read the + with its initialization. Otherwise, systemd might try to read the file before it exists.</para> <para>The following example shows a simple daemon that forks and @@ -1287,7 +1279,7 @@ ExecStart=/usr/sbin/simple-dbus-service [Install] WantedBy=multi-user.target</programlisting> - <para>For <emphasis>bus-activatable</emphasis> services, don't + <para>For <emphasis>bus-activatable</emphasis> services, do not include a <literal>[Install]</literal> section in the systemd service file, but use the <varname>SystemdService=</varname> option in the corresponding DBus service file, for example @@ -1329,7 +1321,7 @@ ExecStart=/usr/sbin/simple-notifying-service WantedBy=multi-user.target</programlisting> <para>Note that the daemon has to support systemd's notification - protocol, else systemd will think the service hasn't started yet + protocol, else systemd will think the service has not started yet and kill it after a timeout. For an example of how to update daemons to support this protocol transparently, take a look at <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>. diff --git a/man/systemd.slice.xml b/man/systemd.slice.xml index a501327335..eee98d99ee 100644 --- a/man/systemd.slice.xml +++ b/man/systemd.slice.xml @@ -71,6 +71,9 @@ the root slice <filename>-.slice</filename>. </para> + <para>Note that slice units cannot be templated, nor is possible to add multiple names to a slice unit by creating + additional symlinks to it.</para> + <para>By default, service and scope units are placed in <filename>system.slice</filename>, virtual machines and containers registered with @@ -93,14 +96,23 @@ <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> are allowed. </para> - <para>Unless <varname>DefaultDependencies=false</varname> - is used, slice units will implicitly have dependencies of - type <varname>Conflicts=</varname> and - <varname>Before=</varname> on - <filename>shutdown.target</filename>. These ensure - that slice units are removed prior to system - shutdown. Only slice units involved with early boot or - late system shutdown should disable this option. + <para>See the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/">New + Control Group Interfaces</ulink> for an introduction on how to make + use of slice units from programs.</para> + </refsect1> + + <refsect1> + <title>Automatic Dependencies</title> + + <para>Slice units automatically gain dependencies of type + <varname>After=</varname> and <varname>Requires=</varname> on + their immediate parent slice unit.</para> + + <para>Unless <varname>DefaultDependencies=false</varname> is used in the <literal>[Unit]</literal> section, slice + units will implicitly have dependencies of type <varname>Conflicts=</varname> and <varname>Before=</varname> on + <filename>shutdown.target</filename>. These ensure that slice units are removed prior to system shutdown. Only + slice units involved with early boot or late system shutdown should disable this option. </para> </refsect1> diff --git a/man/systemd.snapshot.xml b/man/systemd.snapshot.xml deleted file mode 100644 index 96069c324a..0000000000 --- a/man/systemd.snapshot.xml +++ /dev/null @@ -1,83 +0,0 @@ -<?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"> - -<!-- - This file is part of systemd. - - Copyright 2010 Lennart Poettering - - systemd is free software; you can redistribute it and/or modify it - under the terms of the GNU Lesser General Public License as published by - the Free Software Foundation; either version 2.1 of the License, or - (at your option) any later version. - - systemd is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public License - along with systemd; If not, see <http://www.gnu.org/licenses/>. ---> - -<refentry id="systemd.snapshot"> - <refentryinfo> - <title>systemd.snapshot</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd.snapshot</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd.snapshot</refname> - <refpurpose>Snapshot unit configuration</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename><replaceable>snapshot</replaceable>.snapshot</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>Snapshot units are not configured via unit configuration - files. Nonetheless they are named similar to filenames. A unit - whose name ends in <literal>.snapshot</literal> refers to a - dynamic snapshot of the systemd runtime state.</para> - - <para>Snapshots are not configured on disk but created dynamically - via <command>systemctl snapshot</command> (see - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - for details) or an equivalent command. When created, they will - automatically get dependencies on the currently activated units. - They act as saved runtime state of the systemd manager. Later on, - the user may choose to return to the saved state via - <command>systemctl isolate</command>. They are useful to roll back - to a defined state after temporarily starting/stopping services or - similar.</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>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml index 1e9778bc2a..0ce1203cfb 100644 --- a/man/systemd.socket.xml +++ b/man/systemd.socket.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -97,16 +97,12 @@ <filename>foo@.service</filename> must exist from which services are instantiated for each incoming connection.</para> - <para>Unless <varname>DefaultDependencies=</varname> is set to - <option>false</option>, socket units will implicitly have - dependencies of type <varname>Requires=</varname> and - <varname>After=</varname> on <filename>sysinit.target</filename> - as well as dependencies of type <varname>Conflicts=</varname> and - <varname>Before=</varname> on - <filename>shutdown.target</filename>. These ensure that socket - units pull in basic system initialization, and are terminated - cleanly prior to system shutdown. Only sockets involved with early - boot or late system shutdown should disable this option.</para> + <para>Unless <varname>DefaultDependencies=</varname> in the <literal>[Unit]</literal> section is set to + <option>false</option>, socket units will implicitly have dependencies of type <varname>Requires=</varname> and + <varname>After=</varname> on <filename>sysinit.target</filename> as well as dependencies of type + <varname>Conflicts=</varname> and <varname>Before=</varname> on <filename>shutdown.target</filename>. These ensure + that socket units pull in basic system initialization, and are terminated cleanly prior to system shutdown. Only + sockets involved with early boot or late system shutdown should disable this option.</para> <para>Socket units will have a <varname>Before=</varname> dependency on the service which they trigger added implicitly. No @@ -134,6 +130,40 @@ </refsect1> <refsect1> + <title>Automatic Dependencies</title> + + <para>Socket units automatically gain a <varname>Before=</varname> + dependency on the service units they activate.</para> + + <para>Socket units referring to file system paths (such as AF_UNIX + sockets or FIFOs) implicitly gain <varname>Requires=</varname> and + <varname>After=</varname> dependencies on all mount units + necessary to access those paths.</para> + + <para>Socket units using the <varname>BindToDevice=</varname> + setting automatically gain a <varname>BindsTo=</varname> and + <varname>After=</varname> dependency on the device unit + encapsulating the specified network interface.</para> + + <para>If <varname>DefaultDependencies=yes</varname> is set (the + default), socket units automatically gain a + <varname>Before=</varname> dependency on + <filename>sockets.target</filename>. They also gain a pair of + <varname>After=</varname> and <varname>Requires=</varname> + dependency on <filename>sysinit.target</filename>, and a pair of + <varname>Before=</varname> and <varname>Conflicts=</varname> + dependencies on <filename>shutdown.target</filename>. These + dependencies ensure that the socket unit is started before normal + services at boot, and is stopped on shutdown.</para> + + <para>Additional implicit dependencies may be added as result of + execution and resource control parameters as documented in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> <title>Options</title> <para>Socket files must include a [Socket] section, which carries @@ -194,7 +224,7 @@ refers to TCP sockets, <constant>SOCK_DGRAM</constant> (i.e. <varname>ListenDatagram=</varname>) to UDP.</para> - <para>These options may be specified more than once in which + <para>These options may be specified more than once, in which case incoming traffic on any of the sockets will trigger service activation, and all listed sockets will be passed to the service, regardless of whether there is incoming traffic @@ -261,6 +291,31 @@ </varlistentry> <varlistentry> + <term><varname>ListenUSBFunction=</varname></term> + <listitem><para>Specifies a <ulink + url="https://www.kernel.org/doc/Documentation/usb/functionfs.txt">USB + FunctionFS</ulink> endpoints location to listen on, for + implementation of USB gadget functions. This expects an + absolute file system path of functionfs mount point as the argument. + Behavior otherwise is very similar to the <varname>ListenFIFO=</varname> + directive above. Use this to open the FunctionFS endpoint + <filename>ep0</filename>. When using this option, the + activated service has to have the + <varname>USBFunctionDescriptors=</varname> and + <varname>USBFunctionStrings=</varname> options set. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SocketProtocol=</varname></term> + <listitem><para>Takes a 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> + </listitem> + </varlistentry> + + <varlistentry> <term><varname>BindIPv6Only=</varname></term> <listitem><para>Takes a one of <option>default</option>, <option>both</option> or <option>ipv6-only</option>. Controls @@ -293,12 +348,14 @@ <listitem><para>Specifies a network interface name to bind this socket to. If set, traffic will only be accepted from the specified network interfaces. This controls the - SO_BINDTODEVICE socket option (see - <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> + SO_BINDTODEVICE socket option (see <citerefentry + project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details). If this option is used, an automatic dependency from this socket unit on the network interface device unit (<citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry> - is created.</para></listitem> + is created. Note that setting this parameter might result in + additional dependencies to be added to the unit (see + above).</para></listitem> </varlistentry> <varlistentry> @@ -359,10 +416,18 @@ to work unmodified with systemd socket activation.</para> - <para>For IPv4 and IPv6 connections the <varname>REMOTE_ADDR</varname> - environment variable will contain the remote IP, and <varname>REMOTE_PORT</varname> + <para>For IPv4 and IPv6 connections, the <varname>REMOTE_ADDR</varname> + environment variable will contain the remote IP address, and <varname>REMOTE_PORT</varname> will contain the remote port. This is the same as the format used by CGI. - For SOCK_RAW the port is the IP protocol.</para></listitem> + For SOCK_RAW, the port is the IP protocol.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Writable=</varname></term> + <listitem><para>Takes a boolean argument. May only be used in + conjunction with <varname>ListenSpecial=</varname>. If true, + the specified special file is opened in read-write mode, if + false, in read-only mode. Defaults to false.</para></listitem> </varlistentry> <varlistentry> @@ -378,6 +443,14 @@ </varlistentry> <varlistentry> + <term><varname>MaxConnectionsPerSource=</varname></term> + <listitem><para>The maximum number of connections for a service per source IP address. + This is very similar to the <varname>MaxConnections=</varname> directive + above. Disabled by default.</para> + </listitem> + </varlistentry> + + <varlistentry> <term><varname>KeepAlive=</varname></term> <listitem><para>Takes a boolean argument. If true, the TCP/IP stack will send a keep alive message after 2h (depending on @@ -394,7 +467,7 @@ <varlistentry> <term><varname>KeepAliveTimeSec=</varname></term> - <listitem><para>Takes time (in seconds) as argument . The connection needs to remain + <listitem><para>Takes time (in seconds) as argument. The connection needs to remain idle before TCP starts sending keepalive probes. This controls the TCP_KEEPIDLE socket option (see <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> @@ -408,7 +481,7 @@ <term><varname>KeepAliveIntervalSec=</varname></term> <listitem><para>Takes time (in seconds) as argument between individual keepalive probes, if the socket option SO_KEEPALIVE - has been set on this socket seconds as argument. This controls + has been set on this socket. This controls the TCP_KEEPINTVL socket option (see <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> and the <ulink @@ -419,7 +492,7 @@ <varlistentry> <term><varname>KeepAliveProbes=</varname></term> - <listitem><para>Takes integer as argument. It's the number of + <listitem><para>Takes an integer as argument. It is the number of unacknowledged probes to send before considering the connection dead and notifying the application layer. This controls the TCP_KEEPCNT socket option (see @@ -462,7 +535,7 @@ and the kernel will ignore initial ACK packets without any data. The argument specifies the approximate amount of time the kernel should wait for incoming data before falling back - to the normal behaviour of honouring empty ACK packets. This + to the normal behavior of honoring empty ACK packets. This option is beneficial for protocols where the client sends the data first (e.g. HTTP, in contrast to SMTP), because the server process will not be woken up unnecessarily before it @@ -695,7 +768,9 @@ with <varname>Accept=no</varname>. It defaults to the service that bears the same name as the socket (with the suffix replaced). In most cases, it should not be necessary to use - this option.</para></listitem> + this option. Note that setting this parameter might result in + additional dependencies to be added to the unit (see + above).</para></listitem> </varlistentry> <varlistentry> @@ -724,6 +799,39 @@ list.</para></listitem> </varlistentry> + <varlistentry> + <term><varname>FileDescriptorName=</varname></term> + <listitem><para>Assigns a name to all file descriptors this + socket unit encapsulates. This is useful to help activated + services identify specific file descriptors, if multiple fds + are passed. Services may use the + <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call to acquire the names configured for the received file + descriptors. Names may contain any ASCII character, but must + exclude control characters and <literal>:</literal>, and must + be at most 255 characters in length. If this setting is not + used, the file descriptor name defaults to the name of the + socket unit, including its <filename>.socket</filename> + suffix.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TriggerLimitIntervalSec=</varname></term> + <term><varname>TriggerLimitBurst=</varname></term> + + <listitem><para>Configures a limit on how often this socket unit my be activated within a specific time + interval. The <varname>TriggerLimitIntervalSec=</varname> may be used to configure the length of the time + interval in the usual time units <literal>us</literal>, <literal>ms</literal>, <literal>s</literal>, + <literal>min</literal>, <literal>h</literal>, … and defaults to 2s (See + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details on + the various time units understood). The <varname>TriggerLimitBurst=</varname> setting takes a positive integer + value and specifies the number of permitted activations per time interval, and defaults to 200 for + <varname>Accept=yes</varname> sockets (thus by default permitting 200 activations per 2s), and 20 otherwise (20 + activations per 2s). Set either to 0 to disable any form of trigger rate limiting. If the limit is hit, the + socket unit is placed into a failure mode, and will not be connectible anymore until restarted. Note that this + limit is enforced before the service activation is enqueued.</para></listitem> + </varlistentry> + </variablelist> <para>Check @@ -744,9 +852,10 @@ <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> - <para> For more extensive descriptions see the "systemd for Developers" series: <ulink url="http://0pointer.de/blog/projects/socket-activation.html">Socket Activation</ulink>, diff --git a/man/systemd.special.xml b/man/systemd.special.xml index cf76aaf607..d977298cd8 100644 --- a/man/systemd.special.xml +++ b/man/systemd.special.xml @@ -83,6 +83,7 @@ <filename>remote-fs.target</filename>, <filename>remote-fs-pre.target</filename>, <filename>rescue.target</filename>, + <filename>initrd-root-device.target</filename>, <filename>initrd-root-fs.target</filename>, <filename>rpcbind.target</filename>, <filename>runlevel2.target</filename>, @@ -92,6 +93,7 @@ <filename>shutdown.target</filename>, <filename>sigpwr.target</filename>, <filename>sleep.target</filename>, + <filename>slices.target</filename>, <filename>smartcard.target</filename>, <filename>sockets.target</filename>, <filename>sound.target</filename>, @@ -125,21 +127,34 @@ <listitem> <para>A special target unit covering basic boot-up.</para> - <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 + <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 mount points, swap - devices, sockets, timers, and path units and other basic - initialization necessary for general purpose daemons.</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 + pressed on the console. Usually, this should be aliased (symlinked) to <filename>reboot.target</filename>.</para> </listitem> </varlistentry> @@ -169,7 +184,7 @@ <varlistentry> <term><filename>default.target</filename></term> <listitem> - <para>The default unit systemd starts at bootup. Usually + <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> @@ -182,7 +197,7 @@ <varlistentry> <term><filename>display-manager.service</filename></term> <listitem> - <para>The display manager service. Usually this should be + <para>The display manager service. Usually, this should be aliased (symlinked) to <filename>gdm.service</filename> or a similar display manager service.</para> </listitem> @@ -190,12 +205,41 @@ <varlistentry> <term><filename>emergency.target</filename></term> <listitem> - <para>A special target unit that starts an emergency shell - on the main console. This unit is supposed to be used with - the kernel command line option - <varname>systemd.unit=</varname> and has otherwise little - use. - </para> + <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 a + request to shut down over D-Bus or a + <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> @@ -407,11 +451,30 @@ <varlistentry> <term><filename>rescue.target</filename></term> <listitem> - <para>A special target unit for setting up the base system - and a rescue shell.</para> + <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.</para> - <para><filename>runlevel1.target</filename> is an alias for - this target unit, for compatibility with SysV.</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>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> @@ -434,8 +497,8 @@ <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>multi-user.target</filename> - (for runlevel 2) or <filename>graphical.target</filename> + (i.e. symlink to) <filename>graphical.target</filename> + (for runlevel 5) or <filename>multi-user.target</filename> (the others).</para> </listitem> </varlistentry> @@ -446,8 +509,9 @@ system shutdown.</para> <para>Services that shall be terminated on system shutdown - shall add <varname>Conflicts=</varname> dependencies to this - unit for their service unit, which is implicitly done when + 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> @@ -471,10 +535,23 @@ </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>user.slice</filename>, + <filename>system.slice</filename>, <filename>machines.slice</filename> slice units, as well as the root + slice unit <filename>-.slice</filename> are 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 + units (see <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details) that shall be active after boot.</para> @@ -503,8 +580,19 @@ <varlistentry> <term><filename>sysinit.target</filename></term> <listitem> - <para>A special target unit covering early boot-up - scripts.</para> + <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> @@ -549,7 +637,7 @@ <varlistentry> <term><filename>umount.target</filename></term> <listitem> - <para>A special target unit that umounts all mount and + <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 @@ -673,7 +761,7 @@ 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 -- + 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 @@ -778,6 +866,7 @@ <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>, @@ -787,30 +876,70 @@ <filename>printer.target</filename>, <filename>smartcard.target</filename>, <filename>sound.target</filename>.</para> + </refsect1> - <para>In addition, the following special unit is understood only - when systemd runs as service instance:</para> + <refsect1> + <title>Special Passive User Units</title> + + <refsect2> + <title>graphical-session.target</title> + + <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> - <variablelist> - <varlistentry> - <term><filename>exit.target</filename></term> - <listitem> - <para>A special service unit for shutting down the user - service manager.</para> + <example> + <title>Nautilus as part of a GNOME session</title> - <para>Applications wanting to terminate the user service - manager should start this unit. If systemd receives - <constant>SIGTERM</constant> or <constant>SIGINT</constant> - when running as user service daemon, it will start this - unit.</para> + <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> + </refsect2> + + <refsect2> + <title>graphical-session-pre.target</title> + + <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> + </refsect2> - <para>Normally, this pulls in - <filename>shutdown.target</filename> which in turn should be - conflicted by all units that want to be shut down on user - service manager exit.</para> - </listitem> - </varlistentry> - </variablelist> </refsect1> <refsect1> @@ -833,7 +962,7 @@ <varlistentry> <term><filename>system.slice</filename></term> <listitem> - <para>By default, all services services started by + <para>By default, all system services started by <command>systemd</command> are found in this slice.</para> </listitem> </varlistentry> diff --git a/man/systemd.swap.xml b/man/systemd.swap.xml index d9a39577d5..cf4e1ba839 100644 --- a/man/systemd.swap.xml +++ b/man/systemd.swap.xml @@ -68,31 +68,42 @@ <para>Additional options are listed in <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - which define the execution environment the - <citerefentry project='man-pages'><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry> - binary is executed in, and in + which define the execution environment the <citerefentry + project='man-pages'><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry> + binary is executed in, in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - which define the way the processes are terminated, and in + which define the way these processes are + terminated, and in <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - which configure resource control settings for the processes of the - service.</para> - - <para>Swap units must be named after the devices - or files they control. Example: the swap device - <filename noindex='true'>/dev/sda5</filename> must be configured in a - unit file <filename>dev-sda5.swap</filename>. For details about - the escaping logic used to convert a file system path to a unit - name, see - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - - <para>All swap units automatically get the appropriate - dependencies on the devices or on the mount points of the files + which configure resource control settings for these processes of the + unit.</para> + + <para>Swap units must be named after the devices or files they control. Example: the swap device <filename + noindex='true'>/dev/sda5</filename> must be configured in a unit file <filename>dev-sda5.swap</filename>. For + details about the escaping logic used to convert a file system path to a unit name, see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Note that swap + units cannot be templated, nor is possible to add multiple names to a swap unit by creating additional symlinks to + it.</para> + </refsect1> + + <refsect1> + <title>Automatic Dependencies</title> + + <para>All swap units automatically get the + <varname>BindsTo=</varname> and <varname>After=</varname> + dependencies on the device units or the mount units of the files they are activated from.</para> - <para>Swap units with <varname>DefaultDependencies=</varname> - enabled implicitly acquire a conflicting dependency to - <filename>umount.target</filename> so that they are deactivated at - shutdown.</para> + <para>Swap units with <varname>DefaultDependencies=</varname> in the <literal>[Unit]</literal> section enabled + implicitly acquire a <varname>Conflicts=</varname> and an <varname>After=</varname> dependency on + <filename>umount.target</filename> so that they are deactivated at shutdown, unless + <varname>DefaultDependencies=no</varname> is specified.</para> + + <para>Additional implicit dependencies may be added as result of + execution and resource control parameters as documented in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> </refsect1> <refsect1> @@ -111,7 +122,7 @@ <filename>/etc/fstab</filename> and a unit file, the configuration in the latter takes precedence.</para> - <para>When reading <filename>/etc/fstab</filename> a few special + <para>When reading <filename>/etc/fstab</filename>, a few special options are understood by systemd which influence how dependencies are created for swap units.</para> @@ -120,11 +131,11 @@ <term><option>noauto</option></term> <term><option>auto</option></term> - <listitem><para>With <option>noauto</option> the swap unit + <listitem><para>With <option>noauto</option>, the swap unit will not be added as a dependency for <filename>swap.target</filename>. This means that it will not be activated automatically during boot, unless it is pulled in - by some other unit. Option <option>auto</option> has the + by some other unit. The <option>auto</option> option has the opposite meaning and is the default.</para> </listitem> </varlistentry> @@ -132,7 +143,7 @@ <varlistentry> <term><option>nofail</option></term> - <listitem><para>With <option>nofail</option> the swap unit + <listitem><para>With <option>nofail</option>, the swap unit will be only wanted, not required by <filename>swap.target</filename>. This means that the boot will continue even if this swap device is not activated @@ -177,8 +188,8 @@ <listitem><para>Swap priority to use when activating the swap device or file. This takes an integer. This setting is - optional and ignored when priority is set by <option>pri=</option> in the - <varname>Options=</varname> option.</para></listitem> + optional and ignored when the priority is set by <option>pri=</option> in the + <varname>Options=</varname> key.</para></listitem> </varlistentry> <varlistentry> diff --git a/man/systemd.target.xml b/man/systemd.target.xml index e790e9b77a..2e35e54fc4 100644 --- a/man/systemd.target.xml +++ b/man/systemd.target.xml @@ -77,15 +77,25 @@ See <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details).</para> + </refsect1> + + <refsect1> + <title>Automatic Dependencies</title> <para>Unless <varname>DefaultDependencies=</varname> is set to - <option>false</option>, target units will implicitly complement - all configured dependencies of type <varname>Wants=</varname>, - <varname>Requires=</varname>, - <varname>RequiresOverridable=</varname> with dependencies of type - <varname>After=</varname> if the units in question also have - <varname>DefaultDependencies=true</varname>. - </para> + <option>no</option> in either of releated units or an explicit ordering + dependency is already defined, target units will implicitly complement all + configured dependencies of type <varname>Wants=</varname> or + <varname>Requires=</varname> with dependencies of type + <varname>After=</varname>. Note that <varname>Wants=</varname> or + <varname>Requires=</varname> must be defined in the target unit itself — if + you for example define <varname>Wants=</varname>some.target in + some.service, the implicit ordering will not be added.</para> + + <para>All target units automatically gain <varname>Conflicts=</varname> + dependency against shutdown.target unless <varname>DefaultDependencies=</varname> + is set to <option>no</option>.</para> + </refsect1> <refsect1> diff --git a/man/systemd.time.xml b/man/systemd.time.xml index 64358351d5..47229b4a4e 100644 --- a/man/systemd.time.xml +++ b/man/systemd.time.xml @@ -57,14 +57,13 @@ <refsect1> <title>Displaying Time Spans</title> - <para>Time spans refer to time durations. On display, systemd will - present time spans as a space-separated series of time values each - suffixed by a time unit.</para> + <para>Time spans refer to time durations. On display, systemd will present time spans as a space-separated series + of time values each suffixed by a time unit. Example:</para> <programlisting>2h 30min</programlisting> - <para>All specified time values are meant to be added up. The - above hence refers to 150 minutes.</para> + <para>All specified time values are meant to be added up. The above hence refers to 150 minutes. Display is + locale-independent, only English names for the time units are used.</para> </refsect1> <refsect1> @@ -82,14 +81,14 @@ <listitem><para>hours, hour, hr, h</para></listitem> <listitem><para>days, day, d</para></listitem> <listitem><para>weeks, week, w</para></listitem> - <listitem><para>months, month</para></listitem> - <listitem><para>years, year, y</para></listitem> + <listitem><para>months, month, M (defined as 30.44 days)</para></listitem> + <listitem><para>years, year, y (defined as 365.25 days)</para></listitem> </itemizedlist> - <para>If no time unit is specified, generally seconds are assumed, - but some exceptions exist and are marked as such. In a few cases - <literal>ns</literal>, <literal>nsec</literal> is accepted too, - where the granularity of the time span allows for this.</para> + <para>If no time unit is specified, generally seconds are assumed, but some exceptions exist and are marked as + such. In a few cases <literal>ns</literal>, <literal>nsec</literal> is accepted too, where the granularity of the + time span permits this. Parsing is generally locale-independent, non-English names for the time units are not + accepted.</para> <para>Examples for valid time span specifications:</para> @@ -110,36 +109,36 @@ <programlisting>Fri 2012-11-23 23:02:15 CET</programlisting> - <para>The weekday is printed according to the locale choice of the - user.</para> + <para>The weekday is printed in the abbreviated English language form. The formatting is locale-independent.</para> + + <para>In some cases timestamps are shown in the UTC timezone instead of the local timezone, which is indicated via + the <literal>UTC</literal> timezone specifier in the output.</para> + + <para>In some cases timestamps are shown with microsecond granularity. In this case the sub-second remainder is + separated by a full stop from the seconds component.</para> </refsect1> <refsect1> <title>Parsing Timestamps</title> - <para>When parsing systemd will accept a similar timestamp syntax, - but excluding any timezone specification (this limitation might be - removed eventually). The weekday specification is optional, but - when the weekday is specified it must either be in the abbreviated - (<literal>Wed</literal>) or non-abbreviated - (<literal>Wednesday</literal>) English language form (case does - not matter), and is not subject to the locale choice of the user. - Either the date, or the time part may be omitted, in which case - the current date or 00:00:00, respectively, is assumed. The seconds - component of the time may also be omitted, in which case ":00" is - assumed. Year numbers may be specified in full or may be - abbreviated (omitting the century).</para> - - <para>A timestamp is considered invalid if a weekday is specified - and the date does not actually match the specified day of the - week.</para> + <para>When parsing, systemd will accept a similar syntax, but expects no timezone specification, unless it is given + as the literal string <literal>UTC</literal> (for the UTC timezone) or is specified to be the locally configured + timezone. Other timezones than the local and UTC are not supported. The weekday specification is optional, but when + the weekday is specified, it must either be in the abbreviated (<literal>Wed</literal>) or non-abbreviated + (<literal>Wednesday</literal>) English language form (case does not matter), and is not subject to the locale + choice of the user. Either the date, or the time part may be omitted, in which case the current date or 00:00:00, + respectively, is assumed. The seconds component of the time may also be omitted, in which case ":00" is + assumed. Year numbers may be specified in full or may be abbreviated (omitting the century).</para> + + <para>A timestamp is considered invalid if a weekday is specified and the date does not match the specified day of + the week.</para> <para>When parsing, systemd will also accept a few special placeholders instead of timestamps: <literal>now</literal> may be used to refer to the current time (or of the invocation of the command that is currently executed). <literal>today</literal>, - <literal>yesterday</literal>, <literal>tomorrow</literal> refer to - 00:00:00 of the current day, the day before or the next day, + <literal>yesterday</literal>, and <literal>tomorrow</literal> refer to + 00:00:00 of the current day, the day before, or the next day, respectively.</para> <para>When parsing, systemd will also accept relative time @@ -157,39 +156,41 @@ 00:00.</para> <para>Examples for valid timestamps and their normalized form - (assuming the current time was 2012-11-23 18:15:22):</para> + (assuming the current time was 2012-11-23 18:15:22 and the timezone + was UTC+8, for example TZ=Asia/Shanghai):</para> <programlisting>Fri 2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13 2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13 - 2012-11-23 → Fri 2012-11-23 00:00:00 - 12-11-23 → Fri 2012-11-23 00:00:00 - 11:12:13 → Fri 2012-11-23 11:12:13 - 11:12 → Fri 2012-11-23 11:12:00 - now → Fri 2012-11-23 18:15:22 - today → Fri 2012-11-23 00:00:00 - yesterday → Fri 2012-11-22 00:00:00 - tomorrow → Fri 2012-11-24 00:00:00 - +3h30min → Fri 2012-11-23 21:45:22 - -5s → Fri 2012-11-23 18:15:17 - 11min ago → Fri 2012-11-23 18:04:22 - @1395716396 → Tue 2014-03-25 03:59:56</programlisting> - - <para>Note that timestamps printed by systemd will not be parsed - correctly by systemd, as the timezone specification is not - accepted, and printing timestamps is subject to locale settings - for the weekday while parsing only accepts English weekday - names.</para> - - <para>In some cases, systemd will display a relative timestamp - (relative to the current time, or the time of invocation of the - command) instead or in addition to an absolute timestamp as - described above. A relative timestamp is formatted as - follows:</para> - - <para>2 months 5 days ago</para> - - <para>Note that any relative timestamp will also parse correctly - where a timestamp is expected. (see above)</para> +2012-11-23 11:12:13 UTC → Fri 2012-11-23 19:12:13 + 2012-11-23 → Fri 2012-11-23 00:00:00 + 12-11-23 → Fri 2012-11-23 00:00:00 + 11:12:13 → Fri 2012-11-23 11:12:13 + 11:12 → Fri 2012-11-23 11:12:00 + now → Fri 2012-11-23 18:15:22 + today → Fri 2012-11-23 00:00:00 + today UTC → Fri 2012-11-23 16:00:00 + yesterday → Fri 2012-11-22 00:00:00 + tomorrow → Fri 2012-11-24 00:00:00 + +3h30min → Fri 2012-11-23 21:45:22 + -5s → Fri 2012-11-23 18:15:17 + 11min ago → Fri 2012-11-23 18:04:22 + @1395716396 → Tue 2014-03-25 03:59:56</programlisting> + + <para>Note that timestamps displayed by remote systems with a non-matching timezone are usually not parsable + locally, as the timezone component is not understood (unless it happens to be <literal>UTC</literal>).</para> + + <para>Timestamps may also be specified with microsecond granularity. The sub-second remainder is expected separated + by a full stop from the seconds component. Example:</para> + + <programlisting>2014-03-25 03:59:56.654563</programlisting> + + <para>In some cases, systemd will display a relative timestamp (relative to the current time, or the time of + invocation of the command) instead of or in addition to an absolute timestamp as described above. A relative + timestamp is formatted as follows:</para> + + <programlisting>2 months 5 days ago</programlisting> + + <para>Note that a relative timestamp is also accepted where a timestamp is expected (see above).</para> </refsect1> <refsect1> @@ -209,8 +210,8 @@ should consist of one or more English language weekday names, either in the abbreviated (Wed) or non-abbreviated (Wednesday) form (case does not matter), separated by commas. Specifying two - weekdays separated by <literal>-</literal> refers to a range of - continuous weekdays. <literal>,</literal> and <literal>-</literal> + weekdays separated by <literal>..</literal> refers to a range of + continuous weekdays. <literal>,</literal> and <literal>..</literal> may be combined freely.</para> <para>In the date and time specifications, any component may be @@ -218,15 +219,22 @@ match. Alternatively, each component can be specified as a list of values separated by commas. Values may also be suffixed with <literal>/</literal> and a repetition value, which indicates that - the value and all values plus multiples of the repetition value - are matched.</para> + the value itself and the value plus all multiples of the repetition value + are matched. Each component may also contain a range of values + separated by <literal>..</literal>.</para> + + <para>The seconds component may contain decimal fractions both in + the value and the repetition. All fractions are rounded to 6 + decimal places.</para> <para>Either time or date specification may be omitted, in which case the current day and 00:00:00 is implied, respectively. If the second component is not specified, <literal>:00</literal> is assumed.</para> - <para>Timezone names may not be specified.</para> + <para>A timezone specification is not expected, unless it is given as the literal string <literal>UTC</literal>, or + the local timezone, similar to the supported syntax of timestamps (see above). Non-local timezones except for UTC + are not supported.</para> <para>The special expressions <literal>minutely</literal>, @@ -242,40 +250,45 @@ <literal>*-*-01 00:00:00</literal>, <literal>Mon *-*-* 00:00:00</literal>, <literal>*-01-01 00:00:00</literal>, - <literal>*-01,04,07,10-01 00:00:0</literal> and - <literal>*-01,07-01 00:00:00</literal> respectively. + <literal>*-01,04,07,10-01 00:00:00</literal> and + <literal>*-01,07-01 00:00:00</literal>, respectively. </para> <para>Examples for valid timestamps and their normalized form:</para> -<programlisting> Sat,Thu,Mon-Wed,Sat-Sun → Mon-Thu,Sat,Sun *-*-* 00:00:00 - Mon,Sun 12-*-* 2,1:23 → Mon,Sun 2012-*-* 01,02:23:00 - Wed *-1 → Wed *-*-01 00:00:00 - Wed-Wed,Wed *-1 → Wed *-*-01 00:00:00 - Wed, 17:48 → Wed *-*-* 17:48:00 -Wed-Sat,Tue 12-10-15 1:2:3 → Tue-Sat 2012-10-15 01:02:03 - *-*-7 0:0:0 → *-*-07 00:00:00 - 10-15 → *-10-15 00:00:00 - monday *-12-* 17:00 → Mon *-12-* 17:00:00 - Mon,Fri *-*-3,1,2 *:30:45 → Mon,Fri *-*-01,02,03 *:30:45 - 12,14,13,12:20,10,30 → *-*-* 12,13,14:10,20,30:00 - mon,fri *-1/2-1,3 *:30:45 → Mon,Fri *-01/2-01,03 *:30:45 - 03-05 08:05:40 → *-03-05 08:05:40 - 08:05:40 → *-*-* 08:05:40 - 05:40 → *-*-* 05:40:00 - Sat,Sun 12-05 08:05:40 → Sat,Sun *-12-05 08:05:40 - Sat,Sun 08:05:40 → Sat,Sun *-*-* 08:05:40 - 2003-03-05 05:40 → 2003-03-05 05:40:00 - 2003-03-05 → 2003-03-05 00:00:00 - 03-05 → *-03-05 00:00:00 - hourly → *-*-* *:00:00 - daily → *-*-* 00:00:00 - monthly → *-*-01 00:00:00 - weekly → Mon *-*-* 00:00:00 - yearly → *-01-01 00:00:00 - annually → *-01-01 00:00:00 - *:2/3 → *-*-* *:02/3:00</programlisting> +<programlisting> Sat,Thu,Mon..Wed,Sat..Sun → Mon..Thu,Sat,Sun *-*-* 00:00:00 + Mon,Sun 12-*-* 2,1:23 → Mon,Sun 2012-*-* 01,02:23:00 + Wed *-1 → Wed *-*-01 00:00:00 + Wed..Wed,Wed *-1 → Wed *-*-01 00:00:00 + Wed, 17:48 → Wed *-*-* 17:48:00 +Wed..Sat,Tue 12-10-15 1:2:3 → Tue..Sat 2012-10-15 01:02:03 + *-*-7 0:0:0 → *-*-07 00:00:00 + 10-15 → *-10-15 00:00:00 + monday *-12-* 17:00 → Mon *-12-* 17:00:00 + Mon,Fri *-*-3,1,2 *:30:45 → Mon,Fri *-*-01,02,03 *:30:45 + 12,14,13,12:20,10,30 → *-*-* 12,13,14:10,20,30:00 + 12..14:10,20,30 → *-*-* 12,13,14:10,20,30:00 + mon,fri *-1/2-1,3 *:30:45 → Mon,Fri *-01/2-01,03 *:30:45 + 03-05 08:05:40 → *-03-05 08:05:40 + 08:05:40 → *-*-* 08:05:40 + 05:40 → *-*-* 05:40:00 + Sat,Sun 12-05 08:05:40 → Sat,Sun *-12-05 08:05:40 + Sat,Sun 08:05:40 → Sat,Sun *-*-* 08:05:40 + 2003-03-05 05:40 → 2003-03-05 05:40:00 + 05:40:23.4200004/3.1700005 → 05:40:23.420000/3.170001 + 2003-02..04-05 → 2003-02,03,04-05 00:00:00 + 2003-03-05 05:40 UTC → 2003-03-05 05:40:00 UTC + 2003-03-05 → 2003-03-05 00:00:00 + 03-05 → *-03-05 00:00:00 + hourly → *-*-* *:00:00 + daily → *-*-* 00:00:00 + daily UTC → *-*-* 00:00:00 UTC + monthly → *-*-01 00:00:00 + weekly → Mon *-*-* 00:00:00 + yearly → *-01-01 00:00:00 + annually → *-01-01 00:00:00 + *:2/3 → *-*-* *:02/3:00</programlisting> <para>Calendar events are used by timer units, see <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry> diff --git a/man/systemd.timer.xml b/man/systemd.timer.xml index 20890f2270..4fe140e4bc 100644 --- a/man/systemd.timer.xml +++ b/man/systemd.timer.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -74,18 +74,28 @@ <filename>foo.service</filename>. The unit to activate may be controlled by <varname>Unit=</varname> (see below).</para> - <para>Unless <varname>DefaultDependencies=</varname> is set to - <option>false</option>, all timer units will implicitly have - dependencies of type <varname>Conflicts=</varname> and - <varname>Before=</varname> on <filename>shutdown.target</filename> - to ensure that they are stopped cleanly prior to system shutdown. - Timer units with at least one <varname>OnCalendar=</varname> - directive will have an additional <varname>After=</varname> - dependency on <filename>timer-sync.target</filename> to avoid - being started before the system clock has been correctly set. Only - timer units involved with early boot or late system shutdown - should disable the <varname>DefaultDependencies=</varname> - option.</para> + <para>Note that in case the unit to activate is already active at the time the timer elapses it is not restarted, + but simply left running. There is no concept of spawning new service instances in this case. Due to this, services + with <varname>RemainAfterExit=</varname> set (which stay around continuously even after the service's main process + exited) are usually not suitable for activation via repetitive timers, as they will only be activated once, and + then stay around forever.</para> + </refsect1> + + <refsect1> + <title>Automatic Dependencies</title> + + <para>Timer units automatically gain a <varname>Before=</varname> + dependency on the service they are supposed to activate.</para> + + <para>Unless <varname>DefaultDependencies=</varname> in the <literal>[Unit]</literal> section is set to + <option>false</option>, all timer units will implicitly have dependencies of type <varname>Requires=</varname> and + <varname>After=</varname> on <filename>sysinit.target</filename>, a dependency of type <varname>Before=</varname> + on <filename>timers.target</filename>, as well as <varname>Conflicts=</varname> and <varname>Before=</varname> on + <filename>shutdown.target</filename> to ensure that they are stopped cleanly prior to system shutdown. Timer units + with at least one <varname>OnCalendar=</varname> directive will have an additional <varname>After=</varname> + dependency on <filename>timer-sync.target</filename> to avoid being started before the system clock has been + correctly set. Only timer units involved with early boot or late system shutdown should disable the + <varname>DefaultDependencies=</varname> option.</para> </refsect1> <refsect1> @@ -127,7 +137,7 @@ boot-up. The argument may also include time units. Example: "OnBootSec=5h 30min" means 5 hours and 30 minutes after boot-up. For details about the syntax of time spans, see - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> <para>If a timer configured with <varname>OnBootSec=</varname> or <varname>OnStartupSec=</varname> is already in the past @@ -180,13 +190,12 @@ <varname>OnUnitInactiveSec=</varname> and ending the time configured with <varname>AccuracySec=</varname> later. Within this time window, the expiry time will be placed at a - host-specific, randomized but stable position that is + host-specific, randomized, but stable position that is synchronized between all local timer units. This is done in - order to distribute the wake-up time in networked - installations, as well as optimizing power consumption to - suppress unnecessary CPU wake-ups. To get best accuracy, set - this option to 1us. Note that the timer is still subject to - the timer slack configured via + order to optimize power consumption to suppress unnecessary + CPU wake-ups. To get best accuracy, set this option to + 1us. Note that the timer is still subject to the timer slack + configured via <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>'s <varname>TimerSlackNSec=</varname> setting. See <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> @@ -194,6 +203,38 @@ this value as high as possible and as low as necessary.</para></listitem> </varlistentry> + + <varlistentry> + <term><varname>RandomizedDelaySec=</varname></term> + + <listitem><para>Delay the timer by a randomly selected, evenly + 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 + 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 + at the same time, possibly resulting in resource + congestion. Note the relation to + <varname>AccuracySec=</varname> above: the latter allows the + service manager to coalesce timer events within a specified + time range in order to minimize wakeups, the former does the + opposite: it stretches timer events over a time range, to make + it unlikely that they fire simultaneously. If + <varname>RandomizedDelaySec=</varname> and + <varname>AccuracySec=</varname> are used in conjunction, first + the randomized delay is added, and then the result is + possibly further shifted to coalesce it with other timer + events happening on the system. As mentioned above + <varname>AccuracySec=</varname> defaults to 1min and + <varname>RandomizedDelaySec=</varname> to 0, thus encouraging + coalescing of timer events. In order to optimally stretch + timer events over a certain range of time, make sure to set + <varname>RandomizedDelaySec=</varname> to a higher value, and + <varname>AccuracySec=1us</varname>.</para></listitem> + </varlistentry> + <varlistentry> <term><varname>Unit=</varname></term> @@ -218,7 +259,8 @@ during the time when the timer was inactive. This is useful to catch up on missed runs of the service when the machine was off. Note that this setting only has an effect on timers - configured with <varname>OnCalendar=</varname>. + configured with <varname>OnCalendar=</varname>. Defaults + to <varname>false</varname>. </para></listitem> </varlistentry> @@ -233,6 +275,24 @@ again after any work that is to be done is finished. Defaults to <varname>false</varname>.</para></listitem> </varlistentry> + + <varlistentry> + <term><varname>RemainAfterElapse=</varname></term> + + <listitem><para>Takes a boolean argument. If true, an elapsed + timer will stay loaded, and its state remains queriable. If + false, an elapsed timer unit that cannot elapse anymore is + unloaded. Turning this off is particularly useful for + transient timer units that shall disappear after they first + elapse. Note that this setting has an effect on repeatedly + starting a timer unit that only elapses once: if + <varname>RemainAfterElapse=</varname> is on, it will not be + started again, and is guaranteed to elapse only once. However, + if <varname>RemainAfterElapse=</varname> is off, it might be + started again if it is already elapsed, and thus be triggered + multiple times. Defaults to + <varname>yes</varname>.</para></listitem> + </varlistentry> </variablelist> </refsect1> diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 0aa1eeac77..79bdb2cd38 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!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" > @@ -60,25 +60,22 @@ <filename><replaceable>target</replaceable>.target</filename>, <filename><replaceable>path</replaceable>.path</filename>, <filename><replaceable>timer</replaceable>.timer</filename>, - <filename><replaceable>snapshot</replaceable>.snapshot</filename>, <filename><replaceable>slice</replaceable>.slice</filename>, <filename><replaceable>scope</replaceable>.scope</filename></para> <para><literallayout><filename>/etc/systemd/system/*</filename> <filename>/run/systemd/system/*</filename> <filename>/usr/lib/systemd/system/*</filename> -<filename>...</filename> +<filename>…</filename> </literallayout></para> - <para><literallayout><filename>$XDG_CONFIG_HOME/systemd/user/*</filename> -<filename>$HOME/.config/systemd/user/*</filename> + <para><literallayout><filename>~/.config/systemd/user/*</filename> <filename>/etc/systemd/user/*</filename> <filename>$XDG_RUNTIME_DIR/systemd/user/*</filename> <filename>/run/systemd/user/*</filename> -<filename>$XDG_DATA_HOME/systemd/user/*</filename> -<filename>$HOME/.local/share/systemd/user/*</filename> +<filename>~/.local/share/systemd/user/*</filename> <filename>/usr/lib/systemd/user/*</filename> -<filename>...</filename> +<filename>…</filename> </literallayout></para> </refsynopsisdiv> @@ -90,7 +87,7 @@ swap file or partition, a start-up target, a watched file system path, a timer controlled and supervised by <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - a temporary system state snapshot, a resource management slice or + a resource management slice or a group of externally created processes. The syntax is inspired by <ulink url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG @@ -115,8 +112,7 @@ <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>. </para> @@ -148,60 +144,71 @@ <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: "50" refers to 50 seconds; "2min - 200ms" refers to 2 minutes plus 200 milliseconds, i.e. 120200ms. - The following time units are understood: s, min, h, d, w, ms, us. - For details see + <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>Empty lines and lines starting with # or ; are - ignored. This may be used for commenting. Lines ending - in a backslash are concatenated with the following - line while reading and the backslash is replaced by a - space character. This may be used to wrap long lines.</para> - - <para>Along with a unit file <filename>foo.service</filename>, the - directory <filename>foo.service.wants/</filename> may exist. All - unit files symlinked from such a directory are implicitly added as - dependencies of type <varname>Wants=</varname> to the unit. This - is useful to hook units into the start-up of other units, without - having to modify their unit files. For details about the semantics - of <varname>Wants=</varname>, see below. The preferred way to - create symlinks in the <filename>.wants/</filename> directory of a - unit file is with the <command>enable</command> command of the + <para>Empty lines and lines starting with <literal>#</literal> or <literal>;</literal> are + ignored. This may be used for commenting. Lines ending in a backslash are concatenated with the + following line while reading and the backslash is replaced by a space character. This may be + used to wrap long lines.</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 + <filename>dbus-org.freedesktop.network1.service</filename>, created during installation as the + symlink <filename>/usr/lib/systemd/system/dbus-org.freedesktop.network1.service</filename>. In + addition, unit files may specify aliases through the <varname>Alias=</varname> directive in the + [Install] section; those aliases are only effective when the unit is enabled. When the unit is + enabled, symlinks will be created for those names, and removed when the unit is disabled. For + example, <filename>reboot.target</filename> specifies + <varname>Alias=ctrl-alt-del.target</varname>, so when enabled it will be invoked whenever + CTRL+ALT+DEL is pressed. Alias names may be used in commands like <command>enable</command>, + <command>disable</command>, <command>start</command>, <command>stop</command>, + <command>status</command>, …, and in unit dependency directives <varname>Wants=</varname>, + <varname>Requires=</varname>, <varname>Before=</varname>, <varname>After=</varname>, …, with the + limitation that aliases specified through <varname>Alias=</varname> are only effective when the + unit is enabled. Aliases cannot be used with the <command>preset</command> command.</para> + + <para>Along with a unit file <filename>foo.service</filename>, the directory + <filename>foo.service.wants/</filename> may exist. All unit files symlinked from such a + directory are implicitly added as dependencies of type <varname>Wants=</varname> to the unit. + This is useful to hook units into the start-up of other units, without having to modify their + unit files. For details about the semantics of <varname>Wants=</varname>, see below. The + preferred way to create symlinks in the <filename>.wants/</filename> directory of a unit file is + with the <command>enable</command> command of the <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - tool which reads information from the [Install] section of unit - files (see below). A similar functionality exists for - <varname>Requires=</varname> type dependencies as well, the - directory suffix is <filename>.requires/</filename> in this - case.</para> - - <para>Along with a unit file <filename>foo.service</filename>, a - directory <filename>foo.service.d/</filename> may exist. All files - with the suffix <literal>.conf</literal> from this directory will - be parsed after the file itself is parsed. This is useful to alter - or add configuration settings to a unit, without having to modify - their unit files. Make sure that the file that is included has the - appropriate section headers before any directive. Note that for - instanced units this logic will first look for the instance - <literal>.d/</literal> subdirectory and read its - <literal>.conf</literal> files, followed by the template - <literal>.d/</literal> subdirectory and reads its - <literal>.conf</literal> files.</para> - - <!-- Note that we do not document .include here, as we - consider it mostly obsolete, and want people to - use .d/ drop-ins instead. --> - - <para>Note that while systemd offers a flexible dependency system - between units it is recommended to use this functionality only - sparingly and instead rely on techniques such as bus-based or - socket-based activation which make dependencies implicit, - resulting in a both simpler and more flexible system.</para> + tool which reads information from the [Install] section of unit files (see below). A similar + functionality exists for <varname>Requires=</varname> type dependencies as well, the directory + suffix is <filename>.requires/</filename> in this case.</para> + + <para>Along with a unit file <filename>foo.service</filename>, a "drop-in" directory + <filename>foo.service.d/</filename> may exist. All files with the suffix + <literal>.conf</literal> from this directory will be parsed after the file itself is + parsed. This is useful to alter or add configuration settings for a unit, without having to + modify unit files. Each drop-in file must have appropriate section headers. Note that for + instantiated units, this logic will first look for the instance <literal>.d/</literal> + subdirectory and read its <literal>.conf</literal> files, followed by the template + <literal>.d/</literal> subdirectory and the <literal>.conf</literal> files there. Also note that + settings from the <literal>[Install]</literal> section are not honored in drop-in unit files, + and have no effect.</para> + + <para>In addition to <filename>/etc/systemd/system</filename>, the drop-in <literal>.d</literal> + directories for system services can be placed in <filename>/usr/lib/systemd/system</filename> or + <filename>/run/systemd/system</filename> directories. Drop-in files in <filename>/etc</filename> + take precedence over those in <filename>/run</filename> which in turn take precedence over those + in <filename>/usr/lib</filename>. Drop-in files under any of these directories take precedence + over unit files wherever located. (Of course, since <filename>/run</filename> is temporary and + <filename>/usr/lib</filename> is for vendors, it is unlikely drop-ins should be used in either + of those places.)</para> + + <!-- Note that we do not document .include here, as we consider it mostly obsolete, and want + people to use .d/ drop-ins instead. --> <para>Some unit names reflect paths existing in the file system namespace. Example: a device unit @@ -209,7 +216,7 @@ device node <filename noindex='true'>/dev/sda</filename> in the file system namespace. If this applies, a special way to escape the path name is used, so that the result is usable as part of a - filename. Basically, given a path, "/" is replaced by "-" and all + filename. Basically, given a path, "/" is replaced by "-", and all other characters which are not ASCII alphanumerics are replaced by C-style "\x2d" escapes (except that "_" is never replaced and "." is only replaced when it would be the first character in the @@ -256,17 +263,40 @@ </refsect1> <refsect1> - <title>Unit Load Path</title> + <title>Automatic Dependencies</title> + + <para>Note that while systemd offers a flexible dependency system + between units it is recommended to use this functionality only + sparingly and instead rely on techniques such as bus-based or + socket-based activation which make dependencies implicit, + resulting in a both simpler and more flexible system.</para> + + <para>A number of unit dependencies are automatically established, + depending on unit configuration. On top of that, for units with + <varname>DefaultDependencies=yes</varname> (the default) a couple + of additional dependencies are added. The precise effect of + <varname>DefaultDependencies=yes</varname> depends on the unit + type (see below).</para> + + <para>If <varname>DefaultDependencies=yes</varname> is set, units + that are referenced by other units of type + <filename>.target</filename> via a <varname>Wants=</varname> or + <varname>Requires=</varname> dependency might automatically gain + an <varname>Before=</varname> dependency too. See + <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para> + </refsect1> + + <refsect1> + <title>Unit File Load Path</title> <para>Unit files are loaded from a set of paths determined during compilation, described in the two tables below. Unit files found in directories listed earlier override files with the same name in directories lower in the list.</para> - <para>When systemd is running in user mode - (<option>--user</option>) and the variable - <varname>$SYSTEMD_UNIT_PATH</varname> is set, the contents of this - variable overrides the unit load path. If + <para>When the variable <varname>$SYSTEMD_UNIT_PATH</varname> is set, + the contents of this variable overrides the unit load path. If <varname>$SYSTEMD_UNIT_PATH</varname> ends with an empty component (<literal>:</literal>), the usual unit load path will be appended to the contents of the variable.</para> @@ -365,7 +395,7 @@ <refsect1> <title>[Unit] Section Options</title> - <para>Unit file may include a [Unit] section, which carries + <para>The unit file may include a [Unit] section, which carries generic information about the unit that is not dependent on the type of unit:</para> @@ -424,7 +454,7 @@ with <varname>After=</varname> or <varname>Before=</varname>, then both units will be started simultaneously and without any delay between them if <filename>foo.service</filename> is - activated. Often it is a better choice to use + activated. Often, it is a better choice to use <varname>Wants=</varname> instead of <varname>Requires=</varname> in order to achieve a system that is more robust when dealing with failing services.</para> @@ -432,32 +462,14 @@ <para>Note that dependencies of this type may also be configured outside of the unit configuration file by adding a symlink to a <filename>.requires/</filename> directory - accompanying the unit file. For details see + accompanying the unit file. For details, see above.</para></listitem> </varlistentry> <varlistentry> - <term><varname>RequiresOverridable=</varname></term> - - <listitem><para>Similar to <varname>Requires=</varname>. - Dependencies listed in <varname>RequiresOverridable=</varname> - which cannot be fulfilled or fail to start are ignored if the - startup was explicitly requested by the user. If the start-up - was pulled in indirectly by some dependency or automatic - start-up of units that is not requested by the user, this - dependency must be fulfilled and otherwise the transaction - fails. Hence, this option may be used to configure - dependencies that are normally honored unless the user - explicitly starts up the unit, in which case whether they - failed or not is irrelevant.</para></listitem> - - </varlistentry> - <varlistentry> <term><varname>Requisite=</varname></term> - <term><varname>RequisiteOverridable=</varname></term> - <listitem><para>Similar to <varname>Requires=</varname> and - <varname>RequiresOverridable=</varname>, respectively. + <listitem><para>Similar to <varname>Requires=</varname>. However, if the units listed here are not started already, they will not be started and the transaction will fail immediately. </para></listitem> @@ -554,14 +566,17 @@ between them are shut down, the inverse of the start-up order is applied. i.e. if a unit is configured with <varname>After=</varname> on another unit, the former is - stopped before the latter if both are shut down. If one unit - with an ordering dependency on another unit is shut down while - the latter is started up, the shut down is ordered before the - start-up regardless of whether the ordering dependency is - actually of type <varname>After=</varname> or - <varname>Before=</varname>. If two units have no ordering - dependencies between them, they are shut down or started up - simultaneously, and no ordering takes place. + stopped before the latter if both are shut down. Given two units + with any ordering dependency between them, if one unit is shut + down and the other is started up, the shutdown is ordered + before the start-up. It doesn't matter if the ordering + dependency is <varname>After=</varname> or + <varname>Before=</varname>. It also doesn't matter which of the + two is shut down, as long as one is shut down and the other is + started up. The shutdown is ordered before the start-up in all + cases. If two units have no ordering dependencies between them, + they are shut down or started up simultaneously, and no ordering + takes place. </para></listitem> </varlistentry> @@ -598,7 +613,7 @@ <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details). If a unit that has this setting set is started, its processes will see the same <filename>/tmp</filename>, - <filename>/tmp/var</filename> and network namespace as one + <filename>/var/tmp</filename> and network namespace as one listed unit that is started. If multiple listed units are already started, it is not defined which namespace is joined. Note that this setting only has an effect if @@ -654,21 +669,11 @@ </varlistentry> <varlistentry> - <term><varname>IgnoreOnSnapshot=</varname></term> - - <listitem><para>Takes a boolean argument. If - <option>true</option>, this unit will not be included in - snapshots. Defaults to <option>true</option> for device and - snapshot units, <option>false</option> for the - others.</para></listitem> - </varlistentry> - - <varlistentry> <term><varname>StopWhenUnneeded=</varname></term> <listitem><para>Takes a boolean argument. If <option>true</option>, this unit will be stopped when it is no - longer used. Note that in order to minimize the work to be + longer used. Note that, in order to minimize the work to be executed, systemd will not stop units by default unless they are conflicting with other units, or the user explicitly requested their shut down. If this option is set, a unit will @@ -730,20 +735,14 @@ <term><varname>JobTimeoutAction=</varname></term> <term><varname>JobTimeoutRebootArgument=</varname></term> - <listitem><para>When a job for this unit is queued a time-out - may be configured. If this 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 0 (job timeouts disabled), except for device units. NB: - this timeout is independent from any unit-specific timeout - (for example, the timeout set with - <varname>StartTimeoutSec=</varname> in service units) as the - job timeout has 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><para>When a job for this unit is queued, a time-out may be configured. If this 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 disabled), + except for device units. NB: this timeout is independent from any unit-specific timeout (for example, the + timeout set with <varname>TimeoutStartSec=</varname> in service units) as the job timeout has 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> <para><varname>JobTimeoutAction=</varname> optionally configures an additional @@ -762,6 +761,58 @@ </varlistentry> <varlistentry> + <term><varname>StartLimitIntervalSec=</varname></term> + <term><varname>StartLimitBurst=</varname></term> + + <listitem><para>Configure unit start rate limiting. By default, units which are started more than 5 times + within 10 seconds are not permitted to start any more times until the 10 second interval ends. With these two + options, this rate limiting may be modified. Use <varname>StartLimitIntervalSec=</varname> to configure the + checking interval (defaults to <varname>DefaultStartLimitIntervalSec=</varname> in manager configuration file, + set to 0 to disable any kind of rate limiting). Use <varname>StartLimitBurst=</varname> to configure how many + starts per interval are allowed (defaults to <varname>DefaultStartLimitBurst=</varname> in manager + configuration file). These configuration options are particularly useful in conjunction with the service + setting <varname>Restart=</varname> (see + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>); however, + they apply to all kinds of starts (including manual), not just those triggered by the + <varname>Restart=</varname> logic. Note that units which are configured for <varname>Restart=</varname> and + which reach the start limit are not attempted to be restarted anymore; however, they may still be restarted + manually at a later point, from which point on, the restart logic is again activated. Note that + <command>systemctl reset-failed</command> will cause the restart rate counter for a service to be flushed, + which is useful if the administrator wants to manually start a unit and the start limit interferes with + that. Note that this rate-limiting is enforced after any unit condition checks are executed, and hence unit + activations with failing conditions are not counted by this rate limiting. Slice, target, device and scope + units do not enforce this setting, as they are unit types whose activation may either never fail, or may + succeed only a single time.</para></listitem> + </varlistentry> + + <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> + </varlistentry> + + <varlistentry> + <term><varname>RebootArgument=</varname></term> + <listitem><para>Configure the optional argument for the + <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call if + <varname>StartLimitAction=</varname> or a service's <varname>FailureAction=</varname> is a reboot action. This + works just like the optional argument to <command>systemctl reboot</command> command.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>ConditionArchitecture=</varname></term> <term><varname>ConditionVirtualization=</varname></term> <term><varname>ConditionHost=</varname></term> @@ -781,18 +832,19 @@ <term><varname>ConditionFileNotEmpty=</varname></term> <term><varname>ConditionFileIsExecutable=</varname></term> - <!-- We don't document ConditionNull= - here as it is not particularly + <!-- We do not document ConditionNull= + here, as it is not particularly useful and probably just confusing. --> - <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 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.</para> + <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> <para><varname>ConditionArchitecture=</varname> may be used to check whether the system is running on a specific @@ -856,7 +908,8 @@ <varname>lxc</varname>, <varname>lxc-libvirt</varname>, <varname>systemd-nspawn</varname>, - <varname>docker</varname> to test + <varname>docker</varname>, + <varname>rkt</varname> to test against a specific implementation. See <citerefentry><refentrytitle>systemd-detect-virt</refentrytitle><manvolnum>1</manvolnum></citerefentry> for a full list of known virtualization technologies and their @@ -887,7 +940,7 @@ <para><varname>ConditionSecurity=</varname> may be used to check whether the given security module is enabled on the - system. Currently the recognized values values are + system. Currently, the recognized values are <varname>selinux</varname>, <varname>apparmor</varname>, <varname>ima</varname>, @@ -930,7 +983,7 @@ <filename>/var</filename> on the next following boot. Units making use of this condition should order themselves before <citerefentry><refentrytitle>systemd-update-done.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - to make sure they run before the stamp files's modification + to make sure they run before the stamp file's modification time gets reset indicating a completed update.</para> <para><varname>ConditionFirstBoot=</varname> takes a boolean @@ -1025,14 +1078,12 @@ <term><varname>AssertFileNotEmpty=</varname></term> <term><varname>AssertFileIsExecutable=</varname></term> - <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 it was triggered - by.</para></listitem> + <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> </varlistentry> <varlistentry> @@ -1044,6 +1095,7 @@ files. This functionality should not be used in normal units.</para></listitem> </varlistentry> + </variablelist> </refsect1> @@ -1051,27 +1103,24 @@ <refsect1> <title>[Install] Section Options</title> - <para>Unit file may include an <literal>[Install]</literal> - section, which carries installation information for the unit. This - section is not interpreted by - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> - during runtime. It is used exclusively by the - <command>enable</command> and <command>disable</command> commands - of the - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - tool during installation of a unit:</para> + <para>Unit files may include an <literal>[Install]</literal> section, which carries installation information for + the unit. This section is not interpreted by + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> during runtime; it is + used by the <command>enable</command> and <command>disable</command> commands of the + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> tool during + installation of a unit. Note that settings in the <literal>[Install]</literal> section may not appear in + <filename>.d/*.conf</filename> unit file drop-ins (see above).</para> <variablelist class='unit-directives'> <varlistentry> <term><varname>Alias=</varname></term> - <listitem><para>A space-separated list of additional names - this unit shall be installed under. The names listed here must - have the same suffix (i.e. type) as the unit file name. This - option may be specified more than once, in which case all - listed names are used. At installation time, - <command>systemctl enable</command> will create symlinks from - these names to the unit filename.</para></listitem> + <listitem><para>A space-separated list of additional names this unit shall be installed under. The names listed + here must have the same suffix (i.e. type) as the unit file name. This option may be specified more than once, + in which case all listed names are used. At installation time, <command>systemctl enable</command> will create + symlinks from these names to the unit filename. Note that not all unit types support such alias names, and this + setting is not supported for them. Specifically, mount, slice, swap, and automount units do not support + aliasing.</para></listitem> </varlistentry> <varlistentry> @@ -1195,7 +1244,7 @@ <row> <entry><literal>%f</literal></entry> <entry>Unescaped filename</entry> - <entry>This is either the unescaped instance name (if applicable) with <filename>/</filename> prepended (if applicable), or the prefix name prepended with <filename>/</filename>.</entry> + <entry>This is either the unescaped instance name (if applicable) with <filename>/</filename> prepended (if applicable), or the unescaped prefix name prepended with <filename>/</filename>.</entry> </row> <row> <entry><literal>%c</literal></entry> @@ -1220,22 +1269,22 @@ <row> <entry><literal>%u</literal></entry> <entry>User name</entry> - <entry>This is the name of the configured user of the unit, or (if none is set) the user running the systemd instance.</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> </row> <row> <entry><literal>%U</literal></entry> <entry>User UID</entry> - <entry>This is the numeric UID of the configured user of the unit, or (if none is set) the user running the systemd user instance. Note that this specifier is not available for units run by the systemd system instance (as opposed to those run by a systemd user instance), unless the user has been configured as a numeric UID in the first place or the configured user is the root user.</entry> + <entry>This is the numeric UID 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>%h</literal></entry> <entry>User home directory</entry> - <entry>This is the home directory of the configured user of the unit, or (if none is set) the user running the systemd user instance. Similar to <literal>%U</literal>, this specifier is not available for units run by the systemd system instance, unless the configured user is the root user.</entry> + <entry>This is the home directory of the user running the service manager instance. In case of the system manager this resolves to <literal>/root</literal>.</entry> </row> <row> <entry><literal>%s</literal></entry> <entry>User shell</entry> - <entry>This is the shell of the configured user of the unit, or (if none is set) the user running the systemd user instance. Similar to <literal>%U</literal>, this specifier is not available for units run by the systemd system instance, unless the configured user is the root user.</entry> + <entry>This is the shell of the user running the service manager instance. In case of the system manager this resolves to <literal>/bin/sh</literal>.</entry> </row> <row> <entry><literal>%m</literal></entry> @@ -1413,6 +1462,7 @@ PrivateTmp=yes</programlisting> cannot be reset to an empty list, so dependencies can only be added in drop-ins. If you want to remove dependencies, you have to override the entire unit.</para> + </example> </refsect1> @@ -1431,7 +1481,6 @@ PrivateTmp=yes</programlisting> <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>, diff --git a/man/systemd.xml b/man/systemd.xml index 4556d56969..7f24a874ed 100644 --- a/man/systemd.xml +++ b/man/systemd.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -119,7 +119,7 @@ run a system instance, even if the process ID is not 1, i.e. systemd is not run as init process. <option>--user</option> does the opposite, running a user instance even if the process - ID is 1. Normally it should not be necessary to pass these + ID is 1. Normally, it should not be necessary to pass these options, as systemd automatically detects the mode it is started in. These options are hence of little use except for debugging. Note that it is not supported booting and @@ -131,17 +131,48 @@ <varlistentry> <term><option>--dump-core</option></term> - <listitem><para>Dump core on crash. This switch has no effect - when run as user instance.</para></listitem> + <listitem><para>Enable core dumping on crash. This switch has + no effect when running as user instance. This setting may also + be enabled during boot on the kernel command line via the + <varname>systemd.dump_core=</varname> option, see + below.</para></listitem> </varlistentry> + + <varlistentry> + <term><option>--crash-vt=</option><replaceable>VT</replaceable></term> + + <listitem><para>Switch to a specific virtual console (VT) on + crash. Takes a positive integer in the range 1–63, or a + boolean argument. If an integer is passed, selects which VT to + switch to. If <constant>yes</constant>, the VT kernel messages + are written to is selected. If <constant>no</constant>, no VT + switch is attempted. This switch has no effect when running as + user instance. This setting may also be enabled during boot, + on the kernel command line via the + <varname>systemd.crash_vt=</varname> option, see + below.</para></listitem> + </varlistentry> + <varlistentry> <term><option>--crash-shell</option></term> - <listitem><para>Run shell on - crash. This switch has no effect when - run as user - instance.</para></listitem> + <listitem><para>Run a shell on crash. This switch has no + effect when running as user instance. This setting may also be + enabled during boot, on the kernel command line via the + <varname>systemd.crash_shell=</varname> option, see + below.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--crash-reboot</option></term> + + <listitem><para>Automatically reboot the system on crash. This + switch has no effect when running as user instance. This + setting may also be enabled during boot, on the kernel command + line via the <varname>systemd.crash_reboot=</varname> option, + see below.</para></listitem> </varlistentry> + <varlistentry> <term><option>--confirm-spawn</option></term> @@ -224,6 +255,14 @@ <option>inherit</option>.</para></listitem> </varlistentry> + <varlistentry> + <term><option>--machine-id=</option></term> + + <listitem><para>Override the machine-id set on the hard drive, + useful for network booting or for containers. May not be set + to all zeros.</para></listitem> + </varlistentry> + <xi:include href="standard-options.xml" xpointer="help" /> <xi:include href="standard-options.xml" xpointer="version" /> </variablelist> @@ -233,7 +272,7 @@ <title>Concepts</title> <para>systemd provides a dependency system between various - entities called "units" of 12 different types. Units encapsulate + entities called "units" of 11 different types. Units encapsulate various objects that are relevant for system boot-up and maintenance. The majority of units are configured in unit configuration files, whose syntax and basic set of options is @@ -258,12 +297,12 @@ <orderedlist> <listitem><para>Service units, which start and control daemons - and the processes they consist of. For details see + and the processes they consist of. For details, see <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> <listitem><para>Socket units, which encapsulate local IPC or network sockets in the system, useful for socket-based - activation. For details about socket units see + activation. For details about socket units, see <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, for details on socket-based activation and other forms of activation, see @@ -275,7 +314,7 @@ <listitem><para>Device units expose kernel devices in systemd and may be used to implement device-based activation. For - details see + details, see <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> <listitem><para>Mount units control mount points in the file @@ -287,12 +326,6 @@ boot-up. See <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> - <listitem><para>Snapshot units can be used to temporarily save - the state of the set of systemd units, which later may be - restored by activating the saved snapshot unit. For more - information see - <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> - <listitem><para>Timer units are useful for triggering activation of other units based on timers. You may find details in <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> @@ -348,7 +381,7 @@ <para>On boot systemd activates the target unit <filename>default.target</filename> whose job is to activate on-boot services and other on-boot units by pulling them in via - dependencies. Usually the unit name is just an alias (symlink) for + dependencies. Usually, the unit name is just an alias (symlink) for either <filename>graphical.target</filename> (for fully-featured boots into the UI) or <filename>multi-user.target</filename> (for limited console-only boots for use in embedded or server @@ -367,6 +400,8 @@ group information is maintained in the kernel, and is accessible via the file system hierarchy (beneath <filename>/sys/fs/cgroup/systemd/</filename>), or in tools such as + <citerefentry project='man-pages'><refentrytitle>systemd-cgls</refentrytitle><manvolnum>1</manvolnum></citerefentry> + or <citerefentry project='man-pages'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry> (<command>ps xawf -eo pid,user,cgroup,args</command> is particularly useful to list all processes and the systemd units @@ -415,7 +450,7 @@ <para>Units may be generated dynamically at boot and system manager reload time, for example based on other configuration - files or parameters passed on the kernel command line. For details see + files or parameters passed on the kernel command line. For details, see <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> <para>Systems which invoke systemd in a container or initrd @@ -529,9 +564,9 @@ <filename>ctrl-alt-del.target</filename> unit. This is mostly equivalent to <command>systemctl start ctl-alt-del.target</command>. If this signal is received more - often than 7 times per 2s an immediate reboot is triggered. + 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 + 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> @@ -573,7 +608,7 @@ <term><constant>SIGUSR2</constant></term> <listitem><para>When this signal is received the systemd - manager will log its complete state in human readable form. + manager will log its complete state in human-readable form. The data logged is the same as printed by <command>systemd-analyze dump</command>.</para></listitem> </varlistentry> @@ -800,13 +835,23 @@ </varlistentry> <varlistentry> + <term><varname>$SYSTEMD_COLORS</varname></term> + + <listitem><para>The value must be a boolean. Controls whether colorized output should be + generated. This can be specified to override the decision that <command>systemd</command> + makes based on <varname>$TERM</varname> and what the console is connected to.</para> + </listitem> + </varlistentry> + + <varlistentry> <term><varname>$LISTEN_PID</varname></term> <term><varname>$LISTEN_FDS</varname></term> + <term><varname>$LISTEN_FDNAMES</varname></term> <listitem><para>Set by systemd for supervised processes during socket-based activation. See <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for more information. </para></listitem> + for more information.</para></listitem> </varlistentry> <varlistentry> @@ -815,7 +860,7 @@ <listitem><para>Set by systemd for supervised processes for status and start-up completion notification. See <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for more information. </para></listitem> + for more information.</para></listitem> </varlistentry> </variablelist> </refsect1> @@ -852,50 +897,66 @@ <term><varname>systemd.dump_core=</varname></term> <listitem><para>Takes a boolean argument. If - <option>true</option>, systemd dumps core when it crashes. - Otherwise, no core dump is created. Defaults to - <option>true</option>.</para></listitem> + <option>yes</option>, the systemd manager (PID 1) dumps core + when it crashes. Otherwise, no core dump is created. Defaults + to <option>yes</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.crash_chvt=</varname></term> + + <listitem><para>Takes a positive integer, or a boolean + argument. If a positive integer (in the range 1–63) is + specified, the system manager (PID 1) will activate the specified + virtual terminal (VT) when it crashes. Defaults to + <constant>no</constant>, meaning that no such switch is + attempted. If set to <constant>yes</constant>, the VT the + kernel messages are written to is selected.</para></listitem> </varlistentry> <varlistentry> <term><varname>systemd.crash_shell=</varname></term> <listitem><para>Takes a boolean argument. If - <option>true</option>, systemd spawns a shell when it crashes. - Otherwise, no shell is spawned. Defaults to - <option>false</option>, for security reasons, as the shell is - not protected by any password + <option>yes</option>, the system manager (PID 1) spawns a + shell when it crashes, after a 10s delay. Otherwise, no shell + is spawned. Defaults to <option>no</option>, for security + reasons, as the shell is not protected by password authentication.</para></listitem> </varlistentry> <varlistentry> - <term><varname>systemd.crash_chvt=</varname></term> + <term><varname>systemd.crash_reboot=</varname></term> - <listitem><para>Takes an integer argument. If positive systemd - activates the specified virtual terminal when it crashes. - Defaults to <constant>-1</constant>.</para></listitem> + <listitem><para>Takes a boolean argument. If + <option>yes</option>, the system manager (PID 1) will reboot + the machine automatically when it crashes, after a 10s delay. + Otherwise, the system will hang indefinitely. Defaults to + <option>no</option>, in order to avoid a reboot loop. If + combined with <varname>systemd.crash_shell=</varname>, the + system is rebooted after the shell exits.</para></listitem> </varlistentry> <varlistentry> <term><varname>systemd.confirm_spawn=</varname></term> <listitem><para>Takes a boolean argument. If - <option>true</option>, asks for confirmation when spawning - processes. Defaults to - <option>false</option>.</para></listitem> + <option>yes</option>, the system manager (PID 1) asks for + confirmation when spawning processes. Defaults to + <option>no</option>.</para></listitem> </varlistentry> <varlistentry> <term><varname>systemd.show_status=</varname></term> <listitem><para>Takes a boolean argument or the constant - <constant>auto</constant>. If <option>true</option>, shows - terse service status updates on the console during bootup. - <constant>auto</constant> behaves like <option>false</option> - until a service fails or there is a significant delay in boot. - Defaults to <option>true</option>, unless - <option>quiet</option> is passed as kernel command line option - in which case it defaults to + <constant>auto</constant>. If <option>yes</option>, the + systemd manager (PID 1) shows terse service status updates on + the console during bootup. <constant>auto</constant> behaves + like <option>false</option> until a service fails or there is + a significant delay in boot. Defaults to + <option>yes</option>, unless <option>quiet</option> is passed + as kernel command line option, in which case it defaults to <constant>auto</constant>.</para></listitem> </varlistentry> @@ -933,6 +994,15 @@ </varlistentry> <varlistentry> + <term><varname>systemd.machine_id=</varname></term> + + <listitem><para>Takes a 32 character hex value to be + used for setting the machine-id. Intended mostly for + network booting where the same machine-id is desired + for every boot.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>quiet</varname></term> <listitem><para>Turn off status output at boot, much like @@ -956,25 +1026,27 @@ <varlistentry> <term><varname>emergency</varname></term> + <term><varname>rd.emergency</varname></term> <term><varname>-b</varname></term> <listitem><para>Boot into emergency mode. This is equivalent - to <varname>systemd.unit=emergency.target</varname> and - provided for compatibility reasons and to be easier to - type.</para></listitem> + to <varname>systemd.unit=emergency.target</varname> or + <varname>rd.systemd.unit=emergency.target</varname>, respectively, and + provided for compatibility reasons and to be easier to type.</para></listitem> </varlistentry> <varlistentry> <term><varname>rescue</varname></term> + <term><varname>rd.rescue</varname></term> <term><varname>single</varname></term> <term><varname>s</varname></term> <term><varname>S</varname></term> <term><varname>1</varname></term> <listitem><para>Boot into rescue mode. This is equivalent to - <varname>systemd.unit=rescue.target</varname> and provided for - compatibility reasons and to be easier to - type.</para></listitem> + <varname>systemd.unit=rescue.target</varname> or + <varname>rd.systemd.unit=rescue.target</varname>, respectively, and + provided for compatibility reasons and to be easier to type.</para></listitem> </varlistentry> <varlistentry> @@ -1011,7 +1083,7 @@ <listitem><para>Set the system locale to use. This overrides the settings in <filename>/etc/locale.conf</filename>. For - more information see + more information, see <citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> and <citerefentry project='man-pages'><refentrytitle>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry>. diff --git a/man/sysusers.d.xml b/man/sysusers.d.xml index 11cb83388f..18ee3800d6 100644 --- a/man/sysusers.d.xml +++ b/man/sysusers.d.xml @@ -113,7 +113,7 @@ u root 0 "Superuser" /root</programlisting> <varlistentry> <term><varname>m</varname></term> <listitem><para>Add a user to a group. If the user or group - are not existing yet, they will be implicitly + do not exist yet, they will be implicitly created.</para></listitem> </varlistentry> @@ -121,7 +121,7 @@ u root 0 "Superuser" /root</programlisting> <term><varname>r</varname></term> <listitem><para>Add a range of numeric UIDs/GIDs to the pool to allocate new UIDs and GIDs from. If no line of this type - is specified the range of UIDs/GIDs is set to some + is specified, the range of UIDs/GIDs is set to some compiled-in default. Note that both UIDs and GIDs are allocated from the same pool, in order to ensure that users and groups of the same name are likely to carry the same @@ -143,32 +143,32 @@ u root 0 "Superuser" /root</programlisting> all system and group names with the underscore, and avoiding too generic names.</para> - <para>For <varname>m</varname> lines this field should contain + <para>For <varname>m</varname> lines, this field should contain the user name to add to a group.</para> - <para>For lines of type <varname>r</varname> this field should + <para>For lines of type <varname>r</varname>, this field should be set to <literal>-</literal>.</para> </refsect2> <refsect2> <title>ID</title> - <para>For <varname>u</varname> and <varname>g</varname> the - numeric 32bit UID or GID of the user/group. Do not use IDs 65535 + <para>For <varname>u</varname> and <varname>g</varname>, the + numeric 32-bit UID or GID of the user/group. Do not use IDs 65535 or 4294967295, as they have special placeholder meanings. Specify <literal>-</literal> for automatic UID/GID allocation for the user or group. Alternatively, specify an absolute path - in the file system. In this case the UID/GID is read from the + in the file system. In this case, the UID/GID is read from the path's owner/group. This is useful to create users whose UID/GID match the owners of pre-existing files (such as SUID or SGID binaries).</para> - <para>For <varname>m</varname> lines this field should contain + <para>For <varname>m</varname> lines, this field should contain the group name to add to a user to.</para> - <para>For lines of type <varname>r</varname> this field should + <para>For lines of type <varname>r</varname>, this field should be set to a UID/GID range in the format - <literal>FROM-TO</literal> where both values are formatted as + <literal>FROM-TO</literal>, where both values are formatted as decimal ASCII numbers. Alternatively, a single UID/GID may be specified formatted as decimal ASCII numbers.</para> </refsect2> @@ -188,7 +188,7 @@ u root 0 "Superuser" /root</programlisting> <refsect2> <title>Home Directory</title> - <para>The home directory for a new system user. If omitted + <para>The home directory for a new system user. If omitted, defaults to the root directory. It is recommended to not unnecessarily specify home directories for system users, unless software strictly requires one to be set.</para> @@ -207,7 +207,7 @@ u root 0 "Superuser" /root</programlisting> <para>Note that <command>systemd-sysusers</command> will do nothing if the specified users or groups already exist, so - normally there no reason to override + normally, there is no reason to override <filename>sysusers.d</filename> vendor configuration, except to block certain users or groups from being created.</para> </refsect1> diff --git a/man/timedatectl.xml b/man/timedatectl.xml index 2d42b41d5e..415e2c799a 100644 --- a/man/timedatectl.xml +++ b/man/timedatectl.xml @@ -108,7 +108,7 @@ on. Note that whether network time synchronization is on simply reflects whether the <filename>systemd-timesyncd.service</filename> unit is - enabled. Even if this command shows the status as off a + enabled. Even if this command shows the status as off, a different service might still synchronize the clock with the network.</para></listitem> </varlistentry> @@ -166,12 +166,27 @@ <term><command>set-ntp [BOOL]</command></term> <listitem><para>Takes a boolean argument. Controls whether - network time synchronization is enabled (if available). This - enables or disables the - <filename>systemd-timesyncd.service</filename> unit. Note that - even if this command turns time synchronization off a - different system service might still synchronize the clock - with the network.</para></listitem> + network time synchronization is active and enabled (if + available). This enables and starts, or disables and stops the + <filename>systemd-timesyncd.service</filename> unit. It does + not affect the state of any other, unrelated network time + synchronization services that might be installed on the + system. This command is hence mostly equivalent to: + <command>systemctl enable --now + systemd-timesyncd.service</command> and <command>systemctl + disable --now systemd-timesyncd.service</command>, but is + protected by a different access policy.</para> + + <para>Note that even if time synchronization is turned off + with this command, another unrelated system service might + still synchronize the clock with the network. Also note that, + strictly speaking, + <filename>systemd-timesyncd.service</filename> does more than + just network time synchronization, as it ensures a monotonic + clock on systems without RTC even if no network is + available. See + <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details about this.</para></listitem> </varlistentry> </variablelist> diff --git a/man/timesyncd.conf.xml b/man/timesyncd.conf.xml index c883685c97..8c86fd0074 100644 --- a/man/timesyncd.conf.xml +++ b/man/timesyncd.conf.xml @@ -68,11 +68,13 @@ <refsect1> <title>Options</title> + <para>The following settings are configured in the <literal>[Time]</literal> section:</para> + <variablelist class='network-directives'> <varlistentry> <term><varname>NTP=</varname></term> - <listitem><para>A space separated list of NTP server host + <listitem><para>A space-separated list of NTP server host names or IP addresses. During runtime this list is combined with any per-interface NTP servers acquired from <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. @@ -84,7 +86,7 @@ <varlistentry> <term><varname>FallbackNTP=</varname></term> - <listitem><para>A space separated list of NTP server host + <listitem><para>A space-separated list of NTP server host names or IP addresses to be used as the fallback NTP servers. Any per-interface NTP servers obtained from <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> diff --git a/man/tmpfiles.d.xml b/man/tmpfiles.d.xml index 8d3ed37ae3..75fb901102 100644 --- a/man/tmpfiles.d.xml +++ b/man/tmpfiles.d.xml @@ -1,5 +1,4 @@ -<?xml version="1.0"?> -<!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -103,8 +102,8 @@ 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 + 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> @@ -158,21 +157,103 @@ <varlistentry> <term><varname>d</varname></term> - <listitem><para>Create a directory if it does not exist yet. - </para></listitem> + <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 time argument is specified.</para></listitem> </varlistentry> <varlistentry> <term><varname>D</varname></term> - <listitem><para>Create or empty a directory.</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.</para></listitem> </varlistentry> <varlistentry> <term><varname>v</varname></term> <listitem><para>Create a subvolume if the path does not - exist yet and the file system supports this - (btrfs). Otherwise create a normal directory, in the same - way as <varname>d</varname>.</para></listitem> + 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> + </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> + </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> </varlistentry> <varlistentry> @@ -193,7 +274,8 @@ be removed and be replaced by the symlink. If the argument is omitted, symlinks to files with the same name residing in the directory <filename>/usr/share/factory/</filename> are - created.</para></listitem> + created. Note that permissions and ownership on symlinks + are ignored.</para></listitem> </varlistentry> <varlistentry> @@ -318,15 +400,15 @@ <varname>+</varname> (the default one) causes the attribute(s) to be added; <varname>-</varname> causes the attribute(s) to be removed; <varname>=</varname> causes the - attributes to set exactly as the following letters. The + attributes to be set exactly as the following letters. The letters <literal>aAcCdDeijsStTu</literal> select the new attributes for the files, see - <citerefentry><refentrytitle>chattr</refentrytitle> + <citerefentry project='man-pages'><refentrytitle>chattr</refentrytitle> <manvolnum>1</manvolnum></citerefentry> for further information. </para> <para>Passing only <varname>=</varname> as argument resets all the file attributes listed above. It has to be pointed - out that the <varname>=</varname> prefix, limits itself to + out that the <varname>=</varname> prefix limits itself to the attributes corresponding to the letters listed here. All other attributes will be left untouched. Does not follow symlinks.</para> @@ -345,12 +427,12 @@ <term><varname>a</varname></term> <term><varname>a+</varname></term> <listitem><para>Set POSIX ACLs (access control lists). If - suffixed with <varname>+</varname>, specified entries will + suffixed with <varname>+</varname>, the specified entries will be added to the existing set. <command>systemd-tmpfiles</command> will automatically add the required base entries for user and group based on the access mode of the file, unless base entries already exist - or are explictly specified. The mask will be added if not + or are explicitly specified. The mask will be added if not specified explicitly or already present. Lines of this type accept shell-style globs in place of normal path names. This can be useful for allowing additional access to certain @@ -468,7 +550,7 @@ <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>, + 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>, @@ -483,16 +565,16 @@ delete when cleaning. If a file or directory is older than the current time minus the age field, it is deleted. The field format is a series of integers each followed by one of the - following postfixes for the respective time units: + following suffixes for the respective time units: <constant>s</constant>, <constant>m</constant> or <constant>min</constant>, <constant>h</constant>, <constant>d</constant>, <constant>w</constant>, - <constant>ms</constant>, + <constant>ms</constant>, and <constant>us</constant>, - respectively meaning seconds, minutes, hours, days, weeks, - milliseconds, and microseconds. Full names of the time units can + meaning seconds, minutes, hours, days, weeks, + milliseconds, and microseconds, respectively. Full names of the time units can be used too. </para> @@ -504,12 +586,12 @@ <para>When the age is set to zero, the files are cleaned unconditionally.</para> - <para>The age field only applies to lines - starting with <varname>d</varname>, - <varname>D</varname>, and - <varname>x</varname>. If omitted or set to - <literal>-</literal>, no automatic clean-up is - done.</para> + <para>The age field only applies to lines starting with + <varname>d</varname>, <varname>D</varname>, <varname>e</varname>, + <varname>v</varname>, <varname>q</varname>, + <varname>Q</varname>, <varname>C</varname>, <varname>x</varname> + and <varname>X</varname>. If omitted or set to + <literal>-</literal>, no automatic clean-up is done.</para> <para>If the age field starts with a tilde character <literal>~</literal>, the clean-up is only applied to files and @@ -521,41 +603,82 @@ <title>Argument</title> <para>For <varname>L</varname> lines determines the destination - path of the symlink. For <varname>c</varname>, - <varname>b</varname> determines the major/minor of the device + path of the symlink. For <varname>c</varname> and + <varname>b</varname>, determines the major/minor of the device node, with major and minor formatted as integers, separated by <literal>:</literal>, e.g. <literal>1:3</literal>. For <varname>f</varname>, <varname>F</varname>, and - <varname>w</varname> may be used to specify a short string that + <varname>w</varname>, the argument may be used to specify a short string that is written to the file, suffixed by a newline. For <varname>C</varname>, specifies the source file or - directory. For <varname>t</varname>, <varname>T</varname> + directory. For <varname>t</varname> and <varname>T</varname>, determines extended attributes to be set. For - <varname>a</varname>, <varname>A</varname> determines ACL - attributes to be set. For <varname>h</varname>, - <varname>H</varname> determines the file attributes to + <varname>a</varname> and <varname>A</varname>, determines ACL + attributes to be set. For <varname>h</varname> and + <varname>H</varname>, determines the file attributes to set. Ignored for all other lines.</para> </refsect2> </refsect1> <refsect1> - <title>Example</title> + <title>Examples</title> <example> - <title>/etc/tmpfiles.d/screen.conf example</title> - <para><command>screen</command> needs two directories created at - boot with specific modes and ownership.</para> + <title>Create directories with specific mode and ownership</title> + <para> + <citerefentry project='die-net'><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + needs two directories created at boot with specific modes and ownership:</para> + + <programlisting># /usr/lib/tmpfiles.d/screen.conf +d /run/screens 1777 root screen 10d +d /run/uscreens 0755 root screen 10d12h +</programlisting> + + <para>Contents of <filename>/run/screens</filename> and /run/uscreens will + cleaned up after 10 and 10½ days, respectively.</para> + </example> - <programlisting>d /run/screens 1777 root root 10d -d /run/uscreens 0755 root root 10d12h -t /run/screen - - - - user.name="John Smith" security.SMACK64=screen</programlisting> + <example> + <title>Create a directory with a SMACK attribute</title> + <programlisting>D /run/cups - - - - +t /run/cups - - - - security.SMACK64=printing user.attr-with-spaces="foo bar" + </programlisting> + + <para>The direcory will be owned by root and have default mode. It's contents are + not subject to time based cleanup, but will be obliterated when + <command>systemd-tmpfiles --remove</command> runs.</para> </example> + <example> - <title>/etc/tmpfiles.d/abrt.conf example</title> - <para><command>abrt</command> needs a directory created at boot with specific mode and ownership and its content should be preserved.</para> + <title>Create a directory and prevent its contents from cleanup</title> + <para> + <citerefentry project='die-net'><refentrytitle>abrt</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + needs a directory created at boot with specific mode and ownership and its content + should be preserved from the automatic cleanup applied to the contents of + <filename>/var/tmp</filename>:</para> + + <programlisting># /usr/lib/tmpfiles.d/tmp.conf +d /var/tmp 1777 root root 30d +</programlisting> + + <programlisting># /usr/lib/tmpfiles.d/abrt.conf +d /var/tmp/abrt 0755 abrt abrt - +</programlisting> + </example> - <programlisting>d /var/tmp/abrt 0755 abrt abrt -x /var/tmp/abrt/*</programlisting> + <example> + <title>Apply clean up during boot and based on time</title> + + <programlisting># /usr/lib/tmpfiles.d/dnf.conf +r! /var/cache/dnf/*/*/download_lock.pid +r! /var/cache/dnf/*/*/metadata_lock.pid +r! /var/lib/dnf/rpmdb_lock.pid +e /var/chache/dnf/ - - - 30d +</programlisting> + + <para>The lock files will be removed during boot. Any files and directories in + <filename>/var/chache/dnf/</filename> will be removed after they have not been + accessed in 30 days.</para> </example> </refsect1> @@ -571,7 +694,9 @@ x /var/tmp/abrt/*</programlisting> <citerefentry project='man-pages'><refentrytitle>setfattr</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>setfacl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>getfacl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>chattr</refentrytitle><manvolnum>1</manvolnum></citerefentry> + <citerefentry project='man-pages'><refentrytitle>chattr</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>btrfs-subvolume</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>btrfs-qgroup</refentrytitle><manvolnum>8</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/udev.xml b/man/udev.xml index 2e1655bf55..dd5563605c 100644 --- a/man/udev.xml +++ b/man/udev.xml @@ -470,7 +470,7 @@ <term><literal>program</literal></term> <listitem> <para>Execute an external program specified as the assigned - value and if it returns successfully + value and, if it returns successfully, import its output, which must be in environment key format. Path specification, command/argument separation, and quoting work like in <varname>RUN</varname>.</para> @@ -536,7 +536,7 @@ <varlistentry> <term><option>string_escape=<replaceable>none|replace</replaceable></option></term> <listitem> - <para>Usually control and other possibly unsafe characters are replaced + <para>Usually, control and other possibly unsafe characters are replaced in strings used for device naming. The mode of replacement can be specified with this option.</para> </listitem> diff --git a/man/udev_device_get_syspath.xml b/man/udev_device_get_syspath.xml index b3062ae4a8..014f43b21c 100644 --- a/man/udev_device_get_syspath.xml +++ b/man/udev_device_get_syspath.xml @@ -127,6 +127,8 @@ <funcprototype> <funcdef>struct udev_device *<function>udev_device_get_parent_with_subsystem_devtype</function></funcdef> <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> + <paramdef>const char *<parameter>subsystem</parameter></paramdef> + <paramdef>const char *<parameter>devtype</parameter></paramdef> </funcprototype> <funcprototype> @@ -137,8 +139,6 @@ <funcprototype> <funcdef>const char *<function>udev_device_get_action</function></funcdef> <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> - <paramdef>const char *<parameter>subsystem</parameter></paramdef> - <paramdef>const char *<parameter>devtype</parameter></paramdef> </funcprototype> </funcsynopsis> @@ -181,13 +181,13 @@ <function>udev_device_get_parent_with_subsystem_devtype()</function> return a pointer to the parent device. No additional reference to this device is acquired, but the child device owns a reference - to such parent device. On failure, <constant>NULL</constant> + to such a parent device. On failure, <constant>NULL</constant> is returned.</para> - <para>On success, <function>udev_device_get_is_initialized()</function> - returns either <constant>1</constant> or <constant>0</constant>, - depending on whether the passed device is initialized or not. On - failure, a negative error code is returned.</para> + <para>On success, <function>udev_device_get_is_initialized()</function> returns either <constant>1</constant> or + <constant>0</constant>, depending on whether the passed device has already been initialized by udev or not. On + failure, a negative error code is returned. Note that devices for which no udev rules are defined are never + reported initialized.</para> </refsect1> <refsect1> diff --git a/man/udev_device_new_from_syspath.xml b/man/udev_device_new_from_syspath.xml index 9c4ab7a1bf..0bb71c8e91 100644 --- a/man/udev_device_new_from_syspath.xml +++ b/man/udev_device_new_from_syspath.xml @@ -127,21 +127,21 @@ <function>udev_device_new_from_subsystem_sysname</function>, and <function>udev_device_new_from_device_id</function> create the device object based on information found in - <filename>/sys</filename> annotated with properties from the udev-internal + <filename>/sys</filename>, annotated with properties from the udev-internal device database. A syspath is any subdirectory of <filename>/sys</filename>, with the restriction that a subdirectory of <filename>/sys/devices</filename> (or a symlink to one) represents a real device and as such must contain a <filename>uevent</filename> file. <function>udev_device_new_from_devnum</function> takes a device type, which can be <constant>b</constant> for block devices or <constant>c</constant> for character devices, as well as a devnum (see - <citerefentry><refentrytitle>makedev</refentrytitle><manvolnum>3</manvolnum></citerefentry>). + <citerefentry project='man-pages'><refentrytitle>makedev</refentrytitle><manvolnum>3</manvolnum></citerefentry>). <function>udev_device_new_from_subsystem_sysname</function> looks up devices based on the provided subsystem and sysname (see <citerefentry><refentrytitle>udev_device_get_subsystem</refentrytitle><manvolnum>3</manvolnum></citerefentry> and <citerefentry><refentrytitle>udev_device_get_sysname</refentrytitle><manvolnum>3</manvolnum></citerefentry>) and <function>udev_device_new_from_device_id</function> looks up devices based on the provided - device id which is a special string in one of the following four forms: + device ID, which is a special string in one of the following four forms: <table> <title>Device ID strings</title> @@ -171,7 +171,7 @@ <para><function>udev_device_new_from_environment</function> creates a device from the current environment (see - <citerefentry><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>). + <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>). Each key-value pair is interpreted in the same way as if it was received in an uevent (see <citerefentry><refentrytitle>udev_monitor_receive_device</refentrytitle><manvolnum>3</manvolnum></citerefentry>). @@ -189,7 +189,8 @@ <function>udev_device_new_from_device_id()</function> and <function>udev_device_new_from_environment()</function> return a pointer to the allocated udev device. On failure, - <constant>NULL</constant> is returned. + <constant>NULL</constant> is returned, + and <varname>errno</varname> is set appropriately. <function>udev_device_ref()</function> returns the argument that it was passed, unmodified. <function>udev_device_unref()</function> always returns diff --git a/man/udev_enumerate_scan_devices.xml b/man/udev_enumerate_scan_devices.xml index 73566f5089..e0b6bfba32 100644 --- a/man/udev_enumerate_scan_devices.xml +++ b/man/udev_enumerate_scan_devices.xml @@ -112,7 +112,7 @@ <constant>NULL</constant> is returned.</para> <para><function>udev_enumerate_get_udev()</function> always - returns a pointer to the udev context that this enumerate + returns a pointer to the udev context that this enumerated object is associated with.</para> </refsect1> diff --git a/man/udev_list_entry.xml b/man/udev_list_entry.xml index 6e033bdc81..a1b531d52a 100644 --- a/man/udev_list_entry.xml +++ b/man/udev_list_entry.xml @@ -104,7 +104,7 @@ <function>udev_list_entry_get_name()</function> and <function>udev_list_entry_get_value()</function> return a pointer to a constant string representing the requested value. - The string is bound to the lifetime of the list-entry itself. + The string is bound to the lifetime of the list entry itself. On failure, <constant>NULL</constant> is returned.</para> </refsect1> diff --git a/man/udevadm.xml b/man/udevadm.xml index 8ef9e23aa2..1c7921f5bd 100644 --- a/man/udevadm.xml +++ b/man/udevadm.xml @@ -202,7 +202,7 @@ </varlistentry> </variablelist> - <para>In addition an optional positional argument can be used + <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> @@ -317,7 +317,7 @@ <term><option>--name-match=<replaceable>NAME</replaceable></option></term> <listitem> <para>Trigger events for devices with a matching - device path. This options can be specified multiple + device path. This option can be specified multiple times.</para> </listitem> </varlistentry> @@ -338,7 +338,7 @@ </varlistentry> </variablelist> - <para>In addition optional positional arguments can be used + <para>In addition, optional positional arguments can be used to specify device names or sys paths. They must start with <filename>/dev</filename> or <filename>/sys</filename> respectively.</para> @@ -380,7 +380,7 @@ <para>Modify the internal state of the running udev daemon.</para> <variablelist> <varlistentry> - <term><option>-x</option></term> + <term><option>-e</option></term> <term><option>--exit</option></term> <listitem> <para>Signal and wait for systemd-udevd to exit.</para> diff --git a/man/vconsole.conf.xml b/man/vconsole.conf.xml index 27196d44e9..fa30ca6569 100644 --- a/man/vconsole.conf.xml +++ b/man/vconsole.conf.xml @@ -55,8 +55,9 @@ <para>The <filename>/etc/vconsole.conf</filename> file configures the virtual console, i.e. keyboard mapping and console font. It is - applied at boot by - <citerefentry><refentrytitle>systemd-vconsole-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + applied at boot by udev using <filename>90-vconsole.rules</filename> file. + You can safely mask this file if you want to avoid this kind of initialization. + </para> <para>The basic file format of the <filename>vconsole.conf</filename> is a newline-separated list of @@ -68,10 +69,10 @@ <para>Note that the kernel command line options <varname>vconsole.keymap=</varname>, - <varname>vconsole.keymap.toggle=</varname>, + <varname>vconsole.keymap_toggle=</varname>, <varname>vconsole.font=</varname>, - <varname>vconsole.font.map=</varname>, - <varname>vconsole.font.unimap=</varname> may be used + <varname>vconsole.font_map=</varname>, + <varname>vconsole.font_unimap=</varname> may be used to override the console settings at boot.</para> <para>Depending on the operating system other configuration files @@ -90,12 +91,10 @@ <term><varname>KEYMAP=</varname></term> <term><varname>KEYMAP_TOGGLE=</varname></term> - <listitem><para>Configures the key mapping table for the - keyboard. <varname>KEYMAP=</varname> defaults to - <literal>us</literal> if not set. The - <varname>KEYMAP_TOGGLE=</varname> can be used to configure a - second toggle keymap and is by default - unset.</para></listitem> + <listitem><para>Configures the key mapping table for the keyboard. + <varname>KEYMAP=</varname> defaults to <literal>us</literal> if not set. The + <varname>KEYMAP_TOGGLE=</varname> can be used to configure a second toggle keymap and is by + default unset.</para></listitem> </varlistentry> <varlistentry> @@ -111,6 +110,32 @@ </refsect1> <refsect1> + <title>Kernel Command Line</title> + + <para>A few configuration parameters from <filename>vconsole.conf</filename> may be overridden + on the kernel command line:</para> + + <variablelist class='kernel-commandline-options'> + <varlistentry> + <term><varname>vconsole.keymap=</varname></term> + <term><varname>vconsole.keymap_toggle=</varname></term> + + <listitem><para>Overrides <varname>KEYMAP=</varname> and <varname>KEYMAP_TOGGLE=</varname>. + </para></listitem> + </varlistentry> + <varlistentry> + + <term><varname>vconsole.font=</varname></term> + <term><varname>vconsole.font_map=</varname></term> + <term><varname>vconsole.font_unimap=</varname></term> + + <listitem><para>Overrides <varname>FONT=</varname>, <varname>FONT_MAP=</varname>, and + <varname>FONT_UNIMAP=</varname>.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> <title>Example</title> <example> |