diff options
Diffstat (limited to 'man')
60 files changed, 2484 insertions, 672 deletions
diff --git a/man/coredumpctl.xml b/man/coredumpctl.xml index efbc655a76..0f1afe77c3 100644 --- a/man/coredumpctl.xml +++ b/man/coredumpctl.xml @@ -86,8 +86,8 @@ </varlistentry> <varlistentry> - <term><option>-F</option></term> - <term><option>--field=</option></term> + <term><option>-F</option> <replaceable>FIELD</replaceable></term> + <term><option>--field=</option><replaceable>FIELD</replaceable></term> <listitem><para>Print all possible data values the specified field takes in matching coredump entries of the @@ -95,13 +95,21 @@ </varlistentry> <varlistentry> - <term><option>-o</option></term> - <term><option>--output=FILE</option></term> + <term><option>-o</option> <replaceable>FILE</replaceable></term> + <term><option>--output=</option><replaceable>FILE</replaceable></term> <listitem><para>Write the core to <option>FILE</option>. </para></listitem> </varlistentry> + <varlistentry> + <term><option>-D</option> <replaceable>DIR</replaceable></term> + <term><option>--directory=</option><replaceable>DIR</replaceable></term> + + <listitem><para>Use the journal files in the specified <option>DIR</option>. + </para></listitem> + </varlistentry> + <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" /> @@ -132,7 +140,7 @@ <listitem><para>Extract the last coredump matching specified characteristics. The coredump will be written on standard output, unless an output file is specified with - <option>-o/--output</option>. </para></listitem> + <option>--output=</option>. </para></listitem> </varlistentry> <varlistentry> diff --git a/man/file-hierarchy.xml b/man/file-hierarchy.xml index 3a5627d196..058998b51f 100644 --- a/man/file-hierarchy.xml +++ b/man/file-hierarchy.xml @@ -86,7 +86,7 @@ <listitem><para>The boot partition used for bringing up the system. On EFI systems this is possibly the EFI System Partition, also see - <citerefentry><refentrytitle>systemd-efi-boot-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>. This directory is usually strictly local to the host, and should be considered read-only, except when a new kernel or boot loader is installed. This directory only exists on @@ -804,7 +804,7 @@ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-path</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-efi-boot-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>, diff --git a/man/journalctl.xml b/man/journalctl.xml index ca933645a9..91a5536ade 100644 --- a/man/journalctl.xml +++ b/man/journalctl.xml @@ -437,13 +437,11 @@ <varlistentry> <term><option>-t</option></term> - <term><option>--identifier=<replaceable>SYSLOG_IDENTIFIER</replaceable>|<replaceable>PATTERN</replaceable></option></term> + <term><option>--identifier=<replaceable>SYSLOG_IDENTIFIER</replaceable></option></term> <listitem><para>Show messages for the specified syslog - identifier <replaceable>SYSLOG_IDENTIFIER</replaceable>, or - for any of the messages with a - <literal>SYSLOG_IDENTIFIER</literal> matched by - <replaceable>PATTERN</replaceable>.</para> + identifier + <replaceable>SYSLOG_IDENTIFIER</replaceable>.</para> <para>This parameter can be specified multiple times.</para></listitem> @@ -536,7 +534,9 @@ </varlistentry> <varlistentry> + <term><option>-S</option></term> <term><option>--since=</option></term> + <term><option>-U</option></term> <term><option>--until=</option></term> <listitem><para>Start showing entries on or newer than the @@ -649,6 +649,7 @@ <varlistentry> <term><option>--vacuum-size=</option></term> <term><option>--vacuum-time=</option></term> + <term><option>--vacuum-files=</option></term> <listitem><para>Removes archived journal files until the disk space they use falls below the specified size (specified with @@ -658,15 +659,24 @@ timespan (specified with the usual <literal>s</literal>, <literal>min</literal>, <literal>h</literal>, <literal>days</literal>, <literal>months</literal>, - <literal>weeks</literal>, <literal>years</literal> - suffixes). Note that running <option>--vacuum-size=</option> - has only indirect effect on the output shown by + <literal>weeks</literal>, <literal>years</literal> suffixes), + or no more than the specified number of separate journal files + remain. Note that running <option>--vacuum-size=</option> has + only indirect effect on the output shown by <option>--disk-usage</option> as the latter includes active - journal files, while the former only operates on archived - journal files. <option>--vacuum-size=</option> and - <option>--vacuum-time=</option> may be combined in a single - invocation to enforce both a size and time limit on the - archived journal files.</para></listitem> + journal files, while the the vacuuming operation only operates + on archived journal files. Similar, + <option>--vacuum-files=</option> might not actually reduce the + number of journal files to below the specified number, as it + will not remove active journal + files. <option>--vacuum-size=</option>, + <option>--vacuum-time=</option> and + <option>--vacuum-files=</option> may be combined in a single + invocation to enforce any combination of a size, a time and a + number of files limit on the archived journal + files. Specifying any of these three parameters as zero is + equivalent to not enforcing the specific limit, and is thus + redundant.</para></listitem> </varlistentry> <varlistentry> @@ -767,6 +777,12 @@ complete.</para></listitem> </varlistentry> + <varlistentry> + <term><option>--rotate</option></term> + + <listitem><para>Asks the Journal daemon to rotate journal files. + </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" /> diff --git a/man/journald.conf.xml b/man/journald.conf.xml index d6fe45d40c..4464fe53ad 100644 --- a/man/journald.conf.xml +++ b/man/journald.conf.xml @@ -173,9 +173,11 @@ <term><varname>SystemMaxUse=</varname></term> <term><varname>SystemKeepFree=</varname></term> <term><varname>SystemMaxFileSize=</varname></term> + <term><varname>SystemMaxFiles=</varname></term> <term><varname>RuntimeMaxUse=</varname></term> <term><varname>RuntimeKeepFree=</varname></term> <term><varname>RuntimeMaxFileSize=</varname></term> + <term><varname>RuntimeMaxFiles=</varname></term> <listitem><para>Enforce size limits on the journal files stored. The options prefixed with <literal>System</literal> @@ -197,8 +199,7 @@ names not ending with <literal>.journal</literal> or <literal>.journal~</literal>, so only such files, located in the appropriate directories, are taken into account when - calculating current disk usage. - </para> + calculating current disk usage.</para> <para><varname>SystemMaxUse=</varname> and <varname>RuntimeMaxUse=</varname> control how much disk space @@ -210,15 +211,17 @@ and use the smaller of the two values.</para> <para>The first pair defaults to 10% and the second to 15% of - the size of the respective file system. If the file system is - nearly full and either <varname>SystemKeepFree=</varname> or - <varname>RuntimeKeepFree=</varname> is violated when - systemd-journald is started, the value will be raised to + the size of the respective file system, but each value is + capped to 4G. If the file system is nearly full and either + <varname>SystemKeepFree=</varname> or + <varname>RuntimeKeepFree=</varname> are violated when + systemd-journald is started, the limit will be raised to the percentage that is actually free. This means that if there was enough free space before and journal files were created, and subsequently something else causes the file system to fill up, journald will stop using more space, but it will not be - removing existing files to go reduce footprint either.</para> + removing existing files to reduce footprint again + either.</para> <para><varname>SystemMaxFileSize=</varname> and <varname>RuntimeMaxFileSize=</varname> control how large @@ -228,13 +231,22 @@ eighth of the values configured with <varname>SystemMaxUse=</varname> and <varname>RuntimeMaxUse=</varname>, so that usually seven - rotated journal files are kept as history.</para></listitem> + rotated journal files are kept as history.</para> <para>Specify values in bytes or use K, M, G, T, P, E as units for the specified sizes (equal to 1024, 1024²,... bytes). Note that size limits are enforced synchronously when journal files are extended, and no explicit rotation step triggered by time is needed.</para> + + <para><varname>SystemMaxFiles=</varname> and + <varname>RuntimeMaxFiles=</varname> control how many + individual journal files to keep at maximum. Note that only + archived files are deleted to reduce the number of files until + this limit is reached; active files will stay around. This + means that in effect there might still be more journal files + around in total than this limit after a vacuuming operation is + complete. This setting defaults to 100.</para></listitem> </varlistentry> <varlistentry> diff --git a/man/kernel-command-line.xml b/man/kernel-command-line.xml index eb73727027..2f81746b5e 100644 --- a/man/kernel-command-line.xml +++ b/man/kernel-command-line.xml @@ -79,8 +79,9 @@ <term><varname>systemd.unit=</varname></term> <term><varname>rd.systemd.unit=</varname></term> <term><varname>systemd.dump_core=</varname></term> - <term><varname>systemd.crash_shell=</varname></term> <term><varname>systemd.crash_chvt=</varname></term> + <term><varname>systemd.crash_shell=</varname></term> + <term><varname>systemd.crash_reboot=</varname></term> <term><varname>systemd.confirm_spawn=</varname></term> <term><varname>systemd.show_status=</varname></term> <term><varname>systemd.log_target=</varname></term> diff --git a/man/machine-id.xml b/man/machine-id.xml index 92d67a3869..db72c2a01c 100644 --- a/man/machine-id.xml +++ b/man/machine-id.xml @@ -63,7 +63,7 @@ <para>The machine ID is usually generated from a random source during system installation and stays constant for all subsequent boots. Optionally, for stateless systems, it is generated during - runtime at boot if it is found to be empty.</para> + runtime at early boot if it is found to be empty.</para> <para>The machine ID does not change based on user configuration or when hardware is replaced.</para> @@ -119,7 +119,7 @@ id[8] = (id[8] & 0x3F) | 0x80;</programlisting> <filename>/etc/machine-id</filename> originates in the <filename>/var/lib/dbus/machine-id</filename> file introduced by D-Bus. In fact, this latter file might be a symlink to - <varname>/etc/machine-id</varname>.</para> + <filename>/etc/machine-id</filename>.</para> </refsect1> <refsect1> diff --git a/man/machinectl.xml b/man/machinectl.xml index a5eb3f08e4..e2be017427 100644 --- a/man/machinectl.xml +++ b/man/machinectl.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -65,6 +65,43 @@ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> virtual machine and container registration manager <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + + <para><command>machinectl</command> may be used to execute + operations on machines and images. Machines in this sense are + considered running instances of:</para> + + <itemizedlist> + <listitem><para>Virtual Machines (VMs) that virtualize hardware + to run full operating system (OS) instances (including their kernels) + in a virtualized environment on top of the host OS.</para></listitem> + + <listitem><para>Containers that share the hardware and + OS kernel with the host OS, in order to run + OS userspace instances on top the host OS.</para></listitem> + + <listitem><para>The host system itself</para></listitem> + </itemizedlist> + + <para>Machines are identified by names that follow the same rules + as UNIX and DNS host names, for details see below. Machines are + instantiated from disk or file system images, that frequently but not + necessarily carry the same name as machines running from + them. Images in this sense are considered:</para> + + <itemizedlist> + <listitem><para>Directory trees containing an OS, including its + top-level directories <filename>/usr</filename>, + <filename>/etc</filename>, and so on.</para></listitem> + + <listitem><para>btrfs subvolumes containing OS trees, similar to + normal directory trees.</para></listitem> + + <listitem><para>Binary "raw" disk images containing MBR or GPT + partition tables and Linux file system partitions.</para></listitem> + + <listitem><para>The file system tree of the host OS itself.</para></listitem> + </itemizedlist> + </refsect1> <refsect1> @@ -138,6 +175,30 @@ </varlistentry> <varlistentry> + <term><option>--uid=</option></term> + + <listitem><para>When used with the <command>shell</command> + command, chooses the user ID to open the interactive shell + session as. If this switch is not specified, defaults to + <literal>root</literal>. Note that this switch is not + supported for the <command>login</command> command (see + below).</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--setenv=</option></term> + + <listitem><para>When used with the <command>shell</command> + command, sets an environment variable to pass to the executed + shell. Takes a pair of environment variable name and value, + separated by <literal>=</literal> as argument. This switch + may be used multiple times to set multiple environment + variables. Note that this switch is not supported for the + <command>login</command> command (see + below).</para></listitem> + </varlistentry> + + <varlistentry> <term><option>--mkdir</option></term> <listitem><para>When used with <command>bind</command> creates @@ -145,7 +206,6 @@ mount.</para></listitem> </varlistentry> - <varlistentry> <term><option>--read-only</option></term> @@ -247,9 +307,11 @@ <term><command>list</command></term> <listitem><para>List currently running (online) virtual - machines and containers. To enumerate container images that - can be started, use <command>list-images</command> (see - below).</para></listitem> + machines and containers. To enumerate machine images that can + be started, use <command>list-images</command> (see + below). Note that this command hides the special + <literal>.host</literal> machine by default. Use the + <option>--all</option> switch to show it.</para></listitem> </varlistentry> <varlistentry> @@ -267,7 +329,7 @@ </varlistentry> <varlistentry> - <term><command>show</command> <replaceable>NAME</replaceable>...</term> + <term><command>show</command> [<replaceable>NAME</replaceable>...]</term> <listitem><para>Show properties of one or more registered virtual machines or containers or the manager itself. If no @@ -316,21 +378,67 @@ </varlistentry> <varlistentry> - <term><command>login</command> <replaceable>NAME</replaceable></term> - - <listitem><para>Open an interactive terminal login session to - a container. This will create a TTY connection to a specific - container and asks for the execution of a getty on it. Note - that this is only supported for containers running + <term><command>login</command> [<replaceable>NAME</replaceable>]</term> + + <listitem><para>Open an interactive terminal login session in + a container or on the local host. If an argument is supplied + it refers to the container machine to connect to. If none is + specified, or the container name is specified as the empty + string, or the special machine name <literal>.host</literal> + (see below) is specified, the connection is made to the local + host instead. This will create a TTY connection to a specific + container or the local host and asks for the execution of a + getty on it. Note that this is only supported for containers + running <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> as init system.</para> <para>This command will open a full login prompt on the - container, which then asks for username and password. Use + container or the local host, which then asks for username and + password. Use <command>shell</command> (see below) or + <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry> + with the <option>--machine=</option> switch to directly invoke + a single command, either interactively or in the + background.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>shell</command> [[<replaceable>NAME</replaceable>@]<replaceable>NAME</replaceable> [<replaceable>PATH</replaceable> [<replaceable>ARGUMENTS</replaceable>...]]] </term> + + <listitem><para>Open an interactive shell session in a + container or on the local host. The first argument refers to + the container machine to connect to. If none is specified, or + the machine name is specified as the empty string, or the + special machine name <literal>.host</literal> (see below) is + specified, the connection is made to the local host + instead. This works similar to <command>login</command> but + immediately invokes a user process. This command runs the + specified executable with the specified arguments, or + <filename>/bin/sh</filename> if none is specified. By default + opens a <literal>root</literal> shell, but by using + <option>--uid=</option>, or by prefixing the machine name with + a username and an <literal>@</literal> character, a different + user may be selected. Use <option>--setenv=</option> to set + environment variables for the executed process.</para> + + <para>When using the <command>shell</command> command without + arguments (thus invoking the executed shell or command on the + local host) it is similar in many ways to a <citerefentry + project='die-net'><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry> + session, but unlike <command>su</command> completely isolates + the new session from the originating session, so that it + shares no process or session properties, and is in a clean and + well-defined state. It will be tracked in a new utmp, login, + audit, security and keyring session, and will not inherit any + environment variables or resource limits, among other + properties.</para> + + <para>Note that the <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry> - with the <option>--machine=</option> switch to invoke a single - command, either interactively or in the background within a - local container.</para></listitem> + may be used in place of the <command>shell</command> command, + and allows more detailed, low-level configuration of the + invoked unit. However, it is frequently more privileged than + the <command>shell</command> command.</para></listitem> </varlistentry> <varlistentry> @@ -453,7 +561,7 @@ </varlistentry> <varlistentry> - <term><command>image-status</command> <replaceable>NAME</replaceable>...</term> + <term><command>image-status</command> [<replaceable>NAME</replaceable>...]</term> <listitem><para>Show terse status information about one or more container or VM images. This function is intended to @@ -463,7 +571,7 @@ </varlistentry> <varlistentry> - <term><command>show-image</command> <replaceable>NAME</replaceable>...</term> + <term><command>show-image</command> [<replaceable>NAME</replaceable>...]</term> <listitem><para>Show properties of one or more registered virtual machine or container images, or the manager itself. If @@ -766,6 +874,41 @@ </refsect1> <refsect1> + <title>Machine and Image Names</title> + + <para>The <command>machinectl</command> tool operates on machines + and images, whose names must be chosen following strict + rules. Machine names must be suitable for use as host names + following a conservative subset of DNS and UNIX/Linux + semantics. Specifically, they must consist of one or more + non-empty label strings, separated by dots. No leading or trailing + dots are allowed. No sequences of multiple dots are allowed. The + label strings may only consists of alphanumeric characters as well + as the dash and underscore. The maximum length of a machine name + is 64 characters.</para> + + <para>A special machine with the name <literal>.host</literal> + refers to the running host system itself. This is useful for execution + operations or inspecting the host system as well. Not that + <command>machinectl list</command> will not show this special + machine unless the <option>--all</option> switch is specified.</para> + + <para>Requirements on image names are less strict, however must be + valid UTF-8, must be suitable as file names (hence not be the + single or double dot, and not include a slash), and may not + contain control characters. Since many operations search for an + image by the name of a requested machine it is recommended to name + images in the same strict fashion as machines.</para> + + <para>A special image with the name <literal>.host</literal> + refers to the image of the running host system. It is hence + conceptually maps to the special <literal>.host</literal> machine + name described above. Note that <command>machinectl + list-images</command> won't show this special image either, unless + <option>--all</option> is specified.</para> + </refsect1> + + <refsect1> <title>Files and Directories</title> <para>Machine images are preferably stored in @@ -872,6 +1015,17 @@ current directory.</para> </example> + <example> + <title>Create a new shell session</title> + + <programlisting># machinectl shell --uid=lennart</programlisting> + + <para>This creates a new shell session on the local host, for + the user ID <literal>lennart</literal>, in a <citerefentry + project='die-net'><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry>-like + fashion.</para> + </example> + </refsect1> <refsect1> diff --git a/man/networkctl.xml b/man/networkctl.xml index 388afbed93..46dab58d61 100644 --- a/man/networkctl.xml +++ b/man/networkctl.xml @@ -87,6 +87,7 @@ <xi:include href="standard-options.xml" xpointer="help" /> <xi:include href="standard-options.xml" xpointer="version" /> + <xi:include href="standard-options.xml" xpointer="no-legend" /> <xi:include href="standard-options.xml" xpointer="no-pager" /> </variablelist> diff --git a/man/nss-myhostname.xml b/man/nss-myhostname.xml index 2d36df6f6f..4481fdf8cb 100644 --- a/man/nss-myhostname.xml +++ b/man/nss-myhostname.xml @@ -111,17 +111,17 @@ <para>Here's an example <filename>/etc/nsswitch.conf</filename> file, that enables <command>myhostname</command> correctly:</para> -<programlisting>passwd: compat -group: compat -shadow: compat +<programlisting>passwd: compat mymachines +group: compat mymachines +shadow: compat -hosts: files dns mymachines <command>myhostname</command> +hosts: files resolve mymachines <command>myhostname</command> networks: files protocols: db files services: db files -ethers: db files -rpc: db files +ethers: db files +rpc: db files netgroup: nis</programlisting> @@ -143,6 +143,7 @@ netgroup: nis</programlisting> <title>See Also</title> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>getent</refentrytitle><manvolnum>1</manvolnum></citerefentry> diff --git a/man/nss-mymachines.xml b/man/nss-mymachines.xml index 41ec458e4b..92c72846c1 100644 --- a/man/nss-mymachines.xml +++ b/man/nss-mymachines.xml @@ -91,7 +91,7 @@ group: compat <command>mymachines</command> shadow: compat -hosts: files dns <command>mymachines</command> myhostname +hosts: files resolve <command>mymachines</command> myhostname networks: files protocols: db files @@ -108,6 +108,7 @@ netgroup: nis</programlisting> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>getent</refentrytitle><manvolnum>1</manvolnum></citerefentry> diff --git a/man/nss-resolve.xml b/man/nss-resolve.xml new file mode 100644 index 0000000000..7d291b83c1 --- /dev/null +++ b/man/nss-resolve.xml @@ -0,0 +1,118 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2011 Lennart Poettering + Copyright 2013 Tom Gundersen + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="nss-resolve" conditional='ENABLE_RESOLVED'> + + <refentryinfo> + <title>nss-resolve</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>nss-resolve</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>nss-resolve</refname> + <refname>libnss_resolve.so.2</refname> + <refpurpose>Provide hostname resolution via <filename>systemd-resolved.service</filename></refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>libnss_resolve.so.2</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>nss-resolve</command> is a plugin module for the + GNU Name Service Switch (NSS) functionality of the GNU C Library + (<command>glibc</command>) enabling it to resolve host names via + the + <citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry> + local network name resolution service.</para> + + <para>To activate the NSS module, <literal>resolve</literal> + has to be added to the line starting with + <literal>hosts:</literal> in + <filename>/etc/nsswitch.conf</filename>.</para> + + <para>It is recommended to place <literal>resolve</literal> early + in the <filename>nsswitch.conf</filename> line (but after the + <literal>files</literal> entry), replacing the + <literal>dns</literal> entry if it exists, to ensure DNS queries + are always routed via + <citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>Example</title> + + <para>Here's an example <filename>/etc/nsswitch.conf</filename> + file, that enables <command>resolve</command> correctly:</para> + +<programlisting>passwd: compat mymachines +group: compat mymachines +shadow: compat + +hosts: files <command>resolve</command> mymachines myhostname +networks: files + +protocols: db files +services: db files +ethers: db files +rpc: db files + +netgroup: nis</programlisting> + + <para>Note that <command>nss-resolve</command> will chain-load + <command>nss-dns</command> if + <filename>systemd-resolved.service</filename> is not running, + ensuring that basic DNS resolution continues to work if the + service is down.</para> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/os-release.xml b/man/os-release.xml index 4ca2e59706..d2e2598204 100644 --- a/man/os-release.xml +++ b/man/os-release.xml @@ -214,10 +214,11 @@ <varlistentry> <term><varname>CPE_NAME=</varname></term> - <listitem><para>A CPE name for the operating system, following - the <ulink url="https://cpe.mitre.org/specification/">Common + <listitem><para>A CPE name for the operating system, in URI + binding syntax, following the + <ulink url="http://scap.nist.gov/specifications/cpe/">Common Platform Enumeration Specification</ulink> as proposed by the - MITRE Corporation. This field is optional. Example: + NIST. This field is optional. Example: <literal>CPE_NAME="cpe:/o:fedoraproject:fedora:17"</literal> </para></listitem> </varlistentry> diff --git a/man/sd_bus_path_encode.xml b/man/sd_bus_path_encode.xml index 21c22a8f7c..696dfd00ba 100644 --- a/man/sd_bus_path_encode.xml +++ b/man/sd_bus_path_encode.xml @@ -44,7 +44,9 @@ <refnamediv> <refname>sd_bus_path_encode</refname> + <refname>sd_bus_path_encode_many</refname> <refname>sd_bus_path_decode</refname> + <refname>sd_bus_path_decode_many</refname> <refpurpose>Convert an external identifier into an object path and back</refpurpose> </refnamediv> @@ -61,11 +63,25 @@ </funcprototype> <funcprototype> + <funcdef>int <function>sd_bus_path_encode_many</function></funcdef> + <paramdef>char **<parameter>out</parameter></paramdef> + <paramdef>const char *<parameter>path_template</parameter></paramdef> + <paramdef>...</paramdef> + </funcprototype> + + <funcprototype> <funcdef>int <function>sd_bus_path_decode</function></funcdef> <paramdef>const char *<parameter>path</parameter></paramdef> <paramdef>const char *<parameter>prefix</parameter></paramdef> <paramdef>char **<parameter>ret_external_id</parameter></paramdef> </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_path_decode_many</function></funcdef> + <paramdef>const char *<parameter>path</parameter></paramdef> + <paramdef>const char *<parameter>path_template</parameter></paramdef> + <paramdef>...</paramdef> + </funcprototype> </funcsynopsis> </refsynopsisdiv> @@ -109,6 +125,28 @@ invalid in a bus object path by <literal>_</literal>, followed by a hexadecimal value. As a special case, the empty string will be replaced by a lone <literal>_</literal>.</para> + + <para><function>sd_bus_path_encode_many()</function> works like + its counterpart <function>sd_bus_path_encode()</function>, but + takes a path-template as argument and encodes multiple labels + according to its embedded directives. For each + <literal>%</literal> character found in the template, the caller + must provide a string via var-args, which will be encoded and + embedded at the position of the <literal>%</literal> character. + Any other character in the template is copied verbatim into the + encoded path.</para> + + <para><function>sd_bus_path_decode_many()</function> does the + reverse of <function>sd_bus_path_encode_many()</function>. It + decodes the passed object path, according to the given + path-template. For each <literal>%</literal> character in the + template, the caller must provide an output storage + (<literal>char **</literal>) via var-args. The decoded label + will be stored there. Each <literal>%</literal> character will + only match the current label. It will never match across labels. + Furthermore, only a single such directive is allowed per label. + If <literal>NULL</literal> is passed as output storage, the + label is verified but not returned to the caller.</para> </refsect1> <refsect1> diff --git a/man/sd_get_seats.xml b/man/sd_get_seats.xml index 4390d36ebe..f1981f7ea2 100644 --- a/man/sd_get_seats.xml +++ b/man/sd_get_seats.xml @@ -115,6 +115,29 @@ errno-style error code.</para> </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>An input parameter was invalid (out of range, + or NULL, where that's not accepted).</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + <refsect1> <title>Notes</title> diff --git a/man/sd_listen_fds.xml b/man/sd_listen_fds.xml index 9b9705eb2e..ccd1266318 100644 --- a/man/sd_listen_fds.xml +++ b/man/sd_listen_fds.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -45,6 +45,7 @@ <refnamediv> <refname>sd_listen_fds</refname> + <refname>sd_listen_fds_with_names</refname> <refname>SD_LISTEN_FDS_START</refname> <refpurpose>Check for file descriptors passed by the system manager</refpurpose> </refnamediv> @@ -59,23 +60,26 @@ <funcdef>int <function>sd_listen_fds</function></funcdef> <paramdef>int <parameter>unset_environment</parameter></paramdef> </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_listen_fds_with_names</function></funcdef> + <paramdef>int <parameter>unset_environment</parameter></paramdef> + <paramdef>char*** <parameter>names</parameter></paramdef> + </funcprototype> </funcsynopsis> </refsynopsisdiv> <refsect1> <title>Description</title> - <para><function>sd_listen_fds()</function> shall be called by a - daemon to check for file descriptors passed by the init system as - part of the socket-based activation logic.</para> - - <para>If the <parameter>unset_environment</parameter> parameter is - non-zero, <function>sd_listen_fds()</function> will unset the - <varname>$LISTEN_FDS</varname> and <varname>$LISTEN_PID</varname> - environment variables before returning (regardless of whether the - function call itself succeeded or not). Further calls to - <function>sd_listen_fds()</function> will then fail, but the - variables are no longer inherited by child processes.</para> + <para><function>sd_listen_fds()</function> may be invoked by a + daemon to check for file descriptors passed by the service manager as + part of the socket-based activation logic. It returns the number + of received file descriptors. If no file descriptors have been + received zero is returned. The first file descriptor may be found + at file descriptor number 3 + (i.e. <constant>SD_LISTEN_FDS_START</constant>), the remaining + descriptors follow at 4, 5, 6, ..., if any.</para> <para>If a daemon receives more than one file descriptor, they will be passed in the same order as configured in the systemd @@ -108,12 +112,86 @@ <literal>FDSTORE=1</literal> messages, these file descriptors are passed last, in arbitrary order, and with duplicates removed.</para> + + <para>If the <parameter>unset_environment</parameter> parameter is + non-zero, <function>sd_listen_fds()</function> will unset the + <varname>$LISTEN_FDS</varname>, <varname>$LISTEN_PID</varname> and + <varname>$LISTEN_FDNAMES</varname> environment variables before + returning (regardless of whether the function call itself + succeeded or not). Further calls to + <function>sd_listen_fds()</function> will then return zero, but the + variables are no longer inherited by child processes.</para> + + <para><function>sd_listen_fds_with_names()</function> is like + <function>sd_listen_fds()</function> but optionally also returns + an array of strings with identification names for the passed file + descriptors, if that is available, and the + <parameter>names</parameter> parameter is non-NULL. This + information is read from the <varname>$LISTEN_FDNAMES</varname> + variable, which may contain a colon-separated list of names. For + socket-activated services, these names may be configured with the + <varname>FileDescriptorName=</varname> setting in socket unit + files, see + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. For file descriptors pushed into the file descriptor + store (see above) the name is set via the + <varname>FDNAME=</varname> field transmitted via + <function>sd_pid_notify_with_fds()</function>. The primary usecase + for these names are services which accept a variety of file + descriptors which are not recognizable with functions like + <function>sd_is_socket()</function> alone, and thus require + identification via a name. It is recommended to rely on named file + descriptors only if identification via + <function>sd_is_socket()</function> and related calls is not + sufficient. Note that the names used are not unique in any + way. The returned array of strings has as many entries as file + descriptors has been received, plus a final NULL pointer + terminating the array. The caller needs to free the array itself + and each of its elements with libc's <function>free()</function> + call after use. If the <parameter>names</parameter> parameter is + NULL the call is entirely equivalent to + <function>sd_listen_fds()</function>.</para> + + <para>Under specific conditions the following automatic file + descriptor names are returned: + + <table> + <title> + <command>Special names</command> + </title> + + <tgroup cols='2'> + <thead> + <row> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>unknown</literal></entry> + <entry>The process received no name for the specific file descriptor from the service manager.</entry> + </row> + + <row> + <entry><literal>stored</literal></entry> + <entry>The file descriptor originates in the service manager's per-service file descriptor store, and the <varname>FDNAME=</varname> field was absent when the file descriptor was submitted to the service manager.</entry> + </row> + + <row> + <entry><literal>connection</literal></entry> + <entry>The service was activated in per-connection style using <varname>Accept=yes</varname> in the socket unit file, and the file descriptor is the connection socket.</entry> + </row> + </tbody> + </tgroup> + </table> + </para> </refsect1> <refsect1> <title>Return Value</title> - <para>On failure, this call returns a negative errno-style error + <para>On failure, these calls returns a negative errno-style error code. If <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname> was not set or was not correctly set for this daemon and hence no file @@ -128,13 +206,16 @@ <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> - <para>Internally, this function checks whether the - <varname>$LISTEN_PID</varname> environment variable equals the - daemon PID. If not, it returns immediately. Otherwise, it parses - the number passed in the <varname>$LISTEN_FDS</varname> + <para>Internally, <function>sd_listen_fds()</function> checks + whether the <varname>$LISTEN_PID</varname> environment variable + equals the daemon PID. If not, it returns immediately. Otherwise, + it parses the number passed in the <varname>$LISTEN_FDS</varname> environment variable, then sets the FD_CLOEXEC flag for the parsed number of file descriptors starting from SD_LISTEN_FDS_START. - Finally, it returns the parsed number.</para> + Finally, it returns the parsed + number. <function>sd_listen_fds_with_names()</function> does the + same but also parses <varname>$LISTEN_FDNAMES</varname> if + set.</para> </refsect1> <refsect1> @@ -144,15 +225,14 @@ <varlistentry> <term><varname>$LISTEN_PID</varname></term> <term><varname>$LISTEN_FDS</varname></term> + <term><varname>$LISTEN_FDNAMES</varname></term> - <listitem><para>Set by the init system - for supervised processes that use - socket-based activation. This - environment variable specifies the - data - <function>sd_listen_fds()</function> - parses. See above for - details.</para></listitem> + <listitem><para>Set by the service manager for supervised + processes that use socket-based activation. This environment + variable specifies the data + <function>sd_listen_fds()</function> and + <function>sd_listen_fds_with_names()</function> parses. See + above for details.</para></listitem> </varlistentry> </variablelist> </refsect1> @@ -167,6 +247,7 @@ <citerefentry><refentrytitle>sd_is_socket</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_is_socket_inet</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_is_socket_unix</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> diff --git a/man/sd_login_monitor_new.xml b/man/sd_login_monitor_new.xml index a7b47a3207..a8854dd590 100644 --- a/man/sd_login_monitor_new.xml +++ b/man/sd_login_monitor_new.xml @@ -161,20 +161,20 @@ is no timeout to wait for this will fill in <constant>(uint64_t) -1</constant> instead. Note that <function>poll()</function> takes a relative timeout in milliseconds rather than an absolute timeout - in microseconds. To convert the absolute 'us' timeout into + in microseconds. To convert the absolute 'µs' timeout into relative 'ms', use code like the following:</para> <programlisting>uint64_t t; int msec; sd_login_monitor_get_timeout(m, &t); if (t == (uint64_t) -1) - msec = -1; + msec = -1; else { - struct timespec ts; - uint64_t n; - clock_getttime(CLOCK_MONOTONIC, &ts); - n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000; - msec = t > n ? (int) ((t - n + 999) / 1000) : 0; + struct timespec ts; + uint64_t n; + clock_getttime(CLOCK_MONOTONIC, &ts); + n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000; + msec = t > n ? (int) ((t - n + 999) / 1000) : 0; }</programlisting> <para>The code above does not do any error checking for brevity's @@ -204,6 +204,29 @@ else { </refsect1> <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>An input parameter was invalid (out of range, + or NULL, where that's not accepted). The specified category to + watch is not known.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> <title>Notes</title> <para>The <function>sd_login_monitor_new()</function>, diff --git a/man/sd_machine_get_class.xml b/man/sd_machine_get_class.xml index 5b881ccea1..9ad7f3fc66 100644 --- a/man/sd_machine_get_class.xml +++ b/man/sd_machine_get_class.xml @@ -56,7 +56,7 @@ <funcprototype> <funcdef>int <function>sd_machine_get_class</function></funcdef> <paramdef>const char* <parameter>machine</parameter></paramdef> - <paramdef>char *<parameter>class</parameter></paramdef> + <paramdef>char **<parameter>class</parameter></paramdef> </funcprototype> <funcprototype> @@ -99,6 +99,35 @@ </refsect1> <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + + <varlistentry> + <term><constant>-ENXIO</constant></term> + + <listitem><para>The specified machine does not exist or is currently not running.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>An input parameter was invalid (out of range, + or NULL, where that's not accepted).</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> <title>Notes</title> <para>The <function>sd_machine_get_class()</function> and diff --git a/man/sd_notify.xml b/man/sd_notify.xml index 14030f56b1..2d73c27f62 100644 --- a/man/sd_notify.xml +++ b/man/sd_notify.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -229,6 +229,27 @@ below.</para></listitem> </varlistentry> + <varlistentry> + <term>FDNAME=...</term> + + <listitem><para>When used in combination with + <varname>FDSTORE=1</varname> specifies a name for the + submitted file descriptors. This name is passed to the service + during activation, and may be queried using + <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>. File + descriptors submitted without this field set, will implicitly + get the name <literal>stored</literal> assigned. Note that if + multiple file descriptors are submitted at once the specified + name will be assigned to all of them. In order to assign + different names to submitted file descriptors, submit them in + seperate invocations of + <function>sd_pid_notify_with_fds()</function>. The name may + consist of any ASCII characters, but must not contain control + characters or <literal>:</literal>. It may not be longer than + 255 characters. If a submitted name does not follow these + restrictions it is ignored.</para></listitem> + </varlistentry> + </variablelist> <para>It is recommended to prefix variable names that are not @@ -358,7 +379,7 @@ in order to continue operation after a service restart without losing state use <literal>FDSTORE=1</literal>:</para> - <programlisting>sd_pid_notify_with_fds(0, 0, "FDSTORE=1", &fd, 1);</programlisting> + <programlisting>sd_pid_notify_with_fds(0, 0, "FDSTORE=1\nFDNAME=foobar", &fd, 1);</programlisting> </example> </refsect1> @@ -367,9 +388,11 @@ <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/sd_pid_get_session.xml b/man/sd_pid_get_session.xml index 9c6706caf8..035effcaa9 100644 --- a/man/sd_pid_get_session.xml +++ b/man/sd_pid_get_session.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -50,6 +50,7 @@ <refname>sd_pid_get_machine_name</refname> <refname>sd_pid_get_slice</refname> <refname>sd_pid_get_user_slice</refname> + <refname>sd_pid_get_cgroup</refname> <refname>sd_peer_get_session</refname> <refname>sd_peer_get_unit</refname> <refname>sd_peer_get_user_unit</refname> @@ -57,6 +58,7 @@ <refname>sd_peer_get_machine_name</refname> <refname>sd_peer_get_slice</refname> <refname>sd_peer_get_user_slice</refname> + <refname>sd_peer_get_cgroup</refname> <refpurpose>Determine session, unit, owner of a session, container/VM or slice of a specific PID or socket peer</refpurpose> @@ -109,6 +111,12 @@ </funcprototype> <funcprototype> + <funcdef>int <function>sd_pid_get_cgroup</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>char **<parameter>cgroup</parameter></paramdef> + </funcprototype> + + <funcprototype> <funcdef>int <function>sd_peer_get_session</function></funcdef> <paramdef>int <parameter>fd</parameter></paramdef> <paramdef>char **<parameter>session</parameter></paramdef> @@ -149,6 +157,12 @@ <paramdef>int <parameter>fd</parameter></paramdef> <paramdef>char **<parameter>slice</parameter></paramdef> </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_peer_get_cgroup</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>char **<parameter>cgroup</parameter></paramdef> + </funcprototype> </funcsynopsis> </refsynopsisdiv> @@ -163,7 +177,7 @@ processes, user processes that are shared between multiple sessions of the same user, or kernel threads). For processes not being part of a login session this function will fail with - -ENXIO. The returned string needs to be freed with the libc + -ENODATA. The returned string needs to be freed with the libc <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> call after use.</para> @@ -175,9 +189,9 @@ paths. Note that not all processes are part of a system unit/service (e.g. user processes, or kernel threads). For processes not being part of a systemd system unit this function - will fail with -ENXIO (More specifically: this call will not work - for kernel threads.) The returned string needs to be freed with - the libc <citerefentry + will fail with -ENODATA (More specifically: this call will not + work for kernel threads.) The returned string needs to be freed + with the libc <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> call after use.</para> @@ -194,7 +208,7 @@ multiple login sessions of the same user, where <function>sd_pid_get_session()</function> will fail. For processes not being part of a login session and not being a shared process - of a user this function will fail with -ENXIO.</para> + of a user this function will fail with -ENODATA.</para> <para><function>sd_pid_get_machine_name()</function> may be used to determine the name of the VM or container is a member of. The @@ -203,7 +217,7 @@ <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> call after use. For processes not part of a VM or containers this - function fails with -ENXIO.</para> + function fails with -ENODATA.</para> <para><function>sd_pid_get_slice()</function> may be used to determine the slice unit the process is a member of. See @@ -217,6 +231,17 @@ returns the user slice (as managed by the user's systemd instance) of a process.</para> + <para><function>sd_pid_get_cgroup()</function> returns the control + group path of the specified process, relative to the root of the + hierarchy. Returns the path without trailing slash, except for + processes located in the root control group, where "/" is + returned. To find the actual control group path in the file system + the returned path needs to be prefixed with + <filename>/sys/fs/cgroup/</filename> (if the unified control group + setup is used), or + <filename>/sys/fs/cgroup/<replaceable>HIERARCHY</replaceable>/</filename> + (if the legacy multi-hierarchy control group setup is used).</para> + <para>If the <varname>pid</varname> parameter of any of these functions is passed as 0, the operation is executed for the calling process.</para> @@ -226,13 +251,14 @@ <function>sd_peer_get_user_unit()</function>, <function>sd_peer_get_owner_uid()</function>, <function>sd_peer_get_machine_name()</function>, - <function>sd_peer_get_slice()</function> and - <function>sd_peer_get_user_slice()</function> calls operate - similar to their PID counterparts, but operate on a connected - AF_UNIX socket and retrieve information about the connected peer - process. Note that these fields are retrieved via - <filename>/proc</filename>, and hence are not suitable for - authorization purposes, as they are subject to races.</para> + <function>sd_peer_get_slice()</function>, + <function>sd_peer_get_user_slice()</function> and + <function>sd_peer_get_cgroup()</function> calls operate similar to + their PID counterparts, but operate on a connected AF_UNIX socket + and retrieve information about the connected peer process. Note + that these fields are retrieved via <filename>/proc</filename>, + and hence are not suitable for authorization purposes, as they are + subject to races.</para> </refsect1> <refsect1> @@ -251,7 +277,22 @@ <variablelist> <varlistentry> - <term><constant>-ENXIO</constant></term> + <term><constant>-ESRCH</constant></term> + + <listitem><para>The specified PID does not refer to a running + process.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>-BADF</constant></term> + + <listitem><para>The specified socket file descriptor was + invalid.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENODATA</constant></term> <listitem><para>Given field is not specified for the described process or peer.</para> @@ -259,11 +300,10 @@ </varlistentry> <varlistentry> - <term><constant>-ESRCH</constant></term> + <term><constant>-EINVAL</constant></term> - <listitem><para>The specified PID does not refer to a running - process.</para> - </listitem> + <listitem><para>An input parameter was invalid (out of range, + or NULL, where that's not accepted).</para></listitem> </varlistentry> <varlistentry> diff --git a/man/sd_seat_get_active.xml b/man/sd_seat_get_active.xml index 3c57ec9ea4..4d3e0822e0 100644 --- a/man/sd_seat_get_active.xml +++ b/man/sd_seat_get_active.xml @@ -149,6 +149,43 @@ </refsect1> <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + + <varlistentry> + <term><constant>-ENODATA</constant></term> + + <listitem><para>Given field is not specified for the described + seat.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENXIO</constant></term> + + <listitem><para>The specified seat is unknown.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>An input parameter was invalid (out of range, + or NULL, where that's not accepted).</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> <title>Notes</title> <para>The <function>sd_seat_get_active()</function>, diff --git a/man/sd_session_is_active.xml b/man/sd_session_is_active.xml index 4ca3a6c150..7de9523789 100644 --- a/man/sd_session_is_active.xml +++ b/man/sd_session_is_active.xml @@ -290,6 +290,43 @@ </refsect1> <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + + <varlistentry> + <term><constant>-ENXIO</constant></term> + + <listitem><para>The specified session does not exist.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENODATA</constant></term> + + <listitem><para>Given field is not specified for the described + session.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>An input parameter was invalid (out of range, + or NULL, where that's not accepted).</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> <title>Notes</title> <para>The <function>sd_session_is_active()</function>, diff --git a/man/sd_uid_get_state.xml b/man/sd_uid_get_state.xml index b158f3528c..13ddf08c65 100644 --- a/man/sd_uid_get_state.xml +++ b/man/sd_uid_get_state.xml @@ -170,6 +170,45 @@ </refsect1> <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + + <varlistentry> + <term><constant>-ENODATA</constant></term> + + <listitem><para>Given field is not specified for the described + user.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENXIO</constant></term> + + <listitem><para>The specified seat is unknown.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>An input parameter was invalid (out of range, + or NULL, where that's not accepted). This is also returned if + the passed user ID is 0xFFFF or 0xFFFFFFFF, which are + undefined on Linux.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> <title>Notes</title> <para>Functions described here are available as a shared library, diff --git a/man/standard-conf.xml b/man/standard-conf.xml index 004f53f70c..ffc6f76294 100644 --- a/man/standard-conf.xml +++ b/man/standard-conf.xml @@ -30,7 +30,9 @@ the vendor, the recommended way is to place a symlink to <filename>/dev/null</filename> in the configuration directory in <filename>/etc/</filename>, with the same filename as the vendor - configuration file.</para> + configuration file. If the vendor configuration file is included in + the initrd image, the image has to be regenerated.</para> + </refsection> <refsection id='main-conf'> diff --git a/man/systemctl.xml b/man/systemctl.xml index 66a090049d..36edc204b7 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -101,10 +101,14 @@ <term><option>--state=</option></term> <listitem> - <para>The argument should be a comma-separated list of unit - LOAD, SUB, or ACTIVE states. When listing units, show only - those in specified states. Use <option>--state=failed</option> - to show only failed units.</para> + <para>The argument should be a comma-separated list of unit + LOAD, SUB, or ACTIVE states. When listing units, show only + those in specified states. Use <option>--state=failed</option> + to show only failed units.</para> + + <para>As a special case, if one of the arguments is + <option>help</option>, a list of allowed values will be + printed and the program will exit.</para> </listitem> </varlistentry> @@ -295,6 +299,17 @@ </varlistentry> <varlistentry> + <term><option>--fail</option></term> + + <listitem> + <para>Shorthand for <option>--job-mode=</option>fail.</para> + <para>When used with the <command>kill</command> command, + if no units were killed, the operation results in an error. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><option>-i</option></term> <term><option>--ignore-inhibitors</option></term> @@ -319,14 +334,11 @@ <term><option>--quiet</option></term> <listitem> - <para>Suppress output to standard output in - <command>snapshot</command>, - <command>is-active</command>, - <command>is-failed</command>, - <command>is-enabled</command>, - <command>is-system-running</command>, - <command>enable</command> and - <command>disable</command>.</para> + <para>Suppress printing of the results of various commands + and also the hints about truncated log lines. This does not + suppress output of commands for which the printed output is + the only result (like <command>show</command>). Errors are + always printed.</para> </listitem> </varlistentry> @@ -477,6 +489,18 @@ </varlistentry> <varlistentry> + <term><option>--message=</option></term> + + <listitem> + <para>When used with <command>halt</command>, + <command>poweroff</command>, <command>reboot</command> or + <command>kexec</command>, set a short message explaining the reason + for the operation. The message will be logged together with the + default shutdown message.</para> + </listitem> + </varlistentry> + + <varlistentry> <term><option>--now</option></term> <listitem> @@ -909,6 +933,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <varname>RequiresOverridable=</varname>, <varname>Requisite=</varname>, <varname>RequisiteOverridable=</varname>, + <varname>ConsistsOf=</varname>, <varname>Wants=</varname>, <varname>BindsTo=</varname> dependencies. If no unit is specified, <filename>default.target</filename> is implied.</para> @@ -1099,9 +1124,9 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <tgroup cols='3'> <thead> <row> - <entry>Printed string</entry> - <entry>Meaning</entry> - <entry>Return value</entry> + <entry>Name</entry> + <entry>Description</entry> + <entry>Exit Code</entry> </row> </thead> <tbody> @@ -1116,7 +1141,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <row> <entry><literal>linked</literal></entry> <entry morerows='1'>Made available through a symlink to the unit file (permanently or just in <filename>/run</filename>).</entry> - <entry morerows='1'>1</entry> + <entry morerows='1'>> 0</entry> </row> <row> <entry><literal>linked-runtime</literal></entry> @@ -1124,7 +1149,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <row> <entry><literal>masked</literal></entry> <entry morerows='1'>Disabled entirely (permanently or just in <filename>/run</filename>).</entry> - <entry morerows='1'>1</entry> + <entry morerows='1'>> 0</entry> </row> <row> <entry><literal>masked-runtime</literal></entry> @@ -1142,7 +1167,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <row> <entry><literal>disabled</literal></entry> <entry>Unit file is not enabled.</entry> - <entry>1</entry> + <entry>> 0</entry> </row> </tbody> </tgroup> @@ -1453,22 +1478,25 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <listitem> <para>Checks whether the system is operational. This - returns success when the system is fully up and running, - meaning not in startup, shutdown or maintenance - mode. Failure is returned otherwise. In addition, the + returns success (exit code 0) when the system is fully up + and running, specifically not in startup, shutdown or + maintenance mode, and with no failed services. Failure is + returned otherwise (exit code non-zero). In addition, the current state is printed in a short string to standard output, see table below. Use <option>--quiet</option> to suppress this output.</para> <table> - <title>Manager Operational States</title> - <tgroup cols='2'> - <colspec colname='name' /> - <colspec colname='description' /> + <title><command>is-system-running</command> output</title> + <tgroup cols='3'> + <colspec colname='name'/> + <colspec colname='description'/> + <colspec colname='exit-code'/> <thead> <row> <entry>Name</entry> <entry>Description</entry> + <entry>Exit Code</entry> </row> </thead> <tbody> @@ -1478,32 +1506,53 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <filename>basic.target</filename> is reached or the <varname>maintenance</varname> state entered. </para></entry> + <entry>> 0</entry> </row> <row> <entry><varname>starting</varname></entry> <entry><para>Late bootup, before the job queue becomes idle for the first time, or one of the rescue targets are reached.</para></entry> + <entry>> 0</entry> </row> <row> <entry><varname>running</varname></entry> <entry><para>The system is fully operational.</para></entry> + <entry>0</entry> </row> <row> <entry><varname>degraded</varname></entry> <entry><para>The system is operational but one or more units failed.</para></entry> + <entry>> 0</entry> </row> <row> <entry><varname>maintenance</varname></entry> <entry><para>The rescue or emergency target is active.</para></entry> + <entry>> 0</entry> </row> <row> <entry><varname>stopping</varname></entry> <entry><para>The manager is shutting down.</para></entry> + <entry>> 0</entry> + </row> + <row> + <entry><varname>offline</varname></entry> + <entry><para>The manager is not + running. Specifically, this is the operational + state if an incompatible program is running as + system manager (PID 1).</para></entry> + <entry>> 0</entry> + </row> + <row> + <entry><varname>unknown</varname></entry> + <entry><para>The operational state could not be + determined, due to lack of resources or another + error cause.</para></entry> + <entry>> 0</entry> </row> </tbody> </tgroup> @@ -1612,13 +1661,17 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service </varlistentry> <varlistentry> - <term><command>exit</command></term> + <term><command>exit <optional><replaceable>EXIT_CODE</replaceable></optional></command></term> <listitem> <para>Ask the systemd manager to quit. This is only supported for user service managers (i.e. in conjunction - with the <option>--user</option> option) and will fail - otherwise.</para> + with the <option>--user</option> option) or in containers + and is equivalent to <command>poweroff</command> otherwise.</para> + + <para>The systemd manager can exit with a non-zero exit + code if the optional argument + <replaceable>EXIT_CODE</replaceable> is given.</para> </listitem> </varlistentry> diff --git a/man/systemd-activate.xml b/man/systemd-activate.xml index 3b854fd8ec..90e974c991 100644 --- a/man/systemd-activate.xml +++ b/man/systemd-activate.xml @@ -115,6 +115,16 @@ </para></listitem> </varlistentry> + <varlistentry> + <term><option>--fdname=</option><replaceable>NAME</replaceable></term> + + <listitem><para>Specify a name for the activation file + descriptors. This is equivalent to setting + <varname>FileDescriptorName=</varname> in socket unit files, and + enables use of + <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> + </varlistentry> + <xi:include href="standard-options.xml" xpointer="help" /> <xi:include href="standard-options.xml" xpointer="version" /> </variablelist> @@ -126,6 +136,7 @@ <varlistentry> <term><varname>$LISTEN_FDS</varname></term> <term><varname>$LISTEN_PID</varname></term> + <term><varname>$LISTEN_FDNAMES</varname></term> <listitem><para>See <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> @@ -165,6 +176,8 @@ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>cat</refentrytitle><manvolnum>1</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/systemd-analyze.xml b/man/systemd-analyze.xml index 198315052f..d2db265f58 100644 --- a/man/systemd-analyze.xml +++ b/man/systemd-analyze.xml @@ -93,7 +93,13 @@ <command>systemd-analyze</command> <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="plain">set-log-level</arg> - <arg choice="opt"><replaceable>LEVEL</replaceable></arg> + <arg choice="plain"><replaceable>LEVEL</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis> + <command>systemd-analyze</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="plain">set-log-target</arg> + <arg choice="plain"><replaceable>TARGET</replaceable></arg> </cmdsynopsis> <cmdsynopsis> <command>systemd-analyze</command> @@ -168,6 +174,13 @@ <option>--log-level=</option> described in <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para> + <para><command>systemd-analyze set-log-target + <replaceable>TARGET</replaceable></command> changes the current log + target of the <command>systemd</command> daemon to + <replaceable>TARGET</replaceable> (accepts the same values as + <option>--log-target=</option> described in + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para> + <para><command>systemd-analyze verify</command> will load unit files and print warnings if any errors are detected. Files specified on the command line will be loaded, but also any other diff --git a/man/systemd-ask-password.xml b/man/systemd-ask-password.xml index 877c71af53..10bb529b81 100644 --- a/man/systemd-ask-password.xml +++ b/man/systemd-ask-password.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -72,17 +72,28 @@ plugged in or at boot, entering an SSL certificate passphrase for web and VPN servers.</para> - <para>Existing agents are: a boot-time password agent asking the - user for passwords using Plymouth; a boot-time password agent - querying the user directly on the console; an agent requesting - password input via a - <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> - message; an agent suitable for running in a GNOME session; a - command line agent which can be started temporarily to process - queued password requests; a TTY agent that is temporarily spawned - during - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - invocations.</para> + <para>Existing agents are: + <itemizedlist> + + <listitem><para>A boot-time password agent asking the user for + passwords using Plymouth</para></listitem> + + <listitem><para>A boot-time password agent querying the user + directly on the console</para></listitem> + + <listitem><para>An agent requesting password input via a + <citerefentry + project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> + message</para></listitem> + + <listitem><para>A command line agent which can be started + temporarily to process queued password + requests</para></listitem> + + <listitem><para>A TTY agent that is temporarily spawned during + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + invocations</para></listitem> + </itemizedlist></para> <para>Additional password agents may be implemented according to the <ulink @@ -112,6 +123,38 @@ </varlistentry> <varlistentry> + <term><option>--id=</option></term> + <listitem><para>Specify an identifier for this password + query. This identifier is freely choosable and allows + recognition of queries by involved agents. It should include + the subsystem doing the query and the specific object the + query is done for. Example: + <literal>--id=cryptsetup:/dev/sda5</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--keyname=</option></term> + <listitem><para>Configure a kernel keyring key name to use as + cache for the password. If set, then the tool will try to push + any collected passwords into the kernel keyring of the root + user, as a key of the specified name. If combined with + <option>--accept-cached</option> it will also try to retrieve + the such cached passwords from the key in the kernel keyring + instead of querying the user right-away. By using this option + the kernel keyring may be used as effective cache to avoid + repeatedly asking users for passwords, if there are multiple + objects that may be unlocked with the same password. The + cached key will have a timeout of 2.5min set, after which it + will be purged from the kernel keyring. Note that it is + possible to cache multiple passwords under the same keyname, + in which case they will be stored as NUL-separated list of + passwords. Use + <citerefentry><refentrytitle>keyctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to access the cached key via the kernel keyring + directly. Example: <literal>--keyname=cryptsetup</literal></para></listitem> + </varlistentry> + + <varlistentry> <term><option>--timeout=</option></term> <listitem><para>Specify the query timeout in seconds. Defaults @@ -138,7 +181,7 @@ <term><option>--accept-cached</option></term> <listitem><para>If passed, accept cached passwords, i.e. - passwords previously typed in.</para></listitem> + passwords previously typed in. </para></listitem> </varlistentry> <varlistentry> @@ -166,6 +209,7 @@ <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>keyctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> </para> diff --git a/man/systemd-cgtop.xml b/man/systemd-cgtop.xml index d4b041a1f9..1c90c0a659 100644 --- a/man/systemd-cgtop.xml +++ b/man/systemd-cgtop.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -64,10 +64,10 @@ regular intervals (by default every 1s), similar in style to <citerefentry project='man-pages'><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> - <para>If <command>systemd-cgtop</command> is not connected to a tty, no - column headers are printed and the default is to only run one iteration. - The <varname>--iterations</varname> argument, if given, is still honored. - This mode is suitable for scripting.</para> + <para>If <command>systemd-cgtop</command> is not connected to a + tty, no column headers are printed and the default is to only run + one iteration. The <varname>--iterations=</varname> argument, if + given, is honored. This mode is suitable for scripting.</para> <para>Resource usage is only accounted for control groups in the relevant hierarchy, i.e. CPU usage is only accounted for control @@ -104,6 +104,7 @@ <variablelist> <varlistentry> <term><option>-p</option></term> + <term><option>--order=path</option></term> <listitem><para>Order by control group path name.</para></listitem> @@ -111,25 +112,28 @@ <varlistentry> <term><option>-t</option></term> + <term><option>--order=tasks</option></term> - <listitem><para>Order by number of tasks in control group - (i.e. threads and processes).</para></listitem> + <listitem><para>Order by number of tasks/processes in the control group.</para></listitem> </varlistentry> <varlistentry> <term><option>-c</option></term> + <term><option>--order=cpu</option></term> <listitem><para>Order by CPU load.</para></listitem> </varlistentry> <varlistentry> <term><option>-m</option></term> + <term><option>--order=memory</option></term> <listitem><para>Order by memory usage.</para></listitem> </varlistentry> <varlistentry> <term><option>-i</option></term> + <term><option>--order=io</option></term> <listitem><para>Order by disk I/O load.</para></listitem> </varlistentry> @@ -140,7 +144,7 @@ <listitem><para>Run in "batch" mode: do not accept input and run until the iteration limit set with - <option>--iterations</option> is exhausted or until killed. + <option>--iterations=</option> is exhausted or until killed. This mode could be useful for sending output from <command>systemd-cgtop</command> to other programs or to a file.</para></listitem> @@ -156,11 +160,67 @@ </varlistentry> <varlistentry> + <term><option>--cpu=percentage</option></term> + <term><option>--cpu=time</option></term> + + <listitem><para>Controls whether the CPU usage is shown as + percentage or time. By default the CPU usage is shown as + percentage. This setting may also be toggled at runtime by + pressing the <keycap>%</keycap> key.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-P</option></term> + + <listitem><para>Count only userspace processes instead of all + tasks. By default all tasks are counted: each kernel thread + and each userspace thread individually. With this setting + kernel threads are excluded from the counting and each + userspace process only counts as one, regardless how many + threads it consists of. This setting may also be toggled at + runtime by pressing the <keycap>P</keycap> key. This option + may not be combined with + <option>-k</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-k</option></term> + + <listitem><para>Count only userspace processes and kernel + threads instead of all tasks. By default all tasks are + counted: each kernel thread and each userspace thread + individually. With this setting kernel threads are included in + the counting and each userspace process only counts as on one, + regardless how many threads it consists of. This setting may + also be toggled at runtime by pressing the <keycap>k</keycap> + key. This option may not be combined with + <option>-P</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--recursive=</option></term> + + <listitem><para>Controls whether the number of processes shown + for a control group shall include all processes that are + contained in any of the child control groups as well. Takes a + boolean argument, defaults to <literal>yes</literal>. If + enabled the processes in child control groups are included, if + disabled only the processes in the control group itself are + counted. This setting may also be toggled at runtime by + pressing the <keycap>r</keycap> key. Note that this setting + only applies to process counting, i.e. when the + <option>-P</option> or <option>-k</option> options are + used. It has not effect if all tasks are counted, in which + case the counting is always recursive.</para></listitem> + </varlistentry> + + <varlistentry> <term><option>-n</option></term> <term><option>--iterations=</option></term> - <listitem><para>Perform only this many iterations. A value of 0 - indicates that the program should run indefinitely.</para></listitem> + <listitem><para>Perform only this many iterations. A value of + 0 indicates that the program should run + indefinitely.</para></listitem> </varlistentry> <varlistentry> @@ -168,10 +228,11 @@ <term><option>--delay=</option></term> <listitem><para>Specify refresh delay in seconds (or if one of - <literal>ms</literal>, - <literal>us</literal>, + <literal>ms</literal>, <literal>us</literal>, <literal>min</literal> is specified as unit in this time - unit).</para></listitem> + unit). This setting may also be increased and decreased at + runtime by pressing the <keycap>+</keycap> and + <keycap>-</keycap> keys.</para></listitem> </varlistentry> <varlistentry> @@ -185,13 +246,21 @@ 3.</para></listitem> </varlistentry> + <varlistentry> + <term><option>-M <replaceable>MACHINE</replaceable></option></term> + <term><option>--machine=<replaceable>MACHINE</replaceable></option></term> + + <listitem><para>Limit control groups shown to the part + corresponding to the container + <replaceable>MACHINE</replaceable>.</para></listitem> + </varlistentry> + <xi:include href="standard-options.xml" xpointer="help" /> <xi:include href="standard-options.xml" xpointer="version" /> </variablelist> </refsect1> - <refsect1> <title>Keys</title> @@ -200,49 +269,84 @@ <variablelist> <varlistentry> - <term>h</term> + <term><keycap>h</keycap></term> <listitem><para>Shows a short help text.</para></listitem> </varlistentry> <varlistentry> - <term>SPACE</term> + <term><keycap function="space"/></term> <listitem><para>Immediately refresh output.</para></listitem> </varlistentry> <varlistentry> - <term>q</term> + <term><keycap>q</keycap></term> <listitem><para>Terminate the program.</para></listitem> </varlistentry> - <varlistentry> - <term>p</term> - <term>t</term> - <term>c</term> - <term>m</term> - <term>i</term> + <term><keycap>p</keycap></term> + <term><keycap>t</keycap></term> + <term><keycap>c</keycap></term> + <term><keycap>m</keycap></term> + <term><keycap>i</keycap></term> <listitem><para>Sort the control groups by path, number of - tasks, CPU load, memory usage, or IO load, respectively. - </para></listitem> + tasks, CPU load, memory usage, or IO load, respectively. This + setting may also be controlled using the + <option>--order=</option> command line + switch.</para></listitem> </varlistentry> <varlistentry> - <term>%</term> + <term><keycap>%</keycap></term> <listitem><para>Toggle between showing CPU time as time or - percentage.</para></listitem> + percentage. This setting may also be controlled using the + <option>--cpu=</option> command line switch.</para></listitem> </varlistentry> <varlistentry> - <term>+</term> - <term>-</term> + <term><keycap>+</keycap></term> + <term><keycap>-</keycap></term> <listitem><para>Increase or decrease refresh delay, - respectively.</para></listitem> + respectively. This setting may also be controlled using the + <option>--delay=</option> command line + switch.</para></listitem> + </varlistentry> + + <varlistentry> + <term><keycap>P</keycap></term> + + <listitem><para>Toggle between counting all tasks, or only + userspace processes. This setting may also be controlled using + the <option>-P</option> command line switch (see + above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><keycap>k</keycap></term> + + <listitem><para>Toggle between counting all tasks, or only + userspace processes and kernel threads. This setting may also + be controlled using the <option>-k</option> command line + switch (see above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><keycap>r</keycap></term> + + <listitem><para>Toggle between recursively including or + excluding processes in child control groups in control group + process counts. This setting may also be controlled using the + <option>--recursive=</option> command line switch. This key is + not available of all tasks are counted, it is only available + if processes are counted, as enabled with the + <keycap>P</keycap> or <keycap>k</keycap> + keys.</para></listitem> </varlistentry> </variablelist> diff --git a/man/systemd-detect-virt.xml b/man/systemd-detect-virt.xml index 40755a24d0..9ea9141d4d 100644 --- a/man/systemd-detect-virt.xml +++ b/man/systemd-detect-virt.xml @@ -88,7 +88,7 @@ </thead> <tbody> <row> - <entry morerows="8">VM</entry> + <entry morerows="9">VM</entry> <entry><varname>qemu</varname></entry> <entry>QEMU software virtualization</entry> </row> @@ -134,6 +134,11 @@ </row> <row> + <entry><varname>parallels</varname></entry> + <entry>Parallels Desktop, Parallels Server</entry> + </row> + + <row> <entry morerows="5">container</entry> <entry><varname>openvz</varname></entry> <entry>OpenVZ/Virtuozzo</entry> diff --git a/man/systemd-efi-boot-generator.xml b/man/systemd-efi-boot-generator.xml deleted file mode 100644 index 23464bcf15..0000000000 --- a/man/systemd-efi-boot-generator.xml +++ /dev/null @@ -1,85 +0,0 @@ -<?xml version="1.0"?> -<!--*-nxml-*--> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> -<!-- - This file is part of systemd. - - Copyright 2013 Lennart Poettering - - systemd is free software; you can redistribute it and/or modify it - under the terms of the GNU Lesser General Public License as published by - the Free Software Foundation; either version 2.1 of the License, or - (at your option) any later version. - - systemd is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public License - along with systemd; If not, see <http://www.gnu.org/licenses/>. ---> -<refentry id="systemd-efi-boot-generator"> - - <refentryinfo> - <title>systemd-efi-boot-generator</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-efi-boot-generator</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-efi-boot-generator</refname> - <refpurpose>Generator for automatically mounting the - EFI System Partition used by the current boot to - <filename>/boot</filename></refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/usr/lib/systemd/system-generators/systemd-efi-boot-generator</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-efi-boot-generator</filename> is a - generator that automatically creates mount and automount units for - the EFI System Partition (ESP), mounting it to - <filename>/boot</filename>. Note that this generator will execute - no operation on non-EFI systems, on systems where the boot loader - does not communicate the used ESP to the OS, on systems where - <filename>/boot</filename> is an explicitly configured mount (for - example, listed in - <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>) - or where the <filename>/boot</filename> mount point is non-empty. - Since this generator creates an automount unit, the mount will - only be activated on-demand, when accessed.</para> - - <para><filename>systemd-efi-boot-generator</filename> implements - <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-fsck@.service.xml b/man/systemd-fsck@.service.xml index e4ffcba168..6d05e90e7b 100644 --- a/man/systemd-fsck@.service.xml +++ b/man/systemd-fsck@.service.xml @@ -61,7 +61,7 @@ responsible for file system checks. They are instantiated for each device that is configured for file system checking. <filename>systemd-fsck-root.service</filename> is responsible for - file system checks on the root file system, but in only if the + file system checks on the root file system, but only if the root filesystem wasn't checked in the initramfs. <filename>systemd-fsck@.service</filename> is used for all other file systems and for the root file system in the initramfs.</para> diff --git a/man/systemd-gpt-auto-generator.xml b/man/systemd-gpt-auto-generator.xml index 710c2e065e..f569ea3cde 100644 --- a/man/systemd-gpt-auto-generator.xml +++ b/man/systemd-gpt-auto-generator.xml @@ -69,7 +69,7 @@ units are explicitly configured (for example, listed in <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>), - the units this generator creates are overriden, but additional + the units this generator creates are overridden, but additional automatic dependencies might be created.</para> <para>This generator will only look for root partitions on the @@ -150,10 +150,16 @@ <filename>/etc/crypttab</filename> with a different device mapper device name.</para> - <para>Also note that - <citerefentry><refentrytitle>systemd-efi-boot-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> - will mount the EFI System Partition (ESP) to - <filename>/boot</filename> if not otherwise mounted.</para> + <para>Mount and automount units for the EFI System Partition (ESP), + mounting it to <filename>/boot</filename> are generated on EFI + systems, where the boot loader communicates the used ESP to the operating + system. Since this generator creates an automount unit, the mount will + only be activated on-demand, when accessed. On systems where + <filename>/boot</filename> is an explicitly configured mount + (for example, listed in + <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>) + or where the <filename>/boot</filename> mount point is non-empty, no + mount units are generated.</para> <para>When using this generator in conjunction with btrfs file systems, make sure to set the correct default subvolumes on them, @@ -170,7 +176,6 @@ <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-efi-boot-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, diff --git a/man/systemd-journald.service.xml b/man/systemd-journald.service.xml index 6b572b8725..08c631e5a1 100644 --- a/man/systemd-journald.service.xml +++ b/man/systemd-journald.service.xml @@ -101,7 +101,10 @@ reboot. To make the data persistent, it is sufficient to create <filename>/var/log/journal/</filename> where <filename>systemd-journald</filename> will then store the - data.</para> + data:</para> + + <programlisting>mkdir -p /var/log/journal +systemd-tmpfiles --create --prefix /var/log/journal</programlisting> <para><filename>systemd-journald</filename> will forward all received log messages to the diff --git a/man/systemd-machine-id-commit.service.xml b/man/systemd-machine-id-commit.service.xml index 7c8fc0874e..10f36b3008 100644 --- a/man/systemd-machine-id-commit.service.xml +++ b/man/systemd-machine-id-commit.service.xml @@ -42,55 +42,50 @@ <refnamediv> <refname>systemd-machine-id-commit.service</refname> - <refpurpose>Commit transient machine-id to disk</refpurpose> + <refpurpose>Commit a transient machine-id to disk</refpurpose> </refnamediv> <refsynopsisdiv> <para><filename>systemd-machine-id-commit.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-machine-id-commit</filename></para> </refsynopsisdiv> <refsect1> <title>Description</title> - <para><filename>systemd-machine-id-commit.service</filename> is a - service responsible for committing any transient - <filename>/etc/machine-id</filename> file to a writable file + <para><filename>systemd-machine-id-commit.service</filename> is an + early-boot service responsible for committing transient + <filename>/etc/machine-id</filename> files to a writable disk file system. See <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more information about this file.</para> - - <para>This service is started shortly after - <filename>local-fs.target</filename> if - <filename>/etc/machine-id</filename> is an independent mount point - (probably a tmpfs one) and /etc is writable. - <command>systemd-machine-id-commit</command> will then write - current machine ID to disk and unmount the transient + for more information about machine IDs.</para> + + <para>This service is started after + <filename>local-fs.target</filename> in case + <filename>/etc/machine-id</filename> is a mount point of its own + (usually from a memory file system such as + <literal>tmpfs</literal>) and /etc is writable. The service will + invoke <command>systemd-machine-id-setup --commit</command>, which + writes the current transient machine ID to disk and unmount the <filename>/etc/machine-id</filename> file in a race-free manner to - ensure that file is always valid for other processes.</para> - - <para>Note that the traditional way to initialize the machine ID - in <filename>/etc/machine-id</filename> is to use - <command>systemd-machine-id-setup</command> by system installer - tools. You can also use - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - to initialize the machine ID on mounted (but not booted) system - images. The main use case for that service is - <filename>/etc/machine-id</filename> being an empty file at boot - and initrd chaining to systemd giving it a read only file system - that will be turned read-write later during the boot - process.</para> - - <para>There is no consequence if that service fails other than a - newer machine-id will be generated during next system boot. - </para> + ensure that file is always valid and accessible for other + processes. See + <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for details.</para> + + <para>The main use case of this service are systems where + <filename>/etc/machine-id</filename> is read-only and initially + not initialized. In this case the system manager will generate a + transient machine ID file on a memory file system, and mount it + over <filename>/etc/machine-id</filename>, during the early boot + phase. This service is then invoked in a later boot phase, as soon + as <filename>/etc</filename> has been remounted writable and the + ID may thus be committed to disk to make it permanent.</para> </refsect1> <refsect1> <title>See Also</title> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-machine-id-commit</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> diff --git a/man/systemd-machine-id-commit.xml b/man/systemd-machine-id-commit.xml deleted file mode 100644 index cfb1722063..0000000000 --- a/man/systemd-machine-id-commit.xml +++ /dev/null @@ -1,123 +0,0 @@ -<?xml version='1.0'?> <!--*-nxml-*--> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - -<!-- - This file is part of systemd. - - Copyright 2014 Didier Roche - - systemd is free software; you can redistribute it and/or modify it - under the terms of the GNU Lesser General Public License as published by - the Free Software Foundation; either version 2.1 of the License, or - (at your option) any later version. - - systemd is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public License - along with systemd; If not, see <http://www.gnu.org/licenses/>. ---> - -<refentry id="systemd-machine-id-commit" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-machine-id-commit</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Didier</firstname> - <surname>Roche</surname> - <email>didrocks@ubuntu.com</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-machine-id-commit</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-machine-id-commit</refname> - <refpurpose>Commit transient machine ID to /etc/machine-id</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-machine-id-commit</command> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-machine-id-commit</command> may be used to - write on disk any transient machine ID mounted as a temporary file - system in <filename>/etc/machine-id</filename> at boot time. See - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more information about this file.</para> - - <para>This tool will execute no operation if - <filename>/etc/machine-id</filename> doesn't contain any valid - machine ID, isn't mounted as an independent temporary file system, - of <filename>/etc</filename> is read-only. If those conditions are - met, it will then write current machine ID to disk and unmount the - transient <filename>/etc/machine-id</filename> file in a race-free - manner to ensure that this file is always valid for other - processes.</para> - - <para>Note that the traditional way to initialize the machine ID - in <filename>/etc/machine-id</filename> is to use - <command>systemd-machine-id-setup</command> by system installer - tools. You can also use - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - to initialize the machine ID on mounted (but not booted) system - images.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--root=<replaceable>root</replaceable></option></term> - <listitem><para>Takes a directory path - as an argument. All paths will be - prefixed with the given alternate - <replaceable>root</replaceable> path, - including config search paths. - </para></listitem> - </varlistentry> - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned, a non-zero failure code - otherwise.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-machine-id-commit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-machine-id-setup.xml b/man/systemd-machine-id-setup.xml index 182717f524..efcf408332 100644 --- a/man/systemd-machine-id-setup.xml +++ b/man/systemd-machine-id-setup.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -35,6 +35,12 @@ <surname>Poettering</surname> <email>lennart@poettering.net</email> </author> + <author> + <contrib>Developer</contrib> + <firstname>Didier</firstname> + <surname>Roche</surname> + <email>didrocks@ubuntu.com</email> + </author> </authorgroup> </refentryinfo> @@ -59,30 +65,43 @@ <para><command>systemd-machine-id-setup</command> may be used by system installer tools to initialize the machine ID stored in - <filename>/etc/machine-id</filename> at install time with a - randomly generated ID. See + <filename>/etc/machine-id</filename> at install time, with a + provisioned or randomly generated ID. See <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information about this file.</para> - <para>This tool will execute no operation if - <filename>/etc/machine-id</filename> is already - initialized.</para> - - <para>If a valid D-Bus machine ID is already configured for the - system, the D-Bus machine ID is copied and used to initialize the - machine ID in <filename>/etc/machine-id</filename>.</para> - - <para>If run inside a KVM virtual machine and a UUID is passed via - the <option>-uuid</option> option, this UUID is used to initialize - the machine ID instead of a randomly generated one. The caller - must ensure that the UUID passed is sufficiently unique and is - different for every booted instanced of the VM.</para> - - <para>Similar, if run inside a Linux container environment and a - UUID is set for the container this is used to initialize the - machine ID. For details see the documentation of the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container - Interface</ulink>.</para> + <para>If the tool is invoked without the <option>--commit</option> + switch <filename>/etc/machine-id</filename> is initialized with a + valid, new machined ID if it is missing or empty. The new machine + ID will be acquired in the following fashion:</para> + + <orderedlist> + <listitem><para>If a valid D-Bus machine ID is already + configured for the system, the D-Bus machine ID is copied and + used to initialize the machine ID in + <filename>/etc/machine-id</filename>.</para></listitem> + + <listitem><para>If run inside a KVM virtual machine and a UUID + is was configured (via the <option>-uuid</option> + option), this UUID is used to initialize the machine ID. The + caller must ensure that the UUID passed is sufficiently unique + and is different for every booted instance of the + VM.</para></listitem> + + <listitem><para>Similar, if run inside a Linux container + environment and a UUID is configured for the container this is + used to initialize the machine ID. For details see the + documentation of the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container + Interface</ulink>.</para></listitem> + + <listitem><para>Otherwise a new ID is randomly + generated.</para></listitem> + </orderedlist> + + <para>The <option>--commit</option> switch may be used to commit a + transient machined ID to disk, making it persistent. For details, + see below.</para> <para>Use <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> @@ -97,13 +116,41 @@ <para>The following options are understood:</para> <variablelist> + <varlistentry> <term><option>--root=<replaceable>root</replaceable></option></term> - <listitem><para>Takes a directory path as an argument. All - paths will be prefixed with the given alternate - <replaceable>root</replaceable> path, including config search - paths. </para></listitem> + <listitem><para>Takes a directory path as argument. All paths + operated will be prefixed with the given alternate + <replaceable>root</replaceable> path, including the path for + <filename>/etc/machine-id</filename> itself.</para></listitem> </varlistentry> + + <varlistentry> + <term><option>--commit</option></term> + <listitem><para>Commit a transient machine ID to disk. This + command may be used to convert a transient machine ID into a + persistent one. A transient machine ID file is one that was + bind mounted from a memory file system (usually + <literal>tmpfs</literal>) to + <filename>/etc/machine-id</filename> during the early phase of + the boot process. This may happen because + <filename>/etc</filename> is initially read-only and was + missing a valid machine ID file at that point.</para> + + <para>This command will execute no operation if + <filename>/etc/machine-id</filename> is not mounted from a + memory file system, or if <filename>/etc</filename> is + read-only. The command will write the current transient + machine ID to disk and unmount the + <filename>/etc/machine-id</filename> mount point in a + race-free manner to ensure that this file is always valid and + accessible for other processes.</para> + + <para>This command is primarily used by the + <citerefentry><refentrytitle>systemd-machine-id-commit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + early-boot service.</para></listitem> + </varlistentry> + <xi:include href="standard-options.xml" xpointer="help" /> <xi:include href="standard-options.xml" xpointer="version" /> </variablelist> @@ -122,6 +169,7 @@ <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-machine-id-commit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry project='dbus'><refentrytitle>dbus-uuidgen</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> </para> diff --git a/man/systemd-networkd-wait-online.service.xml b/man/systemd-networkd-wait-online.service.xml index f53b337daa..bcc5776a8d 100644 --- a/man/systemd-networkd-wait-online.service.xml +++ b/man/systemd-networkd-wait-online.service.xml @@ -80,7 +80,8 @@ several interfaces which will be configured, but a particular one is necessary to access some network resources. This option may be used more than once to wait for multiple network - interfaces.</para></listitem> + interfaces. When used, all other interfaces are ignored. + </para></listitem> </varlistentry> <varlistentry> <term><option>--ignore=</option></term> diff --git a/man/systemd-notify.xml b/man/systemd-notify.xml index 06d5ae5319..71d501f435 100644 --- a/man/systemd-notify.xml +++ b/man/systemd-notify.xml @@ -124,7 +124,12 @@ systemd, non-zero otherwise. If this option is passed, no message is sent. This option is hence unrelated to the other options. For details about the semantics of this option, see - <citerefentry><refentrytitle>sd_booted</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> + <citerefentry><refentrytitle>sd_booted</refentrytitle><manvolnum>3</manvolnum></citerefentry>. An + alternative way to check for this state is to call + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + with the <command>is-system-running</command> command. It will + return <literal>offline</literal> if the system was not booted + with systemd. </para></listitem> </varlistentry> <xi:include href="standard-options.xml" xpointer="help" /> @@ -156,12 +161,12 @@ mkfifo /tmp/waldo systemd-notify --ready --status="Waiting for data..." while : ; do - read a < /tmp/waldo - systemd-notify --status="Processing $a" + read a < /tmp/waldo + systemd-notify --status="Processing $a" - # Do something with $a ... + # Do something with $a ... - systemd-notify --status="Waiting for data..." + systemd-notify --status="Waiting for data..." done</programlisting> </example> </refsect1> diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml index 06285edc0b..4b0e72113e 100644 --- a/man/systemd-nspawn.xml +++ b/man/systemd-nspawn.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -96,7 +96,6 @@ <para>Use a tool like <citerefentry project='mankier'><refentrytitle>dnf</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>, or <citerefentry project='archlinux'><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry> @@ -156,12 +155,15 @@ <para>If neither <option>--directory=</option>, nor <option>--image=</option> is specified the directory is - determined as <filename>/var/lib/machines/</filename> suffixed - by the machine name as specified with - <option>--machine=</option>. If neither - <option>--directory=</option>, <option>--image=</option>, nor - <option>--machine=</option> are specified, the current - directory will be used. May not be specified together with + determined by searching for a directory named the same as the + machine name specified with <option>--machine=</option>. See + <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + section "Files and Directories" for the precise search path.</para> + + <para>If neither <option>--directory=</option>, + <option>--image=</option>, nor <option>--machine=</option> + are specified, the current directory will + be used. May not be specified together with <option>--image=</option>.</para></listitem> </varlistentry> @@ -573,12 +575,17 @@ <term><option>--bind-ro=</option></term> <listitem><para>Bind mount a file or directory from the host - into the container. Either takes a path argument -- in which + into the container. Takes one of: a path argument -- in which case the specified path will be mounted from the host to the same path in the container --, or a colon-separated pair of paths -- in which case the first specified path is the source in the host, and the second path is the destination in the - container. This option may be specified multiple times for + container --, or a colon-separated triple of source path, + destination path and mount options. Mount options are comma + separated and currently only "rbind" and "norbind" + are allowed. Defaults to "rbind". Backslash escapes are interpreted so + <literal>\:</literal> may be used to embed colons in either path. + This option may be specified multiple times for creating multiple independent bind mount points. The <option>--bind-ro=</option> option creates read-only bind mounts.</para></listitem> @@ -597,7 +604,10 @@ otherwise specified). This option is particularly useful for mounting directories such as <filename>/var</filename> as tmpfs, to allow state-less systems, in particular when - combined with <option>--read-only</option>.</para></listitem> + combined with <option>--read-only</option>. + Backslash escapes are interpreted in the path so + <literal>\:</literal> may be used to embed colons in the path. + </para></listitem> </varlistentry> <varlistentry> @@ -609,6 +619,10 @@ list of colon-separated paths to the directory trees to combine and the destination mount point.</para> + <para>Backslash escapes are interpreted in the paths, so + <literal>\:</literal> may be used to embed colons in the paths. + </para> + <para>If three or more paths are specified, then the last specified path is the destination mount point in the container, all paths specified before refer to directory trees @@ -733,34 +747,86 @@ </varlistentry> <varlistentry> - <term><option>--volatile</option><replaceable>=MODE</replaceable></term> + <term><option>--volatile</option></term> + <term><option>--volatile=</option><replaceable>MODE</replaceable></term> <listitem><para>Boots the container in volatile mode. When no mode parameter is passed or when mode is specified as - <literal>yes</literal> full volatile mode is enabled. This + <option>yes</option> full volatile mode is enabled. This means the root directory is mounted as mostly unpopulated <literal>tmpfs</literal> instance, and <filename>/usr</filename> from the OS tree is mounted into it, read-only (the system thus starts up with read-only OS resources, but pristine state and configuration, any changes to the either are lost on shutdown). When the mode parameter - is specified as <literal>state</literal> the OS tree is + is specified as <option>state</option> the OS tree is mounted read-only, but <filename>/var</filename> is mounted as <literal>tmpfs</literal> instance into it (the system thus starts up with read-only OS resources and configuration, but pristine state, any changes to the latter are lost on shutdown). When the mode parameter is specified as - <literal>no</literal> (the default) the whole OS tree is made + <option>no</option> (the default) the whole OS tree is made available writable.</para> - <para>Note that setting this to <literal>yes</literal> or - <literal>state</literal> will only work correctly with + <para>Note that setting this to <option>yes</option> or + <option>state</option> will only work correctly with operating systems in the container that can boot up with only <filename>/usr</filename> mounted, and are able to populate <filename>/var</filename> automatically, as needed.</para></listitem> </varlistentry> + <varlistentry> + <term><option>--settings=</option><replaceable>MODE</replaceable></term> + + <listitem><para>Controls whether + <command>systemd-nspawn</command> shall search for and use + additional per-container settings from + <filename>.nspawn</filename> files. Takes a boolean or the + special values <option>override</option> or + <option>trusted</option>.</para> + + <para>If enabled (the default) a settings file named after the + machine (as specified with the <option>--machine=</option> + setting, or derived from the directory or image file name) + with the suffix <filename>.nspawn</filename> is searched in + <filename>/etc/systemd/nspawn/</filename> and + <filename>/run/systemd/nspawn/</filename>. If it is found + there, its settings are read and used. If it is not found + there it is subsequently searched in the same directory as the + image file or in the immediate parent of the root directory of + the container. In this case, if the file is found its settings + will be also read and used, but potentially unsafe settings + are ignored. Note that in both these cases settings on the + command line take precedence over the corresponding settings + from loaded <filename>.nspawn</filename> files, if both are + specified. Unsafe settings are considered all settings that + elevate the container's privileges or grant access to + additional resources such as files or directories of the + host. For details about the format and contents of + <filename>.nspawn</filename> files consult + <citerefentry><refentrytitle>systemd.nspawn</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para>If this option is set to <option>override</option> the + file is searched, read and used the same way, however the order of + precedence is reversed: settings read from the + <filename>.nspawn</filename> file will take precedence over + the corresponding command line options, if both are + specified.</para> + + <para>If this option is set to <option>trusted</option> the + file is searched, read and used the same way, but regardless + if found in <filename>/etc/systemd/nspawn/</filename>, + <filename>/run/systemd/nspawn/</filename> or next to the image + file or container root directory, all settings will take + effect, however command line arguments still take precedence + over corresponding settings.</para> + + <para>If disabled no <filename>.nspawn</filename> file is read + and no settings except the ones on the command line are in + effect.</para></listitem> + </varlistentry> + <xi:include href="standard-options.xml" xpointer="help" /> <xi:include href="standard-options.xml" xpointer="version" /> </variablelist> @@ -844,9 +910,9 @@ <title>See Also</title> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.nspawn</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry project='mankier'><refentrytitle>dnf</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry project='archlinux'><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, diff --git a/man/systemd-path.xml b/man/systemd-path.xml index dfc75ee0ff..4f790d2cda 100644 --- a/man/systemd-path.xml +++ b/man/systemd-path.xml @@ -64,9 +64,9 @@ <para>When invoked without arguments a list of known paths and their current values is shown. When at least one argument is - passed the path with this is name is queried and its value shown. + passed the path with this name is queried and its value shown. The variables whose name begins with <literal>search-</literal> - don't refer to individual paths, but instead a to a list of + don't refer to individual paths, but instead to a list of colon-separated search paths, in their order of precedence.</para> </refsect1> diff --git a/man/systemd-resolved.service.xml b/man/systemd-resolved.service.xml index 89ec5f8b19..96dc4f6620 100644 --- a/man/systemd-resolved.service.xml +++ b/man/systemd-resolved.service.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -61,15 +61,77 @@ resolver and an LLMNR resolver and responder. It also generates <filename>/run/systemd/resolve/resolv.conf</filename> for compatibility which may be symlinked from - <filename>/etc/resolv.conf</filename>.</para> + <filename>/etc/resolv.conf</filename>. The glibc NSS module + <citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry> + is necessary to allow libc'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 - <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - the per-link static settings in <filename>.network</filename> - files, and the per-link dynamic settings received over DHCP. See + 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, however only if it is not a symlink + to <filename>/run/systemd/resolve/resolv.conf</filename> (see above).</para> + + <para><command>systemd-resolved</command> synthesizes DNS RRs for the following cases:</para> + + <itemizedlist> + <listitem><para>The local, configured hostname is resolved to + all locally configured IP addresses ordered by their scope, or + — if none are configured — the IPv4 address 127.0.0.2 (which + is on the local loopback) and the IPv6 address ::1 (which is the + local host).</para></listitem> + + <listitem><para>The hostname <literal>localhost</literal> is + resolved to the IP addresses 127.0.0.1 and + ::1.</para></listitem> + + <listitem><para>The hostname <literal>gateway</literal> is + resolved to all current default routing gateway addresses, + ordered by their metric. This assigns a stable hostname to the + current gateway, useful for referencing it independently of the + current network configuration state.</para></listitem> + </itemizedlist> + + <para>Lookup requests are routed to the available DNS servers + and LLMNR interfaces according to the following rules:</para> + + <itemizedlist> + <listitem><para>Lookups for the special hostname + <literal>localhost</literal> are never routed to the + network.</para></listitem> + + <listitem><para>Single-label names are routed to all local + interfaces capable of IP multicasting, using the LLMNR + protocol. Lookups for IPv4 addresses are only sent via LLMNR on + IPv4, and lookups for IPv6 addresses are only sent via LLMNR on + IPv6. Lookups for the locally configured host name and the + <literal>gateway</literal> host name are never routed to + LLMNR.</para></listitem> + + <listitem><para>Multi-label names are routed to all local + interfaces that have a DNS sever configured, plus the globally + configured DNS server if there is one. Address lookups from the + link-local addres range are never routed to + DNS.</para></listitem> + </itemizedlist> + + <para>If lookups are routed to multiple interfaces, the first + successful response is returned (thus effectively merging the + lookup zones on all matching interfaces). If the lookup failed on + all interfaces the last failing response is returned.</para> + + <para>Routing of lookups may be influenced by configuring + per-interface domain names, see <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more details.</para> + for details. Lookups for a hostname ending in one of the + per-interface domains are exclusively routed to the matching + interfaces.</para> <para>Note that <filename>/run/systemd/resolve/resolv.conf</filename> should not @@ -82,6 +144,7 @@ <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> </para> diff --git a/man/systemd-rfkill@.service.xml b/man/systemd-rfkill.service.xml index 709b09d818..f464842700 100644 --- a/man/systemd-rfkill@.service.xml +++ b/man/systemd-rfkill.service.xml @@ -19,10 +19,10 @@ You should have received a copy of the GNU Lesser General Public License along with systemd; If not, see <http://www.gnu.org/licenses/>. --> -<refentry id="systemd-rfkill@.service" conditional='ENABLE_RFKILL'> +<refentry id="systemd-rfkill.service" conditional='ENABLE_RFKILL'> <refentryinfo> - <title>systemd-rfkill@.service</title> + <title>systemd-rfkill.service</title> <productname>systemd</productname> <authorgroup> @@ -36,27 +36,29 @@ </refentryinfo> <refmeta> - <refentrytitle>systemd-rfkill@.service</refentrytitle> + <refentrytitle>systemd-rfkill.service</refentrytitle> <manvolnum>8</manvolnum> </refmeta> <refnamediv> - <refname>systemd-rfkill@.service</refname> + <refname>systemd-rfkill.service</refname> + <refname>systemd-rfkill.socket</refname> <refname>systemd-rfkill</refname> - <refpurpose>Load and save the RF kill switch state at boot and shutdown</refpurpose> + <refpurpose>Load and save the RF kill switch state at boot and change</refpurpose> </refnamediv> <refsynopsisdiv> - <para><filename>systemd-rfkill@.service</filename></para> + <para><filename>systemd-rfkill.service</filename></para> + <para><filename>systemd-rfkill.socket</filename></para> <para><filename>/usr/lib/systemd/systemd-rfkill</filename></para> </refsynopsisdiv> <refsect1> <title>Description</title> - <para><filename>systemd-rfkill@.service</filename> is a service + <para><filename>systemd-rfkill.service</filename> is a service that restores the RF kill switch state at early boot and saves it - at shutdown. On disk, the RF kill switch state is stored in + on each change. On disk, the RF kill switch state is stored in <filename>/var/lib/systemd/rfkill/</filename>.</para> </refsect1> diff --git a/man/systemd-run.xml b/man/systemd-run.xml index 71b365c8eb..8850735a34 100644 --- a/man/systemd-run.xml +++ b/man/systemd-run.xml @@ -69,38 +69,41 @@ <title>Description</title> <para><command>systemd-run</command> may be used to create and - start a transient <filename>.service</filename> or a transient - <filename>.timer</filename> or a <filename>.scope</filename> unit - and run the specified <replaceable>COMMAND</replaceable> in - it.</para> + start a transient <filename>.service</filename> or + <filename>.scope</filename> unit and run the specified + <replaceable>COMMAND</replaceable> in it. It may also be used to + create and start transient <filename>.timer</filename> + units.</para> <para>If a command is run as transient service unit, it will be started and managed by the service manager like any other service, - and thus show up in the output of <command>systemctl + and thus shows up in the output of <command>systemctl list-units</command> like any other unit. It will run in a clean - and detached execution environment. <command>systemd-run</command> - will start the service asynchronously in the background and - immediately return.</para> - - <para>If a command is run with timer options, transient timer unit - also be created with transient service unit. But the transient - timer unit is only started immediately. The transient service unit - will be started when the transient timer is elapsed. If - <option>--unit=</option> is specified with timer options, the - <replaceable>COMMAND</replaceable> can be omitted. In this case, - <command>systemd-run</command> assumes service unit is already - loaded and creates transient timer unit only. To successfully - create timer unit, already loaded service unit should be specified - with <option>--unit=</option>. This transient timer unit can - activate the existing service unit like any other timer.</para> + and detached execution environment, with the service manager as + its parent process. In this mode <command>systemd-run</command> + will start the service asynchronously in the background and return + after the command has begun execution.</para> <para>If a command is run as transient scope unit, it will be - started directly by <command>systemd-run</command> and thus - inherit the execution environment of the caller. It is however - managed by the service manager similar to normal services, and - will also show up in the output of <command>systemctl - list-units</command>. Execution in this case is synchronous, and - execution will return only when the command finishes.</para> + started by <command>systemd-run</command> itself as parent process + and will thus inherit the execution environment of the + caller. However, the processes of the command are managed by the + service manager similar to normal services, and will show up in + the output of <command>systemctl list-units</command>. Execution + in this case is synchronous, and will return only when the command + finishes. This mode is enabled via the <option>--scope</option> + switch (see below). </para> + + <para>If a command is run with timer options such as + <option>--on-calendar=</option> (see below), a transient timer + unit is created alongside the service unit for the specified + command. Only the transient timer unit is started immediately, the + transient service unit will be started when the transient timer + elapses. If the <option>--unit=</option> is specified, the + <replaceable>COMMAND</replaceable> may be omitted. In this case, + <command>systemd-run</command> only creates a + <filename>.timer</filename> unit that invokes the specified unit + when elapsing.</para> </refsect1> <refsect1> @@ -110,6 +113,13 @@ <variablelist> <varlistentry> + <term><option>--no-ask-password</option></term> + + <listitem><para>Do not query the user for authentication for + privileged operations.</para></listitem> + </varlistentry> + + <varlistentry> <term><option>--scope</option></term> <listitem> @@ -371,7 +381,7 @@ Dec 08 20:44:48 container systemd[1]: Started /bin/touch /tmp/foo.</programlisti as a service passing its standard input, output and error to the calling TTY.</para> - <programlisting># systemd-run -t /bin/bash</programlisting> + <programlisting># systemd-run -t --send-sighup /bin/bash</programlisting> </refsect1> diff --git a/man/systemd-system.conf.xml b/man/systemd-system.conf.xml index c06accd791..56db9ff17e 100644 --- a/man/systemd-system.conf.xml +++ b/man/systemd-system.conf.xml @@ -51,14 +51,14 @@ </refnamediv> <refsynopsisdiv> - <para><filename>/etc/systemd/system.conf</filename></para> - <para><filename>/etc/systemd/system.conf.d/*.conf</filename></para> - <para><filename>/run/systemd/system.conf.d/*.conf</filename></para> - <para><filename>/usr/lib/systemd/system.conf.d/*.conf</filename></para> - <para><filename>/etc/systemd/user.conf</filename></para> - <para><filename>/etc/systemd/user.conf.d/*.conf</filename></para> - <para><filename>/run/systemd/user.conf.d/*.conf</filename></para> - <para><filename>/usr/lib/systemd/user.conf.d/*.conf</filename></para> + <para><filename>/etc/systemd/system.conf</filename>, + <filename>/etc/systemd/system.conf.d/*.conf</filename>, + <filename>/run/systemd/system.conf.d/*.conf</filename>, + <filename>/usr/lib/systemd/system.conf.d/*.conf</filename></para> + <para><filename>/etc/systemd/user.conf</filename>, + <filename>/etc/systemd/user.conf.d/*.conf</filename>, + <filename>/run/systemd/user.conf.d/*.conf</filename>, + <filename>/usr/lib/systemd/user.conf.d/*.conf</filename></para> </refsynopsisdiv> <refsect1> @@ -90,9 +90,10 @@ <term><varname>LogColor=</varname></term> <term><varname>LogLocation=</varname></term> <term><varname>DumpCore=yes</varname></term> + <term><varname>CrashChangeVT=no</varname></term> <term><varname>CrashShell=no</varname></term> + <term><varname>CrashReboot=no</varname></term> <term><varname>ShowStatus=yes</varname></term> - <term><varname>CrashChVT=1</varname></term> <term><varname>DefaultStandardOutput=journal</varname></term> <term><varname>DefaultStandardError=inherit</varname></term> @@ -305,12 +306,14 @@ <term><varname>DefaultCPUAccounting=</varname></term> <term><varname>DefaultBlockIOAccounting=</varname></term> <term><varname>DefaultMemoryAccounting=</varname></term> + <term><varname>DefaultTasksAccounting=</varname></term> <listitem><para>Configure the default resource accounting settings, as configured per-unit by <varname>CPUAccounting=</varname>, - <varname>BlockIOAccounting=</varname> and - <varname>MemoryAccounting=</varname>. See + <varname>BlockIOAccounting=</varname>, + <varname>MemoryAccounting=</varname> and + <varname>TasksAccounting=</varname>. See <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details on the per-unit settings.</para></listitem> </varlistentry> diff --git a/man/systemd-timesyncd.service.xml b/man/systemd-timesyncd.service.xml index ac1af2d136..01ed0b8149 100644 --- a/man/systemd-timesyncd.service.xml +++ b/man/systemd-timesyncd.service.xml @@ -71,6 +71,10 @@ files, and the per-link dynamic settings received over DHCP. See <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more details.</para> + + <para><citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s + <command>set-ntp</command> command may be used to enable and + start, or disable and stop this service.</para> </refsect1> <refsect1> diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index 45a4422dc3..d3f56fee40 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -1,3 +1,4 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -83,22 +84,27 @@ <varlistentry> <term><varname>WorkingDirectory=</varname></term> - <listitem><para>Takes an absolute directory path. Sets the - working directory for executed processes. If not set, defaults - to the root directory when systemd is running as a system - instance and the respective user's home directory if run as - user.</para></listitem> + <listitem><para>Takes an absolute directory path, or the + special value <literal>~</literal>. Sets the working directory + for executed processes. If set to <literal>~</literal> the + home directory of the user specified in + <varname>User=</varname> is used. If not set, defaults to the + root directory when systemd is running as a system instance + and the respective user's home directory if run as user. If + the setting is prefixed with the <literal>-</literal> + character, a missing working directory is not considered + fatal.</para></listitem> </varlistentry> <varlistentry> <term><varname>RootDirectory=</varname></term> <listitem><para>Takes an absolute directory path. Sets the - root directory for executed processes, with the - <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry> + root directory for executed processes, with the <citerefentry + project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call. If this is used, it must be ensured that the - process and all its auxiliary files are available in the - <function>chroot()</function> jail.</para></listitem> + process binary and all its auxiliary files are available in + the <function>chroot()</function> jail.</para></listitem> </varlistentry> <varlistentry> @@ -263,7 +269,8 @@ <listitem><para>Similar to <varname>Environment=</varname> but reads the environment variables from a text file. The text file should contain new-line-separated variable assignments. - Empty lines and lines starting with ; or # will be ignored, + Empty lines, lines without an <literal>=</literal> separator, + or lines starting with ; or # will be ignored, which may be used for commenting. A line ending with a backslash will be concatenated with the following one, allowing multiline variable definitions. The parser strips @@ -910,10 +917,16 @@ <term><varname>UtmpIdentifier=</varname></term> <listitem><para>Takes a four character identifier string for - an utmp/wtmp entry for this service. This should only be set - for services such as <command>getty</command> implementations + an <citerefentry + project='man-pages'><refentrytitle>utmp</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and wtmp entry for this service. This should only be + set for services such as <command>getty</command> + implementations (such as <citerefentry + project='die-net'><refentrytitle>agetty</refentrytitle><manvolnum>8</manvolnum></citerefentry>) where utmp/wtmp entries must be created and cleared before and - after execution. If the configured string is longer than four + after execution, or for services that shall be executed as if + they were run by a <command>getty</command> process (see + below). If the configured string is longer than four characters, it is truncated and the terminal four characters are used. This setting interprets %I style string replacements. This setting is unset by default, i.e. no @@ -922,6 +935,34 @@ </varlistentry> <varlistentry> + <term><varname>UtmpMode=</varname></term> + + <listitem><para>Takes one of <literal>init</literal>, + <literal>login</literal> or <literal>user</literal>. If + <varname>UtmpIdentifier=</varname> is set, controls which + type of <citerefentry + project='man-pages'><refentrytitle>utmp</refentrytitle><manvolnum>5</manvolnum></citerefentry>/wtmp + entries for this service are generated. This setting has no + effect unless <varname>UtmpIdentifier=</varname> is set + too. If <literal>init</literal> is set, only an + <constant>INIT_PROCESS</constant> entry is generated and the + invoked process must implement a + <command>getty</command>-compatible utmp/wtmp logic. If + <literal>login</literal> is set, first an + <constant>INIT_PROCESS</constant> entry, followed by an + <constant>LOGIN_PROCESS</constant> entry is generated. In + this case the invoked process must implement a <citerefentry + project='die-net'><refentrytitle>login</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible + utmp/wtmp logic. If <literal>user</literal> is set, first an + <constant>INIT_PROCESS</constant> entry, then a + <constant>LOGIN_PROCESS</constant> entry and finally an + <constant>USER_PROCESS</constant> entry is generated. In this + case the invoked process may be any process that is suitable + to be run as session leader. Defaults to + <literal>init</literal>.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>SELinuxContext=</varname></term> <listitem><para>Set the SELinux security context of the diff --git a/man/systemd.generator.xml b/man/systemd.generator.xml index 2285e91812..4514c1afdf 100644 --- a/man/systemd.generator.xml +++ b/man/systemd.generator.xml @@ -331,7 +331,6 @@ find $dir</programlisting> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-debug-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-efi-boot-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-getty-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, diff --git a/man/systemd.journal-fields.xml b/man/systemd.journal-fields.xml index 49f44d2922..494f97aad1 100644 --- a/man/systemd.journal-fields.xml +++ b/man/systemd.journal-fields.xml @@ -258,6 +258,16 @@ <variablelist> <varlistentry> <term> + <option>audit</option> + </term> + <listitem> + <para>for those read from the kernel audit subsystem + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> <option>driver</option> </term> <listitem> diff --git a/man/systemd.link.xml b/man/systemd.link.xml index b630ef7a17..7745260a39 100644 --- a/man/systemd.link.xml +++ b/man/systemd.link.xml @@ -233,6 +233,12 @@ <literal>locally administered</literal> bits set.</para> </listitem> </varlistentry> + <varlistentry> + <term><literal>none</literal></term> + <listitem> + <para>Keeps the MAC address assigned by the kernel.</para> + </listitem> + </varlistentry> </variablelist> </listitem> </varlistentry> @@ -383,7 +389,7 @@ <refsect1> <title>Example</title> <example> - <title>/etc/systemd/network/wireless.link</title> + <title>/etc/systemd/network/25-wireless.link</title> <programlisting>[Match] MACAddress=12:34:56:78:9a:bc diff --git a/man/systemd.netdev.xml b/man/systemd.netdev.xml index 298cf0eb84..70311ca9d9 100644 --- a/man/systemd.netdev.xml +++ b/man/systemd.netdev.xml @@ -135,6 +135,9 @@ <row><entry><varname>macvlan</varname></entry> <entry>A macvlan device is a stacked device which receives packets from its underlying device based on MAC address filtering.</entry></row> + <row><entry><varname>macvtap</varname></entry> + <entry>A macvtap device is a stacked device which receives packets from its underlying device based on MAC address filtering.</entry></row> + <row><entry><varname>sit</varname></entry> <entry>An IPv6 over IPv4 tunnel.</entry></row> @@ -274,6 +277,43 @@ </variablelist> </refsect1> + <refsect1> + <title>[Bridge] Section Options</title> + + <para>The <literal>[Bridge]</literal> section only applies for + netdevs of kind <literal>bridge</literal>, and accepts the + following key:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>HelloTimeSec=</varname></term> + <listitem> + <para>HelloTimeSec specifies the number of seconds a hello packet is + sent out by the root bridge and the designated bridges. Hello packets are + used to communicate information about the topology throughout the entire + bridged local area network.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MaxAgeSec=</varname></term> + <listitem> + <para>MaxAgeSec specifies the number of seconds of maximum message age. + If the last seen (received) hello packet is more than this number of + seconds old, the bridge in question will start the takeover procedure + in attempt to become the Root Bridge itself.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>ForwardDelaySec=</varname></term> + <listitem> + <para>ForwardDelaySec specifies the number of seconds spent in each + of the Listening and Learning states before the Forwarding state is entered.</para> + </listitem> + </varlistentry> + </variablelist> + + </refsect1> + <refsect1> <title>[VLAN] Section Options</title> @@ -316,6 +356,15 @@ </refsect1> + <refsect1> + <title>[MACVTAP] Section Options</title> + + <para>The <literal>[MACVTAP]</literal> section applies for + netdevs of kind <literal>macvtap</literal> and accepts the + same key as <literal>[MACVLAN].</literal> </para> + + </refsect1> + <refsect1> <title>[IPVLAN] Section Options</title> @@ -429,6 +478,15 @@ <para>A boolean. When true receiving zero checksums in VXLAN/IPv6 is turned on.</para> </listitem> </varlistentry> + <varlistentry> + <term><varname>GroupPolicyExtension=</varname></term> + <listitem> + <para>A boolean. When true it enables Group Policy VXLAN extension security label mechanism + across network peers based on VXLAN. For details about the Group Policy VXLAN see the + <ulink url="https://tools.ietf.org/html/draft-smith-vxlan-group-policy"> + VXLAN Group Policy </ulink> document. Defaults to false.</para> + </listitem> + </varlistentry> </variablelist> </refsect1> <refsect1> @@ -514,6 +572,19 @@ </listitem> </varlistentry> <varlistentry> + <term><varname>EncapsulationLimit=</varname></term> + <listitem> + <para>The Tunnel Encapsulation Limit option specifies how many additional + levels of encapsulation are permitted to be prepended to the packet. + For example, a Tunnel Encapsulation Limit option containing a limit + value of zero means that a packet carrying that option may not enter + another tunnel before exiting the current tunnel. + (see <ulink url="https://tools.ietf.org/html/rfc2473#section-4.1.1"> RFC 2473</ulink>). + The valid range is 0-255 and <literal>none</literal>. Defaults to 4. + </para> + </listitem> + </varlistentry> + <varlistentry> <term><varname>Mode=</varname></term> <listitem> <para>An <literal>ip6tnl</literal> tunnels can have three @@ -875,7 +946,7 @@ <refsect1> <title>Example</title> <example> - <title>/etc/systemd/network/bridge.netdev</title> + <title>/etc/systemd/network/25-bridge.netdev</title> <programlisting>[NetDev] Name=bridge0 @@ -883,7 +954,7 @@ Kind=bridge</programlisting> </example> <example> - <title>/etc/systemd/network/vlan1.netdev</title> + <title>/etc/systemd/network/25-vlan1.netdev</title> <programlisting>[Match] Virtualization=no @@ -896,7 +967,7 @@ Kind=vlan Id=1</programlisting> </example> <example> - <title>/etc/systemd/network/ipip.netdev</title> + <title>/etc/systemd/network/25-ipip.netdev</title> <programlisting>[NetDev] Name=ipip-tun Kind=ipip @@ -908,7 +979,7 @@ Remote=192.169.224.239 TTL=64</programlisting> </example> <example> - <title>/etc/systemd/network/tap.netdev</title> + <title>/etc/systemd/network/25-tap.netdev</title> <programlisting>[NetDev] Name=tap-test Kind=tap @@ -918,7 +989,7 @@ MultiQueue=true PacketInfo=true</programlisting> </example> <example> - <title>/etc/systemd/network/sit.netdev</title> + <title>/etc/systemd/network/25-sit.netdev</title> <programlisting>[NetDev] Name=sit-tun Kind=sit @@ -930,7 +1001,7 @@ Remote=10.65.223.239</programlisting> </example> <example> - <title>/etc/systemd/network/gre.netdev</title> + <title>/etc/systemd/network/25-gre.netdev</title> <programlisting>[NetDev] Name=gre-tun Kind=gre @@ -942,7 +1013,7 @@ Remote=10.65.223.239</programlisting> </example> <example> - <title>/etc/systemd/network/vti.netdev</title> + <title>/etc/systemd/network/25-vti.netdev</title> <programlisting>[NetDev] Name=vti-tun @@ -955,7 +1026,7 @@ Remote=10.65.223.239</programlisting> </example> <example> - <title>/etc/systemd/network/veth.netdev</title> + <title>/etc/systemd/network/25-veth.netdev</title> <programlisting>[NetDev] Name=veth-test Kind=veth @@ -965,7 +1036,21 @@ Name=veth-peer</programlisting> </example> <example> - <title>/etc/systemd/network/dummy.netdev</title> + <title>/etc/systemd/network/25-bond.netdev</title> + <programlisting>[NetDev] +Name=bond1 +Kind=bond + +[Bond] +Mode=802.3ad +TransmitHashPolicy=layer3+4 +MIIMonitorSec=1s +LACPTransmitRate=fast +</programlisting> + </example> + + <example> + <title>/etc/systemd/network/25-dummy.netdev</title> <programlisting>[NetDev] Name=dummy-test Kind=dummy diff --git a/man/systemd.network.xml b/man/systemd.network.xml index e44491cc2e..1a33b77002 100644 --- a/man/systemd.network.xml +++ b/man/systemd.network.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -223,7 +223,7 @@ <varlistentry> <term><varname>DHCP=</varname></term> <listitem> - <para>Enables DHCPv4 and/or DHCPv6 support. Accepts + <para>Enables DHCPv4 and/or DHCPv6 client support. Accepts <literal>yes</literal>, <literal>no</literal>, <literal>ipv4</literal>, or <literal>ipv6</literal>.</para> @@ -235,9 +235,10 @@ <varlistentry> <term><varname>DHCPServer=</varname></term> <listitem> - <para>A boolean. Enables a basic DHCPv4 server on the - device. Mostly useful for handing out leases to container - instances.</para> + <para>A boolean. Enables DHCPv4 server support. Defaults + to <literal>no</literal>. Further settings for the DHCP + server may be set in the <literal>[DHCPServer]</literal> + section described below.</para> </listitem> </varlistentry> <varlistentry> @@ -407,6 +408,24 @@ <literal>no</literal>.</para></listitem> </varlistentry> <varlistentry> + <term><varname>IPv6AcceptRouterAdvertisements=</varname></term> + <listitem><para>Force the setting of <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. + 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> + </listitem> + </varlistentry> + <varlistentry> <term><varname>Bridge=</varname></term> <listitem> <para>The name of the bridge to add the link to.</para> @@ -536,12 +555,22 @@ <literal>global</literal>.</para> </listitem> </varlistentry> + <varlistentry> + <term><varname>PreferredSource=</varname></term> + <listitem> + <para>The preferred source address of the route. The address + must be in the format described in + <citerefentry project='man-pages'><refentrytitle>inet_pton</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> </variablelist> </refsect1> <refsect1> <title>[DHCP] Section Options</title> - <para>The <literal>[DHCP]</literal> section accepts the following keys:</para> + <para>The <literal>[DHCP]</literal> section configures the + DHCPv4 and DHCP6 client, if it is enabled with the + <varname>DHCP=</varname> setting described above:</para> <variablelist class='network-directives'> <varlistentry> @@ -552,7 +581,8 @@ any statically configured ones.</para> <para>This corresponds to the <option>nameserver</option> - option in <citerefentry project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + option in <citerefentry + project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> </listitem> </varlistentry> <varlistentry> @@ -582,7 +612,7 @@ <term><varname>UseHostname=</varname></term> <listitem> <para>When true (the default), the hostname received from - the DHCP server will be used as the transient hostname. + the DHCP server will be set as the transient hostname of the system </para> </listitem> </varlistentry> @@ -615,6 +645,15 @@ table with metric of 1024.</para> </listitem> </varlistentry> + + <varlistentry> + <term><varname>UseTimezone=</varname></term> + + <listitem><para>When true, the timezone received from the + DHCP server will be set as as timezone of the local + system. Defaults to <literal>no</literal>.</para></listitem> + </varlistentry> + <varlistentry> <term><varname>CriticalConnection=</varname></term> <listitem> @@ -658,11 +697,114 @@ DHCP server.</para> </listitem> </varlistentry> - </variablelist> + </variablelist> </refsect1> <refsect1> + <title>[DHCPServer] Section Options</title> + <para>The <literal>[DHCPServer]</literal> section contains + settings for the DHCP server, if enabled via the + <varname>DHCPServer=</varname> option described above:</para> + + <variablelist class='network-directives'> + + <varlistentry> + <term><varname>PoolOffset=</varname></term> + <term><varname>PoolSize=</varname></term> + + <listitem><para>Configures the pool of addresses to hand out. The pool + is a contiguous sequence of IP addresses in the subnet configured for + the server address, which does not include the subnet nor the broadcast + address. <varname>PoolOffset=</varname> takes the offset of the pool + from the start of subnet, or zero to use the default value. + <varname>PoolSize=</varname> takes the number of IP addresses in the + pool or zero to use the default value. By default the pool starts at + the first address after the subnet address and takes up the rest of + the subnet, excluding the broadcast address. If the pool includes + the server address (the default), this is reserved and not handed + out to clients.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultLeaseTimeSec=</varname></term> + <term><varname>MaxLeaseTimeSec=</varname></term> + + <listitem><para>Control the default and maximum DHCP lease + time to pass to clients. These settings take time values in seconds or + another common time unit, depending on the suffix. The default + lease time is used for clients that did not ask for a specific + lease time. If a client asks for a lease time longer than the + maximum lease time it is automatically shortened to the + specified time. The default lease time defaults to 1h, the + maximum lease time to 12h. Shorter lease times are beneficial + if the configuration data in DHCP leases changes frequently + and clients shall learn the new settings with shorter + latencies. Longer lease times reduce the generated DHCP + network traffic.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>EmitDNS=</varname></term> + <term><varname>DNS=</varname></term> + + <listitem><para>Configures whether the DHCP leases handed out + to clients shall contain DNS server information. The + <varname>EmitDNS=</varname> setting takes a boolean argument + and defaults to <literal>yes</literal>. The DNS servers to + pass to clients may be configured with the + <varname>DNS=</varname> option, which takes a list of IPv4 + addresses. If the <varname>EmitDNS=</varname> option is + enabled but no servers configured the servers are + automatically propagated from an "uplink" interface that has + appropriate servers set. The "uplink" interface is determined + by the default route of the system with the highest + priority. Note that this information is acquired at the time + the lease is handed out, and does not take uplink interfaces + into account that acquire DNS or NTP server information at a + later point. DNS server propagation does not take + <filename>/etc/resolv.conf</filename> into account. Also, note + that the leases are not refreshed if uplink network + configuration changes. To ensure clients regularly acquire the + most current uplink DNS server information it is thus + advisable to shorten the DHCP lease time via + <varname>MaxLeaseTimeSec=</varname> described + above.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>EmitNTP=</varname></term> + <term><varname>NTP=</varname></term> + + <listitem><para>Similar to the <varname>EmitDNS=</varname> and + <varname>DNS=</varname> settings described above these + settings configure whether and what NTP server information + shall be emitted as part of the DHCP lease. The same syntax, + propagation semantics and defaults apply as for + <varname>EmitDNS=</varname> and + <varname>DNS=</varname>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>EmitTimezone=</varname></term> + <term><varname>Timezone=</varname></term> + + <listitem><para>Configures whether the DHCP leases handed out + to clients shall contain timezone information. The + <varname>EmitTimezone=</varname> setting takes a boolean + argument and defaults to <literal>yes</literal>. The + <varname>Timezone=</varname> setting takes a timezone string + (such as <literal>Europe/Berlin</literal> or + <literal>UTC</literal>) to pass to clients. If no explicit + timezone is set the system timezone of the local host is + propagated, as determined by the + <filename>/etc/localtime</filename> symlink.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> <title>[Bridge] Section Options</title> <para>The <literal>[Bridge]</literal> section accepts the following keys.</para> @@ -769,7 +911,7 @@ DHCP=yes</programlisting> </example> <example> - <title>/etc/systemd/network/bridge-static.network</title> + <title>/etc/systemd/network/25-bridge-static.network</title> <programlisting>[Match] Name=bridge0 @@ -781,7 +923,7 @@ DNS=192.168.0.1</programlisting> </example> <example> - <title>/etc/systemd/network/bridge-slave-interface.network</title> + <title>/etc/systemd/network/25-bridge-slave-interface.network</title> <programlisting>[Match] Name=enp2s0 @@ -790,7 +932,7 @@ Name=enp2s0 Bridge=bridge0</programlisting> </example> <example> - <title>/etc/systemd/network/ipip.network</title> + <title>/etc/systemd/network/25-ipip.network</title> <programlisting>[Match] Name=em1 @@ -800,7 +942,7 @@ Tunnel=ipip-tun</programlisting> </example> <example> - <title>/etc/systemd/network/sit.network</title> + <title>/etc/systemd/network/25-sit.network</title> <programlisting>[Match] Name=em1 @@ -810,7 +952,7 @@ Tunnel=sit-tun</programlisting> </example> <example> - <title>/etc/systemd/network/gre.network</title> + <title>/etc/systemd/network/25-gre.network</title> <programlisting>[Match] Name=em1 @@ -820,7 +962,7 @@ Tunnel=gre-tun</programlisting> </example> <example> - <title>/etc/systemd/network/vti.network</title> + <title>/etc/systemd/network/25-vti.network</title> <programlisting>[Match] Name=em1 @@ -828,6 +970,18 @@ Name=em1 [Network] Tunnel=vti-tun</programlisting> </example> + + <example> + <title>/etc/systemd/network/25-bond.network</title> + + <programlisting>[Match] +Name=bond1 + +[Network] +DHCP=yes +</programlisting> + </example> + </refsect1> <refsect1> diff --git a/man/systemd.nspawn.xml b/man/systemd.nspawn.xml new file mode 100644 index 0000000000..7bfafb424f --- /dev/null +++ b/man/systemd.nspawn.xml @@ -0,0 +1,383 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ +<!ENTITY % entities SYSTEM "custom-entities.ent" > +%entities; +]> + +<!-- + This file is part of systemd. + + Copyright 2015 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.nspawn"> + + <refentryinfo> + <title>systemd.nspawn</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.nspawn</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.nspawn</refname> + <refpurpose>Container settings</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/systemd/nspawn/<replaceable>machine</replaceable>.nspawn</filename></para> + <para><filename>/run/systemd/nspawn/<replaceable>machine</replaceable>.nspawn</filename></para> + <para><filename>/var/lib/machines/<replaceable>machine</replaceable>.nspawn</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>An nspawn container settings file (suffix + <filename>.nspawn</filename>) encodes additional runtime + information about a local container, and is searched, read and + used by + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + when starting a container. Files of this type are named after the + containers they define settings for. They are optional, and only + required for containers whose execution environment shall differ + from the defaults. Files of this type mostly contain settings that + may also be set on the <command>systemd-nspawn</command> command + line, and make it easier to persistently attach specific settings + to specific containers. The syntax of these files is inspired by + <filename>.desktop</filename> files following the <ulink + url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG + Desktop Entry Specification</ulink>, which are in turn inspired by + Microsoft Windows <filename>.ini</filename> files.</para> + + <para>Boolean arguments used in these settings files can be + written in various formats. For positive settings the strings + <option>1</option>, <option>yes</option>, <option>true</option> + and <option>on</option> are equivalent. For negative settings, the + strings <option>0</option>, <option>no</option>, + <option>false</option> and <option>off</option> are + equivalent.</para> + + <para>Empty lines and lines starting with # or ; are + ignored. This may be used for commenting. Lines ending + in a backslash are concatenated with the following + line while reading and the backslash is replaced by a + space character. This may be used to wrap long lines.</para> + + </refsect1> + + <refsect1> + <title><filename>.nspawn</filename> File Discovery</title> + + <para>Files are searched by appending the + <filename>.nspawn</filename> suffix to the machine name of the + container, as specified with the <option>--machine=</option> + switch of <command>systemd-nspawn</command>, or derived from the + directory or image file name. This file is first searched in + <filename>/etc/systemd/nspawn/</filename> and + <filename>/run/systemd/nspawn/</filename>. If found in these + directories its settings are read and all of them take full effect + (but are possibly overridden by corresponding command line + arguments). If not found the file will then be searched next to + the image file or in the immediate parent of the root directory of + the container. If the file is found there only a subset of the + settings will take effect however. All settings that possibly + elevate privileges or grant additional access to resources of the + host (such as files or directories) are ignored. To which options + this applies is documented below.</para> + + <para>Persistent settings file created and maintained by the + administrator (and thus trusted) should be placed in + <filename>/etc/systemd/nspawn/</filename>, while automatically + downloaded (and thus potentially untrusted) settings files are + placed in <filename>/var/lib/machines/</filename> instead (next to + the container images), where their security impact is limited. In + order to add privileged settings to <filename>.nspawn</filename> + files acquired from the image vendor it is recommended to copy the + settings files into <filename>/etc/systemd/nspawn/</filename> and + edit them there, so that the privileged options become + available. The precise algorithm how the files are searched and + interpreted may be configured with + <command>systemd-nspawn</command>'s <option>--settings=</option> + switch, see + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for details.</para> + </refsect1> + + <refsect1> + <title>[Exec] Section Options</title> + + <para>Settings files may include an <literal>[Exec]</literal> + section, which carries various execution parameters:</para> + + <variablelist> + + <varlistentry> + <term><varname>Boot=</varname></term> + + <listitem><para>Takes a boolean argument, defaults to off. If + enabled <command>systemd-nspawn</command> will automatically + search for an <filename>init</filename> executable and invoke + it. In this case the specified parameters using + <varname>Parameters=</varname> are passed as additional + arguments to the <filename>init</filename> process. This + setting corresponds to the <option>--boot</option> switch on + the <command>systemd-nspawn</command> command + line. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Parameters=</varname></term> + + <listitem><para>Takes a space separated list of + arguments. This is either a command line, beginning with the + binary name to execute, or – if <varname>Boot=</varname> is + enabled – the list of arguments to pass to the init + process. This setting corresponds to the command line + parameters passed on the <command>systemd-nspawn</command> + command line.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Environment=</varname></term> + + <listitem><para>Takes an environment variable assignment + consisting of key and value, separated by + <literal>=</literal>. Sets an environment variable for the + main process invoked in the container. This setting may be + used multiple times to set multiple environment variables. It + corresponds to the <option>--setenv=</option> command line + switch.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>User=</varname></term> + + <listitem><para>Takes a UNIX user name. Specifies the user + name to invoke the main process of the container as. This user + must be known in the container's user database. This + corresponds to the <option>--user=</option> command line + switch.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Capability=</varname></term> + <term><varname>DropCapability=</varname></term> + + <listitem><para>Takes a space separated list of Linux process + capabilities (see + <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details). The <varname>Capability=</varname> setting + specifies additional capabilities to pass on top of the + default set of capabilities. The + <varname>DropCapability=</varname> setting specifies + capabilities to drop from the default set. These settings + correspond to the <option>--capability=</option> and + <option>--drop-capability=</option> command line + switches. Note that <varname>Capability=</varname> is a + privileged setting, and only takes effect in + <filename>.nspawn</filename> files in + <filename>/etc/systemd/nspawn/</filename> and + <filename>/run/system/nspawn/</filename> (see above). On the + other hand <varname>DropCapability=</varname> takes effect in + all cases.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Personality=</varname></term> + + <listitem><para>Configures the kernel personality for the + container. This is equivalent to the + <option>--personality=</option> switch.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>MachineID=</varname></term> + + <listitem><para>Configures the 128bit machine ID (UUID) to pass to + the container. This is equivalent to the + <option>--uuid=</option> command line switch. This option is + privileged (see above). </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>[Files] Section Options</title> + + <para>Settings files may include a <literal>[Files]</literal> + section, which carries various parameters configuring the file + system of the container:</para> + + <variablelist> + + <varlistentry> + <term><varname>ReadOnly=</varname></term> + + <listitem><para>Takes a boolean argument, defaults to off. If + specified the container will be run with a read-only file + system. This setting corresponds to the + <option>--read-only</option> command line + switch.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Volatile=</varname></term> + + <listitem><para>Takes a boolean argument, or the special value + <literal>state</literal>. This configures whether to run the + container with volatile state and/or configuration. This + option is equivalent to <option>--volatile=</option>, see + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for details about the specific options + supported.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Bind=</varname></term> + <term><varname>BindReadOnly=</varname></term> + + <listitem><para>Adds a bind mount from the host into the + container. Takes a single path, a pair of two paths separated + by a colon, or a triplet of two paths plus an option string + separated by colons. This option may be used multiple times to + configure multiple bind mounts. This option is equivalent to + the command line switches <option>--bind=</option> and + <option>--bind-ro=</option>, see + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for details about the specific options supported. This setting + is privileged (see above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TemporaryFileSystem=</varname></term> + + <listitem><para>Adds a <literal>tmpfs</literal> mount to the + container. Takes a path or a pair of path and option string, + separated by a colon. This option may be used multiple times to + configure multiple <literal>tmpfs</literal> mounts. This + option is equivalent to the command line switch + <option>--tmpfs=</option>, see + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for details about the specific options supported. This setting + is privileged (see above).</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>[Network] Section Options</title> + + <para>Settings files may include a <literal>[Network]</literal> + section, which carries various parameters configuring the network + connectivity of the container:</para> + + <variablelist> + + <varlistentry> + <term><varname>Private=</varname></term> + + <listitem><para>Takes a boolean argument, defaults to off. If + enabled the container will run in its own network namespace + and not share network interfaces and configuration with the + host. This setting corresponds to the + <option>--private-network</option> command line + switch.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>VirtualEthernet=</varname></term> + + <listitem><para>Takes a boolean argument. Configures whether + to create a virtual ethernet connection + (<literal>veth</literal>) between host and the container. This + setting implies <varname>Private=yes</varname>. This setting + corresponds to the <option>--network-veth</option> command + line switch. This option is privileged (see + above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Interface=</varname></term> + + <listitem><para>Takes a space separated list of interfaces to + add to the container. This option corresponds to the + <option>--network-interface=</option> command line switch and + implies <varname>Private=yes</varname>. This option is + privileged (see above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>MACVLAN=</varname></term> + <term><varname>IPVLAN=</varname></term> + + <listitem><para>Takes a space separated list of interfaces to + add MACLVAN or IPVLAN interfaces to, which are then added to + the container. These options correspond to the + <option>--network-macvlan=</option> and + <option>--network-ipvlan=</option> command line switches and + imply <varname>Private=yes</varname>. These options are + privileged (see above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Bridge=</varname></term> + + <listitem><para>Takes an interface name. This setting implies + <varname>VirtualEthernet=yes</varname> and + <varname>Private=yes</varname> and has the effect that the + host side of the created virtual Ethernet link is connected to + the specified bridge interface. This option corresponds to the + <option>--network-bridge=</option> command line switch. This + option is privileged (see above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Port=</varname></term> + + <listitem><para>Exposes a TCP or UDP port of the container on + the host. This option corresponds to the + <option>--port=</option> command line switch, see + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for the precise syntax of the argument this option takes. This + option is privileged (see above).</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd.resource-control.xml b/man/systemd.resource-control.xml index 8f4e7a3f16..98f4d75ddb 100644 --- a/man/systemd.resource-control.xml +++ b/man/systemd.resource-control.xml @@ -103,10 +103,10 @@ <listitem> <para>Turn on CPU usage accounting for this unit. Takes a boolean argument. Note that turning on CPU accounting for - one unit might also implicitly turn it on for all units + one unit will also implicitly turn it on for all units contained in the same slice and for all its parent slices and the units contained therein. The system default for this - setting maybe controlled with + setting may be controlled with <varname>DefaultCPUAccounting=</varname> in <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> </listitem> @@ -118,10 +118,11 @@ <listitem> <para>Assign the specified CPU time share weight to the - processes executed. Those options take an integer value and + processes executed. These options take an integer value and control the <literal>cpu.shares</literal> control group - attribute, which defaults to 1024. For details about this - control group attribute, see <ulink + attribute. The allowed range is 2 to 262144. Defaults to + 1024. For details about this control group attribute, see + <ulink url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>. The available CPU time is split up among all units within one slice relative to their CPU time share weight.</para> @@ -134,7 +135,7 @@ prioritizing specific services at boot-up differently than during normal runtime.</para> - <para>Those options imply + <para>These options imply <literal>CPUAccounting=true</literal>.</para> </listitem> </varlistentry> @@ -168,9 +169,10 @@ <listitem> <para>Turn on process and kernel memory accounting for this unit. Takes a boolean argument. Note that turning on memory - accounting for one unit might also implicitly turn it on for - all its parent slices. The system default for this setting - maybe controlled with + accounting for one unit will also implicitly turn it on for + all units contained in the same slice and for all its parent + slices and the units contained therein. The system default + for this setting may be controlled with <varname>DefaultMemoryAccounting=</varname> in <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> </listitem> @@ -186,10 +188,11 @@ memory size in bytes. If the value is suffixed with K, M, G or T, the specified memory size is parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), - respectively. This controls the - <literal>memory.limit_in_bytes</literal> control group - attribute. For details about this control group attribute, - see <ulink + 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 url="https://www.kernel.org/doc/Documentation/cgroups/memory.txt">memory.txt</ulink>.</para> <para>Implies <literal>MemoryAccounting=true</literal>.</para> @@ -197,15 +200,52 @@ </varlistentry> <varlistentry> + <term><varname>TasksAccounting=</varname></term> + + <listitem> + <para>Turn on task accounting for this unit. Takes a + boolean argument. If enabled, the system manager will keep + track of the number of tasks in the unit. The number of + tasks accounted this way includes both kernel threads and + userspace processes, with each thread counting + individually. Note that turning on tasks accounting for one + unit will also implicitly turn it on for all units contained + in the same slice and for all its parent slices and the + units contained therein. The system default for this setting + may be controlled with + <varname>DefaultTasksAccounting=</varname> in + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>TasksMax=<replaceable>N</replaceable></varname></term> + + <listitem> + <para>Specify the maximum number of tasks that may be + created in the unit. This ensures that the number of tasks + accounted for the unit (see above) stays below a specific + limit. 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/cgroups/pids.txt">pids.txt</ulink>.</para> + + <para>Implies <literal>TasksAccounting=true</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> <term><varname>BlockIOAccounting=</varname></term> <listitem> <para>Turn on Block IO accounting for this unit. Takes a boolean argument. Note that turning on block IO accounting - for one unit might also implicitly turn it on for all units + for one unit will also implicitly turn it on for all units contained in the same slice and all for its parent slices and the units contained therein. The system default for this - setting maybe controlled with + setting may be controlled with <varname>DefaultBlockIOAccounting=</varname> in <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> </listitem> @@ -219,7 +259,7 @@ the executed processes. Takes a single weight value (between 10 and 1000) to set the default block IO weight. This controls the <literal>blkio.weight</literal> control group attribute, - which defaults to 1000. For details about this control group + which defaults to 500. For details about this control group attribute, see <ulink url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>. The available IO bandwidth is split up among all units within diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 4368ca8a19..8afdbc513b 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -287,7 +287,7 @@ below (see section "Command Lines" below). </para> - <para>When <varname>Type</varname> is not + <para>When <varname>Type=</varname> is not <option>oneshot</option>, only one command may and must be given. When <varname>Type=oneshot</varname> is used, zero or more commands may be specified. This can be specified by @@ -337,6 +337,19 @@ <literal>-</literal>) fail, the rest are not executed and the unit is considered failed.</para> + <para><varname>ExecStart=</varname> commands are only run after + all <varname>ExecStartPre=</varname> commands that were not prefixed + with a <literal>-</literal> exit successfully.</para> + + <para><varname>ExecStartPost=</varname> commands are only run after + the service has started, as determined by <varname>Type=</varname> + (i.e. The process has been started for <varname>Type=simple</varname> + or <varname>Type=idle</varname>, the process exits successfully for + <varname>Type=oneshot</varname>, the initial process exits successfully + for <varname>Type=forking</varname>, <literal>READY=1</literal> is sent + for <varname>Type=notify</varname>, or the <varname>BusName=</varname> + has been taken for <varname>Type=dbus</varname>).</para> + <para>Note that <varname>ExecStartPre=</varname> may not be used to start long-running processes. All processes forked off by processes invoked via <varname>ExecStartPre=</varname> will @@ -408,7 +421,7 @@ <varname>ExecStop=</varname> defined, or where the service exited unexpectedly. This argument takes multiple command lines, following the same scheme as described for - <varname>ExecStart</varname>. Use of these settings is + <varname>ExecStart=</varname>. Use of these settings is optional. Specifier and environment variable substitution is supported.</para></listitem> </varlistentry> @@ -473,7 +486,7 @@ "keep-alive ping"). If the time between two such calls is larger than the configured time, then the service is placed in a failed state and it will be terminated with - <varname>SIGABRT</varname>. By setting + <constant>SIGABRT</constant>. By setting <varname>Restart=</varname> to <option>on-failure</option> or <option>always</option>, the service will be automatically restarted. The time configured here will be passed to the @@ -890,6 +903,27 @@ and no job queued or being executed for it.</para></listitem> </varlistentry> + <varlistentry> + <term><varname>USBFunctionDescriptors=</varname></term> + <listitem><para>Configure the location of a file containing + <ulink + url="https://www.kernel.org/doc/Documentation/usb/functionfs.txt">USB + FunctionFS</ulink> descriptors, for implementation of USB + gadget functions. This is is used only in conjunction with a + socket unit with <varname>ListenUSBFunction=</varname> + configured. The contents of this file is written to the + <filename>ep0</filename> file after it is + opened.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>USBFunctionStrings=</varname></term> + <listitem><para>Configure the location of a file containing + USB FunctionFS strings. Behavior is similar to + <varname>USBFunctionDescriptors=</varname> + above.</para></listitem> + </varlistentry> + </variablelist> <para>Check @@ -922,7 +956,10 @@ the arguments. Double quotes ("...") and single quotes ('...') may be used, in which case everything until the next matching quote becomes part of the same argument. C-style escapes are also - supported, see table below. Quotes themselves are removed after + supported. The table below contains the list of allowed escape + patterns. Only patterns which match the syntax in the table are + allowed; others will result in an error, and must be escaped by + doubling the backslash. Quotes themselves are removed after parsing and escape sequences substituted. In addition, a trailing backslash (<literal>\</literal>) may be used to merge lines. </para> @@ -939,7 +976,7 @@ <literal>&</literal>, and <emphasis>other elements of shell syntax are not supported</emphasis>.</para> - <para>The command to execute must an absolute path name. It may + <para>The command to execute must be an absolute path name. It may contain spaces, but control characters are not allowed.</para> <para>The command line accepts <literal>%</literal> specifiers as @@ -956,7 +993,7 @@ <literal>$FOO</literal> as a separate word on the command line, in which case it will be replaced by the value of the environment variable split at whitespace resulting in zero or more arguments. - For this type of expansion, quotes and respected when splitting + For this type of expansion, quotes are respected when splitting into words, and afterwards removed.</para> <para>Example:</para> diff --git a/man/systemd.slice.xml b/man/systemd.slice.xml index a501327335..87c2a3bce3 100644 --- a/man/systemd.slice.xml +++ b/man/systemd.slice.xml @@ -93,6 +93,11 @@ <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> are allowed. </para> + <para>See the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/">New + Control Group Interfaces</ulink> for an introduction on how to make + use of slice units from programs.</para> + <para>Unless <varname>DefaultDependencies=false</varname> is used, slice units will implicitly have dependencies of type <varname>Conflicts=</varname> and diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml index 36fa3a86be..46a47b2d95 100644 --- a/man/systemd.socket.xml +++ b/man/systemd.socket.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -261,6 +261,22 @@ </varlistentry> <varlistentry> + <term><varname>ListenUSBFunction=</varname></term> + <listitem><para>Specifies a <ulink + url="https://www.kernel.org/doc/Documentation/usb/functionfs.txt">USB + FunctionFS</ulink> endpoint location to listen on, for + implementation of USB gadget functions. This expects an + absolute file system path as the argument. Behavior otherwise + is very similar to the <varname>ListenFIFO=</varname> + directive above. Use this to open FunctionFS endpoint + <filename>ep0</filename>. When using this option, the + activated service has to have the + <varname>USBFunctionDescriptors=</varname> and + <varname>USBFunctionStrings=</varname> options set. + </para></listitem> + </varlistentry> + + <varlistentry> <term><varname>BindIPv6Only=</varname></term> <listitem><para>Takes a one of <option>default</option>, <option>both</option> or <option>ipv6-only</option>. Controls @@ -366,6 +382,14 @@ </varlistentry> <varlistentry> + <term><varname>Writable=</varname></term> + <listitem><para>Takes a boolean argument. May only be used in + conjunction with <varname>ListenSpecial=</varname>. If true, + the specified special file is opened in read-write mode, if + false in read-only mode. Defaults to false.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>MaxConnections=</varname></term> <listitem><para>The maximum number of connections to simultaneously run services instances for, when @@ -724,6 +748,22 @@ list.</para></listitem> </varlistentry> + <varlistentry> + <term><varname>FileDescriptorName=</varname></term> + <listitem><para>Assigns a name to all file descriptors this + socket unit encapsulates. This is useful to help activated + services to identify specific file descriptors, if multiple + are passed. Services may use the + <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call to acquire the names configured for the received file + descriptors. Names may contain any ASCII character, but must + exclude control characters or <literal>:</literal>, and must + be at most 255 characters in length. If this setting is not + used the file descriptor name defaults to the name of the + socket unit, including its <filename>.socket</filename> + suffix.</para></listitem> + </varlistentry> + </variablelist> <para>Check @@ -744,9 +784,10 @@ <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> - <para> For more extensive descriptions see the "systemd for Developers" series: <ulink url="http://0pointer.de/blog/projects/socket-activation.html">Socket Activation</ulink>, diff --git a/man/systemd.special.xml b/man/systemd.special.xml index cf76aaf607..78bad4d814 100644 --- a/man/systemd.special.xml +++ b/man/systemd.special.xml @@ -130,9 +130,22 @@ for this target unit to all services (except for those with <varname>DefaultDependencies=no</varname>).</para> - <para>Usually this should pull-in all mount points, swap - devices, sockets, timers, and path units and other basic - initialization necessary for general purpose daemons.</para> + <para>Usually this should pull-in all local mount points plus + <filename>/var</filename>, <filename>/tmp</filename> and + <filename>/var/tmp</filename>, swap devices, sockets, timers, + path units and other basic initialization necessary for general + purpose daemons. The mentioned mount points are special cased + to allow them to be remote. + </para> + + <para>This target usually does not pull in any non-target units + directly, but rather does so indirectly via other early boot targets. + It is instead meant as a synchronization point for late boot + services. Refer to + <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details on the targets involved. + </para> + </listitem> </varlistentry> <varlistentry> @@ -199,6 +212,25 @@ </listitem> </varlistentry> <varlistentry> + <term><filename>exit.target</filename></term> + <listitem> + <para>A special service unit for shutting down the system or + user service manager. It is equivalent to + <filename>poweroff.target</filename> on non-container + systems, and also works in containers.</para> + + <para>systemd will start this unit when it receives a + request to shut down over D-Bus or a + <constant>SIGTERM</constant> or <constant>SIGINT</constant> + signal when running as user service daemon.</para> + + <para>Normally, this (indirectly) pulls in + <filename>shutdown.target</filename> which in turn should be + conflicted by all units that want to be scheduled for + shutdown when the service manager starts to exit.</para> + </listitem> + </varlistentry> + <varlistentry> <term><filename>final.target</filename></term> <listitem> <para>A special target unit that is used during the shutdown @@ -503,8 +535,14 @@ <varlistentry> <term><filename>sysinit.target</filename></term> <listitem> - <para>A special target unit covering early boot-up - scripts.</para> + <para>This target pulls in the services required for system + initialization. System services pulled in by this target should + declare <varname>DefaultDependencies=no</varname> and specify + all their dependencies manually, including access to anything + more than a read only root filesystem. For details on the + dependencies of this target, refer to + <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + </para> </listitem> </varlistentry> <varlistentry> @@ -778,6 +816,7 @@ <para>When systemd runs as a user instance, the following special units are available, which have similar definitions as their system counterparts: + <filename>exit.target</filename>, <filename>default.target</filename>, <filename>shutdown.target</filename>, <filename>sockets.target</filename>, @@ -787,30 +826,6 @@ <filename>printer.target</filename>, <filename>smartcard.target</filename>, <filename>sound.target</filename>.</para> - - <para>In addition, the following special unit is understood only - when systemd runs as service instance:</para> - - <variablelist> - <varlistentry> - <term><filename>exit.target</filename></term> - <listitem> - <para>A special service unit for shutting down the user - service manager.</para> - - <para>Applications wanting to terminate the user service - manager should start this unit. If systemd receives - <constant>SIGTERM</constant> or <constant>SIGINT</constant> - when running as user service daemon, it will start this - unit.</para> - - <para>Normally, this pulls in - <filename>shutdown.target</filename> which in turn should be - conflicted by all units that want to be shut down on user - service manager exit.</para> - </listitem> - </varlistentry> - </variablelist> </refsect1> <refsect1> @@ -833,7 +848,7 @@ <varlistentry> <term><filename>system.slice</filename></term> <listitem> - <para>By default, all services services started by + <para>By default, all system services started by <command>systemd</command> are found in this slice.</para> </listitem> </varlistentry> diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 0aa1eeac77..8985b6b940 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -256,7 +256,7 @@ </refsect1> <refsect1> - <title>Unit Load Path</title> + <title>Unit File Load Path</title> <para>Unit files are loaded from a set of paths determined during compilation, described in the two tables below. Unit files found @@ -737,7 +737,7 @@ to 0 (job timeouts disabled), except for device units. NB: this timeout is independent from any unit-specific timeout (for example, the timeout set with - <varname>StartTimeoutSec=</varname> in service units) as the + <varname>TimeoutStartSec=</varname> in service units) as the job timeout has no effect on the unit itself, only on the job that might be pending for it. Or in other words: unit-specific timeouts are useful to abort unit state changes, and revert @@ -1044,6 +1044,23 @@ files. This functionality should not be used in normal units.</para></listitem> </varlistentry> + + <varlistentry> + <term><varname>NetClass=</varname></term> + <listitem><para>Configures a network class number to assign to the + unit. This value will be set to the + <literal>net_cls.class_id</literal> property of the + <literal>net_cls</literal> cgroup of the unit. The directive + accepts a numerical value (for fixed number assignment) and the keyword + <literal>auto</literal> (for dynamic allocation). Network traffic of + all processes inside the unit will have the network class ID assigned + by the kernel. Also see + the kernel docs for + <ulink url="https://www.kernel.org/doc/Documentation/cgroups/net_cls.txt">net_cls controller</ulink> + and + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> </variablelist> </refsect1> diff --git a/man/systemd.xml b/man/systemd.xml index 4556d56969..8d74ca49c3 100644 --- a/man/systemd.xml +++ b/man/systemd.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -131,17 +131,48 @@ <varlistentry> <term><option>--dump-core</option></term> - <listitem><para>Dump core on crash. This switch has no effect - when run as user instance.</para></listitem> + <listitem><para>Enable core dumping on crash. This switch has + no effect when running as user instance. This setting may also + be enabled during boot on the kernel command line via the + <varname>systemd.dump_core=</varname> option, see + below.</para></listitem> </varlistentry> + + <varlistentry> + <term><option>--crash-vt=</option><replaceable>VT</replaceable></term> + + <listitem><para>Switch to a specific virtual console (VT) on + crash. Takes a positive integer in the range 1..63, or a + boolean argument. If an integer is passed, selects which VT to + switch to. If <constant>yes</constant>, the VT kernel messages + are written to is selected. If <constant>no</constant>, no VT + switch is attempted. This switch has no effect when running as + user instance. This setting may also be enabled during boot, + on the kernel command line via the + <varname>systemd.crash_vt=</varname> option, see + below.</para></listitem> + </varlistentry> + <varlistentry> <term><option>--crash-shell</option></term> - <listitem><para>Run shell on - crash. This switch has no effect when - run as user - instance.</para></listitem> + <listitem><para>Run a shell on crash. This switch has no + effect when running as user instance. This setting may also be + enabled during boot, on the kernel command line via the + <varname>systemd.crash_shell=</varname> option, see + below.</para></listitem> </varlistentry> + + <varlistentry> + <term><option>--crash-reboot</option></term> + + <listitem><para>Automatically reboot the system on crash. This + switch has no effect when running as user instance. This + setting may also be enabled during boot, on the kernel command + line via the <varname>systemd.crash_reboot=</varname> option, + see below.</para></listitem> + </varlistentry> + <varlistentry> <term><option>--confirm-spawn</option></term> @@ -367,6 +398,8 @@ group information is maintained in the kernel, and is accessible via the file system hierarchy (beneath <filename>/sys/fs/cgroup/systemd/</filename>), or in tools such as + <citerefentry project='man-pages'><refentrytitle>systemd-cgls</refentrytitle><manvolnum>1</manvolnum></citerefentry> + or <citerefentry project='man-pages'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry> (<command>ps xawf -eo pid,user,cgroup,args</command> is particularly useful to list all processes and the systemd units @@ -802,6 +835,7 @@ <varlistentry> <term><varname>$LISTEN_PID</varname></term> <term><varname>$LISTEN_FDS</varname></term> + <term><varname>$LISTEN_FDNAMES</varname></term> <listitem><para>Set by systemd for supervised processes during socket-based activation. See @@ -852,50 +886,66 @@ <term><varname>systemd.dump_core=</varname></term> <listitem><para>Takes a boolean argument. If - <option>true</option>, systemd dumps core when it crashes. - Otherwise, no core dump is created. Defaults to - <option>true</option>.</para></listitem> + <option>yes</option>, the systemd manager (PID 1) dumps core + when it crashes. Otherwise, no core dump is created. Defaults + to <option>yes</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.crash_chvt=</varname></term> + + <listitem><para>Takes a positive integer, or a boolean + argument. If a positive integer (in the range 1..63) is + specified the system manager (PID 1) will activate the specified + virtual terminal (VT) when it crashes. Defaults to + <constant>no</constant>, meaning that no such switch is + attempted. If set to <constant>yes</constant> the VT the + kernel messages are written to is selected.</para></listitem> </varlistentry> <varlistentry> <term><varname>systemd.crash_shell=</varname></term> <listitem><para>Takes a boolean argument. If - <option>true</option>, systemd spawns a shell when it crashes. - Otherwise, no shell is spawned. Defaults to - <option>false</option>, for security reasons, as the shell is - not protected by any password + <option>yes</option>, the system manager (PID 1) spawns a + shell when it crashes, after a 10s delay. Otherwise, no shell + is spawned. Defaults to <option>no</option>, for security + reasons, as the shell is not protected by password authentication.</para></listitem> </varlistentry> <varlistentry> - <term><varname>systemd.crash_chvt=</varname></term> + <term><varname>systemd.crash_reboot=</varname></term> - <listitem><para>Takes an integer argument. If positive systemd - activates the specified virtual terminal when it crashes. - Defaults to <constant>-1</constant>.</para></listitem> + <listitem><para>Takes a boolean argument. If + <option>yes</option>, the system manager (PID 1) will reboot + the machine automatically when it crashes, after a 10s delay. + Otherwise, the system will hang indefinitely. Defaults to + <option>no</option>, in order to avoid a reboot loop. If + combined with <varname>systemd.crash_shell=</varname>, the + system is rebooted after the shell exits.</para></listitem> </varlistentry> <varlistentry> <term><varname>systemd.confirm_spawn=</varname></term> <listitem><para>Takes a boolean argument. If - <option>true</option>, asks for confirmation when spawning - processes. Defaults to - <option>false</option>.</para></listitem> + <option>yes</option>, the system manager (PID 1) asks for + confirmation when spawning processes. Defaults to + <option>no</option>.</para></listitem> </varlistentry> <varlistentry> <term><varname>systemd.show_status=</varname></term> <listitem><para>Takes a boolean argument or the constant - <constant>auto</constant>. If <option>true</option>, shows - terse service status updates on the console during bootup. - <constant>auto</constant> behaves like <option>false</option> - until a service fails or there is a significant delay in boot. - Defaults to <option>true</option>, unless - <option>quiet</option> is passed as kernel command line option - in which case it defaults to + <constant>auto</constant>. If <option>yes</option>, the + systemd manager (PID 1) shows terse service status updates on + the console during bootup. <constant>auto</constant> behaves + like <option>false</option> until a service fails or there is + a significant delay in boot. Defaults to + <option>yes</option>, unless <option>quiet</option> is passed + as kernel command line option in which case it defaults to <constant>auto</constant>.</para></listitem> </varlistentry> diff --git a/man/timedatectl.xml b/man/timedatectl.xml index 2d42b41d5e..c439bc56ed 100644 --- a/man/timedatectl.xml +++ b/man/timedatectl.xml @@ -166,12 +166,27 @@ <term><command>set-ntp [BOOL]</command></term> <listitem><para>Takes a boolean argument. Controls whether - network time synchronization is enabled (if available). This - enables or disables the - <filename>systemd-timesyncd.service</filename> unit. Note that - even if this command turns time synchronization off a - different system service might still synchronize the clock - with the network.</para></listitem> + network time synchronization is active and enabled (if + available). This enables and starts, or disables and stops the + <filename>systemd-timesyncd.service</filename> unit. It does + not affect the state of any other, unrelated network time + synchronization services that might be installed on the + system. This command is hence mostly equivalent to: + <command>systemctl enable --now + systemd-timesyncd.service</command> and <command>systemctl + disable --now systemd-timesyncd.service</command>, but is + protected by a different access policy.</para> + + <para>Note that even if time synchronization is turned off + with this command, another unrelated system service might + still synchronize the clock with the network. Also note that + strictly speaking + <filename>systemd-timesyncd.service</filename> does more than + just network time synchronization as it ensures a monotonic + clock on systems without RTC even if no network is + available. See + <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details about this.</para></listitem> </varlistentry> </variablelist> |