diff options
Diffstat (limited to 'man')
87 files changed, 3142 insertions, 1343 deletions
diff --git a/man/bootctl.xml b/man/bootctl.xml index 6e835c037f..e2575a4751 100644 --- a/man/bootctl.xml +++ b/man/bootctl.xml @@ -47,16 +47,16 @@ <refsynopsisdiv> <cmdsynopsis> - <command>bootctl <arg choice="opt" rep="repeat">OPTIONS</arg>status</command> + <command>bootctl <arg choice="opt" rep="repeat">OPTIONS</arg> status</command> </cmdsynopsis> <cmdsynopsis> - <command>bootctl <arg choice="opt" rep="repeat">OPTIONS</arg>update</command> + <command>bootctl <arg choice="opt" rep="repeat">OPTIONS</arg> update</command> </cmdsynopsis> <cmdsynopsis> - <command>bootctl <arg choice="opt" rep="repeat">OPTIONS</arg>install</command> + <command>bootctl <arg choice="opt" rep="repeat">OPTIONS</arg> install</command> </cmdsynopsis> <cmdsynopsis> - <command>bootctl <arg choice="opt" rep="repeat">OPTIONS</arg>remove</command> + <command>bootctl <arg choice="opt" rep="repeat">OPTIONS</arg> remove</command> </cmdsynopsis> </refsynopsisdiv> @@ -71,19 +71,14 @@ currently installed versions of the boot loader binaries and all current EFI boot variables.</para> - <para><command>bootctl update</command> updates all installed - versions of systemd-boot, if the current version is newer than the - version installed in the EFI system partition. This also includes - the EFI default/fallback loader at /EFI/BOOT/BOOT*.EFI. A - systemd-boot entry in the EFI boot variables is created if there - is no current entry. The created entry will be added to the end of - the boot order list.</para> + <para><command>bootctl update</command> updates all installed versions of systemd-boot, if the current version is + newer than the version installed in the EFI system partition. This also includes the EFI default/fallback loader at + <filename>/EFI/BOOT/BOOT*.EFI</filename>. A systemd-boot entry in the EFI boot variables is created if there is no + current entry. The created entry will be added to the end of the boot order list.</para> - <para><command>bootctl install</command> installs systemd-boot into - the EFI system partition. A copy of systemd-boot will be stored as - the EFI default/fallback loader at /EFI/BOOT/BOOT*.EFI. A systemd-boot - entry in the EFI boot variables is created and added to the top - of the boot order list.</para> + <para><command>bootctl install</command> installs systemd-boot into the EFI system partition. A copy of + systemd-boot will be stored as the EFI default/fallback loader at <filename>/EFI/BOOT/BOOT*.EFI</filename>. A + systemd-boot entry in the EFI boot variables is created and added to the top of the boot order list.</para> <para><command>bootctl remove</command> removes all installed versions of systemd-boot from the EFI system partition, and removes @@ -101,8 +96,10 @@ <xi:include href="standard-options.xml" xpointer="help" /> <xi:include href="standard-options.xml" xpointer="version" /> <varlistentry> - <term><option>--path</option></term> - <listitem><para>Path to the EFI system partition. The default is /boot.</para></listitem> + <term><option>--path=</option></term> + <listitem><para>Path to the EFI System Partition (ESP). If not specified, <filename>/efi</filename>, + <filename>/boot</filename>, and <filename>/boot/efi</filename> are checked in turn. It is recommended to mount + the ESP to <filename>/boot</filename>, if possible.</para></listitem> </varlistentry> <varlistentry> diff --git a/man/coredump.conf.xml b/man/coredump.conf.xml index 4f95680a3a..77b4dac51c 100644 --- a/man/coredump.conf.xml +++ b/man/coredump.conf.xml @@ -83,16 +83,13 @@ <varlistentry> <term><varname>Storage=</varname></term> - <listitem><para>Controls where to store cores. One of - <literal>none</literal>, <literal>external</literal>, - <literal>journal</literal>, and <literal>both</literal>. When - <literal>none</literal>, the core dumps will be logged but not - stored permanently. When <literal>external</literal> (the - default), cores will be stored in <filename>/var/lib/systemd/coredump</filename>. - When <literal>journal</literal>, cores will be stored in - the journal and rotated following normal journal - rotation patterns. When <literal>both</literal>, cores - will be stored in both locations.</para> + <listitem><para>Controls where to store cores. One of <literal>none</literal>, + <literal>external</literal>, and <literal>journal</literal>. When + <literal>none</literal>, the core dumps will be logged (included the traceback if + possible), but not stored permanently. When <literal>external</literal> (the + default), cores will be stored in <filename>/var/lib/systemd/coredump/</filename>. + When <literal>journal</literal>, cores will be stored in the journal and rotated + following normal journal rotation patterns.</para> <para>When cores are stored in the journal, they might be compressed following journal compression settings, see diff --git a/man/crypttab.xml b/man/crypttab.xml index 4b8d4aa3d6..17976f3704 100644 --- a/man/crypttab.xml +++ b/man/crypttab.xml @@ -327,6 +327,17 @@ </varlistentry> <varlistentry> + <term><option>tcrypt-veracrypt</option></term> + + <listitem><para>Check for a VeraCrypt volume. VeraCrypt is a fork of + TrueCrypt that is mostly compatible, but uses different, stronger key + derivation algorithms that cannot be detected without this flag. + Enabling this option could substantially slow down unlocking, because + VeraCrypt's key derivation takes much longer than TrueCrypt's. This + option implies <option>tcrypt</option>.</para></listitem> + </varlistentry> + + <varlistentry> <term><option>timeout=</option></term> <listitem><para>Specifies the timeout for querying for a diff --git a/man/dnssec-trust-anchors.d.xml b/man/dnssec-trust-anchors.d.xml index 4bdc167f79..9a28862ceb 100644 --- a/man/dnssec-trust-anchors.d.xml +++ b/man/dnssec-trust-anchors.d.xml @@ -160,14 +160,12 @@ <refsect1> <title>Negative Trust Anchors</title> - <para>Negative trust anchors define domains where DNSSEC - validation shall be turned off. Negative trust anchor files are - found at the same location as positive trust anchor files, and - follow the same overriding rules. They are text files with the - <filename>.negative</filename> suffix. Empty lines and lines whose - first character is <literal>;</literal> are ignored. Each line - specifies one domain name where DNSSEC validation shall be - disabled on.</para> + <para>Negative trust anchors define domains where DNSSEC validation shall be turned + off. Negative trust anchor files are found at the same location as positive trust anchor files, + and follow the same overriding rules. They are text files with the + <filename>.negative</filename> suffix. Empty lines and lines whose first character is + <literal>;</literal> are ignored. Each line specifies one domain name which is the root of a DNS + subtree where validation shall be disabled.</para> <para>Negative trust anchors are useful to support private DNS subtrees that are not referenced from the Internet DNS hierarchy, diff --git a/man/hostnamectl.xml b/man/hostnamectl.xml index 60004e9d04..9e1b593e6d 100644 --- a/man/hostnamectl.xml +++ b/man/hostnamectl.xml @@ -71,10 +71,9 @@ set, and is valid (something other than localhost), then the transient hostname is not used.</para> - <para>Note that the pretty hostname has little restrictions on the - characters used, while the static and transient hostnames are - limited to the usually accepted characters of Internet domain - names.</para> + <para>Note that the pretty hostname has little restrictions on the characters and length used, while the static and + transient hostnames are limited to the usually accepted characters of Internet domain names, and 64 characters at + maximum (the latter being a Linux limitation).</para> <para>The static hostname is stored in <filename>/etc/hostname</filename>, see @@ -107,15 +106,11 @@ <term><option>--transient</option></term> <term><option>--pretty</option></term> - <listitem><para>If <command>status</command> is used (or no - explicit command is given) and one of those fields is given, - <command>hostnamectl</command> will print out just this - selected hostname.</para> + <listitem><para>If <command>status</command> is invoked (or no explicit command is given) and one of these + switches is specified, <command>hostnamectl</command> will print out just this selected hostname.</para> - <para>If used with <command>set-hostname</command>, only the - selected hostname(s) will be updated. When more than one of - those options is used, all the specified hostnames will be - updated. </para></listitem> + <para>If used with <command>set-hostname</command>, only the selected hostname(s) will be updated. When more + than one of these switches are specified, all the specified hostnames will be updated. </para></listitem> </varlistentry> <xi:include href="user-system-options.xml" xpointer="host" /> @@ -139,22 +134,14 @@ <varlistentry> <term><command>set-hostname <replaceable>NAME</replaceable></command></term> - <listitem><para>Set the system hostname to - <replaceable>NAME</replaceable>. By default, this will alter - the pretty, the static, and the transient hostname alike; - however, if one or more of <option>--static</option>, - <option>--transient</option>, <option>--pretty</option> are - used, only the selected hostnames are changed. If the pretty - hostname is being set, and static or transient are being set - as well, the specified hostname will be simplified in regards - to the character set used before the latter are updated. This - is done by replacing spaces with <literal>-</literal> and - removing special characters. This ensures that the pretty and - the static hostname are always closely related while still - following the validity rules of the specific name. This - simplification of the hostname string is not done if only the - transient and/or static host names are set, and the pretty - host name is left untouched.</para> + <listitem><para>Set the system hostname to <replaceable>NAME</replaceable>. By default, this will alter the + pretty, the static, and the transient hostname alike; however, if one or more of <option>--static</option>, + <option>--transient</option>, <option>--pretty</option> are used, only the selected hostnames are changed. If + the pretty hostname is being set, and static or transient are being set as well, the specified hostname will be + simplified in regards to the character set used before the latter are updated. This is done by removing special + characters and spaces. This ensures that the pretty and the static hostname are always closely related while + still following the validity rules of the specific name. This simplification of the hostname string is not done + if only the transient and/or static host names are set, and the pretty host name is left untouched.</para> <para>Pass the empty string <literal></literal> as the hostname to reset the selected hostnames to their default diff --git a/man/journal-remote.conf.xml b/man/journal-remote.conf.xml index 2d345963d9..f7ac8c46e0 100644 --- a/man/journal-remote.conf.xml +++ b/man/journal-remote.conf.xml @@ -45,22 +45,21 @@ <refnamediv> <refname>journal-remote.conf</refname> <refname>journal-remote.conf.d</refname> - <refpurpose>Journal remote service configuration files</refpurpose> + <refpurpose>Configuration files for the service accepting remote journal uploads</refpurpose> </refnamediv> <refsynopsisdiv> <para><filename>/etc/systemd/journal-remote.conf</filename></para> - <para><filename>/etc/systemd/journald.conf.d/*.conf</filename></para> - <para><filename>/run/systemd/journald.conf.d/*.conf</filename></para> - <para><filename>/usr/lib/systemd/journald.conf.d/*.conf</filename></para> + <para><filename>/etc/systemd/journal-remote.conf.d/*.conf</filename></para> + <para><filename>/run/systemd/journal-remote.conf.d/*.conf</filename></para> + <para><filename>/usr/lib/systemd/journal-remote.conf.d/*.conf</filename></para> </refsynopsisdiv> <refsect1> <title>Description</title> - <para>These files configure various parameters of the systemd-remote-journal - application, - <citerefentry><refentrytitle>systemd-journal-remote</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + <para>These files configure various parameters of + <citerefentry><refentrytitle>systemd-journal-remote.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> </refsect1> <xi:include href="standard-conf.xml" xpointer="main-conf" /> diff --git a/man/journal-upload.conf.xml b/man/journal-upload.conf.xml new file mode 100644 index 0000000000..e3be62dfd1 --- /dev/null +++ b/man/journal-upload.conf.xml @@ -0,0 +1,113 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2016 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="journal-upload.conf" conditional='HAVE_MICROHTTPD' + xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>journal-upload.conf</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Monkey with a keyboard</contrib> + <firstname>Zbigniew</firstname> + <surname>Jędrzejewski-Szmek</surname> + <email>zbyszek@in.waw.pl</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>journal-upload.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>journal-upload.conf</refname> + <refname>journal-upload.conf.d</refname> + <refpurpose>Configuration files for the journal upload service</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/systemd/journal-upload.conf</filename></para> + <para><filename>/etc/systemd/journal-upload.conf.d/*.conf</filename></para> + <para><filename>/run/systemd/journal-upload.conf.d/*.conf</filename></para> + <para><filename>/usr/lib/systemd/journal-upload.conf.d/*.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>These files configure various parameters of + <citerefentry><refentrytitle>systemd-journal-upload.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </refsect1> + + <xi:include href="standard-conf.xml" xpointer="main-conf" /> + + <refsect1> + <title>Options</title> + + <para>All options are configured in the <literal>[Upload]</literal> section:</para> + + <variablelist> + <varlistentry> + <term><varname>URL=</varname></term> + + <listitem><para>The URL to upload the journal entries to. See the description + of <varname>--url=</varname> option in + <citerefentry><refentrytitle>systemd-journal-upload</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for the description of possible values.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ServerKeyFile=</varname></term> + + <listitem><para>SSL key in PEM format.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ServerCertificateFile=</varname></term> + + <listitem><para>SSL CA certificate in PEM format.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TrustedCertificateFile=</varname></term> + + <listitem><para>SSL CA certificate.</para></listitem> + </varlistentry> + + </variablelist> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd-journal-upload</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/journalctl.xml b/man/journalctl.xml index e77621d7b3..63b4a267b8 100644 --- a/man/journalctl.xml +++ b/man/journalctl.xml @@ -250,6 +250,18 @@ <varlistentry> <term> + <option>short-full</option> + </term> + <listitem> + <para>is very similar, but shows timestamps in the format the <option>--since=</option> and + <option>--until=</option> options accept. Unlike the timestamp information shown in + <option>short</option> output mode this mode includes weekday, year and timezone information in the + output, and is locale-independent.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> <option>short-iso</option> </term> <listitem> @@ -572,24 +584,17 @@ <term><option>-U</option></term> <term><option>--until=</option></term> - <listitem><para>Start showing entries on or newer than the - specified date, or on or older than the specified date, - respectively. Date specifications should be of the format - <literal>2012-10-30 18:17:16</literal>. If the time part is - omitted, <literal>00:00:00</literal> is assumed. If only the - seconds component is omitted, <literal>:00</literal> is - assumed. If the date component is omitted, the current day is - assumed. Alternatively the strings - <literal>yesterday</literal>, <literal>today</literal>, - <literal>tomorrow</literal> are understood, which refer to - 00:00:00 of the day before the current day, the current day, - or the day after the current day, - respectively. <literal>now</literal> refers to the current - time. Finally, relative times may be specified, prefixed with - <literal>-</literal> or <literal>+</literal>, referring to - times before or after the current time, respectively. For complete - time and date specification, see - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + <listitem><para>Start showing entries on or newer than the specified date, or on or older than the specified + date, respectively. Date specifications should be of the format <literal>2012-10-30 18:17:16</literal>. If the + time part is omitted, <literal>00:00:00</literal> is assumed. If only the seconds component is omitted, + <literal>:00</literal> is assumed. If the date component is omitted, the current day is assumed. Alternatively + the strings <literal>yesterday</literal>, <literal>today</literal>, <literal>tomorrow</literal> are understood, + which refer to 00:00:00 of the day before the current day, the current day, or the day after the current day, + respectively. <literal>now</literal> refers to the current time. Finally, relative times may be specified, + prefixed with <literal>-</literal> or <literal>+</literal>, referring to times before or after the current + time, respectively. For complete time and date specification, see + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>. Note that + <option>--output=short-full</option> prints timestamps that follow precisely this format. </para> </listitem> </varlistentry> @@ -654,10 +659,12 @@ <term><option>--root=<replaceable>ROOT</replaceable></option></term> <listitem><para>Takes a directory path as an argument. If - specified, journalctl will operate on catalog file hierarchy + specified, journalctl will operate on journal directories and catalog file hierarchy underneath the specified directory instead of the root directory (e.g. <option>--update-catalog</option> will create - <filename><replaceable>ROOT</replaceable>/var/lib/systemd/catalog/database</filename>). + <filename><replaceable>ROOT</replaceable>/var/lib/systemd/catalog/database</filename>, + and journal files under <filename><replaceable>ROOT</replaceable>/run/journal</filename> + or <filename><replaceable>ROOT</replaceable>/var/log/journal</filename> will be displayed). </para></listitem> </varlistentry> diff --git a/man/journald.conf.xml b/man/journald.conf.xml index fef4fde898..9daa964803 100644 --- a/man/journald.conf.xml +++ b/man/journald.conf.xml @@ -129,23 +129,15 @@ <varlistentry> <term><varname>SplitMode=</varname></term> - <listitem><para>Controls whether to split up journal files per user. Split-up journal files are primarily - useful for access control: on UNIX/Linux access control is managed per file, and the journal daemon will assign - users read access to their journal files. This setting takes one of <literal>uid</literal>, - <literal>login</literal> or <literal>none</literal>. If <literal>uid</literal>, all regular users will get each - their own journal files regardless of whether their processes possess login sessions or not, however system - users will log into the system journal. If <literal>login</literal>, actually logged-in users will get each - their own journal files, but users without login session and system users will log into the system - journal. Note that in this mode, user code running outside of any login session will log into the system log - instead of the split-out user logs. Most importantly, this means that information about core dumps of user - processes collected via the - <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry> subsystem - will end up in the system logs instead of the user logs, and thus not be accessible to the owning users. If - <literal>none</literal>, journal files are not split up by user and all messages are instead stored in the - single system journal. In this mode unprivileged users generally do not have access to their own log data. Note - that splitting up journal files by user is only available for journals stored persistently. If journals are - stored on volatile storage (see above), only a single journal file for all user IDs is kept. Defaults to - <literal>uid</literal>.</para></listitem> + <listitem><para>Controls whether to split up journal files per user, either <literal>uid</literal> or + <literal>none</literal>. Split journal files are primarily useful for access control: on UNIX/Linux access + control is managed per file, and the journal daemon will assign users read access to their journal files. If + <literal>uid</literal>, all regular users will each get their own journal files, and system users will log to + the system journal. If <literal>none</literal>, journal files are not split up by user and all messages are + instead stored in the single system journal. In this mode unprivileged users generally do not have access to + their own log data. Note that splitting up journal files by user is only available for journals stored + persistently. If journals are stored on volatile storage (see <varname>Storage=</varname> above), only a single + journal file is used. Defaults to <literal>uid</literal>.</para></listitem> </varlistentry> <varlistentry> @@ -309,22 +301,21 @@ <term><varname>ForwardToConsole=</varname></term> <term><varname>ForwardToWall=</varname></term> - <listitem><para>Control whether log messages received by the - journal daemon shall be forwarded to a traditional syslog - daemon, to the kernel log buffer (kmsg), to the system - console, or sent as wall messages to all logged-in users. - These options take boolean arguments. If forwarding to syslog - is enabled but nothing reads messages from the socket, - forwarding to syslog has no effect. By default, only - forwarding to wall is enabled. These settings may be - overridden at boot time with the kernel command line options - <literal>systemd.journald.forward_to_syslog=</literal>, - <literal>systemd.journald.forward_to_kmsg=</literal>, - <literal>systemd.journald.forward_to_console=</literal>, and - <literal>systemd.journald.forward_to_wall=</literal>. When - forwarding to the console, the TTY to log to can be changed - with <varname>TTYPath=</varname>, described - below.</para></listitem> + <listitem><para>Control whether log messages received by the journal daemon shall + be forwarded to a traditional syslog daemon, to the kernel log buffer (kmsg), to + the system console, or sent as wall messages to all logged-in users. These + options take boolean arguments. If forwarding to syslog is enabled but nothing + reads messages from the socket, forwarding to syslog has no effect. By default, + only forwarding to wall is enabled. These settings may be overridden at boot time + with the kernel command line options + <literal>systemd.journald.forward_to_syslog</literal>, + <literal>systemd.journald.forward_to_kmsg</literal>, + <literal>systemd.journald.forward_to_console</literal>, and + <literal>systemd.journald.forward_to_wall</literal>. If the option name is + specified without <literal>=</literal> and the following argument, true is + assumed. Otherwise, the argument is parsed as a boolean. When forwarding to the + console, the TTY to log to can be changed with <varname>TTYPath=</varname>, + described below.</para></listitem> </varlistentry> <varlistentry> @@ -356,7 +347,14 @@ <literal>notice</literal> for <varname>MaxLevelKMsg=</varname>, <literal>info</literal> for <varname>MaxLevelConsole=</varname>, and <literal>emerg</literal> for - <varname>MaxLevelWall=</varname>.</para></listitem> + <varname>MaxLevelWall=</varname>. These settings may be + overridden at boot time with the kernel command line options + <literal>systemd.journald.max_level_store=</literal>, + <literal>systemd.journald.max_level_syslog=</literal>, + <literal>systemd.journald.max_level_kmsg=</literal>, + <literal>systemd.journald.max_level_console=</literal>, + <literal>systemd.journald.max_level_wall=</literal>.</para> + </listitem> </varlistentry> <varlistentry> diff --git a/man/kernel-command-line.xml b/man/kernel-command-line.xml index 3ecc969c10..1fa31a14b7 100644 --- a/man/kernel-command-line.xml +++ b/man/kernel-command-line.xml @@ -224,15 +224,14 @@ <varlistentry> <term><varname>vconsole.keymap=</varname></term> - <term><varname>vconsole.keymap.toggle=</varname></term> + <term><varname>vconsole.keymap_toggle=</varname></term> <term><varname>vconsole.font=</varname></term> - <term><varname>vconsole.font.map=</varname></term> - <term><varname>vconsole.font.unimap=</varname></term> + <term><varname>vconsole.font_map=</varname></term> + <term><varname>vconsole.font_unimap=</varname></term> <listitem> - <para>Parameters understood by the virtual console setup - logic. For details, see - <citerefentry><refentrytitle>systemd-vconsole-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + <para>Parameters understood by the virtual console setup logic. For details, see + <citerefentry><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> </listitem> </varlistentry> diff --git a/man/kernel-install.xml b/man/kernel-install.xml index eb519188a6..32e6169f63 100644 --- a/man/kernel-install.xml +++ b/man/kernel-install.xml @@ -72,9 +72,12 @@ in <filename>/usr/lib/kernel/install.d/</filename>. This can be used to override a system-supplied executables with a local file if needed; a symbolic link in <filename>/etc/kernel/install.d/</filename> with the same name as an executable in <filename>/usr/lib/kernel/install.d/</filename>, - pointing to /dev/null, disables the executable entirely. Executables must have the + pointing to <filename>/dev/null</filename>, disables the executable entirely. Executables must have the extension <literal>.install</literal>; other extensions are ignored.</para> + <para>An executable should return <constant>0</constant> on success. It may also + return <constant>77</constant> to cause the whole operation to terminate + (executables later in lexical order will be skipped).</para> </refsect1> <refsect1> diff --git a/man/less-variables.xml b/man/less-variables.xml index 0fb4d7fbcf..1f34cbc1bf 100644 --- a/man/less-variables.xml +++ b/man/less-variables.xml @@ -3,27 +3,34 @@ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> <refsect1> - <title>Environment</title> - - <variablelist class='environment-variables'> - <varlistentry id='pager'> - <term><varname>$SYSTEMD_PAGER</varname></term> - - <listitem><para>Pager to use when - <option>--no-pager</option> is not given; - overrides <varname>$PAGER</varname>. Setting - this to an empty string or the value - <literal>cat</literal> is equivalent to passing - <option>--no-pager</option>.</para></listitem> - </varlistentry> - - <varlistentry id='less'> - <term><varname>$SYSTEMD_LESS</varname></term> - - <listitem><para>Override the default - options passed to - <command>less</command> - (<literal>FRSXMK</literal>).</para></listitem> - </varlistentry> - </variablelist> + <title>Environment</title> + + <variablelist class='environment-variables'> + <varlistentry id='pager'> + <term><varname>$SYSTEMD_PAGER</varname></term> + + <listitem><para>Pager to use when <option>--no-pager</option> is not given; overrides + <varname>$PAGER</varname>. If neither <varname>$SYSTEMD_PAGER</varname> nor <varname>$PAGER</varname> are set, a + set of well-known pager implementations are tried in turn, including + <citerefentry><refentrytitle>less</refentrytitle><manvolnum>1</manvolnum></citerefentry> and + <citerefentry><refentrytitle>more</refentrytitle><manvolnum>1</manvolnum></citerefentry>, until one is found. If + no pager implementation is discovered no pager is invoked. Setting this environment variable to an empty string + or the value <literal>cat</literal> is equivalent to passing <option>--no-pager</option>.</para></listitem> + </varlistentry> + + <varlistentry id='less'> + <term><varname>$SYSTEMD_LESS</varname></term> + + <listitem><para>Override the options passed to <command>less</command> (by default + <literal>FRSXMK</literal>).</para></listitem> + </varlistentry> + + <varlistentry id='lesscharset'> + <term><varname>$SYSTEMD_LESSCHARSET</varname></term> + + <listitem><para>Override the charset passed to <command>less</command> (by default <literal>utf-8</literal>, if + the invoking terminal is determined to be UTF-8 compatible).</para></listitem> + </varlistentry> + + </variablelist> </refsect1> diff --git a/man/localectl.xml b/man/localectl.xml index 8d2becb5d9..31238272f3 100644 --- a/man/localectl.xml +++ b/man/localectl.xml @@ -223,7 +223,7 @@ <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-localed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>mkinitrd</refentrytitle><manvolnum>8</manvolnum></citerefentry> + <citerefentry project='die-net'><refentrytitle>mkinitrd</refentrytitle><manvolnum>8</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/logind.conf.xml b/man/logind.conf.xml index adba5a4131..994e0e1140 100644 --- a/man/logind.conf.xml +++ b/man/logind.conf.xml @@ -211,7 +211,7 @@ <term><varname>HandleLidSwitch=</varname></term> <term><varname>HandleLidSwitchDocked=</varname></term> - <listitem><para>Controls whether logind shall handle the + <listitem><para>Controls how logind shall handle the system power and sleep keys and the lid switch to trigger actions such as system power-off or suspend. Can be one of <literal>ignore</literal>, @@ -240,7 +240,16 @@ docking station, or if more than one display is connected, the action specified by <varname>HandleLidSwitchDocked=</varname> occurs; otherwise the <varname>HandleLidSwitch=</varname> - action occurs.</para></listitem> + action occurs.</para> + + <para>A different application may disable logind's handling of system power and + sleep keys and the lid switch by taking a low-level inhibitor lock + ("handle-power-key", "handle-suspend-key", "handle-hibernate-key", + "handle-lid-switch"). This is most commonly used by graphical desktop environments + to take over suspend and hibernation handling, and to use their own configuration + mechanisms. If a low-level inhibitor lock is taken, logind will not take any + action when that key or switch is triggered and the <varname>Handle*=</varname> + settings are irrelevant.</para></listitem> </varlistentry> <varlistentry> @@ -249,21 +258,22 @@ <term><varname>HibernateKeyIgnoreInhibited=</varname></term> <term><varname>LidSwitchIgnoreInhibited=</varname></term> - <listitem><para>Controls whether actions triggered by the - power and sleep keys and the lid switch are subject to - inhibitor locks. These settings take boolean arguments. If - <literal>no</literal>, the inhibitor locks taken by - applications in order to block the requested operation are - respected. If <literal>yes</literal>, the requested operation - is executed in any case. + <listitem><para>Controls whether actions that <command>systemd-logind</command> + takes when the power and sleep keys and the lid switch are triggered are subject + to high-level inhibitor locks ("shutdown", "sleep", "idle"). Low level inhibitor + locks ("handle-*-key"), are always honored, irrespective of this setting.</para> + + <para>These settings take boolean arguments. If <literal>no</literal>, the + inhibitor locks taken by applications are respected. If <literal>yes</literal>, + "shutdown", "sleep", and "idle" inhibitor locks are ignored. <varname>PowerKeyIgnoreInhibited=</varname>, - <varname>SuspendKeyIgnoreInhibited=</varname> and - <varname>HibernateKeyIgnoreInhibited=</varname> default to - <literal>no</literal>. - <varname>LidSwitchIgnoreInhibited=</varname> defaults to - <literal>yes</literal>. This means that the lid switch does - not respect suspend blockers by default, but the power and - sleep keys do. </para></listitem> + <varname>SuspendKeyIgnoreInhibited=</varname>, and + <varname>HibernateKeyIgnoreInhibited=</varname> default to <literal>no</literal>. + <varname>LidSwitchIgnoreInhibited=</varname> defaults to <literal>yes</literal>. + This means that when <command>systemd-logind</command> is handling events by + itself (no low level inhibitor locks are taken by another application), the lid + switch does not respect suspend blockers by default, but the power and sleep keys + do.</para></listitem> </varlistentry> <varlistentry> @@ -318,8 +328,9 @@ <listitem><para>Sets the maximum number of OS tasks each user may run concurrently. This controls the <varname>TasksMax=</varname> setting of the per-user slice unit, see <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. Defaults to 33%, which equals 10813 with the kernel's defaults on the host, but might be smaller - in OS containers.</para></listitem> + for details. If assigned the special value <literal>infinity</literal>, no tasks limit is applied. + Defaults to 33%, which equals 10813 with the kernel's defaults on the host, but might be smaller in + OS containers.</para></listitem> </varlistentry> <varlistentry> diff --git a/man/machinectl.xml b/man/machinectl.xml index 597a5cc583..5a6ec294d2 100644 --- a/man/machinectl.xml +++ b/man/machinectl.xml @@ -186,12 +186,11 @@ <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> + <listitem><para>When used with the <command>shell</command> command, chooses the user ID to + open the interactive shell session as. If the argument to the <command>shell</command> + command also specifies a user name, this option is ignored. If the name is not specified + in either way, <literal>root</literal> will be used by default. Note that this switch is + not supported for the <command>login</command> command (see below).</para></listitem> </varlistentry> <varlistentry> @@ -285,6 +284,20 @@ name passed.</para></listitem> </varlistentry> + <varlistentry> + <term><option>--max-addresses=</option></term> + + <listitem><para>When used with the <option>list-machines</option> + command, limits the number of ip addresses output for every machine. + Defaults to 1. All addresses can be requested with <literal>all</literal> + as argument to <option>--max-addresses</option> . If the argument to + <option>--max-addresses</option> is less than the actual number + of addresses,<literal>...</literal>follows the last address. + If multiple addresses are to be written for a given machine, every + address except the first one is on a new line and is followed by + <literal>,</literal> if another address will be output afterwards. </para></listitem> + </varlistentry> + <xi:include href="user-system-options.xml" xpointer="host" /> <xi:include href="user-system-options.xml" xpointer="machine" /> @@ -330,18 +343,13 @@ <varlistentry> <term><command>show</command> [<replaceable>NAME</replaceable>...]</term> - <listitem><para>Show properties of one or more registered - virtual machines or containers or the manager itself. If no - argument is specified, properties of the manager will be - shown. If a NAME is specified, properties of this virtual - machine or container are shown. By default, empty properties - are suppressed. Use <option>--all</option> to show those too. - To select specific properties to show, use - <option>--property=</option>. This command is intended to be - used whenever computer-parsable output is required, and does - not print the cgroup tree or journal entries. Use - <command>status</command> if you are looking for formatted - human-readable output.</para></listitem> + <listitem><para>Show properties of one or more registered virtual machines or containers or the manager + itself. If no argument is specified, properties of the manager will be shown. If a NAME is specified, + properties of this virtual machine or container are shown. By default, empty properties are suppressed. Use + <option>--all</option> to show those too. To select specific properties to show, use + <option>--property=</option>. This command is intended to be used whenever computer-parsable output is + required, and does not print the control group tree or journal entries. Use <command>status</command> if you + are looking for formatted human-readable output.</para></listitem> </varlistentry> <varlistentry> diff --git a/man/networkd.conf.xml b/man/networkd.conf.xml index 4bfc4f773a..57e647a31b 100644 --- a/man/networkd.conf.xml +++ b/man/networkd.conf.xml @@ -120,7 +120,7 @@ <para>The DUID value specified here overrides the DUID that systemd-networkd generates using the machine-id from the <filename>/etc/machine-id</filename> file. To configure DUID per-network, see - <citerefentry><refentrytitle>systemd.network </refentrytitle><manvolnum>5</manvolnum></citerefentry>. + <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The configured DHCP DUID should conform to the specification in <ulink url="http://tools.ietf.org/html/rfc3315#section-9">RFC 3315</ulink>, <ulink url="http://tools.ietf.org/html/rfc6355">RFC 6355</ulink>. To configure IAID, see diff --git a/man/nss-myhostname.xml b/man/nss-myhostname.xml index a920ec334f..c25476ecc8 100644 --- a/man/nss-myhostname.xml +++ b/man/nss-myhostname.xml @@ -106,11 +106,11 @@ <para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables <command>nss-myhostname</command> correctly:</para> -<programlisting>passwd: compat mymachines -group: compat mymachines +<programlisting>passwd: compat mymachines systemd +group: compat mymachines systemd shadow: compat -hosts: files mymachines resolve <command>myhostname</command> +hosts: files mymachines resolve [!UNAVAIL=return] dns <command>myhostname</command> networks: files protocols: db files @@ -138,6 +138,7 @@ netgroup: nis</programlisting> <title>See Also</title> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nss-systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, diff --git a/man/nss-mymachines.xml b/man/nss-mymachines.xml index ec047449bf..00bcc53ec0 100644 --- a/man/nss-mymachines.xml +++ b/man/nss-mymachines.xml @@ -82,11 +82,11 @@ <para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables <command>nss-mymachines</command> correctly:</para> - <programlisting>passwd: compat <command>mymachines</command> -group: compat <command>mymachines</command> + <programlisting>passwd: compat <command>mymachines</command> systemd +group: compat <command>mymachines</command> systemd shadow: compat -hosts: files <command>mymachines</command> resolve myhostname +hosts: files <command>mymachines</command> resolve [!UNAVAIL=return] dns myhostname networks: files protocols: db files @@ -103,6 +103,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-systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, diff --git a/man/nss-resolve.xml b/man/nss-resolve.xml index d9e56453e8..9f24f65019 100644 --- a/man/nss-resolve.xml +++ b/man/nss-resolve.xml @@ -81,11 +81,11 @@ <para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables <command>nss-resolve</command> correctly:</para> -<programlisting>passwd: compat mymachines -group: compat mymachines +<programlisting>passwd: compat mymachines systemd +group: compat mymachines systemd shadow: compat -hosts: files mymachines <command>resolve</command> myhostname +hosts: files mymachines <command>resolve [!UNAVAIL=return]</command> dns myhostname networks: files protocols: db files @@ -95,6 +95,8 @@ rpc: db files netgroup: nis</programlisting> + <para>This keeps the <command>dns</command> module as a fallback for cases where the <command>nss-resolve</command> + module is not installed.</para> </refsect1> <refsect1> @@ -102,8 +104,9 @@ netgroup: nis</programlisting> <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-systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/nss-systemd.xml b/man/nss-systemd.xml new file mode 100644 index 0000000000..71aed4df83 --- /dev/null +++ b/man/nss-systemd.xml @@ -0,0 +1,111 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2016 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="nss-systemd"> + + <refentryinfo> + <title>nss-systemd</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>nss-systemd</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>nss-systemd</refname> + <refname>libnss_systemd.so.2</refname> + <refpurpose>Provide UNIX user and group name resolution for dynamic users and groups.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>libnss_systemd.so.2</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>nss-systemd</command> is a plug-in module for the GNU Name Service Switch (NSS) functionality of the + GNU C Library (<command>glibc</command>), providing UNIX user and group name resolution for dynamic users and + groups allocated through the <varname>DynamicUser=</varname> option in systemd unit files. See + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details on + this option.</para> + + <para>This module also ensures that the root and nobody users and groups (i.e. the users/groups with the UIDs/GIDs + 0 and 65534) remain resolvable at all times, even if they aren't listed in <filename>/etc/passwd</filename> or + <filename>/etc/group</filename>, or if these files are missing.</para> + + <para>To activate the NSS module, add <literal>systemd</literal> to the lines starting with + <literal>passwd:</literal> and <literal>group:</literal> in <filename>/etc/nsswitch.conf</filename>.</para> + + <para>It is recommended to place <literal>systemd</literal> after the <literal>files</literal> or + <literal>compat</literal> entry of the <filename>/etc/nsswitch.conf</filename> lines so that + <filename>/etc/passwd</filename> and <filename>/etc/group</filename> based mappings take precedence.</para> + </refsect1> + + <refsect1> + <title>Example</title> + + <para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables + <command>nss-systemd</command> correctly:</para> + + <programlisting>passwd: compat mymachines <command>systemd</command> +group: compat mymachines <command>systemd</command> +shadow: compat + +hosts: files mymachines resolve [!UNAVAIL=return] dns myhostname +networks: files + +protocols: db files +services: db files +ethers: db files +rpc: db files + +netgroup: nis</programlisting> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>getent</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/resolved.conf.xml b/man/resolved.conf.xml index 7556c6ff31..4fc1ef1b33 100644 --- a/man/resolved.conf.xml +++ b/man/resolved.conf.xml @@ -206,13 +206,25 @@ <term><varname>Cache=</varname></term> <listitem><para>Takes a boolean argument. If "yes" (the default), resolving a domain name which already got queried earlier will return the previous result as long as it is still valid, and thus does not result in a new - network request. Be aware that that turning off caching comes at a performance penalty, which is particularly + network request. Be aware that turning off caching comes at a performance penalty, which is particularly high when DNSSEC is used.</para> <para>Note that caching is turned off implicitly if the configured DNS server is on a host-local IP address (such as 127.0.0.1 or ::1), in order to avoid duplicate local caching.</para></listitem> </varlistentry> + <varlistentry> + <term><varname>DNSStubListener=</varname></term> + <listitem><para>Takes a boolean argument or one of <literal>udp</literal> and <literal>tcp</literal>. If + <literal>udp</literal> (the default), a DNS stub resolver will listen for UDP requests on address 127.0.0.53 + port 53. If <literal>tcp</literal>, the stub will listen for TCP requests on the same address and port. If + <literal>yes</literal>, the stub listens for both UDP and TCP requests. If <literal>no</literal>, the stub + listener is disabled.</para> + + <para>Note that the DNS stub listener is turned off implicitly when its listening address and port are already + in use.</para></listitem> + </varlistentry> + </variablelist> </refsect1> diff --git a/man/sd-bus.xml b/man/sd-bus.xml index 336dd33ea0..66b1c96c15 100644 --- a/man/sd-bus.xml +++ b/man/sd-bus.xml @@ -44,7 +44,7 @@ <refnamediv> <refname>sd-bus</refname> - <refpurpose>A lightweight D-Bus and kdbus client library</refpurpose> + <refpurpose>A lightweight D-Bus IPC client library</refpurpose> </refnamediv> <refsynopsisdiv> @@ -61,49 +61,40 @@ <refsect1> <title>Description</title> - <para><filename>sd-bus.h</filename> provides an implementation - of a D-Bus client. It can interoperate both with the traditional - <citerefentry project='man-pages'><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - and with kdbus. See + <para><filename>sd-bus.h</filename> provides an implementation of a D-Bus IPC client. See <ulink url="http://www.freedesktop.org/software/dbus/" /> - for more information about the big picture. + for more information about D-Bus IPC. </para> - <important> - <para>Interfaces described here have not been declared stable yet, - and are not accessible from <filename>libsystemd.so</filename>. - This documentation is provided in hope it might be useful for - developers, without any guarantees of availability or stability. - </para> - </important> - <para>See + <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_default</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_request_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_append_array</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_append_string_memfd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_append_strv</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_can_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_get_cookie</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_negotiate_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_path_encode</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_request_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_set_allow_interactive_authorization</refentrytitle><manvolnum>3</manvolnum></citerefentry> <citerefentry><refentrytitle>sd_bus_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_negotiate_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_path_encode</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_set_allow_interactive_authorization</refentrytitle><manvolnum>3</manvolnum></citerefentry> + <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_track_add_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_track_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, for more information about the functions available.</para> </refsect1> @@ -114,9 +105,9 @@ <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>busctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>dbus-send</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <ulink url="https://developer.gnome.org/gio/stable/gdbus.html">gdbus</ulink> + <citerefentry project='man-pages'><refentrytitle>dbus-send</refentrytitle><manvolnum>1</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/sd-event.xml b/man/sd-event.xml index fc615f0906..24a69bb645 100644 --- a/man/sd-event.xml +++ b/man/sd-event.xml @@ -97,7 +97,7 @@ iteration a single event source is dispatched. Each time an event source is dispatched the kernel is polled for new events, before the next event source is dispatched. The event loop is designed to - honour priorities and provide fairness within each priority. It is + honor priorities and provide fairness within each priority. It is not designed to provide optimal throughput, as this contradicts these goals due the limitations of the underlying <citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry> diff --git a/man/sd-id128.xml b/man/sd-id128.xml index ea7972055d..5f24feff8e 100644 --- a/man/sd-id128.xml +++ b/man/sd-id128.xml @@ -47,10 +47,12 @@ <refname>sd-id128</refname> <refname>sd_id128_t</refname> <refname>SD_ID128_MAKE</refname> + <refname>SD_ID128_NULL</refname> <refname>SD_ID128_CONST_STR</refname> <refname>SD_ID128_FORMAT_STR</refname> <refname>SD_ID128_FORMAT_VAL</refname> <refname>sd_id128_equal</refname> + <refname>sd_id128_is_null</refname> <refpurpose>APIs for processing 128-bit IDs</refpurpose> </refnamediv> @@ -88,8 +90,8 @@ union type:</para> <programlisting>typedef union sd_id128 { - uint8_t bytes[16]; - uint64_t qwords[2]; + uint8_t bytes[16]; + uint64_t qwords[2]; } sd_id128_t;</programlisting> <para>This union type allows accessing the 128-bit ID as 16 @@ -108,37 +110,46 @@ <programlisting>#define SD_MESSAGE_COREDUMP SD_ID128_MAKE(fc,2e,22,bc,6e,e6,47,b6,b9,07,29,ab,34,a2,50,b1)</programlisting> + <para><function>SD_ID128_NULL</function> may be used to refer to the 128bit ID consisting of only NUL + bytes.</para> + <para><function>SD_ID128_CONST_STR()</function> may be used to convert constant 128-bit IDs into constant strings for output. The following example code will output the string "fc2e22bc6ee647b6b90729ab34a250b1":</para> <programlisting>int main(int argc, char *argv[]) { - puts(SD_ID128_CONST_STR(SD_MESSAGE_COREDUMP)); + puts(SD_ID128_CONST_STR(SD_MESSAGE_COREDUMP)); }</programlisting> - <para><function>SD_ID128_FORMAT_STR</function> and + <para><function>SD_ID128_FORMAT_STR()</function> and <function>SD_ID128_FORMAT_VAL()</function> may be used to format a 128-bit ID in a <citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> format string, as shown in the following example:</para> <programlisting>int main(int argc, char *argv[]) { - sd_id128_t id; - id = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07); - printf("The ID encoded in this C file is " SD_ID128_FORMAT_STR ".\n", SD_ID128_FORMAT_VAL(id)); - return 0; + sd_id128_t id; + id = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07); + printf("The ID encoded in this C file is " SD_ID128_FORMAT_STR ".\n", SD_ID128_FORMAT_VAL(id)); + return 0; }</programlisting> <para>Use <function>sd_id128_equal()</function> to compare two 128-bit IDs:</para> <programlisting>int main(int argc, char *argv[]) { - sd_id128_t a, b, c; - a = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07); - b = SD_ID128_MAKE(f2,28,88,9c,5f,09,44,15,9d,d7,04,77,58,cb,e7,3e); - c = a; - assert(sd_id128_equal(a, c)); - assert(!sd_id128_equal(a, b)); - return 0; + sd_id128_t a, b, c; + a = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07); + b = SD_ID128_MAKE(f2,28,88,9c,5f,09,44,15,9d,d7,04,77,58,cb,e7,3e); + c = a; + assert(sd_id128_equal(a, c)); + assert(!sd_id128_equal(a, b)); + return 0; +}</programlisting> + + <para>Use <function>sd_id128_is_null()</function> to check if an 128bit ID consists of only NUL bytes:</para> + + <programlisting>int main(int argc, char *argv[]) { + assert(sd_id128_is_null(SD_ID128_NULL)); }</programlisting> <para>Note that new, randomized IDs may be generated with diff --git a/man/sd-journal.xml b/man/sd-journal.xml index 09747a480c..0f4b3e8eea 100644 --- a/man/sd-journal.xml +++ b/man/sd-journal.xml @@ -77,7 +77,6 @@ <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_query_enumerate</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_enumerate_fields</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_get_cutoff_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, @@ -99,6 +98,21 @@ tool.</para> </refsect1> + <refsect1> + <title>Thread safety</title> + + <para>Functions that operate on the <structname>sd_journal</structname> object are thread + agnostic — given <structname>sd_journal</structname> pointer may only be used from one thread at + a time, but multiple threads may use multiple such objects safely. Other functions — + those that are used to send entries to the journal, like + <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and similar, or those that are used to retrieve global information like + <citerefentry><refentrytitle>sd_journal_stream_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>sd_journal_get_catalog_for_message_id</refentrytitle><manvolnum>3</manvolnum></citerefentry> + — are thread-safe and may be called from multiple threads in parallel.</para> + </refsect1> + <xi:include href="libsystemd-pkgconfig.xml" /> <refsect1> @@ -113,7 +127,6 @@ <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_query_enumerate</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_enumerate_fields</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_get_cutoff_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, diff --git a/man/sd_bus_creds_get_pid.xml b/man/sd_bus_creds_get_pid.xml index 4c05835568..9e68d5e8c7 100644 --- a/man/sd_bus_creds_get_pid.xml +++ b/man/sd_bus_creds_get_pid.xml @@ -366,7 +366,7 @@ -ENXIO is returned.</para> <para><function>sd_bus_creds_get_cgroup()</function> will retrieve - the cgroup path. See <ulink + the control group path. See <ulink url="https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink>. </para> diff --git a/man/sd_bus_creds_new_from_pid.xml b/man/sd_bus_creds_new_from_pid.xml index 082f7b67db..b4d7d61d0f 100644 --- a/man/sd_bus_creds_new_from_pid.xml +++ b/man/sd_bus_creds_new_from_pid.xml @@ -66,12 +66,12 @@ <funcprototype> <funcdef>uint64_t <function>sd_bus_creds_get_mask</function></funcdef> - <paramdef>const sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> </funcprototype> <funcprototype> <funcdef>uint64_t <function>sd_bus_creds_get_augmented_mask</function></funcdef> - <paramdef>const sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> </funcprototype> <funcprototype> diff --git a/man/sd_bus_message_append.xml b/man/sd_bus_message_append.xml index 77fce02eae..c222d0fd0e 100644 --- a/man/sd_bus_message_append.xml +++ b/man/sd_bus_message_append.xml @@ -169,6 +169,11 @@ </tgroup> </table> + <para>For types "s" and "g" (unicode string or signature), the pointer may be + <constant>NULL</constant>, which is equivalent to an empty string. See + <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for the precise interpretation of those and other types.</para> + </refsect1> <refsect1> diff --git a/man/sd_bus_negotiate_fds.xml b/man/sd_bus_negotiate_fds.xml index a538b13cf0..1501e1427d 100644 --- a/man/sd_bus_negotiate_fds.xml +++ b/man/sd_bus_negotiate_fds.xml @@ -99,41 +99,27 @@ setting as negotiated by the program ultimately activated. By default, file descriptor passing is enabled for both.</para> - <para><function>sd_bus_negotiate_timestamps()</function> controls - whether implicit sender timestamps shall be attached automatically - to all incoming messages. Takes a bus object and a boolean, which, - when true, enables timestamping, and, when false, disables it. - Use + <para><function>sd_bus_negotiate_timestamp()</function> controls whether implicit sender + timestamps shall be attached automatically to all incoming messages. Takes a bus object and a + boolean, which, when true, enables timestamping, and, when false, disables it. Use <citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_get_seqnum</refentrytitle><manvolnum>3</manvolnum></citerefentry> - to query the timestamps of incoming messages. If negotiation is - disabled or not supported, these calls will fail with - <constant>-ENODATA</constant>. Note that not all transports - support timestamping of messages. Specifically, timestamping is - only available on the kdbus transport, but not on dbus1. The - timestamping is applied by the kernel and cannot be manipulated by - userspace. By default, message timestamping is not negotiated for + to query the timestamps of incoming messages. If negotiation is disabled or not supported, these + calls will fail with <constant>-ENODATA</constant>. Note that currently no transports support + timestamping of messages. By default, message timestamping is not negotiated for connections.</para> - <para><function>sd_bus_negotiate_creds()</function> controls - whether and which implicit sender credentials shall be attached - automatically to all incoming messages. Takes a bus object and a - boolean indicating whether to enable or disable the credential - parts encoded in the bit mask value argument. Note that not all - transports support attaching sender credentials to messages, or do - not support all types of sender credential parameters, or might - suppress them under certain circumstances for individual - messages. Specifically, implicit sender credentials on messages - are only fully supported on kdbus transports, and dbus1 only - supports <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>. The sender - credentials are attached by the kernel and cannot be manipulated - by userspace, and are thus suitable for authorization - decisions. By default, only - <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant> and - <constant>SD_BUS_CREDS_UNIQUE_NAME</constant> are enabled. In - fact, these two credential fields are always sent along and cannot - be turned off.</para> + <para><function>sd_bus_negotiate_creds()</function> controls whether and which implicit sender + credentials shall be attached automatically to all incoming messages. Takes a bus object and a + boolean indicating whether to enable or disable the credential parts encoded in the bit mask + value argument. Note that not all transports support attaching sender credentials to messages, + or do not support all types of sender credential parameters, or might suppress them under + certain circumstances for individual messages. Specifically, dbus1 only supports + <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>. The sender credentials are suitable for + authorization decisions. By default, only <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant> and + <constant>SD_BUS_CREDS_UNIQUE_NAME</constant> are enabled. In fact, these two credential fields + are always sent along and cannot be turned off.</para> <para>The <function>sd_bus_negotiate_fds()</function> function may be called only before the connection has been started with diff --git a/man/sd_bus_track_add_name.xml b/man/sd_bus_track_add_name.xml new file mode 100644 index 0000000000..6a5e344cb1 --- /dev/null +++ b/man/sd_bus_track_add_name.xml @@ -0,0 +1,261 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2016 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_bus_track_add_name"> + + <refentryinfo> + <title>sd_bus_track_add_name</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_track_add_name</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_track_add_name</refname> + <refname>sd_bus_track_add_sender</refname> + <refname>sd_bus_track_remove_name</refname> + <refname>sd_bus_track_remove_sender</refname> + <refname>sd_bus_track_count</refname> + <refname>sd_bus_track_count_sender</refname> + <refname>sd_bus_track_count_name</refname> + <refname>sd_bus_track_contains</refname> + <refname>sd_bus_track_first</refname> + <refname>sd_bus_track_next</refname> + + <refpurpose>Add, remove and retrieve bus peers tracked in a bus peer tracking object</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_track_add_name</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + <paramdef>const char* <parameter>name</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_add_sender</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + <paramdef>sd_bus_message* <parameter>message</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_remove_name</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + <paramdef>const char* <parameter>name</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_remove_sender</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + <paramdef>sd_bus_message* <parameter>message</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>unsigned <function>sd_bus_track_count</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_count_name</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + <paramdef>const char* <parameter>name</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_count_sender</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + <paramdef>sd_bus_message* <parameter>message</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_contains</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + <paramdef>const char* <parameter>name</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>const char* <function>sd_bus_track_first</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>const char* <function>sd_bus_track_next</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_track_add_name()</function> adds a peer to track to a bus peer tracking object. The first + argument should refer to a bus peer tracking object created with + <citerefentry><refentrytitle>sd_bus_track_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, the second + name should refer to a D-Bus peer name to track, either in unique or well-known service format. If the name is not + tracked yet it will be added to the list of names to track. If it already is being tracked and non-recursive mode + is enabled, no operation is executed by this call. If recursive mode is enabled a per-name counter is increased by + one each time this call is invoked, and <function>sd_bus_track_remove_name()</function> has to be called as many + times as <function>sd_bus_track_add_name()</function> was invoked before in order to stop tracking of the name. Use + <citerefentry><refentrytitle>sd_bus_track_set_recursive</refentrytitle><manvolnum>3</manvolnum></citerefentry> to + switch from the default non-recursive mode to recursive mode, or back. Note that the specified name is tracked as + it is, well-known names are not resolved to unique names by this call. Note that multiple bus peer tracking objects + may track the same name.</para> + + <para><function>sd_bus_track_remove_name()</function> undoes the effect of + <function>sd_bus_track_add_name()</function> and removes a bus peer name from the list of peers to watch. Depending + on whether non-recursive or recursive mode is enabled for the bus peer tracking object this call will either remove + the name fully from the tracking object, or will simply decrement the per-name counter by one, removing the name + only when the counter reaches zero (see above). Note that a bus peer disconnecting from the bus will implicitly + remove its names fully from the bus peer tracking object, regardless of the current per-name counter.</para> + + <para><function>sd_bus_track_add_sender()</function> and <function>sd_bus_track_remove_sender()</function> are + similar to <function>sd_bus_track_add_name()</function> and <function>sd_bus_track_remove_name()</function> but + take a bus message as argument. The sender of this bus message is determined and added to/removed from the bus peer + tracking object. As messages always originate from unique names, and never from well-known names this means that + this call will effectively only add unique names to the bus peer tracking object.</para> + + <para><function>sd_bus_track_count()</function> returns the number of names currently being tracked by the + specified bus peer tracking object. Note that this function always returns the actual number of names tracked, and + hence if <function>sd_bus_track_add_name()</function> has been invoked multiple times for the same name it is only + counted as one, regardless if recursive mode is used or not.</para> + + <para><function>sd_bus_track_count_name()</function> returns the current per-name counter for the specified + name. If non-recursive mode is used this returns either 1 or 0, depending on whether the specified name has been + added to the tracking object before, or not. If recursive mode has been enabled, values larger than 1 may be + returned too, in case <function>sd_bus_track_add_name()</function> has been called multiple times for the same + name.</para> + + <para><function>sd_bus_track_count_sender()</function> is similar to + <function>sd_bus_track_count_name()</function>, but takes a bus message object and returns the per-name counter + matching the sender of the message.</para> + + <para><function>sd_bus_track_contains()</function> may be used to determine whether the specified name has been + added at least once to the specified bus peer tracking object.</para> + + <para><function>sd_bus_track_first()</function> and <function>sd_bus_track_next()</function> may be used to + enumerate all names currently being tracked by the passed bus peer tracking + object. <function>sd_bus_track_first()</function> returns the first entry in the object, and resets an internally + maintained read index. Each subsequent invocation of <function>sd_bus_track_next()</function> returns the next name + contained in the bus object. If the end is reached <constant>NULL</constant> is returned. If no names have been + added to the object yet <function>sd_bus_track_first()</function> will return <constant>NULL</constant> + immediately. The order in which names are returned is undefined; in particular which name is considered the first + returned is not defined. If recursive mode is enabled and the same name has been added multiple times to the bus + peer tracking object it is only returned once by this enumeration. If new names are added to or existing names + removed from the bus peer tracking object while it is being enumerated the enumeration ends on the next invocation + of <function>sd_bus_track_next()</function> as <constant>NULL</constant> is returned.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>sd_bus_track_add_name()</function> and <function>sd_bus_track_add_sender()</function> + return 0 if the specified name has already been added to the bus peer tracking object before and positive if it + hasn't. On failure, they return a negative errno-style error code.</para> + + <para><function>sd_bus_track_remove_name()</function> and <function>sd_bus_track_remove_sender()</function> return + positive if the specified name was previously tracked by the bus peer tracking object and has now been removed. In + non-recursive mode, 0 is returned if the specified name was not being tracked yet. In recursive mode + <constant>-EUNATCH</constant> is returned in this case. On failure, they return a negative errno-style error + code.</para> + + <para><function>sd_bus_track_count()</function> returns the number of names currently being tracked, or 0 on + failure.</para> + + <para><function>sd_bus_track_count_name()</function> and <function>sd_bus_track_count_sender()</function> return + the current per-name counter for the specified name or the sender of the specified message. Zero is returned for + names that are not being tracked yet, a positive value for names added at least once. Larger values than 1 are only + returned in recursive mode. On failure, a negative errno-style error code is returned.</para> + + <para><function>sd_bus_track_contains()</function> returns the passed name if it exists in the bus peer tracking + object. On failure, and if the name has not been added yet <constant>NULL</constant> is returned.</para> + + <para><function>sd_bus_track_first()</function> and <function>sd_bus_track_next()</function> return the first/next + name contained in the bus peer tracking object, and <constant>NULL</constant> if the end of the enumeration is + reached and on error.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + + <varlistentry> + <term><constant>-EUNATCH</constant></term> + + <listitem><para><function>sd_bus_track_remove_name()</function> or + <function>sd_bus_track_remove_sender()</function> have been invoked for a name not previously added to the bus + peer object.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>Specified parameter is invalid.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para><function>sd_bus_track_add_name()</function> and the other calls described here are available as a shared library, + which can be compiled and linked to with the <constant>libsystemd</constant> <citerefentry + project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_track_new</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_track_new.xml b/man/sd_bus_track_new.xml new file mode 100644 index 0000000000..60e2e77f75 --- /dev/null +++ b/man/sd_bus_track_new.xml @@ -0,0 +1,263 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2016 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_bus_track_new"> + + <refentryinfo> + <title>sd_bus_track_new</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_track_new</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_track_new</refname> + <refname>sd_bus_track_ref</refname> + <refname>sd_bus_track_unref</refname> + <refname>sd_bus_track_unrefp</refname> + <refname>sd_bus_track_set_recursive</refname> + <refname>sd_bus_track_get_recursive</refname> + <refname>sd_bus_track_get_bus</refname> + <refname>sd_bus_track_get_userdata</refname> + <refname>sd_bus_track_set_userdata</refname> + + <refpurpose>Track bus peers</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_track_new</function></funcdef> + <paramdef>sd_bus* <parameter>bus</parameter></paramdef> + <paramdef>sd_bus_track** <parameter>ret</parameter></paramdef> + <paramdef>sd_bus_track_handler_t <parameter>handler</parameter></paramdef> + <paramdef>void* <parameter>userdata</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_bus_track *<function>sd_bus_track_ref</function></funcdef> + <paramdef>sd_bus_track *<parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_bus_track *<function>sd_bus_track_unref</function></funcdef> + <paramdef>sd_bus_track *<parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void <function>sd_bus_track_unrefp</function></funcdef> + <paramdef>sd_bus_track **<parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_get_recursive</function></funcdef> + <paramdef>sd_bus_track *<parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_set_recursive</function></funcdef> + <paramdef>sd_bus_track *<parameter>t</parameter></paramdef> + <paramdef>int <parameter>b</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_bus* <function>sd_bus_track_get_bus</function></funcdef> + <paramdef>sd_bus_track *<parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void* <function>sd_bus_track_get_userdata</function></funcdef> + <paramdef>sd_bus_track *<parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void* <function>sd_bus_track_set_userdata</function></funcdef> + <paramdef>sd_bus_track *<parameter>t</parameter></paramdef> + <paramdef>void *userdata</paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_track_new()</function> creates a new bus peer tracking object. The object is allocated for + the specified bus, and returned in the <parameter>*ret</parameter> parameter. After use, the object should be freed + again by dropping the acquired reference with <function>sd_bus_track_unref()</function> (see below). A bus peer + tracking object may be used to keep track of peers on a specific IPC bus, for cases where peers are making use of + one or more local objects, in order to control the lifecycle of the local objects and ensure they stay around as + long as the peers needing them are around, and unreferenced (and possibly destroyed) as soon as all relevant peers + have vanished. Each bus peer tracking object may be used to track zero, one or more peers add a time. References to + specific bus peers are added via + <citerefentry><refentrytitle>sd_bus_track_add_name</refentrytitle><manvolnum>3</manvolnum></citerefentry> or + <function>sd_bus_track_add_sender()</function>. They may be dropped again via + <function>sd_bus_track_remove_name()</function> and + <function>sd_bus_track_remove_sender()</function>. Alternatively, references on peers are removed automatically + when they disconnect from the bus. If non-NULL the <parameter>handler</parameter> may specify a function that is + invoked whenever the last reference is dropped, regardless whether the reference is dropped explicitly via + <function>sd_bus_track_remove_name()</function> or implicitly because the peer disconnected from the bus. The final + argument <parameter>userdata</parameter> may be used to attach a generic user data pointer to the object. This + pointer is passed to the handler callback when it is invoked.</para> + + <para><function>sd_bus_track_ref()</function> creates a new reference to a bus peer tracking object. This object + will not be destroyed until <function>sd_bus_track_unref()</function> has been called as many times plus once + more. Once the reference count has dropped to zero, the specified object cannot be used anymore, further calls to + <function>sd_bus_track_ref()</function> or <function>sd_bus_track_unref()</function> on the same object are + illegal.</para> + + <para><function>sd_bus_track_unref()</function> destroys a reference to a bus peer tracking object.</para> + + <para><function>sd_bus_track_unrefp()</function> is similar to <function>sd_bus_track_unref()</function> but takes + a pointer to a pointer to an <type>sd_bus_track</type> object. This call is useful in conjunction with GCC's and + LLVM's <ulink url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up Variable + Attribute</ulink>. Note that this function is defined as inline function.</para> + + <para><function>sd_bus_track_ref()</function>, <function>sd_bus_track_unref()</function> and + <function>sd_bus_track_unrefp()</function> execute no operation if the passed in bus peer tracking object is + <constant>NULL</constant>.</para> + + <para>Bus peer tracking objects may exist in two modes: by default they operate in non-recursive mode, but may + optionally be switched into recursive mode. If operating in the default non-recursive mode a peer is either tracked + or not tracked. In this mode invoking <function>sd_bus_track_add_name()</function> multiple times in a row for the + same peer is fully equivalent to calling it just once, as the call adds the peer to the set of tracked peers if + necessary, and executes no operation if the peer is already being tracked. A single invocation of + <function>sd_bus_track_remove_name()</function> removes the reference on the peer again, regardless how many times + <function>sd_bus_track_add_name()</function> was called before. If operating in recursive mode, the number of times + <function>sd_bus_track_add_name()</function> is invoked for the same peer name is counted and + <function>sd_bus_track_remove_name()</function> must be called the same number of times before the peer is not + tracked anymore, with the exception when the tracked peer vanishes from the bus, in which case the count is + irrelevant and the tracking of the specific peer is immediately + removed. <function>sd_bus_track_get_recursive()</function> may be used to determine whether the bus peer tracking + object is operating in recursive mode. <function>sd_bus_track_set_recursive()</function> may be used to enable or + disable recursive mode. By default a bus peer tracking object operates in non-recursive mode, and + <function>sd_bus_track_get_recursive()</function> for a newly allocated object hence returns a value equal to + zero. Use <function>sd_bus_track_set_recursive()</function> to enable recursive mode, right after allocation. It + takes a boolean argument to enable or disable recursive mode. Note that tracking objects for which + <function>sd_bus_track_add_name()</function> was already invoked at least once (and which hence track already one + or more peers) may not be switched from recursive to non-recursive mode anymore.</para> + + <para><function>sd_bus_track_get_bus()</function> returns the bus object the bus peer tracking object belongs + to. It returns the bus object initially passed to <function>sd_bus_track_new()</function> when the object was + allocated.</para> + + <para><function>sd_bus_track_get_userdata()</function> returns the generic user data pointer set on the bus peer + tracking object at the time of creation using <function>sd_bus_track_new()</function> or at a later time, using + <function>sd_bus_track_set_userdata()</function>.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>sd_bus_track_new()</function> and <function>sd_bus_track_set_recursive()</function> + return 0 or a positive integer. On failure, they return a negative errno-style error code.</para> + + <para><function>sd_bus_track_ref()</function> always returns the argument.</para> + + <para><function>sd_bus_track_unref()</function> always returns <constant>NULL</constant>.</para> + + <para><function>sd_bus_track_get_recursive()</function> returns 0 if non-recursive mode is selected (default), and + greater than 0 if recursive mode is selected. On failure a negative errno-style error code is returned.</para> + + <para><function>sd_bus_track_get_bus()</function> returns the bus object associated to the bus peer tracking + object.</para> + + <para><function>sd_bus_track_get_userdata()</function> returns the generic user data pointer associated with the + bus peer tracking object. <function>sd_bus_track_set_userdata()</function> returns the previous user data pointer + set.</para> + + </refsect1> + + <refsect1> + <title>Reference ownership</title> + + <para>The <function>sd_bus_track_new()</function> function creates a new object and the caller owns the sole + reference. When not needed anymore, this reference should be destroyed with + <function>sd_bus_track_unref()</function>. + </para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + + <varlistentry> + <term><constant>-EBUSY</constant></term> + + <listitem><para>Bus peers have already been added to the bus peer tracking object and + <function>sd_bus_track_set_recursive()</function> was called to change tracking mode.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>Specified parameter is invalid + (<constant>NULL</constant> in case of output + parameters).</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para><function>sd_bus_track_new()</function> and the other calls described here are available as a shared library, + which can be compiled and linked to with the <constant>libsystemd</constant> <citerefentry + project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry> + <citerefentry><refentrytitle>sd_bus_track_add_name</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_event_new.xml b/man/sd_event_new.xml index 2c23b00a8c..c0a5e98177 100644 --- a/man/sd_event_new.xml +++ b/man/sd_event_new.xml @@ -183,8 +183,9 @@ <refsect1> <title>Return Value</title> - <para>On success, <function>sd_event_new()</function> and - <function>sd_event_default()</function> return 0 or a positive + <para>On success, <function>sd_event_new()</function>, + <function>sd_event_default()</function> and + <function>sd_event_get_tid()</function> return 0 or a positive integer. On failure, they return a negative errno-style error code. <function>sd_event_ref()</function> always returns a pointer to the event loop object passed diff --git a/man/sd_event_source_set_priority.xml b/man/sd_event_source_set_priority.xml index 8c9b39fe5e..b6bab6d316 100644 --- a/man/sd_event_source_set_priority.xml +++ b/man/sd_event_source_set_priority.xml @@ -57,9 +57,9 @@ <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> <funcsynopsisinfo><token>enum</token> { - <constant>SD_EVENT_SOURCE_IMPORTANT</constant> = -100, - <constant>SD_EVENT_SOURCE_NORMAL</constant> = 0, - <constant>SD_EVENT_SOURCE_IDLE</constant> = 100, + <constant>SD_EVENT_PRIORITY_IMPORTANT</constant> = -100, + <constant>SD_EVENT_PRIORITY_NORMAL</constant> = 0, + <constant>SD_EVENT_PRIORITY_IDLE</constant> = 100, };</funcsynopsisinfo> <funcprototype> @@ -115,7 +115,7 @@ reliable. However, it is guaranteed that if events are seen on multiple same-priority event sources at the same time, each one is not dispatched again until all others have been dispatched - once. This behaviour guarantees that within each priority + once. This behavior guarantees that within each priority particular event sources do not starve or dominate the event loop.</para> diff --git a/man/sd_id128_get_machine.xml b/man/sd_id128_get_machine.xml index 2ad1f8f728..9a86c24aed 100644 --- a/man/sd_id128_get_machine.xml +++ b/man/sd_id128_get_machine.xml @@ -45,6 +45,7 @@ <refnamediv> <refname>sd_id128_get_machine</refname> <refname>sd_id128_get_boot</refname> + <refname>sd_id128_get_invocation</refname> <refpurpose>Retrieve 128-bit IDs</refpurpose> </refnamediv> @@ -62,6 +63,11 @@ <paramdef>sd_id128_t *<parameter>ret</parameter></paramdef> </funcprototype> + <funcprototype> + <funcdef>int <function>sd_id128_get_invocation</function></funcdef> + <paramdef>sd_id128_t *<parameter>ret</parameter></paramdef> + </funcprototype> + </funcsynopsis> </refsynopsisdiv> @@ -83,11 +89,15 @@ for more information. This function also internally caches the returned ID to make this call a cheap operation.</para> - <para>Note that <function>sd_id128_get_boot()</function> always - returns a UUID v4 compatible ID. - <function>sd_id128_get_machine()</function> will also return a - UUID v4-compatible ID on new installations but might not on older. - It is possible to convert the machine ID into a UUID v4-compatible + <para><function>sd_id128_get_invocation()</function> returns the invocation ID of the currently executed + service. In its current implementation, this reads and parses the <varname>$INVOCATION_ID</varname> environment + variable that the service manager sets when activating a service, see + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. The + ID is cached internally. In future a different mechanism to determine the invocation ID may be added.</para> + + <para>Note that <function>sd_id128_get_boot()</function> and <function>sd_id128_get_invocation()</function> always + return UUID v4 compatible IDs. <function>sd_id128_get_machine()</function> will also return a UUID v4-compatible + ID on new installations but might not on older. It is possible to convert the machine ID into a UUID v4-compatible one. For more information, see <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> @@ -107,11 +117,10 @@ <refsect1> <title>Notes</title> - <para>The <function>sd_id128_get_machine()</function> and - <function>sd_id128_get_boot()</function> interfaces are available - as a shared library, which can be compiled and linked to with the - <literal>libsystemd</literal> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> + <para>The <function>sd_id128_get_machine()</function>, <function>sd_id128_get_boot()</function> and + <function>sd_id128_get_invocation()</function> interfaces are available as a shared library, which can be compiled + and linked to with the <literal>libsystemd</literal> <citerefentry + project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para> </refsect1> <refsect1> @@ -121,8 +130,9 @@ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_id128_randomize</refentrytitle><manvolnum>3</manvolnum></citerefentry> + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_id128_randomize</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/sd_is_fifo.xml b/man/sd_is_fifo.xml index 627cb87aaf..7ff02cbfec 100644 --- a/man/sd_is_fifo.xml +++ b/man/sd_is_fifo.xml @@ -117,10 +117,10 @@ whether the specified file descriptor refers to a socket. If the <parameter>family</parameter> parameter is not <constant>AF_UNSPEC</constant>, it is checked whether the socket - is of the specified family (AF_UNIX, <constant>AF_INET</constant>, - ...). If the <parameter>type</parameter> parameter is not 0, it is - checked whether the socket is of the specified type - (<constant>SOCK_STREAM</constant>, + is of the specified family (<constant>AF_UNIX</constant>, + <constant>AF_INET</constant>, ...). If the <parameter>type</parameter> + parameter is not 0, it is checked whether the socket is of the + specified type (<constant>SOCK_STREAM</constant>, <constant>SOCK_DGRAM</constant>, ...). If the <parameter>listening</parameter> parameter is positive, it is checked whether the socket is in accepting mode, i.e. diff --git a/man/sd_journal_add_match.xml b/man/sd_journal_add_match.xml index 98415d53fd..7c64329aed 100644 --- a/man/sd_journal_add_match.xml +++ b/man/sd_journal_add_match.xml @@ -168,6 +168,9 @@ <refsect1> <title>Notes</title> + <para>All functions listed here are thread-agnostic and only a single thread may operate + on a given <structname>sd_journal</structname> object.</para> + <para>The <function>sd_journal_add_match()</function>, <function>sd_journal_add_disjunction()</function>, <function>sd_journal_add_conjunction()</function> and diff --git a/man/sd_journal_enumerate_fields.xml b/man/sd_journal_enumerate_fields.xml index fa5884106b..bc2c21ed4b 100644 --- a/man/sd_journal_enumerate_fields.xml +++ b/man/sd_journal_enumerate_fields.xml @@ -110,6 +110,9 @@ <refsect1> <title>Notes</title> + <para>All functions listed here are thread-agnostic and only a single thread may operate + on a given <structname>sd_journal</structname> object.</para> + <para>The <function>sd_journal_enumerate_fields()</function> and <function>sd_journal_restart_fields()</function> interfaces are available as a shared library, which can be compiled and linked to with the <constant>libsystemd</constant> <citerefentry diff --git a/man/sd_journal_get_catalog.xml b/man/sd_journal_get_catalog.xml index c19eb11b20..35ec46f63e 100644 --- a/man/sd_journal_get_catalog.xml +++ b/man/sd_journal_get_catalog.xml @@ -112,6 +112,10 @@ <refsect1> <title>Notes</title> + <para>Function <function>sd_journal_get_catalog()</function> is thread-agnostic and only a + single thread may operate on a given <structname>sd_journal</structname> object. Function + <function>sd_journal_get_catalog_for_message_id() is thread-safe.</function></para> + <para>The <function>sd_journal_get_catalog()</function> and <function>sd_journal_get_catalog_for_message_id()</function> interfaces are available as a shared library, which can be diff --git a/man/sd_journal_get_cursor.xml b/man/sd_journal_get_cursor.xml index a400d8b1b5..b7aa05f8b2 100644 --- a/man/sd_journal_get_cursor.xml +++ b/man/sd_journal_get_cursor.xml @@ -122,6 +122,9 @@ <refsect1> <title>Notes</title> + <para>All functions listed here are thread-agnostic and only a single thread may operate + on a given <structname>sd_journal</structname> object.</para> + <para>The <function>sd_journal_get_cursor()</function> and <function>sd_journal_test_cursor()</function> interfaces are available as a shared library, which can be compiled and linked to diff --git a/man/sd_journal_get_cutoff_realtime_usec.xml b/man/sd_journal_get_cutoff_realtime_usec.xml index 23e7cc65e8..0950e11b44 100644 --- a/man/sd_journal_get_cutoff_realtime_usec.xml +++ b/man/sd_journal_get_cutoff_realtime_usec.xml @@ -120,6 +120,9 @@ <refsect1> <title>Notes</title> + <para>All functions listed here are thread-agnostic and only a single thread may operate + on a given <structname>sd_journal</structname> object.</para> + <para>The <function>sd_journal_get_cutoff_realtime_usec()</function> and <function>sd_journal_get_cutoff_monotonic_usec()</function> diff --git a/man/sd_journal_get_usage.xml b/man/sd_journal_get_usage.xml index 72c804d834..06b0ff534d 100644 --- a/man/sd_journal_get_usage.xml +++ b/man/sd_journal_get_usage.xml @@ -80,6 +80,9 @@ <refsect1> <title>Notes</title> + <para>All functions listed here are thread-agnostic and only a single thread may operate + on a given <structname>sd_journal</structname> object.</para> + <para>The <function>sd_journal_get_usage()</function> interface is available as a shared library, which can be compiled and linked to with the diff --git a/man/sd_journal_has_runtime_files.xml b/man/sd_journal_has_runtime_files.xml index 237e649206..3f6d56ca77 100644 --- a/man/sd_journal_has_runtime_files.xml +++ b/man/sd_journal_has_runtime_files.xml @@ -86,6 +86,18 @@ </refsect1> <refsect1> + <title>Notes</title> + + <para>All functions listed here are thread-agnostic and only a single thread may operate + on a given <structname>sd_journal</structname> object.</para> + + <para>Functions listed here are available as a shared library, which can be compiled and linked + to with the <constant>libsystemd</constant> <citerefentry + project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> <title>See Also</title> <para> <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry> diff --git a/man/sd_journal_next.xml b/man/sd_journal_next.xml index 115fe26661..7c385de260 100644 --- a/man/sd_journal_next.xml +++ b/man/sd_journal_next.xml @@ -146,6 +146,9 @@ <refsect1> <title>Notes</title> + <para>All functions listed here are thread-agnostic and only a single thread may operate + on a given <structname>sd_journal</structname> object.</para> + <para>The <function>sd_journal_next()</function>, <function>sd_journal_previous()</function>, <function>sd_journal_next_skip()</function> and diff --git a/man/sd_journal_open.xml b/man/sd_journal_open.xml index 153af2387f..25b3048f2e 100644 --- a/man/sd_journal_open.xml +++ b/man/sd_journal_open.xml @@ -129,10 +129,13 @@ <para><function>sd_journal_open_directory()</function> is similar to <function>sd_journal_open()</function> but takes an absolute directory path as argument. All journal files in this directory will be opened and interleaved - automatically. This call also takes a flags argument. The only flags parameter accepted by this call is - <constant>SD_JOURNAL_OS_ROOT</constant>. If specified, the journal files are searched below the usual - <filename>/var/log/journal</filename> and <filename>/run/log/journal</filename> relative to the specified path, - instead of directly beneath it.</para> + automatically. This call also takes a flags argument. The flags parameters accepted by this call are + <constant>SD_JOURNAL_OS_ROOT</constant>, <constant>SD_JOURNAL_SYSTEM</constant>, and + <constant>SD_JOURNAL_CURRENT_USER</constant>. If <constant>SD_JOURNAL_OS_ROOT</constant> is specified, journal + files are searched for below the usual <filename>/var/log/journal</filename> and + <filename>/run/log/journal</filename> relative to the specified path, instead of directly beneath it. + The other two flags limit which files are opened, the same as for <function>sd_journal_open()</function>. + </para> <para><function>sd_journal_open_directory_fd()</function> is similar to <function>sd_journal_open_directory()</function>, but takes a file descriptor referencing a directory in the file @@ -205,6 +208,9 @@ <refsect1> <title>Notes</title> + <para>All functions listed here are thread-agnostic and only a single thread may operate + on a given <structname>sd_journal</structname> object.</para> + <para>The <function>sd_journal_open()</function>, <function>sd_journal_open_directory()</function> and <function>sd_journal_close()</function> interfaces are available diff --git a/man/sd_journal_print.xml b/man/sd_journal_print.xml index 76542527fc..2d8dd635aa 100644 --- a/man/sd_journal_print.xml +++ b/man/sd_journal_print.xml @@ -201,9 +201,10 @@ sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid( </refsect1> <refsect1> - <title>Async signal safety</title> - <para><function>sd_journal_sendv()</function> is "async signal - safe" in the meaning of + <title>Thread safety</title> + <para>All functions listed here are thread-safe and may be called in parallel from multiple threads.</para> + + <para><function>sd_journal_sendv()</function> is "async signal safe" in the meaning of <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>. </para> diff --git a/man/sd_journal_query_unique.xml b/man/sd_journal_query_unique.xml index dbff55c105..d7a41a039c 100644 --- a/man/sd_journal_query_unique.xml +++ b/man/sd_journal_query_unique.xml @@ -150,6 +150,9 @@ <refsect1> <title>Notes</title> + <para>All functions listed here are thread-agnostic and only a single thread may operate + on a given <structname>sd_journal</structname> object.</para> + <para>The <function>sd_journal_query_unique()</function>, <function>sd_journal_enumerate_unique()</function> and <function>sd_journal_restart_unique()</function> interfaces are diff --git a/man/sd_journal_seek_head.xml b/man/sd_journal_seek_head.xml index d74c2d5bbc..985073496c 100644 --- a/man/sd_journal_seek_head.xml +++ b/man/sd_journal_seek_head.xml @@ -144,6 +144,9 @@ <refsect1> <title>Notes</title> + <para>All functions listed here are thread-agnostic and only a single thread may operate + on a given <structname>sd_journal</structname> object.</para> + <para>The <function>sd_journal_seek_head()</function>, <function>sd_journal_seek_tail()</function>, <function>sd_journal_seek_monotonic_usec()</function>, diff --git a/man/sd_journal_stream_fd.xml b/man/sd_journal_stream_fd.xml index 2ea7731b48..db88eba1bc 100644 --- a/man/sd_journal_stream_fd.xml +++ b/man/sd_journal_stream_fd.xml @@ -104,6 +104,10 @@ <refsect1> <title>Notes</title> + <para>Function <function>sd_journal_stream_fd()</function> is thread-safe and may be called + from multiple threads. All calls will return the same file descriptor, although temporarily + multiple file descriptors may be open.</para> + <para>The <function>sd_journal_stream_fd()</function> interface is available as a shared library, which can be compiled and linked to with the diff --git a/man/sd_notify.xml b/man/sd_notify.xml index 025fbec6c1..94542b80b8 100644 --- a/man/sd_notify.xml +++ b/man/sd_notify.xml @@ -205,28 +205,25 @@ <varlistentry> <term>FDSTORE=1</term> - <listitem><para>Stores additional file descriptors in the - service manager. File descriptors sent this way will be - maintained per-service by the service manager and be passed - again using the usual file descriptor passing logic on the - next invocation of the service (see - <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>). - This is useful for implementing service restart schemes where - services serialize their state to <filename>/run</filename>, - push their file descriptors to the system manager, and are - then restarted, retrieving their state again via socket - passing and <filename>/run</filename>. Note that the service - manager will accept messages for a service only if - <varname>FileDescriptorStoreMax=</varname> is set to non-zero - for it (defaults to zero). See - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. Multiple arrays of file descriptors may be sent - in separate messages, in which case the arrays are combined. - Note that the service manager removes duplicate file - descriptors before passing them to the service. Use - <function>sd_pid_notify_with_fds()</function> to send messages - with <literal>FDSTORE=1</literal>, see - below.</para></listitem> + <listitem><para>Stores additional file descriptors in the service manager. File + descriptors sent this way will be maintained per-service by the service manager + and will be passed again using the usual file descriptor passing logic on the next + invocation of the service, see + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + This is useful for implementing service restart schemes where services serialize + their state to <filename>/run</filename>, push their file descriptors to the + system manager, and are then restarted, retrieving their state again via socket + passing and <filename>/run</filename>. Note that the service manager will accept + messages for a service only if <varname>FileDescriptorStoreMax=</varname> is set + to non-zero for it (defaults to zero, see + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + File descriptors must be pollable, see + <citerefentry><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>. + Multiple arrays of file descriptors may be sent in separate messages, in which + case the arrays are combined. Note that the service manager removes duplicate + file descriptors before passing them to the service. Use + <function>sd_pid_notify_with_fds()</function> to send messages with + <literal>FDSTORE=1</literal>, see below.</para></listitem> </varlistentry> <varlistentry> diff --git a/man/standard-options.xml b/man/standard-options.xml index f214463392..f718451a1b 100644 --- a/man/standard-options.xml +++ b/man/standard-options.xml @@ -28,6 +28,12 @@ </listitem> </varlistentry> + <varlistentry id='no-ask-password'> + <term><option>--no-ask-password</option></term> + + <listitem><para>Do not query the user for authentication for privileged operations.</para></listitem> + </varlistentry> + <varlistentry id='no-legend'> <term><option>--no-legend</option></term> diff --git a/man/systemctl.xml b/man/systemctl.xml index e7880d24f7..dfa00e0c03 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -156,6 +156,10 @@ <para>To list all units installed in the file system, use the <command>list-unit-files</command> command instead.</para> + + <para>When listing units with <command>list-dependencies</command>, recursively show + dependencies of all dependent units (by default only dependencies of target units are + shown).</para> </listitem> </varlistentry> @@ -229,6 +233,8 @@ of <command>status</command>, <command>list-units</command>, <command>list-jobs</command>, and <command>list-timers</command>.</para> + <para>Also, show installation targets in the output of + <command>is-enabled</command>.</para> </listitem> </varlistentry> @@ -302,7 +308,7 @@ <para><literal>ignore-requirements</literal> is similar to <literal>ignore-dependencies</literal>, but only causes the requirement dependencies to be ignored, the ordering - dependencies will still be honoured.</para> + dependencies will still be honored.</para> </listitem> </varlistentry> @@ -359,7 +365,20 @@ to finish. If this is not specified, the job will be verified, enqueued and <command>systemctl</command> will wait until the unit's start-up is completed. By passing this - argument, it is only verified and enqueued.</para> + argument, it is only verified and enqueued. This option may not be + combined with <option>--wait</option>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--wait</option></term> + + <listitem> + <para>Synchronously wait for started units to terminate again. + This option may not be combined with <option>--no-block</option>. + Note that this will wait forever if any given unit never terminates + (by itself or by getting stopped explicitly); particularly services + which use <literal>RemainAfterExit=yes</literal>.</para> </listitem> </varlistentry> @@ -527,8 +546,10 @@ <listitem> <para>When used with <command>enable</command>/<command>disable</command>/<command>is-enabled</command> - (and related commands), use an alternate root path when - looking for unit files.</para> + (and related commands), use the specified root path when looking for unit + files. If this option is present, <command>systemctl</command> will operate on + the file system directly, instead of communicating with the <command>systemd</command> + daemon to carry out changes.</para> </listitem> </varlistentry> @@ -609,7 +630,7 @@ <listitem> <para>When used with <command>list-dependencies</command>, - <command>list-units</command> or <command>list-machines</command>, the + <command>list-units</command> or <command>list-machines</command>, the output is printed as a list instead of a tree, and the bullet circles are omitted.</para> </listitem> @@ -638,13 +659,13 @@ <term><command>list-units <optional><replaceable>PATTERN</replaceable>...</optional></command></term> <listitem> - <para>List units that <command>systemd</command> has loaded. This includes units that - are either referenced directly or through a dependency, or units that were active in the - past and have failed. By default only units which are active, have pending jobs, or have - failed are shown; this can be changed with option <option>--all</option>. If one or more - <replaceable>PATTERN</replaceable>s are specified, only units matching one of them are - shown. The units that are shown are additionally filtered by <option>--type=</option> - and <option>--state=</option> if those options are specified.</para> + <para>List units that <command>systemd</command> currently has in memory. This includes units that are + either referenced directly or through a dependency, units that are pinned by applications programmatically, + or units that were active in the past and have failed. By default only units which are active, have pending + jobs, or have failed are shown; this can be changed with option <option>--all</option>. If one or more + <replaceable>PATTERN</replaceable>s are specified, only units matching one of them are shown. The units + that are shown are additionally filtered by <option>--type=</option> and <option>--state=</option> if those + options are specified.</para> <para>This is the default command.</para> </listitem> @@ -654,9 +675,8 @@ <term><command>list-sockets <optional><replaceable>PATTERN</replaceable>...</optional></command></term> <listitem> - <para>List socket units ordered by listening address. - If one or more <replaceable>PATTERN</replaceable>s are - specified, only socket units matching one of them are + <para>List socket units currently in memory, ordered by listening address. If one or more + <replaceable>PATTERN</replaceable>s are specified, only socket units matching one of them are shown. Produces output similar to <programlisting> LISTEN UNIT ACTIVATES @@ -670,8 +690,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service is not suitable for programmatic consumption. </para> - <para>See also the options <option>--show-types</option>, - <option>--all</option>, and <option>--state=</option>.</para> + <para>Also see <option>--show-types</option>, <option>--all</option>, and <option>--state=</option>.</para> </listitem> </varlistentry> @@ -679,13 +698,11 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <term><command>list-timers <optional><replaceable>PATTERN</replaceable>...</optional></command></term> <listitem> - <para>List timer units ordered by the time they elapse - next. If one or more <replaceable>PATTERN</replaceable>s - are specified, only units matching one of them are shown. + <para>List timer units currently in memory, ordered by the time they elapse next. If one or more + <replaceable>PATTERN</replaceable>s are specified, only units matching one of them are shown. </para> - <para>See also the options <option>--all</option> and - <option>--state=</option>.</para> + <para>Also see <option>--all</option> and <option>--state=</option>.</para> </listitem> </varlistentry> @@ -696,8 +713,8 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <para>Start (activate) one or more units specified on the command line.</para> - <para>Note that glob patterns operate on the set of primary names of currently loaded units. Units which - are not active and are not in a failed state usually are not loaded, and will not be matched by any + <para>Note that glob patterns operate on the set of primary names of units currently in memory. Units which + are not active and are not in a failed state usually are not in memory, and will not be matched by any pattern. In addition, in case of instantiated units, systemd is often unaware of the instance name until the instance has been started. Therefore, using glob patterns with <command>start</command> has limited usefulness. Also, secondary alias names of units are not considered.</para> @@ -860,8 +877,8 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <para>Show properties of one or more units, jobs, or the manager itself. If no argument is specified, properties of the manager will be shown. If a unit name is specified, - properties of the unit is shown, and if a job ID is - specified, properties of the job is shown. By default, empty + properties of the unit are shown, and if a job ID is + specified, properties of the job are shown. By default, empty properties are suppressed. Use <option>--all</option> to show those too. To select specific properties to show, use <option>--property=</option>. This command is intended to be @@ -877,7 +894,11 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <para>Show backing files of one or more units. Prints the "fragment" and "drop-ins" (source files) of units. Each file is preceded by a comment which includes the file - name.</para> + name. Note that this shows the contents of the backing files + on disk, which may not match the system manager's + understanding of these units if any unit files were + updated on disk and the <command>daemon-reload</command> + command wasn't issued since.</para> </listitem> </varlistentry> <varlistentry> @@ -993,7 +1014,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service desired, combine this command with the <option>--now</option> switch, or invoke <command>start</command> with appropriate arguments later. Note that in case of unit instance enablement (i.e. enablement of units of the form <filename>foo@bar.service</filename>), symlinks named the same as instances are created in the - unit configuration diectory, however they point to the single template unit file they are instantiated + unit configuration directory, however they point to the single template unit file they are instantiated from.</para> <para>This command expects either valid unit names (in which case various unit file directories are @@ -1069,8 +1090,8 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <listitem> <para>Reenable one or more units, as specified on the command line. This is a combination of <command>disable</command> and <command>enable</command> and is useful to reset the symlinks a unit file is - enabled with to the defaults configured in its <literal>[Install]</literal> section. This commands expects - a unit uname only, it does not accept paths to unit files.</para> + enabled with to the defaults configured in its <literal>[Install]</literal> section. This command expects + a unit name only, it does not accept paths to unit files.</para> </listitem> </varlistentry> @@ -1088,7 +1109,8 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service enabled and disabled, or only enabled, or only disabled.</para> <para>If the unit carries no install information, it will be silently ignored - by this command.</para> + by this command. <replaceable>NAME</replaceable> must be the real unit name, + any alias names are ignored silently.</para> <para>For more information on the preset policy format, see <citerefentry><refentrytitle>systemd.preset</refentrytitle><manvolnum>5</manvolnum></citerefentry>. @@ -1120,6 +1142,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service exit code of 0 if at least one is enabled, non-zero otherwise. Prints the current enable status (see table). To suppress this output, use <option>--quiet</option>. + To show installation targets, use <option>--full</option>. </para> <table> @@ -1242,7 +1265,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <literal>foo.service.d/</literal> with all their contained files are removed, both below the persistent and runtime configuration directories (i.e. below <filename>/etc/systemd/system</filename> and <filename>/run/systemd/system</filename>); if the unit file has a vendor-supplied version (i.e. a unit file - located below <filename>/usr</filename>) any matching peristent or runtime unit file that overrides it is + located below <filename>/usr</filename>) any matching persistent or runtime unit file that overrides it is removed, too. Note that if a unit file has no vendor-supplied version (i.e. is only defined below <filename>/etc/systemd/system</filename> or <filename>/run/systemd/system</filename>, but not in a unit file stored below <filename>/usr</filename>), then it is not removed. Also, if a unit is masked, it is @@ -1676,20 +1699,15 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <term><command>switch-root <replaceable>ROOT</replaceable> <optional><replaceable>INIT</replaceable></optional></command></term> <listitem> - <para>Switches to a different root directory and executes a - new system manager process below it. This is intended for - usage in initial RAM disks ("initrd"), and will transition - from the initrd's system manager process (a.k.a. "init" - process) to the main system manager process. This call takes two - arguments: the directory that is to become the new root directory, and - the path to the new system manager binary below it to - execute as PID 1. If the latter is omitted or the empty - string, a systemd binary will automatically be searched for - and used as init. If the system manager path is omitted or - equal to the empty string, the state of the initrd's system - manager process is passed to the main system manager, which - allows later introspection of the state of the services - involved in the initrd boot.</para> + <para>Switches to a different root directory and executes a new system manager process below it. This is + intended for usage in initial RAM disks ("initrd"), and will transition from the initrd's system manager + process (a.k.a. "init" process) to the main system manager process which is loaded from the actual host + volume. This call takes two arguments: the directory that is to become the new root directory, and the path + to the new system manager binary below it to execute as PID 1. If the latter is omitted or the empty + string, a systemd binary will automatically be searched for and used as init. If the system manager path is + omitted, equal to the empty string or identical to the path to the systemd binary, the state of the + initrd's system manager process is passed to the main system manager, which allows later introspection of + the state of the services involved in the initrd boot phase.</para> </listitem> </varlistentry> @@ -1746,7 +1764,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service are equivalent to: <programlisting># systemctl status dev-sda.device # systemctl status home.mount</programlisting> - In the second case, shell-style globs will be matched against the primary names of all currently loaded units; + In the second case, shell-style globs will be matched against the primary names of all units currently in memory; literal unit names, with or without a suffix, will be treated as in the first case. This means that literal unit names always refer to exactly one unit, but globs may match zero units and this is not considered an error.</para> @@ -1758,11 +1776,11 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <literal>[]</literal> may be used. See <citerefentry project='man-pages'><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry> for more details. The patterns are matched against the primary names of - currently loaded units, and patterns which do not match anything + units currently in memory, and patterns which do not match anything are silently skipped. For example: <programlisting># systemctl stop sshd@*.service</programlisting> will stop all <filename>sshd@.service</filename> instances. Note that alias names of units, and units that aren't - loaded are not considered for glob expansion. + in memory are not considered for glob expansion. </para> <para>For unit file commands, the specified <replaceable>NAME</replaceable> should be the name of the unit file @@ -1804,6 +1822,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service </variablelist> <xi:include href="less-variables.xml" xpointer="pager"/> <xi:include href="less-variables.xml" xpointer="less"/> + <xi:include href="less-variables.xml" xpointer="lesscharset"/> </refsect1> <refsect1> diff --git a/man/systemd-analyze.xml b/man/systemd-analyze.xml index bc37765dff..8fa7cd3329 100644 --- a/man/systemd-analyze.xml +++ b/man/systemd-analyze.xml @@ -181,14 +181,15 @@ <option>--log-target=</option>, described in <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para> - <para><command>systemd-analyze verify</command> will load unit - files and print warnings if any errors are detected. Files - specified on the command line will be loaded, but also any other - units referenced by them. This command works by prepending the - directories for all command line arguments at the beginning of the - unit load path, which means that all units files found in those - directories will be used in preference to the unit files found in - the standard locations, even if not listed explicitly.</para> + <para><command>systemd-analyze verify</command> will load unit files and print + warnings if any errors are detected. Files specified on the command line will be + loaded, but also any other units referenced by them. The full unit search path is + formed by combining the directories for all command line arguments, and the usual unit + load paths (variable <varname>$SYSTEMD_UNIT_PATH</varname> is supported, and may be + used to replace or augment the compiled in set of unit load paths; see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + All units files present in the directories containing the command line arguments will + be used in preference to the other paths.</para> <para>If no command is passed, <command>systemd-analyze time</command> is implied.</para> diff --git a/man/systemd-coredump.xml b/man/systemd-coredump.xml index a28dc62e5a..4a1bc8b296 100644 --- a/man/systemd-coredump.xml +++ b/man/systemd-coredump.xml @@ -107,7 +107,7 @@ <citerefentry><refentrytitle>systemd-sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>. </para> - <para>The behaviour of <command>systemd-coredump</command> itself is configured through the configuration file + <para>The behavior of <command>systemd-coredump</command> itself is configured through the configuration file <filename>/etc/systemd/coredump.conf</filename> and corresponding snippets <filename>/etc/systemd/coredump.conf.d/*.conf</filename>, see <citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. A new diff --git a/man/systemd-detect-virt.xml b/man/systemd-detect-virt.xml index 2b7f4e69ab..996c2fa256 100644 --- a/man/systemd-detect-virt.xml +++ b/man/systemd-detect-virt.xml @@ -50,7 +50,8 @@ <refsynopsisdiv> <cmdsynopsis> - <command>systemd-detect-virt <arg choice="opt" rep="repeat">OPTIONS</arg></command> + <command>systemd-detect-virt</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> </cmdsynopsis> </refsynopsisdiv> @@ -88,7 +89,7 @@ </thead> <tbody> <row> - <entry valign="top" morerows="9">VM</entry> + <entry valign="top" morerows="10">VM</entry> <entry><varname>qemu</varname></entry> <entry>QEMU software virtualization</entry> </row> @@ -138,6 +139,11 @@ <entry>Parallels Desktop, Parallels Server</entry> </row> + <row> + <entry><varname>bhyve</varname></entry> + <entry>bhyve, FreeBSD hypervisor</entry> + </row> + <row> <entry valign="top" morerows="5">Container</entry> <entry><varname>openvz</varname></entry> @@ -213,6 +219,16 @@ </varlistentry> <varlistentry> + <term><option>--private-users</option></term> + + <listitem><para>Detect whether invoked in a user namespace. In this mode, no + output is written, but the return value indicates whether the process was invoked + inside of a user namespace or not. See + <citerefentry project='man-pages'><refentrytitle>user_namespaces</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for more information.</para></listitem> + </varlistentry> + + <varlistentry> <term><option>-q</option></term> <term><option>--quiet</option></term> @@ -238,7 +254,8 @@ <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry> + <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>namespaces</refentrytitle><manvolnum>7</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/systemd-escape.xml b/man/systemd-escape.xml index dbb3869a24..5e95e22536 100644 --- a/man/systemd-escape.xml +++ b/man/systemd-escape.xml @@ -97,7 +97,7 @@ <listitem><para>Inserts the escaped strings in a unit name template. Takes a unit name template such as - <filename>foobar@.service</filename> May not be used in + <filename>foobar@.service</filename>. May not be used in conjunction with <option>--suffix=</option>, <option>--unescape</option> or <option>--mangle</option>.</para></listitem> @@ -108,9 +108,10 @@ <term><option>-p</option></term> <listitem><para>When escaping or unescaping a string, assume - it refers to a file system path. This enables special - processing of the initial <literal>/</literal> of the - path.</para></listitem> + it refers to a file system path. This eliminates leading, + trailing or duplicate <literal>/</literal> characters + and rejects <literal>.</literal> and <literal>..</literal> + path components.</para></listitem> </varlistentry> <varlistentry> @@ -143,7 +144,7 @@ <refsect1> <title>Examples</title> - <para>Escape a single string:</para> + <para>To escape a single string:</para> <programlisting>$ systemd-escape 'Hallöchen, Meister' Hall\xc3\xb6chen\x2c\x20Meister</programlisting> @@ -155,7 +156,7 @@ Hallöchen, Meister</programlisting> <programlisting>$ systemd-escape -p --suffix=mount "/tmp//waldi/foobar/" tmp-waldi-foobar.mount</programlisting> - <para>To generate instance names of three strings</para> + <para>To generate instance names of three strings:</para> <programlisting>$ systemd-escape --template=systemd-nspawn@.service 'My Container 1' 'containerb' 'container/III' systemd-nspawn@My\x20Container\x201.service systemd-nspawn@containerb.service systemd-nspawn@container-III.service</programlisting> </refsect1> diff --git a/man/systemd-gpt-auto-generator.xml b/man/systemd-gpt-auto-generator.xml index e890c4dce2..d26206710f 100644 --- a/man/systemd-gpt-auto-generator.xml +++ b/man/systemd-gpt-auto-generator.xml @@ -137,6 +137,11 @@ <entry>Swap</entry> <entry>All swap partitions located on the disk the root partition is located on are enabled.</entry> </row> + <row> + <entry>c12a7328-f81f-11d2-ba4b-00a0c93ec93b</entry> + <entry>EFI System Partition (ESP)</entry> + <entry>The first ESP located on the disk the root partition is located on is mounted to <filename>/boot</filename> or <filename>/efi</filename>, see below.</entry> + </row> </tbody> </tgroup> </table> @@ -150,16 +155,14 @@ <filename>/etc/crypttab</filename> with a different device mapper device name.</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>Mount and automount units for the EFI System Partition (ESP) are generated on EFI systems. The ESP is mounted + to <filename>/boot</filename>, unless a mount point directory <filename>/efi</filename> exists, in which case it is + mounted there. Since this generator creates an automount unit, the mount will only be activated on-demand, when + accessed. On systems where <filename>/boot</filename> (or <filename>/efi</filename> if it exists) is an explicitly + configured mount (for example, listed in <citerefentry + project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>) or where the + <filename>/boot</filename> (or <filename>/efi</filename>) mount point is non-empty, no mount units are + generated.</para> <para>When using this generator in conjunction with btrfs file systems, make sure to set the correct default subvolumes on them, diff --git a/man/systemd-inhibit.xml b/man/systemd-inhibit.xml index 9d85908f97..ce169960d8 100644 --- a/man/systemd-inhibit.xml +++ b/man/systemd-inhibit.xml @@ -61,7 +61,7 @@ <title>Description</title> <para><command>systemd-inhibit</command> may be used to execute a - program with a shutdown, sleep or idle inhibitor lock taken. The + program with a shutdown, sleep, or idle inhibitor lock taken. The lock will be acquired before the specified command line is executed and released afterwards.</para> diff --git a/man/systemd-journal-gatewayd.service.xml b/man/systemd-journal-gatewayd.service.xml index 9ed85c3950..2cb114f6e3 100644 --- a/man/systemd-journal-gatewayd.service.xml +++ b/man/systemd-journal-gatewayd.service.xml @@ -100,6 +100,16 @@ with <option>--cert=</option>.</para></listitem> </varlistentry> + <varlistentry> + <term><option>-D <replaceable>DIR</replaceable></option></term> + <term><option>--directory=<replaceable>DIR</replaceable></option></term> + + <listitem><para>Takes a directory path as argument. If + specified, <command>systemd-journal-gatewayd</command> will serve the + specified journal directory <replaceable>DIR</replaceable> instead of + the default runtime and system journal paths.</para></listitem> + </varlistentry> + <xi:include href="standard-options.xml" xpointer="help" /> <xi:include href="standard-options.xml" xpointer="version" /> </variablelist> diff --git a/man/systemd-journal-remote.xml b/man/systemd-journal-remote.xml index 3899f175d4..ee2d5c2486 100644 --- a/man/systemd-journal-remote.xml +++ b/man/systemd-journal-remote.xml @@ -121,8 +121,8 @@ <replaceable>ADDRESS</replaceable>. This URL should refer to the root of a remote <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry> - instance (e.g. <ulink>http://some.host:19531/</ulink> or - <ulink>https://some.host:19531/</ulink>).</para></listitem> + instance, e.g. http://some.host:19531/ or + https://some.host:19531/.</para></listitem> </varlistentry> </variablelist> @@ -250,20 +250,19 @@ </varlistentry> <varlistentry> - <term><option>--compress</option></term> - <term><option>--no-compress</option></term> + <term><option>--compress</option> [<replaceable>BOOL</replaceable>]</term> - <listitem><para>Compress or not, respectively, the data in the - journal using XZ.</para></listitem> + <listitem><para>If this is set to <literal>yes</literal> then compress + the data in the journal using XZ. The default is <literal>yes</literal>. + </para></listitem> </varlistentry> <varlistentry> - <term><option>--seal</option></term> - <term><option>--no-seal</option></term> + <term><option>--seal</option> [<replaceable>BOOL</replaceable>]</term> - <listitem><para>Periodically sign or not, respectively, the - data in the journal using Forward Secure Sealing. - </para></listitem> + <listitem><para>If this is set to <literal>yes</literal> then + periodically sign the data in the journal using Forward Secure Sealing. + The default is <literal>no</literal>.</para></listitem> </varlistentry> <varlistentry> diff --git a/man/systemd-logind.service.xml b/man/systemd-logind.service.xml index 5733e42cd1..f0bdb1c756 100644 --- a/man/systemd-logind.service.xml +++ b/man/systemd-logind.service.xml @@ -84,7 +84,7 @@ management</para></listitem> </itemizedlist> - <para>User sessions are registered in logind via the + <para>User sessions are registered with logind via the <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry> PAM module.</para> diff --git a/man/systemd-machine-id-setup.xml b/man/systemd-machine-id-setup.xml index 749987a937..944e899bd4 100644 --- a/man/systemd-machine-id-setup.xml +++ b/man/systemd-machine-id-setup.xml @@ -82,7 +82,7 @@ <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> + is 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 @@ -154,7 +154,7 @@ <varlistentry> <term><option>--print</option></term> - <listitem><para>Print the machine ID generated or commited after the operation is complete.</para></listitem> + <listitem><para>Print the machine ID generated or committed after the operation is complete.</para></listitem> </varlistentry> <xi:include href="standard-options.xml" xpointer="help" /> diff --git a/man/systemd-mount.xml b/man/systemd-mount.xml new file mode 100644 index 0000000000..06b7c85bd8 --- /dev/null +++ b/man/systemd-mount.xml @@ -0,0 +1,295 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2016 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-mount" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-mount</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-mount</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-mount</refname> + <refpurpose>Establish a mount or auto-mount point transiently</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-mount</command> + <arg choice="opt" rep="repeat"><replaceable>OPTIONS</replaceable></arg> + <arg choice="plain"><replaceable>WHAT</replaceable></arg> + <arg choice="opt"><replaceable>WHERE</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis> + <command>systemd-mount</command> + <arg choice="opt" rep="repeat"><replaceable>OPTIONS</replaceable></arg> + <arg choice="plain"><option>--list</option></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-mount</command> may be used to create and start a transient <filename>.mount</filename> or + <filename>.automount</filename> unit of the file system <replaceable>WHAT</replaceable> on the mount point + <replaceable>WHERE</replaceable>.</para> + + <para>In many ways, <command>systemd-mount</command> is similar to the lower-level + <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> command, however instead + of executing the mount operation directly and immediately, <command>systemd-mount</command> schedules it through + the service manager job queue, so that it may pull in further dependencies (such as parent mounts, or a file system + checker to execute a priori), and may make use of the auto-mounting logic.</para> + + <para>The command takes either one or two arguments. If only one argument is specified it should refer to a block + device containing a file system (e.g. <literal>/dev/sdb1</literal>), which is then probed for a label and other + metadata, and is mounted to a directory whose name is generated from the label. In this mode the block device must + exist at the time of invocation of the command, so that it may be probed. If the device is found to be a removable + block device (e.g. a USB stick) an automount point instead of a regular mount point is created (i.e. the + <option>--automount=</option> option is implied, see below).</para> + + <para>If two arguments are specified the first indicates the mount source (the <replaceable>WHAT</replaceable>) and + the second indicates the path to mount it on (the <replaceable>WHERE</replaceable>). In this mode no probing of the + source is attempted, and a backing device node doesn't have to exist yet. However, if this mode is combined with + <option>--discover</option>, device node probing for additional metadata is enabled, and – much like in the + single-argument case discussed above – the specified device has to exist at the time of invocation of the + command.</para> + + <para>Use the <option>--list</option> command to show a terse table of all local, known block devices with file + systems that may be mounted with this command.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + + <varlistentry> + <term><option>--no-block</option></term> + + <listitem> + <para>Do not synchronously wait for the requested operation to finish. If this is not specified, the job will + be verified, enqueued and <command>systemd-mount</command> will wait until the mount or automount unit's + start-up is completed. By passing this argument, it is only verified and enqueued.</para> + </listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="no-pager"/> + <xi:include href="standard-options.xml" xpointer="no-ask-password"/> + + <varlistentry> + <term><option>--quiet</option></term> + <term><option>-q</option></term> + + <listitem><para>Suppresses additional informational output while running.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--discover</option></term> + + <listitem><para>Enable probing of the mount source. This switch is implied if a single argument is specified on + the command line. If passed, additional metadata is read from the device to enhance the unit to create. For + example, a descriptive string for the transient units is generated from the file system label and device + model. Moreover if a removable block device (e.g. USB stick) is detected an automount unit instead of a regular + mount unit is created, with a short idle time-out, in order to ensure the file-system is placed in a clean + state quickly after each access.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--type=</option></term> + <term><option>-t</option></term> + + <listitem><para>Specifies the file system type to mount (e.g. <literal>vfat</literal>, <literal>ext4</literal>, + …). If omitted (or set to <literal>auto</literal>) the file system is determined automatically.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--options=</option></term> + <term><option>-o</option></term> + + <listitem><para>Additional mount options for the mount point.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--fsck=</option></term> + + <listitem><para>Takes a boolean argument, defaults to on. Controls whether to run a file system check + immediately before the mount operation. In the automount case (see <option>--automount=</option> below) the + check will be run the moment the first access to the device is made, which might slightly delay the + access.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--description=</option></term> + + <listitem><para>Provide a description for the mount or automount unit. See <varname>Description=</varname> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--property=</option></term> + <term><option>-p</option></term> + + <listitem><para>Sets a unit property for the mount unit that is created. This takes an assignment in the same + format as <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s + <command>set-property</command> command.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--automount=</option></term> + + <listitem><para>Takes a boolean argument. Controls whether to create an automount point or a regular mount + point. If true an automount point is created that is backed by the actual file system at the time of first + access. If false a plain mount point is created that is backed by the actual file system immediately. Automount + points have the benefit that the file system stays unmounted and hence in clean state until it is first + accessed. In automount mode the <option>--timeout-idle-sec=</option> switch (see below) may be used to ensure + the mount point is unmounted automatically after the last access and an idle period passed.</para> + + <para>If this switch is not specified it defaults to false. If not specified and <option>--discover</option> is + used (or only a single argument passed, which implies <option>--discover</option>, see above), and the file + system block device is detected to be removable, it is set to true, in order to increase the chance that the + file system is in a fully clean state if the device is unplugged abruptly.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-A</option></term> + + <listitem><para>Equivalent to <option>--automount=yes</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--timeout-idle-sec=</option></term> + + <listitem><para>Takes a time value that controls the idle timeout in automount mode. If set to + <literal>infinity</literal> (the default) no automatic unmounts are done. Otherwise the file system backing the + automount point is detached after the last access and the idle timeout passed. See + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details on + the time syntax supported. This option has no effect if only a regular mount is established, and automounting + is not used.</para> + + <para>Note that if <option>--discover</option> is used (or only a single argument passed, which implies + <option>--discover</option>, see above), and the file system block device is detected to be removable, + <option>--timeout-idle-sec=1s</option> is implied.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--automount-property=</option></term> + + <listitem><para>Similar to <option>--property=</option>, but applies additional properties to the automount + unit created, instead of the mount unit.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--bind-device=</option></term> + + <listitem><para>Takes a boolean argument, defaults to off. This option only has an effect in automount mode, + and controls whether the automount unit shall be bound to the backing device's lifetime. If enabled, the + automount point will be removed automatically when the backing device vanishes. If disabled the automount point + stays around, and subsequent accesses will block until backing device is replugged. This option has no effect + in case of non-device mounts, such as network or virtual file system mounts.</para> + + <para>Note that if <option>--discover</option> is used (or only a single argument passed, which implies + <option>--discover</option>, see above), and the file system block device is detected to be removable, this + option is implied.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--list</option></term> + + <listitem><para>Instead of establishing a mount or automount point, print a terse list of block devices + containing file systems that may be mounted with <literal>systemd-mount</literal>, along with useful metadata + such as labels, etc.</para></listitem> + </varlistentry> + + <xi:include href="user-system-options.xml" xpointer="user" /> + <xi:include href="user-system-options.xml" xpointer="system" /> + <xi:include href="user-system-options.xml" xpointer="host" /> + <xi:include href="user-system-options.xml" xpointer="machine" /> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + </variablelist> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success, 0 is returned, a non-zero failure + code otherwise.</para> + </refsect1> + + <refsect1> + <title>The udev Database</title> + + <para>If <option>--discover</option> is used, <command>systemd-mount</command> honors a couple of additional udev + properties of block devices:</para> + + <variablelist class='udev-directives'> + <varlistentry> + <term><varname>SYSTEMD_MOUNT_OPTIONS=</varname></term> + + <listitem><para>The mount options to use, if <option>--options=</option> is not used.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SYSTEMD_MOUNT_WHERE=</varname></term> + + <listitem><para>The file system path to place the mount point at, instead of the automatically generated + one.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml index 69d2f6ff7d..c449edee89 100644 --- a/man/systemd-nspawn.xml +++ b/man/systemd-nspawn.xml @@ -274,8 +274,7 @@ signals. It is recommended to use this mode to invoke arbitrary commands in containers, unless they have been modified to run correctly as PID 1. Or in other words: this switch should be used for pretty much all commands, except when the command refers to an init or shell implementation, as these are generally capable of running - correctly as PID 1. This option may not be combined with <option>--boot</option> or - <option>--share-system</option>.</para> + correctly as PID 1. This option may not be combined with <option>--boot</option>.</para> </listitem> </varlistentry> @@ -285,8 +284,7 @@ <listitem><para>Automatically search for an init binary and invoke it as PID 1, instead of a shell or a user supplied program. If this option is used, arguments specified on the command line are used as arguments for the - init binary. This option may not be combined with <option>--as-pid2</option> or - <option>--share-system</option>.</para> + init binary. This option may not be combined with <option>--as-pid2</option>.</para> <para>The following table explains the different modes of invocation and relationship to <option>--as-pid2</option> (see above):</para> @@ -407,41 +405,42 @@ purposes (usually in the range beyond the host's UID/GID 65536). The parameter may be specified as follows:</para> <orderedlist> - <listitem><para>The value <literal>no</literal> turns off user namespacing. This is the default.</para></listitem> - - <listitem><para>The value <literal>yes</literal> (or the omission of a parameter) turns on user - namespacing. The UID/GID range to use is determined automatically from the file ownership of the root - directory of the container's directory tree. To use this option, make sure to prepare the directory tree in - advance, and ensure that all files and directories in it are owned by UIDs/GIDs in the range you'd like to - use. Also, make sure that used file ACLs exclusively reference UIDs/GIDs in the appropriate range. If this - mode is used the number of UIDs/GIDs assigned to the container for use is 65536, and the UID/GID of the - root directory must be a multiple of 65536.</para></listitem> - - <listitem><para>The value "pick" turns on user namespacing. In this case the UID/GID range is automatically - chosen. As first step, the file owner of the root directory of the container's directory tree is read, and it - is checked that it is currently not used by the system otherwise (in particular, that no other container is - using it). If this check is successful, the UID/GID range determined this way is used, similar to the - behaviour if "yes" is specified. If the check is not successful (and thus the UID/GID range indicated in the - root directory's file owner is already used elsewhere) a new – currently unused – UID/GID range of 65536 - UIDs/GIDs is randomly chosen between the host UID/GIDs of 524288 and 1878982656, always starting at a - multiple of 65536. This setting implies <option>--private-users-chown</option> (see below), which has the - effect that the files and directories in the container's directory tree will be owned by the appropriate - users of the range picked. Using this option makes user namespace behaviour fully automatic. Note that the - first invocation of a previously unused container image might result in picking a new UID/GID range for it, - and thus in the (possibly expensive) file ownership adjustment operation. However, subsequent invocations of - the container will be cheap (unless of course the picked UID/GID range is assigned to a different use by - then).</para></listitem> - - <listitem><para>Finally if one or two colon-separated numeric parameters are specified, user namespacing is - turned on, too. The first parameter specifies the first host UID/GID to assign to the container, the second - parameter specifies the number of host UIDs/GIDs to assign to the container. If the second parameter is - omitted, 65536 UIDs/GIDs are assigned.</para></listitem> + <listitem><para>If one or two colon-separated numbers are specified, user namespacing is turned on. The first + parameter specifies the first host UID/GID to assign to the container, the second parameter specifies the + number of host UIDs/GIDs to assign to the container. If the second parameter is omitted, 65536 UIDs/GIDs are + assigned.</para></listitem> + + <listitem><para>If the parameter is omitted, or true, user namespacing is turned on. The UID/GID range to + use is determined automatically from the file ownership of the root directory of the container's directory + tree. To use this option, make sure to prepare the directory tree in advance, and ensure that all files and + directories in it are owned by UIDs/GIDs in the range you'd like to use. Also, make sure that used file ACLs + exclusively reference UIDs/GIDs in the appropriate range. If this mode is used the number of UIDs/GIDs + assigned to the container for use is 65536, and the UID/GID of the root directory must be a multiple of + 65536.</para></listitem> + + <listitem><para>If the parameter is false, user namespacing is turned off. This is the default.</para> + </listitem> + + <listitem><para>The special value <literal>pick</literal> turns on user namespacing. In this case the UID/GID + range is automatically chosen. As first step, the file owner of the root directory of the container's + directory tree is read, and it is checked that it is currently not used by the system otherwise (in + particular, that no other container is using it). If this check is successful, the UID/GID range determined + this way is used, similar to the behavior if "yes" is specified. If the check is not successful (and thus + the UID/GID range indicated in the root directory's file owner is already used elsewhere) a new – currently + unused – UID/GID range of 65536 UIDs/GIDs is randomly chosen between the host UID/GIDs of 524288 and + 1878982656, always starting at a multiple of 65536. This setting implies + <option>--private-users-chown</option> (see below), which has the effect that the files and directories in + the container's directory tree will be owned by the appropriate users of the range picked. Using this option + makes user namespace behavior fully automatic. Note that the first invocation of a previously unused + container image might result in picking a new UID/GID range for it, and thus in the (possibly expensive) file + ownership adjustment operation. However, subsequent invocations of the container will be cheap (unless of + course the picked UID/GID range is assigned to a different use by then).</para></listitem> </orderedlist> <para>It is recommended to assign at least 65536 UIDs/GIDs to each container, so that the usable UID/GID range in the container covers 16 bit. For best security, do not assign overlapping UID/GID ranges to multiple containers. It is hence a good idea to use the upper 16 bit of the host 32-bit UIDs/GIDs as container identifier, while the lower 16 - bit encode the container UID/GID used. This is in fact the behaviour enforced by the + bit encode the container UID/GID used. This is in fact the behavior enforced by the <option>--private-users=pick</option> option.</para> <para>When user namespaces are used, the GID range assigned to each container is always chosen identical to the @@ -456,17 +455,6 @@ </varlistentry> <varlistentry> - <term><option>-U</option></term> - - <listitem><para>If the kernel supports the user namespaces feature, equivalent to - <option>--private-users=pick</option>, otherwise equivalent to - <option>--private-users=no</option>.</para> - - <para>Note that <option>-U</option> is the default if the <filename>systemd-nspawn@.service</filename> template unit - file is used.</para></listitem> - </varlistentry> - - <varlistentry> <term><option>--private-users-chown</option></term> <listitem><para>If specified, all files and directories in the container's directory tree will adjusted so that @@ -479,6 +467,23 @@ </varlistentry> <varlistentry> + <term><option>-U</option></term> + + <listitem><para>If the kernel supports the user namespaces feature, equivalent to + <option>--private-users=pick --private-users-chown</option>, otherwise equivalent to + <option>--private-users=no</option>.</para> + + <para>Note that <option>-U</option> is the default if the + <filename>systemd-nspawn@.service</filename> template unit file is used.</para> + + <para>Note: it is possible to undo the effect of <option>--private-users-chown</option> (or + <option>-U</option>) on the file system by redoing the operation with the first UID of 0:</para> + + <programlisting>systemd-nspawn … --private-users=0 --private-users-chown</programlisting> + </listitem> + </varlistentry> + + <varlistentry> <term><option>--private-network</option></term> <listitem><para>Disconnect networking of the container from @@ -717,7 +722,7 @@ and the subdirectory is symlinked into the host at the same location. <literal>try-host</literal> and <literal>try-guest</literal> do the same but do not fail if - the host does not have persistent journalling enabled. If + the host does not have persistent journaling enabled. If <literal>auto</literal> (the default), and the right subdirectory of <filename>/var/log/journal</filename> exists, it will be bind mounted into the container. If the @@ -847,23 +852,6 @@ </varlistentry> <varlistentry> - <term><option>--share-system</option></term> - - <listitem><para>Allows the container to share certain system - facilities with the host. More specifically, this turns off - PID namespacing, UTS namespacing and IPC namespacing, and thus - allows the guest to see and interact more easily with - processes outside of the container. Note that using this - option makes it impossible to start up a full Operating System - in the container, as an init system cannot operate in this - mode. It is only useful to run specific programs or - applications this way, without involving an init system in the - container. This option implies <option>--register=no</option>. - This option may not be combined with - <option>--boot</option>.</para></listitem> - </varlistentry> - - <varlistentry> <term><option>--register=</option></term> <listitem><para>Controls whether the container is registered @@ -877,9 +865,7 @@ and shown by tools such as <citerefentry project='man-pages'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>. If the container does not run an init system, it is - recommended to set this option to <literal>no</literal>. Note - that <option>--share-system</option> implies - <option>--register=no</option>. </para></listitem> + recommended to set this option to <literal>no</literal>.</para></listitem> </varlistentry> <varlistentry> @@ -1037,9 +1023,9 @@ </example> <example> - <title>Spawn a shell in a container of a minimal gNewSense unstable distribution</title> + <title>Spawn a shell in a container of a minimal gNewSense Ucclia distribution</title> - <programlisting># debootstrap --arch=amd64 unstable ~/gnewsense-tree/ + <programlisting># debootstrap --arch=amd64 ucclia ~/gnewsense-tree/ # systemd-nspawn -D ~/gnewsense-tree/</programlisting> <para>This installs a minimal gNewSense unstable distribution into @@ -1048,12 +1034,12 @@ </example> <example> - <title>Boot a minimal Parabola GNU/Linux-libre distribution in a container</title> + <title>Boot a minimal Parabola distribution in a container</title> <programlisting># pacstrap -c -d ~/parabola-tree/ base # systemd-nspawn -bD ~/parabola-tree/</programlisting> - <para>This installs a minimal Parabola GNU/Linux-libre distribution into the + <para>This installs a minimal Parabola distribution into the directory <filename>~/parabola-tree/</filename> and then boots an OS in a namespace container in it.</para> </example> diff --git a/man/systemd-resolve.xml b/man/systemd-resolve.xml index ca26bb4d49..2bc917ac26 100644 --- a/man/systemd-resolve.xml +++ b/man/systemd-resolve.xml @@ -135,7 +135,7 @@ TXT).</para> <para>The <option>--openpgp</option> switch may be used to query PGP keys stored as - <ulink url="https://tools.ietf.org/html/draft-wouters-dane-openpgp-02">OPENPGPKEY</ulink> resource records. + <ulink url="https://tools.ietf.org/html/rfc7929">OPENPGPKEY</ulink> resource records. When this option is specified one or more e-mail address must be specified.</para> <para>The <option>--tlsa</option> switch maybe be used to query TLS public @@ -339,7 +339,7 @@ www.0pointer.net: 2a01:238:43ed:c300:10c3:bcf3:3266:da74 </example> <example> - <title>Retrieve the MX record of the <literal>0pointer.net</literal> domain</title> + <title>Retrieve the MX record of the <literal>yahoo.com</literal> domain</title> <programlisting>$ systemd-resolve -t MX yahoo.com --legend=no yahoo.com. IN MX 1 mta7.am0.yahoodns.net diff --git a/man/systemd-resolved.service.xml b/man/systemd-resolved.service.xml index aa1c2365e5..56f67960ce 100644 --- a/man/systemd-resolved.service.xml +++ b/man/systemd-resolved.service.xml @@ -68,12 +68,12 @@ link-local networking).</para></listitem> <listitem><para>The glibc - <citerefentry><refentrytitle>getaddrinfo</refentrytitle><manvolnum>3</manvolnum></citerefentry> API as defined + <citerefentry project='man-pages'><refentrytitle>getaddrinfo</refentrytitle><manvolnum>3</manvolnum></citerefentry> API as defined by <ulink url="https://tools.ietf.org/html/rfc3493">RFC3493</ulink> and its related resolver functions, - including <citerefentry><refentrytitle>gethostbyname</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This + including <citerefentry project='man-pages'><refentrytitle>gethostbyname</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This API is widely supported, including beyond the Linux platform. In its current form it does not expose DNSSEC validation status information however, and is synchronous only. This API is backed by the glibc Name Service - Switch (<citerefentry><refentrytitle>nss</refentrytitle><manvolnum>5</manvolnum></citerefentry>). Usage of the + Switch (<citerefentry project='man-pages'><refentrytitle>nss</refentrytitle><manvolnum>5</manvolnum></citerefentry>). Usage of the glibc NSS module <citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry> is required in order to allow glibc's NSS resolver functions to resolve host names via <command>systemd-resolved</command>.</para></listitem> @@ -164,7 +164,7 @@ <title><filename>/etc/resolv.conf</filename></title> <para>Three modes of handling <filename>/etc/resolv.conf</filename> (see - <citerefentry><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>) are + <citerefentry project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>) are supported:</para> <itemizedlist> diff --git a/man/systemd-run.xml b/man/systemd-run.xml index 9c1a29218e..2ad8cb0835 100644 --- a/man/systemd-run.xml +++ b/man/systemd-run.xml @@ -45,7 +45,7 @@ <refnamediv> <refname>systemd-run</refname> - <refpurpose>Run programs in transient scope or service or timer units</refpurpose> + <refpurpose>Run programs in transient scope units, service units, or timer-scheduled service units</refpurpose> </refnamediv> <refsynopsisdiv> @@ -68,42 +68,30 @@ <refsect1> <title>Description</title> - <para><command>systemd-run</command> may be used to create and - start a transient <filename>.service</filename> or - <filename>.scope</filename> unit and run the specified - <replaceable>COMMAND</replaceable> in it. It may also be used to - create and start 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 shows up in the output of <command>systemctl - list-units</command> like any other unit. It will run in a clean - and detached execution environment, with the service manager as - its parent process. In this mode, <command>systemd-run</command> - will start the service asynchronously in the background and return - after the command has begun execution.</para> - - <para>If a command is run as transient scope unit, it will be - 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> + <para><command>systemd-run</command> may be used to create and start a transient <filename>.service</filename> or + <filename>.scope</filename> unit and run the specified <replaceable>COMMAND</replaceable> in it. It may also be + used to create and start a transient <filename>.timer</filename> unit, that activates a + <filename>.service</filename> unit when elapsing.</para> + + <para>If a command is run as transient service unit, it will be started and managed by the service manager like any + other service, and thus shows up in the output of <command>systemctl list-units</command> like any other unit. It + will run in a clean and detached execution environment, with the service manager as its parent process. In this + mode, <command>systemd-run</command> will start the service asynchronously in the background and return after the + command has begun execution (unless <option>--no-block</option> or <option>--watch</option> are specified, see + below).</para> + + <para>If a command is run as transient scope unit, it will be executed by <command>systemd-run</command> itself as + parent process and will thus inherit the execution environment of the caller. However, the processes of the command + are managed by the service manager similar to normal services, and will show up in the output of <command>systemctl + list-units</command>. Execution in this case is synchronous, and will return only when the command finishes. This + mode is enabled via the <option>--scope</option> switch (see below). </para> + + <para>If a command is run with timer options such as <option>--on-calendar=</option> (see below), a transient timer + unit is created alongside the service unit for the specified command. Only the transient timer unit is started + immediately, the transient service unit will be started when the timer elapses. If the <option>--unit=</option> + option is specified, the <replaceable>COMMAND</replaceable> may be omitted. In this case, + <command>systemd-run</command> creates only a <filename>.timer</filename> unit that invokes the specified unit when + elapsing.</para> </refsect1> <refsect1> @@ -123,8 +111,8 @@ <term><option>--scope</option></term> <listitem> - <para>Create a transient <filename>.scope</filename> unit instead of - the default transient <filename>.service</filename> unit. + <para>Create a transient <filename>.scope</filename> unit instead of the default transient + <filename>.service</filename> unit (see above). </para> </listitem> </varlistentry> @@ -140,9 +128,8 @@ <term><option>--property=</option></term> <term><option>-p</option></term> - <listitem><para>Sets a unit property for the scope or service - unit that is created. This takes an assignment in the same - format as + <listitem><para>Sets a property on the scope or service unit that is created. This option takes an assignment + in the same format as <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s <command>set-property</command> command.</para> </listitem> @@ -151,9 +138,8 @@ <varlistentry> <term><option>--description=</option></term> - <listitem><para>Provide a description for the service or scope - unit. If not specified, the command itself will be used as a - description. See <varname>Description=</varname> in + <listitem><para>Provide a description for the service, scope or timer unit. If not specified, the command + itself will be used as a description. See <varname>Description=</varname> in <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. </para></listitem> </varlistentry> @@ -161,19 +147,16 @@ <varlistentry> <term><option>--slice=</option></term> - <listitem><para>Make the new <filename>.service</filename> or - <filename>.scope</filename> unit part of the specified slice, - instead of the <filename>system.slice</filename>.</para> + <listitem><para>Make the new <filename>.service</filename> or <filename>.scope</filename> unit part of the + specified slice, instead of <filename>system.slice</filename>.</para> </listitem> </varlistentry> <varlistentry> <term><option>--remain-after-exit</option></term> - <listitem><para>After the service or scope process has - terminated, keep the service around until it is explicitly - stopped. This is useful to collect runtime information about - the service after it finished running. Also see + <listitem><para>After the service process has terminated, keep the service around until it is explicitly + stopped. This is useful to collect runtime information about the service after it finished running. Also see <varname>RemainAfterExit=</varname> in <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>. </para> @@ -183,10 +166,8 @@ <varlistentry> <term><option>--send-sighup</option></term> - <listitem><para>When terminating the scope or service unit, - send a SIGHUP immediately after SIGTERM. This is useful to - indicate to shells and shell-like processes that the - connection has been severed. Also see + <listitem><para>When terminating the scope or service unit, send a SIGHUP immediately after SIGTERM. This is + useful to indicate to shells and shell-like processes that the connection has been severed. Also see <varname>SendSIGHUP=</varname> in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. </para> @@ -209,9 +190,8 @@ <term><option>--uid=</option></term> <term><option>--gid=</option></term> - <listitem><para>Runs the service process under the UNIX user - and group. Also see <varname>User=</varname> and - <varname>Group=</varname> in + <listitem><para>Runs the service process under the specified UNIX user and group. Also see + <varname>User=</varname> and <varname>Group=</varname> in <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> </listitem> </varlistentry> @@ -239,11 +219,9 @@ <term><option>--pty</option></term> <term><option>-t</option></term> - <listitem><para>When invoking a command, the service connects - its standard input and output to the invoking tty via a - pseudo TTY device. This allows invoking binaries as services - that expect interactive user input, such as interactive - command shells.</para></listitem> + <listitem><para>When invoking the command, the transient service connects its standard input and output to the + terminal <command>systemd-run</command> is invoked on, via a pseudo TTY device. This allows running binaries + that expect interactive user input as services, such as interactive command shells.</para></listitem> </varlistentry> <varlistentry> @@ -263,44 +241,32 @@ <term><option>--on-unit-active=</option></term> <term><option>--on-unit-inactive=</option></term> - <listitem><para>Defines monotonic timers relative to different - starting points. Also see <varname>OnActiveSec=</varname>, - <varname>OnBootSec=</varname>, - <varname>OnStartupSec=</varname>, - <varname>OnUnitActiveSec=</varname> and - <varname>OnUnitInactiveSec=</varname> in - <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This - options have no effect in conjunction with - <option>--scope</option>.</para> + <listitem><para>Defines a monotonic timer relative to different starting points for starting the specified + command. See <varname>OnActiveSec=</varname>, <varname>OnBootSec=</varname>, <varname>OnStartupSec=</varname>, + <varname>OnUnitActiveSec=</varname> and <varname>OnUnitInactiveSec=</varname> in + <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry> for + details. These options may not be combined with <option>--scope</option>.</para> </listitem> </varlistentry> <varlistentry> <term><option>--on-calendar=</option></term> - <listitem><para>Defines realtime (i.e. wallclock) timers with - calendar event expressions. Also see - <varname>OnCalendar=</varname> in - <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This - option has no effect in conjunction with - <option>--scope</option>.</para> + <listitem><para>Defines a calendar timer for starting the specified command. See <varname>OnCalendar=</varname> + in <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This + option may not be combined with <option>--scope</option>.</para> </listitem> </varlistentry> <varlistentry> <term><option>--timer-property=</option></term> - <listitem><para>Sets a timer unit property for the timer unit - that is created. It is similar with - <option>--property</option> but only for created timer - unit. This option only has effect in conjunction with - <option>--on-active=</option>, <option>--on-boot=</option>, - <option>--on-startup=</option>, - <option>--on-unit-active=</option>, - <option>--on-unit-inactive=</option>, - <option>--on-calendar=</option>. This takes an assignment in - the same format as - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s + <listitem><para>Sets a property on the timer unit that is created. This option is similar to + <option>--property=</option> but applies to the transient timer unit rather than the transient service unit + created. This option only has an effect in conjunction with <option>--on-active=</option>, + <option>--on-boot=</option>, <option>--on-startup=</option>, <option>--on-unit-active=</option>, + <option>--on-unit-inactive=</option> or <option>--on-calendar=</option>. This option takes an assignment in the + same format as <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s <command>set-property</command> command.</para> </listitem> </varlistentry> @@ -308,14 +274,25 @@ <term><option>--no-block</option></term> <listitem> - <para>Do not synchronously wait for the requested operation - to finish. If this is not specified, the job will be - verified, enqueued and <command>systemd-run</command> will - wait until the unit's start-up is completed. By passing this - argument, it is only verified and enqueued.</para> + <para>Do not synchronously wait for the unit start operation to finish. If this option is not specified, the + start request for the transient unit will be verified, enqueued and <command>systemd-run</command> will wait + until the unit's start-up is completed. By passing this argument, it is only verified and enqueued. This + option may not be combined with <option>--wait</option>.</para> </listitem> </varlistentry> + <varlistentry> + <term><option>--wait</option></term> + + <listitem><para>Synchronously wait for the transient service to terminate. If this option is specified, the + start request for the transient unit is verified, enqueued, and waited for. Subsequently the invoked unit is + monitored, and it is waited until it is deactivated again (most likely because the specified command + completed). On exit, terse information about the unit's runtime is shown, including total runtime (as well as + CPU usage, if <option>--property=CPUAccounting=1</option> was set) and the exit code and status of the main + process. This output may be suppressed with <option>--quiet</option>. This option may not be combined with + <option>--no-block</option>, <option>--scope</option> or the various timer options.</para></listitem> + </varlistentry> + <xi:include href="user-system-options.xml" xpointer="user" /> <xi:include href="user-system-options.xml" xpointer="system" /> <xi:include href="user-system-options.xml" xpointer="host" /> @@ -425,7 +402,7 @@ There is a screen on: when the user first logs in, and stays around as long as at least one login session is open. After the user logs out of the last session, <filename>user@.service</filename> and all services underneath it - are terminated. This behaviour is the default, when "lingering" is + are terminated. This behavior is the default, when "lingering" is not enabled for that user. Enabling lingering means that <filename>user@.service</filename> is started automatically during boot, even if the user is not logged in, and that the service is @@ -452,6 +429,7 @@ There is a screen on: <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-mount</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/systemd-socket-activate.xml b/man/systemd-socket-activate.xml index 2cf3a7d377..1c0619a840 100644 --- a/man/systemd-socket-activate.xml +++ b/man/systemd-socket-activate.xml @@ -142,7 +142,7 @@ <varname>FileDescriptorName=</varname> in socket unit files, and enables use of <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Multiple entries may be specifies using separate options or by separating names with colons - (<literal>:</literal>) in one option. In case more names are given than descriptors, superfluous ones willl be + (<literal>:</literal>) in one option. In case more names are given than descriptors, superfluous ones will be ignored. In case less names are given than descriptors, the remaining file descriptors will be unnamed. </para></listitem> </varlistentry> diff --git a/man/systemd-system.conf.xml b/man/systemd-system.conf.xml index 1bb40fd234..e4e81f7f2e 100644 --- a/man/systemd-system.conf.xml +++ b/man/systemd-system.conf.xml @@ -106,6 +106,18 @@ </varlistentry> <varlistentry> + <term><varname>CtrlAltDelBurstAction=</varname></term> + + <listitem><para>Defines what action will be performed + if user presses Ctrl-Alt-Delete more than 7 times in 2s. + Can be set to <literal>reboot-force</literal>, <literal>poweroff-force</literal>, + <literal>reboot-immediate</literal>, <literal>poweroff-immediate</literal> + or disabled with <literal>none</literal>. Defaults to + <literal>reboot-force</literal>. + </para></listitem> + </varlistentry> + + <varlistentry> <term><varname>CPUAffinity=</varname></term> <listitem><para>Configures the initial CPU affinity for the @@ -318,7 +330,7 @@ <varname>TasksAccounting=</varname>. See <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details on the per-unit - settings. <varname>DefaulTasksAccounting=</varname> defaults + settings. <varname>DefaultTasksAccounting=</varname> defaults to on, the other three settings to off.</para></listitem> </varlistentry> diff --git a/man/systemd-vconsole-setup.service.xml b/man/systemd-vconsole-setup.service.xml index ff079761c1..f2da2a7b77 100644 --- a/man/systemd-vconsole-setup.service.xml +++ b/man/systemd-vconsole-setup.service.xml @@ -43,61 +43,39 @@ <refnamediv> <refname>systemd-vconsole-setup.service</refname> <refname>systemd-vconsole-setup</refname> - <refpurpose>Configure the virtual console at boot</refpurpose> + <refpurpose>Configure the virtual consoles</refpurpose> </refnamediv> <refsynopsisdiv> <para><filename>systemd-vconsole-setup.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-vconsole-setup</filename></para> + <cmdsynopsis> + <command>/usr/lib/systemd/systemd-vconsole-setup</command> + <arg choice="opt">TTY</arg> + </cmdsynopsis> </refsynopsisdiv> <refsect1> <title>Description</title> - <para><filename>systemd-vconsole-setup.service</filename> is an - early boot service that configures the virtual console font and - console keymap. Internally it calls - <citerefentry project='mankier'><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry> - and - <citerefentry project='die-net'><refentrytitle>setfont</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - - <para>See - <citerefentry><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for information about the configuration files understood by this - service.</para> - - - </refsect1> - - <refsect1> - <title>Kernel Command Line</title> - - <para>A few configuration parameters from - <filename>vconsole.conf</filename> may be overridden on the kernel - command line:</para> - - <variablelist class='kernel-commandline-options'> - <varlistentry> - <term><varname>vconsole.keymap=</varname></term> - <term><varname>vconsole.keymap.toggle=</varname></term> - - <listitem><para>Overrides the key mapping table for the - keyboard and the second toggle keymap.</para></listitem> - </varlistentry> - <varlistentry> - - <term><varname>vconsole.font=</varname></term> - <term><varname>vconsole.font.map=</varname></term> - <term><varname>vconsole.font.unimap=</varname></term> + <para><filename>systemd-vconsole-setup</filename> is a helper used to prepare either all virtual consoles, or — if + the optional <replaceable>TTY</replaceable> parameter is provided — a specific one. When the system is booting up + it's called by <citerefentry><command>udev</command></citerefentry> during vtconsole subsystem initialization. + <productname>Systemd</productname> also calls it internally as needed via + <filename>systemd-vconsole-setup.service</filename>. The helper calls + <citerefentry project='mankier'><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry> and + <citerefentry project='die-net'><refentrytitle>setfont</refentrytitle><manvolnum>8</manvolnum></citerefentry> + internally. + </para> - <listitem><para>Configures the console font, the console map, - and the unicode font map.</para></listitem> - </varlistentry> - </variablelist> + <para> + You may want to use this helper whenever you change <filename>vconsole.conf</filename> to + refresh the settings on your consoles — either through the <command>systemctl restart</command> / + <command>systemctl start</command> command or directly through the executable. + </para> <para>See <citerefentry><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for information about these settings.</para> + for information about the configuration files and kernel command line options understood by this program.</para> </refsect1> <refsect1> diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index 41ae6e76de..3c350df11f 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -74,6 +74,10 @@ execution specific configuration options are configured in the [Service], [Socket], [Mount], or [Swap] sections, depending on the unit type.</para> + + <para>In addition, options which control resources through Linux Control Groups (cgroups) are listed in + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + Those options complement options listed here.</para> </refsect1> <refsect1> @@ -107,46 +111,76 @@ <varlistentry> <term><varname>WorkingDirectory=</varname></term> - <listitem><para>Takes a directory path relative to the service's root - directory specified by <varname>RootDirectory=</varname>, or the - special value <literal>~</literal>. Sets the working directory - for executed processes. If set to <literal>~</literal>, the - home directory of the user specified in - <varname>User=</varname> is used. If not set, defaults to the - root directory when systemd is running as a system instance - and the respective user's home directory if run as user. If - the setting is prefixed with the <literal>-</literal> - character, a missing working directory is not considered - fatal. If <varname>RootDirectory=</varname> is not set, then - <varname>WorkingDirectory=</varname> is relative to the root of - the system running the service manager. - Note that setting this parameter might result in - additional dependencies to be added to the unit (see - above).</para></listitem> + <listitem><para>Takes a directory path relative to the service's root directory specified by + <varname>RootDirectory=</varname>, or the special value <literal>~</literal>. Sets the working directory for + executed processes. If set to <literal>~</literal>, the home directory of the user specified in + <varname>User=</varname> is used. If not set, defaults to the root directory when systemd is running as a + system instance and the respective user's home directory if run as user. If the setting is prefixed with the + <literal>-</literal> character, a missing working directory is not considered fatal. If + <varname>RootDirectory=</varname> is not set, then <varname>WorkingDirectory=</varname> is relative to the root + of the system running the service manager. Note that setting this parameter might result in additional + dependencies to be added to the unit (see above).</para></listitem> </varlistentry> <varlistentry> <term><varname>RootDirectory=</varname></term> - <listitem><para>Takes a directory path relative to the host's root directory - (i.e. the root of the system running the service manager). Sets the - root directory for executed processes, with the <citerefentry - project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry> - system call. If this is used, it must be ensured that the - process binary and all its auxiliary files are available in - the <function>chroot()</function> jail. Note that setting this - parameter might result in additional dependencies to be added - to the unit (see above).</para></listitem> + <listitem><para>Takes a directory path relative to the host's root directory (i.e. the root of the system + running the service manager). Sets the root directory for executed processes, with the <citerefentry + project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system + call. If this is used, it must be ensured that the process binary and all its auxiliary files are available in + the <function>chroot()</function> jail. Note that setting this parameter might result in additional + dependencies to be added to the unit (see above).</para> + + <para>The <varname>PrivateUsers=</varname> setting is particularly useful in conjunction with + <varname>RootDirectory=</varname>. For details, see below.</para></listitem> </varlistentry> <varlistentry> <term><varname>User=</varname></term> <term><varname>Group=</varname></term> - <listitem><para>Sets the Unix user or group that the processes - are executed as, respectively. Takes a single user or group - name or ID as argument. If no group is set, the default group - of the user is chosen. These do not affect commands prefixed with <literal>+</literal>.</para></listitem> + <listitem><para>Set the UNIX user or group that the processes are executed as, respectively. Takes a single + user or group name, or numeric ID as argument. For system services (services run by the system service manager, + i.e. managed by PID 1) and for user services of the root user (services managed by root's instance of + <command>systemd --user</command>), the default is <literal>root</literal>, but <varname>User=</varname> may be + used to specify a different user. For user services of any other user, switching user identity is not + permitted, hence the only valid setting is the same user the user's service manager is running as. If no group + is set, the default group of the user is used. This setting does not affect commands whose command line is + prefixed with <literal>+</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DynamicUser=</varname></term> + + <listitem><para>Takes a boolean parameter. If set, a UNIX user and group pair is allocated dynamically when the + unit is started, and released as soon as it is stopped. The user and group will not be added to + <filename>/etc/passwd</filename> or <filename>/etc/group</filename>, but are managed transiently during + runtime. The <citerefentry><refentrytitle>nss-systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry> + glibc NSS module provides integration of these dynamic users/groups into the system's user and group + databases. The user and group name to use may be configured via <varname>User=</varname> and + <varname>Group=</varname> (see above). If these options are not used and dynamic user/group allocation is + enabled for a unit, the name of the dynamic user/group is implicitly derived from the unit name. If the unit + name without the type suffix qualifies as valid user name it is used directly, otherwise a name incorporating a + hash of it is used. If a statically allocated user or group of the configured name already exists, it is used + and no dynamic user/group is allocated. Dynamic users/groups are allocated from the UID/GID range + 61184…65519. It is recommended to avoid this range for regular system or login users. At any point in time + each UID/GID from this range is only assigned to zero or one dynamically allocated users/groups in + use. However, UID/GIDs are recycled after a unit is terminated. Care should be taken that any processes running + as part of a unit for which dynamic users/groups are enabled do not leave files or directories owned by these + users/groups around, as a different unit might get the same UID/GID assigned later on, and thus gain access to + these files or directories. If <varname>DynamicUser=</varname> is enabled, <varname>RemoveIPC=</varname>, + <varname>PrivateTmp=</varname> are implied. This ensures that the lifetime of IPC objects and temporary files + created by the executed processes is bound to the runtime of the service, and hence the lifetime of the dynamic + user/group. Since <filename>/tmp</filename> and <filename>/var/tmp</filename> are usually the only + world-writable directories on a system this ensures that a unit making use of dynamic user/group allocation + cannot leave files around after unit termination. Moreover <varname>ProtectSystem=strict</varname> and + <varname>ProtectHome=read-only</varname> are implied, thus prohibiting the service to write to arbitrary file + system locations. In order to allow the service to write to certain directories, they have to be whitelisted + using <varname>ReadWritePaths=</varname>, but care must be taken so that UID/GID recycling doesn't + create security issues involving files created by the service. Use <varname>RuntimeDirectory=</varname> (see + below) in order to assign a writable runtime directory to a service, owned by the dynamic user/group and + removed automatically when the unit is terminated. Defaults to off.</para></listitem> </varlistentry> <varlistentry> @@ -165,6 +199,18 @@ </varlistentry> <varlistentry> + <term><varname>RemoveIPC=</varname></term> + + <listitem><para>Takes a boolean parameter. If set, all System V and POSIX IPC objects owned by the user and + group the processes of this unit are run as are removed when the unit is stopped. This setting only has an + effect if at least one of <varname>User=</varname>, <varname>Group=</varname> and + <varname>DynamicUser=</varname> are used. It has no effect on IPC objects owned by the root user. Specifically, + this removes System V semaphores, as well as System V and POSIX shared memory segments and message queues. If + multiple units use the same user or group the IPC objects are removed when the last of these units is + stopped. This setting is implied if <varname>DynamicUser=</varname> is set.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>Nice=</varname></term> <listitem><para>Sets the default nice level (scheduling @@ -368,8 +414,9 @@ <option>null</option>, <option>tty</option>, <option>tty-force</option>, - <option>tty-fail</option> or - <option>socket</option>.</para> + <option>tty-fail</option>, + <option>socket</option> or + <option>fd</option>.</para> <para>If <option>null</option> is selected, standard input will be connected to <filename>/dev/null</filename>, i.e. all @@ -407,6 +454,20 @@ <citerefentry project='freebsd'><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry> daemon.</para> + <para>The <option>fd</option> option connects + the input stream to a single file descriptor provided by a socket unit. + A custom named file descriptor can be specified as part of this option, + after a <literal>:</literal> (e.g. <literal>fd:<replaceable>foobar</replaceable></literal>). + If no name is specified, <literal>stdin</literal> is assumed + (i.e. <literal>fd</literal> is equivalent to <literal>fd:stdin</literal>). + At least one socket unit defining such name must be explicitly provided via the + <varname>Sockets=</varname> option, and file descriptor name may differ + from the name of its containing socket unit. + If multiple matches are found, the first one will be used. + See <varname>FileDescriptorName=</varname> in + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more details about named descriptors and ordering.</para> + <para>This setting defaults to <option>null</option>.</para></listitem> </varlistentry> @@ -423,8 +484,9 @@ <option>kmsg</option>, <option>journal+console</option>, <option>syslog+console</option>, - <option>kmsg+console</option> or - <option>socket</option>.</para> + <option>kmsg+console</option>, + <option>socket</option> or + <option>fd</option>.</para> <para><option>inherit</option> duplicates the file descriptor of standard input for standard output.</para> @@ -473,6 +535,20 @@ similar to the same option of <varname>StandardInput=</varname>.</para> + <para>The <option>fd</option> option connects + the output stream to a single file descriptor provided by a socket unit. + A custom named file descriptor can be specified as part of this option, + after a <literal>:</literal> (e.g. <literal>fd:<replaceable>foobar</replaceable></literal>). + If no name is specified, <literal>stdout</literal> is assumed + (i.e. <literal>fd</literal> is equivalent to <literal>fd:stdout</literal>). + At least one socket unit defining such name must be explicitly provided via the + <varname>Sockets=</varname> option, and file descriptor name may differ + from the name of its containing socket unit. + If multiple matches are found, the first one will be used. + See <varname>FileDescriptorName=</varname> in + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more details about named descriptors and ordering.</para> + <para>If the standard output (or error output, see below) of a unit is connected to the journal, syslog or the kernel log buffer, the unit will implicitly gain a dependency of type <varname>After=</varname> on <filename>systemd-journald.socket</filename> (also see the automatic dependencies section above).</para> @@ -490,9 +566,13 @@ <listitem><para>Controls where file descriptor 2 (STDERR) of the executed processes is connected to. The available options are identical to those of <varname>StandardOutput=</varname>, - with one exception: if set to <option>inherit</option> the + with some exceptions: if set to <option>inherit</option> the file descriptor used for standard output is duplicated for - standard error. This setting defaults to the value set with + standard error, while <option>fd</option> operates on the error + stream and will look by default for a descriptor named + <literal>stderr</literal>.</para> + + <para>This setting defaults to the value set with <option>DefaultStandardError=</option> in <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, which defaults to <option>inherit</option>. Note that setting @@ -666,8 +746,19 @@ <varname>MemoryLimit=</varname> is a more powerful (and working) replacement for <varname>LimitRSS=</varname>.</para> + <para>For system units these resource limits may be chosen freely. For user units however (i.e. units run by a + per-user instance of + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>), these limits are + bound by (possibly more restrictive) per-user limits enforced by the OS.</para> + + <para>Resource limits not configured explicitly for a unit default to the value configured in the various + <varname>DefaultLimitCPU=</varname>, <varname>DefaultLimitFSIZE=</varname>, … options available in + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, and – + if not configured there – the kernel or per-user defaults, as defined by the OS (the latter only for user + services, see above).</para> + <table> - <title>Limit directives and their equivalent with ulimit</title> + <title>Resource limit directives, their equivalent <command>ulimit</command> shell commands and the unit used</title> <tgroup cols='3'> <colspec colname='directive' /> @@ -676,7 +767,7 @@ <thead> <row> <entry>Directive</entry> - <entry>ulimit equivalent</entry> + <entry><command>ulimit</command> equivalent</entry> <entry>Unit</entry> </row> </thead> @@ -784,49 +875,37 @@ <listitem><para>Controls which capabilities to include in the capability bounding set for the executed process. See <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> for - details. Takes a whitespace-separated list of capability names as read by <citerefentry - project='mankier'><refentrytitle>cap_from_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - e.g. <constant>CAP_SYS_ADMIN</constant>, <constant>CAP_DAC_OVERRIDE</constant>, - <constant>CAP_SYS_PTRACE</constant>. Capabilities listed will be included in the bounding set, all others are - removed. If the list of capabilities is prefixed with <literal>~</literal>, all but the listed capabilities - will be included, the effect of the assignment inverted. Note that this option also affects the respective - capabilities in the effective, permitted and inheritable capability sets. If this option is not used, the - capability bounding set is not modified on process execution, hence no limits on the capabilities of the - process are enforced. This option may appear more than once, in which case the bounding sets are merged. If the - empty string is assigned to this option, the bounding set is reset to the empty capability set, and all prior - settings have no effect. If set to <literal>~</literal> (without any further argument), the bounding set is - reset to the full set of available capabilities, also undoing any previous settings. This does not affect - commands prefixed with <literal>+</literal>.</para></listitem> + details. Takes a whitespace-separated list of capability names, e.g. <constant>CAP_SYS_ADMIN</constant>, + <constant>CAP_DAC_OVERRIDE</constant>, <constant>CAP_SYS_PTRACE</constant>. Capabilities listed will be + included in the bounding set, all others are removed. If the list of capabilities is prefixed with + <literal>~</literal>, all but the listed capabilities will be included, the effect of the assignment + inverted. Note that this option also affects the respective capabilities in the effective, permitted and + inheritable capability sets. If this option is not used, the capability bounding set is not modified on process + execution, hence no limits on the capabilities of the process are enforced. This option may appear more than + once, in which case the bounding sets are merged. If the empty string is assigned to this option, the bounding + set is reset to the empty capability set, and all prior settings have no effect. If set to + <literal>~</literal> (without any further argument), the bounding set is reset to the full set of available + capabilities, also undoing any previous settings. This does not affect commands prefixed with + <literal>+</literal>.</para></listitem> </varlistentry> <varlistentry> <term><varname>AmbientCapabilities=</varname></term> - <listitem><para>Controls which capabilities to include in the - ambient capability set for the executed process. Takes a - whitespace-separated list of capability names as read by - <citerefentry project='mankier'><refentrytitle>cap_from_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - e.g. <constant>CAP_SYS_ADMIN</constant>, - <constant>CAP_DAC_OVERRIDE</constant>, - <constant>CAP_SYS_PTRACE</constant>. This option may appear more than - once in which case the ambient capability sets are merged. - If the list of capabilities is prefixed with <literal>~</literal>, all - but the listed capabilities will be included, the effect of the - assignment inverted. If the empty string is - assigned to this option, the ambient capability set is reset to - the empty capability set, and all prior settings have no effect. - If set to <literal>~</literal> (without any further argument), the - ambient capability set is reset to the full set of available - capabilities, also undoing any previous settings. Note that adding - capabilities to ambient capability set adds them to the process's - inherited capability set. - </para><para> - Ambient capability sets are useful if you want to execute a process - as a non-privileged user but still want to give it some capabilities. - Note that in this case option <constant>keep-caps</constant> is - automatically added to <varname>SecureBits=</varname> to retain the - capabilities over the user change. <varname>AmbientCapabilities=</varname> does not affect - commands prefixed with <literal>+</literal>.</para></listitem> + <listitem><para>Controls which capabilities to include in the ambient capability set for the executed + process. Takes a whitespace-separated list of capability names, e.g. <constant>CAP_SYS_ADMIN</constant>, + <constant>CAP_DAC_OVERRIDE</constant>, <constant>CAP_SYS_PTRACE</constant>. This option may appear more than + once in which case the ambient capability sets are merged. If the list of capabilities is prefixed with + <literal>~</literal>, all but the listed capabilities will be included, the effect of the assignment + inverted. If the empty string is assigned to this option, the ambient capability set is reset to the empty + capability set, and all prior settings have no effect. If set to <literal>~</literal> (without any further + argument), the ambient capability set is reset to the full set of available capabilities, also undoing any + previous settings. Note that adding capabilities to ambient capability set adds them to the process's inherited + capability set. </para><para> Ambient capability sets are useful if you want to execute a process as a + non-privileged user but still want to give it some capabilities. Note that in this case option + <constant>keep-caps</constant> is automatically added to <varname>SecureBits=</varname> to retain the + capabilities over the user change. <varname>AmbientCapabilities=</varname> does not affect commands prefixed + with <literal>+</literal>.</para></listitem> </varlistentry> <varlistentry> @@ -852,101 +931,75 @@ <term><varname>ReadOnlyPaths=</varname></term> <term><varname>InaccessiblePaths=</varname></term> - <listitem><para>Sets up a new file system namespace for - executed processes. These options may be used to limit access - a process might have to the main file system hierarchy. Each - setting takes a space-separated list of paths relative to - the host's root directory (i.e. the system running the service manager). - Note that if entries contain symlinks, they are resolved from the host's root directory as well. - Entries (files or directories) listed in - <varname>ReadWritePaths=</varname> are accessible from - within the namespace with the same access rights as from - outside. Entries listed in - <varname>ReadOnlyPaths=</varname> are accessible for - reading only, writing will be refused even if the usual file - access controls would permit this. Entries listed in - <varname>InaccessiblePaths=</varname> will be made - inaccessible for processes inside the namespace, and may not - countain any other mountpoints, including those specified by - <varname>ReadWritePaths=</varname> or - <varname>ReadOnlyPaths=</varname>. - Note that restricting access with these options does not extend - to submounts of a directory that are created later on. - Non-directory paths can be specified as well. These - options may be specified more than once, in which case all - paths listed will have limited access from within the - namespace. If the empty string is assigned to this option, the - specific list is reset, and all prior assignments have no - effect.</para> - <para>Paths in - <varname>ReadOnlyPaths=</varname> - and - <varname>InaccessiblePaths=</varname> - may be prefixed with - <literal>-</literal>, in which case - they will be ignored when they do not - exist. Note that using this - setting will disconnect propagation of - mounts from the service to the host - (propagation in the opposite direction - continues to work). This means that - this setting may not be used for - services which shall be able to - install mount points in the main mount - namespace.</para></listitem> + <listitem><para>Sets up a new file system namespace for executed processes. These options may be used to limit + access a process might have to the file system hierarchy. Each setting takes a space-separated list of paths + relative to the host's root directory (i.e. the system running the service manager). Note that if paths + contain symlinks, they are resolved relative to the root directory set with + <varname>RootDirectory=</varname>.</para> + + <para>Paths listed in <varname>ReadWritePaths=</varname> are accessible from within the namespace with the same + access modes as from outside of it. Paths listed in <varname>ReadOnlyPaths=</varname> are accessible for + reading only, writing will be refused even if the usual file access controls would permit this. Nest + <varname>ReadWritePaths=</varname> inside of <varname>ReadOnlyPaths=</varname> in order to provide writable + subdirectories within read-only directories. Use <varname>ReadWritePaths=</varname> in order to whitelist + specific paths for write access if <varname>ProtectSystem=strict</varname> is used. Paths listed in + <varname>InaccessiblePaths=</varname> will be made inaccessible for processes inside the namespace (along with + everything below them in the file system hierarchy).</para> + + <para>Note that restricting access with these options does not extend to submounts of a directory that are + created later on. Non-directory paths may be specified as well. These options may be specified more than once, + in which case all paths listed will have limited access from within the namespace. If the empty string is + assigned to this option, the specific list is reset, and all prior assignments have no effect.</para> + + <para>Paths in <varname>ReadWritePaths=</varname>, <varname>ReadOnlyPaths=</varname> and + <varname>InaccessiblePaths=</varname> may be prefixed with <literal>-</literal>, in which case they will be ignored + when they do not exist. Note that using this setting will disconnect propagation of mounts from the service to + the host (propagation in the opposite direction continues to work). This means that this setting may not be used + for services which shall be able to install mount points in the main mount namespace. Note that the effect of + these settings may be undone by privileged processes. In order to set up an effective sandboxed environment for + a unit it is thus recommended to combine these settings with either + <varname>CapabilityBoundingSet=~CAP_SYS_ADMIN</varname> or <varname>SystemCallFilter=~@mount</varname>.</para></listitem> </varlistentry> <varlistentry> <term><varname>PrivateTmp=</varname></term> - <listitem><para>Takes a boolean argument. If true, sets up a - new file system namespace for the executed processes and - mounts private <filename>/tmp</filename> and - <filename>/var/tmp</filename> directories inside it that is - not shared by processes outside of the namespace. This is - useful to secure access to temporary files of the process, but - makes sharing between processes via <filename>/tmp</filename> - or <filename>/var/tmp</filename> impossible. If this is - enabled, all temporary files created by a service in these - directories will be removed after the service is stopped. - Defaults to false. It is possible to run two or more units - within the same private <filename>/tmp</filename> and - <filename>/var/tmp</filename> namespace by using the + <listitem><para>Takes a boolean argument. If true, sets up a new file system namespace for the executed + processes and mounts private <filename>/tmp</filename> and <filename>/var/tmp</filename> directories inside it + that is not shared by processes outside of the namespace. This is useful to secure access to temporary files of + the process, but makes sharing between processes via <filename>/tmp</filename> or <filename>/var/tmp</filename> + impossible. If this is enabled, all temporary files created by a service in these directories will be removed + after the service is stopped. Defaults to false. It is possible to run two or more units within the same + private <filename>/tmp</filename> and <filename>/var/tmp</filename> namespace by using the <varname>JoinsNamespaceOf=</varname> directive, see - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. Note that using this setting will disconnect - propagation of mounts from the service to the host - (propagation in the opposite direction continues to work). - This means that this setting may not be used for services - which shall be able to install mount points in the main mount - namespace.</para></listitem> + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for + details. This setting is implied if <varname>DynamicUser=</varname> is set. For this setting the same + restrictions regarding mount propagation and privileges apply as for <varname>ReadOnlyPaths=</varname> and + related calls, see above.</para></listitem> + </varlistentry> <varlistentry> <term><varname>PrivateDevices=</varname></term> - <listitem><para>Takes a boolean argument. If true, sets up a - new /dev namespace for the executed processes and only adds - API pseudo devices such as <filename>/dev/null</filename>, - <filename>/dev/zero</filename> or - <filename>/dev/random</filename> (as well as the pseudo TTY - subsystem) to it, but no physical devices such as - <filename>/dev/sda</filename>. This is useful to securely turn - off physical device access by the executed process. Defaults - to false. Enabling this option will also remove - <constant>CAP_MKNOD</constant> from the capability bounding - set for the unit (see above), and set - <varname>DevicePolicy=closed</varname> (see + <listitem><para>Takes a boolean argument. If true, sets up a new /dev namespace for the executed processes and + only adds API pseudo devices such as <filename>/dev/null</filename>, <filename>/dev/zero</filename> or + <filename>/dev/random</filename> (as well as the pseudo TTY subsystem) to it, but no physical devices such as + <filename>/dev/sda</filename>, system memory <filename>/dev/mem</filename>, system ports + <filename>/dev/port</filename> and others. This is useful to securely turn off physical device access by the + executed process. Defaults to false. Enabling this option will install a system call filter to block low-level + I/O system calls that are grouped in the <varname>@raw-io</varname> set, will also remove + <constant>CAP_MKNOD</constant> and <constant>CAP_SYS_RAWIO</constant> from the capability bounding set for + the unit (see above), and set <varname>DevicePolicy=closed</varname> (see <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details). Note that using this setting will disconnect - propagation of mounts from the service to the host - (propagation in the opposite direction continues to work). - This means that this setting may not be used for services - which shall be able to install mount points in the main mount - namespace. The /dev namespace will be mounted read-only and 'noexec'. - The latter may break old programs which try to set up executable - memory by using <citerefentry><refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum></citerefentry> - of <filename>/dev/zero</filename> instead of using <constant>MAP_ANON</constant>.</para></listitem> + for details). Note that using this setting will disconnect propagation of mounts from the service to the host + (propagation in the opposite direction continues to work). This means that this setting may not be used for + services which shall be able to install mount points in the main mount namespace. The /dev namespace will be + mounted read-only and 'noexec'. The latter may break old programs which try to set up executable memory by + using <citerefentry><refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum></citerefentry> of + <filename>/dev/zero</filename> instead of using <constant>MAP_ANON</constant>. This setting is implied if + <varname>DynamicUser=</varname> is set. For this setting the same restrictions regarding mount propagation and + privileges apply as for <varname>ReadOnlyPaths=</varname> and related calls, see above.</para></listitem> </varlistentry> <varlistentry> @@ -971,76 +1024,107 @@ </varlistentry> <varlistentry> + <term><varname>PrivateUsers=</varname></term> + + <listitem><para>Takes a boolean argument. If true, sets up a new user namespace for the executed processes and + configures a minimal user and group mapping, that maps the <literal>root</literal> user and group as well as + the unit's own user and group to themselves and everything else to the <literal>nobody</literal> user and + group. This is useful to securely detach the user and group databases used by the unit from the rest of the + system, and thus to create an effective sandbox environment. All files, directories, processes, IPC objects and + other resources owned by users/groups not equaling <literal>root</literal> or the unit's own will stay visible + from within the unit but appear owned by the <literal>nobody</literal> user and group. If this mode is enabled, + all unit processes are run without privileges in the host user namespace (regardless if the unit's own + user/group is <literal>root</literal> or not). Specifically this means that the process will have zero process + capabilities on the host's user namespace, but full capabilities within the service's user namespace. Settings + such as <varname>CapabilityBoundingSet=</varname> will affect only the latter, and there's no way to acquire + additional capabilities in the host's user namespace. Defaults to off.</para> + + <para>This setting is particularly useful in conjunction with <varname>RootDirectory=</varname>, as the need to + synchronize the user and group databases in the root directory and on the host is reduced, as the only users + and groups who need to be matched are <literal>root</literal>, <literal>nobody</literal> and the unit's own + user and group.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>ProtectSystem=</varname></term> - <listitem><para>Takes a boolean argument or - <literal>full</literal>. If true, mounts the - <filename>/usr</filename> and <filename>/boot</filename> - directories read-only for processes invoked by this unit. If - set to <literal>full</literal>, the <filename>/etc</filename> - directory is mounted read-only, too. This setting ensures that - any modification of the vendor-supplied operating system (and - optionally its configuration) is prohibited for the service. - It is recommended to enable this setting for all long-running - services, unless they are involved with system updates or need - to modify the operating system in other ways. Note however - that processes retaining the CAP_SYS_ADMIN capability can undo - the effect of this setting. This setting is hence particularly - useful for daemons which have this capability removed, for - example with <varname>CapabilityBoundingSet=</varname>. - Defaults to off.</para></listitem> + <listitem><para>Takes a boolean argument or the special values <literal>full</literal> or + <literal>strict</literal>. If true, mounts the <filename>/usr</filename> and <filename>/boot</filename> + directories read-only for processes invoked by this unit. If set to <literal>full</literal>, the + <filename>/etc</filename> directory is mounted read-only, too. If set to <literal>strict</literal> the entire + file system hierarchy is mounted read-only, except for the API file system subtrees <filename>/dev</filename>, + <filename>/proc</filename> and <filename>/sys</filename> (protect these directories using + <varname>PrivateDevices=</varname>, <varname>ProtectKernelTunables=</varname>, + <varname>ProtectControlGroups=</varname>). This setting ensures that any modification of the vendor-supplied + operating system (and optionally its configuration, and local mounts) is prohibited for the service. It is + recommended to enable this setting for all long-running services, unless they are involved with system updates + or need to modify the operating system in other ways. If this option is used, + <varname>ReadWritePaths=</varname> may be used to exclude specific directories from being made read-only. This + setting is implied if <varname>DynamicUser=</varname> is set. For this setting the same restrictions regarding + mount propagation and privileges apply as for <varname>ReadOnlyPaths=</varname> and related calls, see + above. Defaults to off.</para></listitem> </varlistentry> <varlistentry> <term><varname>ProtectHome=</varname></term> - <listitem><para>Takes a boolean argument or - <literal>read-only</literal>. If true, the directories - <filename>/home</filename>, <filename>/root</filename> and - <filename>/run/user</filename> - are made inaccessible and empty for processes invoked by this - unit. If set to <literal>read-only</literal>, the three - directories are made read-only instead. It is recommended to - enable this setting for all long-running services (in - particular network-facing ones), to ensure they cannot get - access to private user data, unless the services actually - require access to the user's private data. Note however that - processes retaining the CAP_SYS_ADMIN capability can undo the - effect of this setting. This setting is hence particularly - useful for daemons which have this capability removed, for - example with <varname>CapabilityBoundingSet=</varname>. - Defaults to off.</para></listitem> + <listitem><para>Takes a boolean argument or <literal>read-only</literal>. If true, the directories + <filename>/home</filename>, <filename>/root</filename> and <filename>/run/user</filename> are made inaccessible + and empty for processes invoked by this unit. If set to <literal>read-only</literal>, the three directories are + made read-only instead. It is recommended to enable this setting for all long-running services (in particular + network-facing ones), to ensure they cannot get access to private user data, unless the services actually + require access to the user's private data. This setting is implied if <varname>DynamicUser=</varname> is + set. For this setting the same restrictions regarding mount propagation and privileges apply as for + <varname>ReadOnlyPaths=</varname> and related calls, see above.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ProtectKernelTunables=</varname></term> + + <listitem><para>Takes a boolean argument. If true, kernel variables accessible through + <filename>/proc/sys</filename>, <filename>/sys</filename>, <filename>/proc/sysrq-trigger</filename>, + <filename>/proc/latency_stats</filename>, <filename>/proc/acpi</filename>, + <filename>/proc/timer_stats</filename>, <filename>/proc/fs</filename> and <filename>/proc/irq</filename> will + be made read-only to all processes of the unit. Usually, tunable kernel variables should only be written at + boot-time, with the <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> + mechanism. Almost no services need to write to these at runtime; it is hence recommended to turn this on for + most services. For this setting the same restrictions regarding mount propagation and privileges apply as for + <varname>ReadOnlyPaths=</varname> and related calls, see above. Defaults to off. + Note that this option does not prevent kernel tuning through IPC interfaces and external programs. However + <varname>InaccessiblePaths=</varname> can be used to make some IPC file system objects + inaccessible.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ProtectControlGroups=</varname></term> + + <listitem><para>Takes a boolean argument. If true, the Linux Control Groups (<citerefentry + project='man-pages'><refentrytitle>cgroups</refentrytitle><manvolnum>7</manvolnum></citerefentry>) hierarchies + accessible through <filename>/sys/fs/cgroup</filename> will be made read-only to all processes of the + unit. Except for container managers no services should require write access to the control groups hierarchies; + it is hence recommended to turn this on for most services. For this setting the same restrictions regarding + mount propagation and privileges apply as for <varname>ReadOnlyPaths=</varname> and related calls, see + above. Defaults to off.</para></listitem> </varlistentry> <varlistentry> <term><varname>MountFlags=</varname></term> - <listitem><para>Takes a mount propagation flag: - <option>shared</option>, <option>slave</option> or - <option>private</option>, which control whether mounts in the - file system namespace set up for this unit's processes will - receive or propagate mounts or unmounts. See - <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details. Defaults to <option>shared</option>. Use - <option>shared</option> to ensure that mounts and unmounts are - propagated from the host to the container and vice versa. Use - <option>slave</option> to run processes so that none of their - mounts and unmounts will propagate to the host. Use - <option>private</option> to also ensure that no mounts and - unmounts from the host will propagate into the unit processes' - namespace. Note that <option>slave</option> means that file - systems mounted on the host might stay mounted continuously in - the unit's namespace, and thus keep the device busy. Note that - the file system namespace related options - (<varname>PrivateTmp=</varname>, - <varname>PrivateDevices=</varname>, - <varname>ProtectSystem=</varname>, - <varname>ProtectHome=</varname>, - <varname>ReadOnlyPaths=</varname>, - <varname>InaccessiblePaths=</varname> and - <varname>ReadWritePaths=</varname>) require that mount - and unmount propagation from the unit's file system namespace - is disabled, and hence downgrade <option>shared</option> to + <listitem><para>Takes a mount propagation flag: <option>shared</option>, <option>slave</option> or + <option>private</option>, which control whether mounts in the file system namespace set up for this unit's + processes will receive or propagate mounts or unmounts. See <citerefentry + project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>2</manvolnum></citerefentry> for + details. Defaults to <option>shared</option>. Use <option>shared</option> to ensure that mounts and unmounts + are propagated from the host to the container and vice versa. Use <option>slave</option> to run processes so + that none of their mounts and unmounts will propagate to the host. Use <option>private</option> to also ensure + that no mounts and unmounts from the host will propagate into the unit processes' namespace. Note that + <option>slave</option> means that file systems mounted on the host might stay mounted continuously in the + unit's namespace, and thus keep the device busy. Note that the file system namespace related options + (<varname>PrivateTmp=</varname>, <varname>PrivateDevices=</varname>, <varname>ProtectSystem=</varname>, + <varname>ProtectHome=</varname>, <varname>ProtectKernelTunables=</varname>, + <varname>ProtectControlGroups=</varname>, <varname>ReadOnlyPaths=</varname>, + <varname>InaccessiblePaths=</varname>, <varname>ReadWritePaths=</varname>) require that mount and unmount + propagation from the unit's file system namespace is disabled, and hence downgrade <option>shared</option> to <option>slave</option>. </para></listitem> </varlistentry> @@ -1150,42 +1234,49 @@ <varlistentry> <term><varname>NoNewPrivileges=</varname></term> - <listitem><para>Takes a boolean argument. If true, ensures - that the service process and all its children can never gain - new privileges. This option is more powerful than the - respective secure bits flags (see above), as it also prohibits - UID changes of any kind. This is the simplest, most effective - way to ensure that a process and its children can never - elevate privileges again.</para></listitem> + <listitem><para>Takes a boolean argument. If true, ensures that the service + process and all its children can never gain new privileges. This option is more + powerful than the respective secure bits flags (see above), as it also prohibits + UID changes of any kind. This is the simplest and most effective way to ensure that + a process and its children can never elevate privileges again. Defaults to false, + but in the user manager instance certain settings force + <varname>NoNewPrivileges=yes</varname>, ignoring the value of this setting. + Those is the case when <varname>SystemCallFilter=</varname>, + <varname>SystemCallArchitectures=</varname>, + <varname>RestrictAddressFamilies=</varname>, + <varname>PrivateDevices=</varname>, + <varname>ProtectKernelTunables=</varname>, + <varname>ProtectKernelModules=</varname>, + <varname>MemoryDenyWriteExecute=</varname>, or + <varname>RestrictRealtime=</varname> are specified. + </para></listitem> </varlistentry> <varlistentry> <term><varname>SystemCallFilter=</varname></term> - <listitem><para>Takes a space-separated list of system call - names. If this setting is used, all system calls executed by - the unit processes except for the listed ones will result in - immediate process termination with the - <constant>SIGSYS</constant> signal (whitelisting). If the - first character of the list is <literal>~</literal>, the - effect is inverted: only the listed system calls will result - in immediate process termination (blacklisting). If running in - user mode, or in system mode, but without the - <constant>CAP_SYS_ADMIN</constant> capability (e.g. setting - <varname>User=nobody</varname>), - <varname>NoNewPrivileges=yes</varname> is implied. This - feature makes use of the Secure Computing Mode 2 interfaces of - the kernel ('seccomp filtering') and is useful for enforcing a - minimal sandboxing environment. Note that the - <function>execve</function>, - <function>rt_sigreturn</function>, - <function>sigreturn</function>, - <function>exit_group</function>, <function>exit</function> - system calls are implicitly whitelisted and do not need to be - listed explicitly. This option may be specified more than once, - in which case the filter masks are merged. If the empty string - is assigned, the filter is reset, all prior assignments will - have no effect. This does not affect commands prefixed with <literal>+</literal>.</para> + <listitem><para>Takes a space-separated list of system call names. If this setting is used, all system calls + executed by the unit processes except for the listed ones will result in immediate process termination with the + <constant>SIGSYS</constant> signal (whitelisting). If the first character of the list is <literal>~</literal>, + the effect is inverted: only the listed system calls will result in immediate process termination + (blacklisting). If running in user mode, or in system mode, but without the <constant>CAP_SYS_ADMIN</constant> + capability (e.g. setting <varname>User=nobody</varname>), <varname>NoNewPrivileges=yes</varname> is + implied. This feature makes use of the Secure Computing Mode 2 interfaces of the kernel ('seccomp filtering') + and is useful for enforcing a minimal sandboxing environment. Note that the <function>execve</function>, + <function>exit</function>, <function>exit_group</function>, <function>getrlimit</function>, + <function>rt_sigreturn</function>, <function>sigreturn</function> system calls and the system calls for + querying time and sleeping are implicitly whitelisted and do not need to be listed explicitly. This option may + be specified more than once, in which case the filter masks are merged. If the empty string is assigned, the + filter is reset, all prior assignments will have no effect. This does not affect commands prefixed with + <literal>+</literal>.</para> + + <para>Note that strict system call filters may impact execution and error handling code paths of the service + invocation. Specifically, access to the <function>execve</function> system call is required for the execution + of the service binary — if it is blocked service invocation will necessarily fail. Also, if execution of the + service binary fails for some reason (for example: missing service executable), the error handling logic might + require access to an additional set of system calls in order to process and log this failure correctly. It + might be necessary to temporarily disable system call filters in order to simplify debugging of such + failures.</para> <para>If you specify both types of this option (i.e. whitelisting and blacklisting), the first encountered will @@ -1219,6 +1310,10 @@ </thead> <tbody> <row> + <entry>@basic-io</entry> + <entry>System calls for basic I/O: reading, writing, seeking, file descriptor duplication and closing (<citerefentry project='man-pages'><refentrytitle>read</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>write</refentrytitle><manvolnum>2</manvolnum></citerefentry>, and related calls)</entry> + </row> + <row> <entry>@clock</entry> <entry>System calls for changing the system clock (<citerefentry project='man-pages'><refentrytitle>adjtimex</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>settimeofday</refentrytitle><manvolnum>2</manvolnum></citerefentry>, and related calls)</entry> </row> @@ -1236,7 +1331,7 @@ </row> <row> <entry>@ipc</entry> - <entry>SysV IPC, POSIX Message Queues or other IPC (<citerefentry project='man-pages'><refentrytitle>mq_overview</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>svipc</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> + <entry>Pipes, SysV IPC, POSIX Message Queues and other IPC (<citerefentry project='man-pages'><refentrytitle>mq_overview</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>svipc</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> </row> <row> <entry>@keyring</entry> @@ -1264,18 +1359,30 @@ </row> <row> <entry>@process</entry> - <entry>Process control, execution, namespaces (<citerefentry project='man-pages'><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>namespaces</refentrytitle><manvolnum>7</manvolnum></citerefentry>, …</entry> + <entry>Process control, execution, namespaces (<citerefentry project='man-pages'><refentrytitle>clone</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>namespaces</refentrytitle><manvolnum>7</manvolnum></citerefentry>, …</entry> </row> <row> <entry>@raw-io</entry> - <entry>Raw I/O port access (<citerefentry project='man-pages'><refentrytitle>ioperm</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>iopl</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <function>pciconfig_read()</function>, …</entry> + <entry>Raw I/O port access (<citerefentry project='man-pages'><refentrytitle>ioperm</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>iopl</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <function>pciconfig_read()</function>, …)</entry> + </row> + <row> + <entry>@resources</entry> + <entry>System calls for changing resource limits, memory and scheduling parameters (<citerefentry project='man-pages'><refentrytitle>setrlimit</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>setpriority</refentrytitle><manvolnum>2</manvolnum></citerefentry>, …)</entry> </row> </tbody> </tgroup> </table> - Note, that as new system calls are added to the kernel, additional system calls might be added to the groups - above, so the contents of the sets may change between systemd versions.</para></listitem> + Note that as new system calls are added to the kernel, additional system calls might be added to the groups + above, so the contents of the sets may change between systemd versions.</para> + + <para>It is recommended to combine the file system namespacing related options with + <varname>SystemCallFilter=~@mount</varname>, in order to prohibit the unit's processes to undo the + mappings. Specifically these are the options <varname>PrivateTmp=</varname>, + <varname>PrivateDevices=</varname>, <varname>ProtectSystem=</varname>, <varname>ProtectHome=</varname>, + <varname>ProtectKernelTunables=</varname>, <varname>ProtectControlGroups=</varname>, + <varname>ReadOnlyPaths=</varname>, <varname>InaccessiblePaths=</varname> and + <varname>ReadWritePaths=</varname>.</para></listitem> </varlistentry> <varlistentry> @@ -1295,27 +1402,25 @@ <varlistentry> <term><varname>SystemCallArchitectures=</varname></term> - <listitem><para>Takes a space-separated list of architecture - identifiers to include in the system call filter. The known - architecture identifiers are <constant>x86</constant>, - <constant>x86-64</constant>, <constant>x32</constant>, - <constant>arm</constant> as well as the special identifier - <constant>native</constant>. Only system calls of the - specified architectures will be permitted to processes of this - unit. This is an effective way to disable compatibility with - non-native architectures for processes, for example to - prohibit execution of 32-bit x86 binaries on 64-bit x86-64 - systems. The special <constant>native</constant> identifier - implicitly maps to the native architecture of the system (or - more strictly: to the architecture the system manager is - compiled for). If running in user mode, or in system mode, - but without the <constant>CAP_SYS_ADMIN</constant> - capability (e.g. setting <varname>User=nobody</varname>), - <varname>NoNewPrivileges=yes</varname> is implied. Note - that setting this option to a non-empty list implies that - <constant>native</constant> is included too. By default, this - option is set to the empty list, i.e. no architecture system - call filtering is applied.</para></listitem> + <listitem><para>Takes a space-separated list of architecture identifiers to + include in the system call filter. The known architecture identifiers are the same + as for <varname>ConditionArchitecture=</varname> described in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + as well as <constant>x32</constant>, <constant>mips64-n32</constant>, + <constant>mips64-le-n32</constant>, and the special identifier + <constant>native</constant>. Only system calls of the specified architectures will + be permitted to processes of this unit. This is an effective way to disable + compatibility with non-native architectures for processes, for example to prohibit + execution of 32-bit x86 binaries on 64-bit x86-64 systems. The special + <constant>native</constant> identifier implicitly maps to the native architecture + of the system (or more strictly: to the architecture the system manager is + compiled for). If running in user mode, or in system mode, but without the + <constant>CAP_SYS_ADMIN</constant> capability (e.g. setting + <varname>User=nobody</varname>), <varname>NoNewPrivileges=yes</varname> is + implied. Note that setting this option to a non-empty list implies that + <constant>native</constant> is included too. By default, this option is set to the + empty list, i.e. no architecture system call filtering is applied. + </para></listitem> </varlistentry> <varlistentry> @@ -1358,6 +1463,26 @@ </varlistentry> <varlistentry> + <term><varname>ProtectKernelModules=</varname></term> + + <listitem><para>Takes a boolean argument. If true, explicit module loading will + be denied. This allows to turn off module load and unload operations on modular + kernels. It is recommended to turn this on for most services that do not need special + file systems or extra kernel modules to work. Default to off. Enabling this option + removes <constant>CAP_SYS_MODULE</constant> from the capability bounding set for + the unit, and installs a system call filter to block module system calls, + also <filename>/usr/lib/modules</filename> is made inaccessible. For this + setting the same restrictions regarding mount propagation and privileges + apply as for <varname>ReadOnlyPaths=</varname> and related calls, see above. + Note that limited automatic module loading due to user configuration or kernel + mapping tables might still happen as side effect of requested user operations, + both privileged and unprivileged. To disable module auto-load feature please see + <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> + <constant>kernel.modules_disabled</constant> mechanism and + <filename>/proc/sys/kernel/modules_disabled</filename> documentation.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>Personality=</varname></term> <listitem><para>Controls which kernel architecture <citerefentry @@ -1403,12 +1528,15 @@ <term><varname>MemoryDenyWriteExecute=</varname></term> <listitem><para>Takes a boolean argument. If set, attempts to create memory mappings that are writable and - executable at the same time, or to change existing memory mappings to become executable are prohibited. + executable at the same time, or to change existing memory mappings to become executable, or mapping shared memory + segments as executable are prohibited. Specifically, a system call filter is added that rejects <citerefentry><refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum></citerefentry> - system calls with both <constant>PROT_EXEC</constant> and <constant>PROT_WRITE</constant> set - and <citerefentry><refentrytitle>mprotect</refentrytitle><manvolnum>2</manvolnum></citerefentry> - system calls with <constant>PROT_EXEC</constant> set. Note that this option is incompatible with programs + system calls with both <constant>PROT_EXEC</constant> and <constant>PROT_WRITE</constant> set, + <citerefentry><refentrytitle>mprotect</refentrytitle><manvolnum>2</manvolnum></citerefentry> + system calls with <constant>PROT_EXEC</constant> set and + <citerefentry><refentrytitle>shmat</refentrytitle><manvolnum>2</manvolnum></citerefentry> + system calls with <constant>SHM_EXEC</constant> set. Note that this option is incompatible with programs that generate program code dynamically at runtime, such as JIT execution engines, or programs compiled making use of the code "trampoline" feature of various C compilers. This option improves service security, as it makes harder for software exploits to change running code dynamically. @@ -1421,7 +1549,7 @@ <listitem><para>Takes a boolean argument. If set, any attempts to enable realtime scheduling in a process of the unit are refused. This restricts access to realtime task scheduling policies such as <constant>SCHED_FIFO</constant>, <constant>SCHED_RR</constant> or <constant>SCHED_DEADLINE</constant>. See - <citerefentry><refentrytitle>sched</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details about + <citerefentry project='man-pages'><refentrytitle>sched</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details about these scheduling policies. Realtime scheduling policies may be used to monopolize CPU time for longer periods of time, and may hence be used to lock up or otherwise trigger Denial-of-Service situations on the system. It is hence recommended to restrict access to realtime scheduling to the few programs that actually require @@ -1478,6 +1606,16 @@ </varlistentry> <varlistentry> + <term><varname>$INVOCATION_ID</varname></term> + + <listitem><para>Contains a randomized, unique 128bit ID identifying each runtime cycle of the unit, formatted + as 32 character hexadecimal string. A new ID is assigned each time the unit changes from an inactive state into + an activating or active state, and may be used to identify this specific runtime cycle, in particular in data + stored offline, such as the journal. The same ID is passed to all processes run as part of the + unit.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>$XDG_RUNTIME_DIR</varname></term> <listitem><para>The directory for volatile state. Set for the @@ -1503,7 +1641,7 @@ <varlistentry> <term><varname>$MAINPID</varname></term> - <listitem><para>The PID of the units main process if it is + <listitem><para>The PID of the unit's main process if it is known. This is only set for control processes as invoked by <varname>ExecReload=</varname> and similar. </para></listitem> </varlistentry> @@ -1574,6 +1712,118 @@ functions) if their standard output or standard error output is connected to the journal anyway, thus enabling delivery of structured metadata along with logged messages.</para></listitem> </varlistentry> + + <varlistentry> + <term><varname>$SERVICE_RESULT</varname></term> + + <listitem><para>Only defined for the service unit type, this environment variable is passed to all + <varname>ExecStop=</varname> and <varname>ExecStopPost=</varname> processes, and encodes the service + "result". Currently, the following values are defined: <literal>timeout</literal> (in case of an operation + timeout), <literal>exit-code</literal> (if a service process exited with a non-zero exit code; see + <varname>$EXIT_CODE</varname> below for the actual exit code returned), <literal>signal</literal> (if a + service process was terminated abnormally by a signal; see <varname>$EXIT_CODE</varname> below for the actual + signal used for the termination), <literal>core-dump</literal> (if a service process terminated abnormally and + dumped core), <literal>watchdog</literal> (if the watchdog keep-alive ping was enabled for the service but it + missed the deadline), or <literal>resources</literal> (a catch-all condition in case a system operation + failed).</para> + + <para>This environment variable is useful to monitor failure or successful termination of a service. Even + though this variable is available in both <varname>ExecStop=</varname> and <varname>ExecStopPost=</varname>, it + is usually a better choice to place monitoring tools in the latter, as the former is only invoked for services + that managed to start up correctly, and the latter covers both services that failed during their start-up and + those which failed during their runtime.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$EXIT_CODE</varname></term> + <term><varname>$EXIT_STATUS</varname></term> + + <listitem><para>Only defined for the service unit type, these environment variables are passed to all + <varname>ExecStop=</varname>, <varname>ExecStopPost=</varname> processes and contain exit status/code + information of the main process of the service. For the precise definition of the exit code and status, see + <citerefentry><refentrytitle>wait</refentrytitle><manvolnum>2</manvolnum></citerefentry>. <varname>$EXIT_CODE</varname> + is one of <literal>exited</literal>, <literal>killed</literal>, + <literal>dumped</literal>. <varname>$EXIT_STATUS</varname> contains the numeric exit code formatted as string + if <varname>$EXIT_CODE</varname> is <literal>exited</literal>, and the signal name in all other cases. Note + that these environment variables are only set if the service manager succeeded to start and identify the main + process of the service.</para> + + <table> + <title>Summary of possible service result variable values</title> + <tgroup cols='3'> + <colspec colname='result' /> + <colspec colname='status' /> + <colspec colname='code' /> + <thead> + <row> + <entry><varname>$SERVICE_RESULT</varname></entry> + <entry><varname>$EXIT_STATUS</varname></entry> + <entry><varname>$EXIT_CODE</varname></entry> + </row> + </thead> + + <tbody> + <row> + <entry morerows="1" valign="top"><literal>timeout</literal></entry> + <entry valign="top"><literal>killed</literal></entry> + <entry><literal>TERM</literal>, <literal>KILL</literal></entry> + </row> + + <row> + <entry valign="top"><literal>exited</literal></entry> + <entry><literal>0</literal>, <literal>1</literal>, <literal>2</literal>, <literal + >3</literal>, …, <literal>255</literal></entry> + </row> + + <row> + <entry valign="top"><literal>exit-code</literal></entry> + <entry valign="top"><literal>exited</literal></entry> + <entry><literal>0</literal>, <literal>1</literal>, <literal>2</literal>, <literal + >3</literal>, …, <literal>255</literal></entry> + </row> + + <row> + <entry valign="top"><literal>signal</literal></entry> + <entry valign="top"><literal>killed</literal></entry> + <entry><literal>HUP</literal>, <literal>INT</literal>, <literal>KILL</literal>, …</entry> + </row> + + <row> + <entry valign="top"><literal>core-dump</literal></entry> + <entry valign="top"><literal>dumped</literal></entry> + <entry><literal>ABRT</literal>, <literal>SEGV</literal>, <literal>QUIT</literal>, …</entry> + </row> + + <row> + <entry morerows="2" valign="top"><literal>watchdog</literal></entry> + <entry><literal>dumped</literal></entry> + <entry><literal>ABRT</literal></entry> + </row> + <row> + <entry><literal>killed</literal></entry> + <entry><literal>TERM</literal>, <literal>KILL</literal></entry> + </row> + <row> + <entry><literal>exited</literal></entry> + <entry><literal>0</literal>, <literal>1</literal>, <literal>2</literal>, <literal + >3</literal>, …, <literal>255</literal></entry> + </row> + + <row> + <entry><literal>resources</literal></entry> + <entry>any of the above</entry> + <entry>any of the above</entry> + </row> + + <row> + <entry namest="results" nameend="code">Note: the process may be also terminated by a signal not sent by systemd. In particular the process may send an arbitrary signal to itself in a handler for any of the non-maskable signals. Nevertheless, in the <literal>timeout</literal> and <literal>watchdog</literal> rows above only the signals that systemd sends have been included.</entry> + </row> + </tbody> + </tgroup> + </table> + + </listitem> + </varlistentry> </variablelist> <para>Additional variables may be configured by the following @@ -1609,4 +1859,5 @@ </para> </refsect1> + </refentry> diff --git a/man/systemd.link.xml b/man/systemd.link.xml index d5b4d1038d..8edbe758d9 100644 --- a/man/systemd.link.xml +++ b/man/systemd.link.xml @@ -107,7 +107,7 @@ <listitem> <para>A whitespace-separated list of shell-style globs matching the device name, as exposed by the udev property - "INTERFACE". This can not be used to match on names that have + "INTERFACE". This cannot be used to match on names that have already been changed from userspace. Caution is advised when matching on kernel-assigned names, as they are known to be unstable between reboots.</para> @@ -387,6 +387,46 @@ </variablelist> </listitem> </varlistentry> + <varlistentry> + <term><varname>TCPSegmentationOffload=</varname></term> + <listitem> + <para>The TCP Segmentation Offload (TSO) when true enables + TCP segmentation offload. Takes a boolean value. + Defaults to "unset".</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>GenericSegmentationOffload=</varname></term> + <listitem> + <para>The Generic Segmentation Offload (GSO) when true enables + generic segmentation offload. Takes a boolean value. + Defaults to "unset".</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>UDPSegmentationOffload=</varname></term> + <listitem> + <para>The UDP Segmentation Offload (USO) when true enables + UDP segmentation offload. Takes a boolean value. + Defaults to "unset".</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>GenericReceiveOffload=</varname></term> + <listitem> + <para>The Generic Receive Offload (GRO) when true enables + generic receive offload. Takes a boolean value. + Defaults to "unset".</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>LargeReceiveOffload=</varname></term> + <listitem> + <para>The Large Receive Offload (LRO) when true enables + large receive offload. Takes a boolean value. + Defaults to "unset".</para> + </listitem> + </varlistentry> </variablelist> </refsect1> diff --git a/man/systemd.mount.xml b/man/systemd.mount.xml index 66cddd72e0..b0f156f6df 100644 --- a/man/systemd.mount.xml +++ b/man/systemd.mount.xml @@ -160,7 +160,7 @@ for details about the conversion.</para> <para>The NFS mount option <option>bg</option> for NFS background mounts - as documented in <citerefentry><refentrytitle>nfs</refentrytitle><manvolnum>5</manvolnum></citerefentry> + as documented in <citerefentry project='man-pages'><refentrytitle>nfs</refentrytitle><manvolnum>5</manvolnum></citerefentry> is not supported in <filename>/etc/fstab</filename> entries. The systemd mount option <option>nofail</option> provides similar functionality and should be used instead.</para> @@ -352,6 +352,30 @@ </varlistentry> <varlistentry> + <term><varname>LazyUnmount=</varname></term> + + <listitem><para>Takes a boolean argument. If true, detach the + filesystem from the filesystem hierarchy at time of the unmount + operation, and clean up all references to the filesystem as + soon as they are not busy anymore. + This corresponds with + <citerefentry project='man-pages'><refentrytitle>umount</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s + <parameter>-l</parameter> switch. Defaults to + off.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ForceUnmount=</varname></term> + + <listitem><para>Takes a boolean argument. If true, force an + unmount (in case of an unreachable NFS system). + This corresponds with + <citerefentry project='man-pages'><refentrytitle>umount</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s + <parameter>-f</parameter> switch. Defaults to + off.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>DirectoryMode=</varname></term> <listitem><para>Directories of mount points (and any parent directories) are automatically created if needed. This option @@ -373,7 +397,7 @@ Takes a unit-less value in seconds, or a time span value such as "5min 20s". Pass 0 to disable the timeout logic. The default value is set from the manager configuration file's - <varname>DefaultTimeoutStart=</varname> + <varname>DefaultTimeoutStartSec=</varname> variable.</para></listitem> </varlistentry> </variablelist> diff --git a/man/systemd.netdev.xml b/man/systemd.netdev.xml index a5c6f0fa40..ffb66e735b 100644 --- a/man/systemd.netdev.xml +++ b/man/systemd.netdev.xml @@ -58,31 +58,38 @@ <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>. </para> - <para>Virtual Network Device files must have the extension - <filename>.netdev</filename>; other extensions are ignored. - Virtual network devices are created as soon as networkd is - started. If a netdev with the specified name already exists, - networkd will use that as-is rather than create its own. Note that - the settings of the pre-existing netdev will not be changed by + <para>The main Virtual Network Device file must have the extension <filename>.netdev</filename>; + other extensions are ignored. Virtual network devices are created as soon as networkd is + started. If a netdev with the specified name already exists, networkd will use that as-is rather + than create its own. Note that the settings of the pre-existing netdev will not be changed by networkd.</para> - <para>The <filename>.netdev</filename> files are read from the - files located in the system network directory - <filename>/usr/lib/systemd/network</filename>, the volatile - runtime network directory - <filename>/run/systemd/network</filename> and the local - administration network directory - <filename>/etc/systemd/network</filename>. All configuration files - are collectively sorted and processed in lexical order, regardless - of the directories in which they live. However, files with - identical filenames replace each other. Files in - <filename>/etc</filename> have the highest priority, files in - <filename>/run</filename> take precedence over files with the same - name in <filename>/usr/lib</filename>. This can be used to - override a system-supplied configuration file with a local file if - needed. As a special case, an empty file (file size 0) or symlink - with the same name pointing to <filename>/dev/null</filename> - disables the configuration file entirely (it is "masked").</para> + <para>The <filename>.netdev</filename> files are read from the files located in the system + network directory <filename>/usr/lib/systemd/network</filename>, the volatile runtime network + directory <filename>/run/systemd/network</filename> and the local administration network + directory <filename>/etc/systemd/network</filename>. All configuration files are collectively + sorted and processed in lexical order, regardless of the directories in which they live. + However, files with identical filenames replace each other. Files in <filename>/etc</filename> + have the highest priority, files in <filename>/run</filename> take precedence over files with + the same name in <filename>/usr/lib</filename>. This can be used to override a system-supplied + configuration file with a local file if needed. As a special case, an empty file (file size 0) + or symlink with the same name pointing to <filename>/dev/null</filename> disables the + configuration file entirely (it is "masked").</para> + + <para>Along with the netdev file <filename>foo.netdev</filename>, a "drop-in" directory + <filename>foo.netdev.d/</filename> may exist. All files with the suffix <literal>.conf</literal> + from this directory will be parsed after the file itself is parsed. This is useful to alter or + add configuration settings, without having to modify the main configuration file. Each drop-in + file must have appropriate section headers.</para> + + <para>In addition to <filename>/etc/systemd/network</filename>, drop-in <literal>.d</literal> + directories can be placed in <filename>/usr/lib/systemd/network</filename> or + <filename>/run/systemd/network</filename> directories. Drop-in files in + <filename>/etc</filename> take precedence over those in <filename>/run</filename> which in turn + take precedence over those in <filename>/usr/lib</filename>. Drop-in files under any of these + directories take precedence over the main netdev file wherever located. (Of course, since + <filename>/run</filename> is temporary and <filename>/usr/lib</filename> is for vendors, it is + unlikely drop-ins should be used in either of those places.)</para> </refsect1> <refsect1> @@ -163,7 +170,10 @@ <entry>A virtual extensible LAN (vxlan), for connecting Cloud computing deployments.</entry></row> <row><entry><varname>vrf</varname></entry> - <entry>A Virtual Routing and Forwarding (<ulink url="https://www.kernel.org/doc/Documentation/networking/vrf.txt">VRF</ulink>) interface to create separate routing and forwarding domains.</entry></row> + <entry>A Virtual Routing and Forwarding (<ulink url="https://www.kernel.org/doc/Documentation/networking/vrf.txt">VRF</ulink>) interface to create separate routing and forwarding domains.</entry></row> + + <row><entry><varname>vcan</varname></entry> + <entry>The virtual CAN driver (vcan). Similar to the network loopback devices, vcan offers a virtual local CAN interface.</entry></row> </tbody> </tgroup> @@ -315,6 +325,26 @@ </listitem> </varlistentry> <varlistentry> + <term><varname>AgeingTimeSec=</varname></term> + <listitem> + <para>This specifies the number of seconds a MAC Address will be kept in + the forwarding database after having a packet received from this MAC Address.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Priority=</varname></term> + <listitem> + <para>The priority of the bridge. An integer between 0 and 65535. A lower value + means higher priority. The bridge having the lowest priority will be elected as root bridge.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>DefaultPVID=</varname></term> + <listitem> + <para>This specifies the default port VLAN ID of a newly attached bridge port.</para> + </listitem> + </varlistentry> + <varlistentry> <term><varname>MulticastQuerier=</varname></term> <listitem> <para>A boolean. This setting controls the IFLA_BR_MCAST_QUERIER option in the kernel. @@ -343,8 +373,15 @@ </para> </listitem> </varlistentry> + <varlistentry> + <term><varname>STP=</varname></term> + <listitem> + <para>A boolean. This enables the bridge's Spanning Tree Protocol (STP). When unset, + the kernel's default setting applies. + </para> + </listitem> + </varlistentry> </variablelist> - </refsect1> <refsect1> @@ -500,7 +537,7 @@ </listitem> </varlistentry> <varlistentry> - <term><varname>UDPCheckSum=</varname></term> + <term><varname>UDPChecksum=</varname></term> <listitem> <para>A boolean. When true, transmitting UDP checksums when doing VXLAN/IPv4 is turned on.</para> </listitem> @@ -512,11 +549,23 @@ </listitem> </varlistentry> <varlistentry> - <term><varname>UDP6ZeroCheckSumRx=</varname></term> + <term><varname>UDP6ZeroChecksumRx=</varname></term> <listitem> <para>A boolean. When true, receiving zero checksums in VXLAN/IPv6 is turned on.</para> </listitem> </varlistentry> + <varlistentry> + <term><varname>RemoteChecksumTx=</varname></term> + <listitem> + <para>A boolean. When true, remote transmit checksum offload of VXLAN is turned on.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>RemoteChecksumRx=</varname></term> + <listitem> + <para>A boolean. When true, remote receive checksum offload in VXLAN is turned on.</para> + </listitem> + </varlistentry> <varlistentry> <term><varname>GroupPolicyExtension=</varname></term> <listitem> diff --git a/man/systemd.network.xml b/man/systemd.network.xml index 4541a55490..2fb4907634 100644 --- a/man/systemd.network.xml +++ b/man/systemd.network.xml @@ -58,31 +58,40 @@ <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>. </para> - <para>Network files must have the extension - <filename>.network</filename>; other extensions are ignored. - Networks are applied to links whenever the links appear.</para> - - <para>The <filename>.network</filename> files are read from the - files located in the system network directory - <filename>/usr/lib/systemd/network</filename>, the volatile - runtime network directory - <filename>/run/systemd/network</filename> and the local - administration network directory - <filename>/etc/systemd/network</filename>. All configuration files - are collectively sorted and processed in lexical order, regardless - of the directories in which they live. However, files with - identical filenames replace each other. Files in - <filename>/etc</filename> have the highest priority, files in - <filename>/run</filename> take precedence over files with the same - name in <filename>/usr/lib</filename>. This can be used to - override a system-supplied configuration file with a local file if - needed. As a special case, an empty file (file size 0) or symlink - with the same name pointing to <filename>/dev/null</filename> - disables the configuration file entirely (it is "masked").</para> - - <para>Note that an interface without any static IPv6 addresses configured, and neither DHCPv6 nor IPv6LL enabled, - shall be considered to have no IPv6 support. IPv6 will be automatically disabled for that interface by writing "1" - to <filename>/proc/sys/net/ipv6/conf/<replaceable>ifname</replaceable>/disable_ipv6</filename>. + <para>The main network file must have the extension <filename>.network</filename>; other + extensions are ignored. Networks are applied to links whenever the links appear.</para> + + <para>The <filename>.network</filename> files are read from the files located in the system + network directory <filename>/usr/lib/systemd/network</filename>, the volatile runtime network + directory <filename>/run/systemd/network</filename> and the local administration network + directory <filename>/etc/systemd/network</filename>. All configuration files are collectively + sorted and processed in lexical order, regardless of the directories in which they live. + However, files with identical filenames replace each other. Files in <filename>/etc</filename> + have the highest priority, files in <filename>/run</filename> take precedence over files with + the same name in <filename>/usr/lib</filename>. This can be used to override a system-supplied + configuration file with a local file if needed. As a special case, an empty file (file size 0) + or symlink with the same name pointing to <filename>/dev/null</filename> disables the + configuration file entirely (it is "masked").</para> + + <para>Along with the network file <filename>foo.network</filename>, a "drop-in" directory + <filename>foo.network.d/</filename> may exist. All files with the suffix + <literal>.conf</literal> from this directory will be parsed after the file itself is + parsed. This is useful to alter or add configuration settings, without having to modify the main + configuration file. Each drop-in file must have appropriate section headers.</para> + + <para>In addition to <filename>/etc/systemd/network</filename>, drop-in <literal>.d</literal> + directories can be placed in <filename>/usr/lib/systemd/network</filename> or + <filename>/run/systemd/network</filename> directories. Drop-in files in + <filename>/etc</filename> take precedence over those in <filename>/run</filename> which in turn + take precedence over those in <filename>/usr/lib</filename>. Drop-in files under any of these + directories take precedence over the main netdev file wherever located. (Of course, since + <filename>/run</filename> is temporary and <filename>/usr/lib</filename> is for vendors, it is + unlikely drop-ins should be used in either of those places.)</para> + + <para>Note that an interface without any static IPv6 addresses configured, and neither DHCPv6 + nor IPv6LL enabled, shall be considered to have no IPv6 support. IPv6 will be automatically + disabled for that interface by writing "1" to + <filename>/proc/sys/net/ipv6/conf/<replaceable>ifname</replaceable>/disable_ipv6</filename>. </para> </refsect1> @@ -212,6 +221,17 @@ below 1280 (the minimum MTU for IPv6) it will automatically be increased to this value.</para> </listitem> </varlistentry> + <varlistentry> + <term><varname>ARP=</varname></term> + <listitem> + <para> A boolean. Enables or disables the ARP (low-level Address Resolution Protocol) + for this interface. Defaults to unset, which means that the kernel default will be used.</para> + <para> For example, disabling ARP is useful when creating multiple MACVLAN or VLAN virtual + interfaces atop a single lower-level physical interface, which will then only serve as a + link/"bridge" device aggregating traffic to the same physical link and not participate in + the network otherwise.</para> + </listitem> + </varlistentry> </variablelist> </refsect1> @@ -447,24 +467,31 @@ <varlistentry> <term><varname>Domains=</varname></term> <listitem> - <para>The domains used for DNS host name resolution on this link. Takes a list of DNS domain names which - are used as search suffixes for extending single-label host names (host names containing no dots) to become - fully qualified domain names (FQDNs). If a single-label host name is resolved on this interface, each of - the specified search domains are appended to it in turn, converting it into a fully qualified domain name, - until one of them may be successfully resolved.</para> - - <para>The specified domains are also used for routing of DNS queries: look-ups for host names ending in the - domains specified here are preferably routed to the DNS servers configured for this interface. If a domain - name is prefixed with <literal>~</literal>, the domain name becomes a pure "routing" domain, is used for - DNS query routing purposes only and is not used in the described domain search logic. By specifying a - routing domain of <literal>~.</literal> (the tilde indicating definition of a routing domain, the dot - referring to the DNS root domain which is the implied suffix of all valid DNS names) it is possible to - route all DNS traffic preferably to the DNS server specified for this interface. The route domain logic is - particularly useful on multi-homed hosts with DNS servers serving particular private DNS zones on each - interface.</para> + <para>A list of domains which should be resolved using the DNS servers on this link. Each item in the list + should be a domain name, optionally prefixed with a tilde (<literal>~</literal>). The domains with the + prefix are called "routing-only domains". The domains without the prefix are called "search domains" and + are first used as search suffixes for extending single-label host names (host names containing no dots) to + become fully qualified domain names (FQDNs). If a single-label host name is resolved on this interface, + each of the specified search domains are appended to it in turn, converting it into a fully qualified + domain name, until one of them may be successfully resolved.</para> + + <para>Both "search" and "routing-only" domains are used for routing of DNS queries: look-ups for host names + ending in those domains (hence also single label names, if any "search domains" are listed), are routed to + the DNS servers configured for this interface. The domain routing logic is particularly useful on + multi-homed hosts with DNS servers serving particular private DNS zones on each interface.</para> + + <para>The "routing-only" domain <literal>~.</literal> (the tilde indicating definition of a routing domain, + the dot referring to the DNS root domain which is the implied suffix of all valid DNS names) has special + effect. It causes all DNS traffic which does not match another configured domain routing entry to be routed + to DNS servers specified for this interface. This setting is useful to prefer a certain set of DNS servers + if a link on which they are connected is available.</para> <para>This setting is read by - <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + "Search domains" correspond to the <varname>domain</varname> and <varname>search</varname> entries in + <citerefentry><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + Domain name routing has no equivalent in the traditional glibc API, which has no concept of domain + name servers limited to a specific link.</para> </listitem> </varlistentry> <varlistentry> @@ -668,6 +695,57 @@ which is then configured to use them explicitly.</para> </listitem> </varlistentry> + <varlistentry> + <term><varname>HomeAddress=</varname></term> + <listitem> + <para>Takes a boolean argument. Designates this address the "home address" as defined in + <ulink url="https://tools.ietf.org/html/rfc6275">RFC 6275</ulink>. + Supported only on IPv6. Defaults to false.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>DuplicateAddressDetection=</varname></term> + <listitem> + <para>Takes a boolean argument. Do not perform Duplicate Address Detection + <ulink url="https://tools.ietf.org/html/rfc4862">RFC 4862</ulink> when adding this address. + Supported only on IPv6. Defaults to false.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>ManageTemporaryAddress=</varname></term> + <listitem> + <para>Takes a boolean argument. If true the kernel manage temporary addresses created + from this one as template on behalf of Privacy Extensions + <ulink url="https://tools.ietf.org/html/rfc3041">RFC 3041</ulink>. For this to become + active, the use_tempaddr sysctl setting has to be set to a value greater than zero. + The given address needs to have a prefix length of 64. This flag allows to use privacy + extensions in a manually configured network, just like if stateless auto-configuration + was active. Defaults to false. </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>PrefixRoute=</varname></term> + <listitem> + <para>Takes a boolean argument. When adding or modifying an IPv6 address, the userspace + application needs a way to suppress adding a prefix route. This is for example relevant + together with IFA_F_MANAGERTEMPADDR, where userspace creates autoconf generated addresses, + but depending on on-link, no route for the prefix should be added. Defaults to false.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>AutoJoin=</varname></term> + <listitem> + <para>Takes a boolean argument. Joining multicast group on ethernet level via + <command>ip maddr</command> command would not work if we have an Ethernet switch that does + IGMP snooping since the switch would not replicate multicast packets on ports that did not + have IGMP reports for the multicast addresses. Linux vxlan interfaces created via + <command>ip link add vxlan</command> or networkd's netdev kind vxlan have the group option + that enables then to do the required join. By extending ip address command with option + <literal>autojoin</literal> we can get similar functionality for openvswitch (OVS) vxlan + interfaces as well as other tunneling mechanisms that need to receive multicast traffic. + Defaults to <literal>no</literal>.</para> + </listitem> + </varlistentry> </variablelist> </refsect1> @@ -897,6 +975,15 @@ DHCP server.</para> </listitem> </varlistentry> + + <varlistentry> + <term><varname>RouteTable=<replaceable>num</replaceable></varname></term> + <listitem> + <para>The table identifier for DHCP routes (a number between 1 and 4294967295, or 0 to unset). + The table can be retrieved using <command>ip route show table <replaceable>num</replaceable></command>. + </para> + </listitem> + </varlistentry> </variablelist> </refsect1> @@ -937,6 +1024,16 @@ project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> </listitem> </varlistentry> + + <varlistentry> + <term><varname>RouteTable=<replaceable>num</replaceable></varname></term> + <listitem> + <para>The table identifier for the routes received in the Router Advertisement + (a number between 1 and 4294967295, or 0 to unset). + The table can be retrieved using <command>ip route show table <replaceable>num</replaceable></command>. + </para> + </listitem> + </varlistentry> </variablelist> </refsect1> diff --git a/man/systemd.offline-updates.xml b/man/systemd.offline-updates.xml index ae53b8552d..07a5225512 100644 --- a/man/systemd.offline-updates.xml +++ b/man/systemd.offline-updates.xml @@ -77,7 +77,7 @@ <listitem> <para>Very early in the new boot - <citerefentry><refentrytitle>systemd-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + <citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> checks whether <filename>/system-update</filename> exists. If so, it (temporarily and for this boot only) redirects (i.e. symlinks) <filename>default.target</filename> to <filename>system-update.target</filename>, a special target that is pulls in the base system @@ -143,7 +143,7 @@ <varname>FailureAction=</varname> makes sure that the specified unit is activated if your script exits uncleanly (by non-zero error code, or signal/coredump). If your script succeeds you should trigger the reboot in your own code, for example by invoking logind's - <command>Reboot()</command> call or calling <command>systemct reboot</command>. See + <command>Reboot()</command> call or calling <command>systemctl reboot</command>. See <ulink url="http://www.freedesktop.org/wiki/Software/systemd/logind">logind dbus API</ulink> for details.</para> </listitem> @@ -162,8 +162,8 @@ <ulink url="http://www.freedesktop.org/wiki/Software/systemd/SystemUpdates/">Implementing Offline System Updates</ulink>, <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>dnf.plugin.system-upgrade</refentrytitle><manvolnum>8</manvolnum></citerefentry> + <citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='mankier'><refentrytitle>dnf.plugin.system-upgrade</refentrytitle><manvolnum>8</manvolnum></citerefentry> </para> </refsect1> </refentry> diff --git a/man/systemd.preset.xml b/man/systemd.preset.xml index b7164014f0..d09167baaf 100644 --- a/man/systemd.preset.xml +++ b/man/systemd.preset.xml @@ -98,6 +98,10 @@ Empty lines and lines whose first non-whitespace character is # or ; are ignored.</para> + <para>Presets must refer to the "real" unit file, and not to any aliases. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for a description of unit aliasing.</para> + <para>Two different directives are understood: <literal>enable</literal> may be used to enable units by default, <literal>disable</literal> to disable units by default.</para> diff --git a/man/systemd.resource-control.xml b/man/systemd.resource-control.xml index bf44a68345..02878b28a0 100644 --- a/man/systemd.resource-control.xml +++ b/man/systemd.resource-control.xml @@ -60,12 +60,10 @@ <refsect1> <title>Description</title> - <para>Unit configuration files for services, slices, scopes, - sockets, mount points, and swap devices share a subset of - configuration options for resource control of spawned - processes. Internally, this relies on the Control Groups - kernel concept for organizing processes in a hierarchical tree of - named groups for the purpose of resource management.</para> + <para>Unit configuration files for services, slices, scopes, sockets, mount points, and swap devices share a subset + of configuration options for resource control of spawned processes. Internally, this relies on the Linux Control + Groups (cgroups) kernel concept for organizing processes in a hierarchical tree of named groups for the purpose of + resource management.</para> <para>This man page lists the configuration options shared by those six unit types. See @@ -83,6 +81,11 @@ [Slice], [Scope], [Service], [Socket], [Mount], or [Swap] sections, depending on the unit type.</para> + <para>In addition, options which control resources available to programs + <emphasis>executed</emphasis> by systemd are listed in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + Those options complement options listed here.</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 @@ -99,19 +102,28 @@ <refsect1> <title>Unified and Legacy Control Group Hierarchies</title> - <para>The unified control group hierarchy is the new version of kernel control group interface. Depending on the - resource type, there are differences in resource control capabilities. Also, because of interface changes, some - resource types have a separate set of options on the unified hierarchy.</para> + <para>The unified control group hierarchy is the new version of kernel control group interface, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>. Depending on the resource type, + there are differences in resource control capabilities. Also, because of interface changes, some resource types + have separate set of options on the unified hierarchy.</para> <para> <variablelist> + <varlistentry> - <term><option>IO</option></term> + <term><option>CPU</option></term> <listitem> - <para><varname>IO</varname> prefixed settings are superset of and replace <varname>BlockIO</varname> - prefixed ones. On unified hierarchy, IO resource control also applies to buffered writes.</para> + <para>Due to the lack of consensus in the kernel community, the CPU controller support on the unified + control group hierarchy requires out-of-tree kernel patches. See <ulink + url="https://git.kernel.org/cgit/linux/kernel/git/tj/cgroup.git/tree/Documentation/cgroup-v2-cpu.txt?h=cgroup-v2-cpu">cgroup-v2-cpu.txt</ulink>.</para> + + <para><varname>CPUWeight=</varname> and <varname>StartupCPUWeight=</varname> replace + <varname>CPUShares=</varname> and <varname>StartupCPUShares=</varname>, respectively.</para> + + <para>The <literal>cpuacct</literal> controller does not exist separately on the unified hierarchy.</para> </listitem> </varlistentry> + <varlistentry> <term><option>Memory</option></term> <listitem> @@ -119,13 +131,29 @@ and <varname>MemoryHigh=</varname> are effective only on unified hierarchy.</para> </listitem> </varlistentry> + + <varlistentry> + <term><option>IO</option></term> + <listitem> + <para><varname>IO</varname> prefixed settings are superset of and replace <varname>BlockIO</varname> + prefixed ones. On unified hierarchy, IO resource control also applies to buffered writes.</para> + </listitem> + </varlistentry> + </variablelist> </para> - <para>To ease the transition, there is best-effort translation between the two versions of settings. If all - settings of a unit for a given resource type are for the other hierarchy type, the settings are translated and - applied. If there are any valid settings for the hierarchy in use, all translations are disabled for the resource - type. Mixing the two types of settings on a unit can lead to confusing results.</para> + <para>To ease the transition, there is best-effort translation between the two versions of settings. For each + controller, if any of the settings for the unified hierarchy are present, all settings for the legacy hierarchy are + ignored. If the resulting settings are for the other type of hierarchy, the configurations are translated before + application.</para> + + <para>Legacy control group hierarchy (see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v1/cgroups.txt">cgroups.txt</ulink>), also called cgroup-v1, + doesn't allow safe delegation of controllers to unprivileged processes. If the system uses the legacy control group + hierarchy, resource control is disabled for systemd user instance, see + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + </para> </refsect1> <refsect1> @@ -152,30 +180,26 @@ </varlistentry> <varlistentry> - <term><varname>CPUShares=<replaceable>weight</replaceable></varname></term> - <term><varname>StartupCPUShares=<replaceable>weight</replaceable></varname></term> + <term><varname>CPUWeight=<replaceable>weight</replaceable></varname></term> + <term><varname>StartupCPUWeight=<replaceable>weight</replaceable></varname></term> <listitem> - <para>Assign the specified CPU time share weight to the - processes executed. These options take an integer value and - control the <literal>cpu.shares</literal> control group - attribute. The allowed range is 2 to 262144. Defaults to - 1024. For details about this control group attribute, see - <ulink + <para>Assign the specified CPU time weight to the processes executed, if the unified control group hierarchy + is used on the system. These options take an integer value and control the <literal>cpu.weight</literal> + control group attribute. The allowed range is 1 to 10000. Defaults to 100. For details about this control + group attribute, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink> and <ulink url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>. - The available CPU time is split up among all units within - one slice relative to their CPU time share weight.</para> + The available CPU time is split up among all units within one slice relative to their CPU time weight.</para> - <para>While <varname>StartupCPUShares=</varname> only - applies to the startup phase of the system, - <varname>CPUShares=</varname> applies to normal runtime of - the system, and if the former is not set also to the startup - phase. Using <varname>StartupCPUShares=</varname> allows - prioritizing specific services at boot-up differently than - during normal runtime.</para> + <para>While <varname>StartupCPUWeight=</varname> only applies to the startup phase of the system, + <varname>CPUWeight=</varname> applies to normal runtime of the system, and if the former is not set also to + the startup phase. Using <varname>StartupCPUWeight=</varname> allows prioritizing specific services at + boot-up differently than during normal runtime.</para> + + <para>Implies <literal>CPUAccounting=true</literal>.</para> - <para>These options imply - <literal>CPUAccounting=true</literal>.</para> + <para>These settings replace <varname>CPUShares=</varname> and <varname>StartupCPUShares=</varname>.</para> </listitem> </varlistentry> @@ -183,20 +207,16 @@ <term><varname>CPUQuota=</varname></term> <listitem> - <para>Assign the specified CPU time quota to the processes - executed. Takes a percentage value, suffixed with "%". The - percentage specifies how much CPU time the unit shall get at - maximum, relative to the total CPU time available on one - CPU. Use values > 100% for allotting CPU time on more than - one CPU. This controls the - <literal>cpu.cfs_quota_us</literal> control group - attribute. For details about this control group attribute, - see <ulink + <para>Assign the specified CPU time quota to the processes executed. Takes a percentage value, suffixed with + "%". The percentage specifies how much CPU time the unit shall get at maximum, relative to the total CPU time + available on one CPU. Use values > 100% for allotting CPU time on more than one CPU. This controls the + <literal>cpu.max</literal> attribute on the unified control group hierarchy and + <literal>cpu.cfs_quota_us</literal> on legacy. For details about these control group attributes, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink> and <ulink url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>.</para> - <para>Example: <varname>CPUQuota=20%</varname> ensures that - the executed processes will never get more than 20% CPU time - on one CPU.</para> + <para>Example: <varname>CPUQuota=20%</varname> ensures that the executed processes will never get more than + 20% CPU time on one CPU.</para> <para>Implies <literal>CPUAccounting=true</literal>.</para> </listitem> @@ -234,7 +254,8 @@ <para>Implies <literal>MemoryAccounting=true</literal>.</para> - <para>This setting is supported only if the unified control group hierarchy is used.</para> + <para>This setting is supported only if the unified control group hierarchy is used and disables + <varname>MemoryLimit=</varname>.</para> </listitem> </varlistentry> @@ -256,7 +277,8 @@ <para>Implies <literal>MemoryAccounting=true</literal>.</para> - <para>This setting is supported only if the unified control group hierarchy is used.</para> + <para>This setting is supported only if the unified control group hierarchy is used and disables + <varname>MemoryLimit=</varname>.</para> </listitem> </varlistentry> @@ -278,29 +300,26 @@ <para>Implies <literal>MemoryAccounting=true</literal>.</para> - <para>This setting is supported only if the unified control group hierarchy is used. Use - <varname>MemoryLimit=</varname> on systems using the legacy control group hierarchy.</para> + <para>This setting replaces <varname>MemoryLimit=</varname>.</para> </listitem> </varlistentry> <varlistentry> - <term><varname>MemoryLimit=<replaceable>bytes</replaceable></varname></term> + <term><varname>MemorySwapMax=<replaceable>bytes</replaceable></varname></term> <listitem> - <para>Specify the limit on maximum memory usage of the executed processes. The limit specifies how much - process and kernel memory can be used by tasks in this unit. Takes a memory size in bytes. If the value is - suffixed with K, M, G or T, the specified memory size is parsed as Kilobytes, Megabytes, Gigabytes, or - Terabytes (with the base 1024), respectively. Alternatively, a percentage value may be specified, which is - taken relative to the installed physical memory on the system. If assigned the special value - <literal>infinity</literal>, no memory limit is applied. This controls the - <literal>memory.limit_in_bytes</literal> control group attribute. For details about this control group - attribute, see <ulink - url="https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt">memory.txt</ulink>.</para> + <para>Specify the absolute limit on swap usage of the executed processes in this unit.</para> + + <para>Takes a swap size in bytes. If the value is suffixed with K, M, G or T, the specified swap size is + parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. If assigned the + special value <literal>infinity</literal>, no swap limit is applied. This controls the + <literal>memory.swap.max</literal> control group attribute. For details about this control group attribute, + see <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para> <para>Implies <literal>MemoryAccounting=true</literal>.</para> - <para>This setting is supported only if the legacy control group hierarchy is used. Use - <varname>MemoryMax=</varname> on systems using the unified control group hierarchy.</para> + <para>This setting is supported only if the unified control group hierarchy is used and disables + <varname>MemoryLimit=</varname>.</para> </listitem> </varlistentry> @@ -352,8 +371,8 @@ in <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - <para>This setting is supported only if the unified control group hierarchy is used. Use - <varname>BlockIOAccounting=</varname> on systems using the legacy control group hierarchy.</para> + <para>This setting replaces <varname>BlockIOAccounting=</varname> and disables settings prefixed with + <varname>BlockIO</varname> or <varname>StartupBlockIO</varname>.</para> </listitem> </varlistentry> @@ -378,9 +397,8 @@ <para>Implies <literal>IOAccounting=true</literal>.</para> - <para>This setting is supported only if the unified control group hierarchy is used. Use - <varname>BlockIOWeight=</varname> and <varname>StartupBlockIOWeight=</varname> on systems using the legacy - control group hierarchy.</para> + <para>These settings replace <varname>BlockIOWeight=</varname> and <varname>StartupBlockIOWeight=</varname> + and disable settings prefixed with <varname>BlockIO</varname> or <varname>StartupBlockIO</varname>.</para> </listitem> </varlistentry> @@ -399,8 +417,8 @@ <para>Implies <literal>IOAccounting=true</literal>.</para> - <para>This setting is supported only if the unified control group hierarchy is used. Use - <varname>BlockIODeviceWeight=</varname> on systems using the legacy control group hierarchy.</para> + <para>This setting replaces <varname>BlockIODeviceWeight=</varname> and disables settings prefixed with + <varname>BlockIO</varname> or <varname>StartupBlockIO</varname>.</para> </listitem> </varlistentry> @@ -424,8 +442,9 @@ <para>Implies <literal>IOAccounting=true</literal>.</para> - <para>This setting is supported only if the unified control group hierarchy is used. Use - <varname>BlockIOAccounting=</varname> on systems using the legacy control group hierarchy.</para> + <para>These settings replace <varname>BlockIOReadBandwidth=</varname> and + <varname>BlockIOWriteBandwidth=</varname> and disable settings prefixed with <varname>BlockIO</varname> or + <varname>StartupBlockIO</varname>.</para> </listitem> </varlistentry> @@ -449,100 +468,8 @@ <para>Implies <literal>IOAccounting=true</literal>.</para> - <para>This setting is supported only if the unified control group hierarchy is used.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>BlockIOAccounting=</varname></term> - - <listitem> - <para>Turn on Block I/O accounting for this unit, if the legacy control group hierarchy is used on the - system. Takes a boolean argument. Note that turning on block I/O accounting for one unit will also implicitly - turn it on for all units contained in the same slice and all for its parent slices and the units contained - therein. The system default for this setting may be controlled with - <varname>DefaultBlockIOAccounting=</varname> in - <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - - <para>This setting is supported only if the legacy control group hierarchy is used. Use - <varname>IOAccounting=</varname> on systems using the unified control group hierarchy.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>BlockIOWeight=<replaceable>weight</replaceable></varname></term> - <term><varname>StartupBlockIOWeight=<replaceable>weight</replaceable></varname></term> - - <listitem><para>Set the default overall block I/O weight for the executed processes, if the legacy control - group hierarchy is used on the system. Takes a single weight value (between 10 and 1000) to set the default - block I/O weight. This controls the <literal>blkio.weight</literal> control group attribute, which defaults to - 500. For details about this control group attribute, see <ulink - url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>. - The available I/O bandwidth is split up among all units within one slice relative to their block I/O - weight.</para> - - <para>While <varname>StartupBlockIOWeight=</varname> only - applies to the startup phase of the system, - <varname>BlockIOWeight=</varname> applies to the later runtime - of the system, and if the former is not set also to the - startup phase. This allows prioritizing specific services at - boot-up differently than during runtime.</para> - - <para>Implies - <literal>BlockIOAccounting=true</literal>.</para> - - <para>This setting is supported only if the legacy control group hierarchy is used. Use - <varname>IOWeight=</varname> and <varname>StartupIOWeight=</varname> on systems using the unified control group - hierarchy.</para> - - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>BlockIODeviceWeight=<replaceable>device</replaceable> <replaceable>weight</replaceable></varname></term> - - <listitem> - <para>Set the per-device overall block I/O weight for the executed processes, if the legacy control group - hierarchy is used on the system. Takes a space-separated pair of a file path and a weight value to specify - the device specific weight value, between 10 and 1000. (Example: "/dev/sda 500"). The file path may be - specified as path to a block device node or as any other file, in which case the backing block device of the - file system of the file is determined. This controls the <literal>blkio.weight_device</literal> control group - attribute, which defaults to 1000. Use this option multiple times to set weights for multiple devices. For - details about this control group attribute, see <ulink - url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>.</para> - - <para>Implies - <literal>BlockIOAccounting=true</literal>.</para> - - <para>This setting is supported only if the legacy control group hierarchy is used. Use - <varname>IODeviceWeight=</varname> on systems using the unified control group hierarchy.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>BlockIOReadBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term> - <term><varname>BlockIOWriteBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term> - - <listitem> - <para>Set the per-device overall block I/O bandwidth limit for the executed processes, if the legacy control - group hierarchy is used on the system. Takes a space-separated pair of a file path and a bandwidth value (in - bytes per second) to specify the device specific bandwidth. The file path may be a path to a block device - node, or as any other file in which case the backing block device of the file system of the file is used. If - the bandwidth is suffixed with K, M, G, or T, the specified bandwidth is parsed as Kilobytes, Megabytes, - Gigabytes, or Terabytes, respectively, to the base of 1000. (Example: - "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This controls the - <literal>blkio.throttle.read_bps_device</literal> and <literal>blkio.throttle.write_bps_device</literal> - control group attributes. Use this option multiple times to set bandwidth limits for multiple devices. For - details about these control group attributes, see <ulink - url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>. - </para> - - <para>Implies - <literal>BlockIOAccounting=true</literal>.</para> - - <para>This setting is supported only if the legacy control group hierarchy is used. Use - <varname>IOReadBandwidthMax=</varname> and <varname>IOWriteBandwidthMax=</varname> on systems using the - unified control group hierarchy.</para> + <para>These settings are supported only if the unified control group hierarchy is used and disable settings + prefixed with <varname>BlockIO</varname> or <varname>StartupBlockIO</varname>.</para> </listitem> </varlistentry> @@ -674,6 +601,149 @@ </refsect1> <refsect1> + <title>Deprecated Options</title> + + <para>The following options are deprecated. Use the indicated superseding options instead:</para> + + <variablelist class='unit-directives'> + + <varlistentry> + <term><varname>CPUShares=<replaceable>weight</replaceable></varname></term> + <term><varname>StartupCPUShares=<replaceable>weight</replaceable></varname></term> + + <listitem> + <para>Assign the specified CPU time share weight to the processes executed. These options take an integer + value and control the <literal>cpu.shares</literal> control group attribute. The allowed range is 2 to + 262144. Defaults to 1024. For details about this control group attribute, see <ulink + url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>. + The available CPU time is split up among all units within one slice relative to their CPU time share + weight.</para> + + <para>While <varname>StartupCPUShares=</varname> only applies to the startup phase of the system, + <varname>CPUShares=</varname> applies to normal runtime of the system, and if the former is not set also to + the startup phase. Using <varname>StartupCPUShares=</varname> allows prioritizing specific services at + boot-up differently than during normal runtime.</para> + + <para>Implies <literal>CPUAccounting=true</literal>.</para> + + <para>These settings are deprecated. Use <varname>CPUWeight=</varname> and + <varname>StartupCPUWeight=</varname> instead.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>MemoryLimit=<replaceable>bytes</replaceable></varname></term> + + <listitem> + <para>Specify the limit on maximum memory usage of the executed processes. The limit specifies how much + process and kernel memory can be used by tasks in this unit. Takes a memory size in bytes. If the value is + suffixed with K, M, G or T, the specified memory size is parsed as Kilobytes, Megabytes, Gigabytes, or + Terabytes (with the base 1024), respectively. Alternatively, a percentage value may be specified, which is + taken relative to the installed physical memory on the system. If assigned the special value + <literal>infinity</literal>, no memory limit is applied. This controls the + <literal>memory.limit_in_bytes</literal> control group attribute. For details about this control group + attribute, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt">memory.txt</ulink>.</para> + + <para>Implies <literal>MemoryAccounting=true</literal>.</para> + + <para>This setting is deprecated. Use <varname>MemoryMax=</varname> instead.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>BlockIOAccounting=</varname></term> + + <listitem> + <para>Turn on Block I/O accounting for this unit, if the legacy control group hierarchy is used on the + system. Takes a boolean argument. Note that turning on block I/O accounting for one unit will also implicitly + turn it on for all units contained in the same slice and all for its parent slices and the units contained + therein. The system default for this setting may be controlled with + <varname>DefaultBlockIOAccounting=</varname> in + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para>This setting is deprecated. Use <varname>IOAccounting=</varname> instead.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>BlockIOWeight=<replaceable>weight</replaceable></varname></term> + <term><varname>StartupBlockIOWeight=<replaceable>weight</replaceable></varname></term> + + <listitem><para>Set the default overall block I/O weight for the executed processes, if the legacy control + group hierarchy is used on the system. Takes a single weight value (between 10 and 1000) to set the default + block I/O weight. This controls the <literal>blkio.weight</literal> control group attribute, which defaults to + 500. For details about this control group attribute, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>. + The available I/O bandwidth is split up among all units within one slice relative to their block I/O + weight.</para> + + <para>While <varname>StartupBlockIOWeight=</varname> only + applies to the startup phase of the system, + <varname>BlockIOWeight=</varname> applies to the later runtime + of the system, and if the former is not set also to the + startup phase. This allows prioritizing specific services at + boot-up differently than during runtime.</para> + + <para>Implies + <literal>BlockIOAccounting=true</literal>.</para> + + <para>These settings are deprecated. Use <varname>IOWeight=</varname> and <varname>StartupIOWeight=</varname> + instead.</para> + + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>BlockIODeviceWeight=<replaceable>device</replaceable> <replaceable>weight</replaceable></varname></term> + + <listitem> + <para>Set the per-device overall block I/O weight for the executed processes, if the legacy control group + hierarchy is used on the system. Takes a space-separated pair of a file path and a weight value to specify + the device specific weight value, between 10 and 1000. (Example: "/dev/sda 500"). The file path may be + specified as path to a block device node or as any other file, in which case the backing block device of the + file system of the file is determined. This controls the <literal>blkio.weight_device</literal> control group + attribute, which defaults to 1000. Use this option multiple times to set weights for multiple devices. For + details about this control group attribute, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>.</para> + + <para>Implies + <literal>BlockIOAccounting=true</literal>.</para> + + <para>This setting is deprecated. Use <varname>IODeviceWeight=</varname> instead.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>BlockIOReadBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term> + <term><varname>BlockIOWriteBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term> + + <listitem> + <para>Set the per-device overall block I/O bandwidth limit for the executed processes, if the legacy control + group hierarchy is used on the system. Takes a space-separated pair of a file path and a bandwidth value (in + bytes per second) to specify the device specific bandwidth. The file path may be a path to a block device + node, or as any other file in which case the backing block device of the file system of the file is used. If + the bandwidth is suffixed with K, M, G, or T, the specified bandwidth is parsed as Kilobytes, Megabytes, + Gigabytes, or Terabytes, respectively, to the base of 1000. (Example: + "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This controls the + <literal>blkio.throttle.read_bps_device</literal> and <literal>blkio.throttle.write_bps_device</literal> + control group attributes. Use this option multiple times to set bandwidth limits for multiple devices. For + details about these control group attributes, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>. + </para> + + <para>Implies + <literal>BlockIOAccounting=true</literal>.</para> + + <para>These settings are deprecated. Use <varname>IOReadBandwidthMax=</varname> and + <varname>IOWriteBandwidthMax=</varname> instead.</para> + </listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> <title>See Also</title> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, @@ -684,6 +754,7 @@ <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, The documentation for control groups and specific controllers in the Linux kernel: diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 875d368fcf..5c65957bda 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -96,9 +96,12 @@ <varname>After=</varname> on <filename>dbus.socket</filename>.</para> - <para>Socket activated service are automatically ordered after - their activated <filename>.socket</filename> units via an - automatic <varname>After=</varname> dependency.</para> + <para>Socket activated services are automatically ordered after + their activating <filename>.socket</filename> units via an + automatic <varname>After=</varname> dependency. + Services also pull in all <filename>.socket</filename> units + listed in <varname>Sockets=</varname> via automatic + <varname>Wants=</varname> and <varname>After=</varname> dependencies.</para> <para>Unless <varname>DefaultDependencies=</varname> in the <literal>[Unit]</literal> is set to <option>false</option>, service units will implicitly have dependencies of type <varname>Requires=</varname> and @@ -209,11 +212,11 @@ if used in combination with <varname>PrivateNetwork=</varname><option>yes</option>.</para> - <para>Behavior of <option>idle</option> is very similar to - <option>simple</option>; however, actual execution of the - service binary is delayed until all jobs are dispatched. This - may be used to avoid interleaving of output of shell services - with the status output on the console.</para> + <para>Behavior of <option>idle</option> is very similar to <option>simple</option>; however, actual execution + of the service binary is delayed until all active jobs are dispatched. This may be used to avoid interleaving + of output of shell services with the status output on the console. Note that this type is useful only to + improve console output, it is not useful as a general unit ordering tool, and the effect of this service type + is subject to a 5s time-out, after which the service binary is invoked anyway.</para> </listitem> </varlistentry> @@ -276,17 +279,12 @@ below (see section "Command Lines" below). </para> - <para>When <varname>Type=</varname> is not - <option>oneshot</option>, only one command may and must be - given. When <varname>Type=oneshot</varname> is used, zero or - more commands may be specified. This can be specified by - providing multiple command lines in the same directive, or - alternatively, this directive may be specified more than once - with the same effect. If the empty string is assigned to this - option, the list of commands to start is reset, prior - assignments of this option will have no effect. If no - <varname>ExecStart=</varname> is specified, then the service - must have <varname>RemainAfterExit=yes</varname> set.</para> + <para>Unless <varname>Type=</varname> is <option>oneshot</option>, exactly one command must be given. When + <varname>Type=oneshot</varname> is used, zero or more commands may be specified. Commands may be specified by + providing multiple command lines in the same directive, or alternatively, this directive may be specified more + than once with the same effect. If the empty string is assigned to this option, the list of commands to start + is reset, prior assignments of this option will have no effect. If no <varname>ExecStart=</varname> is + specified, then the service must have <varname>RemainAfterExit=yes</varname> set.</para> <para>For each of the specified commands, the first argument must be an absolute path to an executable. Optionally, if this file name is prefixed with <literal>@</literal>, the second token will be @@ -294,7 +292,7 @@ the absolute filename is prefixed with <literal>-</literal>, an exit code of the command normally considered a failure (i.e. non-zero exit status or abnormal exit due to signal) is ignored and considered success. If the absolute path is prefixed with <literal>+</literal> then it is executed with full - privileges. <literal>-</literal>, <literal>@</literal>, and <literal>+</literal> may be used together and they + privileges. <literal>@</literal>, <literal>-</literal>, and <literal>+</literal> may be used together and they can appear in any order.</para> <para>If more than one command is specified, the commands are @@ -429,7 +427,13 @@ service failed to start up correctly. Commands configured with this setting need to be able to operate even if the service failed starting up half-way and left incompletely initialized data around. As the service's processes have been terminated already when the commands specified with this setting are executed they should - not attempt to communicate with them.</para></listitem> + not attempt to communicate with them.</para> + + <para>Note that all commands that are configured with this setting are invoked with the result code of the + service, as well as the main process' exit code and status, set in the <varname>$SERVICE_RESULT</varname>, + <varname>$EXIT_CODE</varname> and <varname>$EXIT_STATUS</varname> environment variables, see + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for + details.</para></listitem> </varlistentry> <varlistentry> @@ -848,13 +852,13 @@ serialized to <filename>/run</filename> and the file descriptors passed to the service manager, to allow restarts without losing state. Defaults to 0, i.e. no file descriptors - may be stored in the service manager by default. All file + may be stored in the service manager. All file descriptors passed to the service manager from a specific service are passed back to the service's main process on the next service restart. Any file descriptors passed to the service manager are automatically closed when POLLHUP or POLLERR is seen on them, or when the service is fully stopped - and no job queued or being executed for it.</para></listitem> + and no job is queued or being executed for it.</para></listitem> </varlistentry> <varlistentry> diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml index 5bf54d8ef3..0ce1203cfb 100644 --- a/man/systemd.socket.xml +++ b/man/systemd.socket.xml @@ -294,10 +294,10 @@ <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 + FunctionFS</ulink> endpoints 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> + absolute file system path of functionfs mount point as the argument. + Behavior otherwise is very similar to the <varname>ListenFIFO=</varname> directive above. Use this to open the FunctionFS endpoint <filename>ep0</filename>. When using this option, the activated service has to have the @@ -443,6 +443,14 @@ </varlistentry> <varlistentry> + <term><varname>MaxConnectionsPerSource=</varname></term> + <listitem><para>The maximum number of connections for a service per source IP address. + This is very similar to the <varname>MaxConnections=</varname> directive + above. Disabled by default.</para> + </listitem> + </varlistentry> + + <varlistentry> <term><varname>KeepAlive=</varname></term> <listitem><para>Takes a boolean argument. If true, the TCP/IP stack will send a keep alive message after 2h (depending on @@ -527,7 +535,7 @@ and the kernel will ignore initial ACK packets without any data. The argument specifies the approximate amount of time the kernel should wait for incoming data before falling back - to the normal behavior of honouring empty ACK packets. This + to the normal behavior of honoring empty ACK packets. This option is beneficial for protocols where the client sends the data first (e.g. HTTP, in contrast to SMTP), because the server process will not be woken up unnecessarily before it diff --git a/man/systemd.special.xml b/man/systemd.special.xml index 18ad8f92e5..d977298cd8 100644 --- a/man/systemd.special.xml +++ b/man/systemd.special.xml @@ -879,6 +879,70 @@ </refsect1> <refsect1> + <title>Special Passive User Units</title> + + <refsect2> + <title>graphical-session.target</title> + + <para>This target is active whenever any graphical session is running. It + is used to stop user services which only apply to a graphical (X, + Wayland, etc.) session when the session is terminated. Such services + should have <literal>PartOf=graphical-session.target</literal> in their + <literal>[Unit]</literal> section. A target for a particular session + (e. g. <filename>gnome-session.target</filename>) starts and stops + <literal>graphical-session.target</literal> with + <literal>BindsTo=graphical-session.target</literal>.</para> + + <para>Which services are started by a session target is determined by the + <literal>Wants=</literal> and <literal>Requires=</literal> dependencies. + For services that can be enabled independently, symlinks in + <literal>.wants/</literal> and <literal>.requires/</literal> should be + used, see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + Those symlinks should either be shipped in packages, or should be added + dynamically after installation, for example using <literal>systemctl add-wants</literal>, see + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + </para> + + <example> + <title>Nautilus as part of a GNOME session</title> + + <para><literal>gnome-session.target</literal> pulls in Nautilus as + top-level service:</para> + + <programlisting>[Unit] +Description=User systemd services for GNOME graphical session +Wants=nautilus.service +BindsTo=graphical-session.target + </programlisting> + + <para><literal>nautilus.service</literal> gets stopped when the session stops:</para> + + <programlisting>[Unit] +Description=Render the desktop icons with Nautilus +PartOf=graphical-session.target + +[Service] +... + </programlisting> + </example> + </refsect2> + + <refsect2> + <title>graphical-session-pre.target</title> + + <para>This target contains services which set up the environment or + global configuration of a graphical session, such as SSH/GPG agents + (which need to export an environment variable into all desktop processes) + or migration of obsolete d-conf keys after an OS upgrade (which needs to + happen before starting any process that might use them). This target must + be started before starting a graphical session + like <filename>gnome-session.target</filename>.</para> + </refsect2> + + </refsect1> + + <refsect1> <title>Special Slice Units</title> <para>There are four <literal>.slice</literal> units which form diff --git a/man/systemd.target.xml b/man/systemd.target.xml index 2e35e54fc4..b3cccd4e52 100644 --- a/man/systemd.target.xml +++ b/man/systemd.target.xml @@ -83,7 +83,7 @@ <title>Automatic Dependencies</title> <para>Unless <varname>DefaultDependencies=</varname> is set to - <option>no</option> in either of releated units or an explicit ordering + <option>no</option> in either of related units or an explicit ordering dependency is already defined, target units will implicitly complement all configured dependencies of type <varname>Wants=</varname> or <varname>Requires=</varname> with dependencies of type diff --git a/man/systemd.time.xml b/man/systemd.time.xml index aae3accb6c..47229b4a4e 100644 --- a/man/systemd.time.xml +++ b/man/systemd.time.xml @@ -57,14 +57,13 @@ <refsect1> <title>Displaying Time Spans</title> - <para>Time spans refer to time durations. On display, systemd will - present time spans as a space-separated series of time values each - suffixed by a time unit.</para> + <para>Time spans refer to time durations. On display, systemd will present time spans as a space-separated series + of time values each suffixed by a time unit. Example:</para> <programlisting>2h 30min</programlisting> - <para>All specified time values are meant to be added up. The - above hence refers to 150 minutes.</para> + <para>All specified time values are meant to be added up. The above hence refers to 150 minutes. Display is + locale-independent, only English names for the time units are used.</para> </refsect1> <refsect1> @@ -83,13 +82,13 @@ <listitem><para>days, day, d</para></listitem> <listitem><para>weeks, week, w</para></listitem> <listitem><para>months, month, M (defined as 30.44 days)</para></listitem> - <listitem><para>years, year, y (define as 365.25 days)</para></listitem> + <listitem><para>years, year, y (defined as 365.25 days)</para></listitem> </itemizedlist> - <para>If no time unit is specified, generally seconds are assumed, - but some exceptions exist and are marked as such. In a few cases - <literal>ns</literal>, <literal>nsec</literal> is accepted too, - where the granularity of the time span allows for this.</para> + <para>If no time unit is specified, generally seconds are assumed, but some exceptions exist and are marked as + such. In a few cases <literal>ns</literal>, <literal>nsec</literal> is accepted too, where the granularity of the + time span permits this. Parsing is generally locale-independent, non-English names for the time units are not + accepted.</para> <para>Examples for valid time span specifications:</para> @@ -110,30 +109,29 @@ <programlisting>Fri 2012-11-23 23:02:15 CET</programlisting> - <para>The weekday is printed according to the locale choice of the - user.</para> + <para>The weekday is printed in the abbreviated English language form. The formatting is locale-independent.</para> + + <para>In some cases timestamps are shown in the UTC timezone instead of the local timezone, which is indicated via + the <literal>UTC</literal> timezone specifier in the output.</para> + + <para>In some cases timestamps are shown with microsecond granularity. In this case the sub-second remainder is + separated by a full stop from the seconds component.</para> </refsect1> <refsect1> <title>Parsing Timestamps</title> - <para>When parsing, systemd will accept a similar syntax, but - expects no timezone specification, unless it is given as the - literal string "UTC". In this case, the time is considered in UTC, - otherwise in the local timezone. The weekday specification is - optional, but when the weekday is specified, it must either be in - the abbreviated (<literal>Wed</literal>) or non-abbreviated - (<literal>Wednesday</literal>) English language form (case does - not matter), and is not subject to the locale choice of the user. - Either the date, or the time part may be omitted, in which case - the current date or 00:00:00, respectively, is assumed. The seconds - component of the time may also be omitted, in which case ":00" is - assumed. Year numbers may be specified in full or may be - abbreviated (omitting the century).</para> - - <para>A timestamp is considered invalid if a weekday is specified - and the date does not actually match the specified day of the - week.</para> + <para>When parsing, systemd will accept a similar syntax, but expects no timezone specification, unless it is given + as the literal string <literal>UTC</literal> (for the UTC timezone) or is specified to be the locally configured + timezone. Other timezones than the local and UTC are not supported. The weekday specification is optional, but when + the weekday is specified, it must either be in the abbreviated (<literal>Wed</literal>) or non-abbreviated + (<literal>Wednesday</literal>) English language form (case does not matter), and is not subject to the locale + choice of the user. Either the date, or the time part may be omitted, in which case the current date or 00:00:00, + respectively, is assumed. The seconds component of the time may also be omitted, in which case ":00" is + assumed. Year numbers may be specified in full or may be abbreviated (omitting the century).</para> + + <para>A timestamp is considered invalid if a weekday is specified and the date does not match the specified day of + the week.</para> <para>When parsing, systemd will also accept a few special placeholders instead of timestamps: <literal>now</literal> may be @@ -167,8 +165,6 @@ 2012-11-23 → Fri 2012-11-23 00:00:00 12-11-23 → Fri 2012-11-23 00:00:00 11:12:13 → Fri 2012-11-23 11:12:13 - 11:12:13.9900009 → Fri 2012-11-23 11:12:13 - format_timestamp_us: Fri 2012-11-23 11:12:13.990000 11:12 → Fri 2012-11-23 11:12:00 now → Fri 2012-11-23 18:15:22 today → Fri 2012-11-23 00:00:00 @@ -176,28 +172,25 @@ yesterday → Fri 2012-11-22 00:00:00 tomorrow → Fri 2012-11-24 00:00:00 +3h30min → Fri 2012-11-23 21:45:22 - +3h30min UTC → -EINVAL -5s → Fri 2012-11-23 18:15:17 11min ago → Fri 2012-11-23 18:04:22 - 11min ago UTC → -EINVAL @1395716396 → Tue 2014-03-25 03:59:56</programlisting> - <para>Note that timestamps printed by systemd will not be parsed - correctly by systemd, as the timezone specification is not - accepted, and printing timestamps is subject to locale settings - for the weekday, while parsing only accepts English weekday - names.</para> + <para>Note that timestamps displayed by remote systems with a non-matching timezone are usually not parsable + locally, as the timezone component is not understood (unless it happens to be <literal>UTC</literal>).</para> - <para>In some cases, systemd will display a relative timestamp - (relative to the current time, or the time of invocation of the - command) instead or in addition to an absolute timestamp as - described above. A relative timestamp is formatted as - follows:</para> + <para>Timestamps may also be specified with microsecond granularity. The sub-second remainder is expected separated + by a full stop from the seconds component. Example:</para> + + <programlisting>2014-03-25 03:59:56.654563</programlisting> + + <para>In some cases, systemd will display a relative timestamp (relative to the current time, or the time of + invocation of the command) instead of or in addition to an absolute timestamp as described above. A relative + timestamp is formatted as follows:</para> - <para>2 months 5 days ago</para> + <programlisting>2 months 5 days ago</programlisting> - <para>Note that any relative timestamp will also parse correctly - where a timestamp is expected. (see above)</para> + <para>Note that a relative timestamp is also accepted where a timestamp is expected (see above).</para> </refsect1> <refsect1> @@ -239,8 +232,9 @@ second component is not specified, <literal>:00</literal> is assumed.</para> - <para>A timezone specification is not expected, unless it is given - as the literal string "UTC", similarly to timestamps.</para> + <para>A timezone specification is not expected, unless it is given as the literal string <literal>UTC</literal>, or + the local timezone, similar to the supported syntax of timestamps (see above). Non-local timezones except for UTC + are not supported.</para> <para>The special expressions <literal>minutely</literal>, @@ -263,38 +257,38 @@ <para>Examples for valid timestamps and their normalized form:</para> -<programlisting> Sat,Thu,Mon..Wed,Sat..Sun → Mon..Thu,Sat,Sun *-*-* 00:00:00 - Mon,Sun 12-*-* 2,1:23 → Mon,Sun 2012-*-* 01,02:23:00 - Wed *-1 → Wed *-*-01 00:00:00 +<programlisting> Sat,Thu,Mon..Wed,Sat..Sun → Mon..Thu,Sat,Sun *-*-* 00:00:00 + Mon,Sun 12-*-* 2,1:23 → Mon,Sun 2012-*-* 01,02:23:00 + Wed *-1 → Wed *-*-01 00:00:00 Wed..Wed,Wed *-1 → Wed *-*-01 00:00:00 - Wed, 17:48 → Wed *-*-* 17:48:00 + Wed, 17:48 → Wed *-*-* 17:48:00 Wed..Sat,Tue 12-10-15 1:2:3 → Tue..Sat 2012-10-15 01:02:03 - *-*-7 0:0:0 → *-*-07 00:00:00 - 10-15 → *-10-15 00:00:00 - monday *-12-* 17:00 → Mon *-12-* 17:00:00 - Mon,Fri *-*-3,1,2 *:30:45 → Mon,Fri *-*-01,02,03 *:30:45 - 12,14,13,12:20,10,30 → *-*-* 12,13,14:10,20,30:00 - 12..14:10,20,30 → *-*-* 12,13,14:10,20,30:00 - mon,fri *-1/2-1,3 *:30:45 → Mon,Fri *-01/2-01,03 *:30:45 - 03-05 08:05:40 → *-03-05 08:05:40 - 08:05:40 → *-*-* 08:05:40 - 05:40 → *-*-* 05:40:00 - Sat,Sun 12-05 08:05:40 → Sat,Sun *-12-05 08:05:40 - Sat,Sun 08:05:40 → Sat,Sun *-*-* 08:05:40 - 2003-03-05 05:40 → 2003-03-05 05:40:00 -05:40:23.4200004/3.1700005 → 05:40:23.420000/3.170001 - 2003-02..04-05 → 2003-02,03,04-05 00:00:00 - 2003-03-05 05:40 UTC → 2003-03-05 05:40:00 UTC - 2003-03-05 → 2003-03-05 00:00:00 - 03-05 → *-03-05 00:00:00 - hourly → *-*-* *:00:00 - daily → *-*-* 00:00:00 - daily UTC → *-*-* 00:00:00 UTC - monthly → *-*-01 00:00:00 - weekly → Mon *-*-* 00:00:00 - yearly → *-01-01 00:00:00 - annually → *-01-01 00:00:00 - *:2/3 → *-*-* *:02/3:00</programlisting> + *-*-7 0:0:0 → *-*-07 00:00:00 + 10-15 → *-10-15 00:00:00 + monday *-12-* 17:00 → Mon *-12-* 17:00:00 + Mon,Fri *-*-3,1,2 *:30:45 → Mon,Fri *-*-01,02,03 *:30:45 + 12,14,13,12:20,10,30 → *-*-* 12,13,14:10,20,30:00 + 12..14:10,20,30 → *-*-* 12,13,14:10,20,30:00 + mon,fri *-1/2-1,3 *:30:45 → Mon,Fri *-01/2-01,03 *:30:45 + 03-05 08:05:40 → *-03-05 08:05:40 + 08:05:40 → *-*-* 08:05:40 + 05:40 → *-*-* 05:40:00 + Sat,Sun 12-05 08:05:40 → Sat,Sun *-12-05 08:05:40 + Sat,Sun 08:05:40 → Sat,Sun *-*-* 08:05:40 + 2003-03-05 05:40 → 2003-03-05 05:40:00 + 05:40:23.4200004/3.1700005 → 05:40:23.420000/3.170001 + 2003-02..04-05 → 2003-02,03,04-05 00:00:00 + 2003-03-05 05:40 UTC → 2003-03-05 05:40:00 UTC + 2003-03-05 → 2003-03-05 00:00:00 + 03-05 → *-03-05 00:00:00 + hourly → *-*-* *:00:00 + daily → *-*-* 00:00:00 + daily UTC → *-*-* 00:00:00 UTC + monthly → *-*-01 00:00:00 + weekly → Mon *-*-* 00:00:00 + yearly → *-01-01 00:00:00 + annually → *-01-01 00:00:00 + *:2/3 → *-*-* *:02/3:00</programlisting> <para>Calendar events are used by timer units, see <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry> diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 85a7b12d76..40c4cfd854 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -144,61 +144,69 @@ <option>false</option> and <option>off</option> are equivalent.</para> - <para>Time span values encoded in unit files can be written in - various formats. A stand-alone number specifies a time in seconds. - If suffixed with a time unit, the unit is honored. A concatenation - of multiple values with units is supported, in which case the - values are added up. Example: "50" refers to 50 seconds; "2min - 200ms" refers to 2 minutes plus 200 milliseconds, i.e. 120200ms. - The following time units are understood: s, min, h, d, w, ms, us. - For details see + <para>Time span values encoded in unit files can be written in various formats. A stand-alone + number specifies a time in seconds. If suffixed with a time unit, the unit is honored. A + concatenation of multiple values with units is supported, in which case the values are added + up. Example: <literal>50</literal> refers to 50 seconds; <literal>2min 200ms</literal> refers to + 2 minutes and 200 milliseconds, i.e. 120200 ms. The following time units are understood: + <literal>s</literal>, <literal>min</literal>, <literal>h</literal>, <literal>d</literal>, + <literal>w</literal>, <literal>ms</literal>, <literal>us</literal>. For details see <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> - <para>Empty lines and lines starting with # or ; are - ignored. This may be used for commenting. Lines ending - in a backslash are concatenated with the following - line while reading and the backslash is replaced by a - space character. This may be used to wrap long lines.</para> - - <para>Along with a unit file <filename>foo.service</filename>, the - directory <filename>foo.service.wants/</filename> may exist. All - unit files symlinked from such a directory are implicitly added as - dependencies of type <varname>Wants=</varname> to the unit. This - is useful to hook units into the start-up of other units, without - having to modify their unit files. For details about the semantics - of <varname>Wants=</varname>, see below. The preferred way to - create symlinks in the <filename>.wants/</filename> directory of a - unit file is with the <command>enable</command> command of the + <para>Empty lines and lines starting with <literal>#</literal> or <literal>;</literal> are + ignored. This may be used for commenting. Lines ending in a backslash are concatenated with the + following line while reading and the backslash is replaced by a space character. This may be + used to wrap long lines.</para> + + <para>Units can be aliased (have an alternative name), by creating a symlink from the new name + to the existing name in one of the unit search paths. For example, + <filename>systemd-networkd.service</filename> has the alias + <filename>dbus-org.freedesktop.network1.service</filename>, created during installation as the + symlink <filename>/usr/lib/systemd/system/dbus-org.freedesktop.network1.service</filename>. In + addition, unit files may specify aliases through the <varname>Alias=</varname> directive in the + [Install] section; those aliases are only effective when the unit is enabled. When the unit is + enabled, symlinks will be created for those names, and removed when the unit is disabled. For + example, <filename>reboot.target</filename> specifies + <varname>Alias=ctrl-alt-del.target</varname>, so when enabled it will be invoked whenever + CTRL+ALT+DEL is pressed. Alias names may be used in commands like <command>enable</command>, + <command>disable</command>, <command>start</command>, <command>stop</command>, + <command>status</command>, …, and in unit dependency directives <varname>Wants=</varname>, + <varname>Requires=</varname>, <varname>Before=</varname>, <varname>After=</varname>, …, with the + limitation that aliases specified through <varname>Alias=</varname> are only effective when the + unit is enabled. Aliases cannot be used with the <command>preset</command> command.</para> + + <para>Along with a unit file <filename>foo.service</filename>, the directory + <filename>foo.service.wants/</filename> may exist. All unit files symlinked from such a + directory are implicitly added as dependencies of type <varname>Wants=</varname> to the unit. + This is useful to hook units into the start-up of other units, without having to modify their + unit files. For details about the semantics of <varname>Wants=</varname>, see below. The + preferred way to create symlinks in the <filename>.wants/</filename> directory of a unit file is + with the <command>enable</command> command of the <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - tool which reads information from the [Install] section of unit - files (see below). A similar functionality exists for - <varname>Requires=</varname> type dependencies as well, the - directory suffix is <filename>.requires/</filename> in this - case.</para> + tool which reads information from the [Install] section of unit files (see below). A similar + functionality exists for <varname>Requires=</varname> type dependencies as well, the directory + suffix is <filename>.requires/</filename> in this case.</para> <para>Along with a unit file <filename>foo.service</filename>, a "drop-in" directory - <filename>foo.service.d/</filename> may exist. All files with the suffix <literal>.conf</literal> from this - directory will be parsed after the file itself is parsed. This is useful to alter or add configuration settings for - a unit, without having to modify unit files. Each drop-in file must have appropriate section headers. Note that for - instantiated units, this logic will first look for the instance <literal>.d/</literal> subdirectory and read its - <literal>.conf</literal> files, followed by the template <literal>.d/</literal> subdirectory and the - <literal>.conf</literal> files there. Also note that settings from the <literal>[Install]</literal> section are not - honoured in drop-in unit files, and have no effect.</para> - - <para>In addition to <filename>/etc/systemd/system</filename>, - the drop-in <literal>.conf</literal> files for system services - can be placed in <filename>/usr/lib/systemd/system</filename> or - <filename>/run/systemd/system</filename> directories. Drop-in - files in <filename>/etc</filename> take precedence over those in - <filename>/run</filename> which in turn take precedence over - those in <filename>/usr/lib</filename>. Drop-in files under any of - these directories take precedence over unit files wherever located. - (Of course, since <filename>/run</filename> is temporary and - <filename>/usr/lib</filename> is for vendors, it is unlikely - drop-ins should be used in either of those places.)</para> - <!-- Note that we do not document .include here, as we - consider it mostly obsolete, and want people to - use .d/ drop-ins instead. --> + <filename>foo.service.d/</filename> may exist. All files with the suffix + <literal>.conf</literal> from this directory will be parsed after the file itself is + parsed. This is useful to alter or add configuration settings for a unit, without having to + modify unit files. Each drop-in file must have appropriate section headers. Note that for + instantiated units, this logic will first look for the instance <literal>.d/</literal> + subdirectory and read its <literal>.conf</literal> files, followed by the template + <literal>.d/</literal> subdirectory and the <literal>.conf</literal> files there. Also note that + settings from the <literal>[Install]</literal> section are not honored in drop-in unit files, + and have no effect.</para> + + <para>In addition to <filename>/etc/systemd/system</filename>, the drop-in <literal>.d</literal> + directories for system services can be placed in <filename>/usr/lib/systemd/system</filename> or + <filename>/run/systemd/system</filename> directories. Drop-in files in <filename>/etc</filename> + take precedence over those in <filename>/run</filename> which in turn take precedence over those + in <filename>/usr/lib</filename>. Drop-in files under any of these directories take precedence + over unit files wherever located.</para> + + <!-- Note that we do not document .include here, as we consider it mostly obsolete, and want + people to use .d/ drop-ins instead. --> <para>Some unit names reflect paths existing in the file system namespace. Example: a device unit @@ -900,7 +908,8 @@ <varname>systemd-nspawn</varname>, <varname>docker</varname>, <varname>rkt</varname> to test - against a specific implementation. See + against a specific implementation, or + <varname>private-users</varname> to check whether we are running in a user namespace. See <citerefentry><refentrytitle>systemd-detect-virt</refentrytitle><manvolnum>1</manvolnum></citerefentry> for a full list of known virtualization technologies and their identifiers. If multiple virtualization technologies are @@ -1244,7 +1253,7 @@ <row> <entry><literal>%r</literal></entry> <entry>Control group path of the slice the unit is placed in</entry> - <entry>This usually maps to the parent cgroup path of <literal>%c</literal>.</entry> + <entry>This usually maps to the parent control group path of <literal>%c</literal>.</entry> </row> <row> <entry><literal>%R</literal></entry> diff --git a/man/systemd.xml b/man/systemd.xml index 4f0201fc76..79d8aedbbc 100644 --- a/man/systemd.xml +++ b/man/systemd.xml @@ -272,7 +272,7 @@ <title>Concepts</title> <para>systemd provides a dependency system between various - entities called "units" of 12 different types. Units encapsulate + entities called "units" of 11 different types. Units encapsulate various objects that are relevant for system boot-up and maintenance. The majority of units are configured in unit configuration files, whose syntax and basic set of options is @@ -837,8 +837,10 @@ <varlistentry> <term><varname>$SYSTEMD_COLORS</varname></term> - <listitem><para>Controls whether colorized output should be generated. - </para></listitem> + <listitem><para>The value must be a boolean. Controls whether colorized output should be + generated. This can be specified to override the decision that <command>systemd</command> + makes based on <varname>$TERM</varname> and what the console is connected to.</para> + </listitem> </varlistentry> <varlistentry> @@ -849,7 +851,7 @@ <listitem><para>Set by systemd for supervised processes during socket-based activation. See <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for more information. </para></listitem> + for more information.</para></listitem> </varlistentry> <varlistentry> @@ -858,7 +860,7 @@ <listitem><para>Set by systemd for supervised processes for status and start-up completion notification. See <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for more information. </para></listitem> + for more information.</para></listitem> </varlistentry> </variablelist> </refsect1> diff --git a/man/tmpfiles.d.xml b/man/tmpfiles.d.xml index 957475d2bd..e040a1636d 100644 --- a/man/tmpfiles.d.xml +++ b/man/tmpfiles.d.xml @@ -626,7 +626,7 @@ <example> <title>Create directories with specific mode and ownership</title> <para> - <citerefentry><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>, needs two directories created at boot with specific modes and ownership:</para> <programlisting># /usr/lib/tmpfiles.d/screen.conf @@ -644,7 +644,7 @@ d /run/uscreens 0755 root screen 10d12h t /run/cups - - - - security.SMACK64=printing user.attr-with-spaces="foo bar" </programlisting> - <para>The direcory will be owned by root and have default mode. It's contents are + <para>The directory will be owned by root and have default mode. Its contents are not subject to time based cleanup, but will be obliterated when <command>systemd-tmpfiles --remove</command> runs.</para> </example> @@ -652,7 +652,7 @@ t /run/cups - - - - security.SMACK64=printing user.attr-with-spaces="foo bar" <example> <title>Create a directory and prevent its contents from cleanup</title> <para> - <citerefentry><refentrytitle>abrt</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>abrt</refentrytitle><manvolnum>1</manvolnum></citerefentry>, needs a directory created at boot with specific mode and ownership and its content should be preserved from the automatic cleanup applied to the contents of <filename>/var/tmp</filename>:</para> diff --git a/man/udev.xml b/man/udev.xml index dd5563605c..3359fb0865 100644 --- a/man/udev.xml +++ b/man/udev.xml @@ -577,8 +577,8 @@ <para>The <varname>NAME</varname>, <varname>SYMLINK</varname>, <varname>PROGRAM</varname>, <varname>OWNER</varname>, - <varname>GROUP</varname>, <varname>MODE</varname>, and - <varname>RUN</varname> fields support simple string substitutions. + <varname>GROUP</varname>, <varname>MODE</varname>, <varname>SECLABEL</varname>, + and <varname>RUN</varname> fields support simple string substitutions. The <varname>RUN</varname> substitutions are performed after all rules have been processed, right before the program is executed, allowing for the use of device properties set by earlier matching rules. For all other diff --git a/man/vconsole.conf.xml b/man/vconsole.conf.xml index 27196d44e9..fa30ca6569 100644 --- a/man/vconsole.conf.xml +++ b/man/vconsole.conf.xml @@ -55,8 +55,9 @@ <para>The <filename>/etc/vconsole.conf</filename> file configures the virtual console, i.e. keyboard mapping and console font. It is - applied at boot by - <citerefentry><refentrytitle>systemd-vconsole-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + applied at boot by udev using <filename>90-vconsole.rules</filename> file. + You can safely mask this file if you want to avoid this kind of initialization. + </para> <para>The basic file format of the <filename>vconsole.conf</filename> is a newline-separated list of @@ -68,10 +69,10 @@ <para>Note that the kernel command line options <varname>vconsole.keymap=</varname>, - <varname>vconsole.keymap.toggle=</varname>, + <varname>vconsole.keymap_toggle=</varname>, <varname>vconsole.font=</varname>, - <varname>vconsole.font.map=</varname>, - <varname>vconsole.font.unimap=</varname> may be used + <varname>vconsole.font_map=</varname>, + <varname>vconsole.font_unimap=</varname> may be used to override the console settings at boot.</para> <para>Depending on the operating system other configuration files @@ -90,12 +91,10 @@ <term><varname>KEYMAP=</varname></term> <term><varname>KEYMAP_TOGGLE=</varname></term> - <listitem><para>Configures the key mapping table for the - keyboard. <varname>KEYMAP=</varname> defaults to - <literal>us</literal> if not set. The - <varname>KEYMAP_TOGGLE=</varname> can be used to configure a - second toggle keymap and is by default - unset.</para></listitem> + <listitem><para>Configures the key mapping table for the keyboard. + <varname>KEYMAP=</varname> defaults to <literal>us</literal> if not set. The + <varname>KEYMAP_TOGGLE=</varname> can be used to configure a second toggle keymap and is by + default unset.</para></listitem> </varlistentry> <varlistentry> @@ -111,6 +110,32 @@ </refsect1> <refsect1> + <title>Kernel Command Line</title> + + <para>A few configuration parameters from <filename>vconsole.conf</filename> may be overridden + on the kernel command line:</para> + + <variablelist class='kernel-commandline-options'> + <varlistentry> + <term><varname>vconsole.keymap=</varname></term> + <term><varname>vconsole.keymap_toggle=</varname></term> + + <listitem><para>Overrides <varname>KEYMAP=</varname> and <varname>KEYMAP_TOGGLE=</varname>. + </para></listitem> + </varlistentry> + <varlistentry> + + <term><varname>vconsole.font=</varname></term> + <term><varname>vconsole.font_map=</varname></term> + <term><varname>vconsole.font_unimap=</varname></term> + + <listitem><para>Overrides <varname>FONT=</varname>, <varname>FONT_MAP=</varname>, and + <varname>FONT_UNIMAP=</varname>.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> <title>Example</title> <example> |