diff options
Diffstat (limited to 'man')
62 files changed, 2021 insertions, 1477 deletions
diff --git a/man/bootchart.conf.xml b/man/bootchart.conf.xml deleted file mode 100644 index f6ac7e6ae2..0000000000 --- a/man/bootchart.conf.xml +++ /dev/null @@ -1,172 +0,0 @@ -<?xml version='1.0'?> <!--*-nxml-*--> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - -<!-- - This file is part of systemd. - - Copyright 2012 Intel Corporation - - Authors: - Auke Kok <auke-jan.h.kok@intel.com> - - systemd is free software; you can redistribute it and/or modify it - under the terms of the GNU Lesser General Public License as published by - the Free Software Foundation; either version 2.1 of the License, or - (at your option) any later version. - - systemd is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public License - along with systemd; If not, see <http://www.gnu.org/licenses/>. ---> - -<refentry id="bootchart.conf" conditional='ENABLE_BOOTCHART' - xmlns:xi="http://www.w3.org/2001/XInclude"> - <refentryinfo> - <title>bootchart.conf</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Auke</firstname> - <surname>Kok</surname> - <email>auke-jan.h.kok@intel.com</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>bootchart.conf</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>bootchart.conf</refname> - <refname>bootchart.conf.d</refname> - <refpurpose>Boot performance analysis graphing tool configuration files</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/systemd/bootchart.conf</filename></para> - <para><filename>/etc/systemd/bootchart.conf.d/*.conf</filename></para> - <para><filename>/run/systemd/bootchart.conf.d/*.conf</filename></para> - <para><filename>/usr/lib/systemd/bootchart.conf.d/*.conf</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>When starting, systemd-bootchart will read the configuration - file <filename>/etc/systemd/bootchart.conf</filename>, followed by - the files in the <filename>bootchart.conf.d</filename> - directories. These configuration files determine logging - parameters and graph output.</para> - </refsect1> - - <xi:include href="standard-conf.xml" xpointer="main-conf" /> - - <refsect1> - <title>Options</title> - - <variablelist class='bootchart-directives'> - - <varlistentry> - <term><varname>Samples=500</varname></term> - <listitem><para>Configure the amount of samples to record in - total before bootchart exits. Each sample will record at - intervals defined by Frequency=.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Frequency=25</varname></term> - <listitem><para>Configure the sample log frequency. This can - be a fractional number, but must be larger than 0.0. Most - systems can cope with values under 25–50 without impacting - boot time severely.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Relative=no</varname></term> - <listitem><para>Configures whether the left axis of the output - graph equals time=0.0 (<constant>CLOCK_MONOTONIC</constant> - start). This is useful for using bootchart at post-boot time - to profile an already booted system, otherwise the graph would - become extremely large. If set to yes, the horizontal axis - starts at the first recorded sample instead of time=0.0. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Filter=no</varname></term> - <listitem><para>Configures whether the resulting graph should - omit tasks that did not contribute significantly to the boot. - Processes that are too short-lived (only seen in one sample) - or that do not consume any significant CPU time (less than - 0.001sec) will not be displayed in the output - graph.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Output=[path]</varname></term> - <listitem><para>Configures the output directory for writing - the graphs. By default, bootchart writes the graphs to - <filename>/run/log</filename>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Init=[path]</varname></term> - <listitem><para>Configures bootchart to run a non-standard - binary instead of - <filename>/usr/lib/systemd/systemd</filename>. This option is - only relevant if bootchart was invoked from the kernel command - line with - init=/usr/lib/systemd/systemd-bootchart.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>PlotMemoryUsage=no</varname></term> - <listitem><para>If set to yes, enables logging and graphing of - processes' PSS memory consumption.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>PlotEntropyGraph=no</varname></term> - <listitem><para>If set to yes, enables logging and graphing of - the kernel random entropy pool size.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ScaleX=100</varname></term> - <listitem><para>Horizontal scaling factor for all variable - graph components.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ScaleY=20</varname></term> - <listitem><para>Vertical scaling factor for all variable graph - components.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ControlGroup=no</varname></term> - <listitem><para>Display process control group. - </para></listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd-bootchart</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/bootup.xml b/man/bootup.xml index b92057af29..986996398c 100644 --- a/man/bootup.xml +++ b/man/bootup.xml @@ -179,6 +179,8 @@ identical to the system manager bootup (see above) until it reaches <filename>basic.target</filename>. From there, systemd approaches the special target <filename>initrd.target</filename>. + When the root device becomes available, + <filename>initd-root-device.target</filename> is reached. If the root device can be mounted at <filename>/sysroot</filename>, the <filename>sysroot.mount</filename> unit becomes active and @@ -204,7 +206,10 @@ | emergency.service ______________________/| | / | v - | sysroot.mount <emphasis>emergency.target</emphasis> + | initrd-root-device.target <emphasis>emergency.target</emphasis> + | | + | v + | sysroot.mount | | | v | initrd-root-fs.target diff --git a/man/busctl.xml b/man/busctl.xml index 26d778d4dd..b71a174634 100644 --- a/man/busctl.xml +++ b/man/busctl.xml @@ -473,7 +473,6 @@ o "/org/freedesktop/systemd1/job/42684"</programlisting> <ulink url="http://freedesktop.org/wiki/Software/dbus">D-Bus</ulink>, <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-bus-proxyd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry project='die-net'><refentrytitle>wireshark</refentrytitle><manvolnum>1</manvolnum></citerefentry> </para> diff --git a/man/coredump.conf.xml b/man/coredump.conf.xml index a0a497b467..4f95680a3a 100644 --- a/man/coredump.conf.xml +++ b/man/coredump.conf.xml @@ -45,7 +45,7 @@ <refnamediv> <refname>coredump.conf</refname> <refname>coredump.conf.d</refname> - <refpurpose>Coredump storage configuration files</refpurpose> + <refpurpose>Core dump storage configuration files</refpurpose> </refnamediv> <refsynopsisdiv> @@ -60,7 +60,14 @@ <para>These files configure the behavior of <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - a handler for core dumps invoked by the kernel.</para> + a handler for core dumps invoked by the kernel. Whether <command>systemd-coredump</command> is used + is determined by the kernel's + <varname>kernel.core_pattern</varname> <citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> + setting. See + <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry> + and + <citerefentry project='man-pages'><refentrytitle>core</refentrytitle><manvolnum>5</manvolnum></citerefentry> + pages for the details.</para> </refsect1> <xi:include href="standard-conf.xml" xpointer="main-conf" /> @@ -79,7 +86,7 @@ <listitem><para>Controls where to store cores. One of <literal>none</literal>, <literal>external</literal>, <literal>journal</literal>, and <literal>both</literal>. When - <literal>none</literal>, the coredumps will be logged but not + <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 @@ -107,7 +114,7 @@ <term><varname>ProcessSizeMax=</varname></term> <listitem><para>The maximum size in bytes of a core - which will be processed. Coredumps exceeding this size + which will be processed. Core dumps exceeding this size will be logged, but the backtrace will not be generated and the core will not be stored.</para></listitem> </varlistentry> @@ -125,14 +132,14 @@ <term><varname>KeepFree=</varname></term> <listitem><para>Enforce limits on the disk space taken up by - externally stored coredumps. <option>MaxUse=</option> makes - sure that old coredumps are removed as soon as the total disk - space taken up by coredumps grows beyond this limit (defaults + externally stored core dumps. <option>MaxUse=</option> makes + sure that old core dumps are removed as soon as the total disk + space taken up by core dumps grows beyond this limit (defaults to 10% of the total disk size). <option>KeepFree=</option> controls how much disk space to keep free at least (defaults to 15% of the total disk size). Note that the disk space used - by coredumps might temporarily exceed these limits while - coredumps are processed. Note that old coredumps are also + by core dumps might temporarily exceed these limits while + core dumps are processed. Note that old core dumps are also removed based on time via <citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Set either value to 0 to turn off size-based diff --git a/man/coredumpctl.xml b/man/coredumpctl.xml index 0f1afe77c3..abc245be5e 100644 --- a/man/coredumpctl.xml +++ b/man/coredumpctl.xml @@ -45,7 +45,7 @@ <refnamediv> <refname>coredumpctl</refname> - <refpurpose>Retrieve coredumps from the journal</refpurpose> + <refpurpose>Retrieve and process saved core dumps and metadata</refpurpose> </refnamediv> <refsynopsisdiv> @@ -60,9 +60,10 @@ <refsect1> <title>Description</title> - <para><command>coredumpctl</command> may be used to - retrieve coredumps from - <citerefentry><refentrytitle>systemd-journald</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + <para><command>coredumpctl</command> is a tool that can be used to retrieve and process core + dumps and metadata which were saved by + <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + </para> </refsect1> <refsect1> @@ -71,18 +72,23 @@ <para>The following options are understood:</para> <variablelist> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + <varlistentry> <term><option>--no-legend</option></term> - <listitem><para>Do not print column headers. - </para></listitem> + <listitem><para>Do not print column headers.</para></listitem> </varlistentry> + <xi:include href="standard-options.xml" xpointer="no-pager" /> + <varlistentry> <term><option>-1</option></term> - <listitem><para>Show information of a single coredump only, - instead of listing all known coredumps. </para></listitem> + <listitem><para>Show information of a single core dump only, instead of listing + all known core dumps.</para></listitem> </varlistentry> <varlistentry> @@ -90,7 +96,7 @@ <term><option>--field=</option><replaceable>FIELD</replaceable></term> <listitem><para>Print all possible data values the specified - field takes in matching coredump entries of the + field takes in matching core dump entries of the journal.</para></listitem> </varlistentry> @@ -110,11 +116,11 @@ </para></listitem> </varlistentry> - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - <xi:include href="standard-options.xml" xpointer="no-pager" /> - </variablelist> + </refsect1> + + <refsect1> + <title>Commands</title> <para>The following commands are understood:</para> @@ -122,23 +128,31 @@ <varlistentry> <term><command>list</command></term> - <listitem><para>List coredumps captured in the journal + <listitem><para>List core dumps captured in the journal matching specified characteristics. If no command is - specified, this is the implied default.</para></listitem> + specified, this is the implied default.</para> + + <para>It's worth noting that different restrictions apply to + data saved in the journal and core dump files saved in + <filename>/var/lib/systemd/coredump</filename>, see overview in + <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + Thus it may very well happen that a particular core dump is still listed + in the journal while its corresponding core dump file has already been + removed.</para></listitem> </varlistentry> <varlistentry> <term><command>info</command></term> - <listitem><para>Show detailed information about coredumps + <listitem><para>Show detailed information about core dumps captured in the journal.</para></listitem> </varlistentry> <varlistentry> <term><command>dump</command></term> - <listitem><para>Extract the last coredump matching specified - characteristics. The coredump will be written on standard + <listitem><para>Extract the last core dump matching specified + characteristics. The core dump will be written on standard output, unless an output file is specified with <option>--output=</option>. </para></listitem> </varlistentry> @@ -146,7 +160,7 @@ <varlistentry> <term><command>gdb</command></term> - <listitem><para>Invoke the GNU debugger on the last coredump + <listitem><para>Invoke the GNU debugger on the last core dump matching specified characteristics. </para></listitem> </varlistentry> @@ -197,7 +211,7 @@ <refsect1> <title>Exit status</title> <para>On success, 0 is returned; otherwise, a non-zero failure - code is returned. Not finding any matching coredumps is treated as + code is returned. Not finding any matching core dumps is treated as failure. </para> </refsect1> @@ -206,13 +220,13 @@ <title>Examples</title> <example> - <title>List all the coredumps of a program named foo</title> + <title>List all the core dumps of a program named foo</title> <programlisting># coredumpctl list foo</programlisting> </example> <example> - <title>Invoke gdb on the last coredump</title> + <title>Invoke gdb on the last core dump</title> <programlisting># coredumpctl gdb</programlisting> </example> @@ -225,7 +239,7 @@ </example> <example> - <title>Extract the last coredump of /usr/bin/bar to a file named + <title>Extract the last core dump of /usr/bin/bar to a file named <filename noindex="true">bar.coredump</filename></title> <programlisting># coredumpctl -o bar.coredump dump /usr/bin/bar</programlisting> diff --git a/man/daemon.xml b/man/daemon.xml index f74fd35fc5..a649749683 100644 --- a/man/daemon.xml +++ b/man/daemon.xml @@ -180,14 +180,12 @@ functionality of the init system, it is recommended not to execute them when run as new-style service.</para> - <para>Note that new-style init systems guarantee execution of - daemon processes in a clean process context: it is guaranteed - that the environment block is sanitized, that the signal - handlers and mask is reset and that no left-over file - descriptors are passed. Daemons will be executed in their own - session, with standard input/output/error connected to - <filename>/dev/null</filename> unless otherwise configured. The - umask is reset. + <para>Note that new-style init systems guarantee execution of daemon processes in a clean process context: it is + guaranteed that the environment block is sanitized, that the signal handlers and mask is reset and that no + left-over file descriptors are passed. Daemons will be executed in their own session, with standard input + connected to <filename>/dev/null</filename> and standard output/error connected to the + <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + logging service, unless otherwise configured. The umask is reset. </para> <para>It is recommended for new-style daemons to implement the @@ -234,7 +232,7 @@ bus-activatable by supplying a D-Bus service activation configuration file. This has multiple advantages: your daemon may be started lazily on-demand; it may be started in parallel - to other daemons requiring it -- which maximizes + to other daemons requiring it — which maximizes parallelization and boot-up speed; your daemon can be restarted on failure without losing any bus requests, as the bus queues requests for activatable services. See below for diff --git a/man/halt.xml b/man/halt.xml index a06dbd0097..e3fa60a915 100644 --- a/man/halt.xml +++ b/man/halt.xml @@ -133,6 +133,14 @@ </varlistentry> <varlistentry> + <term><option>-n</option></term> + <term><option>--no-sync</option></term> + + <listitem><para>Don't sync hard disks/storage media before + halt, power-off, reboot.</para></listitem> + </varlistentry> + + <varlistentry> <term><option>--no-wall</option></term> <listitem><para>Do not send wall message before halt, diff --git a/man/journalctl.xml b/man/journalctl.xml index b281f26b45..3efe6ef62a 100644 --- a/man/journalctl.xml +++ b/man/journalctl.xml @@ -272,6 +272,16 @@ <varlistentry> <term> + <option>short-unix</option> + </term> + <listitem> + <para>is very similar, but shows seconds passed since January 1st 1970 UTC instead of wallclock + timestamps ("UNIX time"). The time is shown with microsecond accuracy.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> <option>verbose</option> </term> <listitem> @@ -350,6 +360,13 @@ </varlistentry> <varlistentry> + <term><option>--no-hostname</option></term> + + <listitem><para>Don't show the hostname field of log messages originating from the local host. This switch only + has an effect on the <option>short</option> family of output modes (see above).</para></listitem> + </varlistentry> + + <varlistentry> <term><option>-x</option></term> <term><option>--catalog</option></term> @@ -673,9 +690,9 @@ space they use falls below the specified size (specified with the usual <literal>K</literal>, <literal>M</literal>, <literal>G</literal> and <literal>T</literal> suffixes), or all - journal files contain no data older than the specified + archived journal files contain no data older than the specified timespan (specified with the usual <literal>s</literal>, - <literal>min</literal>, <literal>h</literal>, + <literal>m</literal>, <literal>h</literal>, <literal>days</literal>, <literal>months</literal>, <literal>weeks</literal> and <literal>years</literal> suffixes), or no more than the specified number of separate journal files diff --git a/man/journald.conf.xml b/man/journald.conf.xml index a9690e8138..3964cd6bc5 100644 --- a/man/journald.conf.xml +++ b/man/journald.conf.xml @@ -148,12 +148,12 @@ </varlistentry> <varlistentry> - <term><varname>RateLimitInterval=</varname></term> + <term><varname>RateLimitIntervalSec=</varname></term> <term><varname>RateLimitBurst=</varname></term> <listitem><para>Configures the rate limiting that is applied to all messages generated on the system. If, in the time - interval defined by <varname>RateLimitInterval=</varname>, + interval defined by <varname>RateLimitIntervalSec=</varname>, more messages than specified in <varname>RateLimitBurst=</varname> are logged by a service, all further messages within the interval are dropped until the @@ -162,7 +162,7 @@ per-service, so that two services which log do not interfere with each other's limits. Defaults to 1000 messages in 30s. The time specification for - <varname>RateLimitInterval=</varname> may be specified in the + <varname>RateLimitIntervalSec=</varname> may be specified in the following units: <literal>s</literal>, <literal>min</literal>, <literal>h</literal>, <literal>ms</literal>, <literal>us</literal>. To turn off any kind of rate limiting, diff --git a/man/kernel-command-line.xml b/man/kernel-command-line.xml index 42d5e006bb..9c04849f66 100644 --- a/man/kernel-command-line.xml +++ b/man/kernel-command-line.xml @@ -322,6 +322,15 @@ </varlistentry> <varlistentry> + <term><varname>systemd.default_timeout_start_sec=</varname></term> + + <listitem> + <para>Overwrites the default start job timeout <varname>DefaultTimeoutStartSec=</varname> at boot. For details, + see <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> <term><varname>modules-load=</varname></term> <term><varname>rd.modules-load=</varname></term> diff --git a/man/loginctl.xml b/man/loginctl.xml index f41acc6a1b..fb51740503 100644 --- a/man/loginctl.xml +++ b/man/loginctl.xml @@ -94,6 +94,16 @@ </varlistentry> <varlistentry> + <term><option>--value</option></term> + + <listitem> + <para>When printing properties with <command>show</command>, + only print the value, and skip the property name and + <literal>=</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> <term><option>-a</option></term> <term><option>--all</option></term> @@ -302,7 +312,10 @@ This allows users who are not logged in to run long-running services. Takes one or more user names or numeric UIDs as argument. If no argument is specified, enables/disables - lingering for the user of the session of the caller. + lingering for the user of the session of the caller.</para> + + <para>See also <varname>KillUserProcesses=</varname> setting in + <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. </para></listitem> </varlistentry> @@ -400,6 +413,37 @@ otherwise.</para> </refsect1> + <refsect1> + <title>Examples</title> + + <example> + <title>Querying user status</title> + + <programlisting>$ loginctl user-status +fatima (1005) + Since: Sat 2016-04-09 14:23:31 EDT; 54min ago + State: active + Sessions: 5 *3 + Unit: user-1005.slice + ├─user@1005.service + ... + ├─session-3.scope + ... + └─session-5.scope + ├─3473 login -- fatima + └─3515 -zsh + +Apr 09 14:40:30 laptop login[2325]: pam_unix(login:session): + session opened for user fatima by LOGIN(uid=0) +Apr 09 14:40:30 laptop login[2325]: LOGIN ON tty3 BY fatima +</programlisting> + + <para>There are two sessions, 3 and 5. Session 3 is a graphical session, + marked with a star. The tree of processing including the two corresponding + scope units and the user manager unit are shown.</para> + </example> + </refsect1> + <xi:include href="less-variables.xml" /> <refsect1> diff --git a/man/logind.conf.xml b/man/logind.conf.xml index 597759e33a..fe92277a1f 100644 --- a/man/logind.conf.xml +++ b/man/logind.conf.xml @@ -119,30 +119,46 @@ <varlistentry> <term><varname>KillUserProcesses=</varname></term> - <listitem><para>Takes a boolean argument. Configures whether - the processes of a user should be killed when the user - completely logs out (i.e. after the user's last session - ended). Defaults to <literal>no</literal>.</para> - - <para>Note that setting <varname>KillUserProcesses=1</varname> + <listitem><para>Takes a boolean argument. Configures whether the processes of a + user should be killed when the user logs out. If true, the scope unit + corresponding to the session and all processes inside that scope will be + terminated. If false, the scope is "abandoned", see + <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + and processes are not killed. Defaults to <literal>yes</literal>, + but see the options <varname>KillOnlyUsers=</varname> and + <varname>KillExcludeUsers=</varname> below.</para> + + <para>In addition to session processes, user process may run under the user + manager unit <filename>user@.service</filename>. Depending on the linger + settings, this may allow users to run processes independent of their login + sessions. See the description of <command>enable-linger</command> in + <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + </para> + + <para>Note that setting <varname>KillUserProcesses=yes</varname> will break tools like - <citerefentry project='die-net'><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem> + <citerefentry project='die-net'><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry> + and + <citerefentry project='die-net'><refentrytitle>tmux</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + unless they are moved out of the session scope. See example in + <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + </para></listitem> </varlistentry> <varlistentry> <term><varname>KillOnlyUsers=</varname></term> <term><varname>KillExcludeUsers=</varname></term> - <listitem><para>These settings take space-separated lists of - usernames that influence the effect of - <varname>KillUserProcesses=</varname>. If not empty, only - processes of users listed in <varname>KillOnlyUsers=</varname> - will be killed when they log out entirely. Processes of users - listed in <varname>KillExcludeUsers=</varname> are excluded - from being killed. <varname>KillExcludeUsers=</varname> - defaults to <literal>root</literal> and takes precedence over - <varname>KillOnlyUsers=</varname>, which defaults to the empty - list.</para></listitem> + <listitem><para>These settings take space-separated lists of usernames that override + the <varname>KillUserProcesses=</varname> setting. A user name may be added to + <varname>KillExcludeUsers=</varname> to exclude the processes in the session scopes of + that user from being killed even if <varname>KillUserProcesses=yes</varname> is set. If + <varname>KillExcludeUsers=</varname> is not set, the <literal>root</literal> user is + excluded by default. <varname>KillExcludeUsers=</varname> may be set to an empty value + to override this default. If a user is not excluded, <varname>KillOnlyUsers=</varname> + is checked next. If this setting is specified, only the session scopes of those users + will be killed. Otherwise, users are subject to the + <varname>KillUserProcesses=yes</varname> setting.</para></listitem> </varlistentry> <varlistentry> @@ -281,6 +297,22 @@ </varlistentry> <varlistentry> + <term><varname>InhibitorsMax=</varname></term> + + <listitem><para>Controls the maximum number of concurrent inhibitors to permit. Defaults to 8192 + (8K).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SessionsMax=</varname></term> + + <listitem><para>Controls the maximum number of concurrent user sessions to manage. Defaults to 8192 + (8K). Depending on how the <filename>pam_systemd.so</filename> module is included in the PAM stack + configuration, further login sessions will either be refused, or permitted but not tracked by + <filename>systemd-logind</filename>.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>UserTasksMax=</varname></term> <listitem><para>Sets the maximum number of OS tasks each user diff --git a/man/machinectl.xml b/man/machinectl.xml index 0e07c201bd..4b7f9a0391 100644 --- a/man/machinectl.xml +++ b/man/machinectl.xml @@ -133,7 +133,16 @@ <para>When listing VM or container images, do not suppress images beginning in a dot character - (<literal>.</literal>).</para></listitem> + (<literal>.</literal>).</para> + + <para>When cleaning VM or container images, remove all images, not just hidden ones.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--value</option></term> + + <listitem><para>When printing properties with <command>show</command>, only print the value, + and skip the property name and <literal>=</literal>.</para></listitem> </varlistentry> <varlistentry> @@ -186,16 +195,14 @@ </varlistentry> <varlistentry> - <term><option>--setenv=</option></term> + <term><option>-E <replaceable>NAME</replaceable>=<replaceable>VALUE</replaceable></option></term> + <term><option>--setenv=<replaceable>NAME</replaceable>=<replaceable>VALUE</replaceable></option></term> - <listitem><para>When used with the <command>shell</command> - command, sets an environment variable to pass to the executed - shell. Takes a pair of environment variable name and value, - separated by <literal>=</literal> as argument. This switch - may be used multiple times to set multiple environment - variables. Note that this switch is not supported for the - <command>login</command> command (see - below).</para></listitem> + <listitem><para>When used with the <command>shell</command> command, sets an environment + variable to pass to the executed shell. Takes an environment variable name and value, + separated by <literal>=</literal>. This switch may be used multiple times to set multiple + environment variables. Note that this switch is not supported for the + <command>login</command> command (see below).</para></listitem> </varlistentry> <varlistentry> @@ -210,9 +217,11 @@ <term><option>--read-only</option></term> <listitem><para>When used with <command>bind</command>, applies - a read-only bind mount.</para></listitem> - </varlistentry> + a read-only bind mount.</para> + <para>When used with <command>clone</command>, <command>import-raw</command> or <command>import-tar</command> a + read-only container or VM image is created.</para></listitem> + </varlistentry> <varlistentry> <term><option>-n</option></term> @@ -580,19 +589,20 @@ <varlistentry> <term><command>clone</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term> - <listitem><para>Clones a container or VM image. The - arguments specify the name of the image to clone and the name - of the newly cloned image. Note that plain directory container - images are cloned into subvolume images with this command. - Note that cloning a container or VM image is optimized for - btrfs file systems, and might not be efficient on others, due - to file system limitations.</para> + <listitem><para>Clones a container or VM image. The arguments specify the name of the image to clone and the + name of the newly cloned image. Note that plain directory container images are cloned into btrfs subvolume + images with this command, if the underlying file system supports this. Note that cloning a container or VM + image is optimized for btrfs file systems, and might not be efficient on others, due to file system + limitations.</para> <para>Note that this command leaves host name, machine ID and all other settings that could identify the instance unmodified. The original image and the cloned copy will hence share these credentials, and it might be necessary to manually - change them in the copy.</para></listitem> + change them in the copy.</para> + + <para>If combined with the <option>--read-only</option> switch a read-only cloned image is + created.</para></listitem> </varlistentry> <varlistentry> @@ -653,6 +663,23 @@ itself.</para></listitem> </varlistentry> + <varlistentry> + <term><command>clean</command></term> + + <listitem><para>Remove hidden VM or container images (or all). This command removes all hidden machine images + from <filename>/var/lib/machines</filename>, i.e. those whose name begins with a dot. Use <command>machinectl + list-images --all</command> to see a list of all machine images, including the hidden ones.</para> + + <para>When combined with the <option>--all</option> switch removes all images, not just hidden ones. This + command effectively empties <filename>/var/lib/machines</filename>.</para> + + <para>Note that commands such as <command>machinectl pull-tar</command> or <command>machinectl + pull-raw</command> usually create hidden, read-only, unmodified machine images from the downloaded image first, + before cloning a writable working copy of it, in order to avoid duplicate downloads in case of images that are + reused multiple times. Use <command>machinectl clean</command> to remove old, hidden images created this + way.</para></listitem> + </varlistentry> + </variablelist></refsect2> <refsect2><title>Image Transfer Commands</title><variablelist> @@ -933,12 +960,12 @@ <title>Download a Fedora image, set a root password in it, start it as service</title> - <programlisting># machinectl pull-raw --verify=no http://ftp.halifax.rwth-aachen.de/fedora/linux/releases/21/Cloud/Images/x86_64/Fedora-Cloud-Base-20141203-21.x86_64.raw.xz -# systemd-nspawn -M Fedora-Cloud-Base-20141203-21 + <programlisting># machinectl pull-raw --verify=no https://dl.fedoraproject.org/pub/fedora/linux/releases/23/Cloud/x86_64/Images/Fedora-Cloud-Base-23-20151030.x86_64.raw.xz +# systemd-nspawn -M Fedora-Cloud-Base-23-20151030 # passwd # exit -# machinectl start Fedora-Cloud-Base-20141203-21 -# machinectl login Fedora-Cloud-Base-20141203-21</programlisting> +# machinectl start Fedora-Cloud-Base-23-20151030 +# machinectl login Fedora-Cloud-Base-23-20151030</programlisting> <para>This downloads the specified <filename>.raw</filename> image with verification disabled. Then, a shell is opened in it diff --git a/man/networkctl.xml b/man/networkctl.xml index c688714b30..24e1de6986 100644 --- a/man/networkctl.xml +++ b/man/networkctl.xml @@ -102,12 +102,14 @@ <varlistentry> <term> <command>list</command> + <optional><replaceable>LINK...</replaceable></optional> </term> <listitem> - <para>Show a list of existing links and their - status. Produces output similar to <programlisting> -IDX LINK TYPE OPERATIONAL SETUP + <para>Show a list of existing links and their status. If no further arguments are specified shows all links, + otherwise just the specified links. Produces output similar to: + + <programlisting>IDX LINK TYPE OPERATIONAL SETUP 1 lo loopback carrier unmanaged 2 eth0 ether routable configured 3 virbr0 ether no-carrier unmanaged @@ -128,10 +130,10 @@ IDX LINK TYPE OPERATIONAL SETUP state, kernel module driver, hardware and IP address, configured DNS servers, etc.</para> - <para>When no links are specified, routable links are - shown. Also see the option <option>--all</option>.</para> + <para>When no links are specified, an overall network status is shown. Also see the option + <option>--all</option>.</para> - <para>Produces output similar to + <para>Produces output similar to: <programlisting> ● State: routable Address: 10.193.76.5 on eth0 @@ -148,11 +150,26 @@ IDX LINK TYPE OPERATIONAL SETUP <varlistentry> <term> <command>lldp</command> + <optional><replaceable>LINK...</replaceable></optional> </term> <listitem> - <para>Show LLDP (Link Layer Discovery Protocol) - status.</para> + <para>Show discovered LLDP (Link Layer Discovery Protocol) neighbors. If one or more link names are specified + only neighbors on those interfaces are shown. Otherwise shows discovered neighbors on all interfaces. Note + that for this feature to work, <varname>LLDP=</varname> must be turned on on the specific interface, see + <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for + details.</para> + + <para>Produces output similar to: + <programlisting>LINK CHASSIS ID SYSTEM NAME CAPS PORT ID PORT DESCRIPTION +enp0s25 00:e0:4c:00:00:00 GS1900 ..b........ 2 Port #2 + +Capability Flags: +o - Other; p - Repeater; b - Bridge; w - WLAN Access Point; r - Router; +t - Telephone; d - DOCSIS cable device; a - Station; c - Customer VLAN; +s - Service VLAN, m - Two-port MAC Relay (TPMR) + +1 neighbors listed.</programlisting></para> </listitem> </varlistentry> </variablelist> diff --git a/man/networkd.conf.xml b/man/networkd.conf.xml new file mode 100644 index 0000000000..4bfc4f773a --- /dev/null +++ b/man/networkd.conf.xml @@ -0,0 +1,154 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2014 Vinay Kulkarni + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="networkd.conf" conditional='ENABLE_NETWORKD' + xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>networkd.conf</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Vinay</firstname> + <surname>Kulkarni</surname> + <email>kulkarniv@vmware.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>networkd.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>networkd.conf</refname> + <refname>networkd.conf.d</refname> + <refpurpose>Global Network configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/systemd/networkd.conf</filename></para> + <para><filename>/etc/systemd/networkd.conf.d/*.conf</filename></para> + <para><filename>/usr/lib/systemd/networkd.conf.d/*.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>These configuration files control global network parameters. + Currently the DHCP Unique Identifier (DUID).</para> + + </refsect1> + + <xi:include href="standard-conf.xml" xpointer="main-conf" /> + + <refsect1> + <title>[DHCP] Section Options</title> + + <para>This section configures the DHCP Unique Identifier (DUID) value used by DHCP + protocol. DHCPv6 client protocol sends the DHCP Unique Identifier and the interface + Identity Association Identifier (IAID) to a DHCP server when acquiring a dynamic IPv6 + address. DHCPv4 client protocol sends IAID and DUID to the DHCP server when acquiring + a dynamic IPv4 address if <option>ClientIdentifier=duid</option>. IAID and DUID allows + a DHCP server to uniquely identify the machine and the interface requesting a DHCP IP. + To configure IAID and ClientIdentifier, see + <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para> + + <para>The following options are understood:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>DUIDType=</varname></term> + <listitem><para>Specifies how the DUID should be generated. See + <ulink url="https://tools.ietf.org/html/rfc3315#section-9">RFC 3315</ulink> + for a description of all the options.</para> + + <para>The following values are understood: + <variablelist> + <varlistentry> + <term><option>vendor</option> </term> + <listitem><para>If <literal>DUIDType=vendor</literal>, then the DUID value will be generated using + <literal>43793</literal> as the vendor identifier (systemd) and hashed contents of + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + This is the default if <varname>DUIDType=</varname> is not specified. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>link-layer-time</option> </term> + <term><option>link-layer</option> </term> + <term><option>uuid</option> </term> + <listitem><para>Those values are parsed and can be used to set the DUID type + field, but DUID contents must be provided using <varname>DUIDRawData=</varname>. + </para></listitem> + </varlistentry> + </variablelist> + </para> + + <para>In all cases, <varname>DUIDRawData=</varname> can be used to override the + actual DUID value that is used.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DUIDRawData=</varname></term> + <listitem><para>Specifies the DHCP DUID value as a single newline-terminated, hexadecimal string, with each + byte separated by <literal>:</literal>. The DUID that is sent is composed of the DUID type specified by + <varname>DUIDType=</varname> and the value configured here.</para> + + <para>The DUID value specified here overrides the DUID that systemd-networkd generates using the machine-id + from the <filename>/etc/machine-id</filename> file. To configure DUID per-network, see + <citerefentry><refentrytitle>systemd.network </refentrytitle><manvolnum>5</manvolnum></citerefentry>. + The configured DHCP DUID should conform to the specification in + <ulink url="http://tools.ietf.org/html/rfc3315#section-9">RFC 3315</ulink>, + <ulink url="http://tools.ietf.org/html/rfc6355">RFC 6355</ulink>. To configure IAID, see + <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum> + </citerefentry>.</para> + + <example> + <title>A <option>DUIDType=vendor</option> with a custom value</title> + + <programlisting>DUIDType=vendor +DUIDRawData=00:00:ab:11:f9:2a:c2:77:29:f9:5c:00</programlisting> + + <para>This specifies a 14 byte DUID, with the type DUID-EN (<literal>00:02</literal>), enterprise number + 43793 (<literal>00:00:ab:11</literal>), and identifier value <literal>f9:2a:c2:77:29:f9:5c:00</literal>. + </para> + </example> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/nss-myhostname.xml b/man/nss-myhostname.xml index 251bdecbad..a920ec334f 100644 --- a/man/nss-myhostname.xml +++ b/man/nss-myhostname.xml @@ -57,12 +57,11 @@ <refsect1> <title>Description</title> - <para><command>nss-myhostname</command> is a plugin for the GNU - Name Service Switch (NSS) functionality of the GNU C Library - (<command>glibc</command>), primarily providing hostname resolution - for the locally configured system hostname as returned by - <citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>. - The precise hostnames resolved by this module are:</para> + <para><command>nss-myhostname</command> is a plug-in module for the GNU Name Service Switch (NSS) functionality of + the GNU C Library (<command>glibc</command>), primarily providing hostname resolution for the locally configured + system hostname as returned by + <citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>. The precise + hostnames resolved by this module are:</para> <itemizedlist> <listitem><para>The local, configured hostname is resolved to @@ -71,16 +70,16 @@ is on the local loopback) and the IPv6 address ::1 (which is the local host).</para></listitem> - <listitem><para>The hostname <literal>localhost</literal> (as well as any hostname ending in - <literal>.localhost</literal>, <literal>.localdomain</literal> or equal to <literal>localdomain</literal>) is - resolved to the IP addresses 127.0.0.1 and ::1.</para></listitem> + <listitem><para>The hostnames <literal>localhost</literal> and + <literal>localhost.localdomain</literal> (as well as any hostname + ending in <literal>.localhost</literal> or <literal>.localhost.localdomain</literal>) + are resolved to the IP addresses 127.0.0.1 and ::1.</para></listitem> <listitem><para>The hostname <literal>gateway</literal> is resolved to all current default routing gateway addresses, ordered by their metric. This assigns a stable hostname to the current gateway, useful for referencing it independently of the current network configuration state.</para></listitem> - </itemizedlist> <para>Various software relies on an always-resolvable local @@ -93,29 +92,25 @@ changing <filename>/etc/hosts</filename> is unnecessary, and on many systems, the file becomes entirely optional.</para> - <para>To activate the NSS modules, <literal>myhostname</literal> - has to be added to the line starting with - <literal>hosts:</literal> in - <filename>/etc/nsswitch.conf</filename>.</para> + <para>To activate the NSS modules, add <literal>myhostname</literal> to the line starting with + <literal>hosts:</literal> in <filename>/etc/nsswitch.conf</filename>.</para> - <para>It is recommended to place <literal>myhostname</literal> - last in the <filename>nsswitch.conf</filename> line to make sure - that this mapping is only used as fallback, and that any DNS or - <filename>/etc/hosts</filename> based mapping takes - precedence.</para> + <para>It is recommended to place <literal>myhostname</literal> last in the <filename>nsswitch.conf</filename>' + <literal>hosts:</literal> line to make sure that this mapping is only used as fallback, and that any DNS or + <filename>/etc/hosts</filename> based mapping takes precedence.</para> </refsect1> <refsect1> <title>Example</title> - <para>Here is an example <filename>/etc/nsswitch.conf</filename> - file that enables <command>myhostname</command> correctly:</para> + <para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables + <command>nss-myhostname</command> correctly:</para> <programlisting>passwd: compat mymachines group: compat mymachines shadow: compat -hosts: files resolve mymachines <command>myhostname</command> +hosts: files mymachines resolve <command>myhostname</command> networks: files protocols: db files diff --git a/man/nss-mymachines.xml b/man/nss-mymachines.xml index d2bec763bb..ec047449bf 100644 --- a/man/nss-mymachines.xml +++ b/man/nss-mymachines.xml @@ -56,42 +56,37 @@ <refsect1> <title>Description</title> - <para><command>nss-mymachines</command> is a plugin for the GNU - Name Service Switch (NSS) functionality of the GNU C Library - (<command>glibc</command>), providing hostname resolution for - container names of containers running locally that are registered - with - <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - The container names are resolved to the IP addresses of the - specific container, ordered by their scope.</para> - - <para>The module also resolves user IDs used by containers to user - names indicating the container name, and back.</para> - - <para>To activate the NSS modules, <literal>mymachines</literal> - has to be added to the lines starting with - <literal>hosts:</literal>, <literal>passwd:</literal> and - <literal>group:</literal> in + <para><command>nss-mymachines</command> is a plug-in module for the GNU Name Service Switch (NSS) functionality of + the GNU C Library (<command>glibc</command>), providing hostname resolution for the names of containers running + locally that are registered with + <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. The + container names are resolved to the IP addresses of the specific container, ordered by their scope. This + functionality only applies to containers using network namespacing.</para> + + <para>The module also resolves user and group IDs used by containers to user and group names indicating the + container name, and back. This functionality only applies to containers using user namespacing.</para> + + <para>To activate the NSS module, add <literal>mymachines</literal> to the lines starting with + <literal>hosts:</literal>, <literal>passwd:</literal> and <literal>group:</literal> in <filename>/etc/nsswitch.conf</filename>.</para> - <para>It is recommended to place <literal>mymachines</literal> - near the end of the <filename>nsswitch.conf</filename> lines to - make sure that its mappings are only used as fallback, and that any - other mappings, such as DNS or <filename>/etc/hosts</filename> - based mappings, take precedence.</para> + <para>It is recommended to place <literal>mymachines</literal> after the <literal>files</literal> or + <literal>compat</literal> entry of the <filename>/etc/nsswitch.conf</filename> lines to make sure that its mappings + are preferred over other resolvers such as DNS, but so that <filename>/etc/hosts</filename>, + <filename>/etc/passwd</filename> and <filename>/etc/group</filename> based mappings take precedence.</para> </refsect1> <refsect1> <title>Example</title> - <para>Here is an example <filename>/etc/nsswitch.conf</filename> - file that enables <command>mymachines</command> correctly:</para> + <para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables + <command>nss-mymachines</command> correctly:</para> <programlisting>passwd: compat <command>mymachines</command> group: compat <command>mymachines</command> shadow: compat -hosts: files resolve <command>mymachines</command> myhostname +hosts: files <command>mymachines</command> resolve myhostname networks: files protocols: db files diff --git a/man/nss-resolve.xml b/man/nss-resolve.xml index 8b0928145f..d9e56453e8 100644 --- a/man/nss-resolve.xml +++ b/man/nss-resolve.xml @@ -56,37 +56,36 @@ <refsect1> <title>Description</title> - <para><command>nss-resolve</command> is a plugin module for the - GNU Name Service Switch (NSS) functionality of the GNU C Library - (<command>glibc</command>) enabling it to resolve host names via - the - <citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry> - local network name resolution service.</para> - - <para>To activate the NSS module, <literal>resolve</literal> - has to be added to the line starting with - <literal>hosts:</literal> in - <filename>/etc/nsswitch.conf</filename>.</para> - - <para>It is recommended to place <literal>resolve</literal> early - in the <filename>nsswitch.conf</filename> line (but after the - <literal>files</literal> entry), replacing the - <literal>dns</literal> entry if it exists, to ensure DNS queries - are always routed via + <para><command>nss-resolve</command> is a plug-in module for the GNU Name Service Switch (NSS) functionality of the + GNU C Library (<command>glibc</command>) enabling it to resolve host names via the + <citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry> local network + name resolution service. It replaces the <command>nss-dns</command> plug-in module that traditionally resolves + hostnames via DNS.</para> + + <para>To activate the NSS module, add <literal>resolve</literal> to the line starting with + <literal>hosts:</literal> in <filename>/etc/nsswitch.conf</filename>.</para> + + <para>It is recommended to place <literal>resolve</literal> early in <filename>/etc/nsswitch.conf</filename>' + <literal>hosts:</literal> line (but after the <literal>files</literal> or <literal>mymachines</literal> entries), + replacing the <literal>dns</literal> entry if it exists, to ensure DNS queries are always routed via <citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + + <para>Note that <command>nss-resolve</command> will chain-load <command>nss-dns</command> if + <filename>systemd-resolved.service</filename> is not running, ensuring that basic DNS resolution continues to work + if the service is down.</para> </refsect1> <refsect1> <title>Example</title> - <para>Here is an example <filename>/etc/nsswitch.conf</filename> - file that enables <command>resolve</command> correctly:</para> + <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 shadow: compat -hosts: files <command>resolve</command> mymachines myhostname +hosts: files mymachines <command>resolve</command> myhostname networks: files protocols: db files @@ -96,12 +95,6 @@ rpc: db files netgroup: nis</programlisting> - <para>Note that <command>nss-resolve</command> will chain-load - <command>nss-dns</command> if - <filename>systemd-resolved.service</filename> is not running, - ensuring that basic DNS resolution continues to work if the - service is down.</para> - </refsect1> <refsect1> diff --git a/man/sd_bus_creds_get_pid.xml b/man/sd_bus_creds_get_pid.xml index 3bcda46656..4c05835568 100644 --- a/man/sd_bus_creds_get_pid.xml +++ b/man/sd_bus_creds_get_pid.xml @@ -406,15 +406,11 @@ For processes that are not part of a session, returns -ENXIO. </para> - <para><function>sd_bus_creds_has_effective_cap()</function> will - check whether the capability specified by - <parameter>capability</parameter> was set in the effective - capabilities mask. A positive return value means that is was - set, zero means that it was not set, and a negative return - value indicates an error. See - <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> - and <varname>Capabilities=</varname> and - <varname>CapabilityBoundingSet=</varname> settings in + <para><function>sd_bus_creds_has_effective_cap()</function> will check whether the capability specified by + <parameter>capability</parameter> was set in the effective capabilities mask. A positive return value means that it + was set, zero means that it was not set, and a negative return value indicates an error. See <citerefentry + project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> and the + <varname>AmbientCapabilities=</varname> and <varname>CapabilityBoundingSet=</varname> settings in <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. </para> diff --git a/man/sd_event_source_set_priority.xml b/man/sd_event_source_set_priority.xml index 9234f4233e..8c9b39fe5e 100644 --- a/man/sd_event_source_set_priority.xml +++ b/man/sd_event_source_set_priority.xml @@ -97,7 +97,7 @@ <constant>SD_EVENT_PRIORITY_IDLE</constant> (100) may be used to indicate event sources that shall be dispatched early, normally or late. It is recommended to specify priorities based on these - definitions, and relative to them -- however, the full 64bit + definitions, and relative to them — however, the full 64bit signed integer range is available for ordering event sources.</para> diff --git a/man/sd_journal_add_match.xml b/man/sd_journal_add_match.xml index 3b27444f8d..98415d53fd 100644 --- a/man/sd_journal_add_match.xml +++ b/man/sd_journal_add_match.xml @@ -88,11 +88,19 @@ <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> and <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - Matches are of the form <literal>FIELD=value</literal>, where the - field part is a short uppercase string consisting only of 0–9, A–Z - and the underscore. It may not begin with two underscores or be - the empty string. The value part may be any value, including - binary. If a match is applied, only entries with this field set + Parameter <parameter>data</parameter> must be of the form + <literal><replaceable>FIELD</replaceable>=<replaceable>value</replaceable></literal>, + where the <replaceable>FIELD</replaceable> part is a short uppercase string consisting only + of 0–9, A–Z and the underscore; it may not begin with two underscores or be the empty + string. The <replaceable>value</replaceable> part may be anything, including binary. Parameter + <parameter>size</parameter> specifies the number of bytes in <parameter>data</parameter> + (i.e. the length of <replaceable>FIELD</replaceable>, plus one, plus the length of + <replaceable>value</replaceable>). Parameter <parameter>size</parameter> may also be + specified as <constant>0</constant>, in which case <parameter>data</parameter> + must be a <constant>NUL</constant>-terminated string, and the bytes before the terminating + zero are used as the match.</para> + + <para>If a match is applied, only entries with this field set will be iterated. Multiple matches may be active at the same time: If they apply to different fields, only entries with both fields set like this will be iterated. If they apply to the same fields, diff --git a/man/sd_journal_get_data.xml b/man/sd_journal_get_data.xml index 1f25d068d7..908ee7db16 100644 --- a/man/sd_journal_get_data.xml +++ b/man/sd_journal_get_data.xml @@ -148,7 +148,7 @@ <function>sd_journal_enumerate_unique()</function>. This threshold is a hint only: it indicates that the client program is interested only in the initial parts of the data fields, up to the threshold - in size -- but the library might still return larger data objects. + in size — but the library might still return larger data objects. That means applications should not rely exclusively on this setting to limit the size of the data fields returned, but need to apply a explicit size limit on the returned data as well. This diff --git a/man/sd_journal_open.xml b/man/sd_journal_open.xml index fef453f8dc..153af2387f 100644 --- a/man/sd_journal_open.xml +++ b/man/sd_journal_open.xml @@ -45,14 +45,16 @@ <refnamediv> <refname>sd_journal_open</refname> <refname>sd_journal_open_directory</refname> + <refname>sd_journal_open_directory_fd</refname> <refname>sd_journal_open_files</refname> - <refname>sd_journal_open_container</refname> + <refname>sd_journal_open_files_fd</refname> <refname>sd_journal_close</refname> <refname>sd_journal</refname> <refname>SD_JOURNAL_LOCAL_ONLY</refname> <refname>SD_JOURNAL_RUNTIME_ONLY</refname> <refname>SD_JOURNAL_SYSTEM</refname> <refname>SD_JOURNAL_CURRENT_USER</refname> + <refname>SD_JOURNAL_OS_ROOT</refname> <refpurpose>Open the system journal for reading</refpurpose> </refnamediv> @@ -74,6 +76,13 @@ </funcprototype> <funcprototype> + <funcdef>int <function>sd_journal_open_directory_fd</function></funcdef> + <paramdef>sd_journal **<parameter>ret</parameter></paramdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>flags</parameter></paramdef> + </funcprototype> + + <funcprototype> <funcdef>int <function>sd_journal_open_files</function></funcdef> <paramdef>sd_journal **<parameter>ret</parameter></paramdef> <paramdef>const char **<parameter>paths</parameter></paramdef> @@ -81,9 +90,10 @@ </funcprototype> <funcprototype> - <funcdef>int <function>sd_journal_open_container</function></funcdef> + <funcdef>int <function>sd_journal_open_files_fd</function></funcdef> <paramdef>sd_journal **<parameter>ret</parameter></paramdef> - <paramdef>const char *<parameter>machine</parameter></paramdef> + <paramdef>int <parameter>fds[]</parameter></paramdef> + <paramdef>unsigned <parameter>n_fds</parameter></paramdef> <paramdef>int <parameter>flags</parameter></paramdef> </funcprototype> @@ -117,29 +127,28 @@ <constant>SD_JOURNAL_CURRENT_USER</constant> are specified, all journal file types will be opened.</para> - <para><function>sd_journal_open_directory()</function> is similar - to <function>sd_journal_open()</function> but takes an absolute - directory path as argument. All journal files in this directory - will be opened and interleaved automatically. This call also takes - a flags argument, but it must be passed as 0 as no flags are - currently understood for this call.</para> - - <para><function>sd_journal_open_files()</function> is similar to - <function>sd_journal_open()</function> but takes a - <constant>NULL</constant>-terminated list of file paths to open. - All files will be opened and interleaved automatically. This call - also takes a flags argument, but it must be passed as 0 as no - flags are currently understood for this call. Please note that in - the case of a live journal, this function is only useful for - debugging, because individual journal files can be rotated at any - moment, and the opening of specific files is inherently - racy.</para> - - <para><function>sd_journal_open_container()</function> is similar - to <function>sd_journal_open()</function> but opens the journal - files of a running OS container. The specified machine name refers - to a container that is registered with - <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + <para><function>sd_journal_open_directory()</function> is similar to <function>sd_journal_open()</function> but + takes an absolute directory path as argument. All journal files in this directory will be opened and interleaved + automatically. This call also takes a flags argument. The 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> + + <para><function>sd_journal_open_directory_fd()</function> is similar to + <function>sd_journal_open_directory()</function>, but takes a file descriptor referencing a directory in the file + system instead of an absolute file system path.</para> + + <para><function>sd_journal_open_files()</function> is similar to <function>sd_journal_open()</function> but takes a + <constant>NULL</constant>-terminated list of file paths to open. All files will be opened and interleaved + automatically. This call also takes a flags argument, but it must be passed as 0 as no flags are currently + understood for this call. Please note that in the case of a live journal, this function is only useful for + debugging, because individual journal files can be rotated at any moment, and the opening of specific files is + inherently racy.</para> + + <para><function>sd_journal_open_files_fd()</function> is similar to <function>sd_journal_open_files()</function> + but takes an array of open file descriptors that must reference journal files, instead of an array of file system + paths. Pass the array of file descriptors as second argument, and the number of array entries in the third. The + flags parameter must be passed as 0.</para> <para><varname>sd_journal</varname> objects cannot be used in the child after a fork. Functions which take a journal object as an @@ -205,26 +214,6 @@ </refsect1> <refsect1> - <title>History</title> - - <para><function>sd_journal_open()</function>, - <function>sd_journal_close()</function>, - <constant>SD_JOURNAL_LOCAL_ONLY</constant>, - <constant>SD_JOURNAL_RUNTIME_ONLY</constant>, - <constant>SD_JOURNAL_SYSTEM_ONLY</constant> were added in - systemd-38.</para> - - <para><function>sd_journal_open_directory()</function> was added - in systemd-187.</para> - - <para><constant>SD_JOURNAL_SYSTEM</constant>, - <constant>SD_JOURNAL_CURRENT_USER</constant>, and - <function>sd_journal_open_files()</function> were added in - systemd-205. <constant>SD_JOURNAL_SYSTEM_ONLY</constant> was - deprecated.</para> - </refsect1> - - <refsect1> <title>See Also</title> <para> diff --git a/man/sd_uid_get_state.xml b/man/sd_uid_get_state.xml index 4cc7405dd6..130af761da 100644 --- a/man/sd_uid_get_state.xml +++ b/man/sd_uid_get_state.xml @@ -218,19 +218,6 @@ </refsect1> <refsect1> - <title>History</title> - - <para><function>sd_uid_get_state()</function>, - <function>sd_uid_is_on_seat()</function>, - <function>sd_uid_get_sessions()</function>, and - <function>sd_uid_get_seats()</function> functions were added in - systemd-31.</para> - - <para><function>sd_uid_get_display()</function> was added in - systemd-213.</para> - </refsect1> - - <refsect1> <title>See Also</title> <para> diff --git a/man/sd_watchdog_enabled.xml b/man/sd_watchdog_enabled.xml index 6e27528a71..3de9899453 100644 --- a/man/sd_watchdog_enabled.xml +++ b/man/sd_watchdog_enabled.xml @@ -155,18 +155,6 @@ </refsect1> <refsect1> - <title>History</title> - - <para>The watchdog functionality and the - <varname>$WATCHDOG_USEC</varname> variable were added in - systemd-41.</para> - - <para><function>sd_watchdog_enabled()</function> function was - added in systemd-209. Since that version, the - <varname>$WATCHDOG_PID</varname> variable is also set.</para> - </refsect1> - - <refsect1> <title>See Also</title> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, diff --git a/man/systemctl.xml b/man/systemctl.xml index 1480bf8380..991e9bafaf 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -233,6 +233,16 @@ </varlistentry> <varlistentry> + <term><option>--value</option></term> + + <listitem> + <para>When printing properties with <command>show</command>, + only print the value, and skip the property name and + <literal>=</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> <term><option>--show-types</option></term> <listitem> @@ -1074,22 +1084,22 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <term><command>preset <replaceable>NAME</replaceable>...</command></term> <listitem> - <para>Reset one or more unit files, as specified on the - command line, to the defaults configured in the preset - policy files. This has the same effect as - <command>disable</command> or <command>enable</command>, - depending how the unit is listed in the preset files.</para> + <para>Reset the enable/disable status one or more unit files, as specified on + the command line, to the defaults configured in the preset policy files. This + has the same effect as <command>disable</command> or + <command>enable</command>, depending how the unit is listed in the preset + files.</para> - <para>Use <option>--preset-mode=</option> to control - whether units shall be enabled and disabled, or only - enabled, or only disabled.</para> + <para>Use <option>--preset-mode=</option> to control whether units shall be + enabled and disabled, or only enabled, or only disabled.</para> - <para>For more information on the preset policy format, - see + <para>If the unit carries no install information, it will be silently ignored + by this command.</para> + + <para>For more information on the preset policy format, see <citerefentry><refentrytitle>systemd.preset</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - For more information on the concept of presets, please - consult the <ulink - url="http://freedesktop.org/wiki/Software/systemd/Preset">Preset</ulink> + For more information on the concept of presets, please consult the + <ulink url="http://freedesktop.org/wiki/Software/systemd/Preset">Preset</ulink> document.</para> </listitem> </varlistentry> @@ -1158,22 +1168,32 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service </row> <row> <entry><literal>static</literal></entry> - <entry>The unit file is not enabled, and has no provisions for enabling in the <literal>[Install]</literal> section.</entry> + <entry>The unit file is not enabled, and has no provisions for enabling in the <literal>[Install]</literal> unit file section.</entry> <entry>0</entry> </row> <row> <entry><literal>indirect</literal></entry> - <entry>The unit file itself is not enabled, but it has a non-empty <varname>Also=</varname> setting in the <literal>[Install]</literal> section, listing other unit files that might be enabled.</entry> + <entry>The unit file itself is not enabled, but it has a non-empty <varname>Also=</varname> setting in the <literal>[Install]</literal> unit file section, listing other unit files that might be enabled.</entry> <entry>0</entry> </row> <row> <entry><literal>disabled</literal></entry> - <entry>Unit file is not enabled, but contains an <literal>[Install]</literal> section with installation instructions.</entry> + <entry>The unit file is not enabled, but contains an <literal>[Install]</literal> section with installation instructions.</entry> <entry>> 0</entry> </row> <row> + <entry><literal>generated</literal></entry> + <entry>The unit file was generated dynamically via a generator tool. See <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>. Generated unit files may not be enabled, they are enabled implicitly by their generator.</entry> + <entry>0</entry> + </row> + <row> + <entry><literal>transient</literal></entry> + <entry>The unit file has been created dynamically with the runtime API. Transient units may not be enabled.</entry> + <entry>0</entry> + </row> + <row> <entry><literal>bad</literal></entry> - <entry>Unit file is invalid or another error occurred. Note that <command>is-enabled</command> will not actually return this state, but print an error message instead. However the unit file listing printed by <command>list-unit-files</command> might show it.</entry> + <entry>The unit file is invalid or another error occurred. Note that <command>is-enabled</command> will not actually return this state, but print an error message instead. However the unit file listing printed by <command>list-unit-files</command> might show it.</entry> <entry>> 0</entry> </row> </tbody> @@ -1225,6 +1245,28 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service </varlistentry> <varlistentry> + <term><command>revert <replaceable>NAME</replaceable>...</command></term> + + <listitem> + <para>Revert one or more unit files to their vendor versions. This command removes drop-in configuration + files that modify the specified units, as well as any user-configured unit file that overrides a matching + vendor supplied unit file. Specifically, for a unit <literal>foo.service</literal> the matching directories + <literal>foo.service.d/</literal> with all their contained files are removed, both below the persistent and + runtime configuration directories (i.e. below <filename>/etc/systemd/system</filename> and + <filename>/run/systemd/system</filename>); if the unit file has a vendor-supplied version (i.e. a unit file + located below <filename>/usr</filename>) any matching peristent or runtime unit file that overrides it is + removed, too. Note that if a unit file has no vendor-supplied version (i.e. is only defined below + <filename>/etc/systemd/system</filename> or <filename>/run/systemd/system</filename>, but not in a unit + file stored below <filename>/usr</filename>), then it is not removed. Also, if a unit is masked, it is + unmasked.</para> + + <para>Effectively, this command may be used to undo all changes made with <command>systemctl + edit</command>, <command>systemctl set-property</command> and <command>systemctl mask</command> and puts + the original unit file with its settings back in effect.</para> + </listitem> + </varlistentry> + + <varlistentry> <term><command>add-wants <replaceable>TARGET</replaceable> <replaceable>NAME</replaceable>...</command></term> <term><command>add-requires <replaceable>TARGET</replaceable> diff --git a/man/systemd-ask-password.xml b/man/systemd-ask-password.xml index 2a4d24349b..2b6fb5a82f 100644 --- a/man/systemd-ask-password.xml +++ b/man/systemd-ask-password.xml @@ -67,7 +67,7 @@ processes.</para> <para>The purpose of this tool is to query system-wide passwords - -- that is passwords not attached to a specific user account. + — that is passwords not attached to a specific user account. Examples include: unlocking encrypted hard disks when they are plugged in or at boot, entering an SSL certificate passphrase for web and VPN servers.</para> @@ -192,6 +192,15 @@ This will output one password per line.</para></listitem> </varlistentry> + <varlistentry> + <term><option>--no-output</option></term> + + <listitem><para>Do not print passwords to standard output. + This is useful if you want to store a password in kernel + keyring with <option>--keyname</option> but do not want it + to show up on screen or in logs.</para></listitem> + </varlistentry> + <xi:include href="standard-options.xml" xpointer="help" /> </variablelist> diff --git a/man/systemd-bootchart.xml b/man/systemd-bootchart.xml deleted file mode 100644 index bcee11fd0b..0000000000 --- a/man/systemd-bootchart.xml +++ /dev/null @@ -1,323 +0,0 @@ -<?xml version='1.0'?> <!--*-nxml-*--> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - -<!-- - This file is part of systemd. - - Copyright 2012 Intel Corporation - - Authors: - Auke Kok <auke-jan.h.kok@intel.com> - William Giokas <1007380@gmail.com> - - systemd is free software; you can redistribute it and/or modify it - under the terms of the GNU Lesser General Public License as published by - the Free Software Foundation; either version 2.1 of the License, or - (at your option) any later version. - - systemd is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public License - along with systemd; If not, see <http://www.gnu.org/licenses/>. ---> - -<refentry id="systemd-bootchart" conditional='ENABLE_BOOTCHART' - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-bootchart</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Auke</firstname> - <surname>Kok</surname> - <email>auke-jan.h.kok@intel.com</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-bootchart</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-bootchart</refname> - <refpurpose>Boot performance graphing tool</refpurpose> - </refnamediv> - - <refsect1> - <title>Description</title> - <para> - <command>systemd-bootchart</command> is a tool, usually run at - system startup, that collects the CPU load, disk load, memory - usage, as well as per-process information from a running system. - Collected results are output as an SVG graph. Normally, - systemd-bootchart is invoked by the kernel by passing - <option>init=<filename>/usr/lib/systemd/systemd-bootchart</filename></option> - on the kernel command line. systemd-bootchart will then fork the - real init off to resume normal system startup, while monitoring - and logging startup information in the background. - </para> - <para> - After collecting a certain amount of data (usually 15–30 - seconds, default 20 s) the logging stops and a graph is - generated from the logged information. This graph contains vital - clues as to which resources are being used, in which order, and - where possible problems exist in the startup sequence of the - system. It is essentially a more detailed version of the - <command>systemd-analyze plot</command> function. - </para> - <para> - Of course, bootchart can also be used at any moment in time to - collect and graph some data for an amount of time. It is - recommended to use the <option>--rel</option> switch in this - case. - </para> - <para> - Bootchart does not require root privileges, and will happily run - as a normal user. - </para> - <para> - Bootchart graphs are by default written time-stamped in - <filename>/run/log</filename> and saved to the journal with - <varname>MESSAGE_ID=9f26aa562cf440c2b16c773d0479b518</varname>. - Journal field <varname>BOOTCHART=</varname> contains the - bootchart in SVG format. - </para> - - </refsect1> - - <refsect1> - <title>Invocation</title> - - <para><command>systemd-bootchart</command> can be invoked in several different ways:</para> - - <variablelist> - - <varlistentry> - <term><emphasis>Kernel invocation</emphasis></term> - <listitem><para>The kernel can invoke - <command>systemd-bootchart</command> instead of the init - process. In turn, <command>systemd-bootchart</command> will - invoke <command>/usr/lib/systemd/systemd</command>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><emphasis>Started as a standalone program</emphasis></term> - <listitem><para>One can execute - <command>systemd-bootchart</command> as normal application - from the command line. In this mode, it is highly recommended - to pass the <option>-r</option> flag in order to not graph the - time elapsed since boot and before systemd-bootchart was - started, as it may result in extremely large graphs. The time - elapsed since boot might also include any time that the system - was suspended.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>These options can also be set in the - <filename>/etc/systemd/bootchart.conf</filename> file. See - <citerefentry project='man-pages'><refentrytitle>bootchart.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para> - - <variablelist> - <xi:include href="standard-options.xml" xpointer="help" /> - - <varlistentry> - <term><option>-n</option></term> - <term><option>--sample <replaceable>N</replaceable></option></term> - <listitem><para>Specify the number of samples, - <replaceable>N</replaceable>, to record. Samples will be - recorded at intervals defined with <option>--freq</option>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-f</option></term> - <term><option>--freq <replaceable>f</replaceable></option></term> - <listitem><para>Specify the sample log frequency, a positive - real <replaceable>f</replaceable>, in Hz. Most systems can - cope with values up to 25–50 without creating too much - overhead.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-r</option></term> - <term><option>--rel</option></term> - <listitem><para>Use relative times instead of absolute times. - This is useful for using bootchart at post-boot time to - profile an already booted system. Without this option the - graph would become extremely large. If set, the horizontal - axis starts at the first recorded sample instead of time - 0.0.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-F</option></term> - <term><option>--no-filter</option></term> - <listitem><para>Disable filtering of tasks that did not - contribute significantly to the boot. Processes that are too - short-lived (only seen in one sample) or that do not consume - any significant CPU time (less than 0.001 s) will not be - displayed in the output graph. </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-C</option></term> - <term><option>--cmdline</option></term> - <listitem><para>Display the full command line with arguments - of processes, instead of only the process name. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-g</option></term> - <term><option>--control-group</option></term> - <listitem><para>Display process control group - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-o</option></term> - <term><option>--output <replaceable>path</replaceable></option></term> - <listitem><para>Specify the output directory for the graphs. - By default, bootchart writes the graphs to - <filename>/run/log</filename>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-i</option></term> - <term><option>--init <replaceable>path</replaceable></option></term> - <listitem><para>Use this init binary. Defaults to - <command>/usr/lib/systemd/systemd</command>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-p</option></term> - <term><option>--pss</option></term> - <listitem><para>Enable logging and graphing of processes' PSS - (Proportional Set Size) memory consumption. See - <filename>filesystems/proc.txt</filename> in the kernel - documentation for an explanation of this field. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-e</option></term> - <term><option>--entropy</option></term> - <listitem><para>Enable logging and graphing of the kernel - random entropy pool size.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-x</option></term> - <term><option>--scale-x <replaceable>N</replaceable></option></term> - <listitem><para>Horizontal scaling factor for all variable - graph components.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-y</option></term> - <term><option>--scale-y <replaceable>N</replaceable></option></term> - <listitem><para>Vertical scaling factor for all variable graph - components.</para></listitem> - </varlistentry> - - </variablelist> - - - </refsect1> - - <refsect1> - <title>Output</title> - - <para><command>systemd-bootchart</command> generates SVG graphs. - In order to render those on a graphical display any SVG capable - viewer can be used. It should be noted that the SVG render engines - in most browsers (including Chrome and Firefox) are many times - faster than dedicated graphical applications like Gimp and - Inkscape. Just point your browser at - <ulink url="file:///run/log/" />! - </para> - </refsect1> - - <refsect1> - <title>History</title> - - <para>This version of bootchart was implemented from scratch, but - is inspired by former bootchart incantations:</para> - - <variablelist> - <varlistentry> - <term><emphasis>Original bash</emphasis></term> - <listitem><para>The original bash/shell code implemented - bootchart. This version created a compressed tarball for - processing with external applications. This version did not - graph anything, only generated data.</para></listitem> - </varlistentry> - - <varlistentry> - <term><emphasis>Ubuntu C Implementation</emphasis></term> - <listitem><para>This version replaced the shell version with a - fast and efficient data logger, but also did not graph the - data.</para></listitem> - </varlistentry> - - <varlistentry> - <term><emphasis>Java bootchart</emphasis></term> - <listitem><para>This was the original graphing application for - charting the data, written in java.</para></listitem> - </varlistentry> - - <varlistentry> - <term><emphasis>pybootchartgui.py</emphasis></term> - <listitem><para>pybootchart created a graph from the data - collected by either the bash or C version.</para></listitem> - </varlistentry> - </variablelist> - - <para>The version of bootchart you are using now combines both the - data collection and the charting into a single application, making - it more efficient and simpler. There are no longer any timing - issues with the data collector and the grapher, as the graphing - cannot be run until the data has been collected. Also, the data - kept in memory is reduced to the absolute minimum needed.</para> - - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry project='man-pages'><refentrytitle>bootchart.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> - - <refsect1> - <title>Bugs</title> - - <para>systemd-bootchart does not get the model information for the - hard drive unless the root device is specified with - <code>root=/dev/sdxY</code>. Using UUIDs or PARTUUIDs will boot - fine, but the hard drive model will not be added to the - chart.</para> - <para>For bugs, please contact the author and current maintainer:</para> - <simplelist> - <member>Auke Kok <email>auke-jan.h.kok@intel.com</email></member> - </simplelist> - </refsect1> - -</refentry> diff --git a/man/systemd-bus-proxyd.service.xml b/man/systemd-bus-proxyd.service.xml deleted file mode 100644 index 02189eea7c..0000000000 --- a/man/systemd-bus-proxyd.service.xml +++ /dev/null @@ -1,80 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - -<!-- - This file is part of systemd. - - Copyright 2013 Zbigniew Jędrzejewski-Szmek - - systemd is free software; you can redistribute it and/or modify it - under the terms of the GNU Lesser General Public License as published by - the Free Software Foundation; either version 2.1 of the License, or - (at your option) any later version. - - systemd is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public License - along with systemd; If not, see <http://www.gnu.org/licenses/>. ---> - -<refentry id="systemd-bus-proxyd.service"> - - <refentryinfo> - <title>systemd-bus-proxyd.service</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-bus-proxyd.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-bus-proxyd.service</refname> - <refname>systemd-bus-proxyd.socket</refname> - <refpurpose>Proxy classic D-Bus clients to kdbus</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-bus-proxyd.service</filename></para> - <para><filename>systemd-bus-proxyd.socket</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-bus-proxyd.socket</filename> will launch - <filename>systemd-bus-proxyd.service</filename> for connections - to the classic D-Bus socket in - <filename>/var/run/dbus/system_bus_socket</filename>.</para> - - <para><filename>systemd-bus-proxyd.service</filename> is launched - for an existing D-Bus connection and will use - <command>systemd-bus-proxyd</command> to proxy messages from this - connection to the system bus (either kdbus or classic D-Bus). - </para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd-bus-proxyd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='dbus'><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <ulink url="http://freedesktop.org/wiki/Software/dbus">D-Bus</ulink> - </para> - </refsect1> -</refentry> diff --git a/man/systemd-bus-proxyd.xml b/man/systemd-bus-proxyd.xml deleted file mode 100644 index 0923396151..0000000000 --- a/man/systemd-bus-proxyd.xml +++ /dev/null @@ -1,108 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - -<!-- - This file is part of systemd. - - Copyright 2013 Zbigniew Jędrzejewski-Szmek - - systemd is free software; you can redistribute it and/or modify it - under the terms of the GNU Lesser General Public License as published by - the Free Software Foundation; either version 2.1 of the License, or - (at your option) any later version. - - systemd is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public License - along with systemd; If not, see <http://www.gnu.org/licenses/>. ---> - -<refentry id="systemd-bus-proxyd" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-bus-proxyd</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-bus-proxyd</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-bus-proxyd</refname> - <refpurpose>Connect STDIO or a socket to a given bus address</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>/usr/lib/systemd/systemd-bus-proxyd</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="opt"><replaceable>PLACEHOLDER</replaceable></arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-bus-proxyd</command> will proxy D-Bus - messages to and from a bus. The will be either the system bus or - the bus specified with <option>--address</option> when that option - is given. Messages will be proxied to/from standard input and - output, or the socket received through socket activation.</para> - - <para>This program can be used to connect a program using classic - D-Bus to kdbus.</para> - </refsect1> - - <refsect1> - <title>Options and Arguments</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--address=<replaceable>ADDRESS</replaceable><optional>:<replaceable>ADDRESS...</replaceable></optional></option></term> - - <listitem> - <para>Connect to the bus specified by - <replaceable>ADDRESS</replaceable>. Multiple colon-separated - addresses can be specified, in which case - <command>systemd-bus-proxyd</command> will attempt to - connect to them in turn.</para> - </listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - - <para><replaceable>PLACEHOLDER</replaceable>, if given, must be a string - of <literal>x</literal> and will be used to display information about - the process that <command>systemd-bus-proxyd</command> is forwarding - messages for.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry project='dbus'><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <ulink url="http://freedesktop.org/wiki/Software/dbus">D-Bus</ulink> - </para> - </refsect1> -</refentry> diff --git a/man/systemd-coredump.xml b/man/systemd-coredump.xml index f1598461ef..a28dc62e5a 100644 --- a/man/systemd-coredump.xml +++ b/man/systemd-coredump.xml @@ -45,50 +45,89 @@ <refnamediv> <refname>systemd-coredump</refname> - <refpurpose>Log and store core dumps</refpurpose> + <refname>systemd-coredump.socket</refname> + <refname>systemd-coredump@.service</refname> + <refpurpose>Acquire, save and process core dumps</refpurpose> </refnamediv> <refsynopsisdiv> <para><filename>/usr/lib/systemd/systemd-coredump</filename></para> + <para><filename>systemd-coredump@.service</filename></para> + <para><filename>systemd-coredump.socket</filename></para> </refsynopsisdiv> <refsect1> <title>Description</title> + <para><command>systemd-coredump</command> is a system service that can acquire core dumps + from the kernel and handle them in various ways.</para> - <para><command>systemd-coredump</command> can be used as a helper - binary by the kernel when a user space program receives a fatal - signal and dumps core. For it to be used in this capacity, it must - be specified by the - <varname>kernel.core_pattern</varname> <citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> - setting. Systemd installs - <filename>/usr/lib/sysctl.d/50-coredump.conf</filename> which - configures <varname>kernel.core_pattern</varname> to invoke - <command>systemd-coredump</command>. This file may be masked or - overridden to use a different setting following normal - <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> rules.</para> - - <para>The behavior of a specific program upon reception of a - signal is governed by a few factors which are described in detail - in <citerefentry project='man-pages'><refentrytitle>core</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - In particular, the coredump will only be processed when the - related resource limits are high enough. For programs started by - <command>systemd</command>, those may be set using - <varname>LimitCore=</varname> (see - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + <para>Core dumps can be written to the journal or saved as a file. Once saved they can be retrieved + for further processing, for example in + <citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>. </para> - <para><command>systemd-coredump</command> will log the coredump - including a backtrace if possible, and store the core (contents of - process' memory contents) in an external file on disk in - <filename>/var/lib/systemd/coredump</filename>, or directly in - the journal. This behavior may be modified using - <citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + <para>By default, <command>systemd-coredump</command> will log the core dump including a backtrace + if possible to the journal and store the core dump itself in an external file in + <filename>/var/lib/systemd/coredump</filename>.</para> + + <para>When the kernel invokes <command>systemd-coredump</command> to handle a core dump, + it will connect to the socket created by the <filename>systemd-coredump.socket</filename> + unit, which in turn will spawn a <filename>systemd-coredump@.service</filename> instance + to process the core dump. Hence <filename>systemd-coredump.socket</filename> + and <filename>systemd-coredump@.service</filename> are helper units which do the actual + processing of core dumps and are subject to normal service management.</para> + + <para>The behavior of a specific program upon reception of a signal is governed by a few + factors which are described in detail in + <citerefentry project='man-pages'><refentrytitle>core</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + In particular, the core dump will only be processed when the related resource limits are sufficient. + </para> + </refsect1> + + <refsect1> + <title>Configuration</title> + <para>For programs started by <command>systemd</command> process resource limits can be set by directive + <varname>LimitCore=</varname>, see + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para> - <para>Apart from the + <para>In order to be used <command>systemd-coredump</command> must be configured in + <citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> + parameter <varname>kernel.core_pattern</varname>. The syntax of this parameter is explained in + <citerefentry project='man-pages'><refentrytitle>core</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + Systemd installs the file <filename>/usr/lib/sysctl.d/50-coredump.conf</filename> which configures + <varname>kernel.core_pattern</varname> accordingly. This file may be masked or overridden to use a different + setting following normal + <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> + rules. + If the sysctl configuration is modified, it must be updated in the kernel before + it takes effect, see + <citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd-sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + </para> + + <para>The behaviour of <command>systemd-coredump</command> itself is configured through the configuration file + <filename>/etc/systemd/coredump.conf</filename> and corresponding snippets + <filename>/etc/systemd/coredump.conf.d/*.conf</filename>, see + <citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. A new + instance of <command>systemd-coredump</command> is invoked upon receiving every core dump. Therefore, changes + in these files will take effect the next time a core dump is received.</para> + + <para>Resources used by core dump files are restricted in two ways. Parameters like maximum size of acquired + core dumps and files can be set in files <filename>/etc/systemd/coredump.conf</filename> and snippets mentioned + above. In addition the storage time of core dump files is restricted by <command>systemd-tmpfiles</command>, + corresponding settings are by default in <filename>/usr/lib/tmpfiles.d/systemd.conf</filename>.</para> + </refsect1> + + <refsect1> + <title>Usage</title> + <para>Data stored in the journal can be viewed with <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - log viewer, + as usual. <citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - may be used to list and extract coredumps.</para> + can be used to retrieve saved core dumps independent of their location, to display information and to process + them e.g. by passing to the GNU debugger (gdb).</para> </refsect1> <refsect1> @@ -97,6 +136,7 @@ <citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>core</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-sysctl.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. diff --git a/man/systemd-importd.service.xml b/man/systemd-importd.service.xml new file mode 100644 index 0000000000..8fdced475c --- /dev/null +++ b/man/systemd-importd.service.xml @@ -0,0 +1,82 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2016 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-importd.service" conditional='ENABLE_IMPORTD'> + + <refentryinfo> + <title>systemd-importd.service</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-importd.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-importd.service</refname> + <refname>systemd-importd</refname> + <refpurpose>VM and container image import and export service</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-importd.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-importd</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-importd</command> is a system service that allows importing, exporting and downloading of + system images suitable for running as VM or containers. It is a companion service for + <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, and provides the implementation for + <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s + <command>pull-raw</command>, <command>pull-tar</command>, <command>import-raw</command>, + <command>import-tar</command>, <command>export-raw</command>, and <command>export-tar</command> commands.</para> + + <para>See the + <ulink url="http://www.freedesktop.org/wiki/Software/systemd/importd"> + importd D-Bus API Documentation</ulink> for information about the + APIs <filename>systemd-importd</filename> provides.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-journal-gatewayd.service.xml b/man/systemd-journal-gatewayd.service.xml index e32ac26850..9ed85c3950 100644 --- a/man/systemd-journal-gatewayd.service.xml +++ b/man/systemd-journal-gatewayd.service.xml @@ -262,7 +262,7 @@ <term><uri>boot</uri></term> <listitem><para>Limit events to the current boot of the system - (like <command>journalctl --this--boot</command>).</para></listitem> + (like <command>journalctl --this-boot</command>).</para></listitem> </varlistentry> <varlistentry> diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml index bd7392c2a2..476cc2932f 100644 --- a/man/systemd-nspawn.xml +++ b/man/systemd-nspawn.xml @@ -58,7 +58,7 @@ </cmdsynopsis> <cmdsynopsis> <command>systemd-nspawn</command> - <arg choice="plain">-b</arg> + <arg choice="plain">--boot</arg> <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt" rep="repeat">ARGS</arg> </cmdsynopsis> @@ -263,7 +263,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 + correctly as PID 1. This option may not be combined with <option>--boot</option> or <option>--share-system</option>.</para> </listitem> </varlistentry> @@ -294,12 +294,12 @@ <tbody> <row> <entry>Neither <option>--as-pid2</option> nor <option>--boot</option> specified</entry> - <entry>The passed parameters are interpreted as command line, which is executed as PID 1 in the container.</entry> + <entry>The passed parameters are interpreted as the command line, which is executed as PID 1 in the container.</entry> </row> <row> <entry><option>--as-pid2</option> specified</entry> - <entry>The passed parameters are interpreted as command line, which are executed as PID 2 in the container. A stub init process is run as PID 1.</entry> + <entry>The passed parameters are interpreted as the command line, which is executed as PID 2 in the container. A stub init process is run as PID 1.</entry> </row> <row> @@ -355,7 +355,9 @@ <listitem><para>Set the specified UUID for the container. The init system will initialize <filename>/etc/machine-id</filename> from this if this file is - not set yet. </para></listitem> + not set yet. Note that this option takes effect only if + <filename>/etc/machine-id</filename> in the container is + unpopulated.</para></listitem> </varlistentry> <varlistentry> @@ -385,38 +387,79 @@ <varlistentry> <term><option>--private-users=</option></term> - <listitem><para>Enables user namespacing. If enabled, the - container will run with its own private set of Unix user and - group ids (UIDs and GIDs). Takes none, one or two - colon-separated parameters: the first parameter specifies the - first host UID to assign to the container, the second - parameter specifies the number of host UIDs to assign to the - container. If the second parameter is omitted, 65536 UIDs are - assigned. If the first parameter is also omitted (and hence - no parameter passed at all), the first UID assigned to the - container is read from the owner of the root directory of the - container's directory tree. By default, no user namespacing is - applied.</para> - - <para>Note that user namespacing currently requires OS trees - that are prepared for the UID shift that is being applied: - UIDs and GIDs used for file ownership or in file ACL entries - must be shifted to the container UID base that is - used during container runtime.</para> + <listitem><para>Controls user namespacing. If enabled, the container will run with its own private set of UNIX + user and group ids (UIDs and GIDs). This involves mapping the private UIDs/GIDs used in the container (starting + with the container's root user 0 and up) to a range of UIDs/GIDs on the host that are not used for other + purposes (usually in the range beyond the host's UID/GID 65536). The parameter may be specified as follows:</para> + + <orderedlist> + <listitem><para>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> + </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 + <option>--private-users=pick</option> option.</para> + + <para>When user namespaces are used, the GID range assigned to each container is always chosen identical to the + UID range.</para> + + <para>In most cases, using <option>--private-users=pick</option> is the recommended option as it enhances + container security massively and operates fully automatically in most cases.</para> + + <para>Note that the picked UID/GID range is not written to <filename>/etc/passwd</filename> or + <filename>/etc/group</filename>. In fact, the allocation of the range is not stored persistently anywhere, + except in the file ownership of the files and directories of the container.</para></listitem> + </varlistentry> - <para>It is recommended to assign at least 65536 UIDs to each - container, so that the usable UID range in the container - covers 16 bit. For best security, do not assign overlapping UID - ranges to multiple containers. It is hence a good idea to use - the upper 16 bit of the host 32-bit UIDs as container - identifier, while the lower 16 bit encode the container UID - used.</para> + <varlistentry> + <term><option>-U</option></term> - <para>When user namespaces are used, the GID range assigned to - each container is always chosen identical to the UID - range.</para></listitem> + <listitem><para>If the kernel supports the user namespaces feature, equivalent to + <option>--private-users=pick</option>, otherwise equivalent to + <option>--private-users=no</option>.</para></listitem> </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 + they are owned to the appropriate UIDs/GIDs selected for the container (see above). This operation is + potentially expensive, as it involves descending and iterating through the full directory tree of the + container. Besides actual file ownership, file ACLs are adjusted as well.</para> + + <para>This option is implied if <option>--private-users=pick</option> is used. This option has no effect if + user namespacing is not used.</para></listitem> + </varlistentry> <varlistentry> <term><option>--private-network</option></term> @@ -481,15 +524,23 @@ <term><option>-n</option></term> <term><option>--network-veth</option></term> - <listitem><para>Create a virtual Ethernet link - (<literal>veth</literal>) between host and container. The host - side of the Ethernet link will be available as a network - interface named after the container's name (as specified with - <option>--machine=</option>), prefixed with - <literal>ve-</literal>. The container side of the Ethernet - link will be named <literal>host0</literal>. Note that - <option>--network-veth</option> implies - <option>--private-network</option>.</para></listitem> + <listitem><para>Create a virtual Ethernet link (<literal>veth</literal>) between host and container. The host + side of the Ethernet link will be available as a network interface named after the container's name (as + specified with <option>--machine=</option>), prefixed with <literal>ve-</literal>. The container side of the + Ethernet link will be named <literal>host0</literal>. The <option>--network-veth</option> option implies + <option>--private-network</option>.</para> + + <para>Note that + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + includes by default a network file <filename>/usr/lib/systemd/network/80-container-ve.network</filename> + matching the host-side interfaces created this way, which contains settings to enable automatic address + provisioning on the created virtual link via DHCP, as well as automatic IP routing onto the host's external + network interfaces. It also contains <filename>/usr/lib/systemd/network/80-container-host0.network</filename> + matching the container-side interface created this way, containing settings to enable client side address + assignment via DHCP. In case <filename>systemd-networkd</filename> is running on both the host and inside the + container, automatic IP communication from the container to the host is thus available, with further + connectivity to the external network.</para> + </listitem> </varlistentry> <varlistentry> @@ -500,7 +551,7 @@ host interface name and container interface name. The latter may be omitted in which case the container and host sides will be assigned the same name. This switch is independent of - <option>--network-veth</option>, and -- in contrast -- may be + <option>--network-veth</option>, and — in contrast — may be used multiple times, and allows configuration of the network interface names. Note that <option>--network-bridge=</option> has no effect on interfaces created with @@ -510,16 +561,43 @@ <varlistentry> <term><option>--network-bridge=</option></term> - <listitem><para>Adds the host side of the Ethernet link - created with <option>--network-veth</option> to the specified - bridge. Note that <option>--network-bridge=</option> implies - <option>--network-veth</option>. If this option is used, the - host side of the Ethernet link will use the - <literal>vb-</literal> prefix instead of + <listitem><para>Adds the host side of the Ethernet link created with <option>--network-veth</option> to the + specified Ethernet bridge interface. Expects a valid network interface name of a bridge device as + argument. Note that <option>--network-bridge=</option> implies <option>--network-veth</option>. If this option + is used, the host side of the Ethernet link will use the <literal>vb-</literal> prefix instead of <literal>ve-</literal>.</para></listitem> </varlistentry> <varlistentry> + <term><option>--network-zone=</option></term> + + <listitem><para>Creates a virtual Ethernet link (<literal>veth</literal>) to the container and adds it to an + automatically managed Ethernet bridge interface. The bridge interface is named after the passed argument, + prefixed with <literal>vz-</literal>. The bridge interface is automatically created when the first container + configured for its name is started, and is automatically removed when the last container configured for its + name exits. Hence, each bridge interface configured this way exists only as long as there's at least one + container referencing it running. This option is very similar to <option>--network-bridge=</option>, besides + this automatic creation/removal of the bridge device.</para> + + <para>This setting makes it easy to place multiple related containers on a common, virtual Ethernet-based + broadcast domain, here called a "zone". Each container may only be part of one zone, but each zone may contain + any number of containers. Each zone is referenced by its name. Names may be chosen freely (as long as they form + valid network interface names when prefixed with <literal>vz-</literal>), and it is sufficient to pass the same + name to the <option>--network-zones=</option> switch of the various concurrently running containers to join + them in one zone.</para> + + <para>Note that + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + includes by default a network file <filename>/usr/lib/systemd/network/80-container-vz.network</filename> + matching the bridge interfaces created this way, which contains settings to enable automatic address + provisioning on the created virtual network via DHCP, as well as automatic IP routing onto the host's external + network interfaces. Using <option>--network-zone=</option> is hence in most cases fully automatic and + sufficient to connect multiple local containers in a joined broadcast domain to the host, with further + connectivity to the external network.</para> + </listitem> + </varlistentry> + + <varlistentry> <term><option>-p</option></term> <term><option>--port=</option></term> @@ -534,7 +612,7 @@ port number and its colon may be omitted, in which case the same port as the host port is implied. This option is only supported if private networking is used, such as with - <option>--network-veth</option> or + <option>--network-veth</option>, <option>--network-zone=</option> <option>--network-bridge=</option>.</para></listitem> </varlistentry> @@ -595,9 +673,8 @@ order to trigger an orderly shutdown of the container. Defaults to SIGRTMIN+3 if <option>--boot</option> is used (on systemd-compatible init systems SIGRTMIN+3 - triggers an orderly shutdown). Takes a signal name like - <literal>SIGHUP</literal>, <literal>SIGTERM</literal> or - similar as argument.</para></listitem> + triggers an orderly shutdown). For a list of valid signals, see + <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para></listitem> </varlistentry> <varlistentry> @@ -736,7 +813,8 @@ </varlistentry> <varlistentry> - <term><option>--setenv=</option></term> + <term><option>-E <replaceable>NAME</replaceable>=<replaceable>VALUE</replaceable></option></term> + <term><option>--setenv=<replaceable>NAME</replaceable>=<replaceable>VALUE</replaceable></option></term> <listitem><para>Specifies an environment variable assignment to pass to the init process in the container, in the format diff --git a/man/systemd-resolve.xml b/man/systemd-resolve.xml index f1e663c5bb..4b66f836a2 100644 --- a/man/systemd-resolve.xml +++ b/man/systemd-resolve.xml @@ -65,7 +65,7 @@ <command>systemd-resolve</command> <arg choice="opt" rep="repeat">OPTIONS</arg> <command> --type=<replaceable>TYPE</replaceable></command> - <arg choice="plain" rep="repeat"><replaceable>RRDOMAIN</replaceable></arg> + <arg choice="plain" rep="repeat"><replaceable>DOMAIN</replaceable></arg> </cmdsynopsis> <cmdsynopsis> @@ -79,6 +79,20 @@ <cmdsynopsis> <command>systemd-resolve</command> <arg choice="opt" rep="repeat">OPTIONS</arg> + <command> --openpgp</command> + <arg choice="plain"><replaceable>USER@DOMAIN</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis> + <command>systemd-resolve</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <command> --tlsa</command> + <arg choice="plain"><replaceable>DOMAIN<optional>:PORT</optional></replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis> + <command>systemd-resolve</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> <command> --statistics</command> </cmdsynopsis> @@ -114,8 +128,17 @@ is assumed to be a domain name, that is already prefixed with an SRV type, and an SRV lookup is done (no TXT).</para> + <para>The <option>--openpgp</option> switch may be used to query PGP keys stored as + <ulink url="https://tools.ietf.org/html/draft-wouters-dane-openpgp-02">OPENPGPKEY</ulink> resource records. + When this option is specified one or more e-mail address must be specified.</para> + + <para>The <option>--tlsa</option> switch maybe be used to query TLS public + keys stored as + <ulink url="https://tools.ietf.org/html/rfc6698">TLSA</ulink> resource records. + When this option is specified one or more domain names must be specified.</para> + <para>The <option>--statistics</option> switch may be used to show resolver statistics, including information about - the number of succesful and failed DNSSEC validations.</para> + the number of successful and failed DNSSEC validations.</para> <para>The <option>--reset-statistics</option> may be used to reset various statistics counters maintained the resolver, including those shown in the <option>--statistics</option> output. This operation requires root @@ -152,7 +175,7 @@ <listitem><para>Specifies the network protocol for the query. May be one of <literal>dns</literal> (i.e. classic unicast DNS), <literal>llmnr</literal> (<ulink url="https://tools.ietf.org/html/rfc4795">Link-Local Multicast Name Resolution</ulink>), - <literal>llmr-ipv4</literal>, <literal>llmnr-ipv6</literal> (LLMNR via the indicated underlying IP + <literal>llmnr-ipv4</literal>, <literal>llmnr-ipv6</literal> (LLMNR via the indicated underlying IP protocols). By default the lookup is done via all protocols suitable for the lookup. If used, limits the set of protocols that may be used. Use this option multiple times to enable resolving via multiple protocols at the same time. The setting <literal>llmnr</literal> is identical to specifying this switch once with @@ -198,6 +221,28 @@ </varlistentry> <varlistentry> + <term><option>--openpgp</option></term> + + <listitem><para>Enables OPENPGPKEY resource record resolution (see above). Specified e-mail + addresses are converted to the corresponding DNS domain name, and any OPENPGPKEY keys are + printed.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--tlsa</option></term> + + <listitem><para>Enables TLSA resource record resolution (see above). + A query will be performed for each of the specified names prefixed with + the port and family + (<literal>_<replaceable>port</replaceable>._<replaceable>family</replaceable>.<replaceable>domain</replaceable></literal>). + The port number may be specified after a colon + (<literal>:</literal>), otherwise <constant>443</constant> will be used + by default. The family may be specified as an argument after + <option>--tlsa</option>, otherwise <constant>tcp</constant> will be + used.</para></listitem> + </varlistentry> + + <varlistentry> <term><option>--cname=</option><replaceable>BOOL</replaceable></term> <listitem><para>Takes a boolean parameter. If true (the default), DNS CNAME or DNAME redirections are @@ -214,6 +259,16 @@ </varlistentry> <varlistentry> + <term><option>--raw</option><optional>=payload|packet</optional></term> + + <listitem><para>Dump the answer as binary data. If there is no argument or if the argument is + <literal>payload</literal>, the payload of the packet is exported. If the argument is + <literal>packet</literal>, the whole packet is dumped in wire format, prefixed by + length specified as a little-endian 64-bit number. This format allows multiple packets + to be dumped and unambigously parsed.</para></listitem> + </varlistentry> + + <varlistentry> <term><option>--legend=</option><replaceable>BOOL</replaceable></term> <listitem><para>Takes a boolean parameter. If true (the default), column headers and meta information about the @@ -244,27 +299,70 @@ <example> <title>Retrieve the addresses of the <literal>www.0pointer.net</literal> domain</title> - <programlisting>$ systemd-resolve www.0pointer.net</programlisting> + <programlisting>$ systemd-resolve www.0pointer.net +www.0pointer.net: 2a01:238:43ed:c300:10c3:bcf3:3266:da74 + 85.214.157.71 + +-- Information acquired via protocol DNS in 611.6ms. +-- Data is authenticated: no +</programlisting> </example> <example> <title>Retrieve the domain of the <literal>85.214.157.71</literal> IP address</title> - <programlisting>$ systemd-resolve 85.214.157.71</programlisting> + <programlisting>$ systemd-resolve 85.214.157.71 +85.214.157.71: gardel.0pointer.net + +-- Information acquired via protocol DNS in 1.2997s. +-- Data is authenticated: no +</programlisting> </example> <example> <title>Retrieve the MX record of the <literal>0pointer.net</literal> domain</title> - <programlisting>$ systemd-resolve -t MX 0pointer.net</programlisting> + <programlisting>$ systemd-resolve -t MX yahoo.com --legend=no +yahoo.com. IN MX 1 mta7.am0.yahoodns.net +yahoo.com. IN MX 1 mta6.am0.yahoodns.net +yahoo.com. IN MX 1 mta5.am0.yahoodns.net +</programlisting> </example> <example> <title>Resolve an SRV service</title> - <programlisting>$ systemd-resolve --service _xmpp-server._tcp gmail.com</programlisting> + <programlisting>$ systemd-resolve --service _xmpp-server._tcp gmail.com +_xmpp-server._tcp/gmail.com: alt1.xmpp-server.l.google.com:5269 [priority=20, weight=0] + 173.194.210.125 + alt4.xmpp-server.l.google.com:5269 [priority=20, weight=0] + 173.194.65.125 + ... +</programlisting> </example> + <example> + <title>Retrieve a PGP key</title> + + <programlisting>$ systemd-resolve --openpgp zbyszek@fedoraproject.org +d08ee310438ca124a6149ea5cc21b6313b390dce485576eff96f8722._openpgpkey.fedoraproject.org. IN OPENPGPKEY + mQINBFBHPMsBEACeInGYJCb+7TurKfb6wGyTottCDtiSJB310i37/6ZYoeIay/5soJjlMyf + MFQ9T2XNT/0LM6gTa0MpC1st9LnzYTMsT6tzRly1D1UbVI6xw0g0vE5y2Cjk3xUwAynCsSs + ... +</programlisting> + </example> + + <example> + <title>Retrieve a TLS key (<literal>=tcp</literal> and + <literal>:443</literal> could be skipped)</title> + + <programlisting>$ systemd-resolve --tlsa=tcp fedoraproject.org:443 +_443._tcp.fedoraproject.org IN TLSA 0 0 1 19400be5b7a31fb733917700789d2f0a2471c0c9d506c0e504c06c16d7cb17c0 + -- Cert. usage: CA constraint + -- Selector: Full Certificate + -- Matching type: SHA-256 +</programlisting> + </example> </refsect1> <refsect1> diff --git a/man/systemd-resolved.service.xml b/man/systemd-resolved.service.xml index 7a9e23a2c6..829729ca09 100644 --- a/man/systemd-resolved.service.xml +++ b/man/systemd-resolved.service.xml @@ -87,9 +87,10 @@ is on the local loopback) and the IPv6 address ::1 (which is the local host).</para></listitem> - <listitem><para>The hostname <literal>localhost</literal> (as well as any hostname ending in - <literal>.localhost</literal>, <literal>.localdomain</literal> or equal to <literal>localdomain</literal>) is - resolved to the IP addresses 127.0.0.1 and ::1.</para></listitem> + <listitem><para>The hostnames <literal>localhost</literal> and + <literal>localhost.localdomain</literal> (as well as any hostname + ending in <literal>.localhost</literal> or <literal>.localhost.localdomain</literal>) + are resolved to the IP addresses 127.0.0.1 and ::1.</para></listitem> <listitem><para>The hostname <literal>gateway</literal> is resolved to all current default routing gateway addresses, diff --git a/man/systemd-run.xml b/man/systemd-run.xml index 414e1c8335..9c1a29218e 100644 --- a/man/systemd-run.xml +++ b/man/systemd-run.xml @@ -226,11 +226,11 @@ </varlistentry> <varlistentry> - <term><option>--setenv=</option></term> + <term><option>-E <replaceable>NAME</replaceable>=<replaceable>VALUE</replaceable></option></term> + <term><option>--setenv=<replaceable>NAME</replaceable>=<replaceable>VALUE</replaceable></option></term> - <listitem><para>Runs the service process with the specified - environment variables set. Also see - <varname>Environment=</varname> in + <listitem><para>Runs the service process with the specified environment variable set. + Also see <varname>Environment=</varname> in <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> </listitem> </varlistentry> @@ -341,33 +341,41 @@ <refsect1> <title>Examples</title> - <para>The following command will log the environment variables - provided by systemd to services:</para> + <example> + <title>Logging environment variables provided by systemd to services</title> - <programlisting># systemd-run env -Running as unit run-19945.service. + <programlisting># systemd-run env +Running as unit: run-19945.service # journalctl -u run-19945.service Sep 08 07:37:21 bupkis systemd[1]: Starting /usr/bin/env... Sep 08 07:37:21 bupkis systemd[1]: Started /usr/bin/env. Sep 08 07:37:21 bupkis env[19948]: PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin Sep 08 07:37:21 bupkis env[19948]: LANG=en_US.UTF-8 Sep 08 07:37:21 bupkis env[19948]: BOOT_IMAGE=/vmlinuz-3.11.0-0.rc5.git6.2.fc20.x86_64</programlisting> + </example> + + <example> + <title>Limiting resources available to a command</title> + + <programlisting># systemd-run -p BlockIOWeight=10 updatedb</programlisting> - <para>The following command invokes the - <citerefentry project='man-pages'><refentrytitle>updatedb</refentrytitle><manvolnum>8</manvolnum></citerefentry> - tool, but lowers the block I/O weight for it to 10. See - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more information on the <varname>BlockIOWeight=</varname> - property.</para> + <para>This command invokes the + <citerefentry project='man-pages'><refentrytitle>updatedb</refentrytitle><manvolnum>8</manvolnum></citerefentry> + tool, but lowers the block I/O weight for it to 10. See + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information on the <varname>BlockIOWeight=</varname> + property.</para> + </example> - <programlisting># systemd-run -p BlockIOWeight=10 updatedb</programlisting> + <example> + <title>Running commands at a specified time</title> - <para>The following command will touch a file after 30 seconds.</para> + <para>The following command will touch a file after 30 seconds.</para> - <programlisting># date; systemd-run --on-active=30 --timer-property=AccuracySec=100ms /bin/touch /tmp/foo + <programlisting># date; systemd-run --on-active=30 --timer-property=AccuracySec=100ms /bin/touch /tmp/foo Mon Dec 8 20:44:24 KST 2014 -Running as unit run-71.timer. -Will run as unit run-71.service. +Running as unit: run-71.timer +Will run service as unit: run-71.service # journalctl -b -u run-71.timer -- Logs begin at Fri 2014-12-05 19:09:21 KST, end at Mon 2014-12-08 20:44:54 KST. -- Dec 08 20:44:38 container systemd[1]: Starting /bin/touch /tmp/foo. @@ -376,13 +384,60 @@ Dec 08 20:44:38 container systemd[1]: Started /bin/touch /tmp/foo. -- Logs begin at Fri 2014-12-05 19:09:21 KST, end at Mon 2014-12-08 20:44:54 KST. -- Dec 08 20:44:48 container systemd[1]: Starting /bin/touch /tmp/foo... Dec 08 20:44:48 container systemd[1]: Started /bin/touch /tmp/foo.</programlisting> - - <para>The following command invokes <filename>/bin/bash</filename> - as a service passing its standard input, output and error to - the calling TTY.</para> - - <programlisting># systemd-run -t --send-sighup /bin/bash</programlisting> - + </example> + + <example> + <title>Allowing access to the tty</title> + + <para>The following command invokes <filename>/bin/bash</filename> as a service + passing its standard input, output and error to the calling TTY.</para> + + <programlisting># systemd-run -t --send-sighup /bin/bash</programlisting> + </example> + + <example> + <title>Start <command>screen</command> as a user service</title> + + <programlisting>$ systemd-run --scope --user screen +Running scope as unit run-r14b0047ab6df45bfb45e7786cc839e76.scope. + +$ screen -ls +There is a screen on: + 492..laptop (Detached) +1 Socket in /var/run/screen/S-fatima. +</programlisting> + + <para>This starts the <command>screen</command> process as a child of the + <command>systemd --user</command> process that was started by + <filename>user@.service</filename>, in a scope unit. A + <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry> + unit is used instead of a + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + unit, because <command>screen</command> will exit when detaching from the terminal, + and a service unit would be terminated. Running <command>screen</command> + as a user unit has the advantage that it is not part of the session scope. + If <varname>KillUserProcesses=yes</varname> is configured in + <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + the default, the session scope will be terminated when the user logs + out of that session.</para> + + <para>The <filename>user@.service</filename> is started automatically + when the user first logs in, and stays around as long as at least one + login session is open. After the user logs out of the last session, + <filename>user@.service</filename> and all services underneath it + are terminated. This behaviour is the default, when "lingering" is + not enabled for that user. Enabling lingering means that + <filename>user@.service</filename> is started automatically during + boot, even if the user is not logged in, and that the service is + not terminated when the user logs out.</para> + + <para>Enabling lingering allows the user to run processes without being logged in, + for example to allow <command>screen</command> to persist after the user logs out, + even if the session scope is terminated. In the default configuration, users can + enable lingering for themselves:</para> + + <programlisting>$ loginctl enable-linger</programlisting> + </example> </refsect1> <refsect1> diff --git a/man/systemd-activate.xml b/man/systemd-socket-activate.xml index 995e6eecce..5d7f157c72 100644 --- a/man/systemd-activate.xml +++ b/man/systemd-socket-activate.xml @@ -21,11 +21,11 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>. --> -<refentry id="systemd-activate" +<refentry id="systemd-socket-activate" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> - <title>systemd-activate</title> + <title>systemd-socket-activate</title> <productname>systemd</productname> <authorgroup> @@ -39,18 +39,18 @@ </refentryinfo> <refmeta> - <refentrytitle>systemd-activate</refentrytitle> - <manvolnum>8</manvolnum> + <refentrytitle>systemd-socket-activate</refentrytitle> + <manvolnum>1</manvolnum> </refmeta> <refnamediv> - <refname>systemd-activate</refname> + <refname>systemd-socket-activate</refname> <refpurpose>Test socket activation of daemons</refpurpose> </refnamediv> <refsynopsisdiv> <cmdsynopsis> - <command>/usr/lib/systemd/systemd-activate</command> + <command>systemd-socket-activate</command> <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="plain"><replaceable>daemon</replaceable></arg> <arg choice="opt" rep="repeat">OPTIONS</arg> @@ -60,20 +60,20 @@ <refsect1> <title>Description</title> - <para><command>systemd-activate</command> may be used to launch a socket-activated service binary from the command + <para><command>systemd-socket-activate</command> may be used to launch a socket-activated service binary from the command line for testing purposes. It may also be used to launch individual instances of the service binary per connection. </para> <para>The daemon to launch and its options should be specified - after options intended for <command>systemd-activate</command>. + after options intended for <command>systemd-socket-activate</command>. </para> <para>If the <option>--inetd</option> option is given, the socket file descriptor will be used as the standard input and output of the launched process. Otherwise, standard input and output will be inherited, and sockets will be passed through file descriptors 3 and higher. Sockets passed through <varname>$LISTEN_FDS</varname> to - <command>systemd-activate</command> will be passed through to the daemon, in the original positions. Other sockets + <command>systemd-socket-activate</command> will be passed through to the daemon, in the original positions. Other sockets specified with <option>--listen=</option> will use consecutive descriptors. By default, - <command>systemd-activate</command> listens on a stream socket, use <option>--datagram</option> and + <command>systemd-socket-activate</command> listens on a stream socket, use <option>--datagram</option> and <option>--seqpacket</option> to listen on datagram or sequential packet sockets instead (see below). </para> </refsect1> @@ -131,18 +131,20 @@ launched process. If <replaceable>VAR</replaceable> is followed by <literal>=</literal>, assume that it is a variable–value pair. Otherwise, obtain the value from the - environment of <command>systemd-activate</command> itself. + environment of <command>systemd-socket-activate</command> itself. </para></listitem> </varlistentry> <varlistentry> - <term><option>--fdname=</option><replaceable>NAME</replaceable></term> - - <listitem><para>Specify a name for the activation file - descriptors. This is equivalent to setting - <varname>FileDescriptorName=</varname> in socket unit files, and - enables use of - <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> + <term><option>--fdname=</option><replaceable>NAME</replaceable><optional>:<replaceable>NAME</replaceable>...</optional></term> + + <listitem><para>Specify names for the file descriptors passed. This is equivalent to setting + <varname>FileDescriptorName=</varname> in socket unit files, and enables use of + <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + Multiple entries may be specifies using separate options or by separating names with colons + (<literal>:</literal>) in one option. In case more names are given than descriptors, superflous ones willl be + ignored. In case less names are given than descriptors, the remaining file descriptors will be unnamed. + </para></listitem> </varlistentry> <xi:include href="standard-options.xml" xpointer="help" /> @@ -180,13 +182,13 @@ <example> <title>Run an echo server on port 2000</title> - <programlisting>$ /usr/lib/systemd/systemd-activate -l 2000 --inetd -a cat</programlisting> + <programlisting>$ systemd-socket-activate -l 2000 --inetd -a cat</programlisting> </example> <example> <title>Run a socket-activated instance of <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry></title> - <programlisting>$ /usr/lib/systemd/systemd-activate -l 19531 /usr/lib/systemd/systemd-journal-gatewayd</programlisting> + <programlisting>$ systemd-socket-activate -l 19531 /usr/lib/systemd/systemd-journal-gatewayd</programlisting> </example> </refsect1> diff --git a/man/systemd-sysctl.service.xml b/man/systemd-sysctl.service.xml index 9027ff0f3f..686b2cdef4 100644 --- a/man/systemd-sysctl.service.xml +++ b/man/systemd-sysctl.service.xml @@ -62,24 +62,29 @@ <para><filename>systemd-sysctl.service</filename> is an early boot service that configures <citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> - kernel parameters.</para> + kernel parameters by invoking <command>/usr/lib/systemd/systemd-sysctl</command>.</para> - <para>If invoked with no arguments, it applies all directives from - all configuration files in - <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> - are searched for a matching file. If one or more filenames are passed on - the command line, only the directives in these files are applied. - </para> + <para>When invoked with no arguments, <command>/usr/lib/systemd/systemd-sysctl</command> applies + all directives from configuration files listed in + <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + If one or more filenames are passed on the command line, only the directives in these files are + applied.</para> + + <para>In addition, <option>--prefix=</option> option may be used to limit which sysctl + settings are applied.</para> <para>See <citerefentry project='man-pages'><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for information about the configuration of this service.</para> + for information about the configuration of sysctl settings. After sysctl configuration is + changed on disk, it must be written to the files in <filename>/proc/sys</filename> before it + takes effect. It is possible to update specific settings, or simply to reload all configuration, + see Examples below.</para> </refsect1> <refsect1><title>Options</title> <variablelist> - <varlistentry id='path'> - <term><option>--path=</option></term> + <varlistentry id='prefix'> + <term><option>--prefix=</option></term> <listitem> <para>Only apply rules with the specified prefix.</para> </listitem> @@ -92,6 +97,50 @@ </refsect1> <refsect1> + <title>Examples</title> + + <example> + <title>Reset all sysctl settings</title> + + <programlisting>systemctl restart systemd-sysctl</programlisting> + </example> + + <example> + <title>View coredump handler configuration</title> + + <programlisting># sysctl kernel.core_pattern +kernel.core_pattern = |/usr/libexec/abrt-hook-ccpp %s %c %p %u %g %t %P %I +</programlisting> + </example> + + <example> + <title>Update coredump handler configuration</title> + + <programlisting># /usr/lib/systemd/systemd-sysctl --prefix kernel.core_pattern</programlisting> + + <para>This searches all the directories listed in + <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for configuration files and writes <filename>/proc/sys/kernel/core_pattern</filename>.</para> + </example> + + <example> + <title>Update coredump handler configuration according to a specific file</title> + + <programlisting># /usr/lib/systemd/systemd-sysctl 50-coredump.conf</programlisting> + + <para>This applies all the settings found in <filename>50-coredump.conf</filename>. + Either <filename>/etc/sysctl.d/50-coredump.conf</filename>, or + <filename>/run/sysctl.d/50-coredump.conf</filename>, or + <filename>/usr/lib/sysctl.d/50-coredump.conf</filename> will be used, in the order + of preference.</para> + </example> + + <para>See + <citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for various ways to directly apply sysctl settings.</para> + </refsect1> + + <refsect1> <title>See Also</title> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, diff --git a/man/systemd-system.conf.xml b/man/systemd-system.conf.xml index edc6df914a..8833e73c72 100644 --- a/man/systemd-system.conf.xml +++ b/man/systemd-system.conf.xml @@ -271,16 +271,16 @@ </varlistentry> <varlistentry> - <term><varname>DefaultStartLimitInterval=</varname></term> + <term><varname>DefaultStartLimitIntervalSec=</varname></term> <term><varname>DefaultStartLimitBurst=</varname></term> <listitem><para>Configure the default unit start rate limiting, as configured per-service by - <varname>StartLimitInterval=</varname> and + <varname>StartLimitIntervalSec=</varname> and <varname>StartLimitBurst=</varname>. See <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details on the per-service settings. - <varname>DefaultStartLimitInterval=</varname> defaults to + <varname>DefaultStartLimitIntervalSec=</varname> defaults to 10s. <varname>DefaultStartLimitBurst=</varname> defaults to 5.</para></listitem> </varlistentry> diff --git a/man/systemd-sysv-generator.xml b/man/systemd-sysv-generator.xml index bb5cc55e9f..2353eb3efe 100644 --- a/man/systemd-sysv-generator.xml +++ b/man/systemd-sysv-generator.xml @@ -77,7 +77,7 @@ which correspond to runlevels for which the script is enabled.</para> - <para><command>systemd</command> does not supports SysV scripts as + <para><command>systemd</command> does not support SysV scripts as part of early boot, so all wrapper units are ordered after <filename>basic.target</filename>.</para> diff --git a/man/systemd-tmpfiles.xml b/man/systemd-tmpfiles.xml index 447a7eaa17..c1aab51551 100644 --- a/man/systemd-tmpfiles.xml +++ b/man/systemd-tmpfiles.xml @@ -75,11 +75,11 @@ <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>. </para> - <para>If invoked with no arguments, it applies all directives from - all configuration files. If one or more absolute filenames are passed on - the command line, only the directives in these files are applied. - If only the basename of a configuration file is specified, all - configuration directories as specified in + <para>If invoked with no arguments, it applies all directives from all configuration + files. If one or more absolute filenames are passed on the command line, only the + directives in these files are applied. If <literal>-</literal> is specified instead + of a filename, directives are read from standard input. If only the basename of a + configuration file is specified, all configuration directories as specified in <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> are searched for a matching file.</para> </refsect1> diff --git a/man/systemd.automount.xml b/man/systemd.automount.xml index 1b0ae832da..a43dc981bd 100644 --- a/man/systemd.automount.xml +++ b/man/systemd.automount.xml @@ -66,14 +66,13 @@ [Install] sections. The automount specific configuration options are configured in the [Automount] section.</para> - <para>Automount units must be named after the automount - directories they control. Example: the automount point - <filename noindex='true'>/home/lennart</filename> must be - configured in a unit file - <filename>home-lennart.automount</filename>. For details about the - escaping logic used to convert a file system path to a unit name - see - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + <para>Automount units must be named after the automount directories they control. Example: the automount point + <filename noindex='true'>/home/lennart</filename> must be configured in a unit file + <filename>home-lennart.automount</filename>. For details about the escaping logic used to convert a file system + path to a unit name see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Note that + automount units cannot be templated, nor is it possible to add multiple names to an automount unit by creating + additional symlinks to its unit file.</para> <para>For each automount unit file a matching mount unit file (see <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry> @@ -97,11 +96,9 @@ <para>An implicit <varname>Before=</varname> dependency is created between an automount unit and the mount unit it activates.</para> - <para>Automount units acquire automatic <varname>Before=</varname> - and <varname>Conflicts=</varname> on - <filename>umount.target</filename> in order to be stopped during - shutdown, unless <varname>DefaultDependencies=no</varname> is - set.</para> + <para>Automount units acquire automatic <varname>Before=</varname> and <varname>Conflicts=</varname> on + <filename>umount.target</filename> in order to be stopped during shutdown, unless + <varname>DefaultDependencies=no</varname> is set in the <literal>[Unit]</literal> section.</para> </refsect1> diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index f0f77c5091..3cf6de8256 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -94,11 +94,9 @@ required to access <filename>/tmp</filename> and <filename>/var/tmp</filename>.</para> - <para>Units whose output standard output or error output is - connected to any other sink but <option>null</option>, - <option>tty</option> and <option>socket</option> automatically - acquire dependencies of type <varname>After=</varname> on - <filename>journald.socket</filename>.</para> + <para>Units whose standard output or error output is connected to <option>journal</option>, <option>syslog</option> + or <option>kmsg</option> (or their combinations with console output, see below) automatically acquire dependencies + of type <varname>After=</varname> on <filename>systemd-journald.socket</filename>.</para> </refsect1> <refsect1> @@ -470,6 +468,10 @@ similar to the same option of <varname>StandardInput=</varname>.</para> + <para>If the standard output (or error output, see below) of a unit is connected to the journal, syslog or the + kernel log buffer, the unit will implicitly gain a dependency of type <varname>After=</varname> on + <filename>systemd-journald.socket</filename> (also see the automatic dependencies section above).</para> + <para>This setting defaults to the value set with <option>DefaultStandardOutput=</option> in <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, @@ -627,27 +629,23 @@ <term><varname>LimitNICE=</varname></term> <term><varname>LimitRTPRIO=</varname></term> <term><varname>LimitRTTIME=</varname></term> - <listitem><para>These settings set both soft and hard limits - of various resources for executed processes. See - <citerefentry><refentrytitle>setrlimit</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details. The resource limit is possible to specify in two formats, - <option>value</option> to set soft and hard limits to the same value, - or <option>soft:hard</option> to set both limits individually (e.g. LimitAS=4G:16G). - Use the string <varname>infinity</varname> to - configure no limit on a specific resource. The multiplicative - suffixes K (=1024), M (=1024*1024) and so on for G, T, P and E - may be used for resource limits measured in bytes - (e.g. LimitAS=16G). For the limits referring to time values, - the usual time units ms, s, min, h and so on may be used (see - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details). Note that if no time unit is specified for - <varname>LimitCPU=</varname> the default unit of seconds is - implied, while for <varname>LimitRTTIME=</varname> the default - unit of microseconds is implied. Also, note that the effective - granularity of the limits might influence their - enforcement. For example, time limits specified for - <varname>LimitCPU=</varname> will be rounded up implicitly to - multiples of 1s.</para> + <listitem><para>Set soft and hard limits on various resources for executed processes. See + <citerefentry><refentrytitle>setrlimit</refentrytitle><manvolnum>2</manvolnum></citerefentry> for details on + the resource limit concept. Resource limits may be specified in two formats: either as single value to set a + specific soft and hard limit to the same value, or as colon-separated pair <option>soft:hard</option> to set + both limits individually (e.g. <literal>LimitAS=4G:16G</literal>). Use the string <varname>infinity</varname> + to configure no limit on a specific resource. The multiplicative suffixes K, M, G, T, P and E (to the base + 1024) may be used for resource limits measured in bytes (e.g. LimitAS=16G). For the limits referring to time + values, the usual time units ms, s, min, h and so on may be used (see + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for + details). Note that if no time unit is specified for <varname>LimitCPU=</varname> the default unit of seconds + is implied, while for <varname>LimitRTTIME=</varname> the default unit of microseconds is implied. Also, note + that the effective granularity of the limits might influence their enforcement. For example, time limits + specified for <varname>LimitCPU=</varname> will be rounded up implicitly to multiples of 1s. For + <varname>LimitNICE=</varname> the value may be specified in two syntaxes: if prefixed with <literal>+</literal> + or <literal>-</literal>, the value is understood as regular Linux nice value in the range -20..19. If not + prefixed like this the value is understood as raw resource limit parameter in the range 0..40 (with 0 being + equivalent to 1).</para> <para>Note that most process resource limits configured with these options are per-process, and processes may fork in order @@ -778,32 +776,21 @@ <varlistentry> <term><varname>CapabilityBoundingSet=</varname></term> - <listitem><para>Controls which capabilities to include in the - capability bounding set for the executed process. See - <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details. Takes a whitespace-separated list of capability - names as read by - <citerefentry project='mankier'><refentrytitle>cap_from_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - e.g. <constant>CAP_SYS_ADMIN</constant>, - <constant>CAP_DAC_OVERRIDE</constant>, - <constant>CAP_SYS_PTRACE</constant>. Capabilities listed will - be included in the bounding set, all others are removed. If - the list of capabilities is prefixed with - <literal>~</literal>, all but the listed capabilities will be - included, the effect of the assignment inverted. Note that - this option also affects the respective capabilities in the - effective, permitted and inheritable capability sets, on top - of what <varname>Capabilities=</varname> does. If this option - is not used, the capability bounding set is not modified on - process execution, hence no limits on the capabilities of the - process are enforced. This option may appear more than once, in - which case the bounding sets are merged. If the empty string - is assigned to this option, the bounding set is reset to the - empty capability set, and all prior settings have no effect. - If set to <literal>~</literal> (without any further argument), - the bounding set is reset to the full set of available - capabilities, also undoing any previous - settings.</para></listitem> + <listitem><para>Controls which capabilities to include in the capability bounding set for the executed + process. See <citerefentry + project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> for + details. Takes a whitespace-separated list of capability names 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.</para></listitem> </varlistentry> <varlistentry> @@ -854,20 +841,6 @@ </varlistentry> <varlistentry> - <term><varname>Capabilities=</varname></term> - <listitem><para>Controls the - <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> - set for the executed process. Take a capability string - describing the effective, permitted and inherited capability - sets as documented in - <citerefentry project='mankier'><refentrytitle>cap_from_text</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - Note that these capability sets are usually influenced (and - filtered) by the capabilities attached to the executed file. - Due to that <varname>CapabilityBoundingSet=</varname> is - probably a much more useful setting.</para></listitem> - </varlistentry> - - <varlistentry> <term><varname>ReadWriteDirectories=</varname></term> <term><varname>ReadOnlyDirectories=</varname></term> <term><varname>InaccessibleDirectories=</varname></term> @@ -884,9 +857,12 @@ reading only, writing will be refused even if the usual file access controls would permit this. Directories listed in <varname>InaccessibleDirectories=</varname> will be made - inaccessible for processes inside the namespace. Note that - restricting access with these options does not extend to - submounts of a directory that are created later on. These + inaccessible for processes inside the namespace, and may not + countain any other mountpoints, including those specified by + <varname>ReadWriteDirectories=</varname> or + <varname>ReadOnlyDirectories=</varname>. + Note that restricting access with these options does not extend + to submounts of a directory that are created later on. These options may be specified more than once, in which case all directories listed will have limited access from within the namespace. If the empty string is assigned to this option, the @@ -957,7 +933,10 @@ (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> + 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> </varlistentry> <varlistentry> @@ -1180,7 +1159,9 @@ first character of the list is <literal>~</literal>, the effect is inverted: only the listed system calls will result in immediate process termination (blacklisting). If running in - user mode and this option is used, + user mode, or in system mode, but without the + <constant>CAP_SYS_ADMIN</constant> capabiblity (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 @@ -1239,8 +1220,10 @@ systems. The special <constant>native</constant> identifier implicitly maps to the native architecture of the system (or more strictly: to the architecture the system manager is - compiled for). If running in user mode and this option is - used, <varname>NoNewPrivileges=yes</varname> is implied. Note + compiled for). If running in user mode, or in system mode, + but without the <constant>CAP_SYS_ADMIN</constant> + capabiblity (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 @@ -1269,8 +1252,10 @@ <function>socketpair()</function> (which creates connected AF_UNIX sockets only) are unaffected. Note that this option has no effect on 32-bit x86 and is ignored (but works - correctly on x86-64). If running in user mode and this option - is used, <varname>NoNewPrivileges=yes</varname> is implied. By + correctly on x86-64). If running in user mode, or in system + mode, but without the <constant>CAP_SYS_ADMIN</constant> + capabiblity (e.g. setting <varname>User=nobody</varname>), + <varname>NoNewPrivileges=yes</varname> is implied. By default, no restriction applies, all address families are accessible to processes. If assigned the empty string, any previous list changes are undone.</para> @@ -1287,14 +1272,17 @@ <varlistentry> <term><varname>Personality=</varname></term> - <listitem><para>Controls which kernel architecture - <citerefentry project='man-pages'><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry> - shall report, when invoked by unit processes. Takes one of - <constant>x86</constant> and <constant>x86-64</constant>. This - is useful when running 32-bit services on a 64-bit host - system. If not specified, the personality is left unmodified - and thus reflects the personality of the host system's - kernel.</para></listitem> + <listitem><para>Controls which kernel architecture <citerefentry + project='man-pages'><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry> shall report, + when invoked by unit processes. Takes one of the architecture identifiers <constant>x86</constant>, + <constant>x86-64</constant>, <constant>ppc</constant>, <constant>ppc-le</constant>, <constant>ppc64</constant>, + <constant>ppc64-le</constant>, <constant>s390</constant> or <constant>s390x</constant>. Which personality + architectures are supported depends on the system architecture. Usually the 64bit versions of the various + system architectures support their immediate 32bit personality architecture counterpart, but no others. For + example, <constant>x86-64</constant> systems support the <constant>x86-64</constant> and + <constant>x86</constant> personalities but no others. The personality feature is useful when running 32-bit + services on a 64-bit host system. If not specified, the personality is left unmodified and thus reflects the + personality of the host system's kernel.</para></listitem> </varlistentry> <varlistentry> diff --git a/man/systemd.link.xml b/man/systemd.link.xml index a9f8a654c8..d5b4d1038d 100644 --- a/man/systemd.link.xml +++ b/man/systemd.link.xml @@ -82,6 +82,10 @@ shipped by the system, any user-supplied <filename>.link</filename> should hence have a lexically earlier name to be considered at all.</para> + + <para>See + <citerefentry><refentrytitle>udevadm</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for diagnosing problems with <filename>.link</filename> files.</para> </refsect1> <refsect1> diff --git a/man/systemd.mount.xml b/man/systemd.mount.xml index 4a8d265fed..66cddd72e0 100644 --- a/man/systemd.mount.xml +++ b/man/systemd.mount.xml @@ -82,14 +82,12 @@ will refuse options that are not listed in <filename>/etc/fstab</filename> if it is not run as UID 0.</para> - <para>Mount units must be named after the mount point directories - they control. Example: the mount point - <filename noindex='true'>/home/lennart</filename> must be - configured in a unit file <filename>home-lennart.mount</filename>. - For details about the escaping logic used to convert a file system - path to a unit name, see - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - Note that mount units cannot be templated.</para> + <para>Mount units must be named after the mount point directories they control. Example: the mount point <filename + noindex='true'>/home/lennart</filename> must be configured in a unit file <filename>home-lennart.mount</filename>. + For details about the escaping logic used to convert a file system path to a unit name, see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Note that mount + units cannot be templated, nor is possible to add multiple names to a mount unit by creating additional symlinks to + it.</para> <para>Optionally, a mount unit may be accompanied by an automount unit, to allow on-demand or parallelized mounting. See @@ -128,26 +126,17 @@ <filename>systemd-quotacheck.service</filename> and <filename>quotaon.service</filename> are added.</para> - <para>For mount units with - <varname>DefaultDependencies=yes</varname> (the default) a couple - additional dependencies are added. Mount units referring to local - file systems automatically gain an <varname>After=</varname> - dependency on <filename>local-fs-pre.target</filename>. Network - mount units automatically acquire <varname>After=</varname> - dependencies on <filename>remote-fs-pre.target</filename>, - <filename>network.target</filename> and - <filename>network-online.target</filename>. Towards the latter a - <varname>Wants=</varname> unit is added as well. Mount units - referring to local and network file systems are distinguished by - their file system type specification. In some cases this is not - sufficient (for example network block device based mounts, such as - iSCSI), in which case <option>_netdev</option> may be added to the - mount option string of the unit, which forces systemd to consider the - mount unit a network mount. Mount units (regardless if local or - network) also acquire automatic <varname>Before=</varname> and - <varname>Conflicts=</varname> on - <filename>umount.target</filename> in order to be stopped - during shutdown.</para> + <para>For mount units with <varname>DefaultDependencies=yes</varname> in the <literal>[Unit]</literal> section (the + default) a couple additional dependencies are added. Mount units referring to local file systems automatically gain + an <varname>After=</varname> dependency on <filename>local-fs-pre.target</filename>. Network mount units + automatically acquire <varname>After=</varname> dependencies on <filename>remote-fs-pre.target</filename>, + <filename>network.target</filename> and <filename>network-online.target</filename>. Towards the latter a + <varname>Wants=</varname> unit is added as well. Mount units referring to local and network file systems are + distinguished by their file system type specification. In some cases this is not sufficient (for example network + block device based mounts, such as iSCSI), in which case <option>_netdev</option> may be added to the mount option + string of the unit, which forces systemd to consider the mount unit a network mount. Mount units (regardless if + local or network) also acquire automatic <varname>Before=</varname> and <varname>Conflicts=</varname> on + <filename>umount.target</filename> in order to be stopped during shutdown.</para> <para>Additional implicit dependencies may be added as result of execution and resource control parameters as documented in @@ -170,6 +159,11 @@ <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> for details about the conversion.</para> + <para>The NFS mount option <option>bg</option> for NFS background mounts + as documented in <citerefentry><refentrytitle>nfs</refentrytitle><manvolnum>5</manvolnum></citerefentry> + is not supported in <filename>/etc/fstab</filename> entries. The systemd mount option <option>nofail</option> + provides similar functionality and should be used instead.</para> + <para>When reading <filename>/etc/fstab</filename> a few special mount options are understood by systemd which influence how dependencies are created for mount points. systemd will create a diff --git a/man/systemd.netdev.xml b/man/systemd.netdev.xml index b697d0c9a6..8d12c305d2 100644 --- a/man/systemd.netdev.xml +++ b/man/systemd.netdev.xml @@ -310,6 +310,26 @@ of the Listening and Learning states before the Forwarding state is entered.</para> </listitem> </varlistentry> + <varlistentry> + <term><varname>MulticastQuerier=</varname></term> + <listitem> + <para>A boolean. This setting controls the IFLA_BR_MCAST_QUERIER option in the kernel. + If enabled, the kernel will send general ICMP queries from a zero source address. + This feature should allow faster convergence on startup, but it causes some + multicast-aware switches to misbehave and disrupt forwarding of multicast packets. + When unset, the kernel's default setting applies. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MulticastSnooping=</varname></term> + <listitem> + <para>A boolean. This setting controls the IFLA_BR_MCAST_SNOOPING option in the kernel. + If enabled, IGMP snooping monitors the Internet Group Management Protocol (IGMP) traffic + between hosts and multicast routers. When unset, the kernel's default setting applies. + </para> + </listitem> + </varlistentry> </variablelist> </refsect1> @@ -361,7 +381,7 @@ <para>The <literal>[MACVTAP]</literal> section applies for netdevs of kind <literal>macvtap</literal> and accepts the - same key as <literal>[MACVLAN].</literal> </para> + same key as <literal>[MACVLAN]</literal>.</para> </refsect1> diff --git a/man/systemd.network.xml b/man/systemd.network.xml index f88751b672..821e22aff8 100644 --- a/man/systemd.network.xml +++ b/man/systemd.network.xml @@ -79,6 +79,11 @@ 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> </refsect1> <refsect1> @@ -100,7 +105,8 @@ <varlistentry> <term><varname>MACAddress=</varname></term> <listitem> - <para>The hardware address.</para> + <para>The hardware address of the interface (use full colon-delimited hexadecimal, e.g., + 01:23:45:67:89:ab).</para> </listitem> </varlistentry> <varlistentry> @@ -193,7 +199,7 @@ <varlistentry> <term><varname>MACAddress=</varname></term> <listitem> - <para>The hardware address.</para> + <para>The hardware address to set for the device.</para> </listitem> </varlistentry> <varlistentry> @@ -202,6 +208,8 @@ <para>The maximum transmission unit in bytes to set for the device. The usual suffixes K, M, G, are supported and are understood to the base of 1024.</para> + <para>Note that if IPv6 is enabled on the interface, and the MTU is chosen + below 1280 (the minimum MTU for IPv6) it will automatically be increased to this value.</para> </listitem> </varlistentry> </variablelist> @@ -237,6 +245,9 @@ <para>Furthermore, note that by default the domain name specified through DHCP is not used for name resolution. See option <option>UseDomains=</option> below.</para> + + <para>See the <literal>[DHCP]</literal> section below for further configuration options for the DHCP client + support.</para> </listitem> </varlistentry> <varlistentry> @@ -270,8 +281,10 @@ <term><varname>IPv6Token=</varname></term> <listitem> <para>An IPv6 address with the top 64 bits unset. When set, indicates the - 64-bit interface part of SLAAC IPv6 addresses for this link. By default, - it is autogenerated.</para> + 64-bit interface part of SLAAC IPv6 addresses for this link. Note that + the token is only ever used for SLAAC, and not for DHCPv6 addresses, even + in the case DHCP is requested by router advertisement. By default, the + token is autogenerated.</para> </listitem> </varlistentry> <varlistentry> @@ -335,18 +348,50 @@ <varlistentry> <term><varname>LLDP=</varname></term> <listitem> - <para>A boolean. When true, enables LLDP link receive support. + <para>Controls support for Ethernet LLDP packet reception. LLDP is a link-layer protocol commonly + implemented on professional routers and bridges which announces which physical port a system is connected + to, as well as other related data. Accepts a boolean or the special value + <literal>routers-only</literal>. When true, incoming LLDP packets are accepted and a database of all LLDP + neighbors maintained. If <literal>routers-only</literal> is set only LLDP data of various types of routers + is collected and LLDP data about other types of devices ignored (such as stations, telephones and + others). If false, LLDP reception is disabled. Defaults to <literal>routers-only</literal>. Use + <citerefentry><refentrytitle>networkctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> to query the + collected neighbor data. LLDP is only available on Ethernet links. See <varname>EmitLLDP=</varname> below + for enabling LLDP packet emission from the local system. </para> </listitem> </varlistentry> <varlistentry> + <term><varname>EmitLLDP=</varname></term> + <listitem> + <para>Controls support for Ethernet LLDP packet emission. Accepts a boolean parameter or the special values + <literal>nearest-bridge</literal>, <literal>non-tpmr-bridge</literal> and + <literal>customer-bridge</literal>. Defaults to false, which turns off LLDP packet emission. If not false, + a short LLDP packet with information about the local system is sent out in regular intervals on the + link. The LLDP packet will contain information about the local host name, the local machine ID (as stored + in <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>) and the + local interface name, as well as the pretty hostname of the system (as set in + <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>). LLDP + emission is only available on Ethernet links. Note that this setting passes data suitable for + identification of host to the network and should thus not be enabled on untrusted networks, where such + identification data should not be made available. Use this option to permit other systems to identify on + which interfaces they are connected to this system. The three special values control propagation of the + LLDP packets. The <literal>nearest-bridge</literal> setting permits propagation only to the nearest + connected bridge, <literal>non-tpmr-bridge</literal> permits propagation across Two-Port MAC Relays, but + not any other bridges, and <literal>customer-bridge</literal> permits propagation until a customer bridge + is reached. For details about these concepts, see <ulink + url="http://standards.ieee.org/getieee802/download/802.1AB-2009.pdf">IEEE 802.1AB-2009</ulink>. Note that + configuring this setting to true is equivalent to <literal>nearest-bridge</literal>, the recommended and + most restricted level of propagation. See <varname>LLDP=</varname> above for an option to enable LLDP + reception.</para> + </listitem> + </varlistentry> + <varlistentry> <term><varname>BindCarrier=</varname></term> <listitem> - <para>A port or a list of ports. When set, controls the - behavior of the current interface. When all ports in the list - are in an operational down state, the current interface is brought - down. When at least one port has carrier, the current interface - is brought up. + <para>A link name or a list of link names. When set, controls the behavior of the current + link. When all links in the list are in an operational down state, the current link is brought + down. When at least one link has carrier, the current interface is brought up. </para> </listitem> </varlistentry> @@ -412,7 +457,7 @@ domains specified here are preferably routed to the DNS servers configured for this interface. If a domain name is prefixed with <literal>~</literal>, the domain name becomes a pure "routing" domain, is used for DNS query routing purposes only and is not used in the described domain search logic. By specifying a - routing domain of <literal>~.</literal> (the tilda indicating definition of a routing domain, the dot + routing domain of <literal>~.</literal> (the tilde indicating definition of a routing domain, the dot referring to the DNS root domain which is the implied suffix of all valid DNS names) it is possible to route all DNS traffic preferably to the DNS server specified for this interface. The route domain logic is particularly useful on multi-homed hosts with DNS servers serving particular private DNS zones on each @@ -517,6 +562,15 @@ </para></listitem> </varlistentry> <varlistentry> + <term><varname>ProxyARP=</varname></term> + <listitem><para>A boolean. Configures proxy ARP. Proxy ARP is the technique in which one host, + usually a router, answers ARP requests intended for another machine. By "faking" its identity, + the router accepts responsibility for routing packets to the "real" destination. (see <ulink + url="https://tools.ietf.org/html/rfc1027">RFC 1027</ulink>. + Defaults to unset. + </para></listitem> + </varlistentry> + <varlistentry> <term><varname>Bridge=</varname></term> <listitem> <para>The name of the bridge to add the link to.</para> @@ -600,6 +654,18 @@ <para>An address label.</para> </listitem> </varlistentry> + <varlistentry> + <term><varname>PreferredLifetime=</varname></term> + <listitem> + <para>Allows the default "preferred lifetime" of the address to be overridden. + Only three settings are accepted: <literal>forever</literal> or <literal>infinity</literal> + which is the default and means that the address never expires, and <literal>0</literal> which means + that the address is considered immediately "expired" and will not be used, + unless explicitly requested. A setting of PreferredLifetime=0 is useful for + addresses which are added to be used only by a specific application, + which is then configured to use them explicitly.</para> + </listitem> + </varlistentry> </variablelist> </refsect1> @@ -654,6 +720,14 @@ <citerefentry project='man-pages'><refentrytitle>inet_pton</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> </listitem> </varlistentry> + <varlistentry> + <term><varname>Table=<replaceable>num</replaceable></varname></term> + <listitem> + <para>The table identifier for the route (a number between 1 and 4294967295, or 0 to unset). + The table can be retrieved using <command>ip route show table <replaceable>num</replaceable></command>. + </para> + </listitem> + </varlistentry> </variablelist> </refsect1> @@ -717,7 +791,7 @@ <varlistentry> <term><varname>UseDomains=</varname></term> <listitem> - <para>Takes a boolean argument, or a the special value <literal>route</literal>. When true, the domain name + <para>Takes a boolean argument, or the special value <literal>route</literal>. When true, the domain name received from the DHCP server will be used as DNS search domain over this link, similar to the effect of the <option>Domains=</option> setting. If set to <literal>route</literal>, the domain name received from the DHCP server will be used for routing DNS queries only, but not for searching, similar to the effect of @@ -760,14 +834,15 @@ false.</para> </listitem> </varlistentry> + <varlistentry> <term><varname>ClientIdentifier=</varname></term> <listitem> - <para>DHCP client identifier to use. Either <literal>mac</literal> - to use the MAC address of the link or <literal>duid</literal> - (the default) to use a RFC4361-compliant Client ID.</para> + <para>The DHCPv4 client identifier to use. Either <literal>mac</literal> to use the MAC address of the link + or <literal>duid</literal> (the default, see below) to use a RFC4361-compliant Client ID.</para> </listitem> </varlistentry> + <varlistentry> <term><varname>VendorClassIdentifier=</varname></term> <listitem> @@ -775,6 +850,32 @@ type and configuration.</para> </listitem> </varlistentry> + + <varlistentry> + <term><varname>DUIDType=</varname></term> + <listitem> + <para>Override the global <varname>DUIDType</varname> setting for this network. See + <citerefentry><refentrytitle>networkd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for a description of possible values.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>DUIDRawData=</varname></term> + <listitem> + <para>Override the global <varname>DUIDRawData</varname> setting for this network. See + <citerefentry><refentrytitle>networkd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for a description of possible values.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>IAID=</varname></term> + <listitem> + <para>The DHCP Identity Association Identifier (IAID) for the interface, a 32-bit unsigned integer.</para> + </listitem> + </varlistentry> + <varlistentry> <term><varname>RequestBroadcast=</varname></term> <listitem> @@ -786,6 +887,7 @@ networks where broadcasts are filtered out.</para> </listitem> </varlistentry> + <varlistentry> <term><varname>RouteMetric=</varname></term> <listitem> @@ -794,8 +896,7 @@ </listitem> </varlistentry> </variablelist> - - </refsect1> + </refsect1> <refsect1> <title>[DHCPServer] Section Options</title> @@ -882,6 +983,16 @@ </varlistentry> <varlistentry> + <term><varname>EmitRouter=</varname></term> + + <listitem><para>Similar to the <varname>EmitDNS=</varname> + setting described above, this setting configures whether the + DHCP lease should contain the router option. The same syntax, + propagation semantics and defaults apply as for + <varname>EmitDNS=</varname>.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>EmitTimezone=</varname></term> <term><varname>Timezone=</varname></term> diff --git a/man/systemd.nspawn.xml b/man/systemd.nspawn.xml index c07a4b0243..3683412c14 100644 --- a/man/systemd.nspawn.xml +++ b/man/systemd.nspawn.xml @@ -224,6 +224,18 @@ </varlistentry> <varlistentry> + <term><varname>KillSignal=</varname></term> + + <listitem><para>Specify the process signal to send to the + container's PID 1 when nspawn itself receives SIGTERM, in + order to trigger an orderly shutdown of the container. + Defaults to SIGRTMIN+3 if <option>Boot=</option> is used + (on systemd-compatible init systems SIGRTMIN+3 triggers an + orderly shutdown). For a list of valid signals, see + <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>Personality=</varname></term> <listitem><para>Configures the kernel personality for the @@ -239,6 +251,14 @@ <option>--uuid=</option> command line switch. This option is privileged (see above). </para></listitem> </varlistentry> + + <varlistentry> + <term><varname>PrivateUsers=</varname></term> + + <listitem><para>Configures support for usernamespacing. This is equivalent to the + <option>--private-users=</option> command line switch, and takes the same options. This option is privileged + (see above). </para></listitem> + </varlistentry> </variablelist> </refsect1> @@ -302,6 +322,16 @@ for details about the specific options supported. This setting is privileged (see above).</para></listitem> </varlistentry> + + <varlistentry> + <term><varname>PrivateUsersChown=</varname></term> + + <listitem><para>Configures whether the ownership of the files and directories in the container tree shall be + adjusted to the UID/GID range used, if necessary and user namespacing is enabled. This is equivalent to the + <option>--private-users-chown</option> command line switch. This option is privileged (see + above). </para></listitem> + </varlistentry> + </variablelist> </refsect1> @@ -390,6 +420,16 @@ </varlistentry> <varlistentry> + <term><varname>Zone=</varname></term> + + <listitem><para>Takes a network zone name. This setting implies <varname>VirtualEthernet=yes</varname> and + <varname>Private=yes</varname> and has the effect that the host side of the created virtual Ethernet link is + connected to an automatically managed bridge interface named after the passed argument, prefixed with + <literal>vz-</literal>. This option corresponds to the <option>--network-zone=</option> command line + switch. This option is privileged (see above).</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>Port=</varname></term> <listitem><para>Exposes a TCP or UDP port of the container on diff --git a/man/systemd.offline-updates.xml b/man/systemd.offline-updates.xml new file mode 100644 index 0000000000..946234ad90 --- /dev/null +++ b/man/systemd.offline-updates.xml @@ -0,0 +1,169 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2013 Lennart Poettering + Copyright 2016 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.offline-updates"> + <refentryinfo> + <title>systemd.offline-updates</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.offline-updates</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.offline-updates</refname> + <refpurpose>Implementation of offline updates in systemd</refpurpose> + </refnamediv> + + <refsect1> + <title>Implementing Offline System Updates</title> + + <para>This man page describes how to implement "offline" system updates with systemd. By "offline" + OS updates we mean package installations and updates that are run with the system booted into a + special system update mode, in order to avoid problems related to conflicts of libraries and + services that are currently running with those on disk. This document is inspired by this + <ulink url="https://wiki.gnome.org/Design/OS/SoftwareUpdates">GNOME design whiteboard</ulink>. + </para> + + <para>The logic:</para> + + <orderedlist> + <listitem> + <para>The package manager prepares system updates by downloading all (RPM or DEB or + whatever) packages to update off-line in a special directory + <filename noindex="true">/var/lib/system-update</filename> (or + another directory of the package/upgrade manager's choice).</para> + </listitem> + + <listitem> + <para>When the user OK'ed the update, the symlink <filename>/system-update</filename> is + created that points to <filename noindex="true">/var/lib/system-update</filename> (or + wherever the directory with the upgrade files is located) and the system is rebooted. This + symlink is in the root directory, since we need to check for it very early at boot, at a + time where <filename>/var</filename> is not available yet.</para> + </listitem> + + <listitem> + <para>Very early in the new boot + <citerefentry><refentrytitle>systemd-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + checks whether <filename>/system-update</filename> exists. If so, it (temporarily and for + this boot only) redirects (i.e. symlinks) <filename>default.target</filename> to + <filename>system-update.target</filename>, a special target that is pulls in the base system + (i.e. <filename>sysinit.target</filename>, so that all file systems are mounted but little + else) and the system update units.</para> + </listitem> + + <listitem> + <para>The system now continues to boot into <filename>default.target</filename>, and thus + into <filename>system-update.target</filename>. This target pulls in the system update unit, + which starts the system update script after all file systems have been mounted.</para> + </listitem> + + <listitem> + <para>As the first step, the update script should check if the + <filename>/system-update</filename> symlink points to the the location used by that update + script. In case it does not exists or points to a different location, the script must exit + without error. It is possible for multiple update services to be installed, and for multiple + update scripts to be launched in parallel, and only the one that corresponds to the tool + that <emphasis>created</emphasis> the symlink before reboot should perform any actions. It + is unsafe to run multiple updates in parallel.</para> + </listitem> + + <listitem> + <para>The update script should now do its job. If applicable and possible, it should + create a file system snapshot, then install all packages. + After completion (regardless whether the update succeeded or failed) the machine + must be rebooted, for example by calling <command>systemctl reboot</command>. + In addition, on failure the script should revert to the old file system snapshot + (without the symlink).</para> + </listitem> + + <listitem> + <para>The system is rebooted. Since the <filename>/system-update</filename> symlink is gone, + the generator won't redirect <filename>default.target</filename> after reboot and the + system now boots into the default target again.</para> + </listitem> + </orderedlist> + </refsect1> + + <refsect1> + <title>Recommendations</title> + + <orderedlist> + <listitem> + <para>To make things a bit more robust we recommend hooking the update script into + <filename>system-update.target</filename> via a <filename noindex='true'>.wants/</filename> + symlink in the distribution package, rather than depending on <command>systemctl + enable</command> in the postinst scriptlets of your package. More specifically, for your + update script create a .service file, without [Install] section, and then add a symlink like + <filename noindex='true'>/usr/lib/systemd/system-update.target.wants/foobar.service</filename> + → <filename noindex='true'>../foobar.service</filename> to your package.</para> + </listitem> + + <listitem> + <para>Make sure to remove the <filename>/system-update</filename> symlink as early as + possible in the update script to avoid reboot loops in case the update fails.</para> + </listitem> + + <listitem> + <para>Use <varname>FailureAction=reboot</varname> in the service file for your update script + to ensure that a reboot is automatically triggered if the update fails. + <varname>FailureAction=</varname> makes sure that the specified unit is activated if your + script exits uncleanly (by non-zero error code, or signal/coredump). If your script succeeds + you should trigger the reboot in your own code, for example by invoking logind's + <command>Reboot()</command> call or calling <command>systemct reboot</command>. See + <ulink url="http://www.freedesktop.org/wiki/Software/systemd/logind">logind dbus API</ulink> + for details.</para> + </listitem> + + <listitem> + <para>The update service should declare <varname>DefaultDependencies=false</varname>, + and pull in any services it requires explicitly.</para> + </listitem> + </orderedlist> + </refsect1> + + <refsect1> + <title>See also</title> + + <para> + <ulink url="http://www.freedesktop.org/wiki/Software/systemd/SystemUpdates/">Implementing Offline System Updates</ulink>, + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>dnf.plugin.system-upgrade</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> +</refentry> diff --git a/man/systemd.path.xml b/man/systemd.path.xml index 1bd65ce86d..7200c8fe27 100644 --- a/man/systemd.path.xml +++ b/man/systemd.path.xml @@ -91,16 +91,12 @@ <para>An implicit <varname>Before=</varname> dependency is added between a path unit and the unit it is supposed to activate.</para> - <para>Unless <varname>DefaultDependencies=false</varname> is used, - path units will implicitly have dependencies of type - <varname>Before=</varname> on <filename>paths.target</filename>, - dependencies of type <varname>After=</varname> and - <varname>Requires=</varname> on - <filename>sysinit.target</filename>, and have dependencies of type - <varname>Conflicts=</varname> and <varname>Before=</varname> on - <filename>shutdown.target</filename>. These ensure that path units - are terminated cleanly prior to system shutdown. Only path units - involved with early boot or late system shutdown should disable + <para>Unless <varname>DefaultDependencies=false</varname> in the <literal>[Unit]</literal> section is used, path + units will implicitly have dependencies of type <varname>Before=</varname> on <filename>paths.target</filename>, + dependencies of type <varname>After=</varname> and <varname>Requires=</varname> on + <filename>sysinit.target</filename>, and have dependencies of type <varname>Conflicts=</varname> and + <varname>Before=</varname> on <filename>shutdown.target</filename>. These ensure that path units are terminated + cleanly prior to system shutdown. Only path units involved with early boot or late system shutdown should disable this option. </para> </refsect1> diff --git a/man/systemd.resource-control.xml b/man/systemd.resource-control.xml index 08cdf06e23..066f2cc19b 100644 --- a/man/systemd.resource-control.xml +++ b/man/systemd.resource-control.xml @@ -99,6 +99,31 @@ </refsect1> <refsect1> + <title>Unified and Legacy Control Group Hierarchies</title> + + <para>Unified control group hierarchy is the new version of kernel control group interface. Depending on the + 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> + <variablelist> + <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> + </refsect1> + + <refsect1> <title>Options</title> <para>Units of the types listed above can have settings @@ -202,7 +227,7 @@ controls the <literal>memory.limit_in_bytes</literal> control group attribute. For details about this control group attribute, see <ulink - url="https://www.kernel.org/doc/Documentation/cgroups/memory.txt">memory.txt</ulink>.</para> + url="https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt">memory.txt</ulink>.</para> <para>Implies <literal>MemoryAccounting=true</literal>.</para> </listitem> @@ -239,7 +264,7 @@ controls the <literal>pids.max</literal> control group attribute. For details about this control group attribute, see <ulink - url="https://www.kernel.org/doc/Documentation/cgroups/pids.txt">pids.txt</ulink>.</para> + url="https://www.kernel.org/doc/Documentation/cgroup-v1/pids.txt">pids.txt</ulink>.</para> <para>Implies <literal>TasksAccounting=true</literal>. The system default for this setting may be controlled with @@ -249,17 +274,130 @@ </varlistentry> <varlistentry> + <term><varname>IOAccounting=</varname></term> + + <listitem> + <para>Turn on Block I/O accounting for this unit, if the unified control group hierarchy is used on the + system. Takes a boolean argument. Note that turning on block I/O accounting for one unit will also implicitly + turn it on for all units contained in the same slice and all for its parent slices and the units contained + therein. The system default for this setting may be controlled with <varname>DefaultIOAccounting=</varname> + in + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para>This setting is supported only if the unified control group hierarchy is used. Use + <varname>BlockIOAccounting=</varname> on systems using the legacy control group hierarchy.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>IOWeight=<replaceable>weight</replaceable></varname></term> + <term><varname>StartupIOWeight=<replaceable>weight</replaceable></varname></term> + + <listitem> + <para>Set the default overall block I/O weight for the executed processes, if the unified control group + hierarchy is used on the system. Takes a single weight value (between 1 and 10000) to set the default block + I/O weight. This controls the <literal>io.weight</literal> control group attribute, which defaults to + 100. For details about this control group attribute, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>. The available I/O + bandwidth is split up among all units within one slice relative to their block I/O weight.</para> + + <para>While <varname>StartupIOWeight=</varname> only applies + to the startup phase of the system, + <varname>IOWeight=</varname> applies to the later runtime of + the system, and if the former is not set also to the startup + phase. This allows prioritizing specific services at boot-up + differently than during runtime.</para> + + <para>Implies <literal>IOAccounting=true</literal>.</para> + + <para>This setting is supported only if the unified control group hierarchy is used. Use + <varname>BlockIOWeight=</varname> and <varname>StartupBlockIOWeight=</varname> on systems using the legacy + control group hierarchy.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>IODeviceWeight=<replaceable>device</replaceable> <replaceable>weight</replaceable></varname></term> + + <listitem> + <para>Set the per-device overall block I/O weight for the executed processes, if the unified control group + hierarchy is used on the system. Takes a space-separated pair of a file path and a weight value to specify + the device specific weight value, between 1 and 10000. (Example: "/dev/sda 1000"). The file path may be + specified as path to a block device node or as any other file, in which case the backing block device of the + file system of the file is determined. This controls the <literal>io.weight</literal> control group + attribute, which defaults to 100. Use this option multiple times to set weights for multiple devices. For + details about this control group attribute, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para> + + <para>Implies <literal>IOAccounting=true</literal>.</para> + + <para>This setting is supported only if the unified control group hierarchy is used. Use + <varname>BlockIODeviceWeight=</varname> on systems using the legacy control group hierarchy.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>IOReadBandwidthMax=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term> + <term><varname>IOWriteBandwidthMax=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term> + + <listitem> + <para>Set the per-device overall block I/O bandwidth maximum limit for the executed processes, if the unified + control group hierarchy is used on the system. This limit is not work-conserving and the executed processes + are not allowed to use more even if the device has idle capacity. Takes a space-separated pair of a file + path and a bandwidth value (in bytes per second) to specify the device specific bandwidth. The file path may + be a path to a block device node, or as any other file in which case the backing block device of the file + system of the file is used. If the bandwidth is suffixed with K, M, G, or T, the specified bandwidth is + parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes, respectively, to the base of 1000. (Example: + "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This controls the <literal>io.max</literal> control + group attributes. Use this option multiple times to set bandwidth limits for multiple devices. For details + about this control group attribute, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>. + </para> + + <para>Implies <literal>IOAccounting=true</literal>.</para> + + <para>This setting is supported only if the unified control group hierarchy is used. Use + <varname>BlockIOAccounting=</varname> on systems using the legacy control group hierarchy.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>IOReadIOPSMax=<replaceable>device</replaceable> <replaceable>IOPS</replaceable></varname></term> + <term><varname>IOWriteIOPSMax=<replaceable>device</replaceable> <replaceable>IOPS</replaceable></varname></term> + + <listitem> + <para>Set the per-device overall block I/O IOs-Per-Second maximum limit for the executed processes, if the + unified control group hierarchy is used on the system. This limit is not work-conserving and the executed + processes are not allowed to use more even if the device has idle capacity. Takes a space-separated pair of + a file path and an IOPS value to specify the device specific IOPS. The file path may be a path to a block + device node, or as any other file in which case the backing block device of the file system of the file is + used. If the IOPS is suffixed with K, M, G, or T, the specified IOPS is parsed as KiloIOPS, MegaIOPS, + GigaIOPS, or TeraIOPS, respectively, to the base of 1000. (Example: + "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 1K"). This controls the <literal>io.max</literal> control + group attributes. Use this option multiple times to set IOPS limits for multiple devices. For details about + this control group attribute, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>. + </para> + + <para>Implies <literal>IOAccounting=true</literal>.</para> + + <para>This setting is supported only if the unified control group hierarchy is used.</para> + </listitem> + </varlistentry> + + <varlistentry> <term><varname>BlockIOAccounting=</varname></term> <listitem> - <para>Turn on Block I/O accounting for this unit. 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 + <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> @@ -267,15 +405,13 @@ <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. 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/cgroups/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> + <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, @@ -286,29 +422,32 @@ <para>Implies <literal>BlockIOAccounting=true</literal>.</para> - </listitem> + + <para>This setting is supported only if the legacy control group hierarchy is used. Use + <varname>IOWeight=</varname> and <varname>StartupIOWeight=</varname> on systems using the unified control group + hierarchy.</para> + + </listitem> </varlistentry> <varlistentry> <term><varname>BlockIODeviceWeight=<replaceable>device</replaceable> <replaceable>weight</replaceable></varname></term> <listitem> - <para>Set the per-device overall block I/O weight for the - executed processes. Takes a space-separated pair of a file - path and a weight value to specify the device specific - weight value, between 10 and 1000. (Example: "/dev/sda - 500"). The file path may be specified as path to a block - device node or as any other file, in which case the backing - block device of the file system of the file is - determined. This controls the - <literal>blkio.weight_device</literal> control group - attribute, which defaults to 1000. Use this option multiple - times to set weights for multiple devices. For details about - this control group attribute, see <ulink - url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.</para> + <para>Set the per-device overall block I/O weight for the executed processes, if the legacy control group + hierarchy is used on the system. Takes a space-separated pair of a file path and a weight value to specify + the device specific weight value, between 10 and 1000. (Example: "/dev/sda 500"). The file path may be + specified as path to a block device node or as any other file, in which case the backing block device of the + file system of the file is determined. This controls the <literal>blkio.weight_device</literal> control group + attribute, which defaults to 1000. Use this option multiple times to set weights for multiple devices. For + details about this control group attribute, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>.</para> <para>Implies <literal>BlockIOAccounting=true</literal>.</para> + + <para>This setting is supported only if the legacy control group hierarchy is used. Use + <varname>IODeviceWeight=</varname> on systems using the unified control group hierarchy.</para> </listitem> </varlistentry> @@ -317,27 +456,25 @@ <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. Takes a space-separated pair of - a file path and a bandwidth value (in bytes per second) to - specify the device specific bandwidth. The file path may be - a path to a block device node, or as any other file in which - case the backing block device of the file system of the file - is used. If the bandwidth is suffixed with K, M, G, or T, - the specified bandwidth is parsed as Kilobytes, Megabytes, - Gigabytes, or Terabytes, respectively, to the base of - 1000. (Example: - "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This - controls the <literal>blkio.read_bps_device</literal> and - <literal>blkio.write_bps_device</literal> control group - attributes. Use this option multiple times to set bandwidth - limits for multiple devices. For details about these control - group attributes, see <ulink - url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>. + <para>Set the per-device overall block I/O bandwidth limit for the executed processes, if the legacy control + group hierarchy is used on the system. Takes a space-separated pair of a file path and a bandwidth value (in + bytes per second) to specify the device specific bandwidth. The file path may be a path to a block device + node, or as any other file in which case the backing block device of the file system of the file is used. If + the bandwidth is suffixed with K, M, G, or T, the specified bandwidth is parsed as Kilobytes, Megabytes, + Gigabytes, or Terabytes, respectively, to the base of 1000. (Example: + "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This controls the + <literal>blkio.throttle.read_bps_device</literal> and <literal>blkio.throttle.write_bps_device</literal> + control group attributes. Use this option multiple times to set bandwidth limits for multiple devices. For + details about these control group attributes, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>. </para> <para>Implies <literal>BlockIOAccounting=true</literal>.</para> + + <para>This setting is supported only if the legacy control group hierarchy is used. Use + <varname>IOReadBandwidthMax=</varname> and <varname>IOWriteBandwidthMax=</varname> on systems using the + unified control group hierarchy.</para> </listitem> </varlistentry> @@ -357,7 +494,7 @@ <literal>devices.deny</literal> control group attributes. For details about these control group attributes, see <ulink - url="https://www.kernel.org/doc/Documentation/cgroups/devices.txt">devices.txt</ulink>.</para> + url="https://www.kernel.org/doc/Documentation/cgroup-v1/devices.txt">devices.txt</ulink>.</para> <para>The device node specifier is either a path to a device node in the file system, starting with @@ -482,10 +619,10 @@ <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, The documentation for control groups and specific controllers in the Linux kernel: - <ulink url="https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink>, - <ulink url="https://www.kernel.org/doc/Documentation/cgroups/cpuacct.txt">cpuacct.txt</ulink>, - <ulink url="https://www.kernel.org/doc/Documentation/cgroups/memory.txt">memory.txt</ulink>, - <ulink url="https://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>. + <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/cgroups.txt">cgroups.txt</ulink>, + <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/cpuacct.txt">cpuacct.txt</ulink>, + <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt">memory.txt</ulink>, + <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>. </para> </refsect1> </refentry> diff --git a/man/systemd.service.xml b/man/systemd.service.xml index d7760d4f2c..6641dfed4f 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -100,18 +100,13 @@ their activated <filename>.socket</filename> units via an automatic <varname>After=</varname> dependency.</para> - <para>Unless <varname>DefaultDependencies=</varname> is set to - <option>false</option>, service units will implicitly have - dependencies of type <varname>Requires=</varname> and - <varname>After=</varname> on <filename>sysinit.target</filename>, - a dependency of type <varname>After=</varname> on - <filename>basic.target</filename> as well as dependencies of - type <varname>Conflicts=</varname> and <varname>Before=</varname> - on <filename>shutdown.target</filename>. These ensure that normal - service units pull in basic system initialization, and are - terminated cleanly prior to system shutdown. Only services - involved with early boot or late system shutdown should disable - this option.</para> + <para>Unless <varname>DefaultDependencies=</varname> in the <literal>[Unit]</literal> is set to + <option>false</option>, service units will implicitly have dependencies of type <varname>Requires=</varname> and + <varname>After=</varname> on <filename>sysinit.target</filename>, a dependency of type <varname>After=</varname> on + <filename>basic.target</filename> as well as dependencies of type <varname>Conflicts=</varname> and + <varname>Before=</varname> on <filename>shutdown.target</filename>. These ensure that normal service units pull in + basic system initialization, and are terminated cleanly prior to system shutdown. Only services involved with early + boot or late system shutdown should disable this option.</para> <para>Instanced service units (i.e. service units with an <literal>@</literal> in their name) are assigned by default a per-template slice unit (see @@ -273,42 +268,6 @@ </varlistentry> <varlistentry> - <term><varname>BusPolicy=</varname></term> - - <listitem><para>If specified, a custom kdbus - endpoint will be created and installed as the default bus node - for the service. Such a custom endpoint can hold an own set of - policy rules that are enforced on top of the bus-wide ones. - The custom endpoint is named after the service it was created - for, and its node will be bind-mounted over the default bus - node location, so the service can only access the bus through - its own endpoint. Note that custom bus endpoints default to a - "deny all" policy. Hence, if at least one - <varname>BusPolicy=</varname> directive is given, you have to - make sure to add explicit rules for everything the service - should be able to do.</para> - <para>The value of this directive is comprised - of two parts; the bus name, and a verb to - specify to granted access, which is one of - <option>see</option>, - <option>talk</option>, or - <option>own</option>. - <option>talk</option> implies - <option>see</option>, and <option>own</option> - implies both <option>talk</option> and - <option>see</option>. - If multiple access levels are specified for the - same bus name, the most powerful one takes - effect. - </para> - <para>Examples:</para> - <programlisting>BusPolicy=org.freedesktop.systemd1 talk</programlisting> - <programlisting>BusPolicy=org.foo.bar see</programlisting> - <para>This option is only available on kdbus enabled systems.</para> - </listitem> - </varlistentry> - - <varlistentry> <term><varname>ExecStart=</varname></term> <listitem><para>Commands with their arguments that are executed when this service is started. The value is split into @@ -446,7 +405,7 @@ asynchronous one.</para> <para>Note that the commands specified in <varname>ExecStop=</varname> are only executed when the service - started successfuly first. They are not invoked if the service was never started at all, or in case its + started successfully first. They are not invoked if the service was never started at all, or in case its start-up failed, for example because any of the commands specified in <varname>ExecStart=</varname>, <varname>ExecStartPre=</varname> or <varname>ExecStartPost=</varname> failed (and weren't prefixed with <literal>-</literal>, see above) or timed out. Use <varname>ExecStopPost=</varname> to invoke commands when a diff --git a/man/systemd.slice.xml b/man/systemd.slice.xml index 5c87bf0260..eee98d99ee 100644 --- a/man/systemd.slice.xml +++ b/man/systemd.slice.xml @@ -71,6 +71,9 @@ the root slice <filename>-.slice</filename>. </para> + <para>Note that slice units cannot be templated, nor is possible to add multiple names to a slice unit by creating + additional symlinks to it.</para> + <para>By default, service and scope units are placed in <filename>system.slice</filename>, virtual machines and containers registered with @@ -106,14 +109,10 @@ <varname>After=</varname> and <varname>Requires=</varname> on their immediate parent slice unit.</para> - <para>Unless <varname>DefaultDependencies=false</varname> - is used, slice units will implicitly have dependencies of - type <varname>Conflicts=</varname> and - <varname>Before=</varname> on - <filename>shutdown.target</filename>. These ensure - that slice units are removed prior to system - shutdown. Only slice units involved with early boot or - late system shutdown should disable this option. + <para>Unless <varname>DefaultDependencies=false</varname> is used in the <literal>[Unit]</literal> section, slice + units will implicitly have dependencies of type <varname>Conflicts=</varname> and <varname>Before=</varname> on + <filename>shutdown.target</filename>. These ensure that slice units are removed prior to system shutdown. Only + slice units involved with early boot or late system shutdown should disable this option. </para> </refsect1> diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml index 43841c2399..5bf54d8ef3 100644 --- a/man/systemd.socket.xml +++ b/man/systemd.socket.xml @@ -97,16 +97,12 @@ <filename>foo@.service</filename> must exist from which services are instantiated for each incoming connection.</para> - <para>Unless <varname>DefaultDependencies=</varname> is set to - <option>false</option>, socket units will implicitly have - dependencies of type <varname>Requires=</varname> and - <varname>After=</varname> on <filename>sysinit.target</filename> - as well as dependencies of type <varname>Conflicts=</varname> and - <varname>Before=</varname> on - <filename>shutdown.target</filename>. These ensure that socket - units pull in basic system initialization, and are terminated - cleanly prior to system shutdown. Only sockets involved with early - boot or late system shutdown should disable this option.</para> + <para>Unless <varname>DefaultDependencies=</varname> in the <literal>[Unit]</literal> section is set to + <option>false</option>, socket units will implicitly have dependencies of type <varname>Requires=</varname> and + <varname>After=</varname> on <filename>sysinit.target</filename> as well as dependencies of type + <varname>Conflicts=</varname> and <varname>Before=</varname> on <filename>shutdown.target</filename>. These ensure + that socket units pull in basic system initialization, and are terminated cleanly prior to system shutdown. Only + sockets involved with early boot or late system shutdown should disable this option.</para> <para>Socket units will have a <varname>Before=</varname> dependency on the service which they trigger added implicitly. No @@ -811,6 +807,23 @@ suffix.</para></listitem> </varlistentry> + <varlistentry> + <term><varname>TriggerLimitIntervalSec=</varname></term> + <term><varname>TriggerLimitBurst=</varname></term> + + <listitem><para>Configures a limit on how often this socket unit my be activated within a specific time + interval. The <varname>TriggerLimitIntervalSec=</varname> may be used to configure the length of the time + interval in the usual time units <literal>us</literal>, <literal>ms</literal>, <literal>s</literal>, + <literal>min</literal>, <literal>h</literal>, … and defaults to 2s (See + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details on + the various time units understood). The <varname>TriggerLimitBurst=</varname> setting takes a positive integer + value and specifies the number of permitted activations per time interval, and defaults to 200 for + <varname>Accept=yes</varname> sockets (thus by default permitting 200 activations per 2s), and 20 otherwise (20 + activations per 2s). Set either to 0 to disable any form of trigger rate limiting. If the limit is hit, the + socket unit is placed into a failure mode, and will not be connectible anymore until restarted. Note that this + limit is enforced before the service activation is enqueued.</para></listitem> + </varlistentry> + </variablelist> <para>Check diff --git a/man/systemd.special.xml b/man/systemd.special.xml index 055d854555..26974ed73f 100644 --- a/man/systemd.special.xml +++ b/man/systemd.special.xml @@ -83,6 +83,7 @@ <filename>remote-fs.target</filename>, <filename>remote-fs-pre.target</filename>, <filename>rescue.target</filename>, + <filename>initrd-root-device.target</filename>, <filename>initrd-root-fs.target</filename>, <filename>rpcbind.target</filename>, <filename>runlevel2.target</filename>, @@ -205,7 +206,7 @@ <term><filename>emergency.target</filename></term> <listitem> <para>A special target unit that starts an emergency shell on the main console. This target does not pull in - any serices or mounts. It is the most minimal version of starting the system in order to acquire an + any services or mounts. It is the most minimal version of starting the system in order to acquire an interactive shell; the only processes running are usually just the system manager (PID 1) and the shell process. This unit is supposed to be used with the kernel command line option <varname>systemd.unit=</varname>; it is also used when a file system check on a required file system fails, @@ -465,6 +466,18 @@ </listitem> </varlistentry> <varlistentry> + <term><filename>initrd-root-device.target</filename></term> + <listitem> + <para>A special initrd target unit that is reached when the root filesystem device is available, but before + it has been mounted. + <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry> + automatically setup the appropiate dependencies to make this happen. + </para> + </listitem> + </varlistentry> + <varlistentry> <term><filename>initrd-root-fs.target</filename></term> <listitem> <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry> @@ -526,7 +539,7 @@ <para>A special target unit that sets up all slice units (see <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details) that shall be active after boot. By default the generic <filename>user.slice</filename>, - <filename>system.slice</filename>, <filename>machines.slice</filename> slice units, as well as the the root + <filename>system.slice</filename>, <filename>machines.slice</filename> slice units, as well as the root slice unit <filename>-.slice</filename> are pulled in and ordered before this unit (see below).</para> <para>It's a good idea to add <varname>WantedBy=slices.target</varname> lines to the <literal>[Install]</literal> @@ -742,7 +755,7 @@ defined what that is supposed to mean, with one exception: at shutdown, a unit that is ordered after <filename>network.target</filename> will be stopped before - the network -- to whatever level it might be set up then -- + the network — to whatever level it might be set up then — is shut down. It is hence useful when writing service files that require network access on shutdown, which should order themselves after this target, but not pull it in. Also see diff --git a/man/systemd.swap.xml b/man/systemd.swap.xml index c600405c87..cf4e1ba839 100644 --- a/man/systemd.swap.xml +++ b/man/systemd.swap.xml @@ -72,19 +72,18 @@ project='man-pages'><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry> binary is executed in, in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - which define the way the these processes are + which define the way these processes are terminated, and in <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, which configure resource control settings for these processes of the unit.</para> - <para>Swap units must be named after the devices - or files they control. Example: the swap device - <filename noindex='true'>/dev/sda5</filename> must be configured in a - unit file <filename>dev-sda5.swap</filename>. For details about - the escaping logic used to convert a file system path to a unit - name, see - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + <para>Swap units must be named after the devices or files they control. Example: the swap device <filename + noindex='true'>/dev/sda5</filename> must be configured in a unit file <filename>dev-sda5.swap</filename>. For + details about the escaping logic used to convert a file system path to a unit name, see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Note that swap + units cannot be templated, nor is possible to add multiple names to a swap unit by creating additional symlinks to + it.</para> </refsect1> <refsect1> @@ -95,12 +94,10 @@ dependencies on the device units or the mount units of the files they are activated from.</para> - <para>Swap units with <varname>DefaultDependencies=</varname> - enabled implicitly acquire a <varname>Conflicts=</varname> and an - <varname>After=</varname> dependency on - <filename>umount.target</filename> so that they are deactivated at - shutdown, unless <varname>DefaultDependencies=no</varname> is - specified.</para> + <para>Swap units with <varname>DefaultDependencies=</varname> in the <literal>[Unit]</literal> section enabled + implicitly acquire a <varname>Conflicts=</varname> and an <varname>After=</varname> dependency on + <filename>umount.target</filename> so that they are deactivated at shutdown, unless + <varname>DefaultDependencies=no</varname> is specified.</para> <para>Additional implicit dependencies may be added as result of execution and resource control parameters as documented in diff --git a/man/systemd.target.xml b/man/systemd.target.xml index bd4ab3903e..ab910d75dd 100644 --- a/man/systemd.target.xml +++ b/man/systemd.target.xml @@ -82,14 +82,11 @@ <refsect1> <title>Automatic Dependencies</title> - <para>Unless <varname>DefaultDependencies=</varname> is set to - <option>no</option>, target units will implicitly complement all - configured dependencies of type <varname>Wants=</varname>, - <varname>Requires=</varname> with dependencies of type - <varname>After=</varname>, unless an ordering dependency of any - kind between the target and the respective other unit is already - in place. Note that this behaviour is disabled if either unit has - <varname>DefaultDependencies=no</varname>.</para> + <para>Unless <varname>DefaultDependencies=</varname> in the <literal>[Unit]</literal> section is set to + <option>no</option>, target units will implicitly complement all configured dependencies of type + <varname>Wants=</varname>, <varname>Requires=</varname> with dependencies of type <varname>After=</varname>, unless + an ordering dependency of any kind between the target and the respective other unit is already in place. Note that + this behaviour is disabled if either unit has <varname>DefaultDependencies=no</varname>.</para> </refsect1> <refsect1> diff --git a/man/systemd.timer.xml b/man/systemd.timer.xml index 29e235e2dc..0fa95e97a8 100644 --- a/man/systemd.timer.xml +++ b/man/systemd.timer.xml @@ -73,6 +73,12 @@ <filename>foo.timer</filename> activates a matching service <filename>foo.service</filename>. The unit to activate may be controlled by <varname>Unit=</varname> (see below).</para> + + <para>Note that in case the unit to activate is already active at the time the timer elapses it is not restarted, + but simply left running. There is no concept of spawning new service instances in this case. Due to this, services + with <varname>RemainAfterExit=</varname> set (which stay around continously even after the service's main process + exited) are usually not suitable for activation via repetitive timers, as they will only be activated once, and + then stay around forever.</para> </refsect1> <refsect1> @@ -81,21 +87,15 @@ <para>Timer units automatically gain a <varname>Before=</varname> dependency on the service they are supposed to activate.</para> - <para>Unless <varname>DefaultDependencies=</varname> is set to - <option>false</option>, all timer units will implicitly have - dependencies of type <varname>Requires=</varname> and - <varname>After=</varname> on <filename>sysinit.target</filename>, - a dependency of type <varname>Before=</varname> on - <filename>timers.target</filename>, as well as - <varname>Conflicts=</varname> and <varname>Before=</varname> on - <filename>shutdown.target</filename> to ensure that they are - stopped cleanly prior to system shutdown. Timer units with at - least one <varname>OnCalendar=</varname> directive will have an - additional <varname>After=</varname> dependency on - <filename>timer-sync.target</filename> to avoid being started - before the system clock has been correctly set. Only timer units - involved with early boot or late system shutdown should disable - the <varname>DefaultDependencies=</varname> option.</para> + <para>Unless <varname>DefaultDependencies=</varname> in the <literal>[Unit]</literal> section is set to + <option>false</option>, all timer units will implicitly have dependencies of type <varname>Requires=</varname> and + <varname>After=</varname> on <filename>sysinit.target</filename>, a dependency of type <varname>Before=</varname> + on <filename>timers.target</filename>, as well as <varname>Conflicts=</varname> and <varname>Before=</varname> on + <filename>shutdown.target</filename> to ensure that they are stopped cleanly prior to system shutdown. Timer units + with at least one <varname>OnCalendar=</varname> directive will have an additional <varname>After=</varname> + dependency on <filename>timer-sync.target</filename> to avoid being started before the system clock has been + correctly set. Only timer units involved with early boot or late system shutdown should disable the + <varname>DefaultDependencies=</varname> option.</para> </refsect1> <refsect1> @@ -259,7 +259,8 @@ during the time when the timer was inactive. This is useful to catch up on missed runs of the service when the machine was off. Note that this setting only has an effect on timers - configured with <varname>OnCalendar=</varname>. + configured with <varname>OnCalendar=</varname>. Defaults + to <varname>false</varname>. </para></listitem> </varlistentry> @@ -287,7 +288,7 @@ starting a timer unit that only elapses once: if <varname>RemainAfterElapse=</varname> is on, it will not be started again, and is guaranteed to elapse only once. However, - if <varname>RemainAfterLeapse=</varname> is off, it might be + if <varname>RemainAfterElapse=</varname> is off, it might be started again if it is already elapsed, and thus be triggered multiple times. Defaults to <varname>yes</varname>.</para></listitem> diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 5794681963..341789cd47 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -66,18 +66,16 @@ <para><literallayout><filename>/etc/systemd/system/*</filename> <filename>/run/systemd/system/*</filename> <filename>/usr/lib/systemd/system/*</filename> -<filename>...</filename> +<filename>…</filename> </literallayout></para> - <para><literallayout><filename>$XDG_CONFIG_HOME/systemd/user/*</filename> -<filename>$HOME/.config/systemd/user/*</filename> + <para><literallayout><filename>~/.config/systemd/user/*</filename> <filename>/etc/systemd/user/*</filename> <filename>$XDG_RUNTIME_DIR/systemd/user/*</filename> <filename>/run/systemd/user/*</filename> -<filename>$XDG_DATA_HOME/systemd/user/*</filename> -<filename>$HOME/.local/share/systemd/user/*</filename> +<filename>~/.local/share/systemd/user/*</filename> <filename>/usr/lib/systemd/user/*</filename> -<filename>...</filename> +<filename>…</filename> </literallayout></para> </refsynopsisdiv> @@ -558,14 +556,17 @@ between them are shut down, the inverse of the start-up order is applied. i.e. if a unit is configured with <varname>After=</varname> on another unit, the former is - stopped before the latter if both are shut down. If one unit - with an ordering dependency on another unit is shut down while - the latter is started up, the shut down is ordered before the - start-up regardless of whether the ordering dependency is - actually of type <varname>After=</varname> or - <varname>Before=</varname>. If two units have no ordering - dependencies between them, they are shut down or started up - simultaneously, and no ordering takes place. + stopped before the latter if both are shut down. Given two units + with any ordering dependency between them, if one unit is shut + down and the other is started up, the shutdown is ordered + before the start-up. It doesn't matter if the ordering + dependency is <varname>After=</varname> or + <varname>Before=</varname>. It also doesn't matter which of the + two is shut down, as long as one is shut down and the other is + started up. The shutdown is ordered before the start-up in all + cases. If two units have no ordering dependencies between them, + they are shut down or started up simultaneously, and no ordering + takes place. </para></listitem> </varlistentry> @@ -602,7 +603,7 @@ <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details). If a unit that has this setting set is started, its processes will see the same <filename>/tmp</filename>, - <filename>/tmp/var</filename> and network namespace as one + <filename>/var/tmp</filename> and network namespace as one listed unit that is started. If multiple listed units are already started, it is not defined which namespace is joined. Note that this setting only has an effect if @@ -750,14 +751,14 @@ </varlistentry> <varlistentry> - <term><varname>StartLimitInterval=</varname></term> + <term><varname>StartLimitIntervalSec=</varname></term> <term><varname>StartLimitBurst=</varname></term> <listitem><para>Configure unit start rate limiting. By default, units which are started more than 5 times within 10 seconds are not permitted to start any more times until the 10 second interval ends. With these two - options, this rate limiting may be modified. Use <varname>StartLimitInterval=</varname> to configure the - checking interval (defaults to <varname>DefaultStartLimitInterval=</varname> in manager configuration file, set - to 0 to disable any kind of rate limiting). Use <varname>StartLimitBurst=</varname> to configure how many + options, this rate limiting may be modified. Use <varname>StartLimitIntervalSec=</varname> to configure the + checking interval (defaults to <varname>DefaultStartLimitIntervalSec=</varname> in manager configuration file, + set to 0 to disable any kind of rate limiting). Use <varname>StartLimitBurst=</varname> to configure how many starts per interval are allowed (defaults to <varname>DefaultStartLimitBurst=</varname> in manager configuration file). These configuration options are particularly useful in conjunction with the service setting <varname>Restart=</varname> (see @@ -768,14 +769,17 @@ manually at a later point, from which point on, the restart logic is again activated. Note that <command>systemctl reset-failed</command> will cause the restart rate counter for a service to be flushed, which is useful if the administrator wants to manually start a unit and the start limit interferes with - that.</para></listitem> + that. Note that this rate-limiting is enforced after any unit condition checks are executed, and hence unit + activations with failing conditions are not counted by this rate limiting. Slice, target, device and scope + units do not enforce this setting, as they are unit types whose activation may either never fail, or may + succeed only a single time.</para></listitem> </varlistentry> <varlistentry> <term><varname>StartLimitAction=</varname></term> <listitem><para>Configure the action to take if the rate limit configured with - <varname>StartLimitInterval=</varname> and <varname>StartLimitBurst=</varname> is hit. Takes one of + <varname>StartLimitIntervalSec=</varname> and <varname>StartLimitBurst=</varname> is hit. Takes one of <option>none</option>, <option>reboot</option>, <option>reboot-force</option>, <option>reboot-immediate</option>, <option>poweroff</option>, <option>poweroff-force</option> or <option>poweroff-immediate</option>. If <option>none</option> is set, hitting the rate limit will trigger no @@ -1101,13 +1105,12 @@ <varlistentry> <term><varname>Alias=</varname></term> - <listitem><para>A space-separated list of additional names - this unit shall be installed under. The names listed here must - have the same suffix (i.e. type) as the unit file name. This - option may be specified more than once, in which case all - listed names are used. At installation time, - <command>systemctl enable</command> will create symlinks from - these names to the unit filename.</para></listitem> + <listitem><para>A space-separated list of additional names this unit shall be installed under. The names listed + here must have the same suffix (i.e. type) as the unit file name. This option may be specified more than once, + in which case all listed names are used. At installation time, <command>systemctl enable</command> will create + symlinks from these names to the unit filename. Note that not all unit types support such alias names, and this + setting is not supported for them. Specifically, mount, slice, swap, and automount units do not support + aliasing.</para></listitem> </varlistentry> <varlistentry> diff --git a/man/tmpfiles.d.xml b/man/tmpfiles.d.xml index 3b6b1e3f11..957475d2bd 100644 --- a/man/tmpfiles.d.xml +++ b/man/tmpfiles.d.xml @@ -157,13 +157,23 @@ <varlistentry> <term><varname>d</varname></term> - <listitem><para>Create a directory if it does not exist yet. - </para></listitem> + <listitem><para>Create a directory. The mode and ownership will be adjusted if + specified and the directory already exists. Contents of this directory are subject + to time based cleanup if the time argument is specified.</para></listitem> </varlistentry> <varlistentry> <term><varname>D</varname></term> - <listitem><para>Create or empty a directory.</para></listitem> + <listitem><para>Similar to <varname>d</varname>, but in addition the contents + of the directory will be removed when <option>--remove</option> is used. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>e</varname></term> + <listitem><para>Similar to <varname>d</varname>, but the directory will not be + created if it does not exist. Lines of this type accept shell-style globs in + place of normal path names.</para></listitem> </varlistentry> <varlistentry> @@ -577,7 +587,7 @@ unconditionally.</para> <para>The age field only applies to lines starting with - <varname>d</varname>, <varname>D</varname>, + <varname>d</varname>, <varname>D</varname>, <varname>e</varname>, <varname>v</varname>, <varname>q</varname>, <varname>Q</varname>, <varname>C</varname>, <varname>x</varname> and <varname>X</varname>. If omitted or set to @@ -612,22 +622,63 @@ </refsect1> <refsect1> - <title>Example</title> + <title>Examples</title> <example> - <title>/etc/tmpfiles.d/screen.conf example</title> - <para><command>screen</command> needs two directories created at - boot with specific modes and ownership.</para> + <title>Create directories with specific mode and ownership</title> + <para> + <citerefentry><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + needs two directories created at boot with specific modes and ownership:</para> + + <programlisting># /usr/lib/tmpfiles.d/screen.conf +d /run/screens 1777 root screen 10d +d /run/uscreens 0755 root screen 10d12h +</programlisting> + + <para>Contents of <filename>/run/screens</filename> and /run/uscreens will + cleaned up after 10 and 10½ days, respectively.</para> + </example> - <programlisting>d /run/screens 1777 root root 10d -d /run/uscreens 0755 root root 10d12h -t /run/screen - - - - user.name="John Smith" security.SMACK64=screen</programlisting> + <example> + <title>Create a directory with a SMACK attribute</title> + <programlisting>D /run/cups - - - - +t /run/cups - - - - security.SMACK64=printing user.attr-with-spaces="foo bar" + </programlisting> + + <para>The direcory will be owned by root and have default mode. It's contents are + not subject to time based cleanup, but will be obliterated when + <command>systemd-tmpfiles --remove</command> runs.</para> </example> + <example> - <title>/etc/tmpfiles.d/abrt.conf example</title> - <para><command>abrt</command> needs a directory created at boot with specific mode and ownership and its content should be preserved.</para> + <title>Create a directory and prevent its contents from cleanup</title> + <para> + <citerefentry><refentrytitle>abrt</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + needs a directory created at boot with specific mode and ownership and its content + should be preserved from the automatic cleanup applied to the contents of + <filename>/var/tmp</filename>:</para> + + <programlisting># /usr/lib/tmpfiles.d/tmp.conf +d /var/tmp 1777 root root 30d +</programlisting> + + <programlisting># /usr/lib/tmpfiles.d/abrt.conf +d /var/tmp/abrt 0755 abrt abrt - +</programlisting> + </example> - <programlisting>d /var/tmp/abrt 0755 abrt abrt -x /var/tmp/abrt/*</programlisting> + <example> + <title>Apply clean up during boot and based on time</title> + + <programlisting># /usr/lib/tmpfiles.d/dnf.conf +r! /var/cache/dnf/*/*/download_lock.pid +r! /var/cache/dnf/*/*/metadata_lock.pid +r! /var/lib/dnf/rpmdb_lock.pid +e /var/chache/dnf/ - - - 30d +</programlisting> + + <para>The lock files will be removed during boot. Any files and directories in + <filename>/var/chache/dnf/</filename> will be removed after they have not been + accessed in 30 days.</para> </example> </refsect1> diff --git a/man/udev_device_get_syspath.xml b/man/udev_device_get_syspath.xml index ca9763fedf..b54749ed56 100644 --- a/man/udev_device_get_syspath.xml +++ b/man/udev_device_get_syspath.xml @@ -127,6 +127,8 @@ <funcprototype> <funcdef>struct udev_device *<function>udev_device_get_parent_with_subsystem_devtype</function></funcdef> <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> + <paramdef>const char *<parameter>subsystem</parameter></paramdef> + <paramdef>const char *<parameter>devtype</parameter></paramdef> </funcprototype> <funcprototype> @@ -137,8 +139,6 @@ <funcprototype> <funcdef>const char *<function>udev_device_get_action</function></funcdef> <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> - <paramdef>const char *<parameter>subsystem</parameter></paramdef> - <paramdef>const char *<parameter>devtype</parameter></paramdef> </funcprototype> </funcsynopsis> |