diff options
Diffstat (limited to 'man')
48 files changed, 1521 insertions, 518 deletions
diff --git a/man/bootctl.xml b/man/bootctl.xml index ebd58750d3..6e835c037f 100644 --- a/man/bootctl.xml +++ b/man/bootctl.xml @@ -74,14 +74,14 @@ <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 + 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 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 + 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> diff --git a/man/busctl.xml b/man/busctl.xml index b71a174634..052a33097f 100644 --- a/man/busctl.xml +++ b/man/busctl.xml @@ -119,8 +119,10 @@ <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> diff --git a/man/crypttab.xml b/man/crypttab.xml index 1de834a045..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> diff --git a/man/journalctl.xml b/man/journalctl.xml index 3efe6ef62a..e77621d7b3 100644 --- a/man/journalctl.xml +++ b/man/journalctl.xml @@ -87,18 +87,26 @@ 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 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>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 @@ -824,7 +832,7 @@ 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 has happened. This command + 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> diff --git a/man/journald.conf.xml b/man/journald.conf.xml index 3964cd6bc5..fef4fde898 100644 --- a/man/journald.conf.xml +++ b/man/journald.conf.xml @@ -129,21 +129,22 @@ <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 + <listitem><para>Controls whether to split up journal files per user. Split-up 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. This setting takes one of <literal>uid</literal>, + <literal>login</literal> or <literal>none</literal>. If <literal>uid</literal>, all regular users will get each + their own journal files regardless of whether their processes possess login sessions 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. Note that in this mode, user code running outside of any login session will log into the system log + instead of the split-out user logs. Most importantly, this means that information about core dumps of user + processes collected via the + <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry> subsystem + will end up in the system logs instead of the user logs, and thus not be accessible to the owning users. 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 above), only a single journal file for all user IDs is kept. Defaults to <literal>uid</literal>.</para></listitem> </varlistentry> diff --git a/man/kernel-command-line.xml b/man/kernel-command-line.xml index 9c04849f66..3ecc969c10 100644 --- a/man/kernel-command-line.xml +++ b/man/kernel-command-line.xml @@ -146,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> @@ -158,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> diff --git a/man/libudev.xml b/man/libudev.xml index 7ef978463c..53b68dcc89 100644 --- a/man/libudev.xml +++ b/man/libudev.xml @@ -81,7 +81,7 @@ <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> diff --git a/man/localectl.xml b/man/localectl.xml index 7def047f62..8d2becb5d9 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><refentrytitle>mkinitrd</refentrytitle><manvolnum>8</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/logind.conf.xml b/man/logind.conf.xml index fe92277a1f..adba5a4131 100644 --- a/man/logind.conf.xml +++ b/man/logind.conf.xml @@ -315,12 +315,11 @@ <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 + <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. Defaults to 12288 (12K).</para></listitem> + for details. 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> diff --git a/man/machinectl.xml b/man/machinectl.xml index 4b7f9a0391..597a5cc583 100644 --- a/man/machinectl.xml +++ b/man/machinectl.xml @@ -333,7 +333,7 @@ <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 @@ -373,8 +373,7 @@ <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> @@ -461,8 +460,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 @@ -576,7 +575,7 @@ <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 diff --git a/man/os-release.xml b/man/os-release.xml index a70ba1aa31..2811f434c5 100644 --- a/man/os-release.xml +++ b/man/os-release.xml @@ -176,6 +176,22 @@ </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 diff --git a/man/resolved.conf.xml b/man/resolved.conf.xml index 920ce9e89b..7556c6ff31 100644 --- a/man/resolved.conf.xml +++ b/man/resolved.conf.xml @@ -202,6 +202,17 @@ </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 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> + </variablelist> </refsect1> 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_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_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_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_event_add_time.xml b/man/sd_event_add_time.xml index a2c0d54b56..5496b71529 100644 --- a/man/sd_event_add_time.xml +++ b/man/sd_event_add_time.xml @@ -123,7 +123,7 @@ 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, + 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 @@ -213,7 +213,7 @@ in µs.</para> <para><function>sd_event_source_get_time_accuracy()</function> - retrieves the configured accuracy value of a 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. The accuracy is specified in µs.</para> @@ -224,7 +224,7 @@ the event source object and accuracy, in µs.</para> <para><function>sd_event_source_get_time_clock()</function> - retrieves the configured clock of a 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> diff --git a/man/sd_event_wait.xml b/man/sd_event_wait.xml index f2aea00e98..26327dc688 100644 --- a/man/sd_event_wait.xml +++ b/man/sd_event_wait.xml @@ -47,6 +47,7 @@ <refname>sd_event_prepare</refname> <refname>sd_event_dispatch</refname> <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> @@ -93,6 +94,12 @@ <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> @@ -140,12 +147,15 @@ determine the state the event loop is currently in. It returns one of the states described below.</para> - <para>All four 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 milliseconds. <constant>(uint64_t) - -1</constant> may be used to specify an infinite timeout.</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> <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_journal_get_data.xml b/man/sd_journal_get_data.xml index 908ee7db16..1321114de0 100644 --- a/man/sd_journal_get_data.xml +++ b/man/sd_journal_get_data.xml @@ -151,7 +151,7 @@ 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_print.xml b/man/sd_journal_print.xml index 17fdc9c1f2..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,35 +117,26 @@ 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> @@ -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_notify.xml b/man/sd_notify.xml index bd6cfdcd29..025fbec6c1 100644 --- a/man/sd_notify.xml +++ b/man/sd_notify.xml @@ -250,6 +250,15 @@ 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 diff --git a/man/systemctl.xml b/man/systemctl.xml index 991e9bafaf..e7880d24f7 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -150,11 +150,11 @@ <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> </listitem> </varlistentry> @@ -481,19 +481,19 @@ <para>When used with <command>enable</command>, overwrite any existing conflicting symlinks.</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, 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> + <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> @@ -638,10 +638,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> has loaded. This includes units that + are either referenced directly or through a dependency, 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> @@ -970,71 +973,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 and their enablement state - (as reported by <command>is-enabled</command>). 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 diectory, 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> @@ -1042,28 +1035,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> @@ -1071,12 +1067,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 commands expects + a unit uname only, it does not accept paths to unit files.</para> </listitem> </varlistentry> @@ -1207,16 +1201,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> @@ -1224,23 +1215,20 @@ 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>FILENAME</replaceable>...</command></term> + <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 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>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> @@ -1304,6 +1292,9 @@ 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> @@ -1600,48 +1591,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 diff --git a/man/systemd-cgtop.xml b/man/systemd-cgtop.xml index c76f646984..be13631239 100644 --- a/man/systemd-cgtop.xml +++ b/man/systemd-cgtop.xml @@ -52,6 +52,7 @@ <cmdsynopsis> <command>systemd-cgtop</command> <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="opt">GROUP</arg> </cmdsynopsis> </refsynopsisdiv> @@ -62,7 +63,9 @@ 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 @@ -252,7 +255,8 @@ <listitem><para>Limit control groups shown to the part corresponding to the container - <replaceable>MACHINE</replaceable>.</para></listitem> + <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" /> 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-machine-id-setup.xml b/man/systemd-machine-id-setup.xml index bfcd74f436..749987a937 100644 --- a/man/systemd-machine-id-setup.xml +++ b/man/systemd-machine-id-setup.xml @@ -151,6 +151,12 @@ 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> diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml index 476cc2932f..69d2f6ff7d 100644 --- a/man/systemd-nspawn.xml +++ b/man/systemd-nspawn.xml @@ -67,69 +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>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> @@ -139,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> @@ -310,6 +321,9 @@ </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> @@ -446,7 +460,10 @@ <listitem><para>If the kernel supports the user namespaces feature, equivalent to <option>--private-users=pick</option>, otherwise equivalent to - <option>--private-users=no</option>.</para></listitem> + <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></listitem> </varlistentry> <varlistentry> @@ -540,6 +557,9 @@ 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> @@ -705,7 +725,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> @@ -910,8 +933,8 @@ <literal>tmpfs</literal> instance, and <filename>/usr</filename> from the OS tree is mounted into it in read-only mode (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 + 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 a <literal>tmpfs</literal> instance into it (the system thus @@ -980,6 +1003,19 @@ 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> diff --git a/man/systemd-resolve.xml b/man/systemd-resolve.xml index 4b66f836a2..ca26bb4d49 100644 --- a/man/systemd-resolve.xml +++ b/man/systemd-resolve.xml @@ -114,6 +114,12 @@ 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> @@ -288,8 +294,21 @@ <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> diff --git a/man/systemd-resolved.service.xml b/man/systemd-resolved.service.xml index 829729ca09..aa1c2365e5 100644 --- a/man/systemd-resolved.service.xml +++ b/man/systemd-resolved.service.xml @@ -58,27 +58,45 @@ <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. In addition it 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>.</para> - - <para>The glibc NSS module - <citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry> is required to - permit glibc's NSS resolver functions to resolve host names via <command>systemd-resolved</command>.</para> - - <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, - and the per-link dynamic settings received over DHCP. See - <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. 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 above).</para> + 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><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><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><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 RRs for the following cases:</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 @@ -137,15 +155,68 @@ 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 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> + <title><filename>/etc/resolv.conf</filename></title> + + <para>Three modes of handling <filename>/etc/resolv.conf</filename> (see + <citerefentry><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> <title>See Also</title> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, diff --git a/man/systemd-socket-activate.xml b/man/systemd-socket-activate.xml index 5d7f157c72..2cf3a7d377 100644 --- a/man/systemd-socket-activate.xml +++ b/man/systemd-socket-activate.xml @@ -142,7 +142,7 @@ <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, superflous ones willl be + (<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> 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 8833e73c72..1bb40fd234 100644 --- a/man/systemd-system.conf.xml +++ b/man/systemd-system.conf.xml @@ -325,12 +325,11 @@ <varlistentry> <term><varname>DefaultTasksMax=</varname></term> - <listitem><para>Configure the default value for the per-unit - <varname>TasksMax=</varname> setting. See + <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. This setting applies to all unit types that - support resource control settings, with the exception of slice - units. Defaults to 512.</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> diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index 3cf6de8256..41ae6e76de 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -107,7 +107,8 @@ <varlistentry> <term><varname>WorkingDirectory=</varname></term> - <listitem><para>Takes an absolute directory path, or the + <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 @@ -116,7 +117,10 @@ 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. Note that setting this parameter might result in + 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> @@ -124,7 +128,8 @@ <varlistentry> <term><varname>RootDirectory=</varname></term> - <listitem><para>Takes an absolute directory path. Sets the + <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 @@ -141,7 +146,7 @@ <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> + of the user is chosen. These do not affect commands prefixed with <literal>+</literal>.</para></listitem> </varlistentry> <varlistentry> @@ -156,7 +161,7 @@ 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> @@ -790,7 +795,8 @@ 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> + 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> @@ -819,7 +825,8 @@ 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.</para></listitem> + capabilities over the user change. <varname>AmbientCapabilities=</varname> does not affect + commands prefixed with <literal>+</literal>.</para></listitem> </varlistentry> <varlistentry> @@ -835,43 +842,46 @@ <option>noroot-locked</option>. 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>ReadWriteDirectories=</varname></term> - <term><varname>ReadOnlyDirectories=</varname></term> - <term><varname>InaccessibleDirectories=</varname></term> + <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 main file system hierarchy. Each - setting takes a space-separated list of absolute directory - paths. Directories listed in - <varname>ReadWriteDirectories=</varname> are accessible from + 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 entries contain symlinks, they are resolved from the host's root directory as well. + Entries (files or directories) listed in + <varname>ReadWritePaths=</varname> are accessible from within the namespace with the same access rights as from - outside. Directories listed in - <varname>ReadOnlyDirectories=</varname> are accessible for + outside. Entries listed in + <varname>ReadOnlyPaths=</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 + access controls would permit this. Entries listed in + <varname>InaccessiblePaths=</varname> will be made inaccessible for processes inside the namespace, and may not countain any other mountpoints, including those specified by - <varname>ReadWriteDirectories=</varname> or - <varname>ReadOnlyDirectories=</varname>. + <varname>ReadWritePaths=</varname> or + <varname>ReadOnlyPaths=</varname>. Note that restricting access with these options does not extend - to submounts of a directory that are created later on. These + to submounts of a directory that are created later on. + Non-directory paths can be specified as well. These options may be specified more than once, in which case all - directories listed will have limited access from within the + 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>ReadOnlyDirectories=</varname> + <varname>ReadOnlyPaths=</varname> and - <varname>InaccessibleDirectories=</varname> + <varname>InaccessiblePaths=</varname> may be prefixed with <literal>-</literal>, in which case they will be ignored when they do not @@ -1026,9 +1036,9 @@ <varname>PrivateDevices=</varname>, <varname>ProtectSystem=</varname>, <varname>ProtectHome=</varname>, - <varname>ReadOnlyDirectories=</varname>, - <varname>InaccessibleDirectories=</varname> and - <varname>ReadWriteDirectories=</varname>) require that mount + <varname>ReadOnlyPaths=</varname>, + <varname>InaccessiblePaths=</varname> and + <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> @@ -1091,8 +1101,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> @@ -1104,7 +1114,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> @@ -1123,7 +1133,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> @@ -1160,7 +1171,7 @@ effect is inverted: only the listed system calls will result in immediate process termination (blacklisting). If running in user mode, or in system mode, but without the - <constant>CAP_SYS_ADMIN</constant> capabiblity (e.g. setting + <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 @@ -1174,7 +1185,7 @@ 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 @@ -1187,7 +1198,84 @@ <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></listitem> </varlistentry> <varlistentry> @@ -1222,7 +1310,7 @@ more strictly: to the architecture the system manager is compiled for). If running in user mode, or in system mode, but without the <constant>CAP_SYS_ADMIN</constant> - capabiblity (e.g. setting <varname>User=nobody</varname>), + 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 @@ -1254,7 +1342,7 @@ has no effect on 32-bit x86 and is ignored (but works correctly on x86-64). If running in user mode, or in system mode, but without the <constant>CAP_SYS_ADMIN</constant> - capabiblity (e.g. setting <varname>User=nobody</varname>), + 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 @@ -1266,7 +1354,7 @@ 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> @@ -1311,6 +1399,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><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> @@ -1437,6 +1554,26 @@ <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> </variablelist> <para>Additional variables may be configured by the following diff --git a/man/systemd.generator.xml b/man/systemd.generator.xml index 4b80dab108..b268104c9d 100644 --- a/man/systemd.generator.xml +++ b/man/systemd.generator.xml @@ -166,7 +166,7 @@ process. That includes simple things such as logging to <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>)!. + <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 @@ -309,12 +309,12 @@ <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 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> diff --git a/man/systemd.netdev.xml b/man/systemd.netdev.xml index 8d12c305d2..a5c6f0fa40 100644 --- a/man/systemd.netdev.xml +++ b/man/systemd.netdev.xml @@ -124,7 +124,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> @@ -161,6 +161,10 @@ <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> + </tbody> </tgroup> </table> @@ -330,6 +334,15 @@ </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> </variablelist> </refsect1> @@ -630,6 +643,33 @@ </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> tunnel can be in one of three @@ -768,8 +808,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> @@ -1101,7 +1140,16 @@ 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 821e22aff8..4541a55490 100644 --- a/man/systemd.network.xml +++ b/man/systemd.network.xml @@ -240,7 +240,7 @@ 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>IPv6AcceptRouterAdvertisements=</literal>.</para> + <literal>IPv6AcceptRA=</literal>.</para> <para>Furthermore, note that by default the domain name specified through DHCP is not used for name resolution. @@ -527,24 +527,20 @@ <literal>no</literal>.</para></listitem> </varlistentry> <varlistentry> - <term><varname>IPv6AcceptRouterAdvertisements=</varname></term> - <listitem><para>Force the setting of the <filename>accept_ra</filename> - (router advertisements) setting for the interface. - When unset, the kernel default is used, and router - advertisements are accepted only when local forwarding - is disabled for that interface. - When router advertisements are accepted, they will - trigger the start of the DHCPv6 client if the relevant - flags are passed, or if no routers are found on the link. - Takes a boolean. If true, router advertisements are - accepted, when false, router advertisements are ignored, - independently of the local forwarding state.</para> - - <para>See - <ulink url="https://www.kernel.org/doc/Documentation/networking/ip-sysctl.txt">ip-sysctl.txt</ulink> - in the kernel documentation, but note that systemd's - setting of <constant>1</constant> corresponds to - kernel's setting of <constant>2</constant>.</para> + <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> @@ -583,6 +579,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 @@ -799,7 +801,7 @@ 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 to single-label names. It is generally safer to use the supplied domain + 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> @@ -839,7 +841,7 @@ <term><varname>ClientIdentifier=</varname></term> <listitem> <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 a RFC4361-compliant Client ID.</para> + or <literal>duid</literal> (the default, see below) to use an RFC4361-compliant Client ID.</para> </listitem> </varlistentry> @@ -899,6 +901,47 @@ </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> + </variablelist> + </refsect1> + + + <refsect1> <title>[DHCPServer] Section Options</title> <para>The <literal>[DHCPServer]</literal> section contains settings for the DHCP server, if enabled via the @@ -1093,6 +1136,39 @@ </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> @@ -1139,6 +1215,26 @@ Name=enp2s0 Bridge=bridge0</programlisting> </example> <example> + <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] @@ -1189,6 +1285,17 @@ 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> diff --git a/man/systemd.nspawn.xml b/man/systemd.nspawn.xml index 3683412c14..b1344d6c10 100644 --- a/man/systemd.nspawn.xml +++ b/man/systemd.nspawn.xml @@ -146,7 +146,8 @@ 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> + <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> @@ -257,7 +258,17 @@ <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). </para></listitem> + (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> @@ -358,13 +369,11 @@ <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).</para></listitem> + <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> diff --git a/man/systemd.offline-updates.xml b/man/systemd.offline-updates.xml index 946234ad90..ae53b8552d 100644 --- a/man/systemd.offline-updates.xml +++ b/man/systemd.offline-updates.xml @@ -93,7 +93,7 @@ <listitem> <para>As the first step, the update script should check if the - <filename>/system-update</filename> symlink points to the the location used by that update + <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 diff --git a/man/systemd.resource-control.xml b/man/systemd.resource-control.xml index 066f2cc19b..bf44a68345 100644 --- a/man/systemd.resource-control.xml +++ b/man/systemd.resource-control.xml @@ -92,16 +92,14 @@ <refsect1> <title>Automatic Dependencies</title> - <para>Units with the <varname>Slice=</varname> setting set get - automatic <varname>Requires=</varname> and - <varname>After=</varname> dependencies on the specified slice - unit.</para> + <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>Unified control group hierarchy is the new version of kernel control group interface. Depending on the + <para>The unified control group hierarchy is the new version of kernel control group interface. Depending on the resource type, there are differences in resource control capabilities. Also, because of interface changes, some resource types have a separate set of options on the unified hierarchy.</para> @@ -114,6 +112,13 @@ prefixed ones. On unified hierarchy, IO resource control also applies to buffered writes.</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> </variablelist> </para> @@ -213,23 +218,89 @@ </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>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. 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 + <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> @@ -256,15 +327,12 @@ <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. 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>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 diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 6641dfed4f..875d368fcf 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -202,8 +202,9 @@ 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> @@ -287,17 +288,14 @@ <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>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 diff --git a/man/systemd.special.xml b/man/systemd.special.xml index 26974ed73f..18ad8f92e5 100644 --- a/man/systemd.special.xml +++ b/man/systemd.special.xml @@ -127,9 +127,9 @@ <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 local mount points plus @@ -473,7 +473,7 @@ <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 appropiate dependencies to make this happen. + automatically setup the appropriate dependencies to make this happen. </para> </listitem> </varlistentry> @@ -497,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> @@ -509,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> @@ -579,6 +580,11 @@ <varlistentry> <term><filename>sysinit.target</filename></term> <listitem> + <para>systemd automatically adds dependencies of the types + <varname>Requires=</varname> and <varname>After=</varname> + for this target unit to all services (except for those with + <varname>DefaultDependencies=no</varname>).</para> + <para>This target pulls in the services required for system initialization. System services pulled in by this target should declare <varname>DefaultDependencies=no</varname> and specify diff --git a/man/systemd.target.xml b/man/systemd.target.xml index ab910d75dd..2e35e54fc4 100644 --- a/man/systemd.target.xml +++ b/man/systemd.target.xml @@ -82,11 +82,20 @@ <refsect1> <title>Automatic Dependencies</title> - <para>Unless <varname>DefaultDependencies=</varname> in the <literal>[Unit]</literal> section is set to - <option>no</option>, target units will implicitly complement all configured dependencies of type - <varname>Wants=</varname>, <varname>Requires=</varname> with dependencies of type <varname>After=</varname>, unless - an ordering dependency of any kind between the target and the respective other unit is already in place. Note that - this behaviour is disabled if either unit has <varname>DefaultDependencies=no</varname>.</para> + <para>Unless <varname>DefaultDependencies=</varname> is set to + <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 ffcac82263..aae3accb6c 100644 --- a/man/systemd.time.xml +++ b/man/systemd.time.xml @@ -217,8 +217,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 @@ -226,8 +226,9 @@ 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 @@ -262,17 +263,18 @@ <para>Examples for valid timestamps and their normalized form:</para> -<programlisting> Sat,Thu,Mon-Wed,Sat-Sun → Mon-Thu,Sat,Sun *-*-* 00:00:00 +<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..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 +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 @@ -281,6 +283,7 @@ Wed-Sat,Tue 12-10-15 1:2:3 → Tue-Sat 2012-10-15 01:02:03 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 diff --git a/man/systemd.timer.xml b/man/systemd.timer.xml index 0fa95e97a8..4fe140e4bc 100644 --- a/man/systemd.timer.xml +++ b/man/systemd.timer.xml @@ -76,7 +76,7 @@ <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 continously even after the service's main process + 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> diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 341789cd47..85a7b12d76 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -1234,7 +1234,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> diff --git a/man/systemd.xml b/man/systemd.xml index e05a9d6e29..4f0201fc76 100644 --- a/man/systemd.xml +++ b/man/systemd.xml @@ -1024,25 +1024,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> diff --git a/man/udev_device_get_syspath.xml b/man/udev_device_get_syspath.xml index b54749ed56..014f43b21c 100644 --- a/man/udev_device_get_syspath.xml +++ b/man/udev_device_get_syspath.xml @@ -184,10 +184,10 @@ 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/udevadm.xml b/man/udevadm.xml index 8c1abd2770..1c7921f5bd 100644 --- a/man/udevadm.xml +++ b/man/udevadm.xml @@ -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> |