diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/journalctl.xml | 17 | ||||
| -rw-r--r-- | man/nss-myhostname.xml | 6 | ||||
| -rw-r--r-- | man/sd-journal.xml | 4 | ||||
| -rw-r--r-- | man/sd_event_add_time.xml | 57 | ||||
| -rw-r--r-- | man/sd_journal_enumerate_fields.xml | 161 | ||||
| -rw-r--r-- | man/sd_journal_query_unique.xml | 44 | ||||
| -rw-r--r-- | man/systemctl.xml | 26 | ||||
| -rw-r--r-- | man/systemd-activate.xml | 50 | ||||
| -rw-r--r-- | man/systemd-nspawn.xml | 72 | ||||
| -rw-r--r-- | man/systemd-resolve.xml | 2 | ||||
| -rw-r--r-- | man/systemd-resolved.service.xml | 14 | ||||
| -rw-r--r-- | man/systemd.network.xml | 4 | ||||
| -rw-r--r-- | man/systemd.nspawn.xml | 32 | ||||
| -rw-r--r-- | man/systemd.resource-control.xml | 17 | ||||
| -rw-r--r-- | man/systemd.service.xml | 176 | ||||
| -rw-r--r-- | man/systemd.special.xml | 39 | ||||
| -rw-r--r-- | man/systemd.swap.xml | 2 | ||||
| -rw-r--r-- | man/systemd.unit.xml | 136 | ||||
| -rw-r--r-- | man/udev_device_new_from_syspath.xml | 3 |
19 files changed, 538 insertions, 324 deletions
diff --git a/man/journalctl.xml b/man/journalctl.xml index b57afb6ebf..b281f26b45 100644 --- a/man/journalctl.xml +++ b/man/journalctl.xml @@ -91,8 +91,14 @@ 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> + to a device node then match is added for the kernel name of the + device (<literal>_KERNEL_DEVICE=</literal>). Also, matches for the + kernel names of all the parent devices are added automatically. + Device node paths are not stable across reboots, therefore match + for the current boot id (<literal>_BOOT_ID=</literal>) is + always added as well. Note that only the log entries for + the existing device nodes maybe queried by providing path to + the device node.</para> <para>Additional constraints may be added using options <option>--boot</option>, <option>--unit=</option>, etc., to @@ -572,6 +578,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> diff --git a/man/nss-myhostname.xml b/man/nss-myhostname.xml index 859bec29e3..251bdecbad 100644 --- a/man/nss-myhostname.xml +++ b/man/nss-myhostname.xml @@ -71,9 +71,9 @@ 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 hostname <literal>localhost</literal> (as well as any hostname ending in + <literal>.localhost</literal>, <literal>.localdomain</literal> or equal to <literal>localdomain</literal>) is + 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, diff --git a/man/sd-journal.xml b/man/sd-journal.xml index a1185d372b..09747a480c 100644 --- a/man/sd-journal.xml +++ b/man/sd-journal.xml @@ -77,6 +77,8 @@ <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_query_enumerate</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>, @@ -111,6 +113,8 @@ <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_query_enumerate</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>, diff --git a/man/sd_event_add_time.xml b/man/sd_event_add_time.xml index 142fa80f8f..a2c0d54b56 100644 --- a/man/sd_event_add_time.xml +++ b/man/sd_event_add_time.xml @@ -114,41 +114,28 @@ <refsect1> <title>Description</title> - <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. 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 + <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 paramater 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 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_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/systemctl.xml b/man/systemctl.xml index cce7861139..1480bf8380 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -1134,7 +1134,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <tbody> <row> <entry><literal>enabled</literal></entry> - <entry morerows='1'>Enabled through creating symlinks encoded in the <literal>[Install]</literal> section (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> @@ -1698,24 +1698,19 @@ 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: @@ -1740,9 +1735,8 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service loaded 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> diff --git a/man/systemd-activate.xml b/man/systemd-activate.xml index c950a0836d..995e6eecce 100644 --- a/man/systemd-activate.xml +++ b/man/systemd-activate.xml @@ -60,27 +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-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>. </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. - By default, <command>systemd-activate</command> listens on a - stream socket, use <option>--datagram</option> to listen on - a datagram socket instead (see below). + <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-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-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> @@ -101,16 +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, instead of a stream socket.</para></listitem> + <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> @@ -170,7 +180,7 @@ <example> <title>Run an echo server on port 2000</title> - <programlisting>$ /usr/lib/systemd/systemd-activate -l 2000 -a cat</programlisting> + <programlisting>$ /usr/lib/systemd/systemd-activate -l 2000 --inetd -a cat</programlisting> </example> <example> diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml index 28b91dee24..86cdb4e124 100644 --- a/man/systemd-nspawn.xml +++ b/man/systemd-nspawn.xml @@ -249,15 +249,75 @@ </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> or + <option>--share-system</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> or + <option>--share-system</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 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 command line, which are 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> + </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> diff --git a/man/systemd-resolve.xml b/man/systemd-resolve.xml index 0defa2d7fb..802d9cbbe6 100644 --- a/man/systemd-resolve.xml +++ b/man/systemd-resolve.xml @@ -126,7 +126,7 @@ When this option is specified one or more e-mail address must be specified.</para> <para>The <option>--statistics</option> switch may be used to show resolver statistics, including information about - the number of succesful and failed DNSSEC validations.</para> + 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 diff --git a/man/systemd-resolved.service.xml b/man/systemd-resolved.service.xml index 4e144b5c98..7a9e23a2c6 100644 --- a/man/systemd-resolved.service.xml +++ b/man/systemd-resolved.service.xml @@ -87,15 +87,18 @@ 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 hostname <literal>localhost</literal> (as well as any hostname ending in + <literal>.localhost</literal>, <literal>.localdomain</literal> or equal to <literal>localdomain</literal>) is + 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 @@ -135,6 +138,10 @@ <para>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>.</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> @@ -146,6 +153,7 @@ <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.network.xml b/man/systemd.network.xml index f88751b672..adfe1ac9b3 100644 --- a/man/systemd.network.xml +++ b/man/systemd.network.xml @@ -412,7 +412,7 @@ domains specified here are preferably routed to the DNS servers configured for this interface. If a domain name is prefixed with <literal>~</literal>, the domain name becomes a pure "routing" domain, is used for DNS query routing purposes only and is not used in the described domain search logic. By specifying a - routing domain of <literal>~.</literal> (the tilda indicating definition of a routing domain, the dot + routing domain of <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) it is possible to route all DNS traffic preferably to the DNS server specified for this interface. The route domain logic is particularly useful on multi-homed hosts with DNS servers serving particular private DNS zones on each @@ -717,7 +717,7 @@ <varlistentry> <term><varname>UseDomains=</varname></term> <listitem> - <para>Takes a boolean argument, or a the special value <literal>route</literal>. When true, the domain name + <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 diff --git a/man/systemd.nspawn.xml b/man/systemd.nspawn.xml index f39e1ad42c..c07a4b0243 100644 --- a/man/systemd.nspawn.xml +++ b/man/systemd.nspawn.xml @@ -141,15 +141,21 @@ <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. </para></listitem> + <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>.</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> @@ -187,6 +193,14 @@ </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> diff --git a/man/systemd.resource-control.xml b/man/systemd.resource-control.xml index b6b38fde58..08cdf06e23 100644 --- a/man/systemd.resource-control.xml +++ b/man/systemd.resource-control.xml @@ -424,23 +424,6 @@ </varlistentry> <varlistentry> - <term><varname>NetClass=</varname></term> - <listitem><para>Configures a network class number to assign to the - unit. This value will be set to the - <literal>net_cls.class_id</literal> property of the - <literal>net_cls</literal> cgroup of the unit. The directive - accepts a numerical value (for fixed number assignment) and the keyword - <literal>auto</literal> (for dynamic allocation). Network traffic of - all processes inside the unit will have the network class ID assigned - by the kernel. Also see - the kernel docs for - <ulink url="https://www.kernel.org/doc/Documentation/cgroups/net_cls.txt">net_cls controller</ulink> - and - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para></listitem> - </varlistentry> - - <varlistentry> <term><varname>Slice=</varname></term> <listitem> diff --git a/man/systemd.service.xml b/man/systemd.service.xml index d7b19ee27f..e55534700a 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -273,42 +273,6 @@ </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 @@ -371,7 +335,7 @@ with a <literal>-</literal> exit successfully.</para> <para><varname>ExecStartPost=</varname> commands are only run after - the service has started, as determined by <varname>Type=</varname> + 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 @@ -383,6 +347,11 @@ 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> @@ -438,21 +407,36 @@ <constant>SIGKILL</constant> immediately after the command 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></listitem> </varlistentry> <varlistentry> @@ -470,7 +454,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 @@ -489,7 +473,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 @@ -506,6 +490,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 @@ -844,85 +838,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. 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>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> diff --git a/man/systemd.special.xml b/man/systemd.special.xml index 0a37f65956..80c15b700d 100644 --- a/man/systemd.special.xml +++ b/man/systemd.special.xml @@ -204,12 +204,22 @@ <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> @@ -440,11 +450,18 @@ <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> @@ -509,7 +526,7 @@ <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 the root + <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> diff --git a/man/systemd.swap.xml b/man/systemd.swap.xml index c600405c87..69d4be4769 100644 --- a/man/systemd.swap.xml +++ b/man/systemd.swap.xml @@ -72,7 +72,7 @@ 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 these processes are + 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 these processes of the diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index a95c160954..5794681963 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -178,18 +178,14 @@ 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> + <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 + honoured in drop-in unit files, and have no effect.</para> <para>In addition to <filename>/etc/systemd/system</filename>, the drop-in <literal>.conf</literal> files for system services @@ -728,20 +724,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>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> + <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 @@ -760,6 +750,55 @@ </varlistentry> <varlistentry> + <term><varname>StartLimitInterval=</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>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 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.</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. 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> @@ -784,13 +823,14 @@ 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 @@ -1024,14 +1064,12 @@ <term><varname>AssertFileNotEmpty=</varname></term> <term><varname>AssertFileIsExecutable=</varname></term> - <listitem><para>Similar to the - <varname>ConditionArchitecture=</varname>, - <varname>ConditionVirtualization=</varname>, etc., 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> @@ -1051,15 +1089,13 @@ <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> diff --git a/man/udev_device_new_from_syspath.xml b/man/udev_device_new_from_syspath.xml index c71356a75a..0bb71c8e91 100644 --- a/man/udev_device_new_from_syspath.xml +++ b/man/udev_device_new_from_syspath.xml @@ -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 |